sys.subproj/sem_open.2

   1 .\"     $Darwin$
   2 .\"
   3 .\" Wilfredo Sanchez, wsanchez@apple.com
   4 .\" Copyright (c) 2000 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 June 8, 2000
  25 .Dt SEM_OPEN 2
  26 .Os Darwin
  27 .Sh NAME
  28 .Nm sem_open
  29 .Nd initialize and open a named semaphore
  30 .Sh SYNOPSIS
  31 .Fd #include <semaphore.h>
  32 .Ft sem_t *
  33 .Fn sem_open "const char *name" "int flags"
  34 .Ft sem_t *
  35 .Fn sem_open "const char *name" "int flags" "mode_t mode" "unsigned int value"
  36 .Sh DESCRIPTION
  37 The named semaphore named
  38 .Fa name
  39 is initialized and opened as specified by the argument
  40 .Fa flags
  41 and a semaphore descriptor is returned to the calling process.
  42 .Pp
  43 The flags specified are formed by
  44 .Em or Ns 'ing
  45 the following values:
  46 .Pp
  47 .Bd -literal -offset indent -compact
  48 O_CREAT         create the semaphore if it does not exist
  49 O_EXCL          error if create and semaphore exists
  50 .Ed
  51 .Pp
  52 If
  53 .Dv O_CREATE
  54 if specified,
  55 .Fn sem_open
  56 requires an additional two arguments.
  57 .Fa mode
  58 specifies the permissions for the semaphore as described in
  59 .Xr chmod 2
  60 and modified by the process' umask value (see
  61 .Xr umask 2 ) .
  62 The semaphore is created with an initial
  63 .Fa value ,
  64 which must be less than or equal to
  65 .Dv SEM_VALUE_MAX .
  66 .Pp
  67 If
  68 .Dv O_EXCL
  69 is specified and the semaphore exists,
  70 .Fn sem_open
  71 fails.  The check for the existence of the semaphore and the creation
  72 of the semaphore are atomic with respect to all processes calling
  73 .Fn sem_open
  74 with
  75 .Dv O_CREAT
  76 and
  77 .Dv O_EXCL
  78 set.
  79 .Pp
  80 When a new semaphore is created, it is given the user ID and group ID
  81 which coorespond to the effective user and group IDs of the calling
  82 process. There is no visible entry in the file system for the created
  83 object in this implementation.
  84 .Pp
  85 The returned semaphore descriptor is available to the calling process
  86 until it is closed with
  87 .Fn sem_close ,
  88 or until the caller exits or execs.
  89 .Pp
  90 If a process makes repeated calls to
  91 .Fn sem_open ,
  92 with the same
  93 .Fa name
  94 argument, the same descriptor is returned for each successful call,
  95 unless
  96 .Fn sem_unlink
  97 has been called on the semaphore in the interim.
  98 .Pp
  99 If
 100 .Fn sem_open
 101 fails for any reason, it will return a value of
 102 .Dv SEM_FAILED
 103 and sets
 104 .Va errno .
 105 On success, it returns a semaphore descriptor.
 106 .Sh ERRORS
 107 The named semaphore is opened unless:
 108 .Bl -tag -width Er
 109 .It Bq Er EACCES
 110 The required permissions (for reading and/or writing)
 111 are denied for the given flags; or
 112 .Dv O_CREAT
 113 is specified, the object does not exist, and permission to
 114 create the semaphore is denied.
 115 .It Bq Er EEXIST
 116 .Dv O_CREAT
 117 and
 118 .Dv O_EXCL
 119 were specified and the semaphore exists.
 120 .It Bq Er EINTR
 121 The
 122 .Fn sem_open
 123 operation was interrupted by a signal.
 124 .It Bq Er EINVAL
 125 The
 126 .Fn shm_open
 127 operation is not supported; or
 128 .Dv O_CREAT
 129 is specified and
 130 .Fa value
 131 exceeds
 132 .Dv SEM_VALUE_MAX .
 133 .It Bq Er EMFILE
 134 The process has already reached its limit for semaphores or file
 135 descriptors in use.
 136 .It Bq Er ENAMETOOLONG
 137 .Fa name
 138 exceeded
 139 .Dv SEM_NAME_LEN
 140 characters.
 141 .It Bq Er ENFILE
 142 Too many semaphores or file descriptors are open on the system.
 143 .It Bq Er ENOENT
 144 .Dv O_CREAT
 145 is not set and the named semaphore does not exist.
 146 .It Bq Er ENOSPC
 147 .Dv O_CREAT
 148 is specified, the file does not exist, and there is insufficient
 149 space available to create the semaphore.
 150 .El
 151 .Sh SEE ALSO
 152 .Xr semctl 2 ,
 153 .Xr semget 2 ,
 154 .Xr semop 2 ,
 155 .Xr sem_close 2 ,
 156 .Xr sem_post 2 ,
 157 .Xr sem_trywait 2 ,
 158 .Xr sem_unlink 2 ,
 159 .Xr sem_wait 2 ,
 160 .Xr umask 2
 161 .Sh HISTORY
 162 .Fn sem_open
 163 is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).