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