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 .Ft int
  32 .Fo shm_open
  33 .Fa "const char *name"
  34 .Fa "int oflag"
  35 .Fa "..."
  36 .Fc
  37 .Pp
  38 The parameter "mode_t mode" is optional.
  39 .Sh DESCRIPTION
  40 The shared memory object referenced by
  41 .Fa name
  42 is opened for reading and/or writing as specified by the argument
  43 .Fa oflag
  44 and the file descriptor returned to the calling process.
  45 The returned file descriptor will be the lowest non-open file
  46 descriptor for the calling process, and is not shared with any
  47 other processes, as it is a new file descriptor. The new file
  48 descriptor will have the
  49 .Dv FD_CLOEXEC
  50 flag set.
  51 Repeated calls
  52 to
  53 .Nm shm_open
  54 with the same string value for
  55 .Fn name
  56 will return a file descriptor referring to the same shared memory
  57 object, provided that the object has not been unlinked by a call to
  58 .Fn shm_unlink .
  59 The
  60 .Fa oflag
  61 argument may indicate the file is to be
  62 created if it does not exist (by specifying the
  63 .Dv O_CREAT
  64 flag), in which case the file is created with mode
  65 .Fa mode
  66 as described in
  67 .Xr chmod 2
  68 and modified by the process' umask value (see
  69 .Xr umask 2 ) .
  70 .Pp
  71 The value of
  72 .Fa oflag
  73 is formed by
  74 .Em or Ns 'ing
  75 the following values:
  76 .Pp
  77 .Bd -literal -offset indent -compact
  78 O_RDONLY        open for reading only
  79 O_RDWR          open for reading and writing
  80 O_CREAT         create object if it does not exist
  81 O_EXCL          error if create and object exists
  82 O_TRUNC         truncate size to 0
  83 .Ed
  84 .Pp
  85 Exactly one of
  86 .Dv O_RDONLY
  87 or
  88 .Dv O_RDWR
  89 must be specified.
  90 .Pp
  91 If
  92 .Dv O_TRUNC
  93 is specified and the
  94 file exists, the file is truncated to zero length.
  95 If
  96 .Dv O_EXCL
  97 is set with
  98 .Dv O_CREAT
  99 and the file already
 100 exists,
 101 .Fn shm_open
 102 returns an error.  This may be used to
 103 implement a simple exclusive access locking mechanism.
 104 .Pp
 105 If successful,
 106 .Fn shm_open
 107 returns a non-negative integer, termed a file descriptor.
 108 It returns -1 and sets
 109 .Va errno
 110 on failure.
 111 The file pointer used to mark the current position within the
 112 memory object is set to the beginning of the object.
 113 .Pp
 114 When a new shared memory object is created it is given the
 115 owner and group corresponding to the effective user and
 116 group of the calling process. There is no visible entry in the
 117 file system for the created object in this implementation.
 118 .Pp
 119 When a shared memory object is created, it persists until it
 120 it unlinked and all other references are gone. Objects do
 121 not persist across a system reboot.
 122 .Pp
 123 The system imposes a limit on the number of file descriptors
 124 open simultaneously by one process.
 125 .Xr Getdtablesize 2
 126 returns the current system limit.
 127 .Sh ERRORS
 128 The named object is opened unless:
 129 .Bl -tag -width Er
 130 .It Bq Er EACCES
 131 The required permissions (for reading and/or writing)
 132 are denied for the given flags.
 133 .It Bq Er EACCES
 134 .Dv O_CREAT
 135 is specified, the object does not exist, and permission to
 136 create the object is denied.
 137 .It Bq Er EEXIST
 138 .Dv O_CREAT
 139 and
 140 .Dv O_EXCL
 141 were specified and the object exists.
 142 .It Bq Er EINTR
 143 The
 144 .Fn shm_open
 145 operation was interrupted by a signal.
 146 .It Bq Er EINVAL
 147 The
 148 .Fn shm_open
 149 operation is not supported.
 150 .It Bq Er EMFILE
 151 The process has already reached its limit for open file descriptors.
 152 .It Bq Er ENAMETOOLONG
 153 .Fa name
 154 exceeded the name size limit.
 155 This is currently
 156 .Dv PSHMNAMLEN
 157 characters (defined in
 158 .In sys/posix_shm.h ) ,
 159 but this may change in the future.
 160 .It Bq Er ENFILE
 161 The system file table is full.
 162 .It Bq Er ENOENT
 163 .Dv O_CREAT
 164 is not set and the named object does not exist.
 165 .It Bq Er ENOSPC
 166 .Dv O_CREAT
 167 is specified, the file does not exist, and there is insufficient
 168 space available to create the object.
 169 .El
 170 .Sh SEE ALSO
 171 .Xr chmod 2 ,
 172 .Xr close 2 ,
 173 .Xr getdtablesize 2 ,
 174 .Xr mmap 2 ,
 175 .Xr shm_unlink 2 ,
 176 .Xr umask 2
 177 .Sh HISTORY
 178 .Fn shm_open
 179 is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).