]> git.pld-linux.org Git - packages/man-pages.git/blob - shmop.2
- separated POSIX man pages, rel. 1
[packages/man-pages.git] / shmop.2
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
31 shmop \- 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
46 The function
47 .B shmat
48 attaches the shared memory segment identified by
49 .B shmid
50 to the address space of the calling process.
51 The attaching address is specified by
52 .I shmaddr
53 with one of the following criteria:
54 .LP
55 If
56 .I shmaddr
57 is
58 .BR NULL ,
59 the system chooses a suitable (unused) address at which to attach
60 the segment.
61 .LP
62 If
63 .I shmaddr
64 isn't
65 .B NULL
66 and
67 .B SHM_RND
68 is asserted in
69 .IR shmflg ,
70 the attach occurs at the address equal to
71 .I shmaddr
72 rounded down to the nearest multiple of
73 .BR SHMLBA .
74 Otherwise
75 .I shmaddr
76 must be a page aligned address at which the attach occurs.
77 .PP
78 If
79 .B SHM_RDONLY
80 is asserted in
81 .IR shmflg ,
82 the segment is attached for reading and the process must have
83 read permission for the segment.
84 Otherwise the segment is attached for read and write
85 and the process must have read and write permission for the segment.
86 There is no notion of write-only shared memory segment.
87 .PP
88 The
89 .B brk
90 value of the calling process is not altered by the attach.
91 The segment will automatically be detached at process exit.
92 The same segment may be attached as a read and as a read-write
93 one, and more than once, in the process's address space.
94 .PP
95 On a successful
96 .B shmat
97 call the system updates the members of the
98 .B shmid_ds
99 structure associated to the shared memory segment as follows:
100 .IP
101 .B shm_atime
102 is set to the current time.
103 .IP
104 .B shm_lpid
105 is set to the process-ID of the calling process.
106 .IP
107 .B shm_nattch
108 is incremented by one.
109 .PP
110 Note that the attach succeeds also if the shared memory segment is
111 marked to be deleted.
112 .PP
113 The function
114 .B shmdt
115 detaches the shared memory segment located at the address specified by
116 .I shmaddr
117 from the address space of the calling process.
118 The to\-be\-detached segment must be currently
119 attached with
120 .I shmaddr
121 equal to the value returned by the its attaching
122 .B shmat
123 call.
124 .PP
125 On a successful
126 .B shmdt
127 call the system updates the members of the
128 .B shmid_ds
129 structure associated with the shared memory segment as follows:
130 .IP
131 .B shm_dtime
132 is set to the current time.
133 .IP
134 .B shm_lpid
135 is set to the process-ID of the calling process.
136 .IP
137 .B shm_nattch
138 is decremented by one.
139 If it becomes 0 and the segment is marked for deletion,
140 the segment is deleted.
141 .PP
142 The occupied region in the user space of the calling process is
143 unmapped.
144 .SH "SYSTEM CALLS"
145 .TP
146 .B fork()
147 After a
148 .B fork()
149 the child inherits the attached shared memory segments.
150 .TP
151 .B exec()
152 After an
153 .B exec()
154 all attached shared memory segments are detached from the process.
155 .TP
156 .B exit()
157 Upon
158 .B exit()
159 all attached shared memory segments are detached from the process.
160 .SH "RETURN VALUE"
161 On failure both functions return
162 .B \-1
163 with
164 .I errno
165 indicating the error.
166 On success
167 .B shmat
168 returns the address of the attached shared memory segment, and
169 .B shmdt
170 returns
171 .BR 0 .
172 .SH ERRORS
173 When
174 .B shmat
175 fails,
176 .I errno
177 is set to one of the following:
178 .TP 11
179 .B EACCES
180 The calling process has no access permissions for the requested attach
181 type.
182 .TP
183 .B EINVAL
184 Invalid
185 .I shmid
186 value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not
187 specified) or invalid
188 .I shmaddr
189 value, or failing attach at
190 .BR brk .
191 .TP
192 .B ENOMEM
193 Could not allocate memory for the descriptor or for the page tables.
194 .PP
195 The function
196 .B shmdt
197 can fail only if there is no shared memory segment attached at
198 .IR shmaddr ,
199 in such a case at return
200 .I errno
201 will 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
207 Using
208 .B shmat
209 with
210 .I shmaddr
211 equal to
212 .B NULL
213 is the preferred, portable way of attaching a shared memory segment.
214 Be aware that the shared memory segment attached in this way
215 may be attached at different addresses in different processes.
216 Therefore, any pointers maintained within the shared memory must be
217 made relative (typically to the starting address of the segment),
218 rather than absolute.
219 .LP
220 The following system parameter affects a
221 .B shmat
222 system call:
223 .TP 11
224 .B SHMLBA
225 Segment low boundary address multiple.
226 Must be page aligned.
227 For the current implementation the
228 .B SHMBLA
229 value is
230 .BR PAGE_SIZE .
231 .PP
232 The implementation has no intrinsic limit to the per\-process maximum
233 number of shared memory segments
234 .RB ( SHMSEG )
235 .SH "CONFORMING TO"
236 SVr4, SVID.  SVr4 documents an additional error condition EMFILE.
237 In SVID-v4 the type of the \fIshmaddr\fP argument was changed from
238 .B "char *"
239 into
240 .BR "const void *" ,
241 and the returned type of \fIshmat\fP() from
242 .B "char *"
243 into
244 .BR "void *" .
245 (Linux libc4 and libc5 have the
246 .B "char *"
247 prototypes; 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.099936 seconds and 3 git commands to generate.