1.\" $OpenBSD: shmctl.2,v 1.19 2021/11/21 23:44:55 jan 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: November 21 2021 $ 34.Dt SHMCTL 2 35.Os 36.Sh NAME 37.Nm shmctl 38.Nd shared memory control operations 39.Sh SYNOPSIS 40.In sys/shm.h 41.Ft int 42.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" 43.Sh DESCRIPTION 44The 45.Fn shmctl 46system call performs some control operations on the shared memory area 47specified by 48.Fa shmid . 49.Pp 50Each shared memory segment has a data structure associated with it, 51parts of which may be altered by 52.Fn shmctl 53and parts of which determine the actions of 54.Fn shmctl . 55.Pp 56This structure is defined as follows in 57.In sys/shm.h : 58.Bd -literal 59struct 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.Pp 72The 73.Bf -literal 74ipc_perm 75.Ef 76structure used inside the 77.Bf -literal 78shmid_ds 79.Ef 80structure is defined in 81.In sys/ipc.h 82and looks like this: 83.Bd -literal 84struct ipc_perm { 85 uid_t cuid; /* creator user id */ 86 gid_t cgid; /* creator group id */ 87 uid_t uid; /* user id */ 88 gid_t gid; /* group id */ 89 mode_t mode; /* r/w permission (see chmod(2)) */ 90 u_short seq; /* sequence # */ 91 /* (to generate unique msg/sem/shm id) */ 92 key_t key; /* user specified msg/sem/shm key */ 93}; 94.Ed 95.Pp 96The operation to be performed by 97.Fn shmctl 98is specified in 99.Fa cmd 100and is one of: 101.Bl -tag -width IPC_RMIDX 102.It Dv IPC_STAT 103Gather information about the shared memory segment and place it in the 104structure pointed to by 105.Fa buf . 106.It Dv IPC_SET 107Set the value of the 108.Va shm_perm.uid , 109.Va shm_perm.gid 110and 111.Va shm_perm.mode 112fields in the structure associated with 113.Fa shmid . 114The values are taken from the corresponding fields in the structure 115pointed to by 116.Fa buf . 117This operation can only be executed by the superuser, or a process that 118has an effective user ID equal to either 119.Va shm_perm.cuid 120or 121.Va shm_perm.uid 122in the data structure associated with the shared memory segment. 123.It Dv IPC_RMID 124Mark the shared memory segment specified by 125.Fa shmid 126for removal when it is no longer in use by any process. 127When it is removed, all data associated with it will be destroyed too. 128Only the superuser or a process with 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 151.Rv -std 152.Sh ERRORS 153.Fn shmctl 154will fail if: 155.Bl -tag -width Er 156.It Bq Er EPERM 157.Fa cmd 158is equal to 159.Dv IPC_SET 160or 161.Dv IPC_RMID 162and the caller is not the superuser, nor does 163the effective UID match either the 164.Va shm_perm.uid 165or 166.Va shm_perm.cuid 167fields of the data structure associated with the shared memory segment. 168.Pp 169An attempt is made to increase the value of 170.Va shm_qbytes 171through 172.Dv IPC_SET 173but the caller is not the superuser. 174.It Bq Er EACCES 175The command is 176.Dv IPC_STAT 177and the caller has no read permission for this shared memory segment. 178.It Bq Er EINVAL 179.Fa shmid 180is not a valid shared memory segment identifier. 181.Pp 182.Va cmd 183is not a valid command. 184.It Bq Er EFAULT 185.Fa buf 186specifies an invalid address. 187.El 188.Sh SEE ALSO 189.Xr ipcrm 1 , 190.Xr ipcs 1 , 191.Xr shmat 2 , 192.Xr shmget 2 193.Sh STANDARDS 194Segments which are marked for removal (but not yet removed 195since they are still in use) can be attached to by new callers 196using 197.Xr shmat 2 . 198This is permitted as an extension beyond the standards. 199