]> git.pld-linux.org Git - packages/man-pages.git/blob - shmctl.2
- separated POSIX man pages, rel. 1
[packages/man-pages.git] / shmctl.2
1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
2 .\"
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
6 .\"
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one
11 .\" 
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein.  The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
18 .\" professionally.
19 .\" 
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
22 .\"
23 .\" Modified Wed Jul 28 11:03:24 1993, Rik Faith <faith@cs.unc.edu>
24 .\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
25 .\"          with material from Giorgio Ciucci <giorgio@crcc.it>
26 .\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
27 .\" Modified Fri Jan 31 17:24:31 1997 by Eric S. Raymond <esr@thyrsus.com>
28 .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
29 .\" Modified 5 Jan 2002 Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
30 .\"
31 .TH SHMCTL 2 2002-01-05 "Linux 2.4.1" "Linux Programmer's Manual"
32 .SH NAME
33 shmctl \- shared memory control
34 .SH SYNOPSIS
35 .ad l
36 .B #include <sys/ipc.h>
37 .sp
38 .B #include <sys/shm.h>
39 .sp
40 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
41 .ad b
42 .SH DESCRIPTION
43 \fBshmctl()\fP
44 allows the user to receive information on a shared memory segment,
45 set the owner, group, and permissions of a shared memory segment,
46 or destroy a segment. The information about the segment identified by
47 \fIshmid\fP is returned in a \fIshmid_ds\fP
48 structure:
49 .PP
50 .in +4n
51 .nf
52 struct shmid_ds {
53     struct ipc_perm shm_perm;  /* operation perms */
54     int shm_segsz;             /* size of segment (bytes) */
55     time_t shm_atime;          /* last attach time */
56     time_t shm_dtime;          /* last detach time */
57     time_t shm_ctime;          /* last change time */
58     unsigned short shm_cpid;   /* pid of creator */
59     unsigned short shm_lpid;   /* pid of last operator */
60     short shm_nattch;          /* no. of current attaches */
61     ...
62 };
63 .fi
64 .in -4n
65 .PP
66 The highlighted fields in the member \fIshm_perm\fP can be set:
67 .PP
68 .in +4n
69 .nf
70 struct ipc_perm {
71     key_t  key;
72     \fBushort uid\fP;   /* \fBowner\fP euid and egid */
73     \fBushort gid\fP;
74     ushort cuid;  /* creator euid and egid */
75     ushort cgid;
76     \fBushort mode\fP;  /* lower 9 bits of access modes */
77     ushort seq;   /* sequence number */
78 };
79 .fi
80 .in -4n
81 .PP
82 The following \fIcmds\fP are available:
83 .br
84 .TP 12
85 .B IPC_STAT
86 is used to copy the information about the shared memory segment into
87 the buffer \fIbuf\fP. The user must have \fBread\fP access to the
88 shared memory segment.
89 .TP
90 .B IPC_SET
91 is used to apply the changes the user has made to the \fIuid\fP, \fIgid\fP,
92 or \fImode\fP members of the \fIshm_perms\fP field.  Only the lowest 9 bits
93 of \fImode\fP are used.  The
94 .I shm_ctime
95 member is also updated.  The user must be the owner, creator, or the
96 super-user.
97 .TP
98 .B IPC_RMID
99 is used to mark the segment as destroyed. It will actually be destroyed
100 after the last detach.  (I.e., when the
101 .I shm_nattch
102 member of the associated structure
103 .I shmid_ds
104 is zero.)  The user must be the owner, creator, or the super-user.
105 .PP
106 The user \fImust\fP ensure that a segment is eventually destroyed; otherwise
107 its pages that were faulted in will remain in memory or swap.
108 .PP
109 In addition, the \fBsuper-user\fP can prevent or allow swapping of a shared
110 memory segment with the following \fIcmds\fP: (Linux only)
111 .br
112 .TP 12
113 .B SHM_LOCK
114 prevents swapping of a shared memory segment. The user must fault in
115 any pages that are required to be present after locking is enabled.
116 .TP
117 .B SHM_UNLOCK
118 allows the shared memory segment to be swapped out.
119 .PP
120 The
121 .BR IPC_INFO ,
122 .BR SHM_STAT
123 and
124 .B SHM_INFO
125 control calls are used by the
126 .BR ipcs (8)
127 program to provide information on allocated resources.  In the future,
128 these may be modified as needed or moved to a proc file system interface.
129 .SH "RETURN VALUE"
130 0 is returned on success, \-1 on error.
131 .SH ERRORS
132 On error,
133 .B errno
134 will be set to one of the following:
135 .TP 12
136 .B EACCES
137 is returned if \fBIPC_STAT\fP is requested and
138 \fIshm_perm.modes\fP does not allow read access for
139 .IR msqid .
140 .TP
141 .B EFAULT
142 The argument
143 .I cmd
144 has value
145 .B IPC_SET
146 or
147 .B IPC_STAT
148 but the address pointed to by
149 .I buf
150 isn't accessible.
151 .TP
152 .B EINVAL
153 is returned if \fIshmid\fP is not a valid identifier, or \fIcmd\fP
154 is not a valid command.
155 .TP
156 .B EIDRM
157 is returned if \fIshmid\fP points to a removed identifier.
158 .TP
159 .B EPERM
160 is returned if \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
161 effective user ID of the calling process is not the creator
162 (as found in
163 .IR shm_perm.cuid ),
164 the owner
165 (as found in
166 .IR shm_perm.uid ),
167 or the super-user.
168 .TP
169 .B EOVERFLOW
170 is returned if \fBIPC_STAT\fP is attempted, and the gid or uid value
171 is too large to be stored in the structure pointed to by
172 .IR buf . 
173 .SH NOTE
174 Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2
175 and have become longs under Linux 2.4. To take advantage of this,
176 a recompilation under glibc-2.1.91 or later should suffice.
177 (The kernel distinguishes old and new calls by a IPC_64 flag in
178 .IR cmd .)
179 .SH "CONFORMING TO"
180 SVr4, SVID.  SVr4 documents additional error conditions EINVAL,
181 ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
182 an EIDRM error condition.
183 .SH "SEE ALSO"
184 .BR shmget (2),
185 .BR shmop (2)
This page took 0.089124 seconds and 3 git commands to generate.