lib/libc/gen/sem_timedwait.3

   1 .\" Copyright (c) 2008, David Xu <davidxu@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" Portions of this text are reprinted and reproduced in electronic form
  26 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
  27 .\" Portable Operating System Interface (POSIX), The Open Group Base
  28 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
  29 .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
  30 .\" event of any discrepancy between this version and the original IEEE and
  31 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
  32 .\" the referee document.  The original Standard can be obtained online at
  33 .\"     http://www.opengroup.org/unix/online.html.
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd May 24, 2017
  38 .Dt SEM_TIMEDWAIT 3
  39 .Os
  40 .Sh NAME
  41 .Nm sem_timedwait ,
  42 .Nm sem_clockwait_np
  43 .Nd "lock a semaphore"
  44 .Sh LIBRARY
  45 .Lb libpthread
  46 .Sh SYNOPSIS
  47 .In semaphore.h
  48 .In time.h
  49 .Ft int
  50 .Fn sem_timedwait "sem_t *sem" "const struct timespec *abs_timeout"
  51 .Ft int
  52 .Fn sem_clockwait_np "sem_t * restrict sem" "clockid_t clock_id" "int flags" "const struct timespec * rqtp" "struct timespec * rmtp"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn sem_timedwait
  56 function locks the semaphore referenced by
  57 .Fa sem ,
  58 as in the
  59 .Xr sem_wait 3
  60 function.
  61 However, if the semaphore cannot be locked without waiting for
  62 another process or thread to unlock the semaphore by performing
  63 a
  64 .Xr sem_post 3
  65 function, this wait will be terminated when the specified timeout expires.
  66 .Pp
  67 The timeout will expire when the absolute time specified by
  68 .Fa abs_timeout
  69 passes, as measured by the clock on which timeouts are based (that is,
  70 when the value of that clock equals or exceeds
  71 .Fa abs_timeout ) ,
  72 or if the
  73 absolute time specified by
  74 .Fa abs_timeout
  75 has already been passed at the time of the call.
  76 .Pp
  77 Note that the timeout is based on the
  78 .Dv CLOCK_REALTIME
  79 clock.
  80 .Pp
  81 The validity of the
  82 .Fa abs_timeout
  83 is not checked if the semaphore can be locked immediately.
  84 .Pp
  85 The
  86 .Fn sem_clockwait_np
  87 function is a more flexible variant of
  88 .Fn sem_timedwait .
  89 The
  90 .Fa clock_id
  91 parameter specifies the reference clock.
  92 If the
  93 .Fa flags
  94 parameter contains
  95 .Dv TIMER_ABSTIME ,
  96 then the requested timeout
  97 .Pq Fa rqtp
  98 is an absolute timeout; otherwise,
  99 the timeout is relative.
 100 If this function fails with
 101 .Er EINTR
 102 and the timeout is relative,
 103 a non-NULL
 104 .Fa rmtp
 105 will be updated to contain the amount of time remaining in the interval
 106 .Po
 107 the requested time minus the time actually slept
 108 .Pc .
 109 An absolute timeout has no effect on
 110 .Fa rmtp .
 111 A single structure can be used for both
 112 .Fa rqtp
 113 and
 114 .Fa rmtp .
 115 .Sh RETURN VALUES
 116 These
 117 functions return zero if the calling process successfully performed the
 118 semaphore lock operation on the semaphore designated by
 119 .Fa sem .
 120 If the call was unsuccessful, the state of the semaphore is unchanged,
 121 and the function returns a value of \-1 and sets the global variable
 122 .Va errno
 123 to indicate the error.
 124 .Sh ERRORS
 125 These functions will fail if:
 126 .Bl -tag -width Er
 127 .It Bq Er EINVAL
 128 The
 129 .Fa sem
 130 argument does not refer to a valid semaphore, or the process or thread would
 131 have blocked, and the
 132 .Fa abs_timeout
 133 parameter specified a nanoseconds field value less than zero or greater than
 134 or equal to 1000 million.
 135 .It Bq Er ETIMEDOUT
 136 The semaphore could not be locked before the specified timeout expired.
 137 .It Bq Er EINTR
 138 A signal interrupted this function.
 139 .El
 140 .Sh SEE ALSO
 141 .Xr sem_post 3 ,
 142 .Xr sem_trywait 3 ,
 143 .Xr sem_wait 3
 144 .Sh STANDARDS
 145 The
 146 .Fn sem_timedwait
 147 function conforms to
 148 .St -p1003.1-2004 .
 149 The
 150 .Fn sem_clockwait_np
 151 function is not specified by any standard;
 152 it exists only on
 153 .Fx
 154 at the time of this writing.
 155 .Sh HISTORY
 156 The
 157 .Fn sem_timedwait
 158 function first appeared in
 159 .Fx 5.0 .
 160 The
 161 .Fn sem_clockwait_np
 162 function first appeared in
 163 .Fx 11.1 .