bsd/man/man2/shmctl.2

   1 .\"   $OpenBSD: shmctl.2,v 1.2 1996/10/08 01:20:15 michaels Exp $
   2 .\"     $NetBSD: shmctl.2,v 1.1 1995/10/16 23:49:30 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1995 Frank van der Linden
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"      This product includes software developed for the NetBSD Project
  18 .\"      by Frank van der Linden
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"/
  33 .Dd August 17, 1995
  34 .Dt SHMCTL 2
  35 .Os
  36 .Sh NAME
  37 .Nm shmctl
  38 .Nd shared memory control operations
  39 .Sh SYNOPSIS
  40 .Fd #include <sys/types.h>
  41 .Fd #include <sys/ipc.h>
  42 .Fd #include <sys/msg.h>
  43 .Ft int
  44 .Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn shmctl
  48 system call performs some control operations on the shared memory area
  49 specified by
  50 .Fa shmid .
  51 Each shared memory segment has a data structure associated with it,
  52 parts of which may be altered by
  53 .Fn shmctl
  54 and parts of which determine the actions of
  55 .Fn shmctl .
  56 This structure is defined as follows in
  57 .Aq Pa sys/shm.h :
  58 .Bd -literal
  59 struct shmid_ds {
  60     struct ipc_perm shm_perm;     /* operation permissions */
  61     int             shm_segsz;    /* size of segment in bytes */
  62     pid_t           shm_lpid;     /* pid of last shm op */
  63     pid_t           shm_cpid;     /* pid of creator */
  64     short           shm_nattch;   /* # of current attaches */
  65     time_t          shm_atime;    /* last shmat() time*/
  66     time_t          shm_dtime;    /* last shmdt() time */
  67     time_t          shm_ctime;    /* last change by shmctl() */
  68     void           *shm_internal; /* sysv stupidity */
  69 };
  70 .Ed
  71 The
  72 .Bf -literal
  73 ipc_perm
  74 .Ef
  75 structure used inside the
  76 .Bf -literal
  77 shmid_ds
  78 .Ef
  79 structure is defined in
  80 .Aq Pa sys/ipc.h
  81 and looks like this:
  82 .Bd -literal
  83 struct ipc_perm {
  84     ushort cuid; /* creator user id */
  85     ushort cgid; /* creator group id */
  86     ushort uid;  /* user id */
  87     ushort gid;  /* group id */
  88     ushort mode; /* r/w permission (see chmod(2)) */
  89     ushort seq;  /* sequence # (to generate unique msg/sem/shm id) */
  90     key_t key;   /* user specified msg/sem/shm key */
  91 };
  92 .Ed
  93 The operation to be performed by
  94 .Fn shmctl
  95 is specified in
  96 .Fa cmd
  97 and is one of:
  98 .Bl -tag -width IPC_RMIDX
  99 .It Dv IPC_STAT
 100 Gather information about the shared memory segment and place it in the
 101 structure pointed to by
 102 .Fa buf .
 103 .It Dv IPC_SET
 104 Set the value of the
 105 .Va shm_perm.uid ,
 106 .Va shm_perm.gid
 107 and
 108 .Va shm_perm.mode
 109 fields in the structure associated with
 110 .Fa shmid .
 111 The values are taken from the corresponding fields in the structure
 112 pointed to by
 113 .Fa buf .
 114 This operation can only be executed by the super-user, or a process that
 115 has an effective user id equal to either
 116 .Va shm_perm.cuid
 117 or
 118 .Va shm_perm.uid
 119 in the data structure associated with the shared memory segment.
 120 .It Dv IPC_RMID
 121 Remove the shared memory segment specified by
 122 .Fa shmid
 123 and destroy the data associated with it. Only the super-user or a process
 124 with an effective uid equal to the
 125 .Va shm_perm.cuid
 126 or
 127 .Va shm_perm.uid
 128 values in the data structure associated with the queue can do this.
 129 .El
 130 The read and write permissions on a shared memory identifier
 131 are determined by the
 132 .Va shm_perm.mode
 133 field in the same way as is
 134 done with files (see
 135 .Xr chmod 2 ),
 136 but the effective uid can match either the
 137 .Va shm_perm.cuid
 138 field or the
 139 .Va shm_perm.uid
 140 field, and the
 141 effective gid can match either
 142 .Va shm_perm.cgid
 143 or
 144 .Va shm_perm.gid .
 145 .Sh RETURN VALUES
 146 Upon successful completion, a value of 0 is returned. Otherwise, -1 is
 147 returned and the global variable
 148 .Va errno
 149 is set to indicate the error.
 150 .Sh ERRORS
 151 .Fn shmctl
 152 will fail if:
 153 .Bl -tag -width Er
 154 .It Bq Er EPERM
 155 .Fa cmd
 156 is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
 157 the effective uid match either the
 158 .Va shm_perm.uid
 159 or
 160 .Va shm_perm.cuid
 161 fields of the data structure associated with the shared memory segment.
 162 An attempt is made to increase the value of
 163 .Va shm_qbytes
 164 through IPC_SET
 165 but the caller is not the super-user.
 166 .It Bq Er EACCES
 167 The command is IPC_STAT
 168 and the caller has no read permission for this shared memory segment.
 169 .It Bq Er EINVAL
 170 .Fa shmid
 171 is not a valid shared memory segment identifier.
 172 .Va cmd
 173 is not a valid command.
 174 .It Bq Er EFAULT
 175 .Fa buf
 176 specifies an invalid address.
 177 .El
 178 .Sh SEE ALSO
 179 .Xr shmat 2 ,
 180 .Xr shmdt 2 ,
 181 .Xr shmget 2