|
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.
 | 