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/shm.h> 41.Ft int 42.Fo shmctl 43.Fa "int shmid" 44.Fa "int cmd" 45.Fa "struct shmid_ds *buf" 46.Fc 47.Sh DESCRIPTION 48The 49.Fn shmctl 50system call performs some control operations on the shared memory area 51specified by 52.Fa shmid . 53Each shared memory segment has a data structure associated with it, 54parts of which may be altered by 55.Fn shmctl 56and parts of which determine the actions of 57.Fn shmctl . 58This structure is defined as follows in 59.Aq Pa sys/shm.h : 60.Bd -literal 61struct shmid_ds { 62 struct ipc_perm shm_perm; /* operation permissions */ 63 size_t 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.Pp 74The 75.Bf -literal 76ipc_perm 77.Ef 78structure used inside the 79.Bf -literal 80shmid_ds 81.Ef 82structure is defined in 83.Aq Pa sys/ipc.h 84and looks like this: 85.Bd -literal 86struct ipc_perm { 87 uid_t uid; /* Owner's user ID */ 88 gid_t gid; /* Owner's group ID */ 89 uid_t cuid; /* Creator's user ID */ 90 gid_t cgid; /* Creator's group ID */ 91 mode_t mode; /* r/w permission (see chmod(2)) */ 92 unsigned short _seq; /* Reserved for internal use */ 93 key_t _key; /* Reserved for internal use */ 94}; 95.Ed 96.Pp 97The operation to be performed by 98.Fn shmctl 99is specified in 100.Fa cmd 101and is one of: 102.Bl -tag -width IPC_RMIDX 103.It Dv IPC_STAT 104Gather information about the shared memory segment and place it in the 105structure pointed to by 106.Fa buf . 107.It Dv IPC_SET 108Set the value of the 109.Va shm_perm.uid , 110.Va shm_perm.gid 111and 112.Va shm_perm.mode 113fields in the structure associated with 114.Fa shmid . 115The values are taken from the corresponding fields in the structure 116pointed to by 117.Fa buf . 118This operation can only be executed by the super-user, or a process that 119has an effective user id equal to either 120.Va shm_perm.cuid 121or 122.Va shm_perm.uid 123in the data structure associated with the shared memory segment. 124.It Dv IPC_RMID 125Remove the shared memory segment specified by 126.Fa shmid 127and destroy the data associated with it. Only the super-user or a process 128with an effective uid equal to the 129.Va shm_perm.cuid 130or 131.Va shm_perm.uid 132values in the data structure associated with the queue can do this. 133.El 134.Pp 135The read and write permissions on a shared memory identifier 136are determined by the 137.Va shm_perm.mode 138field in the same way as is 139done with files (see 140.Xr chmod 2 ), 141but the effective uid can match either the 142.Va shm_perm.cuid 143field or the 144.Va shm_perm.uid 145field, and the 146effective gid can match either 147.Va shm_perm.cgid 148or 149.Va shm_perm.gid . 150.Sh RETURN VALUES 151Upon successful completion, a value of 0 is returned. 152Otherwise, -1 is returned and the global variable 153.Va errno 154is set to indicate the error. 155.Sh ERRORS 156.Fn shmctl 157will fail if: 158.Bl -tag -width Er 159.\" =========== 160.It Bq Er EACCES 161The command is IPC_STAT 162and the caller has no read permission for this shared memory segment. 163.\" =========== 164.It Bq Er EFAULT 165.Fa buf 166specifies an invalid address. 167.\" =========== 168.It Bq Er EINVAL 169.Fa shmid 170is not a valid shared memory segment identifier. 171.Va cmd 172is not a valid command. 173.\" =========== 174.It Bq Er EPERM 175.Fa cmd 176is equal to IPC_SET or IPC_RMID and the caller is not the super-user,\ 177nor does the effective uid match either the 178.Va shm_perm.uid 179or 180.Va shm_perm.cuid 181fields of the data structure associated with the shared memory segment. 182An attempt is made to increase the value of 183.Va shm_qbytes 184through IPC_SET 185but the caller is not the super-user. 186.El 187.Sh LEGACY SYNOPSIS 188.Fd #include <sys/types.h> 189.Fd #include <sys/ipc.h> 190.Fd #include <sys/shm.h> 191.Pp 192All of these include files are necessary. 193.Sh LEGACY DESCRIPTION 194The 195.Bf -literal 196ipc_perm 197.Ef 198structure used inside the 199.Bf -literal 200shmid_ds 201.Ef 202structure, as defined in 203.Aq Pa sys/ipc.h , 204looks like this: 205.Bd -literal 206struct ipc_perm { 207 __uint16_t cuid; /* Creator's user id */ 208 __uint16_t cgid; /* Creator's group id */ 209 __uint16_t uid; /* Owner's user id */ 210 __uint16_t gid; /* Owner's group id */ 211 mode_t mode; /* r/w permission (see chmod(2)) */ 212 __uint16_t seq; /* Reserved for internal use */ 213 key_t key; /* Reserved for internal use */ 214}; 215.Ed 216.Pp 217This structure is maintained for binary backward compatibility 218with previous versions of the interface. 219New code should not use this interface, 220because ID values may be truncated. 221.Pp 222Specifically, 223LEGACY mode limits the allowable uid/gid ranges to 0-32767. 224If the user has a UID that is out of this range (e.g., "nobody"), 225software using the LEGACY API will not behave as expected. 226.Sh SEE ALSO 227.Xr shmat 2 , 228.Xr shmdt 2 , 229.Xr shmget 2 , 230.Xr compat 5 231