#include <sys/shm.h> int shmctl64(int shmid, int cmd, struct shmid_ds64 *buf);
The shmctl64() function allows the caller to control the shared memory segment specified by the shmid parameter.
The shmctl64() function is enabled for large (64-bit) shared memory segments. It can operate on teraspace shared memory segments larger than 4 294 967 295 bytes (4GB minus 1 byte). It also provides additional functionality not available via the shmctl() function.
A shared memory segment is controlled by setting the cmd parameter to one of the following values:
The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment. The structure pointed to by *buf is ignored and can be NULL.
The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.
The SHM_SIZE command can be run only by a thread with appropriate privileges or a thread that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.
If a shared memory segment is resized to a smaller size, other threads using the memory that is being removed from the shared memory segment may experience memory exceptions when accessing that memory.
This command must be called after the teraspace shared memory segment has been created but before any process has attached to the teraspace shared memory segment. Setting the page size of a teraspace shared memory segment after it has been attached to a process will fail with the [EBUSY] error.
Valid values for the shm_pagesize field are:
Setting the page size to a value that is not valid or not supported will fail with the [EINVAL] error.
The SHM_PAGESIZE command can be run only by a thread with appropriate privileges or a thread that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the teraspace shared memory segment.
The members of the shmid_ds64 structure are as follows:
struct ipc_perm shm_perm | The members of the ipc_perm structure
are as follows:
|
||||||||||
pid_t shm_lpid | The process ID of the last job to attach to or detach from the segment using shmat() or shmdt(). | ||||||||||
pid_t shm_cpid | The process ID of the job that created the segment using shmget() or shmget64(). | ||||||||||
shmatt_t shm_nattch | The number of jobs attached to the segment. | ||||||||||
size64_t shm_segsz | The size of the segment in bytes. | ||||||||||
char shm_reserved1[4] | Reserved. This field must be set to binary zero on input. | ||||||||||
time_t shm_atime | The time the last job attached to the segment using shmat(). | ||||||||||
char shm_reserved2[4] | Reserved. This field must be set to binary zero on input. | ||||||||||
time_t shm_dtime | The time the last job detached from the segment using shmdt(). | ||||||||||
char shm_reserved3[4] | Reserved. This field must be set to binary zero on input. | ||||||||||
time_t shm_ctime | The time the last job changed the segment using shmctl() or shmctl64(). | ||||||||||
psize_t shm_pagesize | The page size of the storage backing the segment. | ||||||||||
char shm_reserved4[24] | Reserved. This field must be set to binary zero on input. |
Authorization Required for shmctl64()
Object Referred to | Authority Required | errno |
---|---|---|
Shared memory segment for which state information is retrieved (cmd = IPC_STAT) | Read | EACCES |
Shared memory segment for which state information is set (cmd = IPC_SET) | See Note | EPERM |
Shared memory segment to be removed (cmd = IPC_RMID) | See Note | EPERM |
Shared memory segment to be resized (cmd = SHM_SIZE) | See Note | EPERM |
Shared memory segment for which page size information is set (cmd = SHM_PAGESIZE) | See Note | EPERM |
Note: To set shared memory segment information, to remove a shared memory segment, to resize a shared memory segment, or to set the page size of a shared memory segment, the thread must be the owner or creator of the shared memory segment or have appropriate privileges.
0 | shmctl64() was successful. |
-1 | shmctl64() was not successful. The errno variable is set to indicate the error. |
If shmctl64() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Permission denied.
An attempt was made to access an object in a way forbidden by its object access permissions.
The thread does not have access to the specified file, directory, component, or path.
The cmd parameter is IPC_STAT and the calling thread does not have read permission to shared memory segment.
Resource busy.
An attempt was made to use a system resource that is not available at this time.
The cmd parameter is SHM_PAGESIZE and the shared memory segment has been attached to a process.
A damaged object was encountered.
The shared memory segment has been damaged by a previous shared memory operation.
The address used for an argument is not correct.
In attempting to use an argument in a call, the system detected an address that is not valid.
While attempting to access a parameter passed to this function, the system detected an address that is not valid.
The value specified for the argument is not correct.
A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.
An argument value is not valid, out of range, or NULL.
One of the following has occurred:
Storage allocation request failed.
A function needed to allocate storage, but no storage is available.
A shared memory identifier segment is to be resized, but the amount of available physical memory is not sufficient to fulfill the request.
Operation not supported.
The operation, though supported in general, is not supported for the requested object or the requested arguments.
The SHM_PAGESIZE command is not supported on a nonteraspace shared memory segment.
Operation not permitted.
You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.
The cmd parameter is IPC_RMID, IPC_SET, SHM_SIZE, or SHM_PAGESIZE and both of the following are true:
Unknown system state.
The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.
None.
For an example of using this function, see Example: Using semaphore set and shared memory functions.