sys.subproj/shm_open.2

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