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

   1 '\" te
   2 .\" Copyright (c) 2008, 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
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" 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 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 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.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" 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.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH SEM_WAIT 3C "Feb 5, 2008"
  13 .SH NAME
  14 sem_wait, sem_trywait \- acquire or wait for a semaphore
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <semaphore.h>
  19
  20 \fBint\fR \fBsem_wait\fR(\fBsem_t *\fR\fIsem\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBsem_trywait\fR(\fBsem_t *\fR\fIsem\fR);
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 The \fBsem_wait()\fR function locks the semaphore referenced by \fIsem\fR by
  32 performing a semaphore lock operation on that semaphore. If the semaphore value
  33 is currently zero, then the calling thread  will not return from the call to
  34 \fBsem_wait()\fR until it either locks the semaphore or the call is interrupted
  35 by a signal. The \fBsem_trywait()\fR function locks the semaphore referenced by
  36 \fIsem\fR only if the semaphore is currently not locked; that is, if the
  37 semaphore value is currently positive. Otherwise, it does not lock the
  38 semaphore.
  39 .sp
  40 .LP
  41 Upon successful return, the state of the semaphore is locked and remains locked
  42 until the \fBsem_post\fR(3C) function is executed and returns successfully.
  43 .sp
  44 .LP
  45 The \fBsem_wait()\fR function is interruptible by the delivery of a signal.
  46 .SH RETURN VALUES
  47 .sp
  48 .LP
  49 The \fBsem_wait()\fR and \fBsem_trywait()\fR functions return  \fB0\fR if the
  50 calling process successfully performed the semaphore lock operation on the
  51 semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of
  52 the semaphore is unchanged, and the function returns \fB\(mi1\fR and sets
  53 \fBerrno\fR to indicate the error.
  54 .SH ERRORS
  55 .sp
  56 .LP
  57 The  \fBsem_wait()\fR and \fBsem_trywait()\fR functions will fail if:
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBEINVAL\fR \fR
  62 .ad
  63 .RS 11n
  64 The \fIsem\fR function does not refer to a valid semaphore.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBENOSYS\fR \fR
  71 .ad
  72 .RS 11n
  73 The \fBsem_wait()\fR and \fBsem_trywait()\fR functions are not supported by the
  74 system.
  75 .RE
  76
  77 .sp
  78 .LP
  79 The  \fBsem_trywait()\fR function will fail if:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBEAGAIN\fR \fR
  84 .ad
  85 .RS 11n
  86 The semaphore was already locked, so it cannot be immediately locked by the
  87 \fBsem_trywait()\fR operation.
  88 .RE
  89
  90 .sp
  91 .LP
  92 The  \fBsem_wait()\fR and \fBsem_trywait()\fR functions may fail if:
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBEDEADLK\fR \fR
  97 .ad
  98 .RS 12n
  99 A deadlock condition was detected; that is, two separate processes are waiting
 100 for an available resource to be released via a semaphore "held" by the other
 101 process.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEINTR\fR \fR
 108 .ad
 109 .RS 12n
 110 A signal interrupted this function.
 111 .RE
 112
 113 .SH USAGE
 114 .sp
 115 .LP
 116 Realtime applications may encounter priority inversion when using semaphores.
 117 The problem occurs when a high priority thread "locks" (that is, waits on) a
 118 semaphore that is about to be "unlocked" (that is, posted) by a low priority
 119 thread, but the low priority thread is preempted by a medium priority thread.
 120 This scenario leads to priority inversion; a high priority thread is blocked by
 121 lower priority threads for an unlimited period of time. During system design,
 122 realtime programmers must take into account the possibility of this kind of
 123 priority inversion. They can deal with it in a number of ways, such as by
 124 having critical sections that are guarded by semaphores execute at a high
 125 priority, so that a thread cannot be preempted while executing in its critical
 126 section.
 127 .SH EXAMPLES
 128 .LP
 129 \fBExample 1 \fRThe customer waiting-line in a bank may be analogous to the
 130 synchronization scheme of a semaphore utilizing \fBsem_wait()\fR and
 131 \fBsem_trywait()\fR:
 132 .sp
 133 .in +2
 134 .nf
 135 #include <errno.h>
 136 #define TELLERS 10
 137 sem_t  bank_line;      /* semaphore */
 138 int banking_hours(), deposit_withdrawal;
 139 void *customer(), do_business(), skip_banking_today();
 140 thread_t tid;
 141 \&...
 142
 143 sem_init(&bank_line,TRUE,TELLERS);  /* 10 tellers
 144                                        available */
 145 while(banking_hours())
 146         thr_create(NULL, NULL, customer,
 147             (void *)deposit_withdrawal, THREAD_NEW_LWP, &tid);
 148 \&...
 149
 150 void *
 151 customer(deposit_withdrawal)
 152 void *deposit_withdrawal;
 153 {
 154     int this_customer, in_a_hurry = 50;
 155     this_customer = rand() % 100;
 156     if (this_customer == in_a_hurry)  {
 157         if (sem_trywait(&bank_line) != 0)
 158         if (errno == EAGAIN) {    /* no teller available */
 159             skip_banking_today(this_customer);
 160             return;
 161         }     /*else go immediately to available teller
 162                & decrement bank_line*/
 163     }
 164     else
 165         sem_wait(&bank_line); /* wait for next teller,
 166              then proceed, and decrement bank_line */
 167     do_business((int *)deposit_withdrawal);
 168     sem_getvalue(&bank_line,&num_tellers);
 169     sem_post(&bank_line); /* increment bank_line;
 170         this_customer's teller is now available */
 171 }
 172 .fi
 173 .in -2
 174
 175 .SH ATTRIBUTES
 176 .sp
 177 .LP
 178 See \fBattributes\fR(5) for descriptions of the following attributes:
 179 .sp
 180
 181 .sp
 182 .TS
 183 box;
 184 c | c
 185 l | l .
 186 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 187 _
 188 Interface Stability     Committed
 189 _
 190 MT-Level        MT-Safe
 191 _
 192 Standard        See \fBstandards\fR(5).
 193 .TE
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBsem_post\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)