November 25, 2006 SHMCTL 2

### NAME

shmctl - shared memory control operations

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

The shmctl(``) system call performs control operations on the shared memory segment specified by ```shmid`.

Each shared memory segment has a shmid_ds structure associated with it which contains the following members: ``

        struct ipc_perm shm_perm;   /* operation permissions */
        size_t          shm_segsz;  /* size of segment in bytes */
        pid_t           shm_lpid;   /* pid of last shm op */
        pid_t           shm_cpid;   /* pid of creator */
        shmatt_t        shm_nattch; /* # of current attaches */
        time_t          shm_atime;  /* last shmat() time */
        time_t          shm_dtime;  /* last shmdt() time */
        time_t          shm_ctime;  /* last change by shmctl() */

The ipc_perm structure used inside the shmid_ds structure is defined in <```sys/ipc.h`> and contains the following members: ``

        uid_t cuid;  /* creator user id */
        gid_t cgid;  /* creator group id */
        uid_t uid;   /* user id */
        gid_t gid;   /* group id */
        mode_t mode; /* permission (lower 9 bits) */

The operation to be performed by shmctl(``) is specified in ```cmd` and is one of:

```IPC_STAT`
  Gather information about the shared memory segment and place it in the structure pointed to by ```buf`.

```IPC_SET`
  Set the value of the shm_perm.uid, shm_perm.gid and shm_perm.mode fields in the structure associated with ```shmid`. The values are taken from the corresponding fields in the structure pointed to by ```buf`. This operation can only be executed by the super-user, or a process that has an effective user id equal to either shm_perm.cuid or shm_perm.uid in the data structure associated with the shared memory segment.

```IPC_RMID`
  Remove the shared memory segment specified by ```shmid` and destroy the data associated with it. Only the super-user or a process with an effective uid equal to the shm_perm.cuid or shm_perm.uid values in the data structure associated with the segment can do this.

```SHM_LOCK`
  Lock the shared memory segment specified by ```shmid` in memory. This operation can only be executed by the super-user.

```SHM_UNLOCK`
  Unlock the shared memory segment specified by ```shmid`. This operation can only be executed by the super-user.

The read and write permissions on a shared memory identifier are determined by the shm_perm.mode field in the same way as is done with files (see chmod(2)), but the effective uid can match either the shm_perm.cuid field or the shm_perm.uid field, and the effective gid can match either shm_perm.cgid or shm_perm.gid.

### RETURN VALUES

Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

### ERRORS

shmctl(``) will fail if:

[```EACCES`]
  The command is ```IPC_STAT` and the caller has no read permission for this shared memory segment.

[```EFAULT`]
  ```buf` specifies an invalid address.

[```EINVAL`]
  ```shmid` is not a valid shared memory segment identifier.

  cmd is not a valid command.

[```ENOMEM`]
  The ```cmd` is equal to ```SHM_LOCK` and there is not enough physical memory.

[```EPERM`]
  ```cmd` is equal to ```IPC_SET` or ```IPC_RMID` and the caller is not the super-user, nor does the effective uid match either the shm_perm.uid or shm_perm.cuid fields of the data structure associated with the shared memory segment.

  An attempt was made to increase the value of shm_qbytes through ```IPC_SET` but the caller is not the super-user.

  The ```cmd` is equal to ```SHM_LOCK` or ```SHM_UNLOCK` and the caller is not the super-user.

### SEE ALSO

ipcrm(1), ipcs(1), shmat(2), shmget(2)

### STANDARDS

The shmctl system call conforms to X/Open System Interfaces and Headers Issue 5 (``XSH5'') .

### HISTORY

Shared memory segments appeared in the first release of `AT&T` System V `UNIX`.