]> git.pld-linux.org Git - packages/man-pages.git/blame - shmctl.2
- separated POSIX man pages, rel. 1
[packages/man-pages.git] / shmctl.2
CommitLineData
bc191751 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
33shmctl \- 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
44allows the user to receive information on a shared memory segment,
45set the owner, group, and permissions of a shared memory segment,
46or destroy a segment. The information about the segment identified by
47\fIshmid\fP is returned in a \fIshmid_ds\fP
48structure:
49.PP
50.in +4n
51.nf
52struct 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
66The highlighted fields in the member \fIshm_perm\fP can be set:
67.PP
68.in +4n
69.nf
70struct 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
82The following \fIcmds\fP are available:
83.br
84.TP 12
85.B IPC_STAT
86is used to copy the information about the shared memory segment into
87the buffer \fIbuf\fP. The user must have \fBread\fP access to the
88shared memory segment.
89.TP
90.B IPC_SET
91is used to apply the changes the user has made to the \fIuid\fP, \fIgid\fP,
92or \fImode\fP members of the \fIshm_perms\fP field. Only the lowest 9 bits
93of \fImode\fP are used. The
94.I shm_ctime
95member is also updated. The user must be the owner, creator, or the
96super-user.
97.TP
98.B IPC_RMID
99is used to mark the segment as destroyed. It will actually be destroyed
100after the last detach. (I.e., when the
101.I shm_nattch
102member of the associated structure
103.I shmid_ds
104is zero.) The user must be the owner, creator, or the super-user.
105.PP
106The user \fImust\fP ensure that a segment is eventually destroyed; otherwise
107its pages that were faulted in will remain in memory or swap.
108.PP
109In addition, the \fBsuper-user\fP can prevent or allow swapping of a shared
110memory segment with the following \fIcmds\fP: (Linux only)
111.br
112.TP 12
113.B SHM_LOCK
114prevents swapping of a shared memory segment. The user must fault in
115any pages that are required to be present after locking is enabled.
116.TP
117.B SHM_UNLOCK
118allows the shared memory segment to be swapped out.
119.PP
120The
121.BR IPC_INFO ,
122.BR SHM_STAT
123and
124.B SHM_INFO
125control calls are used by the
126.BR ipcs (8)
127program to provide information on allocated resources. In the future,
128these may be modified as needed or moved to a proc file system interface.
129.SH "RETURN VALUE"
1300 is returned on success, \-1 on error.
131.SH ERRORS
132On error,
133.B errno
134will be set to one of the following:
135.TP 12
136.B EACCES
137is 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
142The argument
143.I cmd
144has value
145.B IPC_SET
146or
147.B IPC_STAT
148but the address pointed to by
149.I buf
150isn't accessible.
151.TP
152.B EINVAL
153is returned if \fIshmid\fP is not a valid identifier, or \fIcmd\fP
154is not a valid command.
155.TP
156.B EIDRM
157is returned if \fIshmid\fP points to a removed identifier.
158.TP
159.B EPERM
160is returned if \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
161effective user ID of the calling process is not the creator
162(as found in
163.IR shm_perm.cuid ),
164the owner
165(as found in
166.IR shm_perm.uid ),
167or the super-user.
168.TP
169.B EOVERFLOW
170is returned if \fBIPC_STAT\fP is attempted, and the gid or uid value
171is too large to be stored in the structure pointed to by
172.IR buf .
173.SH NOTE
174Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2
175and have become longs under Linux 2.4. To take advantage of this,
176a 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"
180SVr4, SVID. SVr4 documents additional error conditions EINVAL,
181ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
182an EIDRM error condition.
183.SH "SEE ALSO"
184.BR shmget (2),
185.BR shmop (2)
This page took 0.056574 seconds and 4 git commands to generate.