usr/src/man/man3c/shm_open.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH SHM_OPEN 3C "Feb 5, 2008"
  48 .SH NAME
  49 shm_open \- open a shared memory object
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <sys/mman.h>
  54
  55 \fBint\fR \fBshm_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, \fBmode_t\fR \fImode\fR);
  56 .fi
  57
  58 .SH DESCRIPTION
  59 .sp
  60 .LP
  61 The \fBshm_open()\fR function establishes a connection between a shared memory
  62 object and a file descriptor. It creates an open file description that refers
  63 to the shared memory object and a file descriptor that refers to that open file
  64 description. The file descriptor is used by other functions to refer to that
  65 shared memory object. The \fIname\fR argument points to a string naming a
  66 shared memory object. It is unspecified whether the name appears in the file
  67 system and is visible to other functions that take pathnames as arguments. The
  68 \fIname\fR argument conforms to the construction rules for a pathname. The
  69 first character of  \fIname\fR must be a slash  (/) character and the remaining
  70 characters of  \fIname\fR cannot include any slash characters.  For maximum
  71 portability,  \fIname\fR should include no more than 14 characters, but this
  72 limit is not enforced.
  73 .sp
  74 .LP
  75 If successful, \fBshm_open()\fR returns a file descriptor for the shared memory
  76 object that is the lowest numbered file descriptor not currently open for that
  77 process. The open file description is new, and therefore the file descriptor
  78 does not share it with any other processes. It is unspecified whether the file
  79 offset is set. The \fBFD_CLOEXEC\fR file descriptor flag associated with the
  80 new file descriptor is set.
  81 .sp
  82 .LP
  83 The file status flags and file access modes of the open file description are
  84 according to the value of \fIoflag\fR. The \fIoflag\fR argument is the bitwise
  85 inclusive OR of the following flags defined in the header <\fBfcntl.h\fR>.
  86 Applications specify exactly one of the first two values (access modes) below
  87 in the value of \fIoflag\fR:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBO_RDONLY\fR \fR
  92 .ad
  93 .RS 13n
  94 Open for read access only.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBO_RDWR\fR \fR
 101 .ad
 102 .RS 13n
 103 Open for read or write access.
 104 .RE
 105
 106 .sp
 107 .LP
 108 Any combination of the remaining flags may be specified in the value of
 109 \fIoflag\fR:
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBO_CREAT\fR \fR
 114 .ad
 115 .RS 12n
 116 If the shared memory object exists, this flag has no effect, except as noted
 117 under \fBO_EXCL\fR below. Otherwise the shared memory object is created; the
 118 user \fBID\fR of the shared memory object will be set to the effective user
 119 \fBID\fR of the process; the group \fBID\fR of the shared memory object will be
 120 set to a system default group \fBID\fR or to the effective group \fBID\fR of
 121 the process. The permission bits of the shared memory object will be set to the
 122 value of the \fImode\fR argument except those set in the file mode creation
 123 mask of the process. When bits in \fImode\fR other than the file permission
 124 bits are set, the effect is unspecified. The \fImode\fR argument does not
 125 affect whether the shared memory object is opened for reading, for writing, or
 126 for both. The shared memory object has a size of zero.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBO_EXCL\fR \fR
 133 .ad
 134 .RS 12n
 135 If \fBO_EXCL\fR and \fBO_CREAT\fR are set, \fBshm_open()\fR fails if the shared
 136 memory object exists. The check for the existence of the shared memory object
 137 and the creation of the object if it does not exist is atomic with respect to
 138 other processes executing \fBshm_open()\fR naming the same shared memory object
 139 with \fBO_EXCL\fR and \fBO_CREAT\fR set. If \fBO_EXCL\fR is set and
 140 \fBO_CREAT\fR is not set, the result is undefined.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBO_TRUNC\fR \fR
 147 .ad
 148 .RS 12n
 149 If the shared memory object exists, and it is successfully opened \fBO_RDWR\fR,
 150 the object will be truncated to zero length and the mode and owner will be
 151 unchanged by this function call. The result of using \fBO_TRUNC\fR with
 152 \fBO_RDONLY\fR is undefined.
 153 .RE
 154
 155 .sp
 156 .LP
 157 When a shared memory object is created, the state of the shared memory object,
 158 including all data associated with the shared memory object, persists until the
 159 shared memory object is unlinked and all other references are gone. It is
 160 unspecified whether the name and shared memory object state remain valid after
 161 a system reboot.
 162 .SH RETURN VALUES
 163 .sp
 164 .LP
 165 Upon successful completion, the \fBshm_open()\fR function returns a
 166 non-negative integer representing the lowest numbered unused file descriptor.
 167 Otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error
 168 condition.
 169 .SH ERRORS
 170 .sp
 171 .LP
 172 The \fBshm_open()\fR function will fail if:
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBEACCES\fR \fR
 177 .ad
 178 .RS 17n
 179 The shared memory object exists and the permissions specified by \fIoflag\fR
 180 are denied, or the shared memory object does not exist and permission to create
 181 the shared memory object is denied, or \fBO_TRUNC\fR is specified and write
 182 permission is denied.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBEEXIST\fR \fR
 189 .ad
 190 .RS 17n
 191 \fBO_CREAT\fR and \fBO_EXCL\fR are set and the named shared memory object
 192 already exists.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBEINTR\fR \fR
 199 .ad
 200 .RS 17n
 201 The \fBshm_open()\fR operation was interrupted by a signal.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBEINVAL\fR \fR
 208 .ad
 209 .RS 17n
 210 The \fBshm_open()\fR operation is not supported for the given name.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEMFILE\fR \fR
 217 .ad
 218 .RS 17n
 219 Too many file descriptors are currently in use by this process.
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBENAMETOOLONG\fR \fR
 226 .ad
 227 .RS 17n
 228 The length of the \fIname\fR string exceeds \fBPATH_MAX\fR, or a pathname
 229 component is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in
 230 effect.
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBENFILE\fR \fR
 237 .ad
 238 .RS 17n
 239 Too many shared memory objects are currently open in the system.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBENOENT\fR \fR
 246 .ad
 247 .RS 17n
 248 \fBO_CREAT\fR is not set and the named shared memory object does not exist.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBENOSPC\fR \fR
 255 .ad
 256 .RS 17n
 257 There is insufficient space for the creation of the new shared memory object.
 258 .RE
 259
 260 .sp
 261 .ne 2
 262 .na
 263 \fB\fBENOSYS\fR \fR
 264 .ad
 265 .RS 17n
 266 The \fBshm_open()\fR function is not supported by the system.
 267 .RE
 268
 269 .SH ATTRIBUTES
 270 .sp
 271 .LP
 272 See \fBattributes\fR(5) for descriptions of the following attributes:
 273 .sp
 274
 275 .sp
 276 .TS
 277 box;
 278 c | c
 279 l | l .
 280 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 281 _
 282 Interface Stability     Committed
 283 _
 284 MT-Level        MT-Safe
 285 _
 286 Standard        See \fBstandards\fR(5).
 287 .TE
 288
 289 .SH SEE ALSO
 290 .sp
 291 .LP
 292 \fBclose\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBmmap\fR(2),
 293 \fBumask\fR(2), \fBshm_unlink\fR(3C), \fBsysconf\fR(3C), \fBfcntl.h\fR(3HEAD),
 294 \fBattributes\fR(5), \fBstandards\fR(5)
 295 .SH NOTES
 296 .sp
 297 .LP
 298 Solaris 2.6 was the first release to support the Asynchronous Input and Output
 299 option. Prior to this release, this function always returned \fB\(mi1\fR and
 300 set \fBerrno\fR to \fBENOSYS\fR.