huschi.net

SHMCTL(3P)                 POSIX Programmer's Manual                SHMCTL(3P)

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 Defi-
       nitions  volume  of  IEEE Std 1003.1-2001, Section 3.340, Shared Memory
       Object). It is unspecified whether this function interoperates with the
       realtime interprocess communication facilities defined in Realtime .
       The shmctl() function provides a variety of shared memory control oper-
       ations 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.
       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 XSI Interprocess Communica-
              tion .
       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 effec-
              tive 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  argu-
              ment.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       The  POSIX Realtime Extension defines alternative interfaces for inter-
       process communication. Application  developers  who  need  to  use  IPC
       should design their applications so that modules using the IPC routines
       described in XSI Interprocess Communication can be easily  modified  to
       use the alternative interfaces.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       XSI  Interprocess  Communication, Realtime, shmat(), shmdt(), shmget(),
       shm_open(),   shm_unlink(),   the   Base    Definitions    volume    of
       IEEE Std 1003.1-2001, <sys/shm.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                           SHMCTL(3P)