sys/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 September 20, 1999
  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 new descriptor is set to remain open across
 124 .Xr execve
 125 system calls; see
 126 .Xr close 2
 127 and
 128 .Xr fcntl 2 .
 129 .Pp
 130 The system imposes a limit on the number of file descriptors
 131 open simultaneously by one process.
 132 .Xr Getdtablesize 2
 133 returns the current system limit.
 134 .Sh ERRORS
 135 The named object is opened unless:
 136 .Bl -tag -width Er
 137 .It Bq Er EACCES
 138 The required permissions (for reading and/or writing)
 139 are denied for the given flags.
 140 .It Bq Er EACCES
 141 .Dv O_CREAT
 142 is specified, the object does not exist, and permission to
 143 create the object is denied.
 144 .It Bq Er EEXIST
 145 .Dv O_CREAT
 146 and
 147 .Dv O_EXCL
 148 were specified and the object exists.
 149 .It Bq Er EINTR
 150 The
 151 .Fn shm_open
 152 operation was interrupted by a signal.
 153 .It Bq Er EINVAL
 154 The
 155 .Fn shm_open
 156 operation is not supported.
 157 .It Bq Er EMFILE
 158 The process has already reached its limit for open file descriptors.
 159 .It Bq Er ENAMETOOLONG
 160 .Fa name
 161 exceeded
 162 .Dv SHM_NAME_MAX
 163 characters.
 164 .It Bq Er ENFILE
 165 The system file table is full.
 166 .It Bq Er ENOENT
 167 .Dv O_CREAT
 168 is not set and the named object does not exist.
 169 .It Bq Er ENOSPC
 170 .Dv O_CREAT
 171 is specified, the file does not exist, and there is insufficient
 172 space available to create the object.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr chmod 2 ,
 176 .Xr close 2 ,
 177 .Xr getdtablesize 2 ,
 178 .Xr mmap 2 ,
 179 .Xr shm_unlink 2 ,
 180 .Xr umask 2
 181 .Sh HISTORY
 182 .Fn shm_open
 183 is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).