Parallel and Distributed Programming Using C++
|
28273 NAME 28274 posix_spawn, posix_spawnp ”spawn a process ( ADVANCED REALTIME )
28275 SYNOPSIS
28276 SPN #include <spawn.h> 28277 int posix_spawn (pid_t *restrict pid , const char *restrict path , 28278 const posix_spawn_file_actions_t * file_actions, 28279 const posix_spawnattr_t *restrict attrp , 28280 char *const argv [restrict], char *const envp [restrict]); 28281 int posix_spawnp (pid_t *restrict pid , const char *restrict file , 28282 const posix_spawn_file_actions_t * file_actions, 28283 const posix_spawnattr_t *restrict attrp , 28284 char *const argv [restrict], char * const envp [restrict]); 28285
28286 DESCRIPTION 28287 The posix_spawn () and posix_spawnp () functions shall create a new process (child process) from 28288 the specified process image. The new process image shall be constructed from a regular 28289 executable file called the new process image file.
28290 When a C program is executed as the result of this call, it shall be entered as a C-language 28291 function call as follows :
28292 int main (int argc , char * argv []);
28293 where argc is the argument count and argv is an array of character pointers to the arguments 28294 themselves . In addition, the following variable:
28295 extern char **environ;
28296 shall be initialized as a pointer to an array of character pointers to the environment strings.
28297 The argument argv is an array of character pointers to null- terminated strings. The last member 28298 of this array shall be a null pointer and is not counted in argc . These strings constitute the 28299 argument list available to the new process image. The value in argv [0] should point to a filename 28300 that is associated with the process image being started by the posix_spawn () or posix_spawnp () 28301 function.
28302 The argument envp is an array of character pointers to null-terminated strings. These strings 28303 constitute the environment for the new process image. The environment array is terminated by a 28304 null pointer.
28305 The number of bytes available for the child process' combined argument and environment lists 28306 is {ARG_MAX}. The implementation shall specify in the system documentation (see the Base 28307 Definitions volume of IEEE Std 1003.1-2001, Chapter 2, Conformance) whether any list 28308 overhead, such as length words, null terminators, pointers, or alignment bytes, is included in 28309 this total.
28310 The path argument to posix_spawn () is a pathname that identifies the new process image file to 28311 execute.
28312 The file parameter to posix_spawnp () shall be used to construct a pathname that identifies the 28313 new process image file. If the file parameter contains a slash character, the file parameter shall be 28314 used as the pathname for the new process image file. Otherwise , the path prefix for this file shall 28315 be obtained by a search of the directories passed as the environment variable PATH (see the Base 28316 Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environment Variables ). If this 28317 environment variable is not defined, the results of the search are implementation-defined.
28318 If file_actions is a null pointer, then file descriptors open in the calling process shall remain open 28319 in the child process, except for those whose close-on- exec flag FD_CLOEXEC is set (see fcntl (). 28320 For those file descriptors that remain open, all attributes of the corresponding open file 28321 descriptions, including file locks (see fcntl ()), shall remain unchanged.
28322 If file_actions is not NULL, then the file descriptors open in the child process shall be those open 28323 in the calling process as modified by the spawn file actions object pointed to by file_actions and 28324 the FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have 28325 been processed . The effective order of processing the spawn file actions shall be:
28326 1. The set of open file descriptors for the child process shall initially be the same set as is 28327 open for the calling process. All attributes of the corresponding open file descriptions, 28328 including file locks (see fcntl ()), shall remain unchanged. 28329 2. The signal mask, signal default actions, and the effective user and group IDs for the child 28330 process shall be changed as specified in the attributes object referenced by attrp . 28331 3. The file actions specified by the spawn file actions object shall be performed in the order in 28332 which they were added to the spawn file actions object. 28333 4. Any file descriptor that has its FD_CLOEXEC flag set (see fcntl ()) shall be closed.
28334 The posix_spawnattr_t spawn attributes object type is defined in < spawn.h>. It shall contain at 28335 least the attributes defined below.
28336 If the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object 28337 referenced by attrp , and the spawn-pgroup attribute of the same object is non-zero , then the 28338 child's process group shall be as specified in the spawn-pgroup attribute of the object referenced 28339 by attrp .
28340 As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of 28341 the object referenced by attrp , and the spawn-pgroup attribute of the same object is set to zero, 28342 then the child shall be in a new process group with a process group ID equal to its process ID.
28343 If the POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object 28344 referenced by attrp , the new child process shall inherit the parent's process group.
28345 PS If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute of the object 28346 referenced by attrp , but POSIX_SPAWN_SETSCHEDULER is not set, the new process image 28347 shall initially have the scheduling policy of the calling process with the scheduling parameters 28348 specified in the spawn-schedparam attribute of the object referenced by attrp .
28349 If the POSIX_SPAWN_SETSCHEDULER flag is set in the spawn-flags attribute of the object 28350 referenced by attrp (regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), 28351 the new process image shall initially have the scheduling policy specified in the spawn - 28352 schedpolicy attribute of the object referenced by attrp and the scheduling parameters specified in 28353 the spawn-schedparam attribute of the same object.
28354 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 28355 governs the effective user ID of the child process. If this flag is not set, the child process shall 28356 inherit the parent process' effective user ID. If this flag is set, the child process' effective user ID 28357 shall be reset to the parent's real user ID. In either case, if the set-user-ID mode bit of the new 28358 process image file is set, the effective user ID of the child process shall become that file's owner 28359 ID before the new process image begins execution.
28360 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 28361 also governs the effective group ID of the child process. If this flag is not set, the child process 28362 shall inherit the parent process' effective group ID. If this flag is set, the child process' effective 28363 group ID shall be reset to the parent's real group ID. In either case, if the set-group-ID mode bit 28364 of the new process image file is set, the effective group ID of the child process shall become that 28365 file's group ID before the new process image begins execution.
28366 If the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object 28367 referenced by attrp , the child process shall initially have the signal mask specified in the spawn - 28368 sigmask attribute of the object referenced by attrp .
28369 If the POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute of the object referenced 28370 by attrp , the signals specified in the spawn-sigdefault attribute of the same object shall be set to 28371 their default actions in the child process. Signals set to the default action in the parent process 28372 shall be set to the default action in the child process.
28373 Signals set to be caught by the calling process shall be set to the default action in the child 28374 process.
28375 Except for SIGCHLD, signals set to be ignored by the calling process image shall be set to be 28376 ignored by the child process, unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag 28377 being set in the spawn-flags attribute of the object referenced by attrp and the signals being 28378 indicated in the spawn-sigdefault attribute of the object referenced by attrp .
28379 If the SIGCHLD signal is set to be ignored by the calling process, it is unspecified whether the 28380 SIGCHLD signal is set to be ignored or to the default action in the child process, unless 28381 otherwise specified by the POSIX_SPAWN_SETSIGDEF flag being set in the spawn_flags 28382 attribute of the object referenced by attrp and the SIGCHLD signal being indicated in the 28383 spawn_sigdefault attribute of the object referenced by attrp .
28384 If the value of the attrp pointer is NULL, then the default values are used.
28385 All process attributes, other than those influenced by the attributes set in the object referenced 28386 by attrp as specified above or by the file descriptor manipulations specified in file_actions, shall 28387 appear in the new process image as though fork () had been called to create a child process and 28388 then a member of the exec family of functions had been called by the child process to execute the 28389 new process image.
28390 THR It is implementation-defined whether the fork handlers are run when posix_spawn () or 28391 posix_spawnp () is called.
28392 RETURN VALUE 28393 Upon successful completion, posix_spawn () and posix_spawnp () shall return the process ID of the 28394 child process to the parent process, in the variable pointed to by a non-NULL pid argument, and 28395 shall return zero as the function return value. Otherwise, no child process shall be created, the 28396 value stored into the variable pointed to by a non-NULL pid is unspecified, and an error number 28397 shall be returned as the function return value to indicate the error. If the pid argument is a null 28398 pointer, the process ID of the child is not returned to the caller.
28399 ERRORS 28400 The posix_spawn () and posix_spawnp () functions may fail if:
28401 [EINVAL] The value specified by file_actions or attrp is invalid.
28402 If this error occurs after the calling process successfully returns from the posix_spawn () or 28403 posix_spawnp () function, the child process may exit with exit status 127.
28404 If posix_spawn () or posix_spawnp () fail for any of the reasons that would cause fork () or one of 28405 the exec family of functions to fail, an error value shall be returned as described by fork () and 28406 exec , respectively (or, if the error occurs after the calling process successfully returns, the child 28407 process shall exit with exit status 127).
28408 If POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by 28409 attrp , and posix_spawn () or posix_spawnp () fails while changing the child's process group, an 28410 error value shall be returned as described by setpgid () (or, if the error occurs after the calling 28411 process successfully returns, the child process shall exit with exit status 127).
28412 PS If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not set 28413 in the spawn-flags attribute of the object referenced by attrp , then if posix_spawn () or 28414 posix_spawnp () fails for any of the reasons that would cause sched_setparam () to fail, an error 28415 value shall be returned as described by sched_setparam () (or, if the error occurs after the calling 28416 process successfully returns, the child process shall exit with exit status 127).
28417 If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by 28418 attrp , and if posix_spawn () or posix_spawnp () fails for any of the reasons that would cause 28419 sched_setscheduler () to fail, an error value shall be returned as described by sched_setscheduler () 28420 (or, if the error occurs after the calling process successfully returns, the child process shall exit 28421 with exit status 127).
28422 If the file_actions argument is not NULL, and specifies any close, dup2 , or open actions to be 28423 performed, and if posix_spawn () or posix_spawnp () fails for any of the reasons that would cause 28424 close (), dup2 (), or open () to fail, an error value shall be returned as described by close (), dup2 (), 28425 and open (), respectively (or, if the error occurs after the calling process successfully returns, the 28426 child process shall exit with exit status 127). An open file action may, by itself, result in any of 28427 the errors described by close () or dup2 (), in addition to those described by open ().
28428 EXAMPLES 28429 None.
28430 APPLICATION USAGE 28431 These functions are part of the Spawn option and need not be provided on all implementations .
28432 RATIONALE 28433 The posix_spawn () function and its close relation posix_spawnp () have been introduced to 28434 overcome the following perceived difficulties with fork (): the fork () function is difficult or 28435 impossible to implement without swapping or dynamic address translation.
28436 Swapping is generally too slow for a realtime environment. 28437 Dynamic address translation is not available everywhere that POSIX might be useful. 28438 Processes are too useful to simply option out of POSIX whenever it must run without 28439 address translation or other MMU services.
28440 Thus, POSIX needs process creation and file execution primitives that can be efficiently 28441 implemented without address translation or other MMU services.
28442 The posix_spawn () function is implementable as a library routine, but both posix_spawn () and 28443 posix_spawnp () are designed as kernel operations. Also, although they may be an efficient 28444 replacement for many fork ()/ exec pairs, their goal is to provide useful process creation 28445 primitives for systems that have difficulty with fork (), not to provide drop-in replacements for 28446 fork ()/ exec .
28447 This view of the role of posix_spawn () and posix_spawnp () influenced the design of their API. It 28448 does not attempt to provide the full functionality of fork ()/ exec in which arbitrary user-specified 28449 operations of any sort are permitted between the creation of the child process and the execution 28450 of the new process image; any attempt to reach that level would need to provide a programming 28451 language as parameters. Instead, posix_spawn () and posix_spawnp () are process creation 28452 primitives like the Start_Process and Start_Process_Search Ada language bindings package 28453 POSIX_Process_Primitives and also like those in many operating systems that are not UNIX 28454 systems, but with some POSIX-specific additions.
28455 To achieve its coverage goals, posix_spawn () and posix_spawnp () have control of six types of 28456 inheritance: file descriptors, process group ID, user and group ID, signal mask, scheduling, and 28457 whether each signal ignored in the parent will remain ignored in the child, or be reset to its 28458 default action in the child.
28459 Control of file descriptors is required to allow an independently written child process image to 28460 access data streams opened by and even generated or read by the parent process without being 28461 specifically coded to know which parent files and file descriptors are to be used. Control of the 28462 process group ID is required to control how the child process' job control relates to that of the 28463 parent.
28464 Control of the signal mask and signal defaulting is sufficient to support the implementation of 28465 system (). Although support for system () is not explicitly one of the goals for posix_spawn () and 28466 posix_spawnp (), it is covered under the "at least 50%" coverage goal.
28467 The intention is that the normal file descriptor inheritance across fork (), the subsequent effect of 28468 the specified spawn file actions, and the normal file descriptor inheritance across one of the exec 28469 family of functions should fully specify open file inheritance. The implementation need make no 28470 decisions regarding the set of open file descriptors when the child process image begins 28471 execution, those decisions having already been made by the caller and expressed as the set of 28472 open file descriptors and their FD_CLOEXEC flags at the time of the call and the spawn file 28473 actions object specified in the call. We have been assured that in cases where the POSIX 28474 Start_Process Ada primitives have been implemented in a library, this method of controlling file 28475 descriptor inheritance may be implemented very easily.
28476 We can identify several problems with posix_spawn () and posix_spawnp (), but there does not 28477 appear to be a solution that introduces fewer problems. Environment modification for child 28478 process attributes not specifiable via the attrp or file_actions arguments must be done in the 28479 parent process, and since the parent generally wants to save its context, it is more costly than 28480 similar functionality with fork ()/ exec . It is also complicated to modify the environment of a 28481 multi-threaded process temporarily, since all threads must agree when it is safe for the 28482 environment to be changed. However, this cost is only borne by those invocations of 28483 posix_spawn () and posix_spawnp () that use the additional functionality. Since extensive 28484 modifications are not the usual case, and are particularly unlikely in time-critical code, keeping 28485 much of the environment control out of posix_spawn () and posix_spawnp () is appropriate design.
28486 The posix_spawn () and posix_spawnp () functions do not have all the power of fork ()/ exec . This is 28487 to be expected. The fork () function is a wonderfully powerful operation. We do not expect to 28488 duplicate its functionality in a simple, fast function with no special hardware requirements. It is 28489 worth noting that posix_spawn () and posix_spawnp () are very similar to the process creation 28490 operations on many operating systems that are not UNIX systems.
28491 Requirements
28492 The requirements for posix_spawn () and posix_spawnp () are: 28493 They must be implementable without an MMU or unusual hardware. 28494 They must be compatible with existing POSIX standards. 28495 Additional goals are: 28496 They should be efficiently implementable. 28497 They should be able to replace at least 50% of typical executions of fork (). 28498 A system with posix_spawn () and posix_spawnp () and without fork () should be useful, at least 28499 for realtime applications. 28500 A system with fork () and the exec family should be able to implement posix_spawn () and 28501 posix_spawnp () as library routines.
28502 Two-Syntax 28503 POSIX exec has several calling sequences with approximately the same functionality. These 28504 appear to be required for compatibility with existing practice. Since the existing practice for the 28505 posix_spawn* () functions is otherwise substantially unlike POSIX, we feel that simplicity 28506 outweighs compatibility. There are, therefore, only two names for the posix_spawn* () functions.
28507 The parameter list does not differ between posix_spawn () and posix_spawnp (); posix_spawnp () 28508 interprets the second parameter more elaborately than posix_spawn ().
28509 Compatibility with POSIX.5 (Ada)
28510 The Start_Process and Start_Process_Search procedures from the POSIX_Process_Primitives 28511 package from the Ada language binding to POSIX.1 encapsulate fork () and exec functionality in a 28512 manner similar to that of posix_spawn () and posix_spawnp (). Originally, in keeping with our 28513 simplicity goal, the standard developers had limited the capabilities of posix_spawn () and 28514 posix_spawnp () to a subset of the capabilities of Start_Process and Start_Process_Search; certain 28515 non-default capabilities were not supported. However, based on suggestions by the ballot group 28516 to improve file descriptor mapping or drop it, and on the advice of an Ada Language Bindings 28517 working group member, the standard developers decided that posix_spawn () and posix_spawnp () 28518 should be sufficiently powerful to implement Start_Process and Start_Process_Search. The 28519 rationale is that if the Ada language binding to such a primitive had already been approved as 28520 an IEEE standard, there can be little justification for not approving the functionally-equivalent 28521 parts of a C binding. The only three capabilities provided by posix_spawn () and posix_spawnp () 28522 that are not provided by Start_Process and Start_Process_Search are optionally specifying the 28523 child's process group ID, the set of signals to be reset to default signal handling in the child 28524 process, and the child's scheduling policy and parameters.
28525 For the Ada language binding for Start_Process to be implemented with posix_spawn (), that 28526 binding would need to explicitly pass an empty signal mask and the parent's environment to 28527 posix_spawn () whenever the caller of Start_Process allowed these arguments to default, since 28528 posix_spawn () does not provide such defaults. The ability of Start_Process to mask user-specified 28529 signals during its execution is functionally unique to the Ada language binding and must be 28530 dealt with in the binding separately from the call to posix_spawn ().
28531 Process Group
28532 The process group inheritance field can be used to join the child process with an existing process 28533 group. By assigning a value of zero to the spawn-pgroup attribute of the object referenced by 28534 attrp , the setpgid () mechanism will place the child process in a new process group.
28535 Threads
28536 Without the posix_spawn () and posix_spawnp () functions, systems without address translation 28537 can still use threads to give an abstraction of concurrency. In many cases, thread creation 28538 suffices, but it is not always a good substitute. The posix_spawn () and posix_spawnp () functions 28539 are considerably "heavier" than thread creation. Processes have several important attributes that 28540 threads do not. Even without address translation, a process may have base-and-bound memory 28541 protection. Each process has a process environment including security attributes and file 28542 capabilities, and powerful scheduling attributes. Processes abstract the behavior of non- 28543 uniform-memory-architecture multi-processors better than threads, and they are more 28544 convenient to use for activities that are not closely linked.
28545 The posix_spawn () and posix_spawnp () functions may not bring support for multiple processes to 28546 every configuration. Process creation is not the only piece of operating system support required 28547 to support multiple processes. The total cost of support for multiple processes may be quite high 28548 in some circumstances. Existing practice shows that support for multiple processes is 28549 uncommon and threads are common among "tiny kernels ". There should, therefore, probably 28550 continue to be AEPs for operating systems with only one process.
28551 Asynchronous Error Notification
28552 A library implementation of posix_spawn () or posix_spawnp () may not be able to detect all 28553 possible errors before it forks the child process. IEEE Std 1003.1-2001 provides for an error 28554 indication returned from a child process which could not successfully complete the spawn 28555 operation via a special exit status which may be detected using the status value returned by 28556 wait () and waitpid ().
28557 The stat_val interface and the macros used to interpret it are not well suited to the purpose of 28558 returning API errors, but they are the only path available to a library implementation. Thus, an 28559 implementation may cause the child process to exit with exit status 127 for any error detected 28560 during the spawn process after the posix_spawn () or posix_spawnp () function has successfully 28561 returned.
28562 The standard developers had proposed using two additional macros to interpret stat_val. The 28563 first, WIFSPAWNFAIL, would have detected a status that indicated that the child exited because 28564 of an error detected during the posix_spawn () or posix_spawnp () operations rather than during 28565 actual execution of the child process image; the second, WSPAWNERRNO, would have 28566 extracted the error value if WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group 28567 strongly opposed this because it would make a library implementation of posix_spawn () or 28568 posix_spawnp () dependent on kernel modifications to waitpid () to be able to embed special 28569 information in stat_val to indicate a spawn failure.
28570 The 8 bits of child process exit status that are guaranteed by IEEE Std 1003.1-2001 to be 28571 accessible to the waiting parent process are insufficient to disambiguate a spawn error from any 28572 other kind of error that may be returned by an arbitrary process image. No other bits of the exit 28573 status are required to be visible in stat_val, so these macros could not be strictly implemented at 28574 the library level. Reserving an exit status of 127 for such spawn errors is consistent with the use 28575 of this value by system () and popen () to signal failures in these operations that occur after the 28576 function has returned but before a shell is able to execute. The exit status of 127 does not 28577 uniquely identify this class of error, nor does it provide any detailed information on the nature 28578 of the failure. Note that a kernel implementation of posix_spawn () or posix_spawnp () is permitted 28579 (and encouraged) to return any possible error as the function value, thus providing more 28580 detailed failure information to the parent process.
28581 Thus, no special macros are available to isolate asynchronous posix_spawn () or posix_spawnp () 28582 errors. Instead, errors detected by the posix_spawn () or posix_spawnp () operations in the context 28583 of the child process before the new process image executes are reported by setting the child's 28584 exit status to 127. The calling process may use the WIFEXITED and WEXITSTATUS macros on 28585 the stat_val stored by the wait () or waitpid () functions to detect spawn failures to the extent that 28586 other status values with which the child process image may exit (before the parent can 28587 conclusively determine that the child process image has begun execution) are distinct from exit 28588 status 127.
28589 FUTURE DIRECTIONS 28590 None.
28591 SEE ALSO 28592 alarm (), chmod (), close (), dup (), exec , exit (), fcntl (), fork (), kill (), open (), 28593 posix_spawn_file_actions_addclose (), posix_spawn_file_actions_adddup2 (), 28594 posix_spawn_file_actions_addopen (), posix_spawn_file_actions_destroy (), <REFERENCE 28595 UNDEFINED>(posix_spawn_file_actions_init), posix_spawnattr_destroy (), posix_spawnattr_init (), 28596 posix_spawnattr_getsigdefault (), posix_spawnattr_getflags (), posix_spawnattr_getpgroup (), 28597 posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), posix_spawnattr_getsigmask (), 28598 posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), posix_spawnattr_setpgroup (), 28599 posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 28600 sched_setparam (), sched_setscheduler (), setpgid (), setuid (), stat (), times (), wait (), the Base 28601 Definitions volume of IEEE Std 1003.1-2001, < spawn.h>
28602 CHANGE HISTORY 28603 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28604 IEEE PASC Interpretation 1003.1 #103 is applied, noting that the signal default actions are 28605 changed as well as the signal mask in step 2.
28606 IEEE PASC Interpretation 1003.1 #132 is applied.
28607 NAME 28608 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen ” add close or open 28609 action to spawn file actions object (ADVANCED REALTIME)
28610 SYNOPSIS
28611 SPN #include <spawn.h> 28612 int posix_spawn_file_actions_addclose (posix_spawn_file_actions_t * 28613 file_actions, int fildes ); 28614 int posix_spawn_file_actions_addopen (posix_spawn_file_actions_t * 28615 restrict file_actions, int fildes, 28616 const char *restrict path, int oflag, mode_t mode );
28617
28618 DESCRIPTION 28619 These functions shall add or delete a close or open action to a spawn file actions object.
28620 A spawn file actions object is of type posix_spawn_file_actions_t (defined in < spawn.h>) and is 28621 used to specify a series of actions to be performed by a posix_spawn () or posix_spawnp () 28622 operation in order to arrive at the set of open file descriptors for the child process given the set of 28623 open file descriptors of the parent. IEEE Std 1003.1-2001 does not define comparison or 28624 assignment operators for the type posix_spawn_file_actions_t.
28625 A spawn file actions object, when passed to posix_spawn () or posix_spawnp (), shall specify how 28626 the set of open file descriptors in the calling process is transformed into a set of potentially open 28627 file descriptors for the spawned process. This transformation shall be as if the specified sequence 28628 of actions was performed exactly once, in the context of the spawned process (prior to execution 28629 of the new process image), in the order in which the actions were added to the object; 28630 additionally, when the new process image is executed, any file descriptor (from this new set) 28631 which has its FD_CLOEXEC flag set shall be closed (see posix_spawn ()).
28632 The posix_spawn_file_actions_addclose () function shall add a close action to the object referenced 28633 by file_actions that shall cause the file descriptor fildes to be closed (as if close ( fildes ) had been 28634 called) when a new process is spawned using this file actions object.
28635 The posix_spawn_file_actions_addopen () function shall add an open action to the object referenced 28636 by file_actions that shall cause the file named by path to be opened (as if open ( path, oflag, mode ) 28637 had been called, and the returned file descriptor, if not fildes , had been changed to fildes ) when a 28638 new process is spawned using this file actions object. If fildes was already an open file descriptor, 28639 it shall be closed before the new file is opened.
28640 The string described by path shall be copied by the posix_spawn_file_actions_addopen () function.
28641 RETURN VALUE 28642 Upon successful completion, these functions shall return zero; otherwise, an error number shall 28643 be returned to indicate the error.
28644 ERRORS 28645 These functions shall fail if:
28646 [EBADF] The value specified by fildes is negative or greater than or equal to 28647 {OPEN_MAX}.
28648 These functions may fail if:
28649 [EINVAL] The value specified by file_actions is invalid. 28650 [ENOMEM] Insufficient memory exists to add to the spawn file actions object.
28651 It shall not be considered an error for the fildes argument passed to these functions to specify a 28652 file descriptor for which the specified operation could not be performed at the time of the call. 28653 Any such error will be detected when the associated file actions object is later used during a 28654 posix_spawn () or posix_spawnp () operation.
28655 EXAMPLES 28656 None.
28657 APPLICATION USAGE 28658 These functions are part of the Spawn option and need not be provided on all implementations.
28659 RATIONALE 28660 A spawn file actions object may be initialized to contain an ordered sequence of close (), dup2 (), 28661 and open () operations to be used by posix_spawn () or posix_spawnp () to arrive at the set of open 28662 file descriptors inherited by the spawned process from the set of open file descriptors in the 28663 parent at the time of the posix_spawn () or posix_spawnp () call. It had been suggested that the 28664 close () and dup2 () operations alone are sufficient to rearrange file descriptors, and that files 28665 which need to be opened for use by the spawned process can be handled either by having the 28666 calling process open them before the posix_spawn () or posix_spawnp () call (and close them after), 28667 or by passing filenames to the spawned process (in argv ) so that it may open them itself. The 28668 standard developers recommend that applications use one of these two methods when practical, 28669 since detailed error status on a failed open operation is always available to the application this 28670 way. However, the standard developers feel that allowing a spawn file actions object to specify 28671 open operations is still appropriate because:
28672 1. It is consistent with equivalent POSIX.5 (Ada) functionality. 28673 2. It supports the I/O redirection paradigm commonly employed by POSIX programs 28674 designed to be invoked from a shell. When such a program is the child process, it may not 28675 be designed to open files on its own. 28676 3. It allows file opens that might otherwise fail or violate file ownership/access rights if 28677 executed by the parent process.
28678 Regarding 2. above, note that the spawn open file action provides to posix_spawn () and 28679 posix_spawnp () the same capability that the shell redirection operators provide to system (), only 28680 without the intervening execution of a shell; for example:
28681 system ("myprog <file1 3<file2");
28682 Regarding 3. above, note that if the calling process needs to open one or more files for access by 28683 the spawned process, but has insufficient spare file descriptors, then the open action is necessary 28684 to allow the open () to occur in the context of the child process after other file descriptors have 28685 been closed (that must remain open in the parent).
28686 Additionally, if a parent is executed from a file having a "set-user-id" mode bit set and the 28687 POSIX_SPAWN_RESETIDS flag is set in the spawn attributes, a file created within the parent 28688 process will (possibly incorrectly) have the parent's effective user ID as its owner, whereas a file 28689 created via an open () action during posix_spawn () or posix_spawnp () will have the parent's real 28690 ID as its owner; and an open by the parent process may successfully open a file to which the real 28691 user should not have access or fail to open a file to which the real user should have access.
28692 File Descriptor Mapping
28693 The standard developers had originally proposed using an array which specified the mapping of 28694 child file descriptors back to those of the parent. It was pointed out by the ballot group that it is 28695 not possible to reshuffle file descriptors arbitrarily in a library implementation of posix_spawn () 28696 or posix_spawnp () without provision for one or more spare file descriptor entries (which simply 28697 may not be available). Such an array requires that an implementation develop a complex 28698 strategy to achieve the desired mapping without inadvertently closing the wrong file descriptor 28699 at the wrong time.
28700 It was noted by a member of the Ada Language Bindings working group that the approved Ada 28701 Language Start_Process family of POSIX process primitives use a caller-specified set of file 28702 actions to alter the normal fork ()/ exec semantics for inheritance of file descriptors in a very 28703 flexible way, yet no such problems exist because the burden of determining how to achieve the 28704 final file descriptor mapping is completely on the application. Furthermore, although the file 28705 actions interface appears frightening at first glance, it is actually quite simple to implement in 28706 either a library or the kernel.
28707 FUTURE DIRECTIONS 28708 None.
28709 SEE ALSO 28710 close (), dup (), open (), posix_spawn (), posix_spawn_file_actions_adddup2 (), 28711 posix_spawn_file_actions_destroy (), posix_spawnp (), the Base Definitions volume of 28712 IEEE Std 1003.1-2001, < spawn.h>
28713 CHANGE HISTORY 28714 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28715 IEEE PASC Interpretation 1003.1 #105 is applied, adding a note to the DESCRIPTION that the 28716 string pointed to by path is copied by the posix_spawn_file_actions_addopen () function.
28717 NAME 28718 posix_spawn_file_actions_adddup2 ” add dup2 action to spawn file actions object 28719 (ADVANCED REALTIME)
28720 SYNOPSIS
28721 SPN #include <spawn.h> 28722 int posix_spawn_file_actions_adddup2 (posix_spawn_file_actions_t * 28723 file_actions, int fildes, int newfildes );
28724
28725 DESCRIPTION 28726 The posix_spawn_file_actions_adddup2 () function shall add a dup2 () action to the object 28727 referenced by file_actions that shall cause the file descriptor fildes to be duplicated as newfildes (as 28728 if dup2 ( fildes, newfildes ) had been called) when a new process is spawned using this file actions 28729 object.
28730 A spawn file actions object is as defined in posix_spawn_file_actions_addclose ().
28731 RETURN VALUE 28732 Upon successful completion, the posix_spawn_file_actions_adddup2 () function shall return zero; 28733 otherwise, an error number shall be returned to indicate the error.
28734 ERRORS 28735 The posix_spawn_file_actions_adddup2 () function shall fail if: 28736 [EBADF] The value specified by fildes or newfildes is negative or greater than or equal to 28737 {OPEN_MAX}. 28738 [ENOMEM] Insufficient memory exists to add to the spawn file actions object.
28739 The posix_spawn_file_actions_adddup2 () function may fail if:
28740 [EINVAL] The value specified by file_actions is invalid.
28741 It shall not be considered an error for the fildes argument passed to the 28742 posix_spawn_file_actions_adddup2 () function to specify a file descriptor for which the specified 28743 operation could not be performed at the time of the call. Any such error will be detected when 28744 the associated file actions object is later used during a posix_spawn () or posix_spawnp () 28745 operation.
28746 EXAMPLES 28747 None.
28748 APPLICATION USAGE 28749 The posix_spawn_file_actions_adddup2 () function is part of the Spawn option and need not be 28750 provided on all implementations.
28751 RATIONALE 28752 Refer to the RATIONALE in posix_spawn_file_actions_addclose ().
28753 FUTURE DIRECTIONS 28754 None.
28755 SEE ALSO 28756 dup (), posix_spawn (), posix_spawn_file_actions_addclose (), posix_spawn_file_actions_destroy (), 28757 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < spawn.h>
28758 CHANGE HISTORY 28759 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28760 IEEE PASC Interpretation 1003.1 #104 is applied, noting that the [EBADF] error can apply to the 28761 newfildes argument in addition to fildes .
28773 NAME 28774 posix_spawn_file_actions_destroy, posix_spawn_file_actions_init ” destroy and initialize 28775 spawn file actions object ( ADVANCED REALTIME )
28776 SYNOPSIS
28777 SPN #include <spawn.h> 28778 int posix_spawn_file_actions_destroy (posix_spawn_file_actions_t * 28779 file_actions); 28780 int posix_spawn_file_actions_init (posix_spawn_file_actions_t * 28781 file_actions);
28782
28783 DESCRIPTION 28784 The posix_spawn_file_actions_destroy () function shall destroy the object referenced by file_actions; 28785 the object becomes, in effect, uninitialized . An implementation may cause 28786 posix_spawn_file_actions_destroy () to set the object referenced by file_actions to an invalid value. A 28787 destroyed spawn file actions object can be reinitialized using posix_spawn_file_actions_init (); the 28788 results of otherwise referencing the object after it has been destroyed are undefined.
28789 The posix_spawn_file_actions_init () function shall initialize the object referenced by file_actions to 28790 contain no file actions for posix_spawn () or posix_spawnp () to perform.
28791 A spawn file actions object is as defined in posix_spawn_file_actions_addclose (). 28792 The effect of initializing an already initialized spawn file actions object is undefined.
28793 RETURN VALUE 28794 Upon successful completion, these functions shall return zero; otherwise, an error number shall 28795 be returned to indicate the error.
28796 ERRORS 28797 The posix_spawn_file_actions_init () function shall fail if:
28798 [ENOMEM] Insufficient memory exists to initialize the spawn file actions object. 28799 The posix_spawn_file_actions_destroy () function may fail if:
28800 [EINVAL] The value specified by file_actions is invalid.
28801 EXAMPLES 28802 None.
28803 APPLICATION USAGE 28804 These functions are part of the Spawn option and need not be provided on all implementations.
28805 RATIONALE 28806 Refer to the RATIONALE in posix_spawn_file_actions_addclose ().
28807 FUTURE DIRECTIONS 28808 None.
28809 SEE ALSO 28810 posix_spawn (), posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < spawn.h>
28811 CHANGE HISTORY 28812 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28813 In the SYNOPSIS, the inclusion of < sys/types.h> is no longer required.
28814 NAME 28815 posix_spawnattr_destroy, posix_spawnattr_init ”destroy and initialize spawn attributes object 28816 ( ADVANCED REALTIME )
28817 SYNOPSIS
28818 SPN #include <spawn.h> 28819 int posix_spawnattr_destroy (posix_spawnattr_t * attr ); 28820 int posix_spawnattr_init (posix_spawnattr_t * attr );
28821
28822 DESCRIPTION 28823 The posix_spawnattr_destroy () function shall destroy a spawn attributes object. A destroyed attr 28824 attributes object can be reinitialized using posix_spawnattr_init (); the results of otherwise 28825 referencing the object after it has been destroyed are undefined. An implementation may cause 28826 posix_spawnattr_destroy () to set the object referenced by attr to an invalid value.
28827 The posix_spawnattr_init () function shall initialize a spawn attributes object attr with the default 28828 value for all of the individual attributes used by the implementation. Results are undefined if 28829 posix_spawnattr_init () is called specifying an already initialized attr attributes object.
28830 A spawn attributes object is of type posix_spawnattr_t (defined in < spawn.h>) and is used to 28831 specify the inheritance of process attributes across a spawn operation. IEEE Std 1003.1-2001 does 28832 not define comparison or assignment operators for the type posix_spawnattr_t.
28833 Each implementation shall document the individual attributes it uses and their default values 28834 unless these values are defined by IEEE Std 1003.1-2001. Attributes not defined by 28835 IEEE Std 1003.1-2001, their default values, and the names of the associated functions to get and 28836 set those attribute values are implementation-defined.
28837 The resulting spawn attributes object (possibly modified by setting individual attribute values), 28838 is used to modify the behavior of posix_spawn () or posix_spawnp (). After a spawn attributes 28839 object has been used to spawn a process by a call to a posix_spawn () or posix_spawnp (), any 28840 function affecting the attributes object (including destruction) shall not affect any process that 28841 has been spawned in this way.
28842 RETURN VALUE 28843 Upon successful completion, posix_spawnattr_destroy () and posix_spawnattr_init () shall return 28844 zero; otherwise, an error number shall be returned to indicate the error.
28845 ERRORS 28846 The posix_spawnattr_init () function shall fail if:
28847 [ENOMEM] Insufficient memory exists to initialize the spawn attributes object.
28848 The posix_spawnattr_destroy () function may fail if:
28849 [EINVAL] The value specified by attr is invalid.
28850 EXAMPLES 28851 None.
28852 APPLICATION USAGE 28853 These functions are part of the Spawn option and need not be provided on all implementations.
28854 RATIONALE 28855 The original spawn interface proposed in IEEE Std 1003.1-2001 defined the attributes that specify 28856 the inheritance of process attributes across a spawn operation as a structure. In order to be able 28857 to separate optional individual attributes under their appropriate options (that is, the spawn- 28858 schedparam and spawn-schedpolicy attributes depending upon the Process Scheduling option), and 28859 also for extensibility and consistency with the newer POSIX interfaces, the attributes interface 28860 has been changed to an opaque data type. This interface now consists of the type 28861 posix_spawnattr_t, representing a spawn attributes object, together with associated functions to 28862 initialize or destroy the attributes object, and to set or get each individual attribute. Although the 28863 new object-oriented interface is more verbose than the original structure, it is simple to use, 28864 more extensible, and easy to implement.
28865 FUTURE DIRECTIONS 28866 None.
28867 SEE ALSO 28868 posix_spawn (), posix_spawnattr_getsigdefault (), posix_spawnattr_getflags (), 28869 posix_spawnattr_getpgroup (), posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), 28870 posix_spawnattr_getsigmask (), posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), 28871 posix_spawnattr_setpgroup (), posix_spawnattr_setsigmask (), posix_spawnattr_setschedpolicy (), 28872 posix_spawnattr_setschedparam (), posix_spawnp (), the Base Definitions volume of 28873 IEEE Std 1003.1-2001, < spawn.h>
28874 CHANGE HISTORY 28875 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28876 IEEE PASC Interpretation 1003.1 #106 is applied, noting that the effect of initializing an already 28877 initialized spawn attributes option is undefined.
28878 NAME 28879 posix_spawnattr_getflags, posix_spawnattr_setflags ” get and set the spawn-flags attribute of a 28880 spawn attributes object (ADVANCED REALTIME)
28881 SYNOPSIS
28882 SPN #include <spawn.h> 28883 int posix_spawnattr_getflags (const posix_spawnattr_t *restrict attr, 28884 short *restrict flags ); 28885 int posix_spawnattr_setflags (posix_spawnattr_t * attr, short flags );
28886
28887 DESCRIPTION 28888 The posix_spawnattr_getflags () function shall obtain the value of the spawn-flags attribute from 28889 the attributes object referenced by attr .
28890 The posix_spawnattr_setflags () function shall set the spawn-flags attribute in an initialized 28891 attributes object referenced by attr .
28892 The spawn-flags attribute is used to indicate which process attributes are to be changed in the 28893 new process image when invoking posix_spawn () or posix_spawnp (). It is the bitwise-inclusive 28894 OR of zero or more of the following flags:
28895 POSIX_SPAWN_RESETIDS 28896 POSIX_SPAWN_SETPGROUP 28897 POSIX_SPAWN_SETSIGDEF 28898 POSIX_SPAWN_SETSIGMASK 28899 PS POSIX_SPAWN_SETSCHEDPARAM 28900 POSIX_SPAWN_SETSCHEDULER 28901
28902 These flags are defined in < spawn.h>. The default value of this attribute shall be as if no flags 28903 were set.
28904 RETURN VALUE 28905 Upon successful completion, posix_spawnattr_getflags () shall return zero and store the value of 28906 the spawn-flags attribute of attr into the object referenced by the flags parameter; otherwise, an 28907 error number shall be returned to indicate the error.
28908 Upon successful completion, posix_spawnattr_setflags () shall return zero; otherwise, an error 28909 number shall be returned to indicate the error.
28910 ERRORS 28911 These functions may fail if:
28912 [EINVAL] The value specified by attr is invalid.
28913 The posix_spawnattr_setflags () function may fail if:
28914 [EINVAL] The value of the attribute being set is not valid.
28915 EXAMPLES 28916 None.
28917 APPLICATION USAGE 28918 These functions are part of the Spawn option and need not be provided on all implementations.
28919 RATIONALE 28920 None.
28921 FUTURE DIRECTIONS 28922 None.
28923 SEE ALSO 28924 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getsigdefault (), 28925 posix_spawnattr_getpgroup (), posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), 28926 posix_spawnattr_getsigmask (), posix_spawnattr_setsigdefault (), posix_spawnattr_setpgroup (), 28927 posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 28928 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < spawn.h>
28929 CHANGE HISTORY 28930 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28931 NAME 28932 posix_spawnattr_getpgroup, posix_spawnattr_setpgroup ” get and set the spawn-pgroup 28933 attribute of a spawn attributes object (ADVANCED REALTIME)
28934 SYNOPSIS
28935 SPN #include <spawn.h> 28936 int posix_spawnattr_getpgroup (const posix_spawnattr_t *restrict attr, 28937 pid_t *restrict pgroup ); 28938 int posix_spawnattr_setpgroup (posix_spawnattr_t * attr, pid_t pgroup );
28939
28940 DESCRIPTION 28941 The posix_spawnattr_getpgroup () function shall obtain the value of the spawn-pgroup attribute 28942 from the attributes object referenced by attr .
28943 The posix_spawnattr_setpgroup () function shall set the spawn-pgroup attribute in an initialized 28944 attributes object referenced by attr .
28945 The spawn-pgroup attribute represents the process group to be joined by the new process image 28946 in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute). The 28947 default value of this attribute shall be zero.
28948 RETURN VALUE 28949 Upon successful completion, posix_spawnattr_getpgroup () shall return zero and store the value of 28950 the spawn-pgroup attribute of attr into the object referenced by the pgroup parameter; otherwise, 28951 an error number shall be returned to indicate the error.
28952 Upon successful completion, posix_spawnattr_setpgroup () shall return zero; otherwise, an error 28953 number shall be returned to indicate the error.
28954 ERRORS 28955 These functions may fail if:
28956 [EINVAL] The value specified by attr is invalid. 28957 The posix_spawnattr_setpgroup () function may fail if: 28958 [EINVAL] The value of the attribute being set is not valid.
28959 EXAMPLES 28960 None.
28961 APPLICATION USAGE 28962 These functions are part of the Spawn option and need not be provided on all implementations.
28963 RATIONALE 28964 None.
28965 FUTURE DIRECTIONS 28966 None.
28967 SEE ALSO 28968 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getsigdefault (), 28969 posix_spawnattr_getflags (), posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), 28970 posix_spawnattr_getsigmask (), posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), 28971 posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 28972 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < spawn.h>
28973 CHANGE HISTORY 28974 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
28975 NAME 28976 posix_spawnattr_getschedparam, posix_spawnattr_setschedparam ” get and set the spawn- 28977 schedparam attribute of a spawn attributes object ( ADVANCED REALTIME )
28978 SYNOPSIS
28979 SPN PS #include <spawn.h> 28980 #include <sched.h> 28981 int posix_spawnattr_getschedparam (const posix_spawnattr_t * 28982 restrict attr, struct sched_param *restrict schedparam ); 28983 int posix_spawnattr_setschedparam (posix_spawnattr_t *restrict attr, 28984 const struct sched_param *restrict schedparam );
28985
28986 DESCRIPTION 28987 The posix_spawnattr_getschedparam () function shall obtain the value of the spawn-schedparam 28988 attribute from the attributes object referenced by attr .
28989 The posix_spawnattr_setschedparam () function shall set the spawn-schedparam attribute in an 28990 initialized attributes object referenced by attr .
28991 The spawn-schedparam attribute represents the scheduling parameters to be assigned to the new 28992 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or 28993 POSIX_SPAWN_SETSCHEDPARAM is set in the spawn-flags attribute). The default value of this 28994 attribute is unspecified.
28995 RETURN VALUE 28996 Upon successful completion, posix_spawnattr_getschedparam () shall return zero and store the 28997 value of the spawn-schedparam attribute of attr into the object referenced by the schedparam 28998 parameter; otherwise, an error number shall be returned to indicate the error.
28999 Upon successful completion, posix_spawnattr_setschedparam () shall return zero; otherwise, an 29000 error number shall be returned to indicate the error.
29001 ERRORS 29002 These functions may fail if: 29003 [EINVAL] The value specified by attr is invalid. 29004 The posix_spawnattr_setschedparam () function may fail if: 29005 [EINVAL] The value of the attribute being set is not valid.
29006 EXAMPLES 29007 None.
29008 APPLICATION USAGE 29009 These functions are part of the Spawn and Process Scheduling options and need not be provided 29010 on all implementations.
29011 RATIONALE 29012 None.
29013 FUTURE DIRECTIONS 29014 None.
29015 SEE ALSO 29016 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getsigdefault (), 29017 posix_spawnattr_getflags (), posix_spawnattr_getpgroup (), posix_spawnattr_getschedpolicy (), 29018 posix_spawnattr_getsigmask (), posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), 29019 posix_spawnattr_setpgroup (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 29020 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, <sched.h>, <spawn.h>
29021 CHANGE HISTORY 29022 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
29023 NAME 29024 posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy ” get and set the spawn-schedpolicy 29025 attribute of a spawn attributes object ( ADVANCED REALTIME )
29026 SYNOPSIS
29027 SPN #include <spawn.h> 29028 #include <sched.h> 29029 int posix_spawnattr_getschedpolicy (const posix_spawnattr_t * 29030 restrict attr , int *restrict schedpolicy ); 29031 int posix_spawnattr_setschedpolicy (posix_spawnattr_t * attr, 29032 int schedpolicy ).;
29033
29034 DESCRIPTION 29035 The posix_spawnattr_getschedpolicy () function shall obtain the value of the spawn-schedpolicy 29036 attribute from the attributes object referenced by attr .
29037 The posix_spawnattr_setschedpolicy () function shall set the spawn-schedpolicy attribute in an 29038 initialized attributes object referenced by attr .
29039 The spawn-schedpolicy attribute represents the scheduling policy to be assigned to the new 29040 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags 29041 attribute). The default value of this attribute is unspecified.
29042 RETURN VALUE 29043 Upon successful completion, posix_spawnattr_getschedpolicy () shall return zero and store the 29044 value of the spawn-schedpolicy attribute of attr into the object referenced by the schedpolicy 29045 parameter; otherwise, an error number shall be returned to indicate the error.
29046 Upon successful completion, posix_spawnattr_setschedpolicy () shall return zero; otherwise, an 29047 error number shall be returned to indicate the error.
29048 ERRORS 29049 These functions may fail if: 29050 [EINVAL] The value specified by attr is invalid. 29051 The posix_spawnattr_setschedpolicy () function may fail if: 29052 [EINVAL] The value of the attribute being set is not valid.
29053 EXAMPLES 29054 None.
29055 APPLICATION USAGE 29056 These functions are part of the Spawn and Process Scheduling options and need not be provided 29057 on all implementations.
29058 RATIONALE 29059 None.
29060 FUTURE DIRECTIONS 29061 None.
29062 SEE ALSO 29063 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getsigdefault (), 29064 posix_spawnattr_getflags (), posix_spawnattr_getpgroup (), posix_spawnattr_getschedparam (), 29065 posix_spawnattr_getsigmask (), posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), 29066 posix_spawnattr_setpgroup (), posix_spawnattr_setschedparam (), posix_spawnattr_setsigmask (), 29067 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < sched.h>, < spawn.h>
29068 CHANGE HISTORY 29069 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
29070 NAME 29071 posix_spawnattr_getsigdefault, posix_spawnattr_setsigdefault ” get and set the spawn-sigdefault 29072 attribute of a spawn attributes object ( ADVANCED REALTIME )
29073 SYNOPSIS
29074 SPN #include <signal.h> 29075 #include <spawn.h> 29076 int posix_spawnattr_getsigdefault (const posix_spawnattr_t * 29077 restrict attr, sigset_t *restrict sigdefault ); 29078 int posix_spawnattr_setsigdefault (posix_spawnattr_t *restrict attr, 29079 const sigset_t *restrict sigdefault );
29080
29081 DESCRIPTION 29082 The posix_spawnattr_getsigdefault () function shall obtain the value of the spawn-sigdefault 29083 attribute from the attributes object referenced by attr .
29084 The posix_spawnattr_setsigdefault () function shall set the spawn-sigdefault attribute in an 29085 initialized attributes object referenced by attr .
29086 The spawn-sigdefault attribute represents the set of signals to be forced to default signal handling 29087 in the new process image (if POSIX_SPAWN_SETSIGDEF is set in the spawn-flags attribute) by a 29088 spawn operation. The default value of this attribute shall be an empty signal set.
29089 RETURN VALUE 29090 Upon successful completion, posix_spawnattr_getsigdefault () shall return zero and store the value 29091 of the spawn-sigdefault attribute of attr into the object referenced by the sigdefault parameter; 29092 otherwise, an error number shall be returned to indicate the error.
29093 Upon successful completion, posix_spawnattr_setsigdefault () shall return zero; otherwise, an error 29094 number shall be returned to indicate the error.
29095 ERRORS 29096 These functions may fail if:
29097 [EINVAL] The value specified by attr is invalid. 29098 The posix_spawnattr_setsigdefault () function may fail if: 29099 [EINVAL] The value of the attribute being set is not valid.
29100 EXAMPLES 29101 None.
29102 APPLICATION USAGE 29103 These functions are part of the Spawn option and need not be provided on all implementations.
29104 RATIONALE 29105 None.
29106 FUTURE DIRECTIONS 29107 None.
29108 SEE ALSO 29109 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getflags (), 29110 posix_spawnattr_getpgroup (), posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), 29111 posix_spawnattr_getsigmask (), posix_spawnattr_setflags (), posix_spawnattr_setpgroup (), 29112 posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 29113 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < signal.h >, < spawn.h >
29114 CHANGE HISTORY 29115 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
29116 NAME 29117 posix_spawnattr_getsigmask, posix_spawnattr_setsigmask ”get and set the spawn-sigmask 29118 attribute of a spawn attributes object ( ADVANCED REALTIME )
29119 SYNOPSIS
29120 SPN #include <signal.h> 29121 #include <spawn.h> 29122 int posix_spawnattr_getsigmask (const posix_spawnattr_t *restrict attr, 29123 sigset_t *restrict sigmask ); 29124 int posix_spawnattr_setsigmask (posix_spawnattr_t *restrict attr, 29125 const sigset_t *restrict sigmask );
29126
29127 DESCRIPTION 29128 The posix_spawnattr_getsigmask () function shall obtain the value of the spawn-sigmask attribute 29129 from the attributes object referenced by attr .
29130 The posix_spawnattr_setsigmask () function shall set the spawn-sigmask attribute in an initialized 29131 attributes object referenced by attr .
29132 The spawn-sigmask attribute represents the signal mask in effect in the new process image of a 29133 spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the spawn-flags attribute). The 29134 default value of this attribute is unspecified.
29135 RETURN VALUE 29136 Upon successful completion, posix_spawnattr_getsigmask () shall return zero and store the value 29137 of the spawn-sigmask attribute of attr into the object referenced by the sigmask parameter; 29138 otherwise, an error number shall be returned to indicate the error.
29139 Upon successful completion, posix_spawnattr_setsigmask () shall return zero; otherwise, an error 29140 number shall be returned to indicate the error.
29141 ERRORS 29142 These functions may fail if:
29143 [EINVAL] The value specified by attr is invalid.
29144 The posix_spawnattr_setsigmask () function may fail if:
29145 [EINVAL] The value of the attribute being set is not valid.
29146 EXAMPLES 29147 None.
29148 APPLICATION USAGE 29149 These functions are part of the Spawn option and need not be provided on all implementations.
29150 RATIONALE 29151 None.
29152 FUTURE DIRECTIONS 29153 None.
29154 SEE ALSO 29155 posix_spawn (), posix_spawnattr_destroy (), posix_spawnattr_init (), posix_spawnattr_getsigdefault (), 29156 posix_spawnattr_getflags (), posix_spawnattr_getpgroup (), posix_spawnattr_getschedparam (), 29157 posix_spawnattr_getschedpolicy (), posix_spawnattr_setsigdefault (), posix_spawnattr_setflags (), 29158 posix_spawnattr_setpgroup (), posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy (), 29159 posix_spawnp (), the Base Definitions volume of IEEE Std 1003.1-2001, < signal.h>, < spawn.h >
29160 CHANGE HISTORY 29161 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
31104 NAME 31105 pthread_attr_destroy, pthread_attr_init ” destroy and initialize the thread attributes object
31106 SYNOPSIS
31107 THR #include <pthread.h> 31108 int pthread_attr_destroy (pthread_attr_t * attr ); 31109 int pthread_attr_init (pthread_attr_t * attr );
31110
31111 DESCRIPTION 31112 The pthread_attr_destroy () function shall destroy a thread attributes object. An implementation 31113 may cause pthread_attr_destroy () to set attr to an implementation-defined invalid value. A 31114 destroyed attr attributes object can be reinitialized using pthread_attr_init (); the results of 31115 otherwise referencing the object after it has been destroyed are undefined.
31116 The pthread_attr_init () function shall initialize a thread attributes object attr with the default 31117 value for all of the individual attributes used by a given implementation.
31118 The resulting attributes object (possibly modified by setting individual attribute values) when 31119 used by pthread_create () defines the attributes of the thread created. A single attributes object can 31120 be used in multiple simultaneous calls to pthread_create (). Results are undefined if 31121 pthread_attr_init () is called specifying an already initialized attr attributes object.
31122 RETURN VALUE 31123 Upon successful completion, pthread_attr_destroy () and pthread_attr_init () shall return a value of 31124 0; otherwise, an error number shall be returned to indicate the error.
31125 ERRORS
31126 The pthread_attr_init () function shall fail if:
31127 [ENOMEM] Insufficient memory exists to initialize the thread attributes object.
31128 These functions shall not return an error code of [EINTR].
31129 EXAMPLES 31130 None.
31131 APPLICATION USAGE 31132 None.
31133 RATIONALE 31134 Attributes objects are provided for threads, mutexes , and condition variables as a mechanism to 31135 support probable future standardization in these areas without requiring that the function itself 31136 be changed.
31137 Attributes objects provide clean isolation of the configurable aspects of threads. For example, 31138 "stack size" is an important attribute of a thread, but it cannot be expressed portably. When 31139 porting a threaded program, stack sizes often need to be adjusted. The use of attributes objects 31140 can help by allowing the changes to be isolated in a single place, rather than being spread across 31141 every instance of thread creation.
31142 Attributes objects can be used to set up "classes' of threads with similar attributes; for example, 31143 "threads with large stacks and high priority" or "threads with minimal stacks". These classes 31144 can be defined in a single place and then referenced wherever threads need to be created. 31145 Changes to "class" decisions become straightforward, and detailed analysis of each 31146 pthread_create () call is not required.
31147 The attributes objects are defined as opaque types as an aid to extensibility. If these objects had 31148 been specified as structures, adding new attributes would force recompilation of all multi-threaded 31149 programs when the attributes objects are extended; this might not be possible if 31150 different program components were supplied by different vendors .
31151 Additionally, opaque attributes objects present opportunities for improving performance. 31152 Argument validity can be checked once when attributes are set, rather than each time a thread is 31153 created. Implementations often need to cache kernel objects that are expensive to create. 31154 Opaque attributes objects provide an efficient mechanism to detect when cached objects become 31155 invalid due to attribute changes.
31156 Since assignment is not necessarily defined on a given opaque type, implementation-defined 31157 default values cannot be defined in a portable way. The solution to this problem is to allow 31158 attributes objects to be initialized dynamically by attributes object initialization functions, so 31159 that default values can be supplied automatically by the implementation.
31160 The following proposal was provided as a suggested alternative to the supplied attributes:
31161 1. Maintain the style of passing a parameter formed by the bitwise-inclusive OR of flags to 31162 the initialization routines ( pthread_create (), pthread_mutex_init (), pthread_cond_init ()). The 31163 parameter containing the flags should be an opaque type for extensibility. If no flags are 31164 set in the parameter, then the objects are created with default characteristics. An 31165 implementation may specify implementation-defined flag values and associated behavior.
31166 2. If further specialization of mutexes and condition variables is necessary, implementations 31167 may specify additional procedures that operate on the pthread_mutex_t and 31168 pthread_cond_t objects (instead of on attributes objects).
31169 The difficulties with this solution are:
31170 1. A bitmask is not opaque if bits have to be set into bitvector attributes objects using 31171 explicitly-coded bitwise-inclusive OR operations. If the set of options exceeds an int , 31172 application programmers need to know the location of each bit. If bits are set or read by 31173 encapsulation (that is, get and set functions), then the bitmask is merely an 31174 implementation of attributes objects as currently defined and should not be exposed to the 31175 programmer.
31176 2. Many attributes are not Boolean or very small integral values. For example, scheduling 31177 policy may be placed in 3-bit or 4-bit, but priority requires 5-bit or more, thereby taking up 31178 at least 8 bits out of a possible 16 bits on machines with 16-bit integers. Because of this, the 31179 bitmask can only reasonably control whether particular attributes are set or not, and it 31180 cannot serve as the repository of the value itself. The value needs to be specified as a 31181 function parameter (which is non-extensible), or by setting a structure field (which is non- 31182 opaque), or by get and set functions (making the bitmask a redundant addition to the 31183 attributes objects).
31184 Stack size is defined as an optional attribute because the very notion of a stack is inherently 31185 machine-dependent . Some implementations may not be able to change the size of the stack, for 31186 example, and others may not need to because stack pages may be discontiguous and can be 31187 allocated and released on demand.
31188 The attribute mechanism has been designed in large measure for extensibility. Future extensions 31189 to the attribute mechanism or to any attributes object defined in this volume of 31190 IEEE Std 1003.1-2001 has to be done with care so as not to affect binary-compatibility.
31191 Attributes objects, even if allocated by means of dynamic allocation functions such as malloc (), 31192 may have their size fixed at compile time. This means, for example, a pthread_create () in an 31193 implementation with extensions to pthread_attr_t cannot look beyond the area that the binary 31194 application assumes is valid. This suggests that implementations should maintain a size field in 31195 the attributes object, as well as possibly version information, if extensions in different directions 31196 (possibly by different vendors) are to be accommodated.
31197 FUTURE DIRECTIONS 31198 None.
31199 SEE ALSO 31200 pthread_attr_getstackaddr (), pthread_attr_getstacksize (), pthread_attr_getdetachstate (), 31201 pthread_create (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h >
31202 CHANGE HISTORY 31203 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
31204 Issue 6 31205 The pthread_attr_destroy () and pthread_attr_init () functions are marked as part of the Threads 31206 option.
31207 IEEE PASC Interpretation 1003.1 #107 is applied, noting that the effect of initializing an already 31208 initialized thread attributes object is undefined.
31209 NAME 31210 pthread_attr_getdetachstate, pthread_attr_setdetachstate ” get and set the detachstate attribute
31211 SYNOPSIS
31212 THR #include <pthread.h> 31213 int pthread_attr_getdetachstate (const pthread_attr_t * attr, 31214 int * detachstate ); 31215 int pthread_attr_setdetachstate (pthread_attr_t * attr, int detachstate );
31216
31217 DESCRIPTION 31218 The detachstate attribute controls whether the thread is created in a detached state. If the thread 31219 is created detached, then use of the ID of the newly created thread by the pthread_detach () or 31220 pthread_join () function is an error.
31221 The pthread_attr_getdetachstate () and pthread_attr_setdetachstate () functions, respectively, shall 31222 get and set the detachstate attribute in the attr object.
31223 For pthread_attr_getdetachstate (), detachstate shall be set to either 31224 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
31225 For pthread_attr_setdetachstate (), the application shall set detachstate to either 31226 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
31227 A value of PTHREAD_CREATE_DETACHED shall cause all threads created with attr to be in 31228 the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE shall cause all 31229 threads created with attr to be in the joinable state. The default value of the detachstate attribute 31230 shall be PTHREAD_CREATE_JOINABLE.
31231 RETURN VALUE 31232 Upon successful completion, pthread_attr_getdetachstate () and pthread_attr_setdetachstate () shall 31233 return a value of 0; otherwise, an error number shall be returned to indicate the error.
31234 The pthread_attr_getdetachstate () function stores the value of the detachstate attribute in detachstate 31235 if successful.
31236 ERRORS 31237 The pthread_attr_setdetachstate () function shall fail if:
31238 [EINVAL] The value of detachstate was not valid
31239 These functions shall not return an error code of [EINTR].
31240 EXAMPLES 31241 None.
31242 APPLICATION USAGE 31243 None.
31244 RATIONALE 31245 None.
31246 FUTURE DIRECTIONS 31247 None.
31248 SEE ALSO 31249 pthread_attr_destroy (), pthread_attr_getstackaddr (), pthread_attr_getstacksize (), pthread_create (), the 31250 Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h >
31251 CHANGE HISTORY 31252 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
31253 Issue 6 31254 The pthread_attr_setdetachstate () and pthread_attr_getdetachstate () functions are marked as part of 31255 the Threads option. 31256 The DESCRIPTION is updated to avoid use of the term "must" for application requirements.
31257 NAME 31258 pthread_attr_getguardsize, pthread_attr_setguardsize ” get and set the thread guardsize 31259 attribute
31260 SYNOPSIS
31261 XSI #include <pthread.h> 31262 int pthread_attr_getguardsize (const pthread_attr_t *restrict attr, 31263 size_t *restrict guardsize ); 31264 int pthread_attr_setguardsize (pthread_attr_t * attr, 31265 size_t guardsize );
31266
31267 DESCRIPTION 31268 The pthread_attr_getguardsize () function shall get the guardsize attribute in the attr object. This 31269 attribute shall be returned in the guardsize parameter.
31270 The pthread_attr_setguardsize () function shall set the guardsize attribute in the attr object. The new 31271 value of this attribute shall be obtained from the guardsize parameter. If guardsize is zero, a guard 31272 area shall not be provided for threads created with attr . If guardsize is greater than zero, a guard 31273 area of at least size guardsize bytes shall be provided for each thread created with attr .
31274 The guardsize attribute controls the size of the guard area for the created thread's stack. The 31275 guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is 31276 created with guard protection, the implementation allocates extra memory at the overflow end 31277 of the stack as a buffer against stack overflow of the stack pointer. If an application overflows 31278 into this buffer an error shall result (possibly in a SIGSEGV signal being delivered to the thread).
31279 A conforming implementation may round up the value contained in guardsize to a multiple of 31280 the configurable system variable {PAGESIZE} (see < sys/mman.h>). If an implementation 31281 rounds up the value of guardsize to a multiple of {PAGESIZE}, a call to pthread_attr_getguardsize () 31282 specifying attr shall store in the guardsize parameter the guard size specified by the previous 31283 pthread_attr_setguardsize () function call.
31284 The default value of the guardsize attribute is {PAGESIZE} bytes. The actual value of {PAGESIZE} 31285 is implementation-defined.
31286 If the stackaddr or stack attribute has been set (that is, the caller is allocating and managing its 31287 own thread stacks), the guardsize attribute shall be ignored and no protection shall be provided 31288 by the implementation. It is the responsibility of the application to manage stack overflow along 31289 with stack allocation and management in this case.
31290 RETURN VALUE 31291 If successful, the pthread_attr_getguardsize () and pthread_attr_setguardsize () functions shall return 31292 zero; otherwise, an error number shall be returned to indicate the error.
31293 ERRORS 31294 The pthread_attr_getguardsize () and pthread_attr_setguardsize () functions shall fail if:
31295 [EINVAL] The attribute attr is invalid.
31296 [EINVAL] The parameter guardsize is invalid.
31297 These functions shall not return an error code of [EINTR].
31298 EXAMPLES 31299 None.
31300 APPLICATION USAGE 31301 None.
31302 RATIONALE 31303 The guardsize attribute is provided to the application for two reasons:
31304 1. Overflow protection can potentially result in wasted system resources. An application 31305 that creates a large number of threads, and which knows its threads never overflow their 31306 stack, can save system resources by turning off guard areas.
31307 2. When threads allocate large data structures on the stack, large guard areas may be needed 31308 to detect stack overflow.
31309 FUTURE DIRECTIONS 31310 None.
31311 SEE ALSO 31312 The Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h >, < sys/mman.h >
31313 CHANGE HISTORY 31314 First released in Issue 5.
31315 Issue 6 31316 In the ERRORS section, a third [EINVAL] error condition is removed as it is covered by the 31317 second error condition.
31318 The restrict keyword is added to the pthread_attr_getguardsize () prototype for alignment with the 31319 ISO/IEC 9899: 1999 standard.
31320 NAME 31321 pthread_attr_getinheritsched, pthread_attr_setinheritsched ” get and set the inheritsched 31322 attribute ( REALTIME THREADS )
31323 SYNOPSIS 31324 THR TPS #include <pthread.h>
31325 int pthread_attr_getinheritsched (const pthread_attr_t *restrict attr, 31326 int *restrict inheritsched ); 31327 int pthread_attr_setinheritsched (pthread_attr_t * attr, 31328 int inheritsched );
31329
31330 DESCRIPTION 31331 The pthread_attr_getinheritsched (), and pthread_attr_setinheritsched () functions, respectively, shall 31332 get and set the inheritsched attribute in the attr argument.
31333 When the attributes objects are used by pthread_create (), the inheritsched attribute determines 31334 how the other scheduling attributes of the created thread shall be set.
31335 PTHREAD_INHERIT_SCHED 31336 Specifies that the thread scheduling attributes shall be inherited from the creating thread, 31337 and the scheduling attributes in this attr argument shall be ignored.
31338 PTHREAD_EXPLICIT_SCHED 31339 Specifies that the thread scheduling attributes shall be set to the corresponding values from 31340 this attributes object.
31341 The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined in 31342 the < pthread.h > header.
31343 The following thread scheduling attributes defined by IEEE Std 1003.1-2001 are affected by the 31344 inheritsched attribute: scheduling policy ( schedpolicy ), scheduling parameters ( schedparam ), and 31345 scheduling contention scope ( contentionscope ).
31346 RETURN VALUE 31347 If successful, the pthread_attr_getinheritsched () and pthread_attr_setinheritsched () functions shall 31348 return zero; otherwise, an error number shall be returned to indicate the error.
31349 ERRORS 31350 The pthread_attr_setinheritsched () function may fail if:
31351 [EINVAL] The value of inheritsched is not valid.
31352 [ENOTSUP] An attempt was made to set the attribute to an unsupported value.
31353 These functions shall not return an error code of [EINTR].
31354 EXAMPLES 31355 None.
31356 APPLICATION USAGE 31357 After these attributes have been set, a thread can be created with the specified attributes using 31358 pthread_create (). Using these routines does not affect the current running thread.
31359 RATIONALE 31360 None.
31361 FUTURE DIRECTIONS 31362 None.
31363 SEE ALSO 31364 pthread_attr_destroy (), pthread_attr_getscope (), pthread_attr_getschedpolicy (), 31365 pthread_attr_getschedparam (), pthread_create (), the Base Definitions volume of 31366 IEEE Std 1003.1-2001, < pthread.h>, < sched.h >
31367 CHANGE HISTORY 31368 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
31369 Marked as part of the Realtime Threads Feature Group.
31370 Issue 6 31371 The pthread_attr_getinheritsched () and pthread_attr_setinheritsched () functions are marked as part 31372 of the Threads and Thread Execution Scheduling options.
31373 The [ENOSYS] error condition has been removed as stubs need not be provided if an 31374 implementation does not support the Thread Execution Scheduling option.
31375 The restrict keyword is added to the pthread_attr_getinheritsched () prototype for alignment with 31376 the ISO/IEC 9899: 1999 standard.
31377 NAME 31378 pthread_attr_getschedparam, pthread_attr_setschedparam ” get and set the schedparam 31379 attribute
31380 SYNOPSIS
31381 THR #include <pthread.h> 31382 int pthread_attr_getschedparam (const pthread_attr_t *restrict attr, 31383 struct sched_param *restrict param ); 31384 int pthread_attr_setschedparam (pthread_attr_t *restrict attr , 31385 const struct sched_param *restrict param );
31386
31387 DESCRIPTION 31388 The pthread_attr_getschedparam (), and pthread_attr_setschedparam () functions, respectively, shall 31389 get and set the scheduling parameter attributes in the attr argument. The contents of the param 31390 structure are defined in the < sched.h > header. For the SCHED_FIFO and SCHED_RR policies, 31391 the only required member of param is sched_priority.
31392 TSP For the SCHED_SPORADIC policy, the required members of the param structure are 31393 sched_priority , sched_ss_low_priority , sched_ss_repl_period , sched_ss_init_budget , and 31394 sched_ss_max_repl. The specified sched_ss_repl_period must be greater than or equal to the 31395 specified sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. 31396 The value of sched_ss_max_repl shall be within the inclusive range [1.{SS_REPL_MAX}] for the 31397 function to succeed; if not, the function shall fail.
31398 RETURN VALUE 31399 If successful, the pthread_attr_getschedparam () and pthread_attr_setschedparam () functions shall 31400 return zero; otherwise, an error number shall be returned to indicate the error.
31401 ERRORS 31402 The pthread_attr_setschedparam () function may fail if:
31403 [EINVAL] The value of param is not valid.
31404 [ENOTSUP] An attempt was made to set the attribute to an unsupported value.
31405 These functions shall not return an error code of [EINTR].
31406 EXAMPLES 31407 None.
31408 APPLICATION USAGE 31409 After these attributes have been set, a thread can be created with the specified attributes using 31410 pthread_create (). Using these routines does not affect the current running thread.
31411 RATIONALE 31412 None.
31413 FUTURE DIRECTIONS 31414 None.
31415 SEE ALSO 31416 pthread_attr_destroy (), pthread_attr_getscope (), pthread_attr_getinheritsched (), 31417 pthread_attr_getschedpolicy (), pthread_create (), the Base Definitions volume of 31418 IEEE Std 1003.1-2001, < pthread.h>, < sched.h >
31419 CHANGE HISTORY 31420 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
31421 Issue 6 31422 The pthread_attr_getschedparam () and pthread_attr_setschedparam () functions are marked as part 31423 of the Threads option.
31424 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999.
31425 The restrict keyword is added to the pthread_attr_getschedparam () and 31426 pthread_attr_setschedparam () prototypes for alignment with the ISO/IEC 9899: 1999 standard.
31427 NAME 31428 pthread_attr_getschedpolicy, pthread_attr_setschedpolicy ” get and set the schedpolicy 31429 attribute ( REALTIME THREADS )
31430 SYNOPSIS
31431 THR TPS #include <pthread.h> 31432 int pthread_attr_getschedpolicy (const pthread_attr_t *restrict attr, 31433 int *restrict policy ); 31434 int pthread_attr_setschedpolicy (pthread_attr_t * attr , int policy );
31435
31436 DESCRIPTION 31437 The pthread_attr_getschedpolicy () and pthread_attr_setschedpolicy () functions, respectively, shall 31438 get and set the schedpolicy attribute in the attr argument.
31439 The supported values of policy shall include SCHED_FIFO, SCHED_RR, and SCHED_OTHER, 31440 which are defined in the < sched.h > header. When threads executing with the scheduling policy 31441 TSP SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC are waiting on a mutex, they shall acquire 31442 the mutex in priority order when the mutex is unlocked.
31443 RETURN VALUE 31444 If successful, the pthread_attr_getschedpolicy () and pthread_attr_setschedpolicy () functions shall 31445 return zero; otherwise, an error number shall be returned to indicate the error.
31446 ERRORS 31447 The pthread_attr_setschedpolicy () function may fail if:
31448 [EINVAL] The value of policy is not valid.
31449 [ENOTSUP] An attempt was made to set the attribute to an unsupported value.
31450 These functions shall not return an error code of [EINTR].
31451 EXAMPLES 31452 None.
31453 APPLICATION USAGE 31454 After these attributes have been set, a thread can be created with the specified attributes using 31455 pthread_create (). Using these routines does not affect the current running thread.
31456 RATIONALE 31457 None.
31458 FUTURE DIRECTIONS 31459 None.
31460 SEE ALSO 31461 pthread_attr_destroy (), pthread_attr_getscope (), pthread_attr_getinheritsched (), 31462 pthread_attr_getschedparam (), pthread_create (), the Base Definitions volume of 31463 IEEE Std 1003.1-2001, < pthread.h>, < sched.h >
31464 CHANGE HISTORY 31465 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
31466 Marked as part of the Realtime Threads Feature Group.
31467 Issue 6 31468 The pthread_attr_getschedpolicy () and pthread_attr_setschedpolicy () functions are marked as part of 31469 the Threads and Thread Execution Scheduling options.
31470 The [ENOSYS] error condition has been removed as stubs need not be provided if an 31471 implementation does not support the Thread Execution Scheduling option.
31472 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999.
31473 The restrict keyword is added to the pthread_attr_getschedpolicy () prototype for alignment with 31474 the ISO/IEC 9899: 1999 standard.
31983 NAME 31984 pthread_cancel ” cancel execution of a thread
31985 SYNOPSIS
31986 THR #include <pthread.h> 31987 int pthread_cancel (pthread_t thread );
31988
31989 DESCRIPTION 31990 The pthread_cancel () function shall request that thread be canceled . The target thread's 31991 cancelability state and type determines when the cancelation takes effect. When the cancelation 31992 is acted on, the cancelation cleanup handlers for thread shall be called. When the last cancelation 31993 cleanup handler returns, the thread-specific data destructor functions shall be called for thread . 31994 When the last destructor function returns, thread shall be terminated.
31995 The cancelation processing in the target thread shall run asynchronously with respect to the 31996 calling thread returning from pthread_cancel ().
31997 RETURN VALUE 31998 If successful, the pthread_cancel () function shall return zero; otherwise, an error number shall be 31999 returned to indicate the error.
32000 ERRORS
32001 The pthread_cancel () function may fail if:
32002 [ESRCH] No thread could be found corresponding to that specified by the given thread 32003 ID.
32004 The pthread_cancel () function shall not return an error code of [EINTR].
32005 EXAMPLES 32006 None.
32007 APPLICATION USAGE 32008 None.
32009 RATIONALE 32010 Two alternative functions were considered for sending the cancelation notification to a thread. 32011 One would be to define a new SIGCANCEL signal that had the cancelation semantics when 32012 delivered; the other was to define the new pthread_cancel () function, which would trigger the 32013 cancelation semantics.
32014 The advantage of a new signal was that so much of the delivery criteria were identical to that 32015 used when trying to deliver a signal that making cancelation notification a signal was seen as 32016 consistent. Indeed, many implementations implement cancelation using a special signal. On the 32017 other hand, there would be no signal functions that could be used with this signal except 32018 pthread_kill (), and the behavior of the delivered cancelation signal would be unlike any 32019 previously existing defined signal.
32020 The benefits of a special function include the recognition that this signal would be defined 32021 because of the similar delivery criteria and that this is the only common behavior between a 32022 cancelation request and a signal. In addition, the cancelation delivery mechanism does not have 32023 to be implemented as a signal. There are also strong, if not stronger, parallels with language 32024 exception mechanisms than with signals that are potentially obscured if the delivery mechanism 32025 is visibly closer to signals.
32026 In the end, it was considered that as there were so many exceptions to the use of the new signal 32027 with existing signals functions it would be misleading. A special function has resolved this 32028 problem. This function was carefully defined so that an implementation wishing to provide the 32029 cancelation functions on top of signals could do so. The special function also means that 32030 implementations are not obliged to implement cancelation with signals.
32031 FUTURE DIRECTIONS 32032 None.
32033 SEE ALSO 32034 pthread_exit (), pthread_cond_timedwait (), pthread_join (), pthread_setcancelstate (), the Base 32035 Definitions volume of IEEE Std 1003.1-2001, < pthread.h >
32036 CHANGE HISTORY 32037 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32038 Issue 6 32039 The pthread_cancel () function is marked as part of the Threads option.
32040 NAME 32041 pthread_cleanup_pop, pthread_cleanup_push ” establish cancelation handlers
32042 SYNOPSIS
32043 THR #include <pthread.h> 32044 void pthread_cleanup_pop (int execute ); 32045 void pthread_cleanup_push (void (* routine ) (void*), void * arg );
32046
32047 DESCRIPTION 32048 The pthread_cleanup_pop () function shall remove the routine at the top of the calling thread's 32049 cancelation cleanup stack and optionally invoke it (if execute is non-zero).
32050 The pthread_cleanup_push () function shall push the specified cancelation cleanup handler routine 32051 onto the calling thread's cancelation cleanup stack. The cancelation cleanup handler shall be 32052 popped from the cancelation cleanup stack and invoked with the argument arg when:
32053 The thread exits (that is, calls pthread_exit ()).
32054 The thread acts upon a cancelation request.
32055 The thread calls pthread_cleanup_pop () with a non-zero execute argument.
32056 These functions may be implemented as macros. The application shall ensure that they appear 32057 as statements, and in pairs within the same lexical scope (that is, the pthread_cleanup_push () 32058 macro may be thought to expand to a token list whose first token is '{' with 32059 pthread_cleanup_pop () expanding to a token list whose last token is the corresponding '}').
32060 The effect of calling longjmp () or siglongjmp () is undefined if there have been any calls to 32061 pthread_cleanup_push () or pthread_cleanup_pop () made without the matching call since the jump 32062 buffer was filled. The effect of calling longjmp () or siglongjmp () from inside a cancelation 32063 cleanup handler is also undefined unless the jump buffer was also filled in the cancelation 32064 cleanup handler.
32065 RETURN VALUE 32066 The pthread_cleanup_push () and pthread_cleanup_pop () functions shall not return a value.
32067 ERRORS 32068 No errors are defined.
32069 These functions shall not return an error code of [EINTR].
32070 EXAMPLES 32071 The following is an example using thread primitives to implement a cancelable, writers-priority 32072 read-write lock:
32073 typedef struct { 32074 pthread_mutex_t lock; 32075 pthread_cond_t rcond, 32076 wcond; 32077 int lock_count; /* <0 .. Held by writer. */ 32078 /* > 0 .. Held by lock_count readers. */ 32079 /* = 0 .. Held by nobody. */ 32080 int waiting_writers; /* Count of waiting writers. */ 32081 } rwlock; 32082 void 32083 waiting_reader_cleanup (void. *arg). 32084 { 32085 rwlock *1; 32086 1 = (rwlock *) arg; 32087 pthread_mutex_unlock (&l->lock); 32088 } 32089 void 32090 lock_for_read (rwlock *1) 32091 { 32092 pthread_mutex_lock (&1->lock); 32093 pthread_cleanup_push (waiting_reader_cleanup, 1); 32094 while ((1->lock_count <0) && (1->waiting_writers ! = 0)) 32095 pthread_cond_wait (&1->rcond, &1->lock); 32096 1->lock_count++; 32097 /* 32098 * Note the pthread_cleanup_pop executes 32099 * waiting_reader_cleanup. 32100 */ 32101 pthread_cleanup_pop(1); 32102 } 32103 void 32104 release_read_lock (rwlock *1) 32105 { 32106 pthread_mutex_lock (&1->lock); 32107 if (--1->lock_count == 0) 32108 pthread_cond_signal (&1->wcond); 32109 pthread_mutex_unlock (1); 32110 } 32111 void 32112 waiting_writer_cleanup (void *arg) 32113 { 32114 rwlock *1; 32115 1 = (rwlock *) arg; 32116 if ((--1->waiting_writers == 0) && (1->lock_count >= 0)) { 32117 /* 32118 * This only happens if we have been canceled. 32119 */ 32120 pthread_cond_broadcast (&l->wcond); 32121 } 32122 pthread_mutex_unlock (&1->lock); 32123 } 32124 void 32125 lock_for_write (rwlock *1) 32126 { 32127 pthread_mutex_lock (&1->lock); 32128 1->waiting_writers++; 32129 pthread_cleanup_push (waiting_writer_cleanup, 1); 32130 while (1->lock_count ! = 0) 32131 pthread_cond_wait (&1->wcond, &1->lock); 32132 1->lock_count = -1; 32133 /* 32134 * Note the pthread_cleanup_pop executes 32135 * waiting_writer_cleanup. 32136 */ 32137 pthread_cleanup_pop (1); 32138 } 32139 void 32140 release_write_lock (rwlock *1) 32141 { 32142 pthread_mutex_lock (&1->lock); 32143 1->lock_count = 0; 32144 if (1->waiting_writers == 0) 32145 pthread_cond_broadcast (&1->rcond) 32146 else 32147 pthread_cond_signal (&1->wcond); 32148 pthread_mutex_unlock (&1->lock); 32149 } 32150 /* 32151 * This function is called to initialize the read/write lock. 32152 */ 32153 void 32154 initialize_rwlock (rwlock *1) 32155 { 32156 pthread_mutex_init (&1->lock, pthread_mutexattr_default); 32157 pthread_cond_init (&1->wcond, pthread_condattr_default); 32158 pthread_cond_init (&1->rcond, pthread_condattr_default); 32159 1->lock_count = 0; 32160 1->waiting_writers = 0; 32161 } 32162 reader_thread() 32163 { 32164 lock_for_read (&lock); 32165 pthread_cleanup_push (release_read_lock, &lock); 32166 /* 32167 * Thread has read lock. 32168 */ 32169 pthread_cleanup_pop (1); 32170 } 32171 writer_thread() 32172 { 32173 lock_for_write (&lock); 32174 pthread_cleanup_push (release_write_lock, &lock); 32175 /* 32176 * Thread has write lock. 32177 */ 32178 pthread_cleanup_pop (1); 32179 }
32180 APPLICATION USAGE 32181 The two routines that push and pop cancelation cleanup handlers, pthread_cleanup_push () and 32182 pthread_cleanup_pop (), can be thought of as left and right parentheses. They always need to be 32183 matched.
32184 RATIONALE 32185 The restriction that the two routines that push and pop cancelation cleanup handlers, 32186 pthread_cleanup_push () and pthread_cleanup_pop (), have to appear in the same lexical scope 32187 allows for efficient macro or compiler implementations and efficient storage management. A 32188 sample implementation of these routines as macros might look like this:
32189 #define pthread_cleanup_push (rtn, arg) { \ 32190 struct _pthread_handler_rec __cleanup_handler, **__head; \ 32191 __cleanup_handler.rtn = rtn; \ 32192 __cleanup_handler.arg = arg; \ 32193 (void) pthread_getspecific (_pthread_handler_key, &__head); \ 32194 __cleanup_handler.next = *__head; \ 32195 *__head = &__cleanup_handler; 32196 #define pthread_cleanup_pop (ex) \ 32197 *__head = __cleanup_handler.next; \ 32198 if (ex) (*__cleanup_handler.rtn) (_cleanup_handler.arg); \ 32199 }
32200 A more ambitious implementation of these routines might do even better by allowing the 32201 compiler to note that the cancelation cleanup handler is a constant and can be expanded inline.
32202 This volume of IEEE Std 1003.1-2001 currently leaves unspecified the effect of calling longjmp () 32203 from a signal handler executing in a POSIX System Interfaces function. If an implementation 32204 wants to allow this and give the programmer reasonable behavior, the longjmp () function has to 32205 call all cancelation cleanup handlers that have been pushed but not popped since the time 32206 setjmp () was called.
32207 Consider a multi-threaded function called by a thread that uses signals. If a signal were 32208 delivered to a signal handler during the operation of qsort () and that handler were to call 32209 longjmp () (which, in turn , did not call the cancelation cleanup handlers) the helper threads 32210 created by the qsort () function would not be canceled. Instead, they would continue to execute 32211 and write into the argument array even though the array might have been popped off the stack.
32212 Note that the specified cleanup handling mechanism is especially tied to the C language and, 32213 while the requirement for a uniform mechanism for expressing cleanup is language- 32214 independent, the mechanism used in other languages may be quite different. In addition, this 32215 mechanism is really only necessary due to the lack of a real exception mechanism in the C 32216 language, which would be the ideal solution.
32217 There is no notion of a cancelation cleanup-safe function. If an application has no cancelation 32218 points in its signal handlers, blocks any signal whose handler may have cancelation points while 32219 calling async-unsafe functions, or disables cancelation while calling async-unsafe functions, all 32220 functions may be safely called from cancelation cleanup routines.
32221 FUTURE DIRECTIONS 32222 None.
32223 SEE ALSO 32224 pthread_cancel (), pthread_setcancelstate (), the Base Definitions volume of IEEE Std 1003.1-2001, 32225 < pthread.h >
32226 CHANGE HISTORY 32227 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32228 Issue 6 32229 The pthread_cleanup_pop () and pthread_cleanup_push () functions are marked as part of the 32230 Threads option.
32231 The APPLICATION USAGE section is added.
32232 The DESCRIPTION is updated to avoid use of the term "must" for application requirements.
32233 NAME 32234 pthread_cond_broadcast, pthread_cond_signal ”broadcast or signal a condition
32235 SYNOPSIS
32236 THR #include <pthread.h> 32237 int pthread_cond_broadcast (pthread_cond_t * cond ); 32238 int pthread_cond_signal (pthread_cond_t * cond );
32239
32240 DESCRIPTION 32241 These functions shall unblock threads blocked on a condition variable.
32242 The pthread_cond_broadcast () function shall unblock all threads currently blocked on the 32243 specified condition variable cond .
32244 The pthread_cond_signal () function shall unblock at least one of the threads that are blocked on 32245 the specified condition variable cond (if any threads are blocked on cond ).
32246 If more than one thread is blocked on a condition variable, the scheduling policy shall determine 32247 the order in which threads are unblocked. When each thread unblocked as a result of a 32248 pthread_cond_broadcast () or pthread_cond_signal () returns from its call to pthread_cond_wait () or 32249 pthread_cond_timedwait (), the thread shall own the mutex with which it called 32250 pthread_cond_wait () or pthread_cond_timedwait (). The thread(s) that are unblocked shall contend 32251 for the mutex according to the scheduling policy (if applicable ), and as if each had called 32252 pthread_mutex_lock ().
32253 The pthread_cond_broadcast () or pthread_cond_signal () functions may be called by a thread 32254 whether or not it currently owns the mutex that threads calling pthread_cond_wait () or 32255 pthread_cond_timedwait () have associated with the condition variable during their waits; 32256 however, if predictable scheduling behavior is required, then that mutex shall be locked by the 32257 thread calling pthread_cond_broadcast () or pthread_cond_signal ().
32258 The pthread_cond_broadcast () and pthread_cond_signal () functions shall have no effect if there are 32259 no threads currently blocked on cond .
32260 RETURN VALUE 32261 If successful, the pthread_cond_broadcast () and pthread_cond_signal () functions shall return zero; 32262 otherwise, an error number shall be returned to indicate the error.
32263 ERRORS 32264 The pthread_cond_broadcast () and pthread_cond_signal () function may fail if:
32265 [EINVAL] The value cond does not refer to an initialized condition variable.
32266 These functions shall not return an error code of [EINTR].
32267 EXAMPLES 32268 None.
32269 APPLICATION USAGE 32270 The pthread_cond_broadcast () function is used whenever the shared-variable state has been 32271 changed in a way that more than one thread can proceed with its task. Consider a single 32272 producer/multiple consumer problem, where the producer can insert multiple items on a list 32273 that is accessed one item at a time by the consumers. By calling the pthread_cond_broadcast () 32274 function, the producer would notify all consumers that might be waiting, and thereby the 32275 application would receive more throughput on a multi-processor. In addition, 32276 pthread_cond_broadcast () makes it easier to implement a read-write lock. The 32277 pthread_cond_broadcast () function is needed in order to wake up all waiting readers when a 32278 writer releases its lock. Finally, the two-phase commit algorithm can use this broadcast function 32279 to notify all clients of an impending transaction commit.
32280 It is not safe to use the pthread_cond_signal () function in a signal handler that is invoked 32281 asynchronously. Even if it were safe, there would still be a race between the test of the Boolean 32282 pthread_cond_wait () that could not be efficiently eliminated.
32283 Mutexes and condition variables are thus not suitable for releasing a waiting thread by signaling 32284 from code running in a signal handler.
32285 RATIONALE
32286 Multiple Awakenings by Condition Signal
32287 On a multi-processor, it may be impossible for an implementation of pthread_cond_signal () to 32288 avoid the unblocking of more than one thread blocked on a condition variable. For example, 32289 consider the following partial implementation of pthread_cond_wait () and pthread_cond_signal (), 32290 executed by two threads in the order given. One thread is trying to wait on the condition 32291 variable, another is concurrently executing pthread_cond_signal (), while a third thread is already 32292 waiting.
32293 pthread_cond_wait (mutex, cond): 32294 value = cond->value; /* 1 */ 32295 pthread_mutex_unlock (mutex); /* 2 */ 32296 pthread_mutex_lock (cond->mutex); /* 10 */ 32297 if (value == cond->value) { /* 11 */ 32298 me->next_cond = cond->waiter; 32299 cond->waiter = me; 32300 pthread_mutex_unlock (cond->mutex); 32301 unable_to_run (me); 32302 } else 32303 pthread_mutex_unlock (cond->mutex); /* 12 */ 32304 pthread_mutex_lock (mutex); /* 13 * / 32305 pthread_cond_signal (cond): 32306 pthread_mutex_lock (cond->mutex); /* 3 */ 32307 cond->value++; /* 4 */ 32308 if (cond->waiter) { /* 5 */ 32309 sleeper = cond->waiter; /* 6 */ 32310 cond->waiter = sleeper->next_cond; /* 7 */ 32311 able_to_run (sleeper); /* 8 */ 32312 } 32313 pthread_mutex_unlock (cond->mutex); /* 9 */
32314 The effect is that more than one thread can return from its call to pthread_cond_wait () or 32315 pthread_cond_timedwait () as a result of one call to pthread_cond_signal (). This effect is called 32316 " spurious wakeup ". Note that the situation is self-correcting in that the number of threads that 32317 are so awakened is finite; for example, the next thread to call pthread_cond_wait () after the
32319 While this problem could be resolved, the loss of efficiency for a fringe condition that occurs 32320 only rarely is unacceptable, especially given that one has to check the predicate associated with a 32321 condition variable anyway. Correcting this problem would unnecessarily reduce the degree of 32322 concurrency in this basic building block for all higher-level synchronization operations.
32323 An added benefit of allowing spurious wakeups is that applications are forced to code a 32324 predicate-testing-loop around the condition wait. This also makes the application tolerate 32325 superfluous condition broadcasts or signals on the same condition variable that may be coded in 32326 some other part of the application. The resulting applications are thus more robust. Therefore, 32327 IEEE Std 1003.1-2001 explicitly documents that spurious wakeups may occur.
32328 FUTURE DIRECTIONS 32329 None.
32330 SEE ALSO 32331 pthread_cond_destroy (), pthread_cond_timedwait (), the Base Definitions volume of 32332 IEEE Std 1003.1-2001, < pthread.h>
32333 CHANGE HISTORY 32334 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32335 Issue 6 32336 The pthread_cond_broadcast () and pthread_cond_signal () functions are marked as part of the 32337 Threads option.
32338 The APPLICATION USAGE section is added.
32339 NAME 32340 pthread_cond_destroy, pthread_cond_init ” destroy and initialize condition variables
32341 SYNOPSIS
32342 THR #include <pthread.h> 32343 int pthread_cond_destroy (pthread_cond_t * cond ); 32344 int pthread_cond_init (pthread_cond_t *restrict cond, 32345 const pthread_condattr_t *restrict attr ); 32346 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
32347
32348 DESCRIPTION 32349 The pthread_cond_destroy () function shall destroy the given condition variable specified by cond ; 32350 the object becomes, in effect, uninitialized. An implementation may cause pthread_cond_destroy () 32351 to set the object referenced by cond to an invalid value. A destroyed condition variable object can 32352 be reinitialized using pthread_cond_init (); the results of otherwise referencing the object after it 32353 has been destroyed are undefined.
32354 It shall be safe to destroy an initialized condition variable upon which no threads are currently 32355 blocked. Attempting to destroy a condition variable upon which other threads are currently 32356 blocked results in undefined behavior.
32357 The pthread_cond_init () function shall initialize the condition variable referenced by cond with 32358 attributes referenced by attr . If attr is NULL, the default condition variable attributes shall be 32359 used; the effect is the same as passing the address of a default condition variable attributes 32360 object. Upon successful initialization, the state of the condition variable shall become initialized.
32361 Only cond itself may be used for performing synchronization. The result of referring to copies of 32362 cond in calls to pthread_cond_wait (), pthread_cond_timedwait (), pthread_cond_signal (), 32363 pthread_cond_broadcast (), and pthread_cond_destroy () is undefined.
32364 Attempting to initialize an already initialized condition variable results in undefined behavior.
32365 In cases where default condition variable attributes are appropriate, the macro 32366 PTHREAD_COND_INITIALIZER can be used to initialize condition variables that are statically 32367 allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_cond_init () 32368 with parameter attr specified as NULL, except that no error checks are performed.
32369 RETURN VALUE 32370 If successful, the pthread_cond_destroy () and pthread_cond_init () functions shall return zero; 32371 otherwise, an error number shall be returned to indicate the error.
32372 The [EBUSY] and [EINVAL] error checks, if implemented, shall act as if they were performed 32373 immediately at the beginning of processing for the function and caused an error return prior to 32374 modifying the state of the condition variable specified by cond .
32375 ERRORS 32376 The pthread_cond_destroy () function may fail if:
32377 [EBUSY] The implementation has detected an attempt to destroy the object referenced 32378 by cond while it is referenced (for example, while being used in a 32379 pthread_cond_wait () or pthread_cond_timedwait () by another thread. 32380 [EINVAL] The value specified by cond is invalid.
32381 The pthread_cond_init () function shall fail if:
32382 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 32383 another condition variable. 32384 [ENOMEM] Insufficient memory exists to initialize the condition variable.
32385 The pthread_cond_init () function may fail if:
32386 [EBUSY] The implementation has detected an attempt to reinitialize the object 32387 referenced by cond , a previously initialized, but not yet destroyed, condition 32388 variable. 32389 [EINVAL] The value specified by attr is invalid.
32390 These functions shall not return an error code of [EINTR].
32391 EXAMPLES 32392 A condition variable can be destroyed immediately after all the threads that are blocked on it are 32393 awakened. For example, consider the following code:
32394 struct list { 32395 pthread_mutex_t lm; 32396 ... 32397 } 32398 struct elt { 32399 key k; 32400 int busy; 32401 pthread_cond_t notbusy; 32402 ... 32403 } 32404 /* Find a list element and reserve it. */ 32405 struct elt * 32406 list_find (struct list *lp, key k) 32407 { 32408 struct elt *ep; 32409 pthread_mutex_lock (&lp->lm); 32410 while ((ep = find_elt (1, k) ! = NULL) && ep->busy) 32411 pthread_cond_wait (&ep->notbusy, &lp->lm); 32412 if (ep != NULL) 32413 ep->busy = 1; 32414 pthread_mutex_unlock (&lp->lm); 32415 return (ep); 32416 } 32417 delete_elt (struct list *lp, struct elt *ep) 32418 { 32419 pthread_mutex_lock (&lp->lm); 32420 assert (ep->busy); 32421 ... remove ep from list ... 32422 ep->busy = 0; /* Paranoid. */ 32423 (A) pthread_cond_broadcast (&ep->notbusy); 32424 pthread_mutex_unlock (&lp->lm); 32425 (B) pthread_cond_destroy (&rp->notbusy); 32426 free (ep); 32427 }
32428 In this example, the condition variable and its list element may be freed (line B) immediately 32429 after all threads waiting for it are awakened (line A), since the mutex and the code ensure that no 32430 other thread can touch the element to be deleted.
32431 APPLICATION USAGE 32432 None.
32433 RATIONALE 32434 See pthread_mutex_init (); a similar rationale applies to condition variables.
32435 FUTURE DIRECTIONS 32436 None.
32437 SEE ALSO 32438 pthread_cond_broadcast (), pthread_cond_signal (), pthread_cond_timedwait (), the Base Definitions 32439 volume of IEEE Std 1003.1-2001, < pthread.h>
32440 CHANGE HISTORY 32441 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32442 Issue 6 32443 The pthread_cond_destroy () and pthread_cond_init () functions are marked as part of the Threads 32444 option.
32445 IEEE PASC Interpretation 1003.1c #34 is applied, updating the DESCRIPTION.
32446 The restrict keyword is added to the pthread_cond_init () prototype for alignment with the 32447 ISO/IEC 9899: 1999 standard.
32456 NAME 32457 pthread_cond_timedwait, pthread_cond_wait ”wait on a condition
32458 SYNOPSIS
32459 THR #include <pthread.h> 32460 int pthread_cond_timedwait (pthread_cond_t *restrict cond, 32461 pthread_mutex_t *restrict mutex, 32462 const struct timespec *restrict abstime ); 32463 int pthread_cond_wait (pthread_cond_t *restrict cond, 32464 pthread_mutex_t *restrict mutex );
32465
32466 DESCRIPTION 32467 The pthread_cond_timedwait () and pthread_cond_wait () functions shall block on a condition 32468 variable. They shall be called with mutex locked by the calling thread or undefined behavior 32469 results.
32470 These functions atomically release mutex and cause the calling thread to block on the condition 32471 variable cond ; atomically here means "atomically with respect to access by another thread to the 32472 mutex and then the condition variable". That is, if another thread is able to acquire the mutex 32473 after the about-to-block thread has released it, then a subsequent call to pthread_cond_broadcast () 32474 or pthread_cond_signal () in that thread shall behave as if it were issued after the about-to-block 32475 thread has blocked.
32476 Upon successful return, the mutex shall have been locked and shall be owned by the calling 32477 thread.
32478 When using condition variables there is always a Boolean predicate involving shared variables 32479 associated with each condition wait that is true if the thread should proceed. Spurious wakeups 32480 from the pthread_cond_timedwait () or pthread_cond_wait () functions may occur. Since the return 32481 from pthread_cond_timedwait () or pthread_cond_wait () does not imply anything about the value 32482 of this predicate, the predicate should be re-evaluated upon such return.
32483 The effect of using more than one mutex for concurrent pthread_cond_timedwait () or 32484 pthread_cond_wait () operations on the same condition variable is undefined; that is, a condition 32485 variable becomes bound to a unique mutex when a thread waits on the condition variable, and 32486 this (dynamic) binding shall end when the wait returns.
32487 A condition wait (whether timed or not) is a cancelation point. When the cancelability enable 32488 state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a 32489 cancelation request while in a condition wait is that the mutex is (in effect) re- acquired before 32490 calling the first cancelation cleanup handler. The effect is as if the thread were unblocked, 32491 allowed to execute up to the point of returning from the call to pthread_cond_timedwait () or 32492 pthread_cond_wait (), but at that point notices the cancelation request and instead of returning to 32493 the caller of pthread_cond_timedwait () or pthread_cond_wait (), starts the thread cancelation 32494 activities, which includes calling cancelation cleanup handlers.
32495 A thread that has been unblocked because it has been canceled while blocked in a call to 32496 pthread_cond_timedwait () or pthread_cond_wait () shall not consume any condition signal that 32497 may be directed concurrently at the condition variable if there are other threads blocked on the 32498 condition variable.
32499 The pthread_cond_timedwait () function shall be equivalent to pthread_cond_wait (), except that an 32500 error is returned if the absolute time specified by abstime passes (that is, system time equals or 32501 exceeds abstime ) before the condition cond is signaled or broadcasted, or if the absolute time 32502 specified by abstime has already been passed at the time of the call.
32503 CS If the Clock Selection option is supported, the condition variable shall have a clock attribute 32504 which specifies the clock that shall be used to measure the time specified by the abstime 32505 argument . When such timeouts occur, pthread_cond_timedwait () shall nonetheless release and 32506 re-acquire the mutex referenced by mutex . The pthread_cond_timedwait () function is also a 32507 cancelation point.
32508 If a signal is delivered to a thread waiting for a condition variable, upon return from the signal 32509 handler the thread resumes waiting for the condition variable as if it was not interrupted , or it 32510 shall return zero due to spurious wakeup.
32511 RETURN VALUE 32512 Except in the case of [ETIMEDOUT], all these error checks shall act as if they were performed 32513 immediately at the beginning of processing for the function and shall cause an error return, in 32514 effect, prior to modifying the state of the mutex specified by mutex or the condition variable 32515 specified by cond .
32516 Upon successful completion, a value of zero shall be returned; otherwise, an error number shall 32517 be returned to indicate the error.
32518 ERRORS 32519 The pthread_cond_timedwait () function shall fail if:
32520 [ETIMEDOUT] The time specified by abstime to pthread_cond_timedwait () has passed.
32521 The pthread_cond_timedwait () and pthread_cond_wait () functions may fail if:
32522 [EINVAL] The value specified by cond, mutex , or abstime is invalid. 32523 [EINVAL] Different mutexes were supplied for concurrent pthread_cond_timedwait () or 32524 pthread_cond_wait () operations on the same condition variable. 32525 [EPERM] The mutex was not owned by the current thread at the time of the call.
32526 These functions shall not return an error code of [EINTR].
32527 EXAMPLES 32528 None.
32529 APPLICATION USAGE 32530 None.
32531 RATIONALE
32532 Condition Wait Semantics
32533 It is important to note that when pthread_cond_wait () and pthread_cond_timedwait () return 32534 without error, the associated predicate may still be false. Similarly, when 32535 pthread_cond_timedwait () returns with the timeout error, the associated predicate may be true 32536 due to an unavoidable race between the expiration of the timeout and the predicate state change.
32537 Some implementations, particularly on a multi-processor, may sometimes cause multiple 32538 threads to wake up when the condition variable is signaled simultaneously on different 32539 processors.
32540 In general, whenever a condition wait returns, the thread has to re-evaluate the predicate 32541 associated with the condition wait to determine whether it can safely proceed, should wait 32542 again, or should declare a timeout. A return from the wait does not imply that the associated 32543 predicate is either true or false.
32544 It is thus recommended that a condition wait be enclosed in the equivalent of a "while loop" 32545 that checks the predicate.
32546 Timed Wait Semantics
32547 An absolute time measure was chosen for specifying the timeout parameter for two reasons. 32548 First, a relative time measure can be easily implemented on top of a function that specifies 32549 absolute time, but there is a race condition associated with specifying an absolute timeout on top 32550 of a function that specifies relative timeouts. For example, assume that clock_gettime () returns 32551 the current time and cond_relative_timed_wait () uses relative timeouts:
32552 clock_gettime (CLOCK_REALTIME, &now) 32553 reltime = sleep_til_this_absolute_time -now; 32554 cond_relative_timed_wait (c, m, &reltime);
32555 If the thread is preempted between the first statement and the last statement, the thread blocks 32556 for too long. Blocking, however, is irrelevant if an absolute timeout is used. An absolute timeout 32557 also need not be recomputed if it is used multiple times in a loop, such as that enclosing a 32558 condition wait.
32559 For cases when the system clock is advanced discontinuously by an operator, it is expected that 32560 implementations process any timed wait expiring at an intervening time as if that time had 32561 actually occurred.
32562 Cancelation and Condition Wait
32563 A condition wait, whether timed or not, is a cancelation point. That is, the functions 32564 pthread_cond_wait () or pthread_cond_timedwait () are points where a pending (or concurrent) 32565 cancelation request is noticed. The reason for this is that an indefinite wait is possible at these 32566 points ”whatever event is being waited for, even if the program is totally correct, might never 32567 occur; for example, some input data being awaited might never be sent. By making condition 32568 wait a cancelation point, the thread can be canceled and perform its cancelation cleanup handler 32569 even though it may be stuck in some indefinite wait.
32570 A side effect of acting on a cancelation request while a thread is blocked on a condition variable 32571 is to re-acquire the mutex before calling any of the cancelation cleanup handlers. This is done in 32572 order to ensure that the cancelation cleanup handler is executed in the same state as the critical 32573 code that lies both before and after the call to the condition wait function. This rule is also 32574 required when interfacing to POSIX threads from languages, such as Ada or C++, which may 32575 choose to map cancelation onto a language exception; this rule ensures that each exception 32576 handler guarding a critical section can always safely depend upon the fact that the associated 32577 mutex has already been locked regardless of exactly where within the critical section the 32578 exception was raised. Without this rule, there would not be a uniform rule that exception 32579 handlers could follow regarding the lock, and so coding would become very cumbersome.
32580 Therefore, since some statement has to be made regarding the state of the lock when a 32581 cancelation is delivered during a wait, a definition has been chosen that makes application 32582 coding most convenient and error free.
32583 When acting on a cancelation request while a thread is blocked on a condition variable, the 32584 implementation is required to ensure that the thread does not consume any condition signals 32585 directed at that condition variable if there are any other threads waiting on that condition 32586 variable. This rule is specified in order to avoid deadlock conditions that could occur if these two 32587 independent requests (one acting on a thread and the other acting on the condition variable) 32588 were not processed independently.
32589 Performance of Mutexes and Condition Variables
32590 Mutexes are expected to be locked only for a few instructions. This practice is almost 32591 automatically enforced by the desire of programmers to avoid long serial regions of execution 32592 (which would reduce total effective parallelism).
32593 When using mutexes and condition variables, one tries to ensure that the usual case is to lock the 32594 mutex, access shared data, and unlock the mutex. Waiting on a condition variable should be a 32595 relatively rare situation. For example, when implementing a read-write lock, code that acquires a 32596 read-lock typically needs only to increment the count of readers (under mutual-exclusion) and 32597 return. The calling thread would actually wait on the condition variable only when there is 32598 already an active writer. So the efficiency of a synchronization operation is bounded by the cost 32599 of mutex lock/unlock and not by condition wait. Note that in the usual case there is no context 32600 switch.
32601 This is not to say that the efficiency of condition waiting is unimportant. Since there needs to be 32602 at least one context switch per Ada rendezvous, the efficiency of waiting on a condition variable 32603 is important. The cost of waiting on a condition variable should be little more than the minimal 32604 cost for a context switch plus the time to unlock and lock the mutex.
32605 Features of Mutexes and Condition Variables
32606 It had been suggested that the mutex acquisition and release be decoupled from condition wait. 32607 This was rejected because it is the combined nature of the operation that, in fact, facilitates 32608 realtime implementations. Those implementations can atomically move a high-priority thread 32609 between the condition variable and the mutex in a manner that is transparent to the caller. This 32610 can prevent extra context switches and provide more deterministic acquisition of a mutex when 32611 the waiting thread is signaled. Thus, fairness and priority issues can be dealt with directly by the 32612 scheduling discipline. Furthermore, the current condition wait operation matches existing 32613 practice.
32614 Scheduling Behavior of Mutexes and Condition Variables
32615 Synchronization primitives that attempt to interfere with scheduling policy by specifying an 32616 ordering rule are considered undesirable. Threads waiting on mutexes and condition variables 32617 are selected to proceed in an order dependent upon the scheduling policy rather than in some 32618 fixed order (for example, FIFO or priority). Thus, the scheduling policy determines which 32619 thread(s) are awakened and allowed to proceed.
32620 Timed Condition Wait
32621 The pthread_cond_timedwait () function allows an application to give up waiting for a particular 32622 condition after a given amount of time. An example of its use follows:
32623 (void) pthread_mutex_lock (&t. mn); 32624 t.waiters++; 32625 clock_gettime (CLOCK_REALTIME, &ts); 32626 ts.tv_sec += 5; 32627 rc = 0; 32628 while (! mypredicate (&t) && rc == 0) 32629 rc = pthread_cond_timedwait (&t.cond, &t.mn, &ts); 32630 t.waiters- -; 32631 if (rc == 0) setmystate (&t); 32632 (void) pthread_mutex_unlock (&t.mn);
32633 By making the timeout parameter absolute, it does not need to be recomputed each time the 32634 program checks its blocking predicate. If the timeout was relative, it would have to be 32635 recomputed before each call. This would be especially difficult since such code would need to 32636 take into account the possibility of extra wakeups that result from extra broadcasts or signals on 32637 the condition variable that occur before either the predicate is true or the timeout is due.
32638 FUTURE DIRECTIONS 32639 None.
32640 SEE ALSO 32641 pthread_cond_signal (), pthread_cond_broadcast (), the Base Definitions volume of 32642 IEEE Std 1003.1-2001, < pthread.h>
32643 CHANGE HISTORY 32644 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32645 Issue 6 32646 The pthread_cond_timedwait () and pthread_cond_wait () functions are marked as part of the 32647 Threads option.
32648 The Open Group Corrigendum U021/9 is applied, correcting the prototype for the 32649 pthread_cond_wait () function.
32650 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding semantics for 32651 the Clock Selection option.
32652 The ERRORS section has an additional case for [EPERM] in response to IEEE PASC 32653 Interpretation 1003.1c #28.
32654 The restrict keyword is added to the pthread_cond_timedwait () and pthread_cond_wait () 32655 prototypes for alignment with the ISO/IEC 9899: 1999 standard.
32656 NAME 32657 pthread_condattr_destroy, pthread_condattr_init ”destroy and initialize the condition variable 32658 attributes object
32659 SYNOPSIS
32660 THR #include <pthread.h> 32661 int pthread_condattr_destroy (pthread_condattr_t * attr ); 32662 int pthread_condattr_init (pthread_condattr_t * attr );
32663
32664 DESCRIPTION 32665 The pthread_condattr_destroy () function shall destroy a condition variable attributes object; the 32666 object becomes, in effect, uninitialized. An implementation may cause pthread_condattr_destroy () 32667 to set the object referenced by attr to an invalid value. A destroyed attr attributes object can be 32668 reinitialized using pthread_condattr_init (); the results of otherwise referencing the object after it 32669 has been destroyed are undefined.
32670 The pthread_condattr_init () function shall initialize a condition variable attributes object attr with 32671 the default value for all of the attributes defined by the implementation.
32672 Results are undefined if pthread_condattr_init () is called specifying an already initialized attr 32673 attributes object.
32674 After a condition variable attributes object has been used to initialize one or more condition 32675 variables, any function affecting the attributes object (including destruction) shall not affect any 32676 previously initialized condition variables.
32677 This volume of IEEE Std 1003.1-2001 requires two attributes, the clock attribute and the process- 32678 shared attribute.
32679 Additional attributes, their default values, and the names of the associated functions to get and 32680 set those attribute values are implementation-defined.
32681 RETURN VALUE 32682 If successful, the pthread_condattr_destroy () and pthread_condattr_init () functions shall return 32683 zero; otherwise, an error number shall be returned to indicate the error.
32684 ERRORS 32685 The pthread_condattr_destroy () function may fail if:
32686 [EINVAL] The value specified by attr is invalid.
32687 The pthread_condattr_init () function shall fail if:
32688 [ENOMEM] Insufficient memory exists to initialize the condition variable attributes object.
32689 These functions shall not return an error code of [EINTR].
32690 EXAMPLES 32691 None.
32692 APPLICATION USAGE 32693 None.
32694 RATIONALE 32695 See pthread_attr_init () and pthread_mutex_init ().
32696 A process-shared attribute has been defined for condition variables for the same reason it has been 32697 defined for mutexes.
32698 FUTURE DIRECTIONS 32699 None.
32700 SEE ALSO 32701 pthread_attr_destroy (), pthread_cond_destroy (), pthread_condattr_getpshared (), pthread_create (), 32702 pthread_mutex_destroy (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
32703 CHANGE HISTORY 32704 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32705 Issue 6 32706 The pthread_condattr_destroy () and pthread_condattr_init () functions are marked as part of the 32707 Threads option.
32753 NAME 32754 pthread_condattr_getpshared, pthread_condattr_setpshared ” get and set the process-shared 32755 condition variable attributes
32756 SYNOPSIS
32757 THR TSH #include <pthread.h> 32758 int pthread_condattr_getpshared (const pthread_condattr_t *restrict attr, 32759 int *restrict pshared ); 32760 int pthread_condattr_setpshared (pthread_condattr_t * attr, 32761 int pshared );
32762
32763 DESCRIPTION 32764 The pthread_condattr_getpshared () function shall obtain the value of the process-shared attribute 32765 from the attributes object referenced by attr . The pthread_condattr_setpshared () function shall set 32766 the process-shared attribute in an initialized attributes object referenced by attr .
32767 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition 32768 variable to be operated upon by any thread that has access to the memory where the condition 32769 variable is allocated, even if the condition variable is allocated in memory that is shared by 32770 multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the 32771 condition variable shall only be operated upon by threads created within the same process as the 32772 thread that initialized the condition variable; if threads of differing processes attempt to operate 32773 on such a condition variable, the behavior is undefined. The default value of the attribute is 32774 PTHREAD_PROCESS_PRIVATE.
32775 RETURN VALUE 32776 If successful, the pthread_condattr_setpshared () function shall return zero; otherwise, an error 32777 number shall be returned to indicate the error.
32778 If successful, the pthread_condattr_getpshared () function shall return zero and store the value of 32779 the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, 32780 an error number shall be returned to indicate the error.
32781 ERRORS 32782 The pthread_condattr_getpshared () and pthread_condattr_setpshared () functions may fail if:
32783 [EINVAL] The value specified by attr is invalid.
32784 The pthread_condattr_setpshared () function may fail if:
32785 [EINVAL] The new value specified for the attribute is outside the range of legal values 32786 for that attribute.
32787 These functions shall not return an error code of [EINTR].
32788 EXAMPLES 32789 None.
32790 APPLICATION USAGE 32791 None.
32792 RATIONALE 32793 None.
32794 FUTURE DIRECTIONS 32795 None.
32796 SEE ALSO 32797 pthread_create (), pthread_cond_destroy (), pthread_condattr_destroy (), pthread_mutex_destroy (), the 32798 Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
32799 CHANGE HISTORY 32800 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32801 Issue 6 32802 The pthread_condattr_getpshared () and pthread_condattr_setpshared () functions are marked as part 32803 of the Threads and Thread Process-Shared Synchronization options.
32804 The restrict keyword is added to the pthread_condattr_getpshared () prototype for alignment with 32805 the ISO/IEC 9899: 1999 standard.
32832 NAME 32833 pthread_create ” thread creation
32834 SYNOPSIS
32835 THR #include <pthread.h> 32836 int pthread_create (pthread_t *restrict thread , 32837 const pthread_attr_t *restrict attr , 32838 void * (* start_routine) (void*), void *restrict arg );
32839
32840 DESCRIPTION 32841 The pthread_create () function shall create a new thread, with attributes specified by attr , within a 32842 process. If attr is NULL, the default attributes shall be used. If the attributes specified by attr are 32843 modified later, the thread's attributes shall not be affected. Upon successful completion, 32844 pthread_create () shall store the ID of the created thread in the location referenced by thread .
32845 The thread is created executing start_routine with arg as its sole argument. If the start_routine 32846 returns, the effect shall be as if there was an implicit call to pthread_exit () using the return value 32847 of start_routine as the exit status. Note that the thread in which main () was originally invoked 32848 differs from this. When it returns from main (), the effect shall be as if there was an implicit call 32849 to exit () using the return value of main () as the exit status.
32850 The signal state of the new thread shall be initialized as follows:
32851 The signal mask shall be inherited from the creating thread.
32852 The set of signals pending for the new thread shall be empty.
32853 The floating-point environment shall be inherited from the creating thread.
32854 If pthread_create () fails, no new thread is created and the contents of the location referenced by 32855 thread are undefined.
32856 TCT If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time clock 32857 accessible, and the initial value of this clock shall be set to zero.
32858 RETURN VALUE 32859 If successful, the pthread_create () function shall return zero; otherwise, an error number shall be 32860 returned to indicate the error.
32861 ERRORS
32862 The pthread_create () function shall fail if:
32863 [EAGAIN] The system lacked the necessary resources to create another thread, or the 32864 system-imposed limit on the total number of threads in a process 32865 {PTHREAD_THREADS_MAX} would be exceeded.
32866 [EINVAL] The value specified by attr is invalid. 32867 [EPERM] The caller does not have appropriate permission to set the required 32868 scheduling parameters or scheduling policy.
32869 The pthread_create () function shall not return an error code of [EINTR].
32870 EXAMPLES 32871 None.
32872 APPLICATION USAGE 32873 None.
32874 RATIONALE 32875 A suggested alternative to pthread_create () would be to define two separate operations: create 32876 and start. Some applications would find such behavior more natural. Ada, in particular, 32877 separates the "creation" of a task from its "activation".
32878 Splitting the operation was rejected by the standard developers for many reasons:
32879 The number of calls required to start a thread would increase from one to two and thus place 32880 an additional burden on applications that do not require the additional synchronization. The 32881 second call, however, could be avoided by the additional complication of a start-up state 32882 attribute.
32883 An extra state would be introduced: "created but not started". This would require the 32884 standard to specify the behavior of the thread operations when the target has not yet started 32885 executing.
32886 For those applications that require such behavior, it is possible to simulate the two separate 32887 steps with the facilities that are currently provided. The start_routine () can synchronize by 32888 waiting on a condition variable that is signaled by the start operation.
32889 An Ada implementor can choose to create the thread at either of two points in the Ada program: 32890 when the task object is created, or when the task is activated (generally at a "begin"). If the first 32891 approach is adopted, the start_routine () needs to wait on a condition variable to receive the 32892 order to begin "activation". The second approach requires no such condition variable or extra 32893 synchronization. In either approach, a separate Ada task control block would need to be created 32894 when the task object is created to hold rendezvous queues, and so on.
32895 An extension of the preceding model would be to allow the state of the thread to be modified 32896 between the create and start. This would allow the thread attributes object to be eliminated. This 32897 has been rejected because:
32898 All state in the thread attributes object has to be able to be set for the thread. This would 32899 require the definition of functions to modify thread attributes. There would be no reduction 32900 in the number of function calls required to set up the thread. In fact, for an application that 32901 creates all threads using identical attributes, the number of function calls required to set up 32902 the threads would be dramatically increased. Use of a thread attributes object permits the 32903 application to make one set of attribute setting function calls. Otherwise, the set of attribute 32904 setting function calls needs to be made for each thread creation.
32905 Depending on the implementation architecture, functions to set thread state would require 32906 kernel calls, or for other implementation reasons would not be able to be implemented as 32907 macros, thereby increasing the cost of thread creation.
32908 The ability for applications to segregate threads by class would be lost.
32909 Another suggested alternative uses a model similar to that for process creation, such as "thread 32910 fork". The fork semantics would provide more flexibility and the "create" function can be 32911 implemented simply by doing a thread fork followed immediately by a call to the desired "start 32912 routine" for the thread. This alternative has these problems:
32913 For many implementations, the entire stack of the calling thread would need to be 32914 duplicated, since in many architectures there is no way to determine the size of the calling 32915 frame.
32916 Efficiency is reduced since at least some part of the stack has to be copied, even though in 32917 most cases the thread never needs the copied context, since it merely calls the desired start 32918 routine.
32919 FUTURE DIRECTIONS 32920 None.
32921 SEE ALSO 32922 fork (), pthread_exit (), pthread_join (), the Base Definitions volume of IEEE Std 1003.1-2001, 32923 < pthread.h>
32924 CHANGE HISTORY 32925 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32926 Issue 6 32927 The pthread_create () function is marked as part of the Threads option.
32928 The following new requirements on POSIX implementations derive from alignment with the 32929 Single UNIX Specification:
32930 The [EPERM] mandatory error condition is added.
32931 The thread CPU-time clock semantics are added for alignment with IEEE Std 1003.1d-1999.
32932 The restrict keyword is added to the pthread_create () prototype for alignment with the 32933 ISO/IEC 9899: 1999 standard.
32934 The DESCRIPTION is updated to make it explicit that the floating-point environment is 32935 inherited from the creating thread.
32936 NAME 32937 pthread_detach ” detach a thread
32938 SYNOPSIS
32939 THR #include <pthread.h> 32940 int pthread_detach (pthread_t thread );
32941
32942 DESCRIPTION 32943 The pthread_detach () function shall indicate to the implementation that storage for the thread 32944 thread can be reclaimed when that thread terminates. If thread has not terminated, 32945 pthread_detach () shall not cause it to terminate. The effect of multiple pthread_detach () calls on 32946 the same target thread is unspecified.
32947 RETURN VALUE 32948 If the call succeeds, pthread_detach () shall return 0; otherwise, an error number shall be returned 32949 to indicate the error.
32950 ERRORS 32951 The pthread_detach () function shall fail if:
32952 [EINVAL] The implementation has detected that the value specified by thread does not 32953 refer to a joinable thread.
32954 [ESRCH] No thread could be found corresponding to that specified by the given thread 32955 ID.
32956 The pthread_detach () function shall not return an error code of [EINTR].
32957 EXAMPLES 32958 None.
32959 APPLICATION USAGE 32960 None.
32961 RATIONALE 32962 The pthread_join () or pthread_detach () functions should eventually be called for every thread that 32963 is created so that storage associated with the thread may be reclaimed.
32964 It has been suggested that a "detach" function is not necessary; the detachstate thread creation 32965 attribute is sufficient, since a thread need never be dynamically detached. However, need arises 32966 in at least two cases:
32967 1. In a cancelation handler for a pthread_join () it is nearly essential to have a pthread_detach () 32968 function in order to detach the thread on which pthread_join () was waiting. Without it, it 32969 would be necessary to have the handler do another pthread_join () to attempt to detach the 32970 thread, which would both delay the cancelation processing for an unbounded period and 32971 introduce a new call to pthread_join (), which might itself need a cancelation handler. A 32972 dynamic detach is nearly essential in this case.
32973 2. In order to detach the "initial thread" (as may be desirable in processes that set up server 32974 threads).
32975 FUTURE DIRECTIONS 32976 None.
32977 SEE ALSO 32978 pthread_join (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
32979 CHANGE HISTORY 32980 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
32981 Issue 6 32982 The pthread_detach () function is marked as part of the Threads option.
33016 NAME 33017 pthread_exit ”thread termination
33018 SYNOPSIS
33019 THR #include <pthread.h> 33020 void pthread_exit (void * value_ptr);
33021
33022 DESCRIPTION 33023 The pthread_exit () function shall terminate the calling thread and make the value value_ptr 33024 available to any successful join with the terminating thread. Any cancelation cleanup handlers 33025 that have been pushed and not yet popped shall be popped in the reverse order that they were 33026 pushed and then executed. After all cancelation cleanup handlers have been executed, if the 33027 thread has any thread-specific data, appropriate destructor functions shall be called in an 33028 unspecified order. Thread termination does not release any application visible process resources, 33029 including, but not limited to, mutexes and file descriptors, nor does it perform any process-level 33030 cleanup actions, including, but not limited to, calling any atexit () routines that may exist.
33031 An implicit call to pthread_exit () is made when a thread other than the thread in which main () 33032 was first invoked returns from the start routine that was used to create it. The function's return 33033 value shall serve as the thread's exit status.
33034 The behavior of pthread_exit () is undefined if called from a cancelation cleanup handler or 33035 destructor function that was invoked as a result of either an implicit or explicit call to 33036 pthread_exit ().
33037 After a thread has terminated, the result of access to local (auto) variables of the thread is 33038 undefined. Thus, references to local variables of the exiting thread should not be used for the 33039 pthread_exit () value_ptr parameter value.
33040 The process shall exit with an exit status of 0 after the last thread has been terminated. The 33041 behavior shall be as if the implementation called exit () with a zero argument at thread 33042 termination time.
33043 RETURN VALUE 33044 The pthread_exit () function cannot return to its caller.
33045 ERRORS 33046 No errors are defined.
33047 EXAMPLES 33048 None.
33049 APPLICATION USAGE 33050 None.
33051 RATIONALE 33052 The normal mechanism by which a thread terminates is to return from the routine that was 33053 specified in the pthread_create () call that started it. The pthread_exit () function provides the 33054 capability for a thread to terminate without requiring a return from the start routine of that 33055 thread, thereby providing a function analogous to exit ().
33056 Regardless of the method of thread termination, any cancelation cleanup handlers that have 33057 been pushed and not yet popped are executed, and the destructors for any existing thread-specific 33058 data are executed. This volume of IEEE Std 1003.1-2001 requires that cancelation 33059 cleanup handlers be popped and called in order. After all cancelation cleanup handlers have 33060 been executed, thread-specific data destructors are called, in an unspecified order, for each item 33061 of thread-specific data that exists in the thread. This ordering is necessary because cancelation 33062 cleanup handlers may rely on thread-specific data.
33063 As the meaning of the status is determined by the application (except when the thread has been 33064 canceled, in which case it is PTHREAD_CANCELED), the implementation has no idea what an 33065 illegal status value is, which is why no address error checking is done.
33066 FUTURE DIRECTIONS 33067 None.
33068 SEE ALSO 33069 exit (), pthread_create (), pthread_join (), the Base Definitions volume of IEEE Std 1003.1-2001, 33070 < pthread.h>
33071 CHANGE HISTORY 33072 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33073 Issue 6 33074 The pthread_exit () function is marked as part of the Threads option.
33075 NAME 33076 pthread_getconcurrency, pthread_setconcurrency ” get and set the level of concurrency
33077 SYNOPSIS
33078 XSI #include <pthread.h> 33079 int pthread_getconcurrency (void); 33080 int pthread_setconcurrency (int new _ level );
33081
33082 DESCRIPTION 33083 Unbound threads in a process may or may not be required to be simultaneously active. By 33084 default, the threads implementation ensures that a sufficient number of threads are active so that 33085 the process can continue to make progress. While this conserves system resources, it may not 33086 produce the most effective level of concurrency.
33087 The pthread_setconcurrency () function allows an application to inform the threads 33088 implementation of its desired concurrency level, new_level. The actual level of concurrency 33089 provided by the implementation as a result of this function call is unspecified.
33090 If new_level is zero, it causes the implementation to maintain the concurrency level at its 33091 discretion as if pthread_setconcurrency () had never been called.
33092 The pthread_getconcurrency () function shall return the value set by a previous call to the 33093 pthread_setconcurrency () function. If the pthread_setconcurrency () function was not previously 33094 called, this function shall return zero to indicate that the implementation is maintaining the 33095 concurrency level.
33096 A call to pthread_setconcurrency () shall inform the implementation of its desired concurrency 33097 level. The implementation shall use this as a hint, not a requirement.
33098 If an implementation does not support multiplexing of user threads on top of several kernel- 33099 scheduled entities, the pthread_setconcurrency () and pthread_getconcurrency () functions are 33100 provided for source code compatibility but they shall have no effect when called. To maintain 33101 the function semantics, the new_level parameter is saved when pthread_setconcurrency () is called 33102 so that a subsequent call to pthread_getconcurrency () shall return the same value.
33103 RETURN VALUE 33104 If successful, the pthread_setconcurrency () function shall return zero; otherwise, an error number 33105 shall be returned to indicate the error.
33106 The pthread_getconcurrency () function shall always return the concurrency level set by a previous 33107 call to pthread_setconcurrency (). If the pthread_setconcurrency () function has never been called, 33108 pthread_getconcurrency () shall return zero.
33109 ERRORS
33110 The pthread_setconcurrency () function shall fail if:
33111 [EINVAL] The value specified by new_level is negative. 33112 [EAGAIN] The value specific by new_level would cause a system resource to be exceeded.
33113 These functions shall not return an error code of [EINTR].
33114 EXAMPLES 33115 None.
33116 APPLICATION USAGE 33117 Use of these functions changes the state of the underlying concurrency upon which the 33118 application depends. Library developers are advised to not use the pthread_getconcurrency () and 33119 pthread_setconcurrency () functions since their use may conflict with an applications use of these 33120 functions.
33121 RATIONALE 33122 None.
33123 FUTURE DIRECTIONS 33124 None.
33125 SEE ALSO 33126 The Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
33127 CHANGE HISTORY 33128 First released in Issue 5.
33161 NAME 33162 pthread_getschedparam, pthread_setschedparam ” dynamic thread scheduling parameters 33163 access (REALTIME THREADS)
33164 SYNOPSIS
33165 THR TPS #include <pthread.h> 33166 int pthread_getschedparam (pthread_t thread, int *restrict policy, 33167 struct sched_param *restrict param ); 33168 int pthread_setschedparam (pthread_t thread, int policy, 33169 const struct sched_param * param );
33170
33171 DESCRIPTION 33172 The pthread_getschedparam () and pthread_setschedparam () functions shall, respectively, get and set 33173 the scheduling policy and parameters of individual threads within a multi-threaded process to 33174 be retrieved and set. For SCHED_FIFO and SCHED_RR, the only required member of the 33175 sched_param structure is the priority sched_priority. For SCHED_OTHER, the affected 33176 scheduling parameters are implementation-defined.
33177 The pthread_getschedparam () function shall retrieve the scheduling policy and scheduling 33178 parameters for the thread whose thread ID is given by thread and shall store those values in 33179 policy and param , respectively. The priority value returned from pthread_getschedparam () shall be 33180 the value specified by the most recent pthread_setschedparam (), pthread_setschedprio (), or 33181 pthread_create () call affecting the target thread. It shall not reflect any temporary adjustments to 33182 its priority as a result of any priority inheritance or ceiling functions. The pthread_setschedparam () 33183 function shall set the scheduling policy and associated scheduling parameters for the thread 33184 whose thread ID is given by thread to the policy and associated parameters provided in policy 33185 and param , respectively.
33186 The policy parameter may have the value SCHED_OTHER, SCHED_FIFO, or SCHED_RR. The 33187 scheduling parameters for the SCHED_OTHER policy are implementation-defined. The 33188 SCHED_FIFO and SCHED_RR policies shall have a single scheduling parameter, priority .
33189 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, then the policy argument may have the 33190 value SCHED_SPORADIC, with the exception for the pthread_setschedparam () function that if the 33191 scheduling policy was not SCHED_SPORADIC at the time of the call, it is implementation- 33192 defined whether the function is supported; in other words, the implementation need not allow 33193 the application to dynamically change the scheduling policy to SCHED_SPORADIC. The 33194 sporadic server scheduling policy has the associated parameters sched_ss_low_priority, 33195 sched_ss_repl_period, sched_ss_init_budget, sched_priority, and sched_ss_max_repl. The specified 33196 sched_ss_repl_period shall be greater than or equal to the specified sched_ss_init_budget for the 33197 function to succeed; if it is not, then the function shall fail. The value of sched_ss_max_repl shall 33198 be within the inclusive range [1,SS_REPL_MAX] for the function to succeed; if not, the function 33199 shall fail.
33200 If the pthread_setschedparam () function fails, the scheduling parameters shall not be changed for 33201 the target thread.
33202 RETURN VALUE 33203 If successful, the pthread_getschedparam () and pthread_setschedparam () functions shall return zero; 33204 otherwise, an error number shall be returned to indicate the error.
33205 ERRORS 33206 The pthread_getschedparam () function may fail if:
33207 [ESRCH] The value specified by thread does not refer to an existing thread.
33208 The pthread_setschedparam () function may fail if:
33209 [EINVAL] The value specified by policy or one of the scheduling parameters associated 33210 with the scheduling policy policy is invalid. 33211 [ENOTSUP] An attempt was made to set the policy or scheduling parameters to an 33212 unsupported value. 33213 TSP [ENOTSUP] An attempt was made to dynamically change the scheduling policy to 33214 SCHED_SPORADIC, and the implementation does not support this change. 33215 [EPERM] The caller does not have the appropriate permission to set either the 33216 scheduling parameters or the scheduling policy of the specified thread. 33217 [EPERM] The implementation does not allow the application to modify one of the 33218 parameters to the value specified. 33219 [ESRCH] The value specified by thread does not refer to a existing thread.
33220 These functions shall not return an error code of [EINTR].
33221 EXAMPLES 33222 None.
33223 APPLICATION USAGE 33224 None.
33225 RATIONALE 33226 None.
33227 FUTURE DIRECTIONS 33228 None.
33229 SEE ALSO 33230 pthread_setschedprio (), sched_getparam (), sched_getscheduler (), the Base Definitions volume of 33231 IEEE Std 1003.1-2001, < pthread.h>, < sched.h>
33232 CHANGE HISTORY 33233 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33234 Issue 6 33235 The pthread_getschedparam () and pthread_setschedparam () functions are marked as part of the 33236 Threads and Thread Execution Scheduling options.
33237 The [ENOSYS] error condition has been removed as stubs need not be provided if an 33238 implementation does not support the Thread Execution Scheduling option.
33239 The Open Group Corrigendum U026/2 is applied, correcting the prototype for the 33240 pthread_setschedparam () function so that its second argument is of type int.
33241 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999.
33242 The restrict keyword is added to the pthread_getschedparam () prototype for alignment with the 33243 ISO/IEC 9899: 1999 standard.
33244 The Open Group Corrigendum U047/1 is applied.
33245 IEEE PASC Interpretation 1003.1 #96 is applied, noting that priority values can also be set by a 33246 call to the pthread_setschedprio () function.
33302 NAME 33303 pthread_join ” wait for thread termination
33304 SYNOPSIS
33305 THR #include <pthread.h> 33306 int pthread_join (pthread_t thread, void ** value_ptr);
33307
33308 DESCRIPTION 33309 The pthread_join () function shall suspend execution of the calling thread until the target thread 33310 terminates, unless the target thread has already terminated. On return from a successful 33311 pthread_join () call with a non-NULL value_ptr argument, the value passed to pthread_exit () by 33312 the terminating thread shall be made available in the location referenced by value_ptr. When a 33313 pthread_join () returns successfully, the target thread has been terminated. The results of multiple 33314 simultaneous calls to pthread_join () specifying the same target thread are undefined. If the 33315 thread calling pthread_join () is canceled, then the target thread shall not be detached.
33316 It is unspecified whether a thread that has exited but remains unjoined counts against 33317 {PTHREAD_THREADS_MAX}.
33318 RETURN VALUE 33319 If successful, the pthread_join () function shall return zero; otherwise, an error number shall be 33320 returned to indicate the error.
33321 ERRORS 33322 The pthread_join () function shall fail if:
33323 [EINVAL] The implementation has detected that the value specified by thread does not 33324 refer to a joinable thread. 33325 [ESRCH] No thread could be found corresponding to that specified by the given thread 33326 ID.
33327 The pthread_join () function may fail if:
33328 [EDEADLK] A deadlock was detected or the value of thread specifies the calling thread.
33329 The pthread_join () function shall not return an error code of [EINTR].
33330 EXAMPLES 33331 An example of thread creation and deletion follows:
33332 typedef struct { 33333 int *ar; 33334 long n; 33335 } subarray; 33336 void * 33337 incer (void *arg) 33338 { 33339 long i; 33340 for (i = 0; i <((subarray *)arg) ->n; i++) 33341 ((subarray *) arg) ->ar[i]++; 33342 } 33343 int main (void) 33344 { 33345 int ar[1000000]; 33346 pthread_t th1, th2; 33347 subarray sb1, sb2; 33348 sb1.ar = &ar[0]; 33349 sb1.n = 500000; 33350 (void) pthread_create(&th1, NULL, incer, &sb1); 33351 sb2.ar = &ar[500000]; 33352 sb2.n = 500000; 33353 (void) pthread_create(&th2, NULL, incer, &sb2); 33354 (void) pthread_join(th1, NULL); 33355 (void) pthread_join(th2, NULL); 33356 return 0; 33357 }
33358 APPLICATION USAGE 33359 None.
33360 RATIONALE
33361 The pthread_join () function is a convenience that has proven useful in multi-threaded 33362 applications. It is true that a programmer could simulate this function if it were not provided by 33363 passing extra state as part of the argument to the start_routine (). The terminating thread would 33364 set a flag to indicate termination and broadcast a condition that is part of that state; a joining 33365 thread would wait on that condition variable. While such a technique would allow a thread to 33366 wait on more complex conditions (for example, waiting for multiple threads to terminate), 33367 waiting on individual thread termination is considered widely useful. Also, including the 33368 pthread_join () function in no way precludes a programmer from coding such complex waits. 33369 Thus, while not a primitive, including pthread_join () in this volume of IEEE Std 1003.1-2001 was 33370 considered valuable .
33371 The pthread_join () function provides a simple mechanism allowing an application to wait for a 33372 thread to terminate. After the thread terminates, the application may then choose to clean up 33373 resources that were used by the thread. For instance, after pthread_join () returns, any 33374 application-provided stack storage could be reclaimed.
33375 The pthread_join () or pthread_detach () function should eventually be called for every thread that 33376 is created with the detachstate attribute set to PTHREAD_CREATE_JOINABLE so that storage 33377 associated with the thread may be reclaimed.
33378 The interaction between pthread_join () and cancelation is well-defined for the following reasons:
33379 The pthread_join () function, like all other non-async-cancel-safe functions, can only be called 33380 with deferred cancelability type.
33381 Cancelation cannot occur in the disabled cancelability state.
33382 Thus, only the default cancelability state need be considered. As specified, either the 33383 pthread_join () call is canceled, or it succeeds, but not both. The difference is obvious to the 33384 application, since either a cancelation handler is run or pthread_join () returns. There are no race 33385 conditions since pthread_join () was called in the deferred cancelability state.
33386 FUTURE DIRECTIONS 33387 None.
33388 SEE ALSO 33389 pthread_create (), wait (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
33390 CHANGE HISTORY 33391 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33392 Issue 6 33393 The pthread_join () function is marked as part of the Threads option.
33621 NAME 33622 pthread_mutex_destroy, pthread_mutex_init ” destroy and initialize a mutex
33623 SYNOPSIS
33624 THR #include <pthread.h> 33625 int pthread_mutex_destroy (pthread_mutex_t * mutex ); 33626 int pthread_mutex_init (pthread_mutex_t *restrict mutex , 33627 const pthread_mutexattr_t *restrict attr ); 33628 pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
33629
33630 DESCRIPTION 33631 The pthread_mutex_destroy () function shall destroy the mutex object referenced by mutex ; the 33632 mutex object becomes, in effect, uninitialized. An implementation may cause 33633 pthread_mutex_destroy () to set the object referenced by mutex to an invalid value. A destroyed 33634 mutex object can be reinitialized using pthread_mutex_init (); the results of otherwise referencing 33635 the object after it has been destroyed are undefined.
33636 It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked 33637 mutex results in undefined behavior.
33638 The pthread_mutex_init () function shall initialize the mutex referenced by mutex with attributes 33639 specified by attr . If attr is NULL, the default mutex attributes are used; the effect shall be the 33640 same as passing the address of a default mutex attributes object. Upon successful initialization, 33641 the state of the mutex becomes initialized and unlocked.
33642 Only mutex itself may be used for performing synchronization. The result of referring to copies 33643 of mutex in calls to pthread_mutex_lock (), pthread_mutex_trylock (), pthread_mutex_unlock (), and 33644 pthread_mutex_destroy () is undefined.
33645 Attempting to initialize an already initialized mutex results in undefined behavior.
33646 In cases where default mutex attributes are appropriate, the macro 33647 PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. 33648 The effect shall be equivalent to dynamic initialization by a call to pthread_mutex_init () with 33649 parameter attr specified as NULL, except that no error checks are performed.
33650 RETURN VALUE 33651 If successful, the pthread_mutex_destroy () and pthread_mutex_init () functions shall return zero; 33652 otherwise, an error number shall be returned to indicate the error.
33653 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 33654 immediately at the beginning of processing for the function and shall cause an error return prior 33655 to modifying the state of the mutex specified by mutex .
33656 ERRORS 33657 The pthread_mutex_destroy () function may fail if:
33658 [EBUSY] The implementation has detected an attempt to destroy the object referenced 33659 by mutex while it is locked or referenced (for example, while being used in a 33660 pthread_cond_timedwait () or pthread_cond_wait ()) by another thread. 33661 [EINVAL] The value specified by mutex is invalid.
33662 The pthread_mutex_init () function shall fail if:
33663 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 33664 another mutex. 33665 [ENOMEM] Insufficient memory exists to initialize the mutex. 33666 [EPERM] The caller does not have the privilege to perform the operation.
33667 The pthread_mutex_init () function may fail if:
33668 [EBUSY] The implementation has detected an attempt to reinitialize the object 33669 referenced by mutex , a previously initialized, but not yet destroyed, mutex. 33670 [EINVAL] The value specified by attr is invalid.
33671 These functions shall not return an error code of [EINTR].
33672 EXAMPLES 33673 None.
33674 APPLICATION USAGE 33675 None.
33676 RATIONALE
33677 Alternate Implementations Possible
33678 This volume of IEEE Std 1003.1-2001 supports several alternative implementations of mutexes. 33679 An implementation may store the lock directly in the object of type pthread_mutex_t. 33680 Alternatively, an implementation may store the lock in the heap and merely store a pointer, 33681 handle, or unique ID in the mutex object. Either implementation has advantages or may be 33682 required on certain hardware configurations. So that portable code can be written that is 33683 invariant to this choice, this volume of IEEE Std 1003.1-2001 does not define assignment or 33684 equality for this type, and it uses the term "initialize" to reinforce the (more restrictive ) notion 33685 that the lock may actually reside in the mutex object itself.
33686 Note that this precludes an over-specification of the type of the mutex or condition variable and 33687 motivates the opaqueness of the type.
33688 An implementation is permitted, but not required, to have pthread_mutex_destroy () store an 33689 illegal value into the mutex. This may help detect erroneous programs that try to lock (or 33690 otherwise reference) a mutex that has already been destroyed.
33691 Tradeoff Between Error Checks and Performance Supported
33692 Many of the error checks were made optional in order to let implementations trade off 33693 performance versus degree of error checking according to the needs of their specific applications 33694 and execution environment. As a general rule, errors or conditions caused by the system (such as 33695 insufficient memory) always need to be reported, but errors due to an erroneously coded 33696 application (such as failing to provide adequate synchronization to prevent a mutex from being 33697 deleted while in use) are made optional.
33698 A wide range of implementations is thus made possible. For example, an implementation 33699 intended for application debugging may implement all of the error checks, but an 33700 implementation running a single, provably correct application under very tight performance 33701 constraints in an embedded computer might implement minimal checks. An implementation 33702 might even be provided in two versions, similar to the options that compilers provide: a full-checking, 33703 but slower version; and a limited-checking, but faster version. To forbid this 33704 optionality would be a disservice to users.
33705 By carefully limiting the use of "undefined behavior" only to things that an erroneous ( badly 33706 coded) application might do, and by defining that resource-not-available errors are mandatory, 33707 this volume of IEEE Std 1003.1-2001 ensures that a fully-conforming application is portable 33708 across the full range of implementations, while not forcing all implementations to add overhead 33709 to check for numerous things that a correct program never does.
33710 Why No Limits are Defined
33711 Defining symbols for the maximum number of mutexes and condition variables was considered 33712 but rejected because the number of these objects may change dynamically. Furthermore, many 33713 implementations place these objects into application memory; thus, there is no explicit 33714 maximum.
33715 Static Initializers for Mutexes and Condition Variables
33716 Providing for static initialization of statically allocated synchronization objects allows modules 33717 with private static synchronization variables to avoid runtime initialization tests and overhead. 33718 Furthermore, it simplifies the coding of self-initializing modules. Such modules are common in 33719 C libraries, where for various reasons the design calls for self-initialization instead of requiring 33720 an explicit module initialization function to be called. An example use of static initialization 33721 follows.
33722 Without static initialization, a self-initializing routine foo () might look as follows:
33723 static pthread_once_t foo_once = PTHREAD_ONCE_INIT; 33724 static pthread_mutex_t foo_mutex; 33725 void foo_init () 33726 { 33727 pthread_mutex_init (&foo_mutex, NULL); 33728 } 33729 void foo() 33730 { 33731 pthread_once (&foo_once, foo_init); 33732 pthread_mutex_lock (&foo_mutex); 33733 /* Do work. */ 33734 pthread_mutex_unlock (&foo_mutex); 33735 }
33736 With static initialization, the same routine could be coded as follows:
33737 static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; 33738 void foo() 33739 { 33740 pthread_mutex_lock(&foo_mutex); 33741 /* Do work. */ 33742 pthread_mutex_unlock(&foo_mutex); 33743 }
33744 Note that the static initialization both eliminates the need for the initialization test inside 33745 pthread_once () and the fetch of & foo_mutex to learn the address to be passed to 33746 pthread_mutex_lock () or pthread_mutex_unlock ().
33747 Thus, the C code written to initialize static objects is simpler on all systems and is also faster on a 33748 large class of systems; those where the (entire) synchronization object can be stored in 33749 application memory.
33750 Yet the locking performance question is likely to be raised for machines that require mutexes to 33751 be allocated out of special memory. Such machines actually have to have mutexes and possibly 33752 condition variables contain pointers to the actual hardware locks. For static initialization to work 33753 on such machines, pthread_mutex_lock () also has to test whether or not the pointer to the actual 33754 lock has been allocated. If it has not, pthread_mutex_lock () has to initialize it before use. The 33755 reservation of such resources can be made when the program is loaded, and hence return codes 33756 have not been added to mutex locking and condition variable waiting to indicate failure to 33757 complete initialization.
33758 This runtime test in pthread_mutex_lock () would at first seem to be extra work; an extra test is 33759 required to see whether the pointer has been initialized. On most machines this would actually 33760 be implemented as a fetch of the pointer, testing the pointer against zero, and then using the 33761 pointer if it has already been initialized. While the test might seem to add extra work, the extra 33762 effort of testing a register is usually negligible since no extra memory references are actually 33763 done. As more and more machines provide caches, the real expenses are memory references, not 33764 instructions executed.
33765 Alternatively, depending on the machine architecture, there are often ways to eliminate all 33766 overhead in the most important case: on the lock operations that occur after the lock has been 33767 initialized. This can be done by shifting more overhead to the less frequent operation: 33768 initialization. Since out-of-line mutex allocation also means that an address has to be 33769 dereferenced to find the actual lock, one technique that is widely applicable is to have static 33770 initialization store a bogus value for that address; in particular, an address that causes a machine 33771 fault to occur. When such a fault occurs upon the first attempt to lock such a mutex, validity 33772 checks can be done, and then the correct address for the actual lock can be filled in. Subsequent 33773 lock operations incur no extra overhead since they do not "fault". This is merely one technique 33774 that can be used to support static initialization, while not adversely affecting the performance of 33775 lock acquisition. No doubt there are other techniques that are highly machine-dependent.
33776 The locking overhead for machines doing out-of-line mutex allocation is thus similar for 33777 modules being implicitly initialized, where it is improved for those doing mutex allocation 33778 entirely inline. The inline case is thus made much faster, and the out-of-line case is not 33779 significantly worse .
33780 Besides the issue of locking performance for such machines, a concern is raised that it is possible 33781 that threads would serialize contending for initialization locks when attempting to finish 33782 initializing statically allocated mutexes. (Such finishing would typically involve taking an 33783 internal lock, allocating a structure, storing a pointer to the structure in the mutex, and releasing 33784 the internal lock.) First, many implementations would reduce such serialization by hashing on 33785 the mutex address. Second, such serialization can only occur a bounded number of times. In 33786 particular, it can happen at most as many times as there are statically allocated synchronization 33787 objects. Dynamically allocated objects would still be initialized via pthread_mutex_init () or 33788 pthread_cond_init ().
33789 Finally, if none of the above optimization techniques for out-of-line allocation yields sufficient 33790 performance for an application on some implementation, the application can avoid static 33791 initialization altogether by explicitly initializing all synchronization objects with the 33792 corresponding pthread_*_init () functions, which are supported by all implementations. An 33793 implementation can also document the tradeoffs and advise which initialization technique is 33794 more efficient for that particular implementation.
33795 Destroying Mutexes
33796 A mutex can be destroyed immediately after it is unlocked. For example, consider the following 33797 code:
33798 struct obj { 33799 pthread_mutex_t om; 33800 int refcnt; 33801 ... 33802 }; 33803 obj_done (struct obj *op) 33804 { 33805 pthread_mutex_lock (&op- >om); 33806 if (- -op- >refcnt == 0) { 33807 pthread_mutex_unlock (&op- >om); 33808 (A) pthread_mutex_destroy (&op- >om); 33809 (B) free(op); 33810 } else 33811 (C) pthread_mutex_unlock (&op->om); 33812 }
33813 In this case obj is reference counted and obj_done () is called whenever a reference to the object is 33814 dropped. Implementations are required to allow an object to be destroyed and freed and 33815 potentially unmapped (for example, lines A and B) immediately after the object is unlocked (line 33816 C).
33817 FUTURE DIRECTIONS 33818 None.
33819 SEE ALSO 33820 pthread_mutex_getprioceiling (), pthread_mutex_lock (), pthread_mutex_timedlock (), 33821 pthread_mutexattr_getpshared (), the Base Definitions volume of IEEE Std 1003.1-2001, 33822 < pthread.h>
33823 CHANGE HISTORY 33824 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33825 Issue 6 33826 The pthread_mutex_destroy () and pthread_mutex_init () functions are marked as part of the 33827 Threads option.
33828 The pthread_mutex_timedlock () function is added to the SEE ALSO section for alignment with 33829 IEEE Std 1003.1d-1999.
33830 IEEE PASC Interpretation 1003.1c #34 is applied, updating the DESCRIPTION. 33831 The restrict keyword is added to the pthread_mutex_init () prototype for alignment with the 33832 ISO/IEC 9899: 1999 standard.
33833 NAME 33834 pthread_mutex_getprioceiling, pthread_mutex_setprioceiling ” get and set the priority ceiling 33835 of a mutex ( REALTIME THREADS )
33836 SYNOPSIS
33837 THR TPP #include <pthread.h> 33838 int pthread_mutex_getprioceiling (const pthread_mutex_t *restrict mutex, 33839 int *restrict prioceiling ) ; 33840 int pthread_mutex_setprioceiling (pthread_mutex_t *restrict mutex, 33841 int prioceiling, int *restrict old _ ceiling );
33842
33843 DESCRIPTION 33844 The pthread_mutex_getprioceiling () function shall return the current priority ceiling of the mutex.
33845 The pthread_mutex_setprioceiling () function shall either lock the mutex if it is unlocked, or block 33846 until it can successfully lock the mutex, then it shall change the mutex's priority ceiling and 33847 release the mutex. When the change is successful, the previous value of the priority ceiling shall 33848 be returned in old_ceiling. The process of locking the mutex need not adhere to the priority 33849 protect protocol.
33850 If the pthread_mutex_setprioceiling () function fails, the mutex priority ceiling shall not be 33851 changed.
33852 RETURN VALUE 33853 If successful, the pthread_mutex_getprioceiling () and pthread_mutex_setprioceiling () functions shall 33854 return zero; otherwise, an error number shall be returned to indicate the error.
33855 ERRORS 33856 The pthread_mutex_getprioceiling () and pthread_mutex_setprioceiling () functions may fail if:
33857 [EINVAL] The priority requested by prioceiling is out of range. 33858 [EINVAL] The value specified by mutex does not refer to a currently existing mutex. 33859 [EPERM] The caller does not have the privilege to perform the operation.
33860 These functions shall not return an error code of [EINTR].
33861 EXAMPLES 33862 None.
33863 APPLICATION USAGE 33864 None.
33865 RATIONALE 33866 None.
33867 FUTURE DIRECTIONS 33868 None.
33869 SEE ALSO 33870 pthread_mutex_destroy (), pthread_mutex_lock (), pthread_mutex_timedlock (), the Base Definitions 33871 volume of IEEE Std 1003.1-2001, < pthread.h>
33872 CHANGE HISTORY 33873 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33874 Marked as part of the Realtime Threads Feature Group.
33875 Issue 6 33876 The pthread_mutex_getprioceiling () and pthread_mutex_setprioceiling () functions are marked as 33877 part of the Threads and Thread Priority Protection options.
33878 The [ENOSYS] error condition has been removed as stubs need not be provided if an 33879 implementation does not support the Thread Priority Protection option.
33880 The [ENOSYS] error denoting non-support of the priority ceiling protocol for mutexes has been 33881 removed. This is because if the implementation provides the functions (regardless of whether 33882 _POSIX_PTHREAD_PRIO_PROTECT is defined), they must function as in the DESCRIPTION 33883 and therefore the priority ceiling protocol for mutexes is supported.
33884 The pthread_mutex_timedlock () function is added to the SEE ALSO section for alignment with 33885 IEEE Std 1003.1d-1999.
33886 The restrict keyword is added to the pthread_mutex_getprioceiling () and 33887 pthread_mutex_setprioceiling () prototypes for alignment with the ISO/IEC 9899: 1999 standard.
33898 NAME 33899 pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock ” lock and unlock a 33900 mutex
33901 SYNOPSIS
33902 THR #include <pthread.h> 33903 int pthread_mutex_lock (pthread_mutex_t * mutex ); 33904 int pthread_mutex_trylock (pthread_mutex_t * mutex ); 33905 int pthread_mutex_unlock (pthread_mutex_t * mutex ); 33906
33907 DESCRIPTION 33908 The mutex object referenced by mutex shall be locked by calling pthread_mutex_lock (). If the 33909 mutex is already locked, the calling thread shall block until the mutex becomes available. This 33910 operation shall return with the mutex object referenced by mutex in the locked state with the 33911 calling thread as its owner.
33912 XSI If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection shall not be provided. 33913 Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it 33914 has not locked or a mutex which is unlocked, undefined behavior results.
33915 If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking shall be provided. 33916 If a thread attempts to relock a mutex that it has already locked, an error shall be returned. If a 33917 thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error 33918 shall be returned.
33919 If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex shall maintain the 33920 concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock 33921 count shall be set to one. Every time a thread relocks this mutex, the lock count shall be 33922 incremented by one. Each time the thread unlocks the mutex, the lock count shall be 33923 decremented by one. When the lock count reaches zero, the mutex shall become available for 33924 other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex 33925 which is unlocked, an error shall be returned.
33926 If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex 33927 results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling 33928 thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in 33929 undefined behavior.
33930 The pthread_mutex_trylock () function shall be equivalent to pthread_mutex_lock (), except that if 33931 the mutex object referenced by mutex is currently locked (by any thread, including the current 33932 thread), the call shall return immediately. If the mutex type is PTHREAD_MUTEX_RECURSIVE 33933 and the mutex is currently owned by the calling thread, the mutex lock count shall be 33934 incremented by one and the pthread_mutex_trylock () function shall immediately return success.
33935 XSI The pthread_mutex_unlock () function shall release the mutex object referenced by mutex . The 33936 manner in which a mutex is released is dependent upon the mutex's type attribute. If there are 33937 threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock () is called, 33938 resulting in the mutex becoming available, the scheduling policy shall determine which thread 33939 shall acquire the mutex.
33940 XSI (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become available 33941 when the count reaches zero and the calling thread no longer has any locks on this mutex.)
33942 If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the 33943 thread shall resume waiting for the mutex as if it was not interrupted.
33944 RETURN VALUE 33945 If successful, the pthread_mutex_lock () and pthread_mutex_unlock () functions shall return zero; 33946 otherwise, an error number shall be returned to indicate the error.
33947 The pthread_mutex_trylock () function shall return zero if a lock on the mutex object referenced by 33948 mutex is acquired. Otherwise, an error number is returned to indicate the error.
33949 ERRORS 33950 The pthread_mutex_lock () and pthread_mutex_trylock () functions shall fail if:
33951 [EINVAL] The mutex was created with the protocol attribute having the value 33952 PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than 33953 the mutex's current priority ceiling.
33954 The pthread_mutex_trylock () function shall fail if: 33955 [EBUSY] The mutex could not be acquired because it was already locked. 33956 The pthread_mutex_lock (), pthread_mutex_trylock (), and pthread_mutex_unlock () functions may 33957 fail if:
33958 [EINVAL] The value specified by mutex does not refer to an initialized mutex object. 33959 XSI [EAGAIN] The mutex could not be acquired because the maximum number of recursive 33960 locks for mutex has been exceeded.
33961 The pthread_mutex_lock () function may fail if:
33962 [EDEADLK] The current thread already owns the mutex.
33963 The pthread_mutex_unlock () function may fail if:
33964 [EPERM] The current thread does not own the mutex.
33965 These functions shall not return an error code of [EINTR].
33966 EXAMPLES 33967 None.
33968 APPLICATION USAGE 33969 None.
33970 RATIONALE 33971 Mutex objects are intended to serve as a low-level primitive from which other thread 33972 synchronization functions can be built. As such, the implementation of mutexes should be as 33973 efficient as possible, and this has ramifications on the features available at the interface.
33974 The mutex functions and the particular default settings of the mutex attributes have been 33975 motivated by the desire to not preclude fast, inlined implementations of mutex locking and 33976 unlocking.
33977 For example, deadlocking on a double-lock is explicitly allowed behavior in order to avoid 33978 requiring more overhead in the basic mechanism than is absolutely necessary. (More "friendly" 33979 mutexes that detect deadlock or that allow multiple locking by the same thread are easily 33980 constructed by the user via the other mechanisms provided. For example, pthread_self () can be 33981 used to record mutex ownership.) Implementations might also choose to provide such extended 33982 features as options via special mutex attributes.
33983 Since most attributes only need to be checked when a thread is going to be blocked, the use of 33984 attributes does not slow the (common) mutex-locking case.
33985 Likewise, while being able to extract the thread ID of the owner of a mutex might be desirable, it 33986 would require storing the current thread ID when each mutex is locked, and this could incur 33987 unacceptable levels of overhead. Similar arguments apply to a mutex_tryunlock operation.
33988 FUTURE DIRECTIONS 33989 None.
33990 SEE ALSO 33991 pthread_mutex_destroy (), pthread_mutex_timedlock (), the Base Definitions volume of 33992 IEEE Std 1003.1-2001, <pthread.h>
33993 CHANGE HISTORY 33994 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
33995 Issue 6 33996 The pthread_mutex_lock (), pthread_mutex_trylock (), and pthread_mutex_unlock () functions are 33997 marked as part of the Threads option.
33998 The following new requirements on POSIX implementations derive from alignment with the 33999 Single UNIX Specification:
34000 The behavior when attempting to relock a mutex is defined.
34001 The pthread_mutex_timedlock () function is added to the SEE ALSO section for alignment with 34002 IEEE Std 1003.1d-1999.
34013 NAME 34014 pthread_mutex_timedlock ” lock a mutex ( ADVANCED REALTIME )
34015 SYNOPSIS
34016 THR TMO #include <pthread.h> 34017 #include <time.h> 34018 int pthread_mutex_timedlock (pthread_mutex_t *restrict mutex , 34019 const struct timespec *restrict abs_timeout);
34020
34021 DESCRIPTION 34022 The pthread_mutex_timedlock () function shall lock the mutex object referenced by mutex . If the 34023 mutex is already locked, the calling thread shall block until the mutex becomes available as in 34024 the pthread_mutex_lock () function. If the mutex cannot be locked without waiting for another 34025 thread to unlock the mutex, this wait shall be terminated when the specified timeout expires .
34026 The timeout shall expire when the absolute time specified by abs_timeout passes, as measured by 34027 the clock on which timeouts are based (that is, when the value of that clock equals or exceeds 34028 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 34029 of the call.
34030 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; if 34031 the Timers option is not supported, the timeout shall be based on the system clock as returned 34032 by the time () function.
34033 The resolution of the timeout shall be the resolution of the clock on which it is based. The 34034 timespec data type is defined in the < time.h> header.
34035 Under no circumstance shall the function fail with a timeout if the mutex can be locked 34036 immediately. The validity of the abs_timeout parameter need not be checked if the mutex can be 34037 locked immediately.
34038 As a consequence of the priority inheritance rules (for mutexes initialized with the 34039 PRIO_INHERIT protocol), if a timed mutex wait is terminated because its timeout expires, the 34040 priority of the owner of the mutex shall be adjusted as necessary to reflect the fact that this 34041 thread is no longer among the threads waiting for the mutex.
34042 RETURN VALUE 34043 If successful, the pthread_mutex_timedlock () function shall return zero; otherwise, an error 34044 number shall be returned to indicate the error.
34045 ERRORS 34046 The pthread_mutex_timedlock () function shall fail if:
34047 [EINVAL] The mutex was created with the protocol attribute having the value 34048 PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than 34049 the mutex' current priority ceiling. 34050 [EINVAL] The process or thread would have blocked, and the abs_timeout parameter 34051 specified a nanoseconds field value less than zero or greater than or equal to 34052 1000 million. 34053 [ETIMEDOUT] The mutex could not be locked before the specified timeout expired .
34054 The pthread_mutex_timedlock () function may fail if:
34055 [EINVAL] The value specified by mutex does not refer to an initialized mutex object. 34056 XSI [EAGAIN] The mutex could not be acquired because the maximum number of recursive 34057 locks for mutex has been exceeded. 34058 [EDEADLK] The current thread already owns the mutex.
34059 This function shall not return an error code of [EINTR].
34060 EXAMPLES 34061 None.
34062 APPLICATION USAGE 34063 The pthread_mutex_timedlock () function is part of the Threads and Timeouts options and need 34064 not be provided on all implementations.
34065 RATIONALE 34066 None.
34067 FUTURE DIRECTIONS 34068 None.
34069 SEE ALSO 34070 pthread_mutex_destroy (), pthread_mutex_lock (), pthread_mutex_trylock (), time (), the Base 34071 Definitions volume of IEEE Std 1003.1-2001, < pthread.h>, < time.h>
34072 CHANGE HISTORY 34073 First released in Issue 6. Derived from IEEE Std 1003.1d-1999.
34083 NAME 34084 pthread_mutexattr_destroy, pthread_mutexattr_init ” destroy and initialize the mutex 34085 attributes object
34086 SYNOPSIS
34087 THR #include <pthread.h> 34088 int pthread_mutexattr_destroy (pthread_mutexattr_t * attr ); 34089 int pthread_mutexattr_init (pthread_mutexattr_t * attr );
34090
34091 DESCRIPTION 34092 The pthread_mutexattr_destroy () function shall destroy a mutex attributes object; the object 34093 becomes, in effect, uninitialized. An implementation may cause pthread_mutexattr_destroy () to 34094 set the object referenced by attr to an invalid value. A destroyed attr attributes object can be 34095 reinitialized using pthread_mutexattr_init (); the results of otherwise referencing the object after it 34096 has been destroyed are undefined.
34097 The pthread_mutexattr_init () function shall initialize a mutex attributes object attr with the 34098 default value for all of the attributes defined by the implementation.
34099 Results are undefined if pthread_mutexattr_init () is called specifying an already initialized attr 34100 attributes object.
34101 After a mutex attributes object has been used to initialize one or more mutexes, any function 34102 affecting the attributes object (including destruction) shall not affect any previously initialized 34103 mutexes.
34104 RETURN VALUE 34105 Upon successful completion, pthread_mutexattr_destroy () and pthread_mutexattr_init () shall 34106 return zero; otherwise, an error number shall be returned to indicate the error.
34107 ERRORS 34108 The pthread_mutexattr_destroy () function may fail if:
34109 [EINVAL] The value specified by attr is invalid.
34110 The pthread_mutexattr_init () function shall fail if:
34111 [ENOMEM] Insufficient memory exists to initialize the mutex attributes object.
34112 These functions shall not return an error code of [EINTR].
34113 EXAMPLES 34114 None.
34115 APPLICATION USAGE 34116 None.
34117 RATIONALE 34118 See pthread_attr_init () for a general explanation of attributes. Attributes objects allow 34119 implementations to experiment with useful extensions and permit extension of this volume of 34120 IEEE Std 1003.1-2001 without changing the existing functions. Thus, they provide for future 34121 extensibility of this volume of IEEE Std 1003.1-2001 and reduce the temptation to standardize 34122 prematurely on semantics that are not yet widely implemented or understood .
34123 Examples of possible additional mutex attributes that have been discussed are spin_only, 34124 limited spin, no_spin, recursive , and metered . (To explain what the latter attributes might mean: 34125 recursive mutexes would allow for multiple re-locking by the current owner; metered mutexes 34126 would transparently keep records of queue length, wait time, and so on.) Since there is not yet 34127 wide agreement on the usefulness of these resulting from shared implementation and usage 34128 experience, they are not yet specified in this volume of IEEE Std 1003.1-2001. Mutex attributes 34129 objects, however, make it possible to test out these concepts for possible standardization at a 34130 later time.
34131 Mutex Attributes and Performance
34132 Care has been taken to ensure that the default values of the mutex attributes have been defined 34133 such that mutexes initialized with the defaults have simple enough semantics so that the locking 34134 and unlocking can be done with the equivalent of a test-and-set instruction (plus possibly a few 34135 other basic instructions).
34136 There is at least one implementation method that can be used to reduce the cost of testing at 34137 lock-time if a mutex has non-default attributes. One such method that an implementation can 34138 employ (and this can be made fully transparent to fully conforming POSIX applications) is to 34139 secretly pre-lock any mutexes that are initialized to non-default attributes. Any later attempt to 34140 lock such a mutex causes the implementation to branch to the "slow path" as if the mutex were 34141 unavailable; then, on the slow path, the implementation can do the "real work" to lock a non-default 34142 mutex. The underlying unlock operation is more complicated since the implementation 34143 never really wants to release the pre-lock on this kind of mutex. This illustrates that, depending 34144 on the hardware, there may be certain optimizations that can be used so that whatever mutex 34145 attributes are considered "most frequently used" can be processed most efficiently.
34146 Process Shared Memory and Synchronization
34147 The existence of memory mapping functions in this volume of IEEE Std 1003.1-2001 leads to the 34148 possibility that an application may allocate the synchronization objects from this section in 34149 memory that is accessed by multiple processes (and therefore, by threads of multiple processes).
34150 In order to permit such usage, while at the same time keeping the usual case (that is, usage 34151 within a single process) efficient, a process-shared option has been defined.
34152 If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option, then the 34153 process-shared attribute can be used to indicate that mutexes or condition variables may be 34154 accessed by threads of multiple processes.
34155 The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the process-shared 34156 attribute so that the most efficient forms of these synchronization objects are created by default.
34157 Synchronization variables that are initialized with the PTHREAD_PROCESS_PRIVATE process- 34158 shared attribute may only be operated on by threads in the process that initialized them. 34159 Synchronization variables that are initialized with the PTHREAD_PROCESS_SHARED process- 34160 shared attribute may be operated on by any thread in any process that has access to it. In 34161 particular, these processes may exist beyond the lifetime of the initializing process. For example, 34162 the following code implements a simple counting semaphore in a mapped file that may be used 34163 by many processes.
34164 /* sem.h */ 34165 struct semaphore { 34166 pthread_mutex_t lock; 34167 pthread_cond_t nonzero; 34168 unsigned count; 34169 }; 34170 typedef struct semaphore semaphore_t; 34171 semaphore_t *semaphore_create (char *semaphore_name); 34172 semaphore_t *semaphore_open (char *semaphore_name); 34173 void semaphore_post (semaphore_t *semap); 34174 void semaphore_wait (semaphore_t *semap); 34175 void semaphore_close (semaphore_t *semap); 34176 /* sem.c */ 34177 #include <sys/types.h> 34178 #include <sys/stat.h> 34179 #include <sys/mman.h> 34180 #include <fcntl.h> 34181 #include <pthread.h> 34182 #include "sem.h" 34183 semaphore_t * 34184 semaphore_create (char *semaphore_name) 34185 { 34186 int fd; 34187 semaphore_t *semap; 34188 pthread_mutexattr_t psharedm; 34189 pthread_condattr_t psharedc; 34190 fd = open(semaphore_name, O_RDWR O_CREAT O_EXCL, 0666); 34191 if (fd <0) 34192 return (NULL); 34193 (void) ftruncate (fd, sizeof (semaphore_t)); 34194 (void) pthread_mutexattr_init (&psharedm); 34195 (void) pthread_mutexattr_setpshared (&psharedm, 34196 PTHREAD_PROCESS_SHARED); 34197 (void) pthread_condattr_init (&psharedc); 34198 (void) pthread_condattr_setpshared (&psharedc, 34199 PTHREAD_PROCESS_SHARED); 34200 semap = (semaphore_t *) mmap (NULL, sizeof (semaphore_t), 34201 PROT_READ PROT_WRITE, MAP_SHARED, 34202 fd, 0); 34203 close (fd); 34204 (void) pthread_mutex_init (&semap->lock, &psharedm); 34205 (void) pthread_cond_init (&semap->nonzero, &psharedc); 34206 semap->count = 0; 34207 return (semap); 34208 } 34209 semaphore_t * 34210 semaphore_open (char *semaphore_name) 34211 { 34212 int fd; 34213 semaphore_t *semap; 34214 fd = open (semaphore_name, O_RDWR, 0666); 34215 if (fd <0) 34216 return (NULL); 34217 semap = (semaphore_t *) mmap (NULL, sizeof (semaphore_t), 34218 PROT_READ PROT_WRITE, MAP_SHARED, 34219 fd, 0); 34220 close (fd); 34221 return (semap); 34222 } 34223 void 34224 semaphore_post (semaphore_t *semap) 34225 { 34226 pthread_mutex_lock (&semap->lock); 34227 if (semap->count == 0) 34228 pthread_cond_signal (&semapx->nonzero); 34229 semap->count++; 34230 pthread_mutex_unlock (&semap->lock); 34231 } 34232 void 34233 semaphore_wait (semaphore_t *semap) 34234 { 34235 pthread_mutex_lock (&semap->lock); 34236 while (semap->count == 0) 34237 pthread_cond_wait (&semap->nonzero, &semap->lock); 34238 semap->count--; 34239 pthread_mutex_unlock (&semap->lock); 34240 } 34241 void 34242 semaphore_close (semaphore_t *semap) 34243 { 34244 munmap ((void *) semap, sizeof (semaphore_t)); 34245 }
34246 The following code is for three separate processes that create, post, and wait on a semaphore in 34247 the file /tmp/semaphore. Once the file is created, the post and wait programs increment and 34248 decrement the counting semaphore (waiting and waking as required) even though they did not 34249 initialize the semaphore.
34250 /* create.c */ 34251 #include "pthread.h" 34252 #include "sem.h" 34253 int 34254 main() 34255 { 34256 semaphore_t *semap; 34257 semap = semaphore_create("/tmp/semaphore"); 34258 if (semap == NULL) 34259 exit(1); 34260 semaphore_close (semap); 34261 return (0); 34262 } 34263 /* post */ 34264 #include "pthread.h" 34265 #include "sem.h" 34266 int 34267 main() 34268 { 34269 semaphore_t *semap; 34270 semap = semaphore_open ("/tmp/semaphore"); 34271 if (semap == NULL) 34272 exit (1); 34273 semaphore_post (semap); 34274 semaphore_close (semap); 34275 return (0); 34276 } 34277 /* wait */ 34278 #include "pthread.h" 34279 #include "sem.h" 34280 int 34281 main () 34282 { 34283 semaphore_t *semap; 34284 semap = semaphore_open ("/tmp/semaphore"); 34285 if (semap == NULL) 34286 exit (1); 34287 semaphore_wait (semap); 34288 semaphore_close (semap); 34289 return (0); 34290 }
34291 FUTURE DIRECTIONS 34292 None.
34293 SEE ALSO 34294 pthread_cond_destroy (), pthread_create (), pthread_mutex_destroy (), pthread_mutexattr_destroy (), the 34295 Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
34296 CHANGE HISTORY 34297 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
34298 Issue 6 34299 The pthread_mutexattr_destroy () and pthread_mutexattr_init () functions are marked as part of the 34300 Threads option.
34301 IEEE PASC Interpretation 1003.1c #27 is applied, updating the ERRORS section.
34302 NAME 34303 pthread_mutexattr_getprioceiling, pthread_mutexattr_setprioceiling ” get and set the 34304 prioceiling attribute of the mutex attributes object ( REALTIME THREADS )
34305 SYNOPSIS 34306 THR TPP # include <pthread.h>
34307 int pthread_mutexattr_getprioceiling (const pthread_mutexattr_t * 34308 restrict attr, int *restrict prioceiling ); 34309 int pthread_mutexattr_setprioceiling (pthread_mutexattr_t * attr, 34310 int prioceiling ); 34311
34312 DESCRIPTION 34313 The pthread_mutexattr_getprioceiling () and pthread_mutexattr_setprioceiling () functions, 34314 respectively, shall get and set the priority ceiling attribute of a mutex attributes object pointed to 34315 by attr which was previously created by the function pthread_mutexattr_init ().
34316 The prioceiling attribute contains the priority ceiling of initialized mutexes. The values of 34317 prioceiling are within the maximum range of priorities defined by SCHED_FIFO.
34318 The prioceiling attribute defines the priority ceiling of initialized mutexes, which is the minimum 34319 priority level at which the critical section guarded by the mutex is executed. In order to avoid 34320 priority inversion, the priority ceiling of the mutex shall be set to a priority higher than or equal 34321 to the highest priority of all the threads that may lock that mutex. The values of prioceiling are 34322 within the maximum range of priorities defined under the SCHED_FIFO scheduling policy.
34323 RETURN VALUE 34324 Upon successful completion, the pthread_mutexattr_getprioceiling () and 34325 pthread_mutexattr_setprioceiling () functions shall return zero; otherwise, an error number shall be 34326 returned to indicate the error.
34327 ERRORS 34328 The pthread_mutexattr_getprioceiling () and pthread_mutexattr_setprioceiling () functions may fail if:
34329 [EINVAL] The value specified by attr or prioceiling is invalid. 34330 [EPERM] The caller does not have the privilege to perform the operation.
34331 These functions shall not return an error code of [EINTR].
34332 EXAMPLES 34333 None.
34334 APPLICATION USAGE 34335 None.
34336 RATIONALE 34337 None.
34338 FUTURE DIRECTIONS 34339 None.
34340 SEE ALSO 34341 pthread_cond_destroy (), pthread_create (), pthread_mutex_destroy (), the Base Definitions volume of 34342 IEEE Std 1003.1-2001, < pthread.h>
34343 CHANGE HISTORY 34344 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34345 Marked as part of the Realtime Threads Feature Group.
34346 Issue 6 34347 The pthread_mutexattr_getprioceiling () and pthread_mutexattr_setprioceiling () functions are 34348 marked as part of the Threads and Thread Priority Protection options.
34349 The [ENOSYS] error condition has been removed as stubs need not be provided if an 34350 implementation does not support the Thread Priority Protection option.
34351 The [ENOTSUP] error condition has been removed since these functions do not have a protocol 34352 argument.
34353 The restrict keyword is added to the pthread_mutexattr_getprioceiling () prototype for alignment 34354 with the ISO/IEC 9899: 1999 standard.
34355 NAME 34356 pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol ” get and set the protocol 34357 attribute of the mutex attributes object ( REALTIME THREADS )
34358 SYNOPSIS 34359 THR # include <pthread.h>
34360 TPPTPI int pthread_mutexattr_getprotocol (const pthread_mutexattr_t * 34361 restrict attr , int *restrict protocol ); 34362 int pthread_mutexattr_setprotocol (pthread_mutexattr_t * attr , 34363 int protocol ); 34364
34365 DESCRIPTION 34366 The pthread_mutexattr_getprotocol () and pthread_mutexattr_setprotocol () functions, respectively, 34367 shall get and set the protocol attribute of a mutex attributes object pointed to by attr which was 34368 previously created by the function pthread_mutexattr_init ().
34369 The protocol attribute defines the protocol to be followed in utilizing mutexes. The value of 34370 protocol may be one of:
34371 PTHREAD_PRIO_NONE 34372 TPI PTHREAD_PRIO_INHERIT 34373 TPP PTHREAD_PRIO_PROTECT 34374
34375 which are defined in the < pthread.h> header.
34376 When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute, its priority 34377 and scheduling shall not be affected by its mutex ownership.
34378 TPI When a thread is blocking higher priority threads because of owning one or more mutexes with 34379 the PTHREAD_PRIO_INHERIT protocol attribute, it shall execute at the higher of its priority or 34380 the priority of the highest priority thread waiting on any of the mutexes owned by this thread 34381 and initialized with this protocol.
34382 TPP When a thread owns one or more mutexes initialized with the PTHREAD_PRIO_PROTECT 34383 protocol, it shall execute at the higher of its priority or the highest of the priority ceilings of all 34384 the mutexes owned by this thread and initialized with this attribute, regardless of whether other 34385 threads are blocked on any of these mutexes or not.
34386 While a thread is holding a mutex which has been initialized with the 34387 PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it shall not be 34388 subject to being moved to the tail of the scheduling queue at its priority in the event that its 34389 original priority is changed, such as by a call to sched_setparam (). Likewise, when a thread 34390 unlocks a mutex that has been initialized with the PTHREAD_PRIO_INHERIT or 34391 PTHREAD_PRIO_PROTECT protocol attributes, it shall not be subject to being moved to the tail 34392 of the scheduling queue at its priority in the event that its original priority is changed.
34393 If a thread simultaneously owns several mutexes initialized with different protocols, it shall 34394 execute at the highest of the priorities that it would have obtained by each of these protocols.
34395 TPI When a thread makes a call to pthread_mutex_lock (), the mutex was initialized with the protocol 34396 attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked 34397 because the mutex is owned by another thread, that owner thread shall inherit the priority level 34398 of the calling thread as long as it continues to own the mutex. The implementation shall update 34399 its execution priority to the maximum of its assigned priority and all its inherited priorities. 34400 Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority 34401 inheritance effect shall be propagated to this other owner thread, in a recursive manner.
34402 RETURN VALUE 34403 Upon successful completion, the pthread_mutexattr_getprotocol () and 34404 pthread_mutexattr_setprotocol () functions shall return zero; otherwise, an error number shall be 34405 returned to indicate the error.
34406 ERRORS 34407 The pthread_mutexattr_setprotocol () function shall fall if:
34408 [ENOTSUP] The value specified by protocol is an unsupported value.
34409 The pthread_mutexattr_getprotocol () and pthread_mutexattr_setprotocol () functions may fail if:
34410 [EINVAL] The value specified by attr or protocol is invalid. 34411 [EPERM] The caller does not have the privilege to perform the operation.
34412 These functions shall not return an error code of [EINTR].
34413 EXAMPLES 34414 None.
34415 APPLICATION USAGE 34416 None.
34417 RATIONALE 34418 None.
34419 FUTURE DIRECTIONS 34420 None.
34421 SEE ALSO 34422 pthread_cond_destroy (), pthread_create (), pthread_mutex_destroy (), the Base Definitions volume of 34423 IEEE Std 1003.1-2001, < pthread.h>
34424 CHANGE HISTORY 34425 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34426 Marked as part of the Realtime Threads Feature Group.
34427 Issue 6 34428 The pthread_mutexattr_getprotocol () and pthread_mutexattr_setprotocol () functions are marked as 34429 part of the Threads option and either the Thread Priority Protection or Thread Priority 34430 Inheritance options.
34431 The [ENOSYS] error condition has been removed as stubs need not be provided if an 34432 implementation does not support the Thread Priority Protection or Thread Priority Inheritance 34433 options.
34434 The restrict keyword is added to the pthread_mutexattr_getprotocol () prototype for alignment 34435 with the ISO/IEC 9899:1999 standard.
34436 NAME 34437 pthread_mutexattr_getpshared, pthread_mutexattr_setpshared ” get and set the process-shared 34438 attribute
34439 SYNOPSIS
34440 THR TSH #include <pthread.h> 34441 int pthread_mutexattr_getpshared (const pthread_mutexattr_t * 34442 restrict attr, int *restrict pshared ); 34443 int pthread_mutexattr_setpshared(pthread_mutexattr_t * attr , 34444 int pshared );
34445
34446 DESCRIPTION 34447 The pthread_mutexattr_getpshared () function shall obtain the value of the process-shared attribute 34448 from the attributes object referenced by attr . The pthread_mutexattr_setpshared () function shall 34449 set the process-shared attribute in an initialized attributes object referenced by attr .
34450 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be 34451 operated upon by any thread that has access to the memory where the mutex is allocated, even if 34452 the mutex is allocated in memory that is shared by multiple processes. If the process-shared 34453 attribute is PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated upon by threads 34454 created within the same process as the thread that initialized the mutex; if threads of differing 34455 processes attempt to operate on such a mutex, the behavior is undefined. The default value of 34456 the attribute shall be PTHREAD_PROCESS_PRIVATE.
34457 RETURN VALUE 34458 Upon successful completion, pthread_mutexattr_setpshared () shall return zero; otherwise, an error 34459 number shall be returned to indicate the error.
34460 Upon successful completion, pthread_mutexattr_getpshared () shall return zero and store the value 34461 of the process-shared attribute of attr into the object referenced by the pshared parameter. 34462 Otherwise, an error number shall be returned to indicate the error.
34463 ERRORS 34464 The pthread_mutexattr_getpshared () and pthread_mutexattr_setpshared () functions may fail if:
34465 [EINVAL] The value specified by attr is invalid.
34466 The pthread_mutexattr_setpshared () function may fail if:
34467 [EINVAL] The new value specified for the attribute is outside the range of legal values 34468 for that attribute.
34469 These functions shall not return an error code of [EINTR].
34470 EXAMPLES 34471 None.
34472 APPLICATION USAGE 34473 None.
34474 RATIONALE 34475 None.
34476 FUTURE DIRECTIONS 34477 None.
34478 SEE ALSO 34479 pthread_cond_destroy (), pthread_create (), pthread_mutex_destroy (), pthread_mutexattr_destroy (), the 34480 Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
34481 CHANGE HISTORY 34482 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
34483 Issue 6 34484 The pthread_mutexattr_getpshared () and pthread_mutexattr_setpshared () functions are marked as 34485 part of the Threads and Thread Process-Shared Synchronization options.
34486 The restrict keyword is added to the pthread_mutexattr_getpshared () prototype for alignment 34487 with the ISO/IEC 9899: 1999 standard.
34488 NAME 34489 pthread_mutexattr_gettype, pthread_mutexattr_settype ” get and set the mutex type attribute
34490 SYNOPSIS
34491 XSI #include <pthread.h> 34492 int pthread_mutexattr_gettype (const pthread_mutexattr_t *restrict attr , 34493 int *restrict type ); 34494 int pthread_mutexattr_settype (pthread_mutexattr_t * attr , int type );
34495
34496 DESCRIPTION 34497 The pthread_mutexattr_gettype () and pthread_mutexattr_settype () functions, respectively, shall get 34498 and set the mutex type attribute. This attribute is set in the type parameter to these functions. The 34499 default value of the type attribute is PTHREAD_MUTEX_DEFAULT.
34500 The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types 34501 include:
34502 PTHREAD_MUTEX_NORMAL 34503 This type of mutex does not detect deadlock. A thread attempting to relock this mutex 34504 without first unlocking it shall deadlock. Attempting to unlock a mutex locked by a 34505 different thread results in undefined behavior. Attempting to unlock an unlocked mutex 34506 results in undefined behavior. 34507 PTHREAD_MUTEX_ERRORCHECK 34508 This type of mutex provides error checking. A thread attempting to relock this mutex 34509 without first unlocking it shall return with an error. A thread attempting to unlock a mutex 34510 which another thread has locked shall return with an error. A thread attempting to unlock 34511 an unlocked mutex shall return with an error. 34512 PTHREAD_MUTEX_RECURSIVE 34513 A thread attempting to relock this mutex without first unlocking it shall succeed in locking 34514 the mutex. The relocking deadlock which can occur with mutexes of type 34515 PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this 34516 mutex shall require the same number of unlocks to release the mutex before another thread 34517 can acquire the mutex. A thread attempting to unlock a mutex which another thread has 34518 locked shall return with an error. A thread attempting to unlock an unlocked mutex shall 34519 return with an error. 34520 PTHREAD_MUTEX_DEFAULT 34521 Attempting to recursively lock a mutex of this type results in undefined behavior. 34522 Attempting to unlock a mutex of this type which was not locked by the calling thread 34523 results in undefined behavior. Attempting to unlock a mutex of this type which is not 34524 locked results in undefined behavior. An implementation may map this mutex to one of the 34525 other mutex types.
34526 RETURN VALUE 34527 Upon successful completion, the pthread_mutexattr_gettype () function shall return zero and store 34528 the value of the type attribute of attr into the object referenced by the type parameter. Otherwise, 34529 an error shall be returned to indicate the error.
34530 If successful, the pthread_mutexattr_settype () function shall return zero; otherwise, an error 34531 number shall be returned to indicate the error.
34532 ERRORS 34533 The pthread_mutexattr_settype () function shall fail if:
34534 [EINVAL] The value type is invalid.
34535 The pthread_mutexattr_gettype () and pthread_mutexattr_settype () functions may fail if:
34536 [EINVAL] The value specified by attr is invalid.
34537 These functions shall not return an error code of [EINTR].
34538 EXAMPLES 34539 None.
34540 APPLICATION USAGE 34541 It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE mutex with 34542 condition variables because the implicit unlock performed for a pthread_cond_timedwait () or 34543 pthread_cond_wait () may not actually release the mutex (if it had been locked multiple times). If 34544 this happens, no other thread can satisfy the condition of the predicate.
34545 RATIONALE 34546 None.
34547 FUTURE DIRECTIONS 34548 None.
34549 SEE ALSO 34550 pthread_cond_timedwait (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
34551 CHANGE HISTORY 34552 First released in Issue 5.
34553 Issue 6 34554 The Open Group Corrigendum U033/3 is applied. The SYNOPSIS for 34555 pthread_mutexattr_gettype () is updated so that the first argument is of type const 34556 pthread_mutexattr_t*.
34557 The restrict keyword is added to the pthread_mutexattr_gettype () prototype for alignment with 34558 the ISO/IEC 9899: 1999 standard.
34604 NAME 34605 pthread_once ” dynamic package initialization
34606 SYNOPSIS
34607 THR #include <pthread.h> 34608 int pthread_once (pthread_once_t * once_control, 34609 void (* init_routine) (void)); 34610 pthread_once_t once_control = PTHREAD_ONCE_INIT;
34611
34612 DESCRIPTION 34613 The first call to pthread_once () by any thread in a process, with a given once_control, shall call the 34614 init_routine with no arguments. Subsequent calls of pthread_once () with the same once_control 34615 shall not call the init_routine. On return from pthread_once (), init_routine shall have completed. 34616 The once_control parameter shall determine whether the associated initialization routine has 34617 been called.
34618 The pthread_once () function is not a cancelation point. However, if init_routine is a cancelation 34619 point and is canceled, the effect on once_control shall be as if pthread_once () was never called.
34620 The constant PTHREAD_ONCE_INIT is defined in the < pthread.h> header.
34621 The behavior of pthread_once () is undefined if once_control has automatic storage duration or is 34622 not initialized by PTHREAD_ONCE_INIT.
34623 RETURN VALUE 34624 Upon successful completion, pthread_once () shall return zero; otherwise, an error number shall 34625 be returned to indicate the error.
34626 ERRORS 34627 The pthread_once () function may fail if:
34628 [EINVAL] If either once_control or init_routine is invalid.
34629 The pthread_once () function shall not return an error code of [EINTR].
34630 EXAMPLES 34631 None.
34632 APPLICATION USAGE 34633 None.
34634 RATIONALE 34635 Some C libraries are designed for dynamic initialization. That is, the global initialization for the 34636 library is performed when the first procedure in the library is called. In a single-threaded 34637 program, this is normally implemented using a static variable whose value is checked on entry 34638 to a routine, as follows:
34639 static int random_is_initialized = 0; 34640 extern int initialize_random (); 34641 int random_function () 34642 { 34643 if (random_is_initialized == 0) { 34644 initialize_random (); 34645 random_is_initialized = 1; 34646 } 34647 ... /* Operations performed after initialization. */ 34648 }
34649 To keep the same structure in a multi-threaded program, a new primitive is needed. Otherwise, 34650 library initialization has to be accomplished by an explicit call to a library-exported initialization 34651 function prior to any use of the library.
34652 For dynamic library initialization in a multi-threaded process, a simple initialization flag is not 34653 sufficient; the flag needs to be protected against modification by multiple threads 34654 simultaneously calling into the library. Protecting the flag requires the use of a mutex; however, 34655 mutexes have to be initialized before they are used. Ensuring that the mutex is only initialized 34656 once requires a recursive solution to this problem.
34657 The use of pthread_once () not only supplies an implementation-guaranteed means of dynamic 34658 initialization, it provides an aid to the reliable construction of multi-threaded and realtime 34659 systems. The preceding example then becomes:
34660 #include <pthread.h> 34661 static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; 34662 extern int initialize_random(); 34663 int random_function() 34664 { 34665 (void) pthread_once (&random_is_initialized, initialize_random); 34666 ... /* Operations performed after initialization. */ 34667 }
34668 Note that a pthread_once_t cannot be an array because some compilers do not accept the 34669 construct &< array_name>.
34670 FUTURE DIRECTIONS 34671 None.
34672 SEE ALSO 34673 The Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
34674 CHANGE HISTORY 34675 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
34676 Issue 6 34677 The pthread_once () function is marked as part of the Threads option.
34678 The [EINVAL] error is added as a may fail case for if either argument is invalid.
34679 NAME 34680 pthread_rwlock_destroy, pthread_rwlock_init ” destroy and initialize a read-write lock object
34681 SYNOPSIS
34682 THR #include <pthread.h> 34683 int pthread_rwlock_destroy(pthread_rwlock_t * rwlock ); 34684 int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, 34685 const pthread_rwlockattr_t *restrict attr );
34686
34687 DESCRIPTION 34688 The pthread_rwlock_destroy () function shall destroy the read-write lock object referenced by 34689 rwlock and release any resources used by the lock. The effect of subsequent use of the lock is 34690 undefined until the lock is reinitialized by another call to pthread_rwlock_init (). An 34691 implementation may cause pthread_rwlock_destroy () to set the object referenced by rwlock to an 34692 invalid value. Results are undefined if pthread_rwlock_destroy () is called when any thread holds 34693 rwlock . Attempting to destroy an uninitialized read-write lock results in undefined behavior.
34694 The pthread_rwlock_init () function shall allocate any resources required to use the read-write 34695 lock referenced by rwlock and initializes the lock to an unlocked state with attributes referenced 34696 by attr . If attr is NULL, the default read-write lock attributes shall be used; the effect is the same 34697 as passing the address of a default read-write lock attributes object. Once initialized, the lock can 34698 be used any number of times without being reinitialized. Results are undefined if 34699 pthread_rwlock_init () is called specifying an already initialized read-write lock. Results are 34700 undefined if a read-write lock is used without first being initialized.
34701 If the pthread_rwlock_init () function fails, rwlock shall not be initialized and the contents of rwlock 34702 are undefined.
34703 Only the object referenced by rwlock may be used for performing synchronization. The result of 34704 referring to copies of that object in calls to pthread_rwlock_destroy (), pthread_rwlock_rdlock (), 34705 pthread_rwlock_timedrdlock (), pthread_rwlock_timedwrlock (), pthread_rwlock_tryrdlock (), 34706 pthread_rwlock_trywrlock (), pthread_rwlock_unlock (), or pthread_rwlock_wrlock () is undefined.
34707 RETURN VALUE 34708 If successful, the pthread_rwlock_destroy () and pthread_rwlock_init () functions shall return zero; 34709 otherwise, an error number shall be returned to indicate the error.
34710 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 34711 immediately at the beginning of processing for the function and caused an error return prior to 34712 modifying the state of the read-write lock specified by rwlock .
34713 ERRORS 34714 The pthread_rwlock_destroy () function may fail if:
34715 [EBUSY] The implementation has detected an attempt to destroy the object referenced 34716 by rwlock while it is locked.
34717 [EINVAL] The value specified by rwlock is invalid.
34718 The pthread_rwlock_init () function shall fail if:
34719 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 34720 another read-write lock. 34721 [ENOMEM] Insufficient memory exists to initialize the read-write lock. 34722 [EPERM] The caller does not have the privilege to perform the operation.
34723 The pthread_rwlock_init () function may fail if:
34724 [EBUSY] The implementation has detected an attempt to reinitialize the object 34725 referenced by rwlock , a previously initialized but not yet destroyed read-write 34726 lock. 34727 [EINVAL] The value specified by attr is invalid.
34728 These functions shall not return an error code of [EINTR].
34729 EXAMPLES 34730 None.
34731 APPLICATION USAGE 34732 None.
34733 RATIONALE 34734 None.
34735 FUTURE DIRECTIONS 34736 None.
34737 SEE ALSO 34738 pthread_rwlock_rdlock (), pthread_rwlock_timedrdlock (), pthread_rwlock_timedwrlock (), 34739 pthread_rwlock_tryrdlock (), pthread_rwlock_trywrlock (), pthread_rwlock_unlock (), 34740 pthread_rwlock_wrlock (), the Base Definitions volume of IEEE Std 1003.1-2001. < pthread.h>
34741 CHANGE HISTORY 34742 First released in Issue 5.
34743 Issue 6 34744 The following changes are made for alignment with IEEE Std 1003.1j-2000:
34745 The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 34746 now part of the Threads option (previously it was part of the Read-Write Locks option in 34747 IEEE Std 1003.1j-2000 and also part of the XSI extension). The initializer macro is also deleted 34748 from the SYNOPSIS.
34749 The DESCRIPTION is updated as follows: 34750 ” It explicitly notes allocation of resources upon initialization of a read-write lock object. 34751 ” A paragraph is added specifying that copies of read-write lock objects may not be used.
34752 An [EINVAL] error is added to the ERRORS section for pthread_rwlock_init (), indicating that 34753 the rwlock value is invalid.
34754 The SEE ALSO section is updated.
34755 The restrict keyword is added to the pthread_rwlock_init () prototype for alignment with the 34756 ISO/IEC 9899: 1999 standard.
34757 NAME 34758 pthread_rwlock_rdlock, pthread_rwlock_tryrdlock ” lock a read-write lock object for reading
34759 SYNOPSIS
34760 THR #include <pthread.h> 34761 int pthread_rwlock_rdlock (pthread_rwlock_t * rwlock ); 34762 int pthread_rwlock_tryrdlock (pthread_rwlock_t * rwlock );
34763
34764 DESCRIPTION 34765 The pthread_rwlock_rdlock () function shall apply a read lock to the read-write lock referenced by 34766 rwlock . The calling thread acquires the read lock if a writer does not hold the lock and there are 34767 no writers blocked on the lock.
34768 TPS If the Thread Execution Scheduling option is supported, and the threads involved in the lock are 34769 executing with the scheduling policies SCHED_FIFO or SCHED_RR, the calling thread shall not 34770 acquire the lock if a writer holds the lock or if writers of higher or equal priority are blocked on 34771 the lock; otherwise, the calling thread shall acquire the lock.
34772 TSP TSP If the Threads Execution Scheduling option is supported, and the threads involved in the lock 34773 are executing with the SCHED_SPORADIC scheduling policy, the calling thread shall not 34774 acquire the lock if a writer holds the lock or if writers of higher or equal priority are blocked on 34775 the lock; otherwise, the calling thread shall acquire the lock.
34776 If the Thread Execution Scheduling option is not supported, it is implementation-defined 34777 whether the calling thread acquires the lock when a writer does not hold the lock and there are 34778 writers blocked on the lock. If a writer holds the lock, the calling thread shall not acquire the 34779 read lock. If the read lock is not acquired, the calling thread shall block until it can acquire the 34780 lock. The calling thread may deadlock if at the time the call is made it holds a write lock.
34781 A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the 34782 pthread_rwlock_rdlock () function n times). If so, the application shall ensure that the thread 34783 performs matching unlocks (that is, it calls the pthread_rwlock_unlock () function n times).
34784 The maximum number of simultaneous read locks that an implementation guarantees can be 34785 applied to a read-write lock shall be implementation-defined. The pthread_rwlock_rdlock () 34786 function may fail if this maximum would be exceeded.
34787 The pthread_rwlock_tryrdlock () function shall apply a read lock as in the pthread_rwlock_rdlock () 34788 function, with the exception that the function shall fail if the equivalent pthread_rwlock_rdlock () 34789 call would have blocked the calling thread. In no case shall the pthread_rwlock_tryrdlock () 34790 function ever block; it always either acquires the lock or fails and returns immediately.
34791 Results are undefined if any of these functions are called with an uninitialized read-write lock.
34792 If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the 34793 signal handler the thread resumes waiting for the read-write lock for reading as if it was not 34794 interrupted.
34795 RETURN VALUE 34796 If successful, the pthread_rwlock_rdlock () function shall return zero; otherwise, an error number 34797 shall be returned to indicate the error.
34798 The pthread_rwlock_tryrdlock () function shall return zero if the lock for reading on the read-write 34799 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned to 34800 indicate the error.
34801 ERRORS 34802 The pthread_rwlock_tryrdlock () function shall fail if:
34803 [EBUSY] The read-write lock could not be acquired for reading because a writer holds 34804 the lock or a writer with the appropriate priority was blocked on it.
34805 The pthread_rwlock_rdlock () and pthread_rwlock_tryrdlock () functions may fail if:
34806 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 34807 object. 34808 [EAGAIN] The read lock could not be acquired because the maximum number of read 34809 locks for rwlock has been exceeded.
34810 The pthread_rwlock_rdlock () function may fail if:
34811 [EDEADLK] The current thread already owns the read-write lock for writing.
34812 These functions shall not return an error code of [EINTR].
34813 EXAMPLES 34814 None.
34815 APPLICATION USAGE 34816 Applications using these functions may be subject to priority inversion, as discussed in the Base 34817 Definitions volume of IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.
34818 RATIONALE 34819 None.
34820 FUTURE DIRECTIONS 34821 None.
34822 SEE ALSO 34823 pthread_rwlock_destroy (), pthread_rwlock_timedrdlock (), pthread_rwlock_timedwrlock (), 34824 pthread_rwlock_trywrlock (), pthread_rwlock_unlock (), pthread_rwlock_wrlock (), the Base Definitions 34825 volume of IEEE Std 1003.1-2001, < pthread.h>
34826 CHANGE HISTORY 34827 First released in Issue 5.
34828 Issue 6 34829 The following changes are made for alignment with IEEE Std 1003.1j-2000:
34830 The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 34831 now part of the Threads option (previously it was part of the Read-Write Locks option in 34832 IEEE Std 1003.1j-2000 and also part of the XSI extension).
34833 The DESCRIPTION is updated as follows: 34834 ” Conditions under which writers have precedence over readers are specified. 34835 ” Failure of pthread_rwlock_tryrdlock () is clarified. 34836 ” A paragraph on the maximum number of read locks is added.
34837 In the ERRORS sections, [EBUSY] is modified to take into account write priority, and 34838 [EDEADLK] is deleted as a pthread_rwlock_tryrdlock () error.
34839 The SEE ALSO section is updated.
34840 NAME 34841 pthread_rwlock_timedrdlock ” lock a read-write lock for reading
34842 SYNOPSIS
34843 THR TMO #include <pthread.h> 34844 #include <time.h> 34845 int pthread_rwlock_timedrdlock (pthread_rwlock_t *restrict rwlock , 34846 const struct timespec *restrict abs _ timeout );
34847
34848 DESCRIPTION 34849 The pthread_rwlock_timedrdlock () function shall apply a read lock to the read-write lock 34850 referenced by rwlock as in the pthread_rwlock_rdlock () function. However, if the lock cannot be 34851 acquired without waiting for other threads to unlock the lock, this wait shall be terminated 34852 when the specified timeout expires. The timeout shall expire when the absolute time specified 34853 by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the 34854 value of that clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout 34855 has already been passed at the time of the call.
34856 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock. If 34857 the Timers option is not supported, the timeout shall be based on the system clock as returned 34858 by the time () function. The resolution of the timeout shall be the resolution of the clock on which 34859 it is based. The timespec data type is defined in the < time.h> header. Under no circumstances 34860 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 34861 abs_timeout parameter need not be checked if the lock can be immediately acquired.
34862 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a read-write 34863 lock via a call to pthread_rwlock_timedrdlock (), upon return from the signal handler the 34864 thread shall resume waiting for the lock as if it was not interrupted.
34865 The calling thread may deadlock if at the time the call is made it holds a write lock on rwlock . 34866 The results are undefined if this function is called with an uninitialized read-write lock.
34867 RETURN VALUE
34868 The pthread_rwlock_timedrdlock () function shall return zero if the lock for reading on the read-write 34869 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned 34870 to indicate the error.
34871 ERRORS 34872 The pthread_rwlock_timedrdlock () function shall fail if:
34873 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired.
34874 The pthread_rwlock_timedrdlock () function may fail if:
34875 [EAGAIN] The read lock could not be acquired because the maximum number of read 34876 locks for lock would be exceeded. 34877 [EDEADLK] The calling thread already holds a write lock on rwlock . 34878 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 34879 object, or the abs_timeout nanosecond value is less than zero or greater than or 34880 equal to 1000 million.
34881 This function shall not return an error code of [EINTR].
34882 EXAMPLES 34883 None.
34884 APPLICATION USAGE 34885 Applications using this function may be subject to priority inversion, as discussed in the Base 34886 Definitions volume of IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.
34887 The pthread_rwlock_timedrdlock () function is part of the Threads and Timeouts options and need 34888 not be provided on all implementations.
34889 RATIONALE 34890 None.
34891 FUTURE DIRECTIONS 34892 None.
34893 SEE ALSO 34894 pthread_rwlock_destroy (), pthread_rwlock_rdlock (), pthread_rwlock_timedwrlock (), 34895 pthread_rwlock_tryrdlock (), pthread_rwlock_trywrlock (), pthread_rwlock_unlock (), 34896 pthread_rwlock_wrlock (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>, 34897 < time.h>
34898 CHANGE HISTORY 34899 First released in Issue 6. Derived from IEEE Std 1003.1j-2000.
34900 NAME 34901 pthread_rwlock_timedwrlock ” lock a read-write lock for writing
34902 SYNOPSIS
34903 THR TMO #include <pthread.h> 34904 #include <time.h> 34905 int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict rwlock, 34906 const struct timespec *restrict abs_timeout);
34907
34908 DESCRIPTION 34909 The pthread_rwlock_timedwrlock () function shall apply a write lock to the read-write lock 34910 referenced by rwlock as in the pthread_rwlock_wrlock () function. However, if the lock cannot be 34911 acquired without waiting for other threads to unlock the lock, this wait shall be terminated 34912 when the specified timeout expires. The timeout shall expire when the absolute time specified 34913 by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the 34914 value of that clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout 34915 has already been passed at the time of the call.
34916 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock. If 34917 the Timers option is not supported, the timeout shall be based on the system clock as returned 34918 by the time () function. The resolution of the timeout shall be the resolution of the clock on which 34919 it is based. The timespec data type is defined in the < time.h> header. Under no circumstances 34920 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 34921 abs_timeout parameter need not be checked if the lock can be immediately acquired.
34922 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a read-write 34923 lock via a call to pthread_rwlock_timedwrlock (), upon return from the signal handler the 34924 thread shall resume waiting for the lock as if it was not interrupted.
34925 The calling thread may deadlock if at the time the call is made it holds the read-write lock. The 34926 results are undefined if this function is called with an uninitialized read-write lock.
34927 RETURN VALUE 34928 The pthread_rwlock_timedwrlock () function shall return zero if the lock for writing on the read-write 34929 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned 34930 to indicate the error.
34931 ERRORS 34932 The pthread_rwlock_timedwrlock () function shall fail if:
34933 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired.
34934 The pthread_rwlock_timedwrlock () function may fail if:
34935 [EDEADLK] The calling thread already holds the rwlock . 34936 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 34937 object, or the abs_timeout nanosecond value is less than zero or greater than or 34938 equal to 1000 million.
34939 This function shall not return an error code of [EINTR].
34940 EXAMPLES 34941 None.
34942 APPLICATION USAGE 34943 Applications using this function may be subject to priority inversion, as discussed in the Base 34944 Definitions volume of IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.
34945 The pthread_rwlock_timedwrlock () function is part of the Threads and Timeouts options and need 34946 not be provided on all implementations.
34947 RATIONALE 34948 None.
34949 FUTURE DIRECTIONS 34950 None.
34951 SEE ALSO 34952 pthread_rwlock_destroy (), pthread_rwlock_rdlock (), pthread_rwlock_timedrdlock (), 34953 pthread_rwlock_tryrdlock (), pthread_rwlock_trywrlock (), pthread_rwlock_unlock (), 34954 pthread_rwlock_wrlock (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>, 34955 < time.h>
34956 CHANGE HISTORY 34957 First released in Issue 6. Derived from IEEE Std 1003.1j-2000.
34966 NAME 34967 pthread_rwlock_trywrlock, pthread_rwlock_wrlock ” lock a read-write lock object for writing
34968 SYNOPSIS
34969 THR #include <pthread.h> 34970 int pthread_rwlock_trywrlock (pthread_rwlock_t * rwlock ); 34971 int pthread_rwlock_wrlock (pthread_rwlock_t * rwlock );
34972
34973 DESCRIPTION 34974 The pthread_rwlock_trywrlock () function shall apply a write lock like the pthread_rwlock_wrlock () 34975 function, with the exception that the function shall fail if any thread currently holds rwlock (for 34976 reading or writing).
34977 The pthread_rwlock_wrlock () function shall apply a write lock to the read-write lock referenced 34978 by rwlock . The calling thread acquires the write lock if no other thread (reader or writer) holds 34979 the read-write lock rwlock . Otherwise, the thread shall block until it can acquire the lock. The 34980 calling thread may deadlock if at the time the call is made it holds the read-write lock (whether a 34981 read or write lock).
34982 Implementations may favor writers over readers to avoid writer starvation .
34983 Results are undefined if any of these functions are called with an uninitialized read-write lock.
34984 If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the 34985 signal handler the thread resumes waiting for the read-write lock for writing as if it was not 34986 interrupted.
34987 RETURN VALUE 34988 The pthread_rwlock_trywrlock () function shall return zero if the lock for writing on the read-write 34989 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned to 34990 indicate the error.
34991 If successful, the pthread_rwlock_wrlock () function shall return zero; otherwise, an error number 34992 shall be returned to indicate the error.
34993 ERRORS 34994 The pthread_rwlock_trywrlock () function shall fail if:
34995 [EBUSY] The read-write lock could not be acquired for writing because it was already 34996 locked for reading or writing.
34997 The pthread_rwlock_trywrlock () and pthread_rwlock_wrlock () functions may fail if:
34998 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 34999 object.
35000 The pthread_rwlock_wrlock () function may fail if:
35001 [EDEADLK] The current thread already owns the read-write lock for writing or reading.
35002 These functions shall not return an error code of [EINTR].
35003 EXAMPLES 35004 None.
35005 APPLICATION USAGE 35006 Applications using these functions may be subject to priority inversion, as discussed in the Base 35007 Definitions volume of IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.
35008 RATIONALE 35009 None.
35010 FUTURE DIRECTIONS 35011 None.
35012 SEE ALSO 35013 pthread_rwlock_destroy (), pthread_rwlock_rdlock (), pthread_rwlock_timedrdlock (), 35014 pthread_rwlock_timedwrlock (), pthread_rwlock_tryrdlock (), pthread_rwlock_unlock (), the Base 35015 Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
35016 CHANGE HISTORY 35017 First released in Issue 5.
35018 Issue 6 35019 The following changes are made for alignment with IEEE Std 1003.1j-2000:
35020 The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35021 now part of the Threads option (previously it was part of the Read-Write Locks option in 35022 IEEE Std 1003.1j-2000 and also part of the XSI extension).
35023 The [EDEADLK] error is deleted as a pthread_rwlock_trywrlock () error.
35024 The SEE ALSO section is updated.
35025 NAME 35026 pthread_rwlock_unlock_unlock a read-write lock object
35027 SYNOPSIS
35028 THR #include <pthread.h> 35029 int pthread_rwlock_unlock(pthread_rwlock_t * rwlock );
35030
35031 DESCRIPTION 35032 The pthread_rwlock_unlock () function shall release a lock held on the read-write lock object 35033 referenced by rwlock . Results are undefined if the read-write lock rwlock is not held by the 35034 calling thread.
35035 If this function is called to release a read lock from the read-write lock object and there are other 35036 read locks currently held on this read-write lock object, the read-write lock object remains in the 35037 read locked state. If this function releases the last read lock for this read-write lock object, the 35038 read-write lock object shall be put in the unlocked state with no owners .
35039 If this function is called to release a write lock for this read-write lock object, the read-write lock 35040 object shall be put in the unlocked state.
35041 If there are threads blocked on the lock when it becomes available, the scheduling policy shall 35042 TPS determine which thread(s) shall acquire the lock. If the Thread Execution Scheduling option is 35043 supported, when threads executing with the scheduling policies SCHED_FIFO, SCHED_RR, or 35044 SCHED_SPORADIC are waiting on the lock, they shall acquire the lock in priority order when 35045 the lock becomes available. For equal priority threads, write locks shall take precedence over 35046 read locks. If the Thread Execution Scheduling option is not supported, it is implementation- 35047 defined whether write locks take precedence over read locks.
35048 Results are undefined if any of these functions are called with an uninitialized read-write lock.
35049 RETURN VALUE 35050 If successful, the pthread_rwlock_unlock () function shall return zero; otherwise, an error number 35051 shall be returned to indicate the error.
35052 ERRORS 35053 The pthread_rwlock_unlock () function may fail if:
35054 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35055 object. 35056 [EPERM] The current thread does not hold a lock on the read-write lock.
35057 The pthread_rwlock_unlock () function shall not return an error code of [EINTR].
35058 EXAMPLES 35059 None.
35060 APPLICATION USAGE 35061 None.
35062 RATIONALE 35063 None.
35064 FUTURE DIRECTIONS 35065 None.
35066 SEE ALSO 35067 pthread_rwlock_destroy (), pthread_rwlock_rdlock (), pthread_rwlock_timedrdlock (), 35068 pthread_rwlock_timedwrlock (), pthread_rwlock_tryrdlock (), pthread_rwlock_trywrlock (), 35069 pthread_rwlock_wrlock (), the Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
35070 CHANGE HISTORY 35071 First released in Issue 5.
35072 Issue 6 35073 The following changes are made for alignment with IEEE Std 1003.1j-2000:
35074 The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35075 now part of the Threads option (previously it was part of the Read-Write Locks option in 35076 IEEE Std 1003.1j-2000 and also part of the XSI extension).
35077 The DESCRIPTION is updated as follows: 35078 ” The conditions under which writers have precedence over readers are specified. 35079 ” The concept of read-write lock owner is deleted.
35080 The SEE ALSO section is updated.
35089 NAME 35090 pthread_rwlockattr_destroy, pthread_rwlockattr_init ” destroy and initialize the read-write 35091 lock attributes object
35092 SYNOPSIS
35093 THR #include <pthread.h> 35094 int pthread_rwlockattr_destroy(pthread_rwlockattr_t * attr ); 35095 int pthread_rwlockattr_init(pthread_rwlockattr_t * attr );
35096
35097 DESCRIPTION 35098 The pthread_rwlockattr_destroy () function shall destroy a read-write lock attributes object. A 35099 destroyed attr attributes object can be reinitialized using pthread_rwlockattr_init (); the results of 35100 otherwise referencing the object after it has been destroyed are undefined. An implementation 35101 may cause pthread_rwlockattr_destroy () to set the object referenced by attr to an invalid value.
35102 The pthread_rwlockattr_init () function shall initialize a read-write lock attributes object attr with 35103 the default value for all of the attributes defined by the implementation.
35104 Results are undefined if pthread_rwlockattr_init () is called specifying an already initialized attr 35105 attributes object.
35106 After a read-write lock attributes object has been used to initialize one or more read-write locks, 35107 any function affecting the attributes object (including destruction) shall not affect any previously 35108 initialized read-write locks.
35109 RETURN VALUE 35110 If successful, the pthread_rwlockattr_destroy () and pthread_rwlockattr_init () functions shall return 35111 zero; otherwise, an error number shall be returned to indicate the error.
35112 ERRORS 35113 The pthread_rwlockattr_destroy () function may fail if:
35114 [EINVAL] The value specified by attr is invalid.
35115 The pthread_rwlockattr_init () function shall fail if:
35116 [ENOMEM] Insufficient memory exists to initialize the read-write lock attributes object.
35117 These functions shall not return an error code of [EINTR].
35118 EXAMPLES 35119 None.
35120 APPLICATION USAGE 35121 None.
35122 RATIONALE 35123 None.
35124 FUTURE DIRECTIONS 35125 None.
35126 SEE ALSO 35127 pthread_rwlock_destroy (), pthread_rwlockattr_getpshared (), pthread_rwlockattr_setpshared (), the 35128 Base Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
35129 CHANGE HISTORY 35130 First released in Issue 5.
35131 Issue 6 35132 The following changes are made for alignment with IEEE Std 1003.1j-2000:
35133 The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35134 now part of the Threads option (previously it was part of the Read-Write Locks option in 35135 IEEE Std 1003.1j-2000 and also part of the XSI extension).
35136 The SEE ALSO section is updated.
35137 NAME 35138 pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared ” get and set the process-shared 35139 attribute of the read-write lock attributes object
35140 SYNOPSIS
35141 THR TSH #include <pthread.h> 35142 int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t * 35143 restrict attr, int *restrict pshared ); 35144 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t * attr, 35145 int pshared );
35146
35147 DESCRIPTION 35148 The pthread_rwlockattr_getpshared () function shall obtain the value of the process-shared attribute 35149 from the initialized attributes object referenced by attr . The pthread_rwlockattr_setpshared () 35150 function shall set the process-shared attribute in an initialized attributes object referenced by attr .
35151 The process-shared attribute shall be set to PTHREAD_PROCESS_SHARED to permit a read- 35152 write lock to be operated upon by any thread that has access to the memory where the read-write 35153 lock is allocated, even if the read-write lock is allocated in memory that is shared by 35154 multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the read- 35155 write lock shall only be operated upon by threads created within the same process as the thread 35156 that initialized the read-write lock; if threads of differing processes attempt to operate on such a 35157 read-write lock, the behavior is undefined. The default value of the process-shared attribute shall 35158 be PTHREAD_PROCESS_PRIVATE.
35159 Additional attributes, their default values, and the names of the associated functions to get and 35160 set those attribute values are implementation-defined.
35161 RETURN VALUE 35162 Upon successful completion, the pthread_rwlockattr_getpshared () function shall return zero and 35163 store the value of the process-shared attribute of attr into the object referenced by the pshared 35164 parameter. Otherwise, an error number shall be returned to indicate the error.
35165 If successful, the pthread_rwlockattr_setpshared () function shall return zero; otherwise, an error 35166 number shall be returned to indicate the error.
35167 ERRORS 35168 The pthread_rwlockattr_getpshared () and pthread_rwlockattr_setpshared () functions may fail if:
35169 [EINVAL] The value specified by attr is invalid.
35170 The pthread_rwlockattr_setpshared () function may fail if:
35171 [EINVAL] The new value specified for the attribute is outside the range of legal values 35172 for that attribute.
35173 These functions shall not return an error code of [EINTR].
35174 EXAMPLES 35175 None.
35176 APPLICATION USAGE 35177 None.
35178 RATIONALE 35179 None.
35180 FUTURE DIRECTIONS 35181 None.
35182 SEE ALSO 35183 pthread_rwlock_destroy (), pthread_rwlockattr_destroy (), pthread_rwlockattr_init (), the Base 35184 Definitions volume of IEEE Std 1003.1-2001, < pthread.h>
35185 CHANGE HISTORY 35186 First released in Issue 5.
35187 ISSUE 6 35188 The following changes are made for alignment with IEEE Std 1003.1j-2000:
35189 The margin code in the SYNOPSIS is changed to THR TSH to indicate that the functionality 35190 is now part of the Threads option (previously it was part of the Read-Write Locks option in 35191 IEEE Std 1003.1j-2000 and also part of the XSI extension).
35192 The DESCRIPTION notes that additional attributes are implementation-defined.
35193 The SEE ALSO section is updated.
35194 The restrict keyword is added to the pthread_rwlockattr_getpshared () prototype for alignment 35195 with the ISO/IEC 9899: 1999 standard.
35214 NAME 35215 pthread_self ” get the calling thread ID
35216 SYNOPSIS
35217 THR #include <pthread.h> 35218 pthread_t pthread_self (void);
35219
35220 DESCRIPTION 35221 The pthread_self () function shall return the thread ID of the calling thread.
35222 RETURN VALUE 35223 Refer to the DESCRIPTION.
35224 ERRORS 35225 No errors are defined.
35226 The pthread_self () function shall not return an error code of [EINTR].
35227 EXAMPLES 35228 None.
35229 APPLICATION USAGE 35230 None.
35231 RATIONALE 35232 The pthread_self () function provides a capability similar to the getpid () function for processes 35233 and the rationale is the same: the creation call does not provide the thread ID to the created 35234 thread.
35235 FUTURE DIRECTIONS 35236 None.
35237 SEE ALSO 35238 pthread_create (), pthread_equal (), the Base Definitions volume of IEEE Std 1003.1-2001, 35239 < pthread.h>
35240 CHANGE HISTORY 35241 First released in Issue 5. Included for alignment with the POSIX Threads Extension.
35242 Issue 6 35243 The pthread_self () function is marked as part of the Threads option.
35244 NAME 35245 pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel ” set cancelability state
35246 SYNOPSIS
35247 THR #include <pthread.h> 35248 int pthread_setcancelstate(int state, int * oldstate ); 35249 int pthread_setcanceltype(int type, int * oldtype ); 35250 void pthread_testcancel(void);
35251
35252 DESCRIPTION 35253 The pthread_setcancelstate () function shall atomically both set the calling thread's cancelability 35254 state to the indicated state and return the previous cancelability state at the location referenced 35255 by oldstate . Legal values for state are PTHREAD_CANCEL_ENABLE and 35256 PTHREAD_CANCEL_DISABLE.
35257 The pthread_setcanceltype () function shall atomically both set the calling thread's cancelability 35258 type to the indicated type and return the previous cancelability type at the location referenced by 35259 oldtype . Legal values for type are PTHREAD_CANCEL_DEFERRED and 35260 PTHREAD_CANCEL_ASYNCHRONOUS.
35261 The cancelability state and type of any newly created threads, including the thread in which 35262 main () was first invoked, shall be PTHREAD_CANCEL_ENABLE and 35263 PTHREAD_CANCEL_DEFERRED respectively.
35264 The pthread_testcancel () function shall create a cancelation point in the calling thread. The 35265 pthread_testcancel () function shall have no effect if cancelability is disabled.
35266 RETURN VALUE 35267 If successful, the pthread_setcancelstate () and pthread_setcanceltype () functions shall return zero; 35268 otherwise, an error number shall be returned to indicate the error.
35269 ERRORS 35270 The pthread_setcancelstate () function may fail if:
35271 [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or 35272 PTHREAD_CANCEL_DISABLE.
35273 The pthread_setcanceltype () function may fail if:
35274 [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or 35275 PTHREAD_CANCEL_ASYNCHRONOUS.
35276 These functions shall not return an error code of [EINTR].
35277 EXAMPLES 35278 None.
35279 APPLICATION USAGE 35280 None.
35281 RATIONALE 35282 The pthread_setcancelstate () and pthread_setcanceltype () functions control the points at which a 35283 thread may be asynchronously canceled. For cancelation control to be usable in modular fashion, 35284 some rules need to be followed.
35285 An object can be considered to be a generalization of a procedure. It is a set of procedures and 35286 global variables written as a unit and called by clients not known by the object. Objects may 35287 depend on other objects.
35288 First, cancelability should only be disabled on entry to on object, never explicitly enabled. On 35289 exit from an object, the cancelability state should always be restored to its value on entry to the 35290 object.
35291 This follows from a modularity argument: if the client of an object (or the client of an object that 35292 uses that object) has disabled cancelability, it is because the client does not want to be concerned 35293 about cleaning up if the thread is canceled while executing some sequence of actions. If an object 35294 is called in such a state and it enables cancelability and a cancelation request is pending for that 35295 thread, then the thread is canceled, contrary to the wish of the client that disabled.
35296 Second, the cancelability type may be explicitly set to either deferred or asynchronous upon entry 35297 to an object. But as with the cancelability state, on exit from an object the cancelability type 35298 should always be restored to its value on entry to the object.
35299 Finally, only functions that are cancel-safe may be called from a thread that is asynchronously 35300 cancelable.
35301 FUTURE DIRECTIONS 35302 None.
35303 SEE ALSO 35304 pthread_cancel (), the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>
35305 CHANGE HISTORY 35306 First released in Issue 5. Included for alignment with the POSIX Threads Extensions.
35307 Issue 6 35308 The pthread_setcancelstate (), pthread_setcanceltype (), and pthread_testcancel () functions are marked 35309 as part of the Threads option.
35328 NAME 35329 pthread_setschedprio ” dynamic thread scheduling parameters access ( REALTIME 35330 THREADS )
35331 SYNOPSIS
35332 THR TPS #include <pthread.h> 35333 int pthread_setschedprio(pthread_t thread, int prio );
35334
35335 DESCRIPTION 35336 The pthread_setschedprio () function shall set the scheduling priority for the thread whose thread 35337 ID is given by thread to the value given by prio . See Scheduling Policies (on page 44) for a 35338 description on how this function call affects the ordering of the thread in the thread list for its 35339 new priority.
35340 If the pthread_setschedprio () function fails, the scheduling priority of the target thread shall not be 35341 changed.
35342 RETURN VALUE 35343 If successful, the pthread_setschedprio () function shall return zero; otherwise, an error number 35344 shall be returned to indicate the error.
35345 ERRORS 35346 The pthread_setschedprio () function may fail if:
35347 [EINVAL] The value of prio is invalid for the scheduling policy of the specified thread. 35348 [ENOTSUP] An attempt was made to set the priority to an unsupported value. 35349 [EPERM] The caller does not have the appropriate permission to set the scheduling 35350 policy of the specified thread. 35351 [EPERM] The implementation does not allow the application to modify the priority to 35352 the value specified. 35353 [ESRCH] The value specified by thread does not refer to an existing thread.
35354 The pthread_setschedprio () function shall not return an error code of [EINTR].
35355 EXAMPLES 35356 None.
35357 APPLICATION USAGE 35358 None.
35359 RATIONALE 35360 The pthread_setschedprio () function provides a way for an application to temporarily raise its 35361 priority and then lower it again, without having the undesired side effect of yielding to other 35362 threads of the same priority. This is necessary if the application is to implement its own 35363 strategies for bounding priority inversion, such as priority inheritance or priority ceilings. This 35364 capability is especially important if the implementation does not support the Thread Priority 35365 Protection or Thread Priority Inheritance options, but even if those options are supported it is 35366 needed if the application is to bound priority inheritance for other resources, such as 35367 semaphores.
35368 The standard developers considered that while it might be preferable conceptually to solve this 35369 problem by modifying the specification of pthread_setschedparam (), it was too late to make such a 35370 change, as there may be implementations that would need to be changed. Therefore, this new 35371 function was introduced.
35372 FUTURE DIRECTIONS 35373 None.
35374 SEE ALSO 35375 Scheduling Policies (on page 44), pthread_getschedparam (), the Base Definitions volume of 35376 IEEE Std 1003.1-2001, < pthread.h>
35377 CHANGE HISTORY 35378 First released in Issue 6. Included as a response to IEEE PASC Interpretation 1003.1 #96.
|