share/man/man3c/sem_open.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH SEM_OPEN 3C "Jul 9, 2009"
  48 .SH NAME
  49 sem_open \- initialize/open a named semaphore
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <semaphore.h>
  54
  55 \fBsem_t *\fR\fBsem_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR,
  56      \fB/* unsigned long\fR \fImode\fR, \fBunsigned int\fR \fIvalue\fR */ ...);
  57 .fi
  58
  59 .SH DESCRIPTION
  60 .sp
  61 .LP
  62 The \fBsem_open()\fR function establishes a connection between a named
  63 semaphore and a process (or LWP or thread). Following a call to
  64 \fBsem_open()\fR with semaphore name \fIname\fR, the process may reference the
  65 semaphore associated with \fIname\fR using the address returned from the call.
  66 This semaphore may be used in subsequent calls to \fBsem_wait\fR(3C),
  67 \fBsem_trywait\fR(3C), \fBsem_post\fR(3C), and \fBsem_close\fR(3C). The
  68 semaphore remains usable by this process until the semaphore is closed by a
  69 successful call to \fBsem_close\fR(3C), \fB_Exit\fR(2), or one of the
  70 \fBexec\fR functions.
  71 .sp
  72 .LP
  73 The \fIoflag\fR argument controls whether the semaphore is created or merely
  74 accessed by the call to \fBsem_open()\fR. The following flag bits may be set in
  75 \fIoflag\fR:
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBO_CREAT\fR\fR
  80 .ad
  81 .RS 11n
  82 This flag is used to create a semaphore if it does not already exist. If
  83 \fBO_CREAT\fR is set and the semaphore already exists, then \fBO_CREAT\fR has
  84 no effect, except as noted under \fB\fR\fBO_EXCL.\fR Otherwise,
  85 \fBsem_open()\fR creates a named semaphore. The \fBO_CREAT\fR flag requires a
  86 third and a fourth argument: \fImode\fR, which is of type \fBmode_t\fR, and
  87 \fIvalue\fR, which is of type \fBunsigned int\fR. The semaphore is created with
  88 an initial value of \fIvalue\fR. Valid initial values for semaphores are less
  89 than or equal to \fBSEM_VALUE_MAX.\fR
  90 .sp
  91 The user \fBID\fR of the semaphore is set to the effective user \fBID\fR of the
  92 process; the group \fBID\fR of the semaphore is set to a system default group
  93 \fBID\fR or to the effective group \fBID\fR of the process. The permission bits
  94 of the semaphore are set to the value of the \fImode\fR argument except those
  95 set in the file mode creation mask of the process (see \fBumask\fR(2)). When
  96 bits in \fImode\fR other than the file permission bits are specified, the
  97 effect is unspecified.
  98 .sp
  99 After the semaphore named \fIname\fR has been created by \fBsem_open()\fR with
 100 the \fBO_CREAT\fR flag, other processes can connect to the semaphore by calling
 101 \fBsem_open()\fR with the same value of \fIname\fR.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBO_EXCL\fR\fR
 108 .ad
 109 .RS 11n
 110 If \fBO_EXCL\fR and \fBO_CREAT\fR are set, \fBsem_open()\fR fails if the
 111 semaphore \fIname\fR exists. The check for the existence of the semaphore and
 112 the creation of the semaphore if it does not exist are atomic with respect to
 113 other processes executing \fBsem_open()\fR with \fBO_EXCL\fR and \fBO_CREAT\fR
 114 set. If \fBO_EXCL\fR is set and \fBO_CREAT\fR is not set, the effect is
 115 undefined.
 116 .RE
 117
 118 .sp
 119 .LP
 120 If flags other than \fBO_CREAT\fR and \fBO_EXCL\fR are specified in the
 121 \fIoflag\fR parameter, the effect is unspecified.
 122 .sp
 123 .LP
 124 The \fIname\fR argument points to a string naming a semaphore object. It is
 125 unspecified whether the name appears in the file system and is visible to
 126 functions that take pathnames as arguments. The \fIname\fR argument conforms to
 127 the construction rules for a pathname. The first character of  \fIname\fR must
 128 be a slash  (/) character and the remaining characters of  \fIname\fR cannot
 129 include any slash characters.  For maximum portability,  \fIname\fR should
 130 include no more than 14 characters, but this limit is not enforced.
 131 .sp
 132 .LP
 133 If a process makes multiple successful calls to \fBsem_open()\fR with the same
 134 value for \fIname\fR, the same semaphore address is returned for each such
 135 successful call, provided that there have been no calls to \fBsem_unlink\fR(3C)
 136 for this semaphore.
 137 .sp
 138 .LP
 139 References to copies of the semaphore produce undefined results.
 140 .sp
 141 .LP
 142 The \fBsem_init\fR(3C) function is used with unnamed semaphores.
 143 .SH RETURN VALUES
 144 .sp
 145 .LP
 146 Upon successful completion, the function returns the address of the semaphore.
 147 Otherwise, it will return a value of \fBSEM_FAILED\fR and set \fBerrno\fR to
 148 indicate the error. The symbol \fBSEM_FAILED\fR is defined in the header
 149 \fB<semaphore.h>\fR\&. No successful return from \fBsem_open()\fR will return
 150 the value \fB\fR\fBSEM_FAILED.\fR
 151 .SH ERRORS
 152 .sp
 153 .LP
 154 If any of the following conditions occur, the \fBsem_open()\fR function will
 155 return \fBSEM_FAILED\fR and set \fBerrno\fR to the corresponding value:
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBEACCES\fR\fR
 160 .ad
 161 .RS 16n
 162 The named semaphore exists and the \fBO_RDWR\fR permissions are denied, or the
 163 named semaphore does not exist and permission to create the named semaphore is
 164 denied.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBEEXIST\fR\fR
 171 .ad
 172 .RS 16n
 173 \fBO_CREAT\fR and  \fBO_EXCL\fR are set and the named semaphore already exists.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBEINTR\fR\fR
 180 .ad
 181 .RS 16n
 182 The \fBsem_open()\fR function was interrupted by a signal.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBEINVAL\fR\fR
 189 .ad
 190 .RS 16n
 191 The \fBsem_open()\fR operation is not supported for the given name, or
 192 \fBO_CREAT\fR was set in \fIoflag\fR and \fIvalue\fR is greater than
 193 \fBSEM_VALUE_MAX\fR.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBEMFILE\fR\fR
 200 .ad
 201 .RS 16n
 202 The number of open semaphore descriptors in this process exceeds
 203 \fBSEM_NSEMS_MAX\fR, or the number of open file descriptors in this process
 204 exceeds  \fBOPEN_MAX\fR.
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBENAMETOOLONG\fR\fR
 211 .ad
 212 .RS 16n
 213 The length of \fIname\fR string exceeds \fIPATH_MAX\fR, or a pathname component
 214 is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBENFILE\fR\fR
 221 .ad
 222 .RS 16n
 223 Too many semaphores are currently open in the system.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBENOENT\fR\fR
 230 .ad
 231 .RS 16n
 232 \fBO_CREAT\fR is not set and the named semaphore does not exist.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBENOSPC\fR\fR
 239 .ad
 240 .RS 16n
 241 There is insufficient space for the creation of the new named semaphore.
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBENOSYS\fR\fR
 248 .ad
 249 .RS 16n
 250 The \fBsem_open()\fR function is not supported by the system.
 251 .RE
 252
 253 .SH ATTRIBUTES
 254 .sp
 255 .LP
 256 See \fBattributes\fR(5) for descriptions of the following attributes:
 257 .sp
 258
 259 .sp
 260 .TS
 261 box;
 262 c | c
 263 l | l .
 264 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 265 _
 266 Interface Stability     Committed
 267 _
 268 MT-Level        MT-Safe
 269 _
 270 Standard        See \fBstandards\fR(5).
 271 .TE
 272
 273 .SH SEE ALSO
 274 .sp
 275 .LP
 276 \fBexec\fR(2), \fBexit\fR(2), \fBumask\fR(2), \fBsem_close\fR(3C),
 277 \fBsem_init\fR(3C), \fBsem_post\fR(3C), \fBsem_unlink\fR(3C),
 278 \fBsem_wait\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)