1.\" $NetBSD: shmctl.2,v 1.13 2002/06/16 22:39:32 wiz 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 June 17, 2002 33.Dt SHMCTL 2 34.Os 35.Sh NAME 36.Nm shmctl 37.Nd shared memory control operations 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.Fd #include \*[Lt]sys/shm.h\*[Gt] 42.Ft int 43.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" 44.Sh DESCRIPTION 45The 46.Fn shmctl 47system call performs control operations on the shared memory segment 48specified by 49.Fa shmid . 50.Pp 51Each shared memory segment has a 52.Sy shmid_ds 53structure associated with it which contains the following members: 54.Bd -literal 55 struct ipc_perm shm_perm; /* operation permissions */ 56 size_t shm_segsz; /* size of segment in bytes */ 57 pid_t shm_lpid; /* pid of last shm op */ 58 pid_t shm_cpid; /* pid of creator */ 59 shmatt_t shm_nattch; /* # of current attaches */ 60 time_t shm_atime; /* last shmat() time*/ 61 time_t shm_dtime; /* last shmdt() time */ 62 time_t shm_ctime; /* last change by shmctl() */ 63.Ed 64.Pp 65The 66.Sy ipc_perm 67structure used inside the 68.Sy shmid_ds 69structure is defined in 70.Aq Pa sys/ipc.h 71and contains the following members: 72.Bd -literal 73 uid_t cuid; /* creator user id */ 74 gid_t cgid; /* creator group id */ 75 uid_t uid; /* user id */ 76 gid_t gid; /* group id */ 77 mode_t mode; /* permission (lower 9 bits) */ 78.Ed 79.Pp 80The operation to be performed by 81.Fn shmctl 82is specified in 83.Fa cmd 84and is one of: 85.Bl -tag -width IPC_RMIDX 86.It Dv IPC_STAT 87Gather information about the shared memory segment and place it in the 88structure pointed to by 89.Fa buf . 90.It Dv IPC_SET 91Set the value of the 92.Va shm_perm.uid , 93.Va shm_perm.gid 94and 95.Va shm_perm.mode 96fields in the structure associated with 97.Fa shmid . 98The values are taken from the corresponding fields in the structure 99pointed to by 100.Fa buf . 101This operation can only be executed by the super-user, or a process that 102has an effective user id equal to either 103.Va shm_perm.cuid 104or 105.Va shm_perm.uid 106in the data structure associated with the shared memory segment. 107.It Dv IPC_RMID 108Remove the shared memory segment specified by 109.Fa shmid 110and destroy the data associated with it. 111Only the super-user or a process with an effective uid equal to the 112.Va shm_perm.cuid 113or 114.Va shm_perm.uid 115values in the data structure associated with the queue can do this. 116.El 117.Pp 118The read and write permissions on a shared memory identifier 119are determined by the 120.Va shm_perm.mode 121field in the same way as is 122done with files (see 123.Xr chmod 2 ) , 124but the effective uid can match either the 125.Va shm_perm.cuid 126field or the 127.Va shm_perm.uid 128field, and the 129effective gid can match either 130.Va shm_perm.cgid 131or 132.Va shm_perm.gid . 133.Sh RETURN VALUES 134Upon successful completion, a value of 0 is returned. 135Otherwise, -1 is returned and the global variable 136.Va errno 137is set to indicate the error. 138.Sh ERRORS 139.Fn shmctl 140will fail if: 141.Bl -tag -width Er 142.It Bq Er EPERM 143.Fa cmd 144is equal to 145.Dv IPC_SET 146or 147.Dv IPC_RMID 148and the caller is not the super-user, nor does 149the effective uid match either the 150.Va shm_perm.uid 151or 152.Va shm_perm.cuid 153fields of the data structure associated with the shared memory segment. 154.Pp 155An attempt was made to increase the value of 156.Va shm_qbytes 157through 158.Dv IPC_SET 159but the caller is not the super-user. 160.It Bq Er EACCES 161The command is 162.Dv IPC_STAT 163and the caller has no read permission for this shared memory segment. 164.It Bq Er EINVAL 165.Fa shmid 166is not a valid shared memory segment identifier. 167.Pp 168.Va cmd 169is not a valid command. 170.It Bq Er EFAULT 171.Fa buf 172specifies an invalid address. 173.El 174.Sh SEE ALSO 175.Xr ipcrm 1 , 176.Xr ipcs 1 , 177.Xr shmat 2 , 178.Xr shmget 2 179.Sh STANDARDS 180The 181.Nm 182system call conforms to 183.St -xsh5 . 184.Sh HISTORY 185Shared memory segments appeared in the first release of 186.At V . 187