bsd/man/man2/shm_open.2

   1 .\"     $Darwin$
   2 .\"
   3 .\" Copyright (c) 1999-2002 Apple Computer, Inc. All rights reserved.
   4 .\"
   5 .\" @APPLE_LICENSE_HEADER_START@
   6 .\"
   7 .\" The contents of this file constitute Original Code as defined in and
   8 .\" are subject to the Apple Public Source License Version 1.1 (the
   9 .\" "License").  You may not use this file except in compliance with the
  10 .\" License.  Please obtain a copy of the License at
  11 .\" http://www.apple.com/publicsource and read it before using this file.
  12 .\"
  13 .\" This Original Code and all software distributed under the License are
  14 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  18 .\" License for the specific language governing rights and limitations
  19 .\" under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .Dd August 29, 2008
  24 .Dt SHM_OPEN 2
  25 .Os Darwin
  26 .Sh NAME
  27 .Nm shm_open
  28 .Nd open a shared memory object
  29 .Sh SYNOPSIS
  30 .Fd #include <sys/mman.h>
  31 .Fd #include <fcntl.h>
  32 .Ft int
  33 .Fo shm_open
  34 .Fa "const char *name"
  35 .Fa "int oflag"
  36 .Fa "..."
  37 .Fc
  38 .Pp
  39 The parameter "mode_t mode" is optional.
  40 .Sh DESCRIPTION
  41 The shared memory object referenced by
  42 .Fa name
  43 is opened for reading and/or writing as specified by the argument
  44 .Fa oflag
  45 and the file descriptor returned to the calling process.
  46 The returned file descriptor will be the lowest non-open file
  47 descriptor for the calling process, and is not shared with any
  48 other processes, as it is a new file descriptor. The new file
  49 descriptor will have the
  50 .Dv FD_CLOEXEC
  51 flag set.
  52 Repeated calls
  53 to
  54 .Nm shm_open
  55 with the same string value for
  56 .Fn name
  57 will return a file descriptor referring to the same shared memory
  58 object, provided that the object has not been unlinked by a call to
  59 .Fn shm_unlink .
  60 The
  61 .Fa oflag
  62 argument may indicate the file is to be
  63 created if it does not exist (by specifying the
  64 .Dv O_CREAT
  65 flag), in which case the file is created with mode
  66 .Fa mode
  67 as described in
  68 .Xr chmod 2
  69 and modified by the process' umask value (see
  70 .Xr umask 2 ) .
  71 .Pp
  72 The value of
  73 .Fa oflag
  74 is formed by
  75 .Em or Ns 'ing
  76 the following values:
  77 .Pp
  78 .Bd -literal -offset indent -compact
  79 O_RDONLY        open for reading only
  80 O_RDWR          open for reading and writing
  81 O_CREAT         create object if it does not exist
  82 O_EXCL          error if create and object exists
  83 O_TRUNC         truncate size to 0
  84 .Ed
  85 .Pp
  86 Exactly one of
  87 .Dv O_RDONLY
  88 or
  89 .Dv O_RDWR
  90 must be specified.
  91 .Pp
  92 If
  93 .Dv O_TRUNC
  94 is specified and the
  95 file exists, the file is truncated to zero length.
  96 If
  97 .Dv O_EXCL
  98 is set with
  99 .Dv O_CREAT
 100 and the file already
 101 exists,
 102 .Fn shm_open
 103 returns an error.  This may be used to
 104 implement a simple exclusive access locking mechanism.
 105 .Pp
 106 If successful,
 107 .Fn shm_open
 108 returns a non-negative integer, termed a file descriptor.
 109 It returns -1 and sets
 110 .Va errno
 111 on failure.
 112 The file pointer used to mark the current position within the
 113 memory object is set to the beginning of the object.
 114 .Pp
 115 When a new shared memory object is created it is given the
 116 owner and group corresponding to the effective user and
 117 group of the calling process. There is no visible entry in the
 118 file system for the created object in this implementation.
 119 .Pp
 120 When a shared memory object is created, it persists until it
 121 it unlinked and all other references are gone. Objects do
 122 not persist across a system reboot.
 123 .Pp
 124 The system imposes a limit on the number of file descriptors
 125 open simultaneously by one process.
 126 .Xr getdtablesize 2
 127 returns the current system limit.
 128 .Sh ERRORS
 129 The named object is opened unless:
 130 .Bl -tag -width Er
 131 .It Bq Er EACCES
 132 The required permissions (for reading and/or writing)
 133 are denied for the given flags.
 134 .It Bq Er EACCES
 135 .Dv O_CREAT
 136 is specified, the object does not exist, and permission to
 137 create the object is denied.
 138 .It Bq Er EEXIST
 139 .Dv O_CREAT
 140 and
 141 .Dv O_EXCL
 142 were specified and the object exists.
 143 .It Bq Er EINTR
 144 The
 145 .Fn shm_open
 146 operation was interrupted by a signal.
 147 .It Bq Er EINVAL
 148 The
 149 .Fn shm_open
 150 operation is not supported.
 151 .It Bq Er EMFILE
 152 The process has already reached its limit for open file descriptors.
 153 .It Bq Er ENAMETOOLONG
 154 .Fa name
 155 exceeded the name size limit.
 156 This is currently
 157 .Dv PSHMNAMLEN
 158 characters (defined in
 159 .In sys/posix_shm.h ) ,
 160 but this may change in the future.
 161 .It Bq Er ENFILE
 162 The system file table is full.
 163 .It Bq Er ENOENT
 164 .Dv O_CREAT
 165 is not set and the named object does not exist.
 166 .It Bq Er ENOSPC
 167 .Dv O_CREAT
 168 is specified, the file does not exist, and there is insufficient
 169 space available to create the object.
 170 .El
 171 .Sh SEE ALSO
 172 .Xr chmod 2 ,
 173 .Xr close 2 ,
 174 .Xr getdtablesize 2 ,
 175 .Xr mmap 2 ,
 176 .Xr shm_unlink 2 ,
 177 .Xr umask 2
 178 .Sh HISTORY
 179 .Fn shm_open
 180 is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).