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 .Dd May 24, 2017
  36 .Dt SEM_TIMEDWAIT 3
  37 .Os
  38 .Sh NAME
  39 .Nm sem_timedwait ,
  40 .Nm sem_clockwait_np
  41 .Nd "lock a semaphore"
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In semaphore.h
  46 .In time.h
  47 .Ft int
  48 .Fn sem_timedwait "sem_t * restrict sem" "const struct timespec * restrict abs_timeout"
  49 .Ft int
  50 .Fn sem_clockwait_np "sem_t * restrict sem" "clockid_t clock_id" "int flags" "const struct timespec * rqtp" "struct timespec * rmtp"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn sem_timedwait
  54 function locks the semaphore referenced by
  55 .Fa sem ,
  56 as in the
  57 .Xr sem_wait 3
  58 function.
  59 However, if the semaphore cannot be locked without waiting for
  60 another process or thread to unlock the semaphore by performing
  61 a
  62 .Xr sem_post 3
  63 function, this wait will be terminated when the specified timeout expires.
  64 .Pp
  65 The timeout will expire when the absolute time specified by
  66 .Fa abs_timeout
  67 passes, as measured by the clock on which timeouts are based (that is,
  68 when the value of that clock equals or exceeds
  69 .Fa abs_timeout ) ,
  70 or if the
  71 absolute time specified by
  72 .Fa abs_timeout
  73 has already been passed at the time of the call.
  74 .Pp
  75 Note that the timeout is based on the
  76 .Dv CLOCK_REALTIME
  77 clock.
  78 .Pp
  79 The validity of the
  80 .Fa abs_timeout
  81 is not checked if the semaphore can be locked immediately.
  82 .Pp
  83 The
  84 .Fn sem_clockwait_np
  85 function is a more flexible variant of
  86 .Fn sem_timedwait .
  87 The
  88 .Fa clock_id
  89 parameter specifies the reference clock.
  90 If the
  91 .Fa flags
  92 parameter contains
  93 .Dv TIMER_ABSTIME ,
  94 then the requested timeout
  95 .Pq Fa rqtp
  96 is an absolute timeout; otherwise,
  97 the timeout is relative.
  98 If this function fails with
  99 .Er EINTR
 100 and the timeout is relative,
 101 a non-NULL
 102 .Fa rmtp
 103 will be updated to contain the amount of time remaining in the interval
 104 .Po
 105 the requested time minus the time actually slept
 106 .Pc .
 107 An absolute timeout has no effect on
 108 .Fa rmtp .
 109 A single structure can be used for both
 110 .Fa rqtp
 111 and
 112 .Fa rmtp .
 113 .Sh RETURN VALUES
 114 These
 115 functions return zero if the calling process successfully performed the
 116 semaphore lock operation on the semaphore designated by
 117 .Fa sem .
 118 If the call was unsuccessful, the state of the semaphore is unchanged,
 119 and the function returns a value of \-1 and sets the global variable
 120 .Va errno
 121 to indicate the error.
 122 .Sh ERRORS
 123 These functions will fail if:
 124 .Bl -tag -width Er
 125 .It Bq Er EINVAL
 126 The
 127 .Fa sem
 128 argument does not refer to a valid semaphore, or the process or thread would
 129 have blocked, and the
 130 .Fa abs_timeout
 131 parameter specified a nanoseconds field value less than zero or greater than
 132 or equal to 1000 million.
 133 .It Bq Er ETIMEDOUT
 134 The semaphore could not be locked before the specified timeout expired.
 135 .It Bq Er EINTR
 136 A signal interrupted this function.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr sem_post 3 ,
 140 .Xr sem_trywait 3 ,
 141 .Xr sem_wait 3
 142 .Sh STANDARDS
 143 The
 144 .Fn sem_timedwait
 145 function conforms to
 146 .St -p1003.1-2004 .
 147 The
 148 .Fn sem_clockwait_np
 149 function is not specified by any standard;
 150 it exists only on
 151 .Fx
 152 at the time of this writing.
 153 .Sh HISTORY
 154 The
 155 .Fn sem_timedwait
 156 function first appeared in
 157 .Fx 5.0 .
 158 The
 159 .Fn sem_clockwait_np
 160 function first appeared in
 161 .Fx 11.1 .