Shared Memory Control
The shmctl system call permits the user to perform a number of generalized control operations on an existing shared memory segment and on the system shared memory data structure (see Table 8.4).
Table 8.4. Summary of the shmctl System Call.
Include File(s) |
|
Manual Section |
2 |
|
Summary |
int shmctl(int shmid, int cmd, struct shmid_ds *buf); |
|||
Return |
Success |
Failure |
Sets errno |
|
-1 |
Yes |
There are three arguments for the shmctl system call. The first, shmid , is a valid shared memory segment identifier generated by a prior shmget system call. The second argument, cmd , specifies the operation shmctl is to perform. The third argument, buf , is a reference to a structure of the type shmid_ds .
The operations that shmctl will perform, which are specified by the following defined constants, consist of
- IPC_STAT Return the current values of the shmid_ds structure for the memory segment indicated by the shmid value. The returned information is stored in a user-generated structure, which is passed by reference as the third argument to shmctl . To specify IPC_STAT, the process must have read permission for the shared memory segment.
- IPC_SET Modify a limited number of members in the permission structure found within the shmid_ds structure. The permission structure members that can be modified are shm_perm.uid , shm_perm.gid , and shm_perm.mode . The accessing process must have the effective ID of the superuser or have an ID that is equivalent to either the shm_perm.cuid or shm_perm.uid value. To modify structure members, the following steps are usually taken. A structure of the type shmid_ds is allocated. The structure is initialized to the current system settings by calling shmctl with the IPC_STAT flag set and passing the reference to the new shmd_ds structure. The appropriate members of the structure are then assigned their new values. Finally, with the cmd argument set to IPC_SET, the shmctl system call is invoked a second time and passed the reference to the modified structure. To carry out this modification sequence, the accessing process must have read and write permissions for the shared memory segment. When IPC_SET is specified, the shm_ctime member is automatically updated with the current time.
- IPC_RMID Remove the system data structure for the referenced shared memory identifier ( shmid ). When specifying IPC_RMID, an address value of 0 is used for buf . The 0 address value is cast to the proper type, with ( shmid_ds * ). Once all references to the shared memory segment are eliminated (i.e., shm_nattch equals 0), the system will remove the actual segment. If a shmctl system call, specifying IPC_RMID, is not done, the memory segment will remain active and associated with its key value.
- SHM_LOCK Lock, in memory, the shared memory segment referenced by the shmid argument. A locked shared segment is not swapped out by the system thus avoiding I/O faults when referenced. Locking can only be specified by processes that have an effective ID equal to that of the superuser.
- SHM_UNLOCK Unlock the shared memory segment referenced by the shmid argument. Once unlocked the shared segment can be swapped out. Again, this can only be specified by processes that have an effective ID equal to that of the superuser.
If shmctl is successful, it returns a value of 0; otherwise , it returns a value of -1 and sets the value in errno to indicate the specific error condition. The values that errno may be assigned and their interpretation are shown in Table 8.5.
Table 8.5. shmctl Error Messages
# |
Constant |
perror Message |
Explanation |
---|---|---|---|
1 |
EPERM |
Operation not permitted |
|
13 |
EACCES |
Permission denied |
The requested operation is not allowed by current access permissions. |
12 |
ENOMEM |
Cannot allocate memory |
The cmd is SHM_LOCK, but there is insufficient memory available. |
14 |
EFAULT |
Bad address |
The third argument to shmctl , buf , contains a reference to an illegal address. |
22 |
EINVAL |
Invalid argument |
|
43 |
EIDRM |
Memory segment is marked as removed. |