46 .TH SEM_TIMEDWAIT 3C "Feb 5, 2008"
47 .SH NAME
48 sem_timedwait, sem_reltimedwait_np \- lock a semaphore
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <semaphore.h>
53 #include <time.h>
54
55 \fBint\fR \fBsem_timedwait\fR(\fBsem_t *restrict\fR \fIsem\fR,
56 \fBconst struct timespec *restrict\fR \fIabs_timeout\fR);
57 .fi
58
59 .LP
60 .nf
61 \fBint\fR \fBsem_reltimedwait_np\fR(\fBsem_t *restrict\fR \fIsem\fR,
62 \fBconst struct timespec *restrict\fR \fIrel_timeout\fR);
63 .fi
64
65 .SH DESCRIPTION
66 .sp
67 .LP
68 The \fBsem_timedwait()\fR function locks the semaphore referenced by \fIsem\fR
69 as in the \fBsem_wait\fR(3C) function. However, if the semaphore cannot be
70 locked without waiting for another process or thread to unlock the semaphore by
71 performing a \fBsem_post\fR(3C) function, this wait is terminated when the
72 specified timeout expires.
73 .sp
74 .LP
75 The \fBsem_reltimedwait_np()\fR function is identical to the
76 \fBsem_timedwait()\fR function, except that the timeout is specified as a
77 relative time interval.
78 .sp
79 .LP
80 For \fBsem_timedwait()\fR, the timeout expires when the absolute time specified
81 by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock
82 (that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or
83 if the absolute time specified by \fIabs_timeout\fR has already been passed at
84 the time of the call.
85 .sp
86 .LP
87 For \fBsem_reltimedwait_np()\fR, the timeout expires when the time interval
88 specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR
89 clock, or if the time interval specified by \fIrel_timeout\fR is negative at
90 the time of the call.
91 .sp
92 .LP
93 The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR
94 clock. The \fBtimespec\fR data type is defined as a structure in the
95 <\fBtime.h\fR> header.
96 .sp
97 .LP
98 Under no circumstance does the function fail with a timeout if the semaphore
99 can be locked immediately. The validity of the \fIabs_timeout\fR need not be
100 checked if the semaphore can be locked immediately.
101 .SH RETURN VALUES
102 .sp
103 .LP
104 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions return 0 if
105 the calling process successfully performed the semaphore lock operation on the
106 semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of
107 the semaphore is be unchanged and the function returns -1 and sets \fBerrno\fR
108 to indicate the error.
109 .SH ERRORS
110 .sp
111 .LP
112 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions will fail
113 if:
114 .sp
115 .ne 2
116 .na
117 \fB\fBEINVAL\fR\fR
118 .ad
119 .RS 13n
120 The \fIsem\fR argument does not refer to a valid semaphore.
121 .RE
122
123 .sp
124 .ne 2
125 .na
126 \fB\fBEINVAL\fR\fR
127 .ad
128 .RS 13n
129 The process or thread would have blocked, and the timeout parameter specified a
130 nanoseconds field value less than zero or greater than or equal to 1,000
146 if:
147 .sp
148 .ne 2
149 .na
150 \fB\fBEDEADLK\fR\fR
151 .ad
152 .RS 11n
153 A deadlock condition was detected.
154 .RE
155
156 .sp
157 .ne 2
158 .na
159 \fB\fBEINTR\fR\fR
160 .ad
161 .RS 11n
162 A signal interrupted this function.
163 .RE
164
165 .SH ATTRIBUTES
166 .sp
167 .LP
168 See \fBattributes\fR(5) for descriptions of the following attributes:
169 .sp
170
171 .sp
172 .TS
173 box;
174 c | c
175 l | l .
176 ATTRIBUTE TYPE ATTRIBUTE VALUE
177 _
178 Interface Stability Commmitted
179 _
180 MT-Level MT-Safe
181 _
182 Standard See below.
183 .TE
184
185 .sp
186 .LP
187 For \fBsem_timedwait()\fR, see \fBstandards\fR(5).
188 .SH SEE ALSO
189 .sp
190 .LP
191 \fBsemctl\fR(2), \fBsemget\fR(2), \fBsemop\fR(2), \fBtime\fR(2),
192 \fBsem_post\fR(3C), \fBsem_trywait\fR(3C), \fBsem_wait\fR(3C),
193 \fBattributes\fR(5), \fBstandards\fR(5)
|
46 .TH SEM_TIMEDWAIT 3C "Feb 5, 2008"
47 .SH NAME
48 sem_timedwait, sem_reltimedwait_np \- lock a semaphore
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <semaphore.h>
53 #include <time.h>
54
55 \fBint\fR \fBsem_timedwait\fR(\fBsem_t *restrict\fR \fIsem\fR,
56 \fBconst struct timespec *restrict\fR \fIabs_timeout\fR);
57 .fi
58
59 .LP
60 .nf
61 \fBint\fR \fBsem_reltimedwait_np\fR(\fBsem_t *restrict\fR \fIsem\fR,
62 \fBconst struct timespec *restrict\fR \fIrel_timeout\fR);
63 .fi
64
65 .SH DESCRIPTION
66 .LP
67 The \fBsem_timedwait()\fR function locks the semaphore referenced by \fIsem\fR
68 as in the \fBsem_wait\fR(3C) function. However, if the semaphore cannot be
69 locked without waiting for another process or thread to unlock the semaphore by
70 performing a \fBsem_post\fR(3C) function, this wait is terminated when the
71 specified timeout expires.
72 .sp
73 .LP
74 The \fBsem_reltimedwait_np()\fR function is identical to the
75 \fBsem_timedwait()\fR function, except that the timeout is specified as a
76 relative time interval.
77 .sp
78 .LP
79 For \fBsem_timedwait()\fR, the timeout expires when the absolute time specified
80 by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock
81 (that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or
82 if the absolute time specified by \fIabs_timeout\fR has already been passed at
83 the time of the call.
84 .sp
85 .LP
86 For \fBsem_reltimedwait_np()\fR, the timeout expires when the time interval
87 specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR
88 clock, or if the time interval specified by \fIrel_timeout\fR is negative at
89 the time of the call.
90 .sp
91 .LP
92 The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR
93 clock. The \fBtimespec\fR data type is defined as a structure in the
94 <\fBtime.h\fR> header.
95 .sp
96 .LP
97 Under no circumstance does the function fail with a timeout if the semaphore
98 can be locked immediately. The validity of the \fIabs_timeout\fR need not be
99 checked if the semaphore can be locked immediately.
100 .SH RETURN VALUES
101 .LP
102 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions return 0 if
103 the calling process successfully performed the semaphore lock operation on the
104 semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of
105 the semaphore is be unchanged and the function returns -1 and sets \fBerrno\fR
106 to indicate the error.
107 .SH ERRORS
108 .LP
109 The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions will fail
110 if:
111 .sp
112 .ne 2
113 .na
114 \fB\fBEINVAL\fR\fR
115 .ad
116 .RS 13n
117 The \fIsem\fR argument does not refer to a valid semaphore.
118 .RE
119
120 .sp
121 .ne 2
122 .na
123 \fB\fBEINVAL\fR\fR
124 .ad
125 .RS 13n
126 The process or thread would have blocked, and the timeout parameter specified a
127 nanoseconds field value less than zero or greater than or equal to 1,000
143 if:
144 .sp
145 .ne 2
146 .na
147 \fB\fBEDEADLK\fR\fR
148 .ad
149 .RS 11n
150 A deadlock condition was detected.
151 .RE
152
153 .sp
154 .ne 2
155 .na
156 \fB\fBEINTR\fR\fR
157 .ad
158 .RS 11n
159 A signal interrupted this function.
160 .RE
161
162 .SH ATTRIBUTES
163 .LP
164 See \fBattributes\fR(5) for descriptions of the following attributes:
165 .sp
166
167 .sp
168 .TS
169 box;
170 c | c
171 l | l .
172 ATTRIBUTE TYPE ATTRIBUTE VALUE
173 _
174 Interface Stability Committed
175 _
176 MT-Level MT-Safe
177 _
178 Standard See below.
179 .TE
180
181 .sp
182 .LP
183 For \fBsem_timedwait()\fR, see \fBstandards\fR(5).
184 .SH SEE ALSO
185 .LP
186 \fBsemctl\fR(2), \fBsemget\fR(2), \fBsemop\fR(2), \fBtime\fR(2),
187 \fBsem_post\fR(3C), \fBsem_trywait\fR(3C), \fBsem_wait\fR(3C),
188 \fBattributes\fR(5), \fBstandards\fR(5)
|