xref: /freebsd/lib/libsys/shmctl.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87)
1*8269e767SBrooks Davis.\"
2*8269e767SBrooks Davis.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com>
3*8269e767SBrooks Davis.\"
4*8269e767SBrooks Davis.\" All rights reserved.
5*8269e767SBrooks Davis.\"
6*8269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
7*8269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
8*8269e767SBrooks Davis.\" are met:
9*8269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
10*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
11*8269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
12*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
13*8269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
14*8269e767SBrooks Davis.\"
15*8269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16*8269e767SBrooks Davis.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17*8269e767SBrooks Davis.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18*8269e767SBrooks Davis.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19*8269e767SBrooks Davis.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20*8269e767SBrooks Davis.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21*8269e767SBrooks Davis.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22*8269e767SBrooks Davis.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23*8269e767SBrooks Davis.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24*8269e767SBrooks Davis.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25*8269e767SBrooks Davis.\"
26*8269e767SBrooks Davis.Dd October 10, 2015
27*8269e767SBrooks Davis.Dt SHMCTL 2
28*8269e767SBrooks Davis.Os
29*8269e767SBrooks Davis.Sh NAME
30*8269e767SBrooks Davis.Nm shmctl
31*8269e767SBrooks Davis.Nd shared memory control
32*8269e767SBrooks Davis.Sh LIBRARY
33*8269e767SBrooks Davis.Lb libc
34*8269e767SBrooks Davis.Sh SYNOPSIS
35*8269e767SBrooks Davis.In sys/types.h
36*8269e767SBrooks Davis.In sys/ipc.h
37*8269e767SBrooks Davis.In sys/shm.h
38*8269e767SBrooks Davis.Ft int
39*8269e767SBrooks Davis.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf"
40*8269e767SBrooks Davis.Sh DESCRIPTION
41*8269e767SBrooks DavisPerforms the action specified by
42*8269e767SBrooks Davis.Fa cmd
43*8269e767SBrooks Davison the shared memory segment identified by
44*8269e767SBrooks Davis.Fa shmid :
45*8269e767SBrooks Davis.Bl -tag -width SHM_UNLOCKX
46*8269e767SBrooks Davis.It Dv IPC_STAT
47*8269e767SBrooks DavisFetch the segment's
48*8269e767SBrooks Davis.Fa "struct shmid_ds" ,
49*8269e767SBrooks Davisstoring it in the memory pointed to by
50*8269e767SBrooks Davis.Fa buf .
51*8269e767SBrooks Davis.\"
52*8269e767SBrooks Davis.\" XXX need to make sure that this is correct for FreeBSD
53*8269e767SBrooks Davis.\"
54*8269e767SBrooks Davis.It Dv IPC_SET
55*8269e767SBrooks DavisChanges the
56*8269e767SBrooks Davis.Fa shm_perm.uid ,
57*8269e767SBrooks Davis.Fa shm_perm.gid ,
58*8269e767SBrooks Davisand
59*8269e767SBrooks Davis.Fa shm_perm.mode
60*8269e767SBrooks Davismembers of the segment's
61*8269e767SBrooks Davis.Fa "struct shmid_ds"
62*8269e767SBrooks Davisto match those of the struct pointed to by
63*8269e767SBrooks Davis.Fa buf .
64*8269e767SBrooks DavisThe calling process's effective uid must
65*8269e767SBrooks Davismatch either
66*8269e767SBrooks Davis.Fa shm_perm.uid
67*8269e767SBrooks Davisor
68*8269e767SBrooks Davis.Fa shm_perm.cuid ,
69*8269e767SBrooks Davisor it must have superuser privileges.
70*8269e767SBrooks Davis.It Dv IPC_RMID
71*8269e767SBrooks DavisRemoves the segment from the system.
72*8269e767SBrooks DavisThe removal will not take
73*8269e767SBrooks Daviseffect until all processes having attached the segment have exited.
74*8269e767SBrooks DavisFor the operation
75*8269e767SBrooks Davisto succeed, the calling process's effective uid must match
76*8269e767SBrooks Davis.Fa shm_perm.uid
77*8269e767SBrooks Davisor
78*8269e767SBrooks Davis.Fa shm_perm.cuid ,
79*8269e767SBrooks Davisor the process must have superuser privileges.
80*8269e767SBrooks DavisIf the
81*8269e767SBrooks Davis.Va kern.ipc.shm_allow_removed
82*8269e767SBrooks Davis.Xr sysctl 3
83*8269e767SBrooks Davisvariable is set to 0, once the IPC_RMID operation has taken place,
84*8269e767SBrooks Davisno further processes will be allowed to attach the segment.
85*8269e767SBrooks Davis.\" .It Dv SHM_LOCK
86*8269e767SBrooks Davis.\" Locks the segment in memory.  The calling process must have
87*8269e767SBrooks Davis.\" superuser privileges. Not implemented in FreeBSD.
88*8269e767SBrooks Davis.\" .It Dv SHM_UNLOCK
89*8269e767SBrooks Davis.\" Unlocks the segment from memory.  The calling process must
90*8269e767SBrooks Davis.\" have superuser privileges.  Not implemented in FreeBSD.
91*8269e767SBrooks Davis.El
92*8269e767SBrooks Davis.Pp
93*8269e767SBrooks DavisThe
94*8269e767SBrooks Davis.Vt shmid_ds
95*8269e767SBrooks Davisstructure is defined as follows:
96*8269e767SBrooks Davis.\"
97*8269e767SBrooks Davis.\" I fiddled with the spaces a bit to make it fit well when viewed
98*8269e767SBrooks Davis.\" with nroff, but otherwise it is straight from sys/shm.h
99*8269e767SBrooks Davis.\"
100*8269e767SBrooks Davis.Bd -literal
101*8269e767SBrooks Davisstruct shmid_ds {
102*8269e767SBrooks Davis    struct ipc_perm shm_perm;   /* operation permission structure */
103*8269e767SBrooks Davis    size_t          shm_segsz;  /* size of segment in bytes */
104*8269e767SBrooks Davis    pid_t           shm_lpid;   /* process ID of last shared memory op */
105*8269e767SBrooks Davis    pid_t           shm_cpid;   /* process ID of creator */
106*8269e767SBrooks Davis    int             shm_nattch; /* number of current attaches */
107*8269e767SBrooks Davis    time_t          shm_atime;  /* time of last shmat() */
108*8269e767SBrooks Davis    time_t          shm_dtime;  /* time of last shmdt() */
109*8269e767SBrooks Davis    time_t          shm_ctime;  /* time of last change by shmctl() */
110*8269e767SBrooks Davis};
111*8269e767SBrooks Davis.Ed
112*8269e767SBrooks Davis.Sh RETURN VALUES
113*8269e767SBrooks Davis.Rv -std shmctl
114*8269e767SBrooks Davis.Sh ERRORS
115*8269e767SBrooks DavisThe
116*8269e767SBrooks Davis.Fn shmctl
117*8269e767SBrooks Davissystem call
118*8269e767SBrooks Daviswill fail if:
119*8269e767SBrooks Davis.Bl -tag -width Er
120*8269e767SBrooks Davis.It Bq Er EINVAL
121*8269e767SBrooks DavisInvalid operation, or
122*8269e767SBrooks Davisno shared memory segment was found corresponding to
123*8269e767SBrooks Davis.Fa shmid .
124*8269e767SBrooks Davis.\"
125*8269e767SBrooks Davis.\" XXX I think the following is right: ipcperm() only returns EPERM
126*8269e767SBrooks Davis.\"	when an attempt is made to modify (IPC_M) by a non-creator
127*8269e767SBrooks Davis.\"	non-owner
128*8269e767SBrooks Davis.It Bq Er EPERM
129*8269e767SBrooks DavisThe calling process's effective uid does not match the uid of
130*8269e767SBrooks Davisthe shared memory segment's owner or creator.
131*8269e767SBrooks Davis.It Bq Er EACCES
132*8269e767SBrooks DavisPermission denied due to mismatch between operation and mode of
133*8269e767SBrooks Davisshared memory segment.
134*8269e767SBrooks Davis.El
135*8269e767SBrooks Davis.Sh "SEE ALSO"
136*8269e767SBrooks Davis.Xr shmat 2 ,
137*8269e767SBrooks Davis.Xr shmdt 2 ,
138*8269e767SBrooks Davis.Xr shmget 2 ,
139*8269e767SBrooks Davis.Xr ftok 3
140