PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       shmctl — XSI shared memory control operations

SYNOPSIS

       #include <sys/shm.h>

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

DESCRIPTION

       The  shmctl()  function  operates  on XSI shared memory (see the Base Definitions volume of POSIX.1‐2008,
       Section 3.342, Shared Memory Object).  It is unspecified whether this  function  interoperates  with  the
       realtime interprocess communication facilities defined in Section 2.8, Realtime.

       The  shmctl()  function  provides a variety of shared memory control operations as specified by cmd.  The
       following values for cmd are available:

       IPC_STAT    Place the current value of each member of the shmid_ds data structure associated  with  shmid
                   into  the  structure  pointed  to  by  buf.   The  contents  of  the structure are defined in
                   <sys/shm.h>.

       IPC_SET     Set the value of the following members of the shmid_ds data structure associated  with  shmid
                   to the corresponding value found in the structure pointed to by buf:

                       shm_perm.uid
                       shm_perm.gid
                       shm_perm.mode    Low-order nine bits.

                   Also,  the  shm_ctime  timestamp  shall  be  set to the current time, as described in Section
                   2.7.1, IPC General Description.

                   IPC_SET can only be executed by a process that has an effective user ID equal to either  that
                   of  a process with appropriate privileges or to the value of shm_perm.cuid or shm_perm.uid in
                   the shmid_ds data structure associated with shmid.

       IPC_RMID    Remove the shared memory identifier specified by shmid from the system and destroy the shared
                   memory segment and shmid_ds data structure associated with it. IPC_RMID can only be  executed
                   by a process that has an effective user ID equal to either that of a process with appropriate
                   privileges  or  to  the value of shm_perm.cuid or shm_perm.uid in the shmid_ds data structure
                   associated with shmid.

RETURN VALUE

       Upon successful completion, shmctl() shall return 0; otherwise, it shall  return  −1  and  set  errno  to
       indicate the error.

ERRORS

       The shmctl() function shall fail if:

       EACCES The  argument  cmd is equal to IPC_STAT and the calling process does not have read permission; see
              Section 2.7, XSI Interprocess Communication.

       EINVAL The value of shmid is not a valid shared memory identifier, or the value of cmd  is  not  a  valid
              command.

       EPERM  The  argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the calling process
              is not equal to that of a process with appropriate privileges and it is not equal to the value  of
              shm_perm.cuid or shm_perm.uid in the data structure associated with shmid.

       The shmctl() function may fail if:

       EOVERFLOW
              The  cmd  argument is IPC_STAT and the gid or uid value is too large to be stored in the structure
              pointed to by the buf argument.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The POSIX Realtime Extension defines alternative interfaces for interprocess  communication.  Application
       developers  who  need  to use IPC should design their applications so that modules using the IPC routines
       described in Section 2.7, XSI Interprocess Communication can be easily modified to  use  the  alternative
       interfaces.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section  2.7,  XSI  Interprocess  Communication,  Section  2.8,  Realtime,  shmat(),  shmdt(),  shmget(),
       shm_open(), shm_unlink()

       The Base Definitions volume of POSIX.1‐2008, Section 3.342, Shared Memory Object, <sys_shm.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In  the  event
       of  any  discrepancy between this version and the original IEEE and The Open Group Standard, the original
       IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at
       http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                                   2013                                        SHMCTL(3POSIX)