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

   1 '\" te
   2 .\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   3 .\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" 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
   5 .\" 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 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.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" 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.
   9 .\" 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.
  10 .\" 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]
  11 .TH SEM_TIMEDWAIT 3C "Feb 5, 2008"
  12 .SH NAME
  13 sem_timedwait, sem_reltimedwait_np \- lock a semaphore
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 #include <semaphore.h>
  18 #include <time.h>
  19
  20 \fBint\fR \fBsem_timedwait\fR(\fBsem_t *restrict\fR \fIsem\fR,
  21      \fBconst struct timespec *restrict\fR \fIabs_timeout\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBsem_reltimedwait_np\fR(\fBsem_t *restrict\fR \fIsem\fR,
  27      \fBconst struct timespec *restrict\fR \fIrel_timeout\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBsem_timedwait()\fR function locks the semaphore referenced by \fIsem\fR
  34 as in the \fBsem_wait\fR(3C) function. However, if the semaphore cannot be
  35 locked without waiting for another process or thread to unlock the semaphore by
  36 performing a \fBsem_post\fR(3C) function, this wait is terminated when the
  37 specified timeout expires.
  38 .sp
  39 .LP
  40 The \fBsem_reltimedwait_np()\fR function is identical to the
  41 \fBsem_timedwait()\fR function, except that the timeout is specified as a
  42 relative time interval.
  43 .sp
  44 .LP
  45 For \fBsem_timedwait()\fR, the timeout expires when the absolute time specified
  46 by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock
  47 (that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or
  48 if the absolute time specified by \fIabs_timeout\fR has already been passed at
  49 the time of the call.
  50 .sp
  51 .LP
  52 For \fBsem_reltimedwait_np()\fR, the timeout expires when the time interval
  53 specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR
  54 clock, or if the time interval specified by \fIrel_timeout\fR is negative at
  55 the time of the call.
  56 .sp
  57 .LP
  58 The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR
  59 clock. The \fBtimespec\fR data type is defined as a structure in the
  60 <\fBtime.h\fR> header.
  61 .sp
  62 .LP
  63 Under no circumstance does the function fail with a timeout if the semaphore
  64 can be locked immediately. The validity of the \fIabs_timeout\fR need not be
  65 checked if the semaphore can be locked immediately.
  66 .SH RETURN VALUES
  67 .sp
  68 .LP
  69 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions return 0 if
  70 the calling process successfully performed the semaphore lock operation on the
  71 semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of
  72 the semaphore is be unchanged and the function returns -1 and sets \fBerrno\fR
  73 to indicate the error.
  74 .SH ERRORS
  75 .sp
  76 .LP
  77 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions will fail
  78 if:
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBEINVAL\fR\fR
  83 .ad
  84 .RS 13n
  85 The \fIsem\fR argument does not refer to a valid semaphore.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBEINVAL\fR\fR
  92 .ad
  93 .RS 13n
  94 The process or thread would have blocked, and the timeout parameter specified a
  95 nanoseconds field value less than zero or greater than or equal to 1,000
  96 million.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBETIMEDOUT\fR\fR
 103 .ad
 104 .RS 13n
 105 The semaphore could not be locked before the specified timeout expired.
 106 .RE
 107
 108 .sp
 109 .LP
 110 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions may fail
 111 if:
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBEDEADLK\fR\fR
 116 .ad
 117 .RS 11n
 118 A deadlock condition was detected.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEINTR\fR\fR
 125 .ad
 126 .RS 11n
 127 A signal interrupted this function.
 128 .RE
 129
 130 .SH ATTRIBUTES
 131 .sp
 132 .LP
 133 See \fBattributes\fR(5) for descriptions of the following attributes:
 134 .sp
 135
 136 .sp
 137 .TS
 138 box;
 139 c | c
 140 l | l .
 141 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 142 _
 143 Interface Stability     Commmitted
 144 _
 145 MT-Level        MT-Safe
 146 _
 147 Standard        See below.
 148 .TE
 149
 150 .sp
 151 .LP
 152 For \fBsem_timedwait()\fR, see \fBstandards\fR(5).
 153 .SH SEE ALSO
 154 .sp
 155 .LP
 156 \fBsemctl\fR(2), \fBsemget\fR(2), \fBsemop\fR(2), \fBtime\fR(2),
 157 \fBsem_post\fR(3C), \fBsem_trywait\fR(3C)\fBsem_wait\fR(3C),
 158 \fBattributes\fR(5), \fBstandards\fR(5)