- online man pages   

Linux man pages : shmctl (2)
SHMCTL(2)		   Linux Programmer's Manual		     SHMCTL(2)


shmctl - shared memory control


#include <sys/ipc.h> #include <sys/shm.h> int shmctl(int shmid, int cmd, struct shmid_ds *buf);


shmctl() allows the user to receive information on a shared memory seg- ment, set the owner, group, and permissions of a shared memory segment, or destroy a segment. The information about the segment identified by shmid is returned in a shmid_ds structure: struct shmid_ds { struct ipc_perm shm_perm; /* operation perms */ int shm_segsz; /* size of segment (bytes) */ time_t shm_atime; /* last attach time */ time_t shm_dtime; /* last detach time */ time_t shm_ctime; /* last change time */ unsigned short shm_cpid; /* pid of creator */ unsigned short shm_lpid; /* pid of last operator */ short shm_nattch; /* no. of current attaches */ ... }; The highlighted fields in the member shm_perm can be set: struct ipc_perm { key_t key; ushort uid; /* owner euid and egid */ ushort gid; ushort cuid; /* creator euid and egid */ ushort cgid; ushort mode; /* lower 9 bits of access modes */ ushort seq; /* sequence number */ }; The following cmds are available: IPC_STAT is used to copy the information about the shared memory segment into the buffer buf. The user must have read access to the shared memory segment. IPC_SET is used to apply the changes the user has made to the uid, gid, or mode members of the shm_perms field. Only the low- est 9 bits of mode are used. The shm_ctime member is also updated. The user must be the owner, creator, or the super-user. IPC_RMID is used to mark the segment as destroyed. It will actually be destroyed after the last detach. (I.e., when the shm_nattch member of the associated structure shmid_ds is zero.) The user must be the owner, creator, or the super- user. The user must ensure that a segment is eventually destroyed; otherwise its pages that were faulted in will remain in memory or swap. In addition, the super-user can prevent or allow swapping of a shared memory segment with the following cmds: (Linux only) SHM_LOCK prevents swapping of a shared memory segment. The user must fault in any pages that are required to be present after locking is enabled. SHM_UNLOCK allows the shared memory segment to be swapped out. The IPC_INFO, SHM_STAT and SHM_INFO control calls are used by the ipcs(8) program to provide information on allocated resources. In the future, these may be modified as needed or moved to a proc file system interface.


0 is returned on success, -1 on error.


On error, errno will be set to one of the following: EACCES is returned if IPC_STAT is requested and shm_perm.modes does not allow read access for shmid. EFAULT The argument cmd has value IPC_SET or IPC_STAT but the address pointed to by buf isn't accessible. EINVAL is returned if shmid is not a valid identifier, or cmd is not a valid command. EIDRM is returned if shmid points to a removed identifier. EPERM is returned if IPC_SET or IPC_RMID is attempted, and the effective user ID of the calling process is not the creator (as found in shm_perm.cuid), the owner (as found in shm_perm.uid), or the super-user. EOVERFLOW is returned if IPC_STAT is attempted, and the gid or uid value is too large to be stored in the structure pointed to by buf.


Various fields in a struct shmid_ds were shorts under Linux 2.2 and have become longs under Linux 2.4. To take advantage of this, a recom- pilation under glibc-2.1.91 or later should suffice. (The kernel dis- tinguishes old and new calls by a IPC_64 flag in cmd.)


SVr4, SVID. SVr4 documents additional error conditions EINVAL, ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents an EIDRM error condition.


shmget(2), shmop(2) Linux 2.4.1 2002-01-05 SHMCTL(2)