shmctl(2) - NetBSD Manual Pages

SHMCTL(2)                 NetBSD System Calls Manual                 SHMCTL(2)


NAME

     shmctl -- shared memory control operations


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <sys/shm.h>

     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 exe-
                cuted 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 deter-
     mined 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 seg-
                        ment.

                        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.

NetBSD 9.3                     November 25, 2006                    NetBSD 9.3