]> git.pld-linux.org Git - packages/man-pages.git/blame - shmop.2
- separated POSIX man pages, rel. 1
[packages/man-pages.git] / shmop.2
CommitLineData
d748a962 1.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
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 Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu)
24.\" with material from Luigi P. Bai (lpb@softint.com)
25.\" Portions Copyright 1993 Luigi P. Bai
26.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com>
27.\" Modified, 5 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
28.\"
29.TH SHMOP 2 2002-01-05 "Linux 2.5" "Linux Programmer's Manual"
30.SH NAME
31shmop \- shared memory operations
32.SH SYNOPSIS
33.nf
34.B
35#include <sys/types.h>
36.B
37#include <sys/shm.h>
38.fi
39.sp
40.BI "void *shmat(int " shmid ,
41.BI "const void *" shmaddr ,
42.BI "int " shmflg );
43.sp
44.BI "int shmdt(const void *" shmaddr );
45.SH DESCRIPTION
46The function
47.B shmat
48attaches the shared memory segment identified by
49.B shmid
50to the address space of the calling process.
51The attaching address is specified by
52.I shmaddr
53with one of the following criteria:
54.LP
55If
56.I shmaddr
57is
58.BR NULL ,
59the system chooses a suitable (unused) address at which to attach
60the segment.
61.LP
62If
63.I shmaddr
64isn't
65.B NULL
66and
67.B SHM_RND
68is asserted in
69.IR shmflg ,
70the attach occurs at the address equal to
71.I shmaddr
72rounded down to the nearest multiple of
73.BR SHMLBA .
74Otherwise
75.I shmaddr
76must be a page aligned address at which the attach occurs.
77.PP
78If
79.B SHM_RDONLY
80is asserted in
81.IR shmflg ,
82the segment is attached for reading and the process must have
83read permission for the segment.
84Otherwise the segment is attached for read and write
85and the process must have read and write permission for the segment.
86There is no notion of write-only shared memory segment.
87.PP
88The
89.B brk
90value of the calling process is not altered by the attach.
91The segment will automatically be detached at process exit.
92The same segment may be attached as a read and as a read-write
93one, and more than once, in the process's address space.
94.PP
95On a successful
96.B shmat
97call the system updates the members of the
98.B shmid_ds
99structure associated to the shared memory segment as follows:
100.IP
101.B shm_atime
102is set to the current time.
103.IP
104.B shm_lpid
105is set to the process-ID of the calling process.
106.IP
107.B shm_nattch
108is incremented by one.
109.PP
110Note that the attach succeeds also if the shared memory segment is
111marked to be deleted.
112.PP
113The function
114.B shmdt
115detaches the shared memory segment located at the address specified by
116.I shmaddr
117from the address space of the calling process.
118The to\-be\-detached segment must be currently
119attached with
120.I shmaddr
121equal to the value returned by the its attaching
122.B shmat
123call.
124.PP
125On a successful
126.B shmdt
127call the system updates the members of the
128.B shmid_ds
129structure associated with the shared memory segment as follows:
130.IP
131.B shm_dtime
132is set to the current time.
133.IP
134.B shm_lpid
135is set to the process-ID of the calling process.
136.IP
137.B shm_nattch
138is decremented by one.
139If it becomes 0 and the segment is marked for deletion,
140the segment is deleted.
141.PP
142The occupied region in the user space of the calling process is
143unmapped.
144.SH "SYSTEM CALLS"
145.TP
146.B fork()
147After a
148.B fork()
149the child inherits the attached shared memory segments.
150.TP
151.B exec()
152After an
153.B exec()
154all attached shared memory segments are detached from the process.
155.TP
156.B exit()
157Upon
158.B exit()
159all attached shared memory segments are detached from the process.
160.SH "RETURN VALUE"
161On failure both functions return
162.B \-1
163with
164.I errno
165indicating the error.
166On success
167.B shmat
168returns the address of the attached shared memory segment, and
169.B shmdt
170returns
171.BR 0 .
172.SH ERRORS
173When
174.B shmat
175fails,
176.I errno
177is set to one of the following:
178.TP 11
179.B EACCES
180The calling process has no access permissions for the requested attach
181type.
182.TP
183.B EINVAL
184Invalid
185.I shmid
186value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not
187specified) or invalid
188.I shmaddr
189value, or failing attach at
190.BR brk .
191.TP
192.B ENOMEM
193Could not allocate memory for the descriptor or for the page tables.
194.PP
195The function
196.B shmdt
197can fail only if there is no shared memory segment attached at
198.IR shmaddr ,
199in such a case at return
200.I errno
201will be set to
202.BR EINVAL .
203.\" Actually the above is what *should* be done, according to POSIX.
204.\" However as at kernel 2.2.19, and 2.4.15, shmdt() never returns an
205.\" error, even if shmaddr is invalid. (MTK, Jan 2002)
206.SH NOTES
207Using
208.B shmat
209with
210.I shmaddr
211equal to
212.B NULL
213is the preferred, portable way of attaching a shared memory segment.
214Be aware that the shared memory segment attached in this way
215may be attached at different addresses in different processes.
216Therefore, any pointers maintained within the shared memory must be
217made relative (typically to the starting address of the segment),
218rather than absolute.
219.LP
220The following system parameter affects a
221.B shmat
222system call:
223.TP 11
224.B SHMLBA
225Segment low boundary address multiple.
226Must be page aligned.
227For the current implementation the
228.B SHMBLA
229value is
230.BR PAGE_SIZE .
231.PP
232The implementation has no intrinsic limit to the per\-process maximum
233number of shared memory segments
234.RB ( SHMSEG )
235.SH "CONFORMING TO"
236SVr4, SVID. SVr4 documents an additional error condition EMFILE.
237In SVID-v4 the type of the \fIshmaddr\fP argument was changed from
238.B "char *"
239into
240.BR "const void *" ,
241and the returned type of \fIshmat\fP() from
242.B "char *"
243into
244.BR "void *" .
245(Linux libc4 and libc5 have the
246.B "char *"
247prototypes; glibc2 has
248.BR "void *" .)
249.SH "SEE ALSO"
250.BR ipc (5),
251.BR shmctl (2),
252.BR shmget (2)
This page took 0.124924 seconds and 4 git commands to generate.