1.\" $OpenBSD: shmctl.2,v 1.13 2007/05/31 19:19:33 jmc Exp $ 2.\" $NetBSD: shmctl.2,v 1.3 1997/03/27 08:20:39 mikel 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 $Mdocdate: May 31 2007 $ 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/shm.h> 43.Ft int 44.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" 45.Sh DESCRIPTION 46The 47.Fn shmctl 48system call performs some control operations on the shared memory area 49specified by 50.Fa shmid . 51.Pp 52Each shared memory segment has a data structure associated with it, 53parts of which may be altered by 54.Fn shmctl 55and parts of which determine the actions of 56.Fn shmctl . 57.Pp 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 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.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 cuid; /* creator user id */ 88 gid_t cgid; /* creator group id */ 89 uid_t uid; /* user id */ 90 gid_t gid; /* group id */ 91 mode_t mode; /* r/w permission (see chmod(2)) */ 92 u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ 93 key_t key; /* user specified msg/sem/shm key */ 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 superuser, 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.Pp 125.It Dv IPC_RMID 126Remove the shared memory segment specified by 127.Fa shmid 128and destroy the data associated with it. 129Only the superuser or a process with an effective UID equal to the 130.Va shm_perm.cuid 131or 132.Va shm_perm.uid 133values in the data structure associated with the queue can do this. 134.El 135.Pp 136The read and write permissions on a shared memory identifier 137are determined by the 138.Va shm_perm.mode 139field in the same way as is 140done with files (see 141.Xr chmod 2 ) , 142but the effective UID can match either the 143.Va shm_perm.cuid 144field or the 145.Va shm_perm.uid 146field, and the 147effective GID can match either 148.Va shm_perm.cgid 149or 150.Va shm_perm.gid . 151.Sh RETURN VALUES 152Upon successful completion, a value of 0 is returned. 153Otherwise, \-1 is returned and the global variable 154.Va errno 155is set to indicate the error. 156.Sh ERRORS 157.Fn shmctl 158will fail if: 159.Bl -tag -width Er 160.It Bq Er EPERM 161.Fa cmd 162is equal to 163.Dv IPC_SET 164or 165.Dv IPC_RMID 166and the caller is not the superuser, nor does 167the effective UID match either the 168.Va shm_perm.uid 169or 170.Va shm_perm.cuid 171fields of the data structure associated with the shared memory segment. 172.Pp 173An attempt is made to increase the value of 174.Va shm_qbytes 175through 176.Dv IPC_SET 177but the caller is not the superuser. 178.It Bq Er EACCES 179The command is 180.Dv IPC_STAT 181and the caller has no read permission for this shared memory segment. 182.It Bq Er EINVAL 183.Fa shmid 184is not a valid shared memory segment identifier. 185.Pp 186.Va cmd 187is not a valid command. 188.It Bq Er EFAULT 189.Fa buf 190specifies an invalid address. 191.El 192.Sh SEE ALSO 193.Xr shmat 2 , 194.Xr shmget 2 195