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
  52 Each shared memory segment has a data structure associated with it,
  53 parts of which may be altered by
  54 .Fn shmctl
  55 and parts of which determine the actions of
  56 .Fn shmctl .
  57
  58 This structure is defined as follows in
  59 .Aq Pa sys/shm.h :
  60 .Bd -literal
  61 struct shmid_ds {
  62     struct ipc_perm shm_perm;     /* operation permissions */
  63     int             shm_segsz;    /* size of segment in bytes */
  64     pid_t           shm_lpid;     /* pid of last shm op */
  65     pid_t           shm_cpid;     /* pid of creator */
  66     short           shm_nattch;   /* # of current attaches */
  67     time_t          shm_atime;    /* last shmat() time*/
  68     time_t          shm_dtime;    /* last shmdt() time */
  69     time_t          shm_ctime;    /* last change by shmctl() */
  70     void           *shm_internal; /* sysv stupidity */
  71 };
  72 .Ed
  73 The
  74 .Bf -literal
  75 ipc_perm
  76 .Ef
  77 structure used inside the
  78 .Bf -literal
  79 shmid_ds
  80 .Ef
  81 structure is defined in
  82 .Aq Pa sys/ipc.h
  83 and looks like this:
  84 .Bd -literal
  85 struct ipc_perm {
  86     ushort cuid; /* creator user id */
  87     ushort cgid; /* creator group id */
  88     ushort uid;  /* user id */
  89     ushort gid;  /* group id */
  90     ushort mode; /* r/w permission (see chmod(2)) */
  91     ushort seq;  /* sequence # (to generate unique msg/sem/shm id) */
  92     key_t key;   /* user specified msg/sem/shm key */
  93 };
  94 .Ed
  95
  96 The operation to be performed by
  97 .Fn shmctl
  98 is specified in
  99 .Fa cmd
 100 and is one of:
 101 .Bl -tag -width IPC_RMIDX
 102 .It Dv IPC_STAT
 103 Gather information about the shared memory segment and place it in the
 104 structure pointed to by
 105 .Fa buf .
 106 .It Dv IPC_SET
 107 Set the value of the
 108 .Va shm_perm.uid ,
 109 .Va shm_perm.gid
 110 and
 111 .Va shm_perm.mode
 112 fields in the structure associated with
 113 .Fa shmid .
 114 The values are taken from the corresponding fields in the structure
 115 pointed to by
 116 .Fa buf .
 117 This operation can only be executed by the super-user, or a process that
 118 has an effective user id equal to either
 119 .Va shm_perm.cuid
 120 or
 121 .Va shm_perm.uid
 122 in the data structure associated with the shared memory segment.
 123
 124 .It Dv IPC_RMID
 125 Remove the shared memory segment specified by
 126 .Fa shmid
 127 and destroy the data associated with it. Only the super-user or a process
 128 with an effective uid equal to the
 129 .Va shm_perm.cuid
 130 or
 131 .Va shm_perm.uid
 132 values in the data structure associated with the queue can do this.
 133 .El
 134
 135 The read and write permissions on a shared memory identifier
 136 are determined by the
 137 .Va shm_perm.mode
 138 field in the same way as is
 139 done with files (see
 140 .Xr chmod 2 ),
 141 but the effective uid can match either the
 142 .Va shm_perm.cuid
 143 field or the
 144 .Va shm_perm.uid
 145 field, and the
 146 effective gid can match either
 147 .Va shm_perm.cgid
 148 or
 149 .Va shm_perm.gid .
 150 .Sh RETURN VALUES
 151 Upon successful completion, a value of 0 is returned. Otherwise, -1 is
 152 returned and the global variable
 153 .Va errno
 154 is set to indicate the error.
 155 .Sh ERRORS
 156 .Fn shmctl
 157 will fail if:
 158 .Bl -tag -width Er
 159 .It Bq Er EPERM
 160 .Fa cmd
 161 is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
 162 the effective uid match either the
 163 .Va shm_perm.uid
 164 or
 165 .Va shm_perm.cuid
 166 fields of the data structure associated with the shared memory segment.
 167
 168 An attempt is made to increase the value of
 169 .Va shm_qbytes
 170 through IPC_SET
 171 but the caller is not the super-user.
 172 .It Bq Er EACCESS
 173 The command is IPC_STAT
 174 and the caller has no read permission for this shared memory segment.
 175 .It Bq Er EINVAL
 176 .Fa shmid
 177 is not a valid shared memory segment identifier.
 178
 179 .Va cmd
 180 is not a valid command.
 181 .It Bq Er EFAULT
 182 .Fa buf
 183 specifies an invalid address.
 184 .El
 185 .Sh SEE ALSO
 186 .Xr shmat 2 ,
 187 .Xr shmdt 2 ,
 188 .Xr shmget 2