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