sys/sem_open.2

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