[c4dddee] | 1 | @c |
---|
[6449498] | 2 | @c COPYRIGHT(c) 1988-2002. |
---|
[7479042] | 3 | @c On-Line Applications Research Corporation(OAR). |
---|
| 4 | @c All rights reserved. |
---|
[c4dddee] | 5 | @c |
---|
[7479042] | 6 | @c $Id$ |
---|
[c4dddee] | 7 | @c |
---|
| 8 | |
---|
[3d7e9240] | 9 | @chapter Semaphore Manager |
---|
[c4dddee] | 10 | |
---|
| 11 | @section Introduction |
---|
| 12 | |
---|
[7479042] | 13 | The semaphore manager provides functions to allocate, delete, and control |
---|
| 14 | semaphores. This manager is based on the POSIX 1003.1 standard. |
---|
[c4dddee] | 15 | |
---|
| 16 | The directives provided by the semaphore manager are: |
---|
| 17 | |
---|
| 18 | @itemize @bullet |
---|
[3d7e9240] | 19 | @item @code{sem_init} - Initialize an unnamed semaphore |
---|
| 20 | @item @code{sem_destroy} - Destroy an unnamed semaphore |
---|
| 21 | @item @code{sem_open} - Open a named semaphore |
---|
| 22 | @item @code{sem_close} - Close a named semaphore |
---|
| 23 | @item @code{sem_unlink} - Remove a named semaphore |
---|
| 24 | @item @code{sem_wait} - Lock a semaphore |
---|
| 25 | @item @code{sem_trywait} - Lock a semaphore |
---|
[e73014b] | 26 | @item @code{sem_timedwait} - Wait on a Semaphore for a Specified Time |
---|
[3d7e9240] | 27 | @item @code{sem_post} - Unlock a semaphore |
---|
| 28 | @item @code{sem_getvalue} - Get the value of a semeaphore |
---|
[c4dddee] | 29 | @end itemize |
---|
| 30 | |
---|
| 31 | @section Background |
---|
| 32 | |
---|
[3d7e9240] | 33 | @subsection Theory |
---|
[7479042] | 34 | Semaphores are used for synchronization and mutual exclusion by indicating the |
---|
| 35 | availability and number of resources. The task (the task which is returning |
---|
| 36 | resources) notifying other tasks of an event increases the number of resources |
---|
| 37 | held by the semaphore by one. The task (the task which will obtain resources) |
---|
| 38 | waiting for the event decreases the number of resources held by the semaphore |
---|
| 39 | by one. If the number of resources held by a semaphore is insufficient (namely |
---|
| 40 | 0), the task requiring resources will wait until the next time resources are |
---|
| 41 | returned to the semaphore. If there is more than one task waiting for a |
---|
| 42 | semaphore, the tasks will be placed in the queue. |
---|
[3d7e9240] | 43 | |
---|
| 44 | @subsection "sem_t" Structure |
---|
[adee5979] | 45 | |
---|
| 46 | @findex sem_t |
---|
| 47 | |
---|
| 48 | The @code{sem_t} structure is used to represent semaphores. It is passed as an |
---|
[3d7e9240] | 49 | argument to the semaphore directives and is defined as follows: |
---|
| 50 | |
---|
| 51 | @example |
---|
[adee5979] | 52 | typedef int sem_t; |
---|
[3d7e9240] | 53 | @end example |
---|
[7479042] | 54 | |
---|
[3d7e9240] | 55 | @subsection Building a Semaphore Attribute Set |
---|
[c4dddee] | 56 | |
---|
| 57 | @section Operations |
---|
| 58 | |
---|
[3d7e9240] | 59 | @subsection Using as a Binary Semaphore |
---|
| 60 | Although POSIX supports mutexes, they are only visible between threads. To work |
---|
| 61 | between processes, a binary semaphore must be used. |
---|
| 62 | |
---|
[7479042] | 63 | Creating a semaphore with a limit on the count of 1 effectively restricts the |
---|
| 64 | semaphore to being a binary semaphore. When the binary semaphore is available, |
---|
| 65 | the count is 1. When the binary semaphore is unavailable, the count is 0. |
---|
| 66 | |
---|
| 67 | Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available. |
---|
[3d7e9240] | 68 | |
---|
[c4dddee] | 69 | There is currently no text in this section. |
---|
| 70 | |
---|
| 71 | @section Directives |
---|
| 72 | |
---|
| 73 | This section details the semaphore manager's directives. |
---|
| 74 | A subsection is dedicated to each of this manager's directives |
---|
| 75 | and describes the calling sequence, related constants, usage, |
---|
| 76 | and status codes. |
---|
| 77 | |
---|
[7479042] | 78 | @c |
---|
| 79 | @c |
---|
| 80 | @c |
---|
[c4dddee] | 81 | @page |
---|
[3d7e9240] | 82 | @subsection sem_init - Initialize an unnamed semaphore |
---|
[c4dddee] | 83 | |
---|
[7479042] | 84 | @findex sem_init |
---|
| 85 | @cindex initialize an unnamed semaphore |
---|
| 86 | |
---|
[c4dddee] | 87 | @subheading CALLING SEQUENCE: |
---|
| 88 | |
---|
| 89 | @ifset is-C |
---|
| 90 | @example |
---|
| 91 | int sem_init( |
---|
[d2bfbaf] | 92 | sem_t *sem, |
---|
| 93 | int pshared, |
---|
| 94 | unsigned int value |
---|
[c4dddee] | 95 | ); |
---|
| 96 | @end example |
---|
| 97 | @end ifset |
---|
| 98 | |
---|
| 99 | @ifset is-Ada |
---|
| 100 | @end ifset |
---|
| 101 | |
---|
| 102 | @subheading STATUS CODES: |
---|
| 103 | |
---|
| 104 | @table @b |
---|
[3d7e9240] | 105 | @item EINVAL |
---|
| 106 | The value argument exceeds SEM_VALUE_MAX |
---|
| 107 | |
---|
| 108 | @item ENOSPC |
---|
| 109 | A resource required to initialize the semaphore has been exhausted |
---|
| 110 | The limit on semaphores (SEM_VALUE_MAX) has been reached |
---|
| 111 | |
---|
| 112 | @item ENOSYS |
---|
| 113 | The function sem_init is not supported by this implementation |
---|
| 114 | |
---|
| 115 | @item EPERM |
---|
| 116 | The process lacks appropriate privileges to initialize the semaphore |
---|
[c4dddee] | 117 | |
---|
| 118 | @end table |
---|
| 119 | |
---|
| 120 | @subheading DESCRIPTION: |
---|
[7479042] | 121 | The sem_init function is used to initialize the unnamed semaphore referred to |
---|
| 122 | by "sem". The value of the initialized semaphore is the parameter "value". The |
---|
[3d7e9240] | 123 | semaphore remains valid until it is destroyed. |
---|
| 124 | |
---|
| 125 | ADD MORE HERE XXX |
---|
[c4dddee] | 126 | |
---|
| 127 | @subheading NOTES: |
---|
[3d7e9240] | 128 | If the functions completes successfully, it shall return a value of zero. |
---|
| 129 | Otherwise, it shall return a value of -1 and set "errno" to specify the error |
---|
| 130 | that occurred. |
---|
| 131 | |
---|
| 132 | Multiprocessing is currently not supported in this implementation. |
---|
[c4dddee] | 133 | |
---|
[7479042] | 134 | @c |
---|
| 135 | @c |
---|
| 136 | @c |
---|
[c4dddee] | 137 | @page |
---|
[3d7e9240] | 138 | @subsection sem_destroy - Destroy an unnamed semaphore |
---|
[c4dddee] | 139 | |
---|
[7479042] | 140 | @findex sem_destroy |
---|
| 141 | @cindex destroy an unnamed semaphore |
---|
| 142 | |
---|
[c4dddee] | 143 | @subheading CALLING SEQUENCE: |
---|
| 144 | |
---|
| 145 | @ifset is-C |
---|
| 146 | @example |
---|
| 147 | int sem_destroy( |
---|
[d2bfbaf] | 148 | sem_t *sem |
---|
[c4dddee] | 149 | ); |
---|
| 150 | @end example |
---|
| 151 | @end ifset |
---|
| 152 | |
---|
| 153 | @ifset is-Ada |
---|
| 154 | @end ifset |
---|
| 155 | |
---|
| 156 | @subheading STATUS CODES: |
---|
| 157 | |
---|
| 158 | @table @b |
---|
[3d7e9240] | 159 | @item EINVAL |
---|
| 160 | The value argument exceeds SEM_VALUE_MAX |
---|
| 161 | |
---|
| 162 | @item ENOSYS |
---|
| 163 | The function sem_init is not supported by this implementation |
---|
| 164 | |
---|
| 165 | @item EBUSY |
---|
| 166 | There are currently processes blocked on the semaphore |
---|
[c4dddee] | 167 | |
---|
| 168 | @end table |
---|
| 169 | |
---|
| 170 | @subheading DESCRIPTION: |
---|
[7479042] | 171 | The sem_destroy function is used to destroy an unnamed semaphore refered to by |
---|
| 172 | "sem". sem_destroy can only be used on a semaphore that was created using |
---|
[3d7e9240] | 173 | sem_init. |
---|
[c4dddee] | 174 | |
---|
| 175 | @subheading NOTES: |
---|
[3d7e9240] | 176 | If the functions completes successfully, it shall return a value of zero. |
---|
| 177 | Otherwise, it shall return a value of -1 and set "errno" to specify the error |
---|
| 178 | that occurred. |
---|
| 179 | |
---|
| 180 | Multiprocessing is currently not supported in this implementation. |
---|
| 181 | |
---|
[c4dddee] | 182 | |
---|
[7479042] | 183 | @c |
---|
| 184 | @c |
---|
| 185 | @c |
---|
[c4dddee] | 186 | @page |
---|
[3d7e9240] | 187 | @subsection sem_open - Open a named semaphore |
---|
[c4dddee] | 188 | |
---|
[7479042] | 189 | @findex sem_open |
---|
| 190 | @cindex open a named semaphore |
---|
| 191 | |
---|
[c4dddee] | 192 | @subheading CALLING SEQUENCE: |
---|
| 193 | |
---|
| 194 | @ifset is-C |
---|
| 195 | @example |
---|
[d2bfbaf] | 196 | int sem_open( |
---|
| 197 | const char *name, |
---|
| 198 | int oflag |
---|
[c4dddee] | 199 | ); |
---|
| 200 | @end example |
---|
| 201 | @end ifset |
---|
| 202 | |
---|
| 203 | @ifset is-Ada |
---|
| 204 | @end ifset |
---|
| 205 | |
---|
[3d7e9240] | 206 | @subheading ARGUMENTS: |
---|
| 207 | |
---|
| 208 | The following flag bit may be set in oflag: |
---|
| 209 | |
---|
[7479042] | 210 | @code{O_CREAT} - Creates the semaphore if it does not already exist. If O_CREAT |
---|
| 211 | is set and the semaphore already exists then O_CREAT has no effect. Otherwise, |
---|
| 212 | sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth |
---|
| 213 | argument: mode and value of type mode_t and unsigned int, respectively. |
---|
[3d7e9240] | 214 | |
---|
[7479042] | 215 | @code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail |
---|
[3d7e9240] | 216 | if the semaphore name exists |
---|
| 217 | |
---|
[c4dddee] | 218 | @subheading STATUS CODES: |
---|
| 219 | |
---|
| 220 | @table @b |
---|
[3d7e9240] | 221 | @item EACCES |
---|
[7479042] | 222 | Valid name specified but oflag permissions are denied, or the semaphore name |
---|
[3d7e9240] | 223 | specified does not exist and permission to create the named semaphore is denied. |
---|
| 224 | |
---|
| 225 | @item EEXIST |
---|
| 226 | O_CREAT and O_EXCL are set and the named semaphore already exists. |
---|
| 227 | |
---|
| 228 | @item EINTR |
---|
[7479042] | 229 | The sem_open() operation was interrupted by a signal. |
---|
[3d7e9240] | 230 | |
---|
| 231 | @item EINVAL |
---|
| 232 | The sem_open() operation is not supported for the given name. |
---|
| 233 | |
---|
| 234 | @item EMFILE |
---|
| 235 | Too many semaphore descriptors or file descriptors in use by this process. |
---|
| 236 | |
---|
| 237 | @item ENAMETOOLONG |
---|
[7479042] | 238 | The length of the name exceed PATH_MAX or name component is longer than NAME_MAX |
---|
| 239 | while POSIX_NO_TRUNC is in effect. |
---|
[3d7e9240] | 240 | |
---|
| 241 | @item ENOENT |
---|
| 242 | O_CREAT is not set and the named semaphore does not exist. |
---|
| 243 | |
---|
| 244 | @item ENOSPC |
---|
| 245 | There is insufficient space for the creation of a new named semaphore. |
---|
| 246 | |
---|
| 247 | @item ENOSYS |
---|
| 248 | The function sem_open() is not supported by this implementation. |
---|
[c4dddee] | 249 | |
---|
| 250 | @end table |
---|
| 251 | |
---|
| 252 | @subheading DESCRIPTION: |
---|
[3d7e9240] | 253 | The sem_open() function establishes a connection between a specified semaphore and |
---|
[7479042] | 254 | a process. After a call to sem_open with a specified semaphore name, a process |
---|
| 255 | can reference to semaphore by the associated name using the address returned by |
---|
| 256 | the call. The oflag arguments listed above control the state of the semaphore by |
---|
[3d7e9240] | 257 | determining if the semaphore is created or accessed by a call to sem_open(). |
---|
[c4dddee] | 258 | |
---|
| 259 | @subheading NOTES: |
---|
| 260 | |
---|
[3d7e9240] | 261 | |
---|
[7479042] | 262 | @c |
---|
| 263 | @c |
---|
| 264 | @c |
---|
[c4dddee] | 265 | @page |
---|
[3d7e9240] | 266 | @subsection sem_close - Close a named semaphore |
---|
[c4dddee] | 267 | |
---|
[7479042] | 268 | @findex sem_close |
---|
| 269 | @cindex close a named semaphore |
---|
| 270 | |
---|
[c4dddee] | 271 | @subheading CALLING SEQUENCE: |
---|
| 272 | |
---|
| 273 | @ifset is-C |
---|
| 274 | @example |
---|
| 275 | int sem_close( |
---|
[d2bfbaf] | 276 | sem_t *sem_close |
---|
[c4dddee] | 277 | ); |
---|
| 278 | @end example |
---|
| 279 | @end ifset |
---|
| 280 | |
---|
| 281 | @ifset is-Ada |
---|
| 282 | @end ifset |
---|
| 283 | |
---|
| 284 | @subheading STATUS CODES: |
---|
| 285 | |
---|
| 286 | @table @b |
---|
[3d7e9240] | 287 | @item EACCES |
---|
[7479042] | 288 | The semaphore argument is not a valid semaphore descriptor. |
---|
[3d7e9240] | 289 | |
---|
| 290 | @item ENOSYS |
---|
| 291 | The function sem_close is not supported by this implementation. |
---|
[c4dddee] | 292 | |
---|
| 293 | @end table |
---|
| 294 | |
---|
| 295 | @subheading DESCRIPTION: |
---|
[7479042] | 296 | The sem_close() function is used to indicate that the calling process is finished |
---|
| 297 | using the named semaphore indicated by sem. The function sem_close deallocates |
---|
| 298 | any system resources that were previously allocated by a sem_open system call. If |
---|
| 299 | sem_close() completes successfully it returns a 1, otherwise a value of -1 is |
---|
[3d7e9240] | 300 | return and errno is set. |
---|
[c4dddee] | 301 | |
---|
| 302 | @subheading NOTES: |
---|
| 303 | |
---|
[7479042] | 304 | @c |
---|
| 305 | @c |
---|
| 306 | @c |
---|
[c4dddee] | 307 | @page |
---|
[3d7e9240] | 308 | @subsection sem_unlink - Unlink a semaphore |
---|
[c4dddee] | 309 | |
---|
[7479042] | 310 | @findex sem_unlink |
---|
| 311 | @cindex unlink a semaphore |
---|
| 312 | |
---|
[c4dddee] | 313 | @subheading CALLING SEQUENCE: |
---|
| 314 | |
---|
| 315 | @ifset is-C |
---|
| 316 | @example |
---|
| 317 | int sem_unlink( |
---|
[d2bfbaf] | 318 | const char *name |
---|
[c4dddee] | 319 | ); |
---|
| 320 | @end example |
---|
| 321 | @end ifset |
---|
| 322 | |
---|
| 323 | @ifset is-Ada |
---|
| 324 | @end ifset |
---|
| 325 | |
---|
| 326 | @subheading STATUS CODES: |
---|
| 327 | |
---|
| 328 | @table @b |
---|
[3d7e9240] | 329 | @item EACCESS |
---|
| 330 | Permission is denied to unlink a semaphore. |
---|
| 331 | |
---|
| 332 | @item ENAMETOOLONG |
---|
[7479042] | 333 | The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect. |
---|
[3d7e9240] | 334 | |
---|
| 335 | @item ENOENT |
---|
| 336 | The name of the semaphore does not exist. |
---|
| 337 | |
---|
| 338 | @item ENOSPC |
---|
| 339 | There is insufficient space for the creation of a new named semaphore. |
---|
| 340 | |
---|
| 341 | @item ENOSYS |
---|
| 342 | The function sem_unlink is not supported by this implementation. |
---|
[c4dddee] | 343 | |
---|
| 344 | @end table |
---|
| 345 | |
---|
| 346 | @subheading DESCRIPTION: |
---|
[3d7e9240] | 347 | The sem_unlink() function shall remove the semaphore name by the string name. If |
---|
[7479042] | 348 | a process is currently accessing the name semaphore, the sem_unlink command has |
---|
[3d7e9240] | 349 | no effect. If one or more processes have the semaphore open when the sem_unlink |
---|
[7479042] | 350 | function is called, the destruction of semaphores shall be postponed until all |
---|
| 351 | reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. |
---|
| 352 | After all references have been destroyed, it returns immediately. |
---|
[3d7e9240] | 353 | |
---|
[7479042] | 354 | If the termination is successful, the function shall return 0. Otherwise, a -1 |
---|
[3d7e9240] | 355 | is returned and the errno is set. |
---|
[c4dddee] | 356 | |
---|
| 357 | @subheading NOTES: |
---|
| 358 | |
---|
[7479042] | 359 | @c |
---|
| 360 | @c |
---|
| 361 | @c |
---|
[c4dddee] | 362 | @page |
---|
[3d7e9240] | 363 | @subsection sem_wait - Wait on a Semaphore |
---|
[c4dddee] | 364 | |
---|
[7479042] | 365 | @findex sem_wait |
---|
| 366 | @cindex wait on a semaphore |
---|
| 367 | |
---|
[c4dddee] | 368 | @subheading CALLING SEQUENCE: |
---|
| 369 | |
---|
| 370 | @ifset is-C |
---|
| 371 | @example |
---|
| 372 | int sem_wait( |
---|
[d2bfbaf] | 373 | sem_t *sem |
---|
[c4dddee] | 374 | ); |
---|
| 375 | @end example |
---|
| 376 | @end ifset |
---|
| 377 | |
---|
| 378 | @ifset is-Ada |
---|
| 379 | @end ifset |
---|
| 380 | |
---|
| 381 | @subheading STATUS CODES: |
---|
| 382 | |
---|
| 383 | @table @b |
---|
[3d7e9240] | 384 | @item EINVAL |
---|
| 385 | The "sem" argument does not refer to a valid semaphore |
---|
[c4dddee] | 386 | |
---|
| 387 | @end table |
---|
| 388 | |
---|
| 389 | @subheading DESCRIPTION: |
---|
[7479042] | 390 | This function attempts to lock a semaphore specified by @code{sem}. If the |
---|
[3d7e9240] | 391 | semaphore is available, then the semaphore is locked (i.e., the semaphore |
---|
[7479042] | 392 | value is decremented). If the semaphore is unavailable (i.e., the semaphore |
---|
[3d7e9240] | 393 | value is zero), then the function will block until the semaphore becomes |
---|
[7479042] | 394 | available. It will then successfully lock the semaphore. The semaphore |
---|
[3d7e9240] | 395 | remains locked until released by a @code{sem_post()} call. |
---|
| 396 | |
---|
| 397 | If the call is unsuccessful, then the function returns -1 and sets errno to the |
---|
| 398 | appropriate error code. |
---|
[c4dddee] | 399 | |
---|
| 400 | @subheading NOTES: |
---|
[3d7e9240] | 401 | Multiprocessing is not supported in this implementation. |
---|
[c4dddee] | 402 | |
---|
[7479042] | 403 | @c |
---|
| 404 | @c |
---|
| 405 | @c |
---|
[c4dddee] | 406 | @page |
---|
[3d7e9240] | 407 | @subsection sem_trywait - Non-blocking Wait on a Semaphore |
---|
[c4dddee] | 408 | |
---|
[7479042] | 409 | @findex sem_trywait |
---|
| 410 | @cindex non |
---|
| 411 | |
---|
[c4dddee] | 412 | @subheading CALLING SEQUENCE: |
---|
| 413 | |
---|
| 414 | @ifset is-C |
---|
| 415 | @example |
---|
| 416 | int sem_trywait( |
---|
[d2bfbaf] | 417 | sem_t *sem |
---|
[3d7e9240] | 418 | ); |
---|
| 419 | @end example |
---|
| 420 | @end ifset |
---|
| 421 | |
---|
| 422 | @ifset is-Ada |
---|
| 423 | @end ifset |
---|
| 424 | |
---|
| 425 | @subheading STATUS CODES: |
---|
| 426 | |
---|
| 427 | @table @b |
---|
| 428 | @item EAGAIN |
---|
| 429 | The semaphore is not available (i.e., the semaphore value is zero), so the |
---|
| 430 | semaphore could not be locked. |
---|
| 431 | |
---|
| 432 | @item EINVAL |
---|
| 433 | The @code{sem} argument does not refewr to a valid semaphore |
---|
| 434 | |
---|
| 435 | @end table |
---|
| 436 | |
---|
| 437 | @subheading DESCRIPTION: |
---|
[7479042] | 438 | This function attempts to lock a semaphore specified by @code{sem}. If the |
---|
[3d7e9240] | 439 | semaphore is available, then the semaphore is locked (i.e., the semaphore |
---|
[7479042] | 440 | value is decremented) and the function returns a value of 0. The semaphore |
---|
| 441 | remains locked until released by a @code{sem_post()} call. If the semaphore |
---|
[3d7e9240] | 442 | is unavailable (i.e., the semaphore value is zero), then the function will |
---|
| 443 | return a value of -1 immediately and set @code{errno} to EAGAIN. |
---|
| 444 | |
---|
| 445 | If the call is unsuccessful, then the function returns -1 and sets |
---|
| 446 | @code{errno} to the appropriate error code. |
---|
| 447 | |
---|
| 448 | @subheading NOTES: |
---|
| 449 | Multiprocessing is not supported in this implementation. |
---|
| 450 | |
---|
[7479042] | 451 | @c |
---|
| 452 | @c |
---|
| 453 | @c |
---|
[3d7e9240] | 454 | @page |
---|
| 455 | @subsection sem_timedwait - Wait on a Semaphore for a Specified Time |
---|
| 456 | |
---|
[7479042] | 457 | @findex sem_timedwait |
---|
| 458 | @cindex wait on a semaphore for a specified time |
---|
| 459 | |
---|
[3d7e9240] | 460 | @subheading CALLING SEQUENCE: |
---|
| 461 | |
---|
| 462 | @ifset is-C |
---|
| 463 | @example |
---|
| 464 | int sem_timedwait( |
---|
[d2bfbaf] | 465 | sem_t *sem, |
---|
[9b4f75e] | 466 | const struct timespec *abstime |
---|
[c4dddee] | 467 | ); |
---|
| 468 | @end example |
---|
| 469 | @end ifset |
---|
| 470 | |
---|
| 471 | @ifset is-Ada |
---|
| 472 | @end ifset |
---|
| 473 | |
---|
| 474 | @subheading STATUS CODES: |
---|
| 475 | |
---|
| 476 | @table @b |
---|
[3d7e9240] | 477 | @item EAGAIN |
---|
| 478 | The semaphore is not available (i.e., the semaphore value is zero), so the |
---|
| 479 | semaphore could not be locked. |
---|
| 480 | |
---|
| 481 | @item EINVAL |
---|
| 482 | The @code{sem} argument does not refewr to a valid semaphore |
---|
[c4dddee] | 483 | |
---|
| 484 | @end table |
---|
| 485 | |
---|
| 486 | @subheading DESCRIPTION: |
---|
[9b4f75e] | 487 | |
---|
| 488 | This function attemtps to lock a semaphore specified by @code{sem}, |
---|
| 489 | and will wait for the semaphore until the absolute time specified by |
---|
| 490 | @code{abstime}. If the semaphore is available, then the semaphore is |
---|
| 491 | locked (i.e., the semaphore value is decremented) and the function |
---|
| 492 | returns a value of 0. The semaphore remains locked until released by |
---|
| 493 | a @code{sem_post()} call. If the semaphore is unavailable, then the |
---|
| 494 | function will wait for the semaphore to become available for the amount |
---|
| 495 | of time specified by @code{timeout}. |
---|
[3d7e9240] | 496 | |
---|
| 497 | If the semaphore does not become available within the interval specified by |
---|
| 498 | @code{timeout}, then the function returns -1 and sets @code{errno} to EAGAIN. |
---|
| 499 | If any other error occurs, the function returns -1 and sets @code{errno} to |
---|
| 500 | the appropriate error code. |
---|
[c4dddee] | 501 | |
---|
| 502 | @subheading NOTES: |
---|
[3d7e9240] | 503 | Multiprocessing is not supported in this implementation. |
---|
[c4dddee] | 504 | |
---|
[7479042] | 505 | @c |
---|
| 506 | @c |
---|
| 507 | @c |
---|
[c4dddee] | 508 | @page |
---|
[3d7e9240] | 509 | @subsection sem_post - Unlock a Semaphore |
---|
[c4dddee] | 510 | |
---|
[7479042] | 511 | @findex sem_post |
---|
| 512 | @cindex unlock a semaphore |
---|
| 513 | |
---|
[c4dddee] | 514 | @subheading CALLING SEQUENCE: |
---|
| 515 | |
---|
| 516 | @ifset is-C |
---|
| 517 | @example |
---|
| 518 | int sem_post( |
---|
[d2bfbaf] | 519 | sem_t *sem |
---|
[c4dddee] | 520 | ); |
---|
| 521 | @end example |
---|
| 522 | @end ifset |
---|
| 523 | |
---|
| 524 | @ifset is-Ada |
---|
| 525 | @end ifset |
---|
| 526 | |
---|
| 527 | @subheading STATUS CODES: |
---|
| 528 | |
---|
| 529 | @table @b |
---|
[3d7e9240] | 530 | @item EINVAL |
---|
| 531 | The @code{sem} argument does not refer to a valid semaphore |
---|
[c4dddee] | 532 | |
---|
| 533 | @end table |
---|
| 534 | |
---|
| 535 | @subheading DESCRIPTION: |
---|
[7479042] | 536 | This function attempts to release the semaphore specified by @code{sem}. If |
---|
[3d7e9240] | 537 | other tasks are waiting on the semaphore, then one of those tasks (which one |
---|
| 538 | depends on the scheduler being used) is allowed to lock the semaphore and |
---|
| 539 | return from its @code{sem_wait()}, @code{sem_trywait()}, or |
---|
[7479042] | 540 | @code{sem_timedwait()} call. If there are no other tasks waiting on the |
---|
| 541 | semaphore, then the semaphore value is simply incremented. @code{sem_post()} |
---|
[3d7e9240] | 542 | returns 0 upon successful completion. |
---|
| 543 | |
---|
| 544 | If an error occurs, the function returns -1 and sets @code{errno} to the |
---|
| 545 | appropriate error code. |
---|
[c4dddee] | 546 | |
---|
| 547 | @subheading NOTES: |
---|
[3d7e9240] | 548 | Multiprocessing is not supported in this implementation. |
---|
[c4dddee] | 549 | |
---|
[7479042] | 550 | @c |
---|
| 551 | @c |
---|
| 552 | @c |
---|
[c4dddee] | 553 | @page |
---|
[3d7e9240] | 554 | @subsection sem_getvalue - Get the value of a semaphore |
---|
[c4dddee] | 555 | |
---|
[7479042] | 556 | @findex sem_getvalue |
---|
| 557 | @cindex get the value of a semaphore |
---|
| 558 | |
---|
[c4dddee] | 559 | @subheading CALLING SEQUENCE: |
---|
| 560 | |
---|
| 561 | @ifset is-C |
---|
| 562 | @example |
---|
| 563 | int sem_getvalue( |
---|
[d2bfbaf] | 564 | sem_t *sem, |
---|
| 565 | int *sval |
---|
[c4dddee] | 566 | ); |
---|
| 567 | @end example |
---|
| 568 | @end ifset |
---|
| 569 | |
---|
| 570 | @ifset is-Ada |
---|
| 571 | @end ifset |
---|
| 572 | |
---|
| 573 | @subheading STATUS CODES: |
---|
| 574 | |
---|
| 575 | @table @b |
---|
[3d7e9240] | 576 | @item EINVAL |
---|
| 577 | The "sem" argument does not refer to a valid semaphore |
---|
| 578 | |
---|
| 579 | @item ENOSYS |
---|
| 580 | The function sem_getvalue is not supported by this implementation |
---|
[c4dddee] | 581 | |
---|
| 582 | @end table |
---|
| 583 | |
---|
| 584 | @subheading DESCRIPTION: |
---|
[7479042] | 585 | The sem_getvalue functions sets the location referenced by the "sval" argument |
---|
[3d7e9240] | 586 | to the value of the semaphore without affecting the state of the semaphore. The |
---|
[7479042] | 587 | updated value represents a semaphore value that occurred at some point during |
---|
| 588 | the call, but is not necessarily the actual value of the semaphore when it |
---|
[3d7e9240] | 589 | returns to the calling process. |
---|
[7479042] | 590 | |
---|
| 591 | If "sem" is locked, the value returned by sem_getvalue will be zero or a |
---|
| 592 | negative number whose absolute value is the number of processes waiting for the |
---|
[3d7e9240] | 593 | semaphore at some point during the call. |
---|
[c4dddee] | 594 | |
---|
| 595 | @subheading NOTES: |
---|
[7479042] | 596 | If the functions completes successfully, it shall return a value of zero. |
---|
| 597 | Otherwise, it shall return a value of -1 and set "errno" to specify the error |
---|
[3d7e9240] | 598 | that occurred. |
---|