usr/src/man/man3c/sem_open.3c

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