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)