SHMCTL - phpMan

SHMCTL(2) Linux Programmer’s Manual SHMCTL(2)

NAME
shmctl - shared memory control

SYNOPSIS
#include <sys/ipc.h>

#include <sys/shm.h>

int shmctl(int shmid, int cmd, struct shmid_ds *buf);

DESCRIPTION
shmctl() allows the user to receive information on a shared memory segment, 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 struc-
ture:

struct shmid_ds {
struct ipc_perm shm_perm; /* operation perms */
size_t 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 lowest 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 asso-
ciated structure shmid_ds is zero.) The user must be the owner, cre-
ator, 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, processes with appropriate privileges 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.

Processes are permitted to use SHM_LOCK and SHM_UNLOCK if they running with the
CAP_IPC_LOCK capability (normally only true for root) or if their current
RLIMIT_MEMLOCK resource limit is non-zero.

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 modi-
fied as needed or moved to a proc file system interface.

RETURN VALUE
0 is returned on success, -1 on error.

ERRORS
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.

NOTE
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 recompilation under
glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls
by a IPC_64 flag in cmd.)

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