1## 2## GNU Pth - The GNU Portable Threads 3## Copyright (c) 1999-2006 Ralf S. Engelschall <rse@engelschall.com> 4## 5## This file is part of GNU Pth, a non-preemptive thread scheduling 6## library which can be found at http://www.gnu.org/software/pth/. 7## 8## This library is free software; you can redistribute it and/or 9## modify it under the terms of the GNU Lesser General Public 10## License as published by the Free Software Foundation; either 11## version 2.1 of the License, or (at your option) any later version. 12## 13## This library is distributed in the hope that it will be useful, 14## but WITHOUT ANY WARRANTY; without even the implied warranty of 15## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16## Lesser General Public License for more details. 17## 18## You should have received a copy of the GNU Lesser General Public 19## License along with this library; if not, write to the Free Software 20## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 21## USA, or contact Ralf S. Engelschall <rse@engelschall.com>. 22## 23## pthread.pod: POSIX.1c Threads ("Pthreads") manual page for Pth 24## 25## This manual page includes parts from: 26## The Single UNIX Specification, Version 2 - Threads 27## http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html 28## Copyright (C) 1997 The Open Group, All Rights Reserved. 29## 30## 31 # ``The trouble with computers is that they 32 # do what you tell them, not what you want.'' 33 34=pod 35 36=head1 NAME 37 38B<pthread> - POSIX.1c Threading API of GNU Pth 39 40=head1 VERSION 41 42GNU Pth PTH_VERSION_STR 43 44=head1 SYNOPSIS 45 46B<Application Makefiles:> 47 48 # manually 49 CFLAGS=-I/path/to/pth/include 50 LDFLAGS=-L/path/to/pth/lib 51 LIBS=-lpthread 52 53 # automatically 54 CFLAGS=`pthread-config --cflags` 55 LDFLAGS=`pthread-config --ldflags` 56 LIBS=`pthread-config --libs` 57 58B<Application source files:> 59 60 #include <pthread.h> 61 62=head1 DESCRIPTION 63 64=head2 Overview 65 66This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of 67GNU Portable Threads (B<Pth>). This API is commonly known as ``I<POSIX 68threads>'' or in short ``I<Pthreads>''. It is provided by B<Pth> with 69the intention of backward compatibility to existing multithreaded 70applications. It is implemented by mapping the various Pthread API 71functions to the corresponding native B<Pth> API functions. 72 73=head2 Supported Features 74 75The following defined feature macros in C<pthread.h> indicate supported 76features: 77 78 #define _POSIX_THREADS 79 #define _POSIX_THREAD_ATTR_STACKADDR 80 #define _POSIX_THREAD_ATTR_STACKSIZE 81 82The following undefined feature macros in C<pthread.h> indicate (still) 83unsupported features: 84 85 #undef _POSIX_THREAD_PRIORITY_SCHEDULING 86 #undef _POSIX_THREAD_PRIO_INHERIT 87 #undef _POSIX_THREAD_PRIO_PROTECT 88 #undef _POSIX_THREAD_PROCESS_SHARED 89 #undef _POSIX_THREAD_SAFE_FUNCTIONS 90 91=head2 Notes 92 93A few notes which you should keep in mind when working with the B<Pth> Pthread 94API. 95 96=over 4 97 98=item B<Non-Preemptive Scheduling> 99 100First you have to always remember when working with this Pthread library that 101it uses non-preemptive scheduling, because it is directly based on B<Pth> 102(B<Pth> for portability reasons is a pure non-preemptive thread scheduling 103system). So there is no implicit yielding of execution control unless you can 104C<pthread_*> functions which could block and you cannot expect granular 105concurrency in your application, of course. Nevertheless the responsiveness 106and concurrency of an event driven application is increased greatly because of 107overlapping I/O. 108 109=item B<Conflicts with Vendor Implementation> 110 111There can be a conflict between the B<Pth> C<pthread.h> header and a possibly 112existing vendor C</usr/include/pthread.h> header which was implicitly included 113by some standard vendor headers (like C</usr/include/unistd.h>). When this 114occurs try to ``C<#define>'' header-dependent values which prevent the 115inclusion of the vendor header. 116 117=back 118 119=head2 Further Reading 120 121There is ``I<The Single UNIX Specification, Version 1222 - Threads>'', from I<The Open Group> of 1997 under 123http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html. This is 124a very complete publically available description of the Pthread API. For 125convinience reasons, a translated copy of these freely available HTML 126pages are appended to this manpage below. These are I<Copyright (C) 1997 127The Open Group>. 128 129Second, you can also buy the official standard from IEEE. It is the IEEE 130POSIX 1003.1c-1995 standard (also known as ISO/IEC 9945-1:1996), which 131is available as part of the ANSI/IEEE 1003.1, 1996 edition, standard. 132 133Finally you can look at the files C<pthread.c> and C<pthread.h> in the B<Pth> 134source tree for details of the implementation, of course. 135 136=head1 SEE ALSO 137 138pthread-config(1), pth(3). 139 140=head1 AUTHOR 141 142 Ralf S. Engelschall 143 rse@engelschall.com 144 www.engelschall.com 145 146=head1 ______________________________________________________________________ 147 148=head1 NAME 149 150B<pthread.h> - threads 151 152=head1 SYNOPSIS 153 154#include <pthread.h> 155 156=head1 DESCRIPTION 157 158The 159I<<pthread.h>> 160header defines the following symbols: 161 162 PTHREAD_CANCEL_ASYNCHRONOUS 163 PTHREAD_CANCEL_ENABLE 164 PTHREAD_CANCEL_DEFERRED 165 PTHREAD_CANCEL_DISABLE 166 PTHREAD_CANCELED 167 PTHREAD_COND_INITIALIZER 168 PTHREAD_CREATE_DETACHED 169 PTHREAD_CREATE_JOINABLE 170 PTHREAD_EXPLICIT_SCHED 171 PTHREAD_INHERIT_SCHED 172 PTHREAD_MUTEX_DEFAULT 173 PTHREAD_MUTEX_ERRORCHECK 174 PTHREAD_MUTEX_NORMAL 175 PTHREAD_MUTEX_INITIALIZER 176 PTHREAD_MUTEX_RECURSIVE 177 PTHREAD_ONCE_INIT 178 PTHREAD_PRIO_INHERIT 179 PTHREAD_PRIO_NONE 180 PTHREAD_PRIO_PROTECT 181 PTHREAD_PROCESS_SHARED 182 PTHREAD_PROCESS_PRIVATE 183 PTHREAD_RWLOCK_INITIALIZER 184 PTHREAD_SCOPE_PROCESS 185 PTHREAD_SCOPE_SYSTEM 186 187The B<pthread_attr_t>, B<pthread_cond_t>, B<pthread_condattr_t>, 188B<pthread_key_t>, B<pthread_mutex_t>, B<pthread_mutexattr_t>, 189B<pthread_once_t>, B<pthread_rwlock_t>, B<pthread_rwlockattr_t> and 190B<pthread_t> types are defined as described in I<<sys/types.h>>. 191 192The following are declared as functions and may also be declared as 193macros. Function prototypes must be provided for use with an ISO C 194compiler. 195 196 int pthread_attr_destroy(pthread_attr_t *); 197 int pthread_attr_getdetachstate(const pthread_attr_t *, int *); 198 int pthread_attr_getguardsize(const pthread_attr_t *, size_t *); 199 int pthread_attr_getinheritsched(const pthread_attr_t *, int *); 200 int pthread_attr_getschedparam(const pthread_attr_t *, struct sched_param *); 201 int pthread_attr_getschedpolicy(const pthread_attr_t *, int *); 202 int pthread_attr_getscope(const pthread_attr_t *, int *); 203 int pthread_attr_getstackaddr(const pthread_attr_t *, void **); 204 int pthread_attr_getstacksize(const pthread_attr_t *, size_t *); 205 int pthread_attr_init(pthread_attr_t *); 206 int pthread_attr_setdetachstate(pthread_attr_t *, int); 207 int pthread_attr_setguardsize(pthread_attr_t *, size_t); 208 int pthread_attr_setinheritsched(pthread_attr_t *, int); 209 int pthread_attr_setschedparam(pthread_attr_t *, const struct sched_param *); 210 int pthread_attr_setschedpolicy(pthread_attr_t *, int); 211 int pthread_attr_setscope(pthread_attr_t *, int); 212 int pthread_attr_setstackaddr(pthread_attr_t *, void *); 213 int pthread_attr_setstacksize(pthread_attr_t *, size_t); 214 int pthread_cancel(pthread_t); 215 void pthread_cleanup_push(void*), void *); 216 void pthread_cleanup_pop(int); 217 int pthread_cond_broadcast(pthread_cond_t *); 218 int pthread_cond_destroy(pthread_cond_t *); 219 int pthread_cond_init(pthread_cond_t *, const pthread_condattr_t *); 220 int pthread_cond_signal(pthread_cond_t *); 221 int pthread_cond_timedwait(pthread_cond_t *, pthread_mutex_t *, const struct timespec *); 222 int pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *); 223 int pthread_condattr_destroy(pthread_condattr_t *); 224 int pthread_condattr_getpshared(const pthread_condattr_t *, int *); 225 int pthread_condattr_init(pthread_condattr_t *); 226 int pthread_condattr_setpshared(pthread_condattr_t *, int); 227 int pthread_create(pthread_t *, const pthread_attr_t *, void *(*)(void *), void *); 228 int pthread_detach(pthread_t); 229 int pthread_equal(pthread_t, pthread_t); 230 void pthread_exit(void *); 231 int pthread_getconcurrency(void); 232 int pthread_getschedparam(pthread_t, int *, struct sched_param *); 233 void *pthread_getspecific(pthread_key_t); 234 int pthread_join(pthread_t, void **); 235 int pthread_key_create(pthread_key_t *, void (*)(void *)); 236 int pthread_key_delete(pthread_key_t); 237 int pthread_mutex_destroy(pthread_mutex_t *); 238 int pthread_mutex_getprioceiling(const pthread_mutex_t *, int *); 239 int pthread_mutex_init(pthread_mutex_t *, const pthread_mutexattr_t *); 240 int pthread_mutex_lock(pthread_mutex_t *); 241 int pthread_mutex_setprioceiling(pthread_mutex_t *, int, int *); 242 int pthread_mutex_trylock(pthread_mutex_t *); 243 int pthread_mutex_unlock(pthread_mutex_t *); 244 int pthread_mutexattr_destroy(pthread_mutexattr_t *); 245 int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *, int *); 246 int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *, int *); 247 int pthread_mutexattr_getpshared(const pthread_mutexattr_t *, int *); 248 int pthread_mutexattr_gettype(const pthread_mutexattr_t *, int *); 249 int pthread_mutexattr_init(pthread_mutexattr_t *); 250 int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); 251 int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); 252 int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); 253 int pthread_mutexattr_settype(pthread_mutexattr_t *, int); 254 int pthread_once(pthread_once_t *, void (*)(void)); 255 int pthread_rwlock_destroy(pthread_rwlock_t *); 256 int pthread_rwlock_init(pthread_rwlock_t *, const pthread_rwlockattr_t *); 257 int pthread_rwlock_rdlock(pthread_rwlock_t *); 258 int pthread_rwlock_tryrdlock(pthread_rwlock_t *); 259 int pthread_rwlock_trywrlock(pthread_rwlock_t *); 260 int pthread_rwlock_unlock(pthread_rwlock_t *); 261 int pthread_rwlock_wrlock(pthread_rwlock_t *); 262 int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); 263 int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *, int *); 264 int pthread_rwlockattr_init(pthread_rwlockattr_t *); 265 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); 266 pthread_t pthread_self(void); 267 int pthread_setcancelstate(int, int *); 268 int pthread_setcanceltype(int, int *); 269 int pthread_setconcurrency(int); 270 int pthread_setschedparam(pthread_t, int, const struct sched_param *); 271 int pthread_setspecific(pthread_key_t, const void *); 272 void pthread_testcancel(void); 273 274Inclusion of the I<<pthread.h>> header will make visible symbols defined 275in the headers I<<sched.h>> and I<<time.h>>. 276 277=head1 APPLICATION USAGE 278 279An interpretation request has been filed with IEEE PASC concerning 280requirements for visibility of symbols in this header. 281 282=head1 FUTURE DIRECTIONS 283 284None. 285 286=head1 SEE ALSO 287 288I<pthread_attr_init()>, 289I<pthread_attr_getguardsize()>, 290I<pthread_attr_setscope()>, 291I<pthread_cancel()>, 292I<pthread_cleanup_push()>, 293I<pthread_cond_init()>, 294I<pthread_cond_signal()>, 295I<pthread_cond_wait()>, 296I<pthread_condattr_init()>, 297I<pthread_create()>, 298I<pthread_detach()>, 299I<pthread_equal()>, 300I<pthread_exit()>, 301I<pthread_getconcurrency()>, 302I<pthread_getschedparam()>, 303I<pthread_join()>, 304I<pthread_key_create()>, 305I<pthread_key_delete()>, 306I<pthread_mutex_init()>, 307I<pthread_mutex_lock()>, 308I<pthread_mutex_setprioceiling()>, 309I<pthread_mutexattr_init()>, 310I<pthread_mutexattr_gettype()>, 311I<pthread_mutexattr_setprotocol()>, 312I<pthread_once()>, 313I<pthread_self()>, 314I<pthread_setcancelstate()>, 315I<pthread_setspecific()>, 316I<pthread_rwlock_init()>, 317I<pthread_rwlock_rdlock()>, 318I<pthread_rwlock_unlock()>, 319I<pthread_rwlock_wrlock()>, 320I<pthread_rwlockattr_init()>, 321I<<sched.h>>, 322I<<time.h>>. 323 324=head1 ______________________________________________________________________ 325 326=head1 NAME 327 328B<pthread_atfork> - register fork handlers 329 330=head1 SYNOPSIS 331 332#include <sys/types.h> 333 334#include <unistd.h> 335 336int pthread_atfork(void (*I<prepare>)(void), void (*I<parent>)(void), 337void (*I<child>)(void)); 338 339=head1 DESCRIPTION 340 341The I<pthread_atfork()> function declares fork handlers to be called 342before and after I<fork()>, in the context of the thread that called 343I<fork()>. The I<prepare> fork handler is called before I<fork()> 344processing commences. The I<parent> fork handle is called after 345I<fork()> processing completes in the parent process. The I<child> fork 346handler is called after I<fork()> processing completes in the child 347process. If no handling is desired at one or more of these three points, 348the corresponding fork handler address(es) may be set to NULL. 349 350The order of calls to I<pthread_atfork()> is significant. The I<parent> 351and I<child> fork handlers are called in the order in which they were 352established by calls to I<pthread_atfork()>. The I<prepare> fork 353handlers are called in the opposite order. 354 355=head1 RETURN VALUE 356 357Upon successful completion, I<pthread_atfork()> returns a value of zero. 358Otherwise, an error number is returned to indicate the error. 359 360=head1 ERRORS 361 362The I<pthread_atfork()> function will fail if: 363 364=over 4 365 366=item [ENOMEM] 367 368Insufficient table space exists to record the fork handler addresses. 369 370=back 371 372The I<pthread_atfork()> function will not return an error code of 373[EINTR]. 374 375=head1 EXAMPLES 376 377None. 378 379=head1 APPLICATION USAGE 380 381None. 382 383=head1 FUTURE DIRECTIONS 384 385None. 386 387=head1 SEE ALSO 388 389I<atexit()>, 390I<fork()>, 391I<<sys/types.h>> 392 393=head1 ______________________________________________________________________ 394 395=head1 NAME 396 397B<pthread_attr_init,> B<pthread_attr_destroy> 398- initialise and destroy threads attribute object 399 400=head1 SYNOPSIS 401 402#include <pthread.h> 403 404int pthread_attr_init(pthread_attr_t *I<attr>); 405 406int pthread_attr_destroy(pthread_attr_t *I<attr>); 407 408=head1 DESCRIPTION 409 410The function I<pthread_attr_init()> initialises a thread attributes 411object I<attr> with the default value for all of the individual 412attributes used by a given implementation. 413 414The resulting attribute object (possibly modified by setting individual 415attribute values), when used by I<pthread_create()>, defines the 416attributes of the thread created. A single attributes object can be used 417in multiple simultaneous calls to I<pthread_create()>. 418 419The I<pthread_attr_destroy()> function is used to destroy a thread 420attributes object. An implementation may cause I<pthread_attr_destroy()> 421to set I<attr> to an implementation-dependent invalid value. The 422behaviour of using the attribute after it has been destroyed is 423undefined. 424 425=head1 RETURN VALUE 426 427Upon successful completion, I<pthread_attr_init()> and 428I<pthread_attr_destroy()> return a value of 0. Otherwise, an error 429number is returned to indicate the error. 430 431=head1 ERRORS 432 433The I<pthread_attr_init()> function will fail if: 434 435=over 4 436 437=item [ENOMEM] 438 439Insufficient memory exists to initialise the thread attributes object. 440 441=back 442 443These functions will not return an error code of [EINTR]. 444 445=head1 EXAMPLES 446 447None. 448 449=head1 APPLICATION USAGE 450 451None. 452 453=head1 FUTURE DIRECTIONS 454 455None. 456 457=head1 SEE ALSO 458 459I<pthread_attr_setstackaddr()>, 460I<pthread_attr_setstacksize()>, 461I<pthread_attr_setdetachstate()>, 462I<pthread_create()>, 463I<<pthread.h>>. 464 465=head1 ______________________________________________________________________ 466 467=head1 NAME 468 469B<pthread_attr_setdetachstate,> B<pthread_attr_getdetachstate> 470- set and get detachstate attribute 471 472=head1 SYNOPSIS 473 474#include <pthread.h> 475 476int pthread_attr_setdetachstate(pthread_attr_t *I<attr>, int I<detachstate>); 477 478int pthread_attr_getdetachstate(const pthread_attr_t *I<attr>, int *I<detachstate>); 479 480=head1 DESCRIPTION 481 482The I<detachstate> attribute controls whether the thread is created in a 483detached state. If the thread is created detached, then use of the ID of 484the newly created thread by the I<pthread_detach()> or I<pthread_join()> 485function is an error. 486 487The I<pthread_attr_setdetachstate()> and 488I<pthread_attr_getdetachstate()>, respectively, set and get the 489I<detachstate> attribute in the I<attr> object. 490 491The I<detachstate> can be set to either PTHREAD_CREATE_DETACHED or 492PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes 493all threads created with I<attr> to be in the detached state, whereas 494using a value of PTHREAD_CREATE_JOINABLE causes all threads created 495with I<attr> to be in the joinable state. The default value of the 496I<detachstate> attribute is PTHREAD_CREATE_JOINABLE . 497 498=head1 RETURN VALUE 499 500Upon successful completion, I<pthread_attr_setdetachstate()> and 501I<pthread_attr_getdetachstate()> return a value of 0. Otherwise, an 502error number is returned to indicate the error. 503 504The I<pthread_attr_getdetachstate()> function stores the value of the 505I<detachstate> attribute in I<detachstate> if successful. 506 507=head1 ERRORS 508 509The I<pthread_attr_setdetachstate()> function will fail if: 510 511=over 4 512 513=item [EINVAL] 514 515The value of I<detachstate> was not valid 516 517=back 518 519These functions will not return an error code of [EINTR]. 520 521=head1 EXAMPLES 522 523None. 524 525=head1 APPLICATION USAGE 526 527None. 528 529=head1 FUTURE DIRECTIONS 530 531None. 532 533=head1 SEE ALSO 534 535I<pthread_attr_init()>, 536I<pthread_attr_setstackaddr()>, 537I<pthread_attr_setstacksize()>, 538I<pthread_create()>, 539I<<pthread.h>>. 540 541=head1 ______________________________________________________________________ 542 543=head1 NAME 544 545B<pthread_attr_getguardsize,> B<pthread_attr_setguardsize> - 546get or set the thread guardsize attribute 547 548=head1 SYNOPSIS 549 550#include <pthread.h> 551 552int pthread_attr_getguardsize(const pthread_attr_t I<*attr>, size_t 553I<*guardsize>); int pthread_attr_setguardsize(pthread_attr_t I<*attr>, 554size_t I<guardsize>); 555 556=head1 DESCRIPTION 557 558The I<guardsize> attribute controls the size of the guard area for the 559created thread's stack. The I<guardsize> attribute provides protection 560against overflow of the stack pointer. If a thread's stack is created 561with guard protection, the implementation allocates extra memory at the 562overflow end of the stack as a buffer against stack overflow of the 563stack pointer. If an application overflows into this buffer an error 564results (possibly in a SIGSEGV signal being delivered to the thread). 565 566The I<guardsize> attribute is provided to the application 567for two reasons: 568 569=over 4 570 571=item 1. 572 573Overflow protection can potentially result in wasted system resources. 574An application that creates a large number of threads, and which knows 575its threads will never overflow their stack, can save system resources 576by turning off guard areas. 577 578=item 2. 579 580When threads allocate large data structures on the stack, 581large guard areas may be needed to detect stack overflow. 582 583=back 584 585The I<pthread_attr_getguardsize()> function gets the I<guardsize> 586attribute in the I<attr> object. This attribute is returned in the 587I<guardsize> parameter. 588 589The I<pthread_attr_setguardsize()> function sets the I<guardsize> 590attribute in the I<attr> object. The new value of this attribute is 591obtained from the I<guardsize> parameter. If I<guardsize> is zero, 592a guard area will not be provided for threads created with I<attr>. 593If I<guardsize> is greater than zero, a guard area of at least size 594I<guardsize> bytes is provided for each thread created with I<attr>. 595 596A conforming implementation is permitted to round up the value 597contained in I<guardsize> to a multiple of the configurable system 598variable PAGESIZE (see I<<sys/mman.h>>). If an implementation rounds 599up the value of I<guardsize> to a multiple of PAGESIZE, a call to 600I<pthread_attr_getguardsize()> specifying I<attr> will store in the 601I<guardsize> parameter the guard size specified by the previous 602I<pthread_attr_setguardsize()> function call. 603 604The default value of the I<guardsize> attribute is PAGESIZE bytes. The 605actual value of PAGESIZE is implementation-dependent and may not be the 606same on all implementations. 607 608If the I<stackaddr> attribute has been set (that is, the caller is 609allocating and managing its own thread stacks), the I<guardsize> 610attribute is ignored and no protection will be provided by the 611implementation. It is the responsibility of the application to manage 612stack overflow along with stack allocation and management in this case. 613 614=head1 RETURN VALUE 615 616If successful, the I<pthread_attr_getguardsize()> and 617I<pthread_attr_setguardsize()> functions return zero. Otherwise, an 618error number is returned to indicate the error. 619 620=head1 ERRORS 621 622The I<pthread_attr_getguardsize()> and I<pthread_attr_setguardsize()> 623functions will fail if: 624 625=over 4 626 627=item [EINVAL] 628 629The attribute I<attr> is invalid. 630 631=item [EINVAL] 632 633The parameter I<guardsize> is invalid. 634 635=item [EINVAL] 636 637The parameter I<guardsize> contains an invalid value. 638 639=back 640 641=head1 EXAMPLES 642 643None. 644 645=head1 APPLICATION USAGE 646 647None. 648 649=head1 FUTURE DIRECTIONS 650 651None. 652 653=head1 SEE ALSO 654 655I<<pthread.h>>. 656 657=head1 ______________________________________________________________________ 658 659=head1 NAME 660 661B<pthread_attr_setinheritsched,> B<pthread_attr_getinheritsched> 662- set and get inheritsched attribute 663(B<REALTIME THREADS>) 664 665=head1 SYNOPSIS 666 667#include <pthread.h> 668 669int pthread_attr_setinheritsched(pthread_attr_t *I<attr>, 670int I<inheritsched>); 671int pthread_attr_getinheritsched(const pthread_attr_t *I<attr>, 672int *I<inheritsched>); 673 674=head1 DESCRIPTION 675 676The functions I<pthread_attr_setinheritsched()> and 677I<pthread_attr_getinheritsched()>, respectively, set and get the 678I<inheritsched> attribute in the I<attr> argument. 679 680When the attribute objects are used by I<pthread_create()>, the 681I<inheritsched> attribute determines how the other scheduling attributes 682of the created thread are to be set: 683 684=over 4 685 686=item PTHREAD_INHERIT_SCHED 687 688Specifies that the scheduling policy and associated attributes are to 689be inherited from the creating thread, and the scheduling attributes in 690this I<attr> argument are to be ignored. 691 692=item PTHREAD_EXPLICIT_SCHED 693 694Specifies that the scheduling policy and associated attributes 695are to be set to the corresponding values from this attribute object. 696 697=back 698 699The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined 700in the header I<<pthread.h>>. 701 702=head1 RETURN VALUE 703 704If successful, the I<pthread_attr_setinheritsched()> and 705I<pthread_attr_getinheritsched()> functions return zero. Otherwise, an 706error number is returned to indicate the error. 707 708=head1 ERRORS 709 710The I<pthread_attr_setinheritsched()> and 711I<pthread_attr_getinheritsched()> functions will fail if: 712 713=over 4 714 715=item [ENOSYS] 716 717The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 718implementation does not support the function. 719 720=back 721 722The I<pthread_attr_setinheritsched()> function may fail if: 723 724=over 4 725 726=item [EINVAL] 727 728The value of the attribute being set is not valid. 729 730=item [ENOTSUP] 731 732An attempt was made to set the attribute to an unsupported value. 733 734=back 735 736=head1 EXAMPLES 737 738None. 739 740=head1 APPLICATION USAGE 741 742After these attributes have been set, a thread can be created with the 743specified attributes using I<pthread_create()>. Using these routines 744does not affect the current running thread. 745 746=head1 FUTURE DIRECTIONS 747 748None. 749 750=head1 SEE ALSO 751 752I<pthread_attr_init()>, 753I<pthread_attr_setscope()>, 754I<pthread_attr_setschedpolicy()>, 755I<pthread_attr_setschedparam()>, 756I<pthread_create()>, 757I<<pthread.h>>, 758I<pthread_setschedparam()>, 759I<<sched.h>>. 760 761=head1 ______________________________________________________________________ 762 763=head1 NAME 764 765B<pthread_attr_setschedparam,> B<pthread_attr_getschedparam> 766- set and get schedparam attribute 767 768=head1 SYNOPSIS 769 770#include <pthread.h> 771 772int pthread_attr_setschedparam(pthread_attr_t *I<attr>, const struct sched_param *I<param>); 773 774int pthread_attr_getschedparam(const pthread_attr_t *I<attr>, struct sched_param *I<param>); 775 776=head1 DESCRIPTION 777 778The functions I<pthread_attr_setschedparam()> and 779I<pthread_attr_getschedparam()>, respectively, set and get the 780scheduling parameter attributes in the I<attr> argument. The contents of 781the I<param> structure are defined in I<<sched.h>>. For the SCHED_FIFO 782and SCHED_RR policies, the only required member of I<param> is 783I<sched_priority>. 784 785=head1 RETURN VALUE 786 787If successful, the I<pthread_attr_setschedparam()> and 788I<pthread_attr_getschedparam()> functions return zero. Otherwise, an 789error number is returned to indicate the error. 790 791=head1 ERRORS 792 793The I<pthread_attr_setschedparam()> function may fail if: 794 795=over 4 796 797=item [EINVAL] 798 799The value of the attribute being set is not valid. 800 801=item [ENOTSUP] 802 803An attempt was made to set the attribute to an unsupported value. 804 805=back 806 807The 808I<pthread_attr_setschedparam()> 809and 810I<pthread_attr_getschedparam()> 811functions will not return an error code of [EINTR]. 812 813=head1 EXAMPLES 814 815None. 816 817=head1 APPLICATION USAGE 818 819After these attributes have been set, a thread can be created with the 820specified attributes using I<pthread_create()>. Using these routines 821does not affect the current running thread. 822 823=head1 FUTURE DIRECTIONS 824 825None. 826 827=head1 SEE ALSO 828 829I<pthread_attr_init()>, 830I<pthread_attr_setscope()>, 831I<pthread_attr_setinheritsched()>, 832I<pthread_attr_setschedpolicy()>, 833I<pthread_create()>, 834I<<pthread.h>>, 835I<pthread_setschedparam()>, 836I<<sched.h>>. 837 838=head1 ______________________________________________________________________ 839 840=head1 NAME 841 842B<pthread_attr_setschedpolicy,> B<pthread_attr_getschedpolicy> 843- set and get schedpolicy attribute 844(B<REALTIME THREADS>) 845 846=head1 SYNOPSIS 847 848#include <pthread.h> 849 850int pthread_attr_setschedpolicy(pthread_attr_t *I<attr>, int I<policy>); 851int pthread_attr_getschedpolicy(const pthread_attr_t *I<attr>, 852int *I<policy>); 853 854=head1 DESCRIPTION 855 856The functions I<pthread_attr_setschedpolicy()> and 857I<pthread_attr_getschedpolicy()>, respectively, set and get the 858I<schedpolicy> attribute in the I<attr> argument. 859 860The supported values of I<policy> include SCHED_FIFO, SCHED_RR and 861SCHED_OTHER, which are defined by the header I<<sched.h>>. When threads 862executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting 863on a mutex, they acquire the mutex in priority order when the mutex is 864unlocked. 865 866=head1 RETURN VALUE 867 868If successful, the I<pthread_attr_setschedpolicy()> and 869I<pthread_attr_getschedpolicy()> functions return zero. Otherwise, an 870error number is returned to indicate the error. 871 872=head1 ERRORS 873 874The I<pthread_attr_setschedpolicy()> and 875I<pthread_attr_getschedpolicy()> functions will fail if: 876 877=over 4 878 879=item [ENOSYS] 880 881The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 882implementation does not support the function. 883 884=back 885 886The I<pthread_attr_setschedpolicy()> function may fail if: 887 888=over 4 889 890=item [EINVAL] 891 892The value of the attribute being set is not valid. 893 894=item [ENOTSUP] 895 896An attempt was made to set the attribute to an unsupported value. 897 898=back 899 900=head1 EXAMPLES 901 902None. 903 904=head1 APPLICATION USAGE 905 906After these attributes have been set, a thread can be created with the 907specified attributes using I<pthread_create()>. Using these routines 908does not affect the current running thread. 909 910=head1 FUTURE DIRECTIONS 911 912None. 913 914=head1 SEE ALSO 915 916I<pthread_attr_init()>, 917I<pthread_attr_setscope()>, 918I<pthread_attr_setinheritsched()>, 919I<pthread_attr_setschedparam()>, 920I<pthread_create()>, 921I<<pthread.h>>, 922I<pthread_setschedparam()>, 923I<<sched.h>>. 924 925=head1 ______________________________________________________________________ 926 927=head1 NAME 928 929B<pthread_attr_setscope,> B<pthread_attr_getscope> 930- set and get contentionscope attribute 931(B<REALTIME THREADS>) 932 933=head1 SYNOPSIS 934 935#include <pthread.h> 936 937int pthread_attr_setscope(pthread_attr_t *I<attr>, int I<contentionscope>); 938int pthread_attr_getscope(const pthread_attr_t *I<attr>, 939int *I<contentionscope>); 940 941=head1 DESCRIPTION 942 943The I<pthread_attr_setscope()> and I<pthread_attr_getscope()> functions 944are used to set and get the I<contentionscope> attribute in the I<attr> 945object. 946 947The I<contentionscope> attribute may have the values 948PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or 949PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. 950The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined 951by the header I<<pthread.h>>. 952 953=head1 RETURN VALUE 954 955If successful, the I<pthread_attr_setscope()> and 956I<pthread_attr_getscope()> functions return zero. Otherwise, an error 957number is returned to indicate the error. 958 959=head1 ERRORS 960 961The I<pthread_attr_setscope()> and I<pthread_attr_getscope()> functions 962will fail if: 963 964=over 4 965 966=item [ENOSYS] 967 968The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 969implementation does not support the function. 970 971=back 972 973The 974I<pthread_attr_setscope()>, 975function may fail if: 976 977=over 4 978 979=item [EINVAL] 980 981The value of the attribute being set is not valid. 982 983=item [ENOTSUP] 984 985An attempt was made to set the attribute to an unsupported value. 986 987=back 988 989=head1 EXAMPLES 990 991None. 992 993=head1 APPLICATION USAGE 994 995After these attributes have been set, a thread can be created with the 996specified attributes using I<pthread_create()>. Using these routines 997does not affect the current running thread. 998 999=head1 FUTURE DIRECTIONS 1000 1001None. 1002 1003=head1 SEE ALSO 1004 1005I<pthread_attr_init()>, 1006I<pthread_attr_setinheritsched()>, 1007I<pthread_attr_setschedpolicy()>, 1008I<pthread_attr_setschedparam()>, 1009I<pthread_create()>, 1010I<<pthread.h>>, 1011I<pthread_setschedparam()>, 1012I<<sched.h>>. 1013 1014=head1 ______________________________________________________________________ 1015 1016=head1 NAME 1017 1018B<pthread_attr_setstackaddr,> B<pthread_attr_getstackaddr> 1019- set and get stackaddr attribute 1020 1021=head1 SYNOPSIS 1022 1023#include <pthread.h> 1024 1025int pthread_attr_setstackaddr(pthread_attr_t *I<attr>, void *I<stackaddr>); 1026 1027int pthread_attr_getstackaddr(const pthread_attr_t *I<attr>, void **I<stackaddr>); 1028 1029=head1 DESCRIPTION 1030 1031The functions I<pthread_attr_setstackaddr()> and 1032I<pthread_attr_getstackaddr()>, respectively, set and get the thread 1033creation I<stackaddr> attribute in the I<attr> object. 1034 1035The I<stackaddr> attribute specifies the location of storage to be used 1036for the created thread's stack. The size of the storage is at least 1037PTHREAD_STACK_MIN. 1038 1039=head1 RETURN VALUE 1040 1041Upon successful completion, I<pthread_attr_setstackaddr()> and 1042I<pthread_attr_getstackaddr()> return a value of 0. Otherwise, an error 1043number is returned to indicate the error. 1044 1045The I<pthread_attr_getstackaddr()> function stores the I<stackaddr> 1046attribute value in I<stackaddr> if successful. 1047 1048=head1 ERRORS 1049 1050No errors are defined. 1051 1052These functions will not return an error code of [EINTR]. 1053 1054=head1 EXAMPLES 1055 1056None. 1057 1058=head1 APPLICATION USAGE 1059 1060None. 1061 1062=head1 FUTURE DIRECTIONS 1063 1064None. 1065 1066=head1 SEE ALSO 1067 1068I<pthread_attr_init()>, 1069I<pthread_attr_setdetachstate()>, 1070I<pthread_attr_setstacksize()>, 1071I<pthread_create()>, 1072I<<limits.h>>, 1073I<<pthread.h>>. 1074 1075=head1 ______________________________________________________________________ 1076 1077=head1 NAME 1078 1079B<pthread_attr_setstacksize,> B<pthread_attr_getstacksize> 1080- set and get stacksize attribute 1081 1082=head1 SYNOPSIS 1083 1084#include <pthread.h> 1085 1086int pthread_attr_setstacksize(pthread_attr_t *I<attr>, size_t I<stacksize>); 1087int pthread_attr_getstacksize(const pthread_attr_t *I<attr>, 1088size_t *I<stacksize>); 1089 1090=head1 DESCRIPTION 1091 1092The functions 1093I<pthread_attr_setstacksize()> 1094and 1095I<pthread_attr_getstacksize()>, 1096respectively, set and get the thread creation 1097I<stacksize> 1098attribute in the 1099I<attr> 1100object. 1101 1102The 1103I<stacksize> 1104attribute defines the minimum stack size (in bytes) allocated for 1105the created threads stack. 1106 1107=head1 RETURN VALUE 1108 1109Upon successful completion, 1110I<pthread_attr_setstacksize()> 1111and 1112I<pthread_attr_getstacksize()> 1113return a value of 0. 1114Otherwise, an error number is returned to indicate the error. 1115The 1116I<pthread_attr_getstacksize()> 1117function stores the 1118I<stacksize> 1119attribute value in 1120I<stacksize> 1121if successful. 1122 1123=head1 ERRORS 1124 1125The 1126I<pthread_attr_setstacksize()> 1127function will fail if: 1128 1129=over 4 1130 1131=item [EINVAL] 1132 1133The value of 1134I<stacksize> 1135is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. 1136 1137=back 1138 1139These functions will not return an error code of [EINTR]. 1140 1141=head1 EXAMPLES 1142 1143None. 1144 1145=head1 APPLICATION USAGE 1146 1147None. 1148 1149=head1 FUTURE DIRECTIONS 1150 1151None. 1152 1153=head1 SEE ALSO 1154 1155I<pthread_attr_init()>, 1156I<pthread_attr_setstackaddr()>, 1157I<pthread_attr_setdetachstate()>, 1158I<pthread_create()>, 1159I<<limits.h>>, 1160I<<pthread.h>>. 1161 1162=head1 ______________________________________________________________________ 1163 1164=head1 NAME 1165 1166B<pthread_attr_init,> B<pthread_attr_destroy> 1167- initialise and destroy threads attribute object 1168 1169=head1 SYNOPSIS 1170 1171#include <pthread.h> 1172 1173int pthread_attr_init(pthread_attr_t *I<attr>); 1174int pthread_attr_destroy(pthread_attr_t *I<attr>); 1175 1176=head1 DESCRIPTION 1177 1178The function 1179I<pthread_attr_init()> 1180initialises a thread attributes object 1181I<attr> 1182with the default value for all of the individual attributes 1183used by a given implementation. 1184 1185The resulting attribute object 1186(possibly modified by setting individual attribute values), 1187when used by 1188I<pthread_create()>, 1189defines the attributes of the thread created. 1190A single attributes object can be used in multiple simultaneous calls to 1191I<pthread_create()>. 1192 1193The 1194I<pthread_attr_destroy()> 1195function is used to destroy a thread attributes object. 1196An implementation may cause 1197I<pthread_attr_destroy()> 1198to set 1199I<attr> 1200to an implementation-dependent invalid value. 1201The behaviour of using the attribute after it has been destroyed is undefined. 1202 1203=head1 RETURN VALUE 1204 1205Upon successful completion, 1206I<pthread_attr_init()> 1207and 1208I<pthread_attr_destroy()> 1209return a value of 0. 1210Otherwise, an error number is returned to indicate the error. 1211 1212=head1 ERRORS 1213 1214The 1215I<pthread_attr_init()> 1216function will fail if: 1217 1218=over 4 1219 1220=item [ENOMEM] 1221 1222Insufficient memory exists to initialise the thread attributes object. 1223 1224=back 1225 1226These functions will not return an error code of [EINTR]. 1227 1228=head1 EXAMPLES 1229 1230None. 1231 1232=head1 APPLICATION USAGE 1233 1234None. 1235 1236=head1 FUTURE DIRECTIONS 1237 1238None. 1239 1240=head1 SEE ALSO 1241 1242I<pthread_attr_setstackaddr()>, 1243I<pthread_attr_setstacksize()>, 1244I<pthread_attr_setdetachstate()>, 1245I<pthread_create()>, 1246I<<pthread.h>>. 1247 1248=head1 ______________________________________________________________________ 1249 1250=head1 NAME 1251 1252B<pthread_attr_setdetachstate,> B<pthread_attr_getdetachstate> 1253- set and get detachstate attribute 1254 1255=head1 SYNOPSIS 1256 1257#include <pthread.h> 1258 1259int pthread_attr_setdetachstate(pthread_attr_t *I<attr>, int I<detachstate>); 1260int pthread_attr_getdetachstate(const pthread_attr_t *I<attr>, 1261int *I<detachstate>); 1262 1263=head1 DESCRIPTION 1264 1265The 1266I<detachstate> 1267attribute controls whether the thread is created in a detached state. 1268If the thread is created detached, 1269then use of the ID of the newly created thread by the 1270I<pthread_detach()> 1271or 1272I<pthread_join()> 1273function is an error. 1274 1275The 1276I<pthread_attr_setdetachstate()> 1277and 1278I<pthread_attr_getdetachstate()>, 1279respectively, set and get the 1280I<detachstate> 1281attribute in the 1282I<attr> 1283object. 1284 1285The 1286I<detachstate> 1287can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. 1288A value of PTHREAD_CREATE_DETACHED causes all threads created with 1289I<attr> 1290to be in the detached state, whereas using a value of 1291PTHREAD_CREATE_JOINABLE 1292causes all threads created with 1293I<attr> 1294to be in the joinable state. 1295The default value of the 1296I<detachstate> 1297attribute is 1298PTHREAD_CREATE_JOINABLE . 1299 1300=head1 RETURN VALUE 1301 1302Upon successful completion, 1303I<pthread_attr_setdetachstate()> 1304and 1305I<pthread_attr_getdetachstate()> 1306return a value of 0. 1307Otherwise, an error number is returned to indicate the error. 1308 1309The 1310I<pthread_attr_getdetachstate()> 1311function stores the value of the 1312I<detachstate> 1313attribute in 1314I<detachstate> 1315if successful. 1316 1317=head1 ERRORS 1318 1319The 1320I<pthread_attr_setdetachstate()> 1321function will fail if: 1322 1323=over 4 1324 1325=item [EINVAL] 1326 1327The value of 1328I<detachstate> 1329was not valid 1330 1331=back 1332 1333These functions will not return an error code of [EINTR]. 1334 1335=head1 EXAMPLES 1336 1337None. 1338 1339=head1 APPLICATION USAGE 1340 1341None. 1342 1343=head1 FUTURE DIRECTIONS 1344 1345None. 1346 1347=head1 SEE ALSO 1348 1349I<pthread_attr_init()>, 1350I<pthread_attr_setstackaddr()>, 1351I<pthread_attr_setstacksize()>, 1352I<pthread_create()>, 1353I<<pthread.h>>. 1354 1355=head1 ______________________________________________________________________ 1356 1357=head1 NAME 1358 1359B<pthread_attr_getguardsize,> B<pthread_attr_setguardsize> - 1360get or set the thread guardsize attribute 1361 1362=head1 SYNOPSIS 1363 1364#include <pthread.h> 1365 1366int pthread_attr_getguardsize(const pthread_attr_t I<*attr>, 1367size_t I<*guardsize>); 1368int pthread_attr_setguardsize(pthread_attr_t I<*attr>, 1369size_t I<guardsize>); 1370 1371=head1 DESCRIPTION 1372 1373The I<guardsize> attribute controls the size 1374of the guard area for the created thread's stack. The I<guardsize> 1375attribute provides protection against overflow of the 1376stack pointer. If a thread's stack is created with guard 1377protection, the implementation allocates extra 1378memory at the overflow end of the stack as a buffer against 1379stack overflow of the stack pointer. If an application 1380overflows into this buffer an error results (possibly 1381in a SIGSEGV signal being delivered to the thread). 1382 1383The I<guardsize> attribute is provided to the application 1384for two reasons: 1385 1386=over 4 1387 1388=item 1. 1389 1390Overflow protection can potentially 1391result in wasted system resources. An application that creates a large 1392number of threads, and which knows its threads will never overflow 1393their stack, can save system resources by turning off guard areas. 1394 1395=item 2. 1396 1397When threads allocate large data structures on the stack, 1398large guard areas may be needed to detect stack overflow. 1399 1400=back 1401 1402The 1403I<pthread_attr_getguardsize()> 1404function gets the 1405I<guardsize> attribute in the I<attr> object. This attribute is 1406returned in the I<guardsize> parameter. 1407 1408The 1409I<pthread_attr_setguardsize()> 1410function sets the 1411I<guardsize> attribute in the I<attr> object. The new value of 1412this attribute is obtained from the I<guardsize> parameter. 1413If I<guardsize> is zero, a guard area will not be 1414provided for threads created with I<attr>. If I<guardsize> is 1415greater 1416than zero, a guard area of at least size I<guardsize> 1417bytes is provided for each thread created with I<attr>. 1418 1419A conforming implementation is permitted to round up 1420the value contained in I<guardsize> to a multiple 1421of the configurable system variable PAGESIZE (see 1422I<<sys/mman.h>>). 1423If an implementation rounds up the 1424value of I<guardsize> to a multiple of PAGESIZE, a call to 1425I<pthread_attr_getguardsize()> 1426specifying I<attr> will 1427store in the I<guardsize> parameter the guard size specified by the 1428previous 1429I<pthread_attr_setguardsize()> 1430function call. 1431 1432The default value of the I<guardsize> attribute is PAGESIZE bytes. 1433The actual value of PAGESIZE is 1434implementation-dependent and may not be the same on all implementations. 1435 1436If the I<stackaddr> attribute has been set (that is, the caller 1437is allocating and managing its own thread stacks), the 1438I<guardsize> attribute is ignored and no protection 1439will be provided by the implementation. It is the 1440responsibility of the application to manage stack overflow 1441along with stack allocation and management in this 1442case. 1443 1444=head1 RETURN VALUE 1445 1446If successful, the 1447I<pthread_attr_getguardsize()> 1448and 1449I<pthread_attr_setguardsize()> 1450functions return zero. 1451Otherwise, an error number is returned to indicate the error. 1452 1453 1454=head1 ERRORS 1455 1456The 1457I<pthread_attr_getguardsize()> 1458and 1459I<pthread_attr_setguardsize()> 1460functions will fail if: 1461 1462=over 4 1463 1464=item [EINVAL] 1465 1466The attribute I<attr> is invalid. 1467 1468=item [EINVAL] 1469 1470The parameter I<guardsize> is invalid. 1471 1472=item [EINVAL] 1473 1474The parameter I<guardsize> contains an invalid value. 1475 1476=back 1477 1478=head1 EXAMPLES 1479 1480None. 1481 1482=head1 APPLICATION USAGE 1483 1484None. 1485 1486=head1 FUTURE DIRECTIONS 1487 1488None. 1489 1490=head1 SEE ALSO 1491 1492I<<pthread.h>>. 1493 1494=head1 ______________________________________________________________________ 1495 1496=head1 NAME 1497 1498B<pthread_attr_setinheritsched,> B<pthread_attr_getinheritsched> 1499- set and get inheritsched attribute 1500(B<REALTIME THREADS>) 1501 1502=head1 SYNOPSIS 1503 1504#include <pthread.h> 1505 1506int pthread_attr_setinheritsched(pthread_attr_t *I<attr>, 1507int I<inheritsched>); 1508int pthread_attr_getinheritsched(const pthread_attr_t *I<attr>, 1509int *I<inheritsched>); 1510 1511=head1 DESCRIPTION 1512 1513The functions 1514I<pthread_attr_setinheritsched()> 1515and 1516I<pthread_attr_getinheritsched()>, 1517respectively, set and get the 1518I<inheritsched> 1519attribute in the 1520I<attr> 1521argument. 1522 1523When the attribute objects are used by 1524I<pthread_create()>, 1525the 1526I<inheritsched> 1527attribute determines how the other scheduling attributes of 1528the created thread are to be set: 1529 1530=over 4 1531 1532=item PTHREAD_INHERIT_SCHED 1533 1534Specifies that the scheduling policy and associated attributes 1535are to be inherited from the creating thread, and the scheduling 1536attributes in this 1537I<attr> 1538argument are to be ignored. 1539 1540=item PTHREAD_EXPLICIT_SCHED 1541 1542Specifies that the scheduling policy and associated attributes 1543are to be set to the corresponding values from this attribute object. 1544 1545=back 1546 1547The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED 1548are defined in the header 1549I<<pthread.h>>. 1550 1551=head1 RETURN VALUE 1552 1553If successful, the 1554I<pthread_attr_setinheritsched()> 1555and 1556I<pthread_attr_getinheritsched()> 1557functions return zero. 1558Otherwise, an error number is returned to indicate the error. 1559 1560=head1 ERRORS 1561 1562The 1563I<pthread_attr_setinheritsched()> 1564and 1565I<pthread_attr_getinheritsched()> 1566functions will fail if: 1567 1568=over 4 1569 1570=item [ENOSYS] 1571 1572The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 1573implementation does not support the function. 1574 1575=back 1576 1577The 1578I<pthread_attr_setinheritsched()> 1579function may fail if: 1580 1581=over 4 1582 1583=item [EINVAL] 1584 1585The value of the attribute being set is not valid. 1586 1587=item [ENOTSUP] 1588 1589An attempt was made to set the attribute to an unsupported value. 1590 1591=back 1592 1593=head1 EXAMPLES 1594 1595None. 1596 1597=head1 APPLICATION USAGE 1598 1599After these attributes have been set, a thread can be created with 1600the specified attributes using 1601I<pthread_create()>. 1602Using these routines does not affect the current running thread. 1603 1604=head1 FUTURE DIRECTIONS 1605 1606None. 1607 1608=head1 SEE ALSO 1609 1610I<pthread_attr_init()>, 1611I<pthread_attr_setscope()>, 1612I<pthread_attr_setschedpolicy()>, 1613I<pthread_attr_setschedparam()>, 1614I<pthread_create()>, 1615I<<pthread.h>>, 1616I<pthread_setschedparam()>, 1617I<<sched.h>>. 1618 1619=head1 ______________________________________________________________________ 1620 1621=head1 NAME 1622 1623B<pthread_attr_setschedparam,> B<pthread_attr_getschedparam> 1624- set and get schedparam attribute 1625 1626=head1 SYNOPSIS 1627 1628#include <pthread.h> 1629 1630int pthread_attr_setschedparam(pthread_attr_t *I<attr>, 1631const struct sched_param *I<param>); 1632int pthread_attr_getschedparam(const pthread_attr_t *I<attr>, 1633struct sched_param *I<param>); 1634 1635=head1 DESCRIPTION 1636 1637The functions 1638I<pthread_attr_setschedparam()> 1639and 1640I<pthread_attr_getschedparam()>, 1641respectively, set and get the scheduling parameter 1642attributes in the 1643I<attr> 1644argument. 1645The contents of the 1646I<param> 1647structure are defined in 1648I<<sched.h>>. 1649For the SCHED_FIFO and SCHED_RR policies, 1650the only required member of 1651I<param> 1652is 1653I<sched_priority>. 1654 1655=head1 RETURN VALUE 1656 1657If successful, the 1658I<pthread_attr_setschedparam()> 1659and 1660I<pthread_attr_getschedparam()> 1661functions return zero. 1662Otherwise, an error number is returned to indicate the error. 1663 1664=head1 ERRORS 1665 1666The 1667I<pthread_attr_setschedparam()> 1668function may fail if: 1669 1670=over 4 1671 1672=item [EINVAL] 1673 1674The value of the attribute being set is not valid. 1675 1676=item [ENOTSUP] 1677 1678An attempt was made to set the attribute to an unsupported value. 1679 1680=back 1681 1682The 1683I<pthread_attr_setschedparam()> 1684and 1685I<pthread_attr_getschedparam()> 1686functions will not return an error code of [EINTR]. 1687 1688=head1 EXAMPLES 1689 1690None. 1691 1692=head1 APPLICATION USAGE 1693 1694After these attributes have been set, a thread can be created with 1695the specified attributes using 1696I<pthread_create()>. 1697Using these routines does not affect the current running thread. 1698 1699=head1 FUTURE DIRECTIONS 1700 1701None. 1702 1703=head1 SEE ALSO 1704 1705I<pthread_attr_init()>, 1706I<pthread_attr_setscope()>, 1707I<pthread_attr_setinheritsched()>, 1708I<pthread_attr_setschedpolicy()>, 1709I<pthread_create()>, 1710I<<pthread.h>>, 1711I<pthread_setschedparam()>, 1712I<<sched.h>>. 1713 1714=head1 ______________________________________________________________________ 1715 1716=head1 NAME 1717 1718B<pthread_attr_setschedpolicy,> B<pthread_attr_getschedpolicy> 1719- set and get schedpolicy attribute 1720(B<REALTIME THREADS>) 1721 1722=head1 SYNOPSIS 1723 1724#include <pthread.h> 1725 1726int pthread_attr_setschedpolicy(pthread_attr_t *I<attr>, int I<policy>); 1727int pthread_attr_getschedpolicy(const pthread_attr_t *I<attr>, 1728int *I<policy>); 1729 1730=head1 DESCRIPTION 1731 1732The functions 1733I<pthread_attr_setschedpolicy()> 1734and 1735I<pthread_attr_getschedpolicy()>, 1736respectively, set and get the 1737I<schedpolicy> 1738attribute in the 1739I<attr> 1740argument. 1741 1742The supported values of 1743I<policy> 1744include SCHED_FIFO, SCHED_RR and SCHED_OTHER, 1745which are defined by the header 1746I<<sched.h>>. 1747When threads executing with the scheduling policy 1748SCHED_FIFO or SCHED_RR are waiting on a mutex, 1749they acquire the mutex in priority order when the mutex is unlocked. 1750 1751=head1 RETURN VALUE 1752 1753If successful, the 1754I<pthread_attr_setschedpolicy()> 1755and 1756I<pthread_attr_getschedpolicy()> 1757functions return zero. 1758Otherwise, an error number is returned to indicate the error. 1759 1760=head1 ERRORS 1761 1762The 1763I<pthread_attr_setschedpolicy()> 1764and 1765I<pthread_attr_getschedpolicy()> 1766functions will fail if: 1767 1768=over 4 1769 1770=item [ENOSYS] 1771 1772The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 1773implementation does not support the function. 1774 1775=back 1776 1777The 1778I<pthread_attr_setschedpolicy()> 1779function may fail if: 1780 1781=over 4 1782 1783=item [EINVAL] 1784 1785The value of the attribute being set is not valid. 1786 1787=item [ENOTSUP] 1788 1789An attempt was made to set the attribute to an unsupported value. 1790 1791=back 1792 1793=head1 EXAMPLES 1794 1795None. 1796 1797=head1 APPLICATION USAGE 1798 1799After these attributes have been set, a thread can be created with 1800the specified attributes using 1801I<pthread_create()>. 1802Using these routines does not affect the current running thread. 1803 1804=head1 FUTURE DIRECTIONS 1805 1806None. 1807 1808=head1 SEE ALSO 1809 1810I<pthread_attr_init()>, 1811I<pthread_attr_setscope()>, 1812I<pthread_attr_setinheritsched()>, 1813I<pthread_attr_setschedparam()>, 1814I<pthread_create()>, 1815I<<pthread.h>>, 1816I<pthread_setschedparam()>, 1817I<<sched.h>>. 1818 1819=head1 ______________________________________________________________________ 1820 1821=head1 NAME 1822 1823B<pthread_attr_setscope,> B<pthread_attr_getscope> 1824- set and get contentionscope attribute 1825(B<REALTIME THREADS>) 1826 1827=head1 SYNOPSIS 1828 1829#include <pthread.h> 1830 1831int pthread_attr_setscope(pthread_attr_t *I<attr>, int I<contentionscope>); 1832int pthread_attr_getscope(const pthread_attr_t *I<attr>, 1833int *I<contentionscope>); 1834 1835=head1 DESCRIPTION 1836 1837The 1838I<pthread_attr_setscope()> 1839and 1840I<pthread_attr_getscope()> 1841functions are used to set and get the 1842I<contentionscope> 1843attribute in the 1844I<attr> 1845object. 1846 1847The 1848I<contentionscope> 1849attribute may have the values 1850PTHREAD_SCOPE_SYSTEM, 1851signifying system scheduling contention scope, 1852or PTHREAD_SCOPE_PROCESS, 1853signifying process scheduling contention scope. 1854The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS 1855are defined by the header 1856I<<pthread.h>>. 1857 1858=head1 RETURN VALUE 1859 1860If successful, the 1861I<pthread_attr_setscope()> 1862and 1863I<pthread_attr_getscope()> 1864functions return zero. 1865Otherwise, an error number is returned to indicate the error. 1866 1867=head1 ERRORS 1868 1869The 1870I<pthread_attr_setscope()> 1871and 1872I<pthread_attr_getscope()> 1873functions will fail if: 1874 1875=over 4 1876 1877=item [ENOSYS] 1878 1879The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 1880implementation does not support the function. 1881 1882=back 1883 1884The 1885I<pthread_attr_setscope()>, 1886function may fail if: 1887 1888=over 4 1889 1890=item [EINVAL] 1891 1892The value of the attribute being set is not valid. 1893 1894=item [ENOTSUP] 1895 1896An attempt was made to set the attribute to an unsupported value. 1897 1898=back 1899 1900=head1 EXAMPLES 1901 1902None. 1903 1904=head1 APPLICATION USAGE 1905 1906After these attributes have been set, a thread can be created with 1907the specified attributes using 1908I<pthread_create()>. 1909Using these routines does not affect the current running thread. 1910 1911=head1 FUTURE DIRECTIONS 1912 1913None. 1914 1915=head1 SEE ALSO 1916 1917I<pthread_attr_init()>, 1918I<pthread_attr_setinheritsched()>, 1919I<pthread_attr_setschedpolicy()>, 1920I<pthread_attr_setschedparam()>, 1921I<pthread_create()>, 1922I<<pthread.h>>, 1923I<pthread_setschedparam()>, 1924I<<sched.h>>. 1925 1926=head1 ______________________________________________________________________ 1927 1928=head1 NAME 1929 1930B<pthread_attr_setstackaddr,> B<pthread_attr_getstackaddr> 1931- set and get stackaddr attribute 1932 1933=head1 SYNOPSIS 1934 1935#include <pthread.h> 1936 1937int pthread_attr_setstackaddr(pthread_attr_t *I<attr>, void *I<stackaddr>); 1938int pthread_attr_getstackaddr(const pthread_attr_t *I<attr>, 1939void **I<stackaddr>); 1940 1941=head1 DESCRIPTION 1942 1943The functions 1944I<pthread_attr_setstackaddr()> 1945and 1946I<pthread_attr_getstackaddr()>, 1947respectively, set and get the thread creation 1948I<stackaddr> 1949attribute in the 1950I<attr> 1951object. 1952 1953The 1954I<stackaddr> 1955attribute specifies the location of storage 1956to be used for the created thread's stack. 1957The size of the storage is at least PTHREAD_STACK_MIN. 1958 1959=head1 RETURN VALUE 1960 1961Upon successful completion, 1962I<pthread_attr_setstackaddr()> 1963and 1964I<pthread_attr_getstackaddr()> 1965return a value of 0. 1966Otherwise, an error number is returned to indicate the error. 1967 1968The 1969I<pthread_attr_getstackaddr()> 1970function stores the 1971I<stackaddr> 1972attribute value in 1973I<stackaddr> 1974if successful. 1975 1976=head1 ERRORS 1977 1978No errors are defined. 1979 1980These functions will not return an error code of [EINTR]. 1981 1982=head1 EXAMPLES 1983 1984None. 1985 1986=head1 APPLICATION USAGE 1987 1988None. 1989 1990=head1 FUTURE DIRECTIONS 1991 1992None. 1993 1994=head1 SEE ALSO 1995 1996I<pthread_attr_init()>, 1997I<pthread_attr_setdetachstate()>, 1998I<pthread_attr_setstacksize()>, 1999I<pthread_create()>, 2000I<<limits.h>>, 2001I<<pthread.h>>. 2002 2003=head1 ______________________________________________________________________ 2004 2005=head1 NAME 2006 2007B<pthread_attr_setstacksize,> B<pthread_attr_getstacksize> 2008- set and get stacksize attribute 2009 2010=head1 SYNOPSIS 2011 2012#include <pthread.h> 2013 2014int pthread_attr_setstacksize(pthread_attr_t *I<attr>, size_t I<stacksize>); 2015int pthread_attr_getstacksize(const pthread_attr_t *I<attr>, 2016size_t *I<stacksize>); 2017 2018=head1 DESCRIPTION 2019 2020The functions 2021I<pthread_attr_setstacksize()> 2022and 2023I<pthread_attr_getstacksize()>, 2024respectively, set and get the thread creation 2025I<stacksize> 2026attribute in the 2027I<attr> 2028object. 2029 2030The 2031I<stacksize> 2032attribute defines the minimum stack size (in bytes) allocated for 2033the created threads stack. 2034 2035=head1 RETURN VALUE 2036 2037Upon successful completion, 2038I<pthread_attr_setstacksize()> 2039and 2040I<pthread_attr_getstacksize()> 2041return a value of 0. 2042Otherwise, an error number is returned to indicate the error. 2043The 2044I<pthread_attr_getstacksize()> 2045function stores the 2046I<stacksize> 2047attribute value in 2048I<stacksize> 2049if successful. 2050 2051=head1 ERRORS 2052 2053The 2054I<pthread_attr_setstacksize()> 2055function will fail if: 2056 2057=over 4 2058 2059=item [EINVAL] 2060 2061The value of 2062I<stacksize> 2063is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. 2064 2065=back 2066 2067These functions will not return an error code of [EINTR]. 2068 2069=head1 EXAMPLES 2070 2071None. 2072 2073=head1 APPLICATION USAGE 2074 2075None. 2076 2077=head1 FUTURE DIRECTIONS 2078 2079None. 2080 2081=head1 SEE ALSO 2082 2083I<pthread_attr_init()>, 2084I<pthread_attr_setstackaddr()>, 2085I<pthread_attr_setdetachstate()>, 2086I<pthread_create()>, 2087I<<limits.h>>, 2088I<<pthread.h>>. 2089 2090=head1 ______________________________________________________________________ 2091 2092=head1 NAME 2093 2094B<pthread_cancel> - cancel execution of a thread 2095 2096=head1 SYNOPSIS 2097 2098#include <pthread.h> 2099 2100int pthread_cancel(pthread_t I<thread>); 2101 2102=head1 DESCRIPTION 2103 2104The 2105I<pthread_cancel()> 2106function requests that 2107I<thread> 2108be canceled. 2109The target threads cancelability state and type 2110determines when the cancellation takes effect. 2111When the cancellation is acted on, the 2112cancellation cleanup handlers for 2113I<thread> 2114are called. 2115When the last cancellation cleanup handler returns, 2116the thread-specific data destructor functions are called for 2117I<thread>. 2118When the last destructor function returns, 2119I<thread> 2120is terminated. 2121 2122The cancellation processing in the target thread runs asynchronously 2123with respect to the calling thread returning from 2124I<pthread_cancel()>. 2125 2126=head1 RETURN VALUE 2127 2128If successful, the 2129I<pthread_cancel()> 2130function returns zero. 2131Otherwise, an error number is returned to indicate the error. 2132 2133=head1 ERRORS 2134 2135The 2136I<pthread_cancel()> 2137function may fail if: 2138 2139=over 4 2140 2141=item [ESRCH] 2142 2143No thread could be found corresponding to that specified 2144by the given thread ID. 2145 2146=back 2147 2148The 2149I<pthread_cancel()> 2150function will not return an error code of [EINTR]. 2151 2152=head1 EXAMPLES 2153 2154None. 2155 2156=head1 APPLICATION USAGE 2157 2158None. 2159 2160=head1 FUTURE DIRECTIONS 2161 2162None. 2163 2164=head1 SEE ALSO 2165 2166I<pthread_exit()>, 2167I<pthread_join()>, 2168I<pthread_setcancelstate()>, 2169I<pthread_cond_wait()>, 2170I<pthread_cond_timedwait()>, 2171I<<pthread.h>>. 2172 2173=head1 ______________________________________________________________________ 2174 2175=head1 NAME 2176 2177B<pthread_cleanup_push,> B<pthread_cleanup_pop> - establish cancellation handlers 2178 2179=head1 SYNOPSIS 2180 2181#include <pthread.h> 2182 2183void pthread_cleanup_push(void (*I<routine>)(void*), void *I<arg>); 2184void pthread_cleanup_pop(int I<execute>); 2185 2186=head1 DESCRIPTION 2187 2188The 2189I<pthread_cleanup_push()> 2190function pushes the specified cancellation cleanup handler 2191I<routine> 2192onto the calling thread's cancellation cleanup stack. 2193The cancellation cleanup handler is popped from the 2194cancellation cleanup stack and invoked with the argument 2195I<arg> 2196when: (a) the thread exits (that is, calls 2197I<pthread_exit()>), 2198(b) the thread acts upon a cancellation request, or 2199(c) the thread calls 2200I<pthread_cleanup_pop()> 2201with a non-zero 2202I<execute> 2203argument. 2204 2205The 2206I<pthread_cleanup_pop()> 2207function removes the routine at the top of the calling thread's 2208cancellation cleanup stack and optionally invokes it (if 2209I<execute> 2210is non-zero). 2211 2212These functions may be implemented as macros and will 2213appear as statements and in pairs within the same lexical scope (that is, the 2214I<pthread_cleanup_push()> 2215macro may be thought to expand to a token list whose first 2216token is 2217B<`{'> 2218with 2219I<pthread_cleanup_pop()> 2220expanding to a token list whose last token is the corresponding 2221B<`}'>. 2222 2223The effect of calling 2224I<longjmp()> 2225or 2226I<siglongjmp()> 2227is undefined if there have been any calls to 2228I<pthread_cleanup_push()> 2229or 2230I<pthread_cleanup_pop()> 2231made without the matching call 2232since the jump buffer was filled. 2233The effect of calling 2234I<longjmp()> 2235or 2236I<siglongjmp()> 2237from inside a cancellation cleanup handler is also 2238undefined unless the jump buffer was also filled in the 2239cancellation cleanup handler. 2240 2241=head1 RETURN VALUE 2242 2243The 2244I<pthread_cleanup_push()> 2245and 2246I<pthread_cleanup_pop()> 2247functions return no value. 2248 2249=head1 ERRORS 2250 2251No errors are defined. 2252 2253These functions will not return an error code of [EINTR]. 2254 2255=head1 EXAMPLES 2256 2257None. 2258 2259=head1 APPLICATION USAGE 2260 2261None. 2262 2263=head1 FUTURE DIRECTIONS 2264 2265None. 2266 2267=head1 SEE ALSO 2268 2269I<pthread_cancel()>, 2270I<pthread_setcancelstate()>, 2271I<<pthread.h>>. 2272 2273=head1 ______________________________________________________________________ 2274 2275=head1 NAME 2276 2277B<pthread_cleanup_push,> B<pthread_cleanup_pop> - establish cancellation handlers 2278 2279=head1 SYNOPSIS 2280 2281#include <pthread.h> 2282 2283void pthread_cleanup_push(void (*I<routine>)(void*), void *I<arg>); 2284void pthread_cleanup_pop(int I<execute>); 2285 2286=head1 DESCRIPTION 2287 2288The 2289I<pthread_cleanup_push()> 2290function pushes the specified cancellation cleanup handler 2291I<routine> 2292onto the calling thread's cancellation cleanup stack. 2293The cancellation cleanup handler is popped from the 2294cancellation cleanup stack and invoked with the argument 2295I<arg> 2296when: (a) the thread exits (that is, calls 2297I<pthread_exit()>), 2298(b) the thread acts upon a cancellation request, or 2299(c) the thread calls 2300I<pthread_cleanup_pop()> 2301with a non-zero 2302I<execute> 2303argument. 2304 2305The 2306I<pthread_cleanup_pop()> 2307function removes the routine at the top of the calling thread's 2308cancellation cleanup stack and optionally invokes it (if 2309I<execute> 2310is non-zero). 2311 2312These functions may be implemented as macros and will 2313appear as statements and in pairs within the same lexical scope (that is, the 2314I<pthread_cleanup_push()> 2315macro may be thought to expand to a token list whose first 2316token is 2317B<`{'> 2318with 2319I<pthread_cleanup_pop()> 2320expanding to a token list whose last token is the corresponding 2321B<`}'>. 2322 2323The effect of calling 2324I<longjmp()> 2325or 2326I<siglongjmp()> 2327is undefined if there have been any calls to 2328I<pthread_cleanup_push()> 2329or 2330I<pthread_cleanup_pop()> 2331made without the matching call 2332since the jump buffer was filled. 2333The effect of calling 2334I<longjmp()> 2335or 2336I<siglongjmp()> 2337from inside a cancellation cleanup handler is also 2338undefined unless the jump buffer was also filled in the 2339cancellation cleanup handler. 2340 2341=head1 RETURN VALUE 2342 2343The 2344I<pthread_cleanup_push()> 2345and 2346I<pthread_cleanup_pop()> 2347functions return no value. 2348 2349=head1 ERRORS 2350 2351No errors are defined. 2352 2353These functions will not return an error code of [EINTR]. 2354 2355=head1 EXAMPLES 2356 2357None. 2358 2359=head1 APPLICATION USAGE 2360 2361None. 2362 2363=head1 FUTURE DIRECTIONS 2364 2365None. 2366 2367=head1 SEE ALSO 2368 2369I<pthread_cancel()>, 2370I<pthread_setcancelstate()>, 2371I<<pthread.h>>. 2372 2373=head1 ______________________________________________________________________ 2374 2375=head1 NAME 2376 2377B<pthread_cond_signal,> B<pthread_cond_broadcast> - signal or broadcast a 2378condition 2379 2380=head1 SYNOPSIS 2381 2382#include <pthread.h> 2383 2384int pthread_cond_signal(pthread_cond_t *I<cond>); 2385int pthread_cond_broadcast(pthread_cond_t *I<cond>); 2386 2387=head1 DESCRIPTION 2388 2389These two functions are used to unblock 2390threads blocked on a condition variable. 2391 2392The 2393I<pthread_cond_signal()> 2394call unblocks at least one of the threads that are blocked on the 2395specified condition variable 2396I<cond> 2397(if any threads are blocked on 2398I<cond>). 2399 2400The 2401I<pthread_cond_broadcast()> 2402call unblocks all threads currently blocked on the specified condition variable 2403I<cond>. 2404 2405If more than one thread is blocked on a condition variable, 2406the scheduling policy determines the order in which threads are unblocked. 2407When each thread unblocked as a result of a 2408I<pthread_cond_signal()> 2409or 2410I<pthread_cond_broadcast()> 2411returns from its call to 2412I<pthread_cond_wait()> 2413or 2414I<pthread_cond_timedwait()>, 2415the thread owns the mutex with which it called 2416I<pthread_cond_wait()> 2417or 2418I<pthread_cond_timedwait()>. 2419The thread(s) that are unblocked contend for the mutex 2420according to the scheduling policy (if applicable), 2421and as if each had called 2422I<pthread_mutex_lock()>. 2423 2424The 2425I<pthread_cond_signal()> 2426or 2427I<pthread_cond_broadcast()> 2428functions may be called by a thread whether or not it 2429currently owns the mutex that threads calling 2430I<pthread_cond_wait()> 2431or 2432I<pthread_cond_timedwait()> 2433have associated with the condition variable during their waits; 2434however, if predictable scheduling behaviour is required, 2435then that mutex is locked by the thread calling 2436I<pthread_cond_signal()> 2437or 2438I<pthread_cond_broadcast()>. 2439 2440The 2441I<pthread_cond_signal()> 2442and 2443I<pthread_cond_broadcast()> 2444functions have no effect if there are no threads 2445currently blocked on 2446I<cond>. 2447 2448=head1 RETURN VALUE 2449 2450If successful, the 2451I<pthread_cond_signal()> 2452and 2453I<pthread_cond_broadcast()> 2454functions return zero. 2455Otherwise, an error number is returned to indicate the error. 2456 2457=head1 ERRORS 2458 2459The 2460I<pthread_cond_signal()> 2461and 2462I<pthread_cond_broadcast()> 2463function may fail if: 2464 2465=over 4 2466 2467=item [EINVAL] 2468 2469The value 2470I<cond> 2471does not refer to an initialised condition variable. 2472 2473=back 2474 2475These functions will not return an error code of [EINTR]. 2476 2477=head1 EXAMPLES 2478 2479None. 2480 2481=head1 APPLICATION USAGE 2482 2483None. 2484 2485=head1 FUTURE DIRECTIONS 2486 2487None. 2488 2489=head1 SEE ALSO 2490 2491I<pthread_cond_init()>, 2492I<pthread_cond_wait()>, 2493I<pthread_cond_timedwait()>, 2494I<<pthread.h>>. 2495 2496 2497=head1 ______________________________________________________________________ 2498 2499=head1 NAME 2500 2501B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy 2502condition variables 2503 2504=head1 SYNOPSIS 2505 2506#include <pthread.h> 2507 2508int pthread_cond_init(pthread_cond_t *I<cond>, 2509const pthread_condattr_t *I<attr>); 2510int pthread_cond_destroy(pthread_cond_t *I<cond>); 2511pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER; 2512 2513=head1 DESCRIPTION 2514 2515The function 2516I<pthread_cond_init()> 2517initialises the condition variable referenced by 2518I<cond> 2519with attributes referenced by 2520I<attr>. 2521If 2522I<attr> 2523is NULL, 2524the default condition variable attributes are used; 2525the effect is the same as passing the address 2526of a default condition variable attributes object. 2527Upon successful initialisation, 2528the state of the condition variable becomes initialised. 2529 2530Attempting to initialise an already initialised 2531condition variable 2532results in undefined behaviour. 2533 2534The function 2535I<pthread_cond_destroy()> 2536destroys the given condition variable specified by 2537I<cond>; 2538the object becomes, in effect, uninitialised. 2539An implementation may cause 2540I<pthread_cond_destroy()> 2541to set the object referenced by 2542I<cond> 2543to an invalid value. 2544A destroyed condition variable object 2545can be re-initialised using 2546I<pthread_cond_init()>; 2547the results of otherwise referencing the object after it has been destroyed 2548are undefined. 2549 2550It is safe to destroy an initialised condition variable 2551upon which no threads are currently blocked. 2552Attempting to destroy a condition variable 2553upon which other threads are currently blocked 2554results in undefined behaviour. 2555 2556In cases where default condition variable attributes are appropriate, 2557the macro PTHREAD_COND_INITIALIZER 2558can be used to initialise condition variables that are statically allocated. 2559The effect is equivalent to dynamic initialisation by a call to 2560I<pthread_cond_init()> 2561with parameter 2562I<attr> 2563specified as NULL, except that no error checks are performed. 2564 2565=head1 RETURN VALUE 2566 2567If successful, the 2568I<pthread_cond_init()> 2569and 2570I<pthread_cond_destroy()> 2571functions return zero. 2572Otherwise, an error number is returned to indicate the error. 2573The [EBUSY] and [EINVAL] 2574error checks, if implemented, 2575act as if they were performed immediately 2576at the beginning of processing for the function 2577and caused an error return 2578prior to modifying the state of the condition variable specified by 2579I<cond>. 2580 2581=head1 ERRORS 2582 2583The 2584I<pthread_cond_init()> 2585function will fail if: 2586 2587=over 4 2588 2589=item [EAGAIN] 2590 2591The system lacked the necessary resources (other 2592than memory) to initialise another condition variable. 2593 2594=item [ENOMEM] 2595 2596Insufficient memory exists to initialise the condition variable. 2597 2598=back 2599 2600The 2601I<pthread_cond_init()> 2602function may fail if: 2603 2604=over 4 2605 2606=item [EBUSY] 2607 2608The implementation has detected an attempt 2609to re-initialise the object referenced by 2610I<cond>, 2611a previously initialised, but 2612not yet destroyed, condition variable. 2613 2614=item [EINVAL] 2615 2616The value specified by 2617I<attr> 2618is invalid. 2619 2620=back 2621 2622 2623 2624The 2625I<pthread_cond_destroy()> 2626function may fail if: 2627 2628=over 4 2629 2630=item [EBUSY] 2631 2632The implementation has detected an attempt to destroy 2633the object referenced by 2634I<cond> 2635while it is referenced 2636(for example, while being used in a 2637I<pthread_cond_wait()> 2638or 2639I<pthread_cond_timedwait()>) 2640by another thread. 2641 2642=item [EINVAL] 2643 2644The value specified by 2645I<cond> 2646is invalid. 2647 2648=back 2649 2650These functions will not return an error code of [EINTR]. 2651 2652=head1 EXAMPLES 2653 2654None. 2655 2656=head1 APPLICATION USAGE 2657 2658None. 2659 2660=head1 FUTURE DIRECTIONS 2661 2662None. 2663 2664=head1 SEE ALSO 2665 2666I<pthread_cond_signal()>, 2667I<pthread_cond_broadcast()>, 2668I<pthread_cond_wait()>, 2669I<pthread_cond_timedwait()>, 2670I<<pthread.h>>. 2671 2672=head1 ______________________________________________________________________ 2673 2674=head1 NAME 2675 2676B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy 2677condition variables 2678 2679=head1 SYNOPSIS 2680 2681#include <pthread.h> 2682 2683int pthread_cond_init(pthread_cond_t *I<cond>, 2684const pthread_condattr_t *I<attr>); 2685int pthread_cond_destroy(pthread_cond_t *I<cond>); 2686pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER; 2687 2688=head1 DESCRIPTION 2689 2690The function 2691I<pthread_cond_init()> 2692initialises the condition variable referenced by 2693I<cond> 2694with attributes referenced by 2695I<attr>. 2696If 2697I<attr> 2698is NULL, 2699the default condition variable attributes are used; 2700the effect is the same as passing the address 2701of a default condition variable attributes object. 2702Upon successful initialisation, 2703the state of the condition variable becomes initialised. 2704 2705Attempting to initialise an already initialised 2706condition variable 2707results in undefined behaviour. 2708 2709The function 2710I<pthread_cond_destroy()> 2711destroys the given condition variable specified by 2712I<cond>; 2713the object becomes, in effect, uninitialised. 2714An implementation may cause 2715I<pthread_cond_destroy()> 2716to set the object referenced by 2717I<cond> 2718to an invalid value. 2719A destroyed condition variable object 2720can be re-initialised using 2721I<pthread_cond_init()>; 2722the results of otherwise referencing the object after it has been destroyed 2723are undefined. 2724 2725It is safe to destroy an initialised condition variable 2726upon which no threads are currently blocked. 2727Attempting to destroy a condition variable 2728upon which other threads are currently blocked 2729results in undefined behaviour. 2730 2731In cases where default condition variable attributes are appropriate, 2732the macro PTHREAD_COND_INITIALIZER 2733can be used to initialise condition variables that are statically allocated. 2734The effect is equivalent to dynamic initialisation by a call to 2735I<pthread_cond_init()> 2736with parameter 2737I<attr> 2738specified as NULL, except that no error checks are performed. 2739 2740=head1 RETURN VALUE 2741 2742If successful, the 2743I<pthread_cond_init()> 2744and 2745I<pthread_cond_destroy()> 2746functions return zero. 2747Otherwise, an error number is returned to indicate the error. 2748The [EBUSY] and [EINVAL] 2749error checks, if implemented, 2750act as if they were performed immediately 2751at the beginning of processing for the function 2752and caused an error return 2753prior to modifying the state of the condition variable specified by 2754I<cond>. 2755 2756=head1 ERRORS 2757 2758The 2759I<pthread_cond_init()> 2760function will fail if: 2761 2762=over 4 2763 2764=item [EAGAIN] 2765 2766The system lacked the necessary resources (other 2767than memory) to initialise another condition variable. 2768 2769=item [ENOMEM] 2770 2771Insufficient memory exists to initialise the condition variable. 2772 2773=back 2774 2775The 2776I<pthread_cond_init()> 2777function may fail if: 2778 2779=over 4 2780 2781=item [EBUSY] 2782 2783The implementation has detected an attempt 2784to re-initialise the object referenced by 2785I<cond>, 2786a previously initialised, but 2787not yet destroyed, condition variable. 2788 2789=item [EINVAL] 2790 2791The value specified by 2792I<attr> 2793is invalid. 2794 2795=back 2796 2797 2798 2799The 2800I<pthread_cond_destroy()> 2801function may fail if: 2802 2803=over 4 2804 2805=item [EBUSY] 2806 2807The implementation has detected an attempt to destroy 2808the object referenced by 2809I<cond> 2810while it is referenced 2811(for example, while being used in a 2812I<pthread_cond_wait()> 2813or 2814I<pthread_cond_timedwait()>) 2815by another thread. 2816 2817=item [EINVAL] 2818 2819The value specified by 2820I<cond> 2821is invalid. 2822 2823=back 2824 2825These functions will not return an error code of [EINTR]. 2826 2827=head1 EXAMPLES 2828 2829None. 2830 2831=head1 APPLICATION USAGE 2832 2833None. 2834 2835=head1 FUTURE DIRECTIONS 2836 2837None. 2838 2839=head1 SEE ALSO 2840 2841I<pthread_cond_signal()>, 2842I<pthread_cond_broadcast()>, 2843I<pthread_cond_wait()>, 2844I<pthread_cond_timedwait()>, 2845I<<pthread.h>>. 2846 2847=head1 ______________________________________________________________________ 2848 2849=head1 NAME 2850 2851B<pthread_cond_signal,> B<pthread_cond_broadcast> - signal or broadcast a 2852condition 2853 2854=head1 SYNOPSIS 2855 2856#include <pthread.h> 2857 2858int pthread_cond_signal(pthread_cond_t *I<cond>); 2859int pthread_cond_broadcast(pthread_cond_t *I<cond>); 2860 2861=head1 DESCRIPTION 2862 2863These two functions are used to unblock 2864threads blocked on a condition variable. 2865 2866The 2867I<pthread_cond_signal()> 2868call unblocks at least one of the threads that are blocked on the 2869specified condition variable 2870I<cond> 2871(if any threads are blocked on 2872I<cond>). 2873 2874The 2875I<pthread_cond_broadcast()> 2876call unblocks all threads currently blocked on the specified condition variable 2877I<cond>. 2878 2879If more than one thread is blocked on a condition variable, 2880the scheduling policy determines the order in which threads are unblocked. 2881When each thread unblocked as a result of a 2882I<pthread_cond_signal()> 2883or 2884I<pthread_cond_broadcast()> 2885returns from its call to 2886I<pthread_cond_wait()> 2887or 2888I<pthread_cond_timedwait()>, 2889the thread owns the mutex with which it called 2890I<pthread_cond_wait()> 2891or 2892I<pthread_cond_timedwait()>. 2893The thread(s) that are unblocked contend for the mutex 2894according to the scheduling policy (if applicable), 2895and as if each had called 2896I<pthread_mutex_lock()>. 2897 2898The 2899I<pthread_cond_signal()> 2900or 2901I<pthread_cond_broadcast()> 2902functions may be called by a thread whether or not it 2903currently owns the mutex that threads calling 2904I<pthread_cond_wait()> 2905or 2906I<pthread_cond_timedwait()> 2907have associated with the condition variable during their waits; 2908however, if predictable scheduling behaviour is required, 2909then that mutex is locked by the thread calling 2910I<pthread_cond_signal()> 2911or 2912I<pthread_cond_broadcast()>. 2913 2914The 2915I<pthread_cond_signal()> 2916and 2917I<pthread_cond_broadcast()> 2918functions have no effect if there are no threads 2919currently blocked on 2920I<cond>. 2921 2922=head1 RETURN VALUE 2923 2924If successful, the 2925I<pthread_cond_signal()> 2926and 2927I<pthread_cond_broadcast()> 2928functions return zero. 2929Otherwise, an error number is returned to indicate the error. 2930 2931=head1 ERRORS 2932 2933The 2934I<pthread_cond_signal()> 2935and 2936I<pthread_cond_broadcast()> 2937function may fail if: 2938 2939=over 4 2940 2941=item [EINVAL] 2942 2943The value 2944I<cond> 2945does not refer to an initialised condition variable. 2946 2947=back 2948 2949These functions will not return an error code of [EINTR]. 2950 2951=head1 EXAMPLES 2952 2953None. 2954 2955=head1 APPLICATION USAGE 2956 2957None. 2958 2959=head1 FUTURE DIRECTIONS 2960 2961None. 2962 2963=head1 SEE ALSO 2964 2965I<pthread_cond_init()>, 2966I<pthread_cond_wait()>, 2967I<pthread_cond_timedwait()>, 2968I<<pthread.h>>. 2969 2970 2971=head1 ______________________________________________________________________ 2972 2973=head1 NAME 2974 2975B<pthread_cond_wait,> B<pthread_cond_timedwait> - wait on a condition 2976 2977=head1 SYNOPSIS 2978 2979#include <pthread.h> 2980 2981int pthread_cond_wait(pthread_cond_t *I<cond>, pthread_mutex_t *I<mutex>); 2982int pthread_cond_timedwait(pthread_cond_t *I<cond>, 2983pthread_mutex_t *I<mutex>, const struct timespec *I<abstime>); 2984 2985=head1 DESCRIPTION 2986 2987The 2988I<pthread_cond_wait()> 2989and 2990I<pthread_cond_timedwait()> 2991functions are used to block on a condition variable. 2992They are called with 2993I<mutex> 2994locked by the calling thread or undefined behaviour will result. 2995 2996These functions atomically release 2997I<mutex> 2998and cause the calling thread to block on the condition variable 2999I<cond>; 3000atomically here means "atomically with respect to access by another 3001thread to the mutex and then the condition variable". 3002That is, if another thread is able to acquire the mutex 3003after the about-to-block thread has released it, 3004then a subsequent call to 3005I<pthread_cond_signal()> 3006or 3007I<pthread_cond_broadcast()> 3008in that thread behaves as if it were issued 3009after the about-to-block thread has blocked. 3010 3011Upon successful return, the mutex has been 3012locked and is owned by the calling thread. 3013 3014When using condition variables there is always a boolean predicate involving 3015shared variables associated with each condition wait that is true if the thread 3016should proceed. 3017Spurious wakeups from the 3018I<pthread_cond_wait()> 3019or 3020I<pthread_cond_timedwait()> 3021functions may occur. 3022Since the return from 3023I<pthread_cond_wait()> 3024or 3025I<pthread_cond_timedwait()> 3026does not imply anything about the value of this predicate, 3027the predicate should be re-evaluated upon such return. 3028 3029The effect of using more than one mutex for concurrent 3030I<pthread_cond_wait()> 3031or 3032I<pthread_cond_timedwait()> 3033operations on the same condition variable is 3034undefined; that is, a condition variable becomes bound to a unique mutex 3035when a thread 3036waits on the condition variable, 3037and this (dynamic) binding ends when the wait returns. 3038 3039A condition wait (whether timed or not) is a cancellation point. 3040When the cancelability enable state of a thread is set to 3041PTHREAD_CANCEL_DEFERRED, 3042a side effect of acting upon a cancellation request 3043while in a condition wait is that the mutex is (in effect) re-acquired 3044before calling the first cancellation cleanup handler. 3045The effect is as if the thread were unblocked, 3046allowed to execute up to the point of returning from the 3047call to 3048I<pthread_cond_wait()> 3049or 3050I<pthread_cond_timedwait()>, 3051but at that point 3052notices the cancellation request and instead of returning to the caller 3053of 3054I<pthread_cond_wait()> 3055or 3056I<pthread_cond_timedwait()>, 3057starts the thread cancellation activities, which includes calling 3058cancellation cleanup handlers. 3059 3060A thread that has been unblocked because it has been 3061canceled while blocked in a call to 3062I<pthread_cond_wait()> 3063or 3064I<pthread_cond_timedwait()> 3065does not consume any condition signal that may be 3066directed concurrently at the 3067condition variable if there are other threads blocked on 3068the condition variable. 3069 3070The 3071I<pthread_cond_timedwait()> 3072function is the same as 3073I<pthread_cond_wait()> 3074except that 3075an error is returned 3076if the absolute time specified by 3077I<abstime> 3078passes (that is, system time equals or exceeds 3079I<abstime>) 3080before the condition 3081I<cond> 3082is signaled or broadcasted, 3083or if the absolute time specified by 3084I<abstime> 3085has already been passed at the time of the call. 3086When such time-outs occur, 3087I<pthread_cond_timedwait()> 3088will nonetheless release 3089and reacquire the mutex referenced by 3090I<mutex>. 3091The function 3092I<pthread_cond_timedwait()> 3093is also a cancellation point. 3094 3095If a signal is delivered to a thread waiting for a condition variable, 3096upon return from the signal handler 3097the thread resumes waiting for the condition variable 3098as if it was not interrupted, 3099or it returns zero due to spurious wakeup. 3100 3101=head1 RETURN VALUE 3102 3103Except in the case of [ETIMEDOUT], 3104all these error checks act as if they were performed immediately 3105at the beginning of processing for the function 3106and cause an error return, 3107in effect, prior to modifying the state of the mutex specified by 3108I<mutex> 3109or the condition variable specified by 3110I<cond>. 3111 3112Upon successful completion, a value of zero is returned. 3113Otherwise, an error number is returned to indicate the error. 3114 3115=head1 ERRORS 3116 3117The 3118I<pthread_cond_timedwait()> 3119function will fail if: 3120 3121=over 4 3122 3123=item [ETIMEDOUT] 3124 3125The time specified by 3126I<abstime> 3127to 3128I<pthread_cond_timedwait()> 3129has passed. 3130 3131=back 3132 3133The 3134I<pthread_cond_wait()> 3135and 3136I<pthread_cond_timedwait()> 3137functions may fail if: 3138 3139=over 4 3140 3141=item [EINVAL] 3142 3143The value specified by 3144I<cond>, 3145I<mutex>, 3146or 3147I<abstime> 3148is invalid. 3149 3150=item [EINVAL] 3151 3152Different mutexes were supplied for concurrent 3153I<pthread_cond_wait()> 3154or 3155I<pthread_cond_timedwait()> 3156operations on the same condition variable. 3157 3158=item [EINVAL] 3159 3160The mutex was not owned by the current thread at the time of the call. 3161 3162=back 3163 3164These functions will not return an error code of [EINTR]. 3165 3166=head1 EXAMPLES 3167 3168None. 3169 3170=head1 APPLICATION USAGE 3171 3172None. 3173 3174=head1 FUTURE DIRECTIONS 3175 3176None. 3177 3178=head1 SEE ALSO 3179 3180I<pthread_cond_signal()>, 3181I<pthread_cond_broadcast()>, 3182I<<pthread.h>>. 3183 3184=head1 ______________________________________________________________________ 3185 3186=head1 NAME 3187 3188B<pthread_cond_wait,> B<pthread_cond_timedwait> - wait on a condition 3189 3190=head1 SYNOPSIS 3191 3192#include <pthread.h> 3193 3194int pthread_cond_wait(pthread_cond_t *I<cond>, pthread_mutex_t *I<mutex>); 3195int pthread_cond_timedwait(pthread_cond_t *I<cond>, 3196pthread_mutex_t *I<mutex>, const struct timespec *I<abstime>); 3197 3198=head1 DESCRIPTION 3199 3200The 3201I<pthread_cond_wait()> 3202and 3203I<pthread_cond_timedwait()> 3204functions are used to block on a condition variable. 3205They are called with 3206I<mutex> 3207locked by the calling thread or undefined behaviour will result. 3208 3209These functions atomically release 3210I<mutex> 3211and cause the calling thread to block on the condition variable 3212I<cond>; 3213atomically here means "atomically with respect to access by another 3214thread to the mutex and then the condition variable". 3215That is, if another thread is able to acquire the mutex 3216after the about-to-block thread has released it, 3217then a subsequent call to 3218I<pthread_cond_signal()> 3219or 3220I<pthread_cond_broadcast()> 3221in that thread behaves as if it were issued 3222after the about-to-block thread has blocked. 3223 3224Upon successful return, the mutex has been 3225locked and is owned by the calling thread. 3226 3227When using condition variables there is always a boolean predicate involving 3228shared variables associated with each condition wait that is true if the thread 3229should proceed. 3230Spurious wakeups from the 3231I<pthread_cond_wait()> 3232or 3233I<pthread_cond_timedwait()> 3234functions may occur. 3235Since the return from 3236I<pthread_cond_wait()> 3237or 3238I<pthread_cond_timedwait()> 3239does not imply anything about the value of this predicate, 3240the predicate should be re-evaluated upon such return. 3241 3242The effect of using more than one mutex for concurrent 3243I<pthread_cond_wait()> 3244or 3245I<pthread_cond_timedwait()> 3246operations on the same condition variable is 3247undefined; that is, a condition variable becomes bound to a unique mutex 3248when a thread 3249waits on the condition variable, 3250and this (dynamic) binding ends when the wait returns. 3251 3252A condition wait (whether timed or not) is a cancellation point. 3253When the cancelability enable state of a thread is set to 3254PTHREAD_CANCEL_DEFERRED, 3255a side effect of acting upon a cancellation request 3256while in a condition wait is that the mutex is (in effect) re-acquired 3257before calling the first cancellation cleanup handler. 3258The effect is as if the thread were unblocked, 3259allowed to execute up to the point of returning from the 3260call to 3261I<pthread_cond_wait()> 3262or 3263I<pthread_cond_timedwait()>, 3264but at that point 3265notices the cancellation request and instead of returning to the caller 3266of 3267I<pthread_cond_wait()> 3268or 3269I<pthread_cond_timedwait()>, 3270starts the thread cancellation activities, which includes calling 3271cancellation cleanup handlers. 3272 3273A thread that has been unblocked because it has been 3274canceled while blocked in a call to 3275I<pthread_cond_wait()> 3276or 3277I<pthread_cond_timedwait()> 3278does not consume any condition signal that may be 3279directed concurrently at the 3280condition variable if there are other threads blocked on 3281the condition variable. 3282 3283The 3284I<pthread_cond_timedwait()> 3285function is the same as 3286I<pthread_cond_wait()> 3287except that 3288an error is returned 3289if the absolute time specified by 3290I<abstime> 3291passes (that is, system time equals or exceeds 3292I<abstime>) 3293before the condition 3294I<cond> 3295is signaled or broadcasted, 3296or if the absolute time specified by 3297I<abstime> 3298has already been passed at the time of the call. 3299When such time-outs occur, 3300I<pthread_cond_timedwait()> 3301will nonetheless release 3302and reacquire the mutex referenced by 3303I<mutex>. 3304The function 3305I<pthread_cond_timedwait()> 3306is also a cancellation point. 3307 3308If a signal is delivered to a thread waiting for a condition variable, 3309upon return from the signal handler 3310the thread resumes waiting for the condition variable 3311as if it was not interrupted, 3312or it returns zero due to spurious wakeup. 3313 3314=head1 RETURN VALUE 3315 3316Except in the case of [ETIMEDOUT], 3317all these error checks act as if they were performed immediately 3318at the beginning of processing for the function 3319and cause an error return, 3320in effect, prior to modifying the state of the mutex specified by 3321I<mutex> 3322or the condition variable specified by 3323I<cond>. 3324 3325Upon successful completion, a value of zero is returned. 3326Otherwise, an error number is returned to indicate the error. 3327 3328=head1 ERRORS 3329 3330The 3331I<pthread_cond_timedwait()> 3332function will fail if: 3333 3334=over 4 3335 3336=item [ETIMEDOUT] 3337 3338The time specified by 3339I<abstime> 3340to 3341I<pthread_cond_timedwait()> 3342has passed. 3343 3344=back 3345 3346The 3347I<pthread_cond_wait()> 3348and 3349I<pthread_cond_timedwait()> 3350functions may fail if: 3351 3352=over 4 3353 3354=item [EINVAL] 3355 3356The value specified by 3357I<cond>, 3358I<mutex>, 3359or 3360I<abstime> 3361is invalid. 3362 3363=item [EINVAL] 3364 3365Different mutexes were supplied for concurrent 3366I<pthread_cond_wait()> 3367or 3368I<pthread_cond_timedwait()> 3369operations on the same condition variable. 3370 3371=item [EINVAL] 3372 3373The mutex was not owned by the current thread at the time of the call. 3374 3375=back 3376 3377These functions will not return an error code of [EINTR]. 3378 3379=head1 EXAMPLES 3380 3381None. 3382 3383=head1 APPLICATION USAGE 3384 3385None. 3386 3387=head1 FUTURE DIRECTIONS 3388 3389None. 3390 3391=head1 SEE ALSO 3392 3393I<pthread_cond_signal()>, 3394I<pthread_cond_broadcast()>, 3395I<<pthread.h>>. 3396 3397=head1 ______________________________________________________________________ 3398 3399=head1 NAME 3400 3401B<pthread_condattr_init,> B<pthread_condattr_destroy> 3402- initialise and destroy condition variable attributes object 3403 3404=head1 SYNOPSIS 3405 3406#include <pthread.h> 3407 3408int pthread_condattr_init(pthread_condattr_t *I<attr>); 3409int pthread_condattr_destroy(pthread_condattr_t *I<attr>); 3410 3411=head1 DESCRIPTION 3412 3413The function 3414I<pthread_condattr_init()> 3415initialises a condition variable attributes object 3416I<attr> 3417with the default value for all of the attributes 3418defined by the implementation. 3419 3420Attempting to initialise an already initialised 3421condition variable attributes object 3422results in undefined behaviour. 3423 3424After a condition variable 3425attributes object has been used to initialise one or more 3426condition variables, any function affecting the attributes object (including 3427destruction) does not affect any previously initialised condition variables. 3428 3429The 3430I<pthread_condattr_destroy()> 3431function destroys a condition variable attributes object; 3432the object becomes, in effect, uninitialised. 3433An implementation may cause 3434I<pthread_condattr_destroy()> 3435to set the object referenced by 3436I<attr> 3437to an invalid value. 3438A destroyed condition variable attributes object 3439can be re-initialised using 3440I<pthread_condattr_init()>; 3441the results of otherwise referencing the object after it has been destroyed 3442are undefined. 3443 3444Additional attributes, their default values, and the names 3445of the associated functions to get and set those attribute values are 3446implementation-dependent. 3447 3448=head1 RETURN VALUE 3449 3450If successful, the 3451I<pthread_condattr_init()> 3452and 3453I<pthread_condattr_destroy()> 3454functions return zero. 3455Otherwise, an error number is returned to indicate the error. 3456 3457=head1 ERRORS 3458 3459The 3460I<pthread_condattr_init()> 3461function will fail if: 3462 3463=over 4 3464 3465=item [ENOMEM] 3466 3467Insufficient memory exists to initialise the condition variable 3468attributes object. 3469 3470=back 3471 3472The 3473I<pthread_condattr_destroy()> 3474function may fail if: 3475 3476=over 4 3477 3478=item [EINVAL] 3479 3480The value specified by 3481I<attr> 3482is invalid. 3483 3484=back 3485 3486These functions will not return an error code of [EINTR]. 3487 3488=head1 EXAMPLES 3489 3490None. 3491 3492=head1 APPLICATION USAGE 3493 3494None. 3495 3496=head1 FUTURE DIRECTIONS 3497 3498None. 3499 3500=head1 SEE ALSO 3501 3502I<pthread_condattr_getpshared()>, 3503I<pthread_create()>, 3504I<pthread_mutex_init()>, 3505I<pthread_cond_init()>, 3506I<<pthread.h>>. 3507 3508 3509=head1 ______________________________________________________________________ 3510 3511=head1 NAME 3512 3513B<pthread_condattr_getpshared,> B<pthread_condattr_setpshared> 3514- get and set the process-shared condition variable attributes 3515 3516=head1 SYNOPSIS 3517 3518#include <pthread.h> 3519 3520int pthread_condattr_getpshared(const pthread_condattr_t *I<attr>, 3521int *I<pshared>); 3522int pthread_condattr_setpshared(pthread_condattr_t *I<attr>, 3523int I<pshared>); 3524 3525=head1 DESCRIPTION 3526 3527The 3528I<pthread_condattr_getpshared()> 3529function obtains the value of the 3530I<process-shared> 3531attribute from the attributes object referenced by 3532I<attr>. 3533The 3534I<pthread_condattr_setpshared()> 3535function is used to set the 3536I<process-shared> 3537attribute in an initialised attributes object referenced by 3538I<attr>. 3539 3540The 3541I<process-shared> 3542attribute is set to PTHREAD_PROCESS_SHARED 3543to permit a condition variable 3544to be operated upon by any thread that has access to the memory 3545where the condition variable 3546is allocated, even if the condition variable 3547is allocated in memory that is shared by multiple processes. 3548If the 3549I<process-shared> 3550attribute is PTHREAD_PROCESS_PRIVATE, the condition variable 3551will only be operated upon by threads created 3552within the same process as the 3553thread that initialised the condition variable; 3554if threads of differing processes 3555attempt to operate on such a condition variable, the behaviour is 3556undefined. The default value of the attribute is 3557PTHREAD_PROCESS_PRIVATE. 3558 3559Additional attributes, their default values, and the names 3560of the associated functions to get and set those attribute values are 3561implementation-dependent. 3562 3563=head1 RETURN VALUE 3564 3565If successful, the 3566I<pthread_condattr_setpshared()> 3567function returns zero. 3568Otherwise, an error number is returned to indicate the error. 3569 3570If successful, the 3571I<pthread_condattr_getpshared()> 3572function returns zero 3573and stores the value of the 3574I<process-shared> 3575attribute of 3576I<attr> 3577into the object referenced by the 3578I<pshared> 3579parameter. 3580Otherwise, an error number is returned to indicate the error. 3581 3582=head1 ERRORS 3583 3584The 3585I<pthread_condattr_getpshared()> 3586and 3587I<pthread_condattr_setpshared()> 3588functions may fail if: 3589 3590=over 4 3591 3592=item [EINVAL] 3593 3594The value specified by 3595I<attr> 3596is invalid. 3597 3598=back 3599 3600The 3601I<pthread_condattr_setpshared()> 3602function may fail if: 3603 3604=over 4 3605 3606=item [EINVAL] 3607 3608The new value specified for the attribute 3609is outside the range of legal values for that attribute. 3610 3611=back 3612 3613These functions will not return an error code of [EINTR]. 3614 3615=head1 EXAMPLES 3616 3617None. 3618 3619=head1 APPLICATION USAGE 3620 3621None. 3622 3623=head1 FUTURE DIRECTIONS 3624 3625None. 3626 3627=head1 SEE ALSO 3628 3629I<pthread_condattr_init()>, 3630I<pthread_create()>, 3631I<pthread_mutex_init()>, 3632I<pthread_cond_init()>, 3633I<<pthread.h>>. 3634 3635=head1 ______________________________________________________________________ 3636 3637=head1 NAME 3638 3639B<pthread_condattr_init,> B<pthread_condattr_destroy> 3640- initialise and destroy condition variable attributes object 3641 3642=head1 SYNOPSIS 3643 3644#include <pthread.h> 3645 3646int pthread_condattr_init(pthread_condattr_t *I<attr>); 3647int pthread_condattr_destroy(pthread_condattr_t *I<attr>); 3648 3649=head1 DESCRIPTION 3650 3651The function 3652I<pthread_condattr_init()> 3653initialises a condition variable attributes object 3654I<attr> 3655with the default value for all of the attributes 3656defined by the implementation. 3657 3658Attempting to initialise an already initialised 3659condition variable attributes object 3660results in undefined behaviour. 3661 3662After a condition variable 3663attributes object has been used to initialise one or more 3664condition variables, any function affecting the attributes object (including 3665destruction) does not affect any previously initialised condition variables. 3666 3667The 3668I<pthread_condattr_destroy()> 3669function destroys a condition variable attributes object; 3670the object becomes, in effect, uninitialised. 3671An implementation may cause 3672I<pthread_condattr_destroy()> 3673to set the object referenced by 3674I<attr> 3675to an invalid value. 3676A destroyed condition variable attributes object 3677can be re-initialised using 3678I<pthread_condattr_init()>; 3679the results of otherwise referencing the object after it has been destroyed 3680are undefined. 3681 3682Additional attributes, their default values, and the names 3683of the associated functions to get and set those attribute values are 3684implementation-dependent. 3685 3686=head1 RETURN VALUE 3687 3688If successful, the 3689I<pthread_condattr_init()> 3690and 3691I<pthread_condattr_destroy()> 3692functions return zero. 3693Otherwise, an error number is returned to indicate the error. 3694 3695=head1 ERRORS 3696 3697The 3698I<pthread_condattr_init()> 3699function will fail if: 3700 3701=over 4 3702 3703=item [ENOMEM] 3704 3705Insufficient memory exists to initialise the condition variable 3706attributes object. 3707 3708=back 3709 3710The 3711I<pthread_condattr_destroy()> 3712function may fail if: 3713 3714=over 4 3715 3716=item [EINVAL] 3717 3718The value specified by 3719I<attr> 3720is invalid. 3721 3722=back 3723 3724These functions will not return an error code of [EINTR]. 3725 3726=head1 EXAMPLES 3727 3728None. 3729 3730=head1 APPLICATION USAGE 3731 3732None. 3733 3734=head1 FUTURE DIRECTIONS 3735 3736None. 3737 3738=head1 SEE ALSO 3739 3740I<pthread_condattr_getpshared()>, 3741I<pthread_create()>, 3742I<pthread_mutex_init()>, 3743I<pthread_cond_init()>, 3744I<<pthread.h>>. 3745 3746 3747=head1 ______________________________________________________________________ 3748 3749=head1 NAME 3750 3751B<pthread_condattr_getpshared,> B<pthread_condattr_setpshared> 3752- get and set the process-shared condition variable attributes 3753 3754=head1 SYNOPSIS 3755 3756#include <pthread.h> 3757 3758int pthread_condattr_getpshared(const pthread_condattr_t *I<attr>, 3759int *I<pshared>); 3760int pthread_condattr_setpshared(pthread_condattr_t *I<attr>, 3761int I<pshared>); 3762 3763=head1 DESCRIPTION 3764 3765The 3766I<pthread_condattr_getpshared()> 3767function obtains the value of the 3768I<process-shared> 3769attribute from the attributes object referenced by 3770I<attr>. 3771The 3772I<pthread_condattr_setpshared()> 3773function is used to set the 3774I<process-shared> 3775attribute in an initialised attributes object referenced by 3776I<attr>. 3777 3778The 3779I<process-shared> 3780attribute is set to PTHREAD_PROCESS_SHARED 3781to permit a condition variable 3782to be operated upon by any thread that has access to the memory 3783where the condition variable 3784is allocated, even if the condition variable 3785is allocated in memory that is shared by multiple processes. 3786If the 3787I<process-shared> 3788attribute is PTHREAD_PROCESS_PRIVATE, the condition variable 3789will only be operated upon by threads created 3790within the same process as the 3791thread that initialised the condition variable; 3792if threads of differing processes 3793attempt to operate on such a condition variable, the behaviour is 3794undefined. The default value of the attribute is 3795PTHREAD_PROCESS_PRIVATE. 3796 3797Additional attributes, their default values, and the names 3798of the associated functions to get and set those attribute values are 3799implementation-dependent. 3800 3801=head1 RETURN VALUE 3802 3803If successful, the 3804I<pthread_condattr_setpshared()> 3805function returns zero. 3806Otherwise, an error number is returned to indicate the error. 3807 3808If successful, the 3809I<pthread_condattr_getpshared()> 3810function returns zero 3811and stores the value of the 3812I<process-shared> 3813attribute of 3814I<attr> 3815into the object referenced by the 3816I<pshared> 3817parameter. 3818Otherwise, an error number is returned to indicate the error. 3819 3820=head1 ERRORS 3821 3822The 3823I<pthread_condattr_getpshared()> 3824and 3825I<pthread_condattr_setpshared()> 3826functions may fail if: 3827 3828=over 4 3829 3830=item [EINVAL] 3831 3832The value specified by 3833I<attr> 3834is invalid. 3835 3836=back 3837 3838The 3839I<pthread_condattr_setpshared()> 3840function may fail if: 3841 3842=over 4 3843 3844=item [EINVAL] 3845 3846The new value specified for the attribute 3847is outside the range of legal values for that attribute. 3848 3849=back 3850 3851These functions will not return an error code of [EINTR]. 3852 3853=head1 EXAMPLES 3854 3855None. 3856 3857=head1 APPLICATION USAGE 3858 3859None. 3860 3861=head1 FUTURE DIRECTIONS 3862 3863None. 3864 3865=head1 SEE ALSO 3866 3867I<pthread_condattr_init()>, 3868I<pthread_create()>, 3869I<pthread_mutex_init()>, 3870I<pthread_cond_init()>, 3871I<<pthread.h>>. 3872 3873=head1 ______________________________________________________________________ 3874 3875=head1 NAME 3876 3877B<pthread_create> - thread creation 3878 3879=head1 SYNOPSIS 3880 3881#include <pthread.h> 3882 3883int pthread_create(pthread_t *I<thread>, const pthread_attr_t *I<attr>, 3884void *(*I<start_routine>)(void*), void *I<arg>); 3885 3886=head1 DESCRIPTION 3887 3888The 3889I<pthread_create()> 3890function is used to create a new thread, with attributes specified by 3891I<attr>, 3892within a process. 3893If 3894I<attr> 3895is NULL, 3896the default attributes are used. 3897If the attributes specified by 3898I<attr> 3899are modified later, the thread's attributes are not affected. 3900Upon successful completion, 3901I<pthread_create()> 3902stores the ID of the created thread in the location referenced by 3903I<thread>. 3904 3905The thread is created executing 3906I<start_routine> 3907with 3908I<arg> 3909as its sole argument. 3910If the 3911I<start_routine> 3912returns, the effect is as if there was an implicit call to 3913I<pthread_exit()> 3914using the return value of 3915I<start_routine> 3916as the exit status. 3917Note that the thread in which 3918I<main()> 3919was originally invoked differs from this. 3920When it returns from 3921I<main()>, 3922the effect is as if there was an implicit call to 3923I<exit()> 3924using the return value of 3925I<main()> 3926as the exit status. 3927 3928The signal state of the new thread is initialised as follows: 3929 3930=over 4 3931 3932=item o 3933 3934The signal mask is inherited from the creating thread. 3935 3936=item o 3937 3938The set of signals pending for the new thread is empty. 3939 3940=back 3941 3942If 3943I<pthread_create()> 3944fails, no new thread is created 3945and the contents of the location referenced by 3946I<thread> 3947are undefined. 3948 3949=head1 RETURN VALUE 3950 3951If successful, the 3952I<pthread_create()> 3953function returns zero. 3954Otherwise, an error number is returned to indicate the error. 3955 3956=head1 ERRORS 3957 3958The 3959I<pthread_create()> 3960function will fail if: 3961 3962=over 4 3963 3964=item [EAGAIN] 3965 3966The system lacked the necessary resources to create another thread, 3967or the system-imposed limit on the total number of threads 3968in a process PTHREAD_THREADS_MAX would be exceeded. 3969 3970=item [EINVAL] 3971 3972The value specified by 3973I<attr> 3974is invalid. 3975 3976=item [EPERM] 3977 3978The caller does not have appropriate permission to set the required 3979scheduling parameters or scheduling policy. 3980 3981=back 3982 3983The 3984I<pthread_create()> 3985function will not return an error code of [EINTR]. 3986 3987=head1 EXAMPLES 3988 3989None. 3990 3991=head1 APPLICATION USAGE 3992 3993None. 3994 3995=head1 FUTURE DIRECTIONS 3996 3997None. 3998 3999=head1 SEE ALSO 4000 4001I<pthread_exit()>, 4002I<pthread_join()>, 4003I<fork()>, 4004I<<pthread.h>>. 4005 4006=head1 ______________________________________________________________________ 4007 4008=head1 NAME 4009 4010B<pthread_detach> - detach a thread 4011 4012=head1 SYNOPSIS 4013 4014#include <pthread.h> 4015 4016int pthread_detach(pthread_t I<thread>); 4017 4018=head1 DESCRIPTION 4019 4020The 4021I<pthread_detach()> 4022function is used to indicate to the implementation that storage 4023for the thread 4024I<thread> 4025can be reclaimed when that thread terminates. 4026If 4027I<thread> 4028has not terminated, 4029I<pthread_detach()> 4030will not cause it to terminate. 4031The effect of multiple 4032I<pthread_detach()> 4033calls on the same target thread is unspecified. 4034 4035=head1 RETURN VALUE 4036 4037If the call succeeds, 4038I<pthread_detach()> 4039returns 0. 4040Otherwise, an error number is returned to indicate the error. 4041 4042=head1 ERRORS 4043 4044The 4045I<pthread_detach()> 4046function will fail if: 4047 4048=over 4 4049 4050=item [EINVAL] 4051 4052The implementation has detected that the value specified by 4053I<thread> 4054does not refer to a joinable thread. 4055 4056=item [ESRCH] 4057 4058No thread could be found corresponding to that specified 4059by the given thread ID. 4060 4061=back 4062 4063The 4064I<pthread_detach()> 4065function will not return an error code of [EINTR]. 4066 4067=head1 EXAMPLES 4068 4069None. 4070 4071=head1 APPLICATION USAGE 4072 4073None. 4074 4075=head1 FUTURE DIRECTIONS 4076 4077None. 4078 4079=head1 SEE ALSO 4080 4081I<pthread_join()>, 4082I<<pthread.h>>. 4083 4084=head1 ______________________________________________________________________ 4085 4086=head1 NAME 4087 4088B<pthread_equal> - compare thread IDs 4089 4090=head1 SYNOPSIS 4091 4092#include <pthread.h> 4093 4094int pthread_equal(pthread_t I<t1>, pthread_t I<t2>); 4095 4096=head1 DESCRIPTION 4097 4098This function compares the thread IDs 4099I<t1> 4100and 4101I<t2>. 4102 4103=head1 RETURN VALUE 4104 4105The 4106I<pthread_equal()> 4107function returns a non-zero value if 4108I<t1> 4109and 4110I<t2> 4111are equal; 4112otherwise, zero is returned. 4113 4114If either 4115I<t1> 4116or 4117I<t2> 4118are not valid thread IDs, the behaviour is undefined. 4119 4120=head1 ERRORS 4121 4122No errors are defined. 4123 4124The 4125I<pthread_equal()> 4126function will not return an error code of [EINTR]. 4127 4128=head1 EXAMPLES 4129 4130None. 4131 4132=head1 APPLICATION USAGE 4133 4134None. 4135 4136=head1 FUTURE DIRECTIONS 4137 4138None. 4139 4140=head1 SEE ALSO 4141 4142I<pthread_create()>, 4143I<pthread_self()>, 4144I<<pthread.h>>. 4145 4146=head1 ______________________________________________________________________ 4147 4148=head1 NAME 4149 4150B<pthread_exit> - thread termination 4151 4152=head1 SYNOPSIS 4153 4154#include <pthread.h> 4155 4156void pthread_exit(void *I<value_ptr>); 4157 4158=head1 DESCRIPTION 4159 4160The 4161I<pthread_exit()> 4162function terminates the calling thread and makes the value 4163I<value_ptr> 4164available to any successful join with the terminating thread. 4165Any cancellation cleanup handlers 4166that have been pushed and not yet popped are popped in the reverse order 4167that they were pushed and then executed. 4168After all cancellation cleanup handlers have been executed, 4169if the thread has any thread-specific data, 4170appropriate destructor functions will be called in an unspecified order. 4171Thread termination does not release any application visible process resources, 4172including, but not limited to, mutexes and file descriptors, 4173nor does it perform any process level cleanup actions, 4174including, but not limited to, calling any 4175I<atexit()> 4176routines that may exist. 4177 4178An implicit call to 4179I<pthread_exit()> 4180is made when a thread other than the thread in which 4181I<main()> 4182was first invoked returns from the start routine 4183that was used to create it. 4184The function's return value serves as the thread's exit status. 4185 4186The behaviour of 4187I<pthread_exit()> 4188is undefined if called from a 4189cancellation cleanup handler 4190or destructor function 4191that was invoked as a result of either an implicit or 4192explicit call to 4193I<pthread_exit()>. 4194 4195After a thread has terminated, 4196the result of access to local (auto) variables of the thread is undefined. 4197Thus, references to local variables of the exiting thread 4198should not be used for the 4199I<pthread_exit()> 4200I<value_ptr> 4201parameter value. 4202 4203The process exits with an exit status of 0 after the 4204last thread has been terminated. 4205The behaviour is as if the implementation called 4206I<exit()> 4207with a zero argument at thread termination time. 4208 4209=head1 RETURN VALUE 4210 4211The 4212I<pthread_exit()> 4213function cannot return to its caller. 4214 4215=head1 ERRORS 4216 4217No errors are defined. 4218 4219The 4220I<pthread_exit()> 4221function will not return an error code of [EINTR]. 4222 4223=head1 EXAMPLES 4224 4225None. 4226 4227=head1 APPLICATION USAGE 4228 4229None. 4230 4231=head1 FUTURE DIRECTIONS 4232 4233None. 4234 4235=head1 SEE ALSO 4236 4237I<pthread_create()>, 4238I<pthread_join()>, 4239I<exit()>, 4240I<_exit()>, 4241I<<pthread.h>>. 4242 4243=head1 ______________________________________________________________________ 4244 4245=head1 NAME 4246 4247B<pthread_getconcurrency,> B<pthread_setconcurrency> - 4248get or set level of concurrency 4249 4250=head1 SYNOPSIS 4251 4252#include <pthread.h> 4253 4254int pthread_getconcurrency(void); 4255int pthread_setconcurrency(int I<new_level>); 4256 4257=head1 DESCRIPTION 4258 4259Unbound threads in a process may or may not be required to be 4260simultaneously active. By default, the threads 4261implementation ensures that a sufficient number of threads are active 4262so that the process can continue to make 4263progress. While this conserves system resources, it may not produce 4264the most effective level of concurrency. 4265 4266The 4267I<pthread_setconcurrency()> 4268function allows an application to inform 4269the threads implementation of its desired concurrency level, 4270I<new_level>. 4271The actual level of concurrency provided by the implementation as a 4272result of this function call is unspecified. 4273 4274If I<new_level> is zero, it causes the implementation to maintain 4275the concurrency level at its discretion as if 4276I<pthread_setconcurrency()> 4277was never called. 4278 4279The 4280I<pthread_getconcurrency()> 4281function returns the 4282value set by a previous call to the 4283I<pthread_setconcurrency()> 4284function. If the 4285I<pthread_setconcurrency()> 4286function was not previously called, 4287this function returns zero to indicate that the implementation 4288is maintaining the concurrency level. 4289 4290When an application calls 4291I<pthread_setconcurrency()> 4292it is 4293informing the implementation of its desired 4294concurrency level. The implementation uses this as a hint, 4295not a requirement. 4296 4297If an implementation does not support multiplexing of user threads 4298on top of several kernel scheduled entities, 4299the 4300I<pthread_setconcurrency()> 4301and 4302I<pthread_getconcurrency()> 4303functions 4304will be provided for source code 4305compatibility but they will have no effect when called. To maintain 4306the function semantics, the I<new_level> 4307parameter will be saved when 4308I<pthread_setconcurrency()> 4309is called so 4310that a subsequent call to 4311I<pthread_getconcurrency()> 4312returns the same value. 4313 4314=head1 RETURN VALUE 4315 4316If successful, the 4317I<pthread_setconcurrency()> 4318function returns zero. Otherwise, an error number is returned 4319to indicate the error. 4320 4321The 4322I<pthread_getconcurrency()> 4323function always returns the concurrency level set by a previous call to 4324I<pthread_setconcurrency()>. 4325If the 4326I<pthread_setconcurrency()> 4327function has never been called, 4328I<pthread_getconcurrency()> 4329returns zero. 4330 4331=head1 ERRORS 4332 4333The 4334I<pthread_setconcurrency()> 4335function will fail if: 4336 4337=over 4 4338 4339=item [EINVAL] 4340 4341The value specified by I<new_level> is negative. 4342 4343=item [EAGAIN] 4344 4345The value specific by I<new_level> would cause a system resource 4346to be exceeded. 4347 4348=back 4349 4350=head1 EXAMPLES 4351 4352None. 4353 4354=head1 APPLICATION USAGE 4355 4356Use of these functions changes the state of the underlying 4357concurrency upon which the application depends. Library 4358developers are advised to not use the 4359I<pthread_getconcurrency()> 4360and 4361I<pthread_setconcurrency()> 4362functions since their 4363use may conflict with an applications use of these functions. 4364 4365=head1 FUTURE DIRECTIONS 4366 4367None. 4368 4369=head1 SEE ALSO 4370 4371I<<pthread.h>>. 4372 4373=head1 ______________________________________________________________________ 4374 4375=head1 NAME 4376 4377B<pthread_getschedparam,> B<pthread_setschedparam> 4378- dynamic thread scheduling parameters access 4379(B<REALTIME THREADS>) 4380 4381=head1 SYNOPSIS 4382 4383#include <pthread.h> 4384 4385int pthread_getschedparam(pthread_t I<thread>, int *I<policy>, 4386struct sched_param *I<param>); 4387int pthread_setschedparam(pthread_t I<thread>, int I<policy>, 4388const struct sched_param *I<param>); 4389 4390=head1 DESCRIPTION 4391 4392The 4393I<pthread_getschedparam()> 4394and 4395I<pthread_setschedparam()> 4396allow the scheduling policy and scheduling parameters of individual threads 4397within a multi-threaded process to be retrieved and set. 4398For SCHED_FIFO and SCHED_RR, 4399the only required member of the 4400B<sched_param> 4401structure is the priority 4402I<sched_priority>. 4403For SCHED_OTHER, 4404the affected scheduling parameters are implementation-dependent. 4405 4406The 4407I<pthread_getschedparam()> 4408function retrieves the scheduling policy and scheduling parameters 4409for the thread whose thread ID is given by 4410I<thread> 4411and stores those values in 4412I<policy> 4413and 4414I<param>, 4415respectively. 4416The priority value returned from 4417I<pthread_getschedparam()> 4418is the value specified by the most recent 4419I<pthread_setschedparam()> 4420or 4421I<pthread_create()> 4422call affecting the target thread, 4423and reflects any temporary adjustments to its priority 4424as a result of any priority inheritance or ceiling functions. 4425The 4426I<pthread_setschedparam()> 4427function sets the scheduling policy 4428and associated scheduling parameters for the thread whose 4429thread ID is given by 4430I<thread> 4431to the policy and associated parameters provided in 4432I<policy> 4433and 4434I<param>, 4435respectively. 4436 4437The 4438I<policy> 4439parameter may have the value SCHED_OTHER, 4440that has implementation-dependent scheduling parameters, 4441SCHED_FIFO or SCHED_RR, 4442that have the single scheduling parameter, 4443I<priority.> 4444 4445If the 4446I<pthread_setschedparam()> 4447function fails, no scheduling parameters will be changed 4448for the target thread. 4449 4450=head1 RETURN VALUE 4451 4452If successful, the 4453I<pthread_getschedparam()> 4454and 4455I<pthread_setschedparam()> 4456functions return zero. 4457Otherwise, an error number is returned to indicate the error. 4458 4459=head1 ERRORS 4460 4461The 4462I<pthread_getschedparam()> 4463and 4464I<pthread_setschedparam()> 4465functions will fail if: 4466 4467=over 4 4468 4469=item [ENOSYS] 4470 4471The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 4472implementation does not support the function. 4473 4474=back 4475 4476The 4477I<pthread_getschedparam()> 4478function may fail if: 4479 4480=over 4 4481 4482=item [ESRCH] 4483 4484The value specified by 4485I<thread> 4486does not refer to a existing thread. 4487 4488=back 4489 4490The 4491I<pthread_setschedparam()> 4492function may fail if: 4493 4494=over 4 4495 4496=item [EINVAL] 4497 4498The value specified by 4499I<policy> 4500or one of the scheduling parameters associated with 4501the scheduling policy 4502I<policy> 4503is invalid. 4504 4505=item [ENOTSUP] 4506 4507An attempt was made to set the policy or scheduling parameters to 4508an unsupported value. 4509 4510=item [EPERM] 4511 4512The caller does not have the appropriate permission to set 4513either the scheduling parameters or the scheduling policy of the 4514specified thread. 4515 4516=item [EPERM] 4517 4518The implementation does not allow the application to modify 4519one of the parameters to the value specified. 4520 4521=item [ESRCH] 4522 4523The value specified by 4524I<thread> 4525does not refer to a existing thread. 4526 4527=back 4528 4529=head1 EXAMPLES 4530 4531None. 4532 4533=head1 APPLICATION USAGE 4534 4535None. 4536 4537=head1 FUTURE DIRECTIONS 4538 4539None. 4540 4541=head1 SEE ALSO 4542 4543I<sched_setparam()>, 4544I<sched_getparam()>, 4545I<sched_setscheduler()>, 4546I<sched_getscheduler()>, 4547I<<pthread.h>>, 4548I<<sched.h>>. 4549 4550=head1 ______________________________________________________________________ 4551 4552=head1 NAME 4553 4554B<pthread_setspecific,> B<pthread_getspecific> - thread-specific data management 4555 4556=head1 SYNOPSIS 4557 4558#include <pthread.h> 4559 4560int pthread_setspecific(pthread_key_t I<key>, const void *I<value>); 4561void *pthread_getspecific(pthread_key_t I<key>); 4562 4563=head1 DESCRIPTION 4564 4565The 4566I<pthread_setspecific()> 4567function associates a thread-specific 4568I<value> 4569with a 4570I<key> 4571obtained via a previous call to 4572I<pthread_key_create()>. 4573Different threads may bind different values to the same key. 4574These values are typically pointers to blocks of dynamically allocated memory 4575that have been reserved for use by the calling thread. 4576 4577The 4578I<pthread_getspecific()> 4579function returns the value currently bound to the specified 4580I<key> 4581on behalf of the calling thread. 4582 4583The effect of calling 4584I<pthread_setspecific()> 4585or 4586I<pthread_getspecific()> 4587with a 4588I<key> 4589value not obtained from 4590I<pthread_key_create()> 4591or after 4592I<key> 4593has been deleted with 4594I<pthread_key_delete()> 4595is undefined. 4596 4597Both 4598I<pthread_setspecific()> 4599and 4600I<pthread_getspecific()> 4601may be called from a thread-specific data destructor function. 4602However, calling 4603I<pthread_setspecific()> 4604from a destructor may result in lost storage or infinite loops. 4605 4606Both functions may be implemented as macros. 4607 4608=head1 RETURN VALUE 4609 4610The function 4611I<pthread_getspecific()> 4612returns the thread-specific data value 4613associated with the given 4614I<key>. 4615If no thread-specific data value is associated with 4616I<key>, 4617then the value NULL is returned. 4618 4619If successful, the 4620I<pthread_setspecific()> 4621function returns zero. 4622Otherwise, an error number is returned to indicate the error. 4623 4624=head1 ERRORS 4625 4626The 4627I<pthread_setspecific()> 4628function will fail if: 4629 4630=over 4 4631 4632=item [ENOMEM] 4633 4634Insufficient memory exists to associate the value with the key. 4635 4636=back 4637 4638The 4639I<pthread_setspecific()> 4640function may fail if: 4641 4642=over 4 4643 4644=item [EINVAL] 4645 4646The key value is invalid. 4647 4648=back 4649 4650No errors are returned from 4651I<pthread_getspecific()>. 4652 4653These functions will not return an error code of [EINTR]. 4654 4655=head1 EXAMPLES 4656 4657None. 4658 4659=head1 APPLICATION USAGE 4660 4661None. 4662 4663=head1 FUTURE DIRECTIONS 4664 4665None. 4666 4667=head1 SEE ALSO 4668 4669I<pthread_key_create()>, 4670I<<pthread.h>>. 4671 4672 4673=head1 ______________________________________________________________________ 4674 4675=head1 NAME 4676 4677B<pthread_join> - wait for thread termination 4678 4679=head1 SYNOPSIS 4680 4681#include <pthread.h> 4682 4683int pthread_join(pthread_t I<thread>, void **I<value_ptr>); 4684 4685=head1 DESCRIPTION 4686 4687The 4688I<pthread_join()> 4689function suspends execution of the calling thread until the target 4690I<thread> 4691terminates, unless the target 4692I<thread> 4693has already terminated. 4694On return from a successful 4695I<pthread_join()> 4696call with a non-NULL 4697I<value_ptr> 4698argument, the value passed to 4699I<pthread_exit()> 4700by the terminating thread is made available in the location referenced by 4701I<value_ptr>. 4702When a 4703I<pthread_join()> 4704returns successfully, the target thread has been terminated. 4705The results of multiple simultaneous calls to 4706I<pthread_join()> 4707specifying the same target thread are undefined. 4708If the thread calling 4709I<pthread_join()> 4710is canceled, then the target thread will not be detached. 4711 4712It is unspecified whether a thread that has exited but remains unjoined 4713counts against _POSIX_THREAD_THREADS_MAX. 4714 4715=head1 RETURN VALUE 4716 4717If successful, the 4718I<pthread_join()> 4719function returns zero. 4720Otherwise, an error number is returned to indicate the error. 4721 4722=head1 ERRORS 4723 4724The 4725I<pthread_join()> 4726function will fail if: 4727 4728=over 4 4729 4730=item [EINVAL] 4731 4732The implementation has detected that the value specified by 4733I<thread> 4734does not refer to a joinable thread. 4735 4736=item [ESRCH] 4737 4738No thread could be found corresponding to that specified 4739by the given thread ID. 4740 4741=back 4742 4743The 4744I<pthread_join()> 4745function may fail if: 4746 4747=over 4 4748 4749=item [EDEADLK] 4750 4751A deadlock was detected or 4752the value of 4753I<thread> 4754specifies the calling thread. 4755 4756=back 4757 4758The 4759I<pthread_join()> 4760function will not return an error code of [EINTR]. 4761 4762=head1 EXAMPLES 4763 4764None. 4765 4766=head1 APPLICATION USAGE 4767 4768None. 4769 4770=head1 FUTURE DIRECTIONS 4771 4772None. 4773 4774=head1 SEE ALSO 4775 4776I<pthread_create()>, 4777I<wait()>, 4778I<<pthread.h>>. 4779 4780=head1 ______________________________________________________________________ 4781 4782=head1 NAME 4783 4784B<pthread_key_create> - thread-specific data key creation 4785 4786=head1 SYNOPSIS 4787 4788#include <pthread.h> 4789 4790int pthread_key_create(pthread_key_t *I<key>, void (*I<destructor>)(void*)); 4791 4792=head1 DESCRIPTION 4793 4794This function creates a thread-specific data 4795key visible to all threads in the process. 4796Key values provided by 4797I<pthread_key_create()> 4798are opaque objects used to locate thread-specific data. 4799Although the same key value may be used by different threads, 4800the values bound to the key by 4801I<pthread_setspecific()> 4802are maintained on a per-thread basis and persist 4803for the life of the calling thread. 4804 4805Upon key creation, 4806the value NULL is associated with the new key in all active threads. 4807Upon thread creation, 4808the value NULL is associated with all defined keys in the new thread. 4809 4810An optional destructor function may be associated with 4811each key value. 4812At thread exit, if a key value has a non-NULL destructor pointer, 4813and the thread has a non-NULL value associated with that key, 4814the function pointed to is called with the current associated value 4815as its sole argument. 4816The order of destructor calls is unspecified 4817if more than one destructor exists for a thread when it exits. 4818 4819If, after all the destructors have been called for all non-NULL values 4820with associated destructors, 4821there are still some non-NULL values with associated destructors, 4822then the process will be repeated. 4823If, after at least PTHREAD_DESTRUCTOR_ITERATIONS 4824iterations of destructor calls for outstanding non-NULL values, 4825there are still some non-NULL values with associated destructors, 4826implementations may stop calling destructors, 4827or they may continue calling destructors 4828until no non-NULL values with associated destructors exist, 4829even though this might result in an infinite loop. 4830 4831=head1 RETURN VALUE 4832 4833If successful, the 4834I<pthread_key_create()> 4835function stores the newly created key value at 4836I<*key> 4837and returns zero. 4838Otherwise, an error number is returned to indicate the error. 4839 4840=head1 ERRORS 4841 4842The 4843I<pthread_key_create()> 4844function will fail if: 4845 4846=over 4 4847 4848=item [EAGAIN] 4849 4850The system lacked the necessary resources to create another thread-specific 4851data key, or the system-imposed limit on the total number of keys per process 4852PTHREAD_KEYS_MAX has been exceeded. 4853 4854=item [ENOMEM] 4855 4856Insufficient memory exists to create the key. 4857 4858=back 4859 4860The 4861I<pthread_key_create()> 4862function will not return an error code of [EINTR]. 4863 4864=head1 EXAMPLES 4865 4866None. 4867 4868=head1 APPLICATION USAGE 4869 4870None. 4871 4872=head1 FUTURE DIRECTIONS 4873 4874None. 4875 4876=head1 SEE ALSO 4877 4878I<pthread_getspecific()>, 4879I<pthread_setspecific()>, 4880I<pthread_key_delete()>, 4881I<<pthread.h>>. 4882 4883=head1 ______________________________________________________________________ 4884 4885=head1 NAME 4886 4887B<pthread_key_delete> - thread-specific data key deletion 4888 4889=head1 SYNOPSIS 4890 4891#include <pthread.h> 4892 4893int pthread_key_delete(pthread_key_t I<key>); 4894 4895=head1 DESCRIPTION 4896 4897This function deletes a thread-specific data 4898key previously returned by 4899I<pthread_key_create()>. 4900The thread-specific data values associated with 4901I<key> 4902need not be NULL at the time 4903I<pthread_key_delete()> 4904is called. 4905It is the responsibility of the application 4906to free any application storage 4907or perform any cleanup actions for data structures 4908related to the deleted key or associated thread-specific data 4909in any threads; 4910this cleanup can be done either before or after 4911I<pthread_key_delete()> 4912is called. 4913Any attempt to use 4914I<key> 4915following the call to 4916I<pthread_key_delete()> 4917results in undefined behaviour. 4918 4919The 4920I<pthread_key_delete()> 4921function is callable from within destructor functions. 4922No destructor functions will be invoked by 4923I<pthread_key_delete()>. 4924Any destructor function that may have been associated with 4925I<key> 4926will no longer be called upon thread exit. 4927 4928=head1 RETURN VALUE 4929 4930If successful, the 4931I<pthread_key_delete()> 4932function returns zero. 4933Otherwise, an error number is returned to indicate the error. 4934 4935=head1 ERRORS 4936 4937The 4938I<pthread_key_delete()> 4939function may fail if: 4940 4941=over 4 4942 4943=item [EINVAL] 4944 4945The 4946I<key> 4947value is invalid. 4948 4949=back 4950 4951The 4952I<pthread_key_delete()> 4953function will not return an error code of [EINTR]. 4954 4955=head1 EXAMPLES 4956 4957None. 4958 4959=head1 APPLICATION USAGE 4960 4961None. 4962 4963=head1 FUTURE DIRECTIONS 4964 4965None. 4966 4967=head1 SEE ALSO 4968 4969I<pthread_key_create()>, 4970I<<pthread.h>>. 4971 4972=head1 ______________________________________________________________________ 4973 4974=head1 NAME 4975 4976B<pthread_kill> - send a signal to a thread 4977 4978=head1 SYNOPSIS 4979 4980#include <signal.h> 4981 4982int pthread_kill(pthread_t I<thread>, int I<sig>); 4983 4984=head1 DESCRIPTION 4985 4986The 4987I<pthread_kill()> 4988function is used to request that a signal be delivered to the specified thread. 4989 4990As in 4991I<kill()>, 4992if 4993I<sig> 4994is zero, error checking is performed but no signal is actually sent. 4995 4996=head1 RETURN VALUE 4997 4998Upon successful completion, the function returns a value of zero. 4999Otherwise the function returns an error number. 5000If the 5001I<pthread_kill()> 5002function fails, no signal is sent. 5003 5004=head1 ERRORS 5005 5006The 5007I<pthread_kill()> 5008function will fail if: 5009 5010=over 4 5011 5012=item [ESRCH] 5013 5014No thread could be found corresponding to that specified 5015by the given thread ID. 5016 5017=item [EINVAL] 5018 5019The value of the 5020I<sig> 5021argument is an invalid or unsupported signal number. 5022 5023=back 5024 5025The 5026I<pthread_kill()> 5027function will not return an error code of [EINTR]. 5028 5029=head1 EXAMPLES 5030 5031None. 5032 5033=head1 APPLICATION USAGE 5034 5035None. 5036 5037=head1 FUTURE DIRECTIONS 5038 5039None. 5040 5041=head1 SEE ALSO 5042 5043I<kill()>, 5044I<pthread_self()>, 5045I<raise()>, 5046I<<signal.h>>. 5047 5048=head1 ______________________________________________________________________ 5049 5050=head1 NAME 5051 5052B<pthread_mutex_init,> B<pthread_mutex_destroy> - initialise or destroy a mutex 5053 5054=head1 SYNOPSIS 5055 5056#include <pthread.h> 5057 5058int pthread_mutex_init(pthread_mutex_t *I<mutex>, 5059const pthread_mutexattr_t *I<attr>); 5060int pthread_mutex_destroy(pthread_mutex_t *I<mutex>); 5061pthread_mutex_t I<mutex> = PTHREAD_MUTEX_INITIALIZER; 5062 5063=head1 DESCRIPTION 5064 5065The 5066I<pthread_mutex_init()> 5067function initialises the mutex referenced by 5068I<mutex> 5069with attributes specified 5070by 5071I<attr>. 5072If 5073I<attr> 5074is NULL, 5075the default mutex attributes are used; the effect is the same as 5076passing the address of a default mutex attributes object. 5077Upon successful initialisation, the state of the mutex becomes 5078initialised and unlocked. 5079 5080Attempting to initialise an already initialised 5081mutex results in 5082undefined behaviour. 5083 5084The 5085I<pthread_mutex_destroy()> 5086function destroys the mutex object referenced by 5087I<mutex>; 5088the mutex object becomes, in effect, uninitialised. 5089An implementation may cause 5090I<pthread_mutex_destroy()> 5091to set the object referenced by 5092I<mutex> 5093to an invalid value. 5094A destroyed mutex object 5095can be re-initialised using 5096I<pthread_mutex_init()>; 5097the results of otherwise referencing the object after it has been destroyed 5098are undefined. 5099 5100It is safe to destroy an initialised mutex that is unlocked. 5101Attempting to destroy a locked mutex results in 5102undefined behaviour. 5103 5104In cases where default mutex attributes are appropriate, 5105the macro PTHREAD_MUTEX_INITIALIZER 5106can be used to initialise mutexes that are statically allocated. 5107The effect is equivalent to dynamic initialisation by a call to 5108I<pthread_mutex_init()> 5109with parameter 5110I<attr> 5111specified as NULL, 5112except that no error checks are performed. 5113 5114=head1 RETURN VALUE 5115 5116If successful, the 5117I<pthread_mutex_init()> 5118and 5119I<pthread_mutex_destroy()> 5120functions return zero. 5121Otherwise, an error number is returned to indicate the error. 5122The [EBUSY] and [EINVAL] error checks, if implemented, 5123act as if they were performed immediately 5124at the beginning of processing for the function 5125and cause an error return 5126prior to modifying the state of the mutex specified by 5127I<mutex>. 5128 5129=head1 ERRORS 5130 5131The 5132I<pthread_mutex_init()> 5133function will fail if: 5134 5135=over 4 5136 5137=item [EAGAIN] 5138 5139The system lacked the necessary resources (other than memory) 5140to initialise another mutex. 5141 5142=item [ENOMEM] 5143 5144Insufficient memory exists to initialise the mutex. 5145 5146=item [EPERM] 5147 5148The caller does not have the privilege to perform the operation. 5149 5150=back 5151 5152The 5153I<pthread_mutex_init()> 5154function may fail if: 5155 5156=over 4 5157 5158=item [EBUSY] 5159 5160The implementation has detected an attempt 5161to re-initialise the object referenced by 5162I<mutex>, 5163a previously initialised, but 5164not yet destroyed, mutex. 5165 5166=item [EINVAL] 5167 5168The value specified by 5169I<attr> 5170is invalid. 5171 5172=back 5173 5174The 5175I<pthread_mutex_destroy()> 5176function may fail if: 5177 5178=over 4 5179 5180=item [EBUSY] 5181 5182The implementation has detected an attempt to destroy 5183the object referenced by 5184I<mutex> 5185while it is locked or referenced 5186(for example, while being used in a 5187I<pthread_cond_wait()> 5188or 5189I<pthread_cond_timedwait()>) 5190by another thread. 5191 5192=item [EINVAL] 5193 5194The value specified by 5195I<mutex> 5196is invalid. 5197 5198=back 5199 5200These functions will not return an error code of [EINTR]. 5201 5202=head1 EXAMPLES 5203 5204None. 5205 5206=head1 APPLICATION USAGE 5207 5208None. 5209 5210=head1 FUTURE DIRECTIONS 5211 5212None. 5213 5214=head1 SEE ALSO 5215 5216I<pthread_mutex_getprioceiling()>, 5217I<pthread_mutex_lock()>, 5218I<pthread_mutex_unlock()>, 5219I<pthread_mutex_setprioceiling()>, 5220I<pthread_mutex_trylock()>, 5221I<pthread_mutexattr_getpshared()>, 5222I<pthread_mutexattr_setpshared()>, 5223I<<pthread.h>>. 5224 5225=head1 ______________________________________________________________________ 5226 5227=head1 NAME 5228 5229B<pthread_mutex_setprioceiling,> B<pthread_mutex_getprioceiling> 5230- change the priority ceiling of a mutex 5231(B<REALTIME THREADS>) 5232 5233=head1 SYNOPSIS 5234 5235#include <pthread.h> 5236 5237int pthread_mutex_setprioceiling(pthread_mutex_t *I<mutex>, int I<prioceiling>, int *I<old_ceiling>); 5238 5239int pthread_mutex_getprioceiling(const pthread_mutex_t *I<mutex>, int *I<prioceiling>); 5240 5241=head1 DESCRIPTION 5242 5243The 5244I<pthread_mutex_getprioceiling()> 5245function returns the current priority ceiling of the mutex. 5246 5247The 5248I<pthread_mutex_setprioceiling()> 5249function either locks the mutex if it is unlocked, or blocks until it can 5250successfully lock the mutex, then it 5251changes the mutex's priority ceiling and releases the mutex. 5252When the change is successful, the previous value of the 5253priority ceiling is returned in 5254I<old_ceiling>. 5255The process of locking the mutex need not adhere 5256to the priority protect protocol. 5257 5258If the 5259I<pthread_mutex_setprioceiling()> 5260function fails, the mutex priority ceiling is not changed. 5261 5262=head1 RETURN VALUE 5263 5264If successful, the 5265I<pthread_mutex_setprioceiling()> 5266and 5267I<pthread_mutex_getprioceiling()> 5268functions return zero. 5269Otherwise, an error number is returned to indicate the error. 5270 5271=head1 ERRORS 5272 5273The 5274I<pthread_mutex_getprioceiling()> 5275and 5276I<pthread_mutex_setprioceiling()> 5277functions will fail if: 5278 5279=over 4 5280 5281=item [ENOSYS] 5282 5283The option _POSIX_THREAD_PRIO_PROTECT is not defined and 5284the implementation does not support the function. 5285 5286=back 5287 5288The 5289I<pthread_mutex_setprioceiling()> 5290and 5291I<pthread_mutex_getprioceiling()> 5292functions may fail if: 5293 5294=over 4 5295 5296=item [EINVAL] 5297 5298The priority requested by 5299I<prioceiling> 5300is out of range. 5301 5302=item [EINVAL] 5303 5304The value specified by 5305I<mutex> 5306does not refer to a currently existing mutex. 5307 5308=item [ENOSYS] 5309 5310The implementation does not support the priority ceiling protocol for mutexes. 5311 5312=item [EPERM] 5313 5314The caller does not have the privilege to perform the operation. 5315 5316=back 5317 5318=head1 EXAMPLES 5319 5320None. 5321 5322=head1 APPLICATION USAGE 5323 5324None. 5325 5326=head1 FUTURE DIRECTIONS 5327 5328None. 5329 5330=head1 SEE ALSO 5331 5332I<pthread_mutex_init()>, 5333I<pthread_mutex_lock()>, 5334I<pthread_mutex_unlock()>, 5335I<pthread_mutex_trylock()>, 5336I<<pthread.h>>. 5337 5338 5339=head1 ______________________________________________________________________ 5340 5341=head1 NAME 5342 5343B<pthread_mutex_init,> B<pthread_mutex_destroy> - initialise or destroy a mutex 5344 5345=head1 SYNOPSIS 5346 5347#include <pthread.h> 5348 5349int pthread_mutex_init(pthread_mutex_t *I<mutex>, 5350const pthread_mutexattr_t *I<attr>); 5351int pthread_mutex_destroy(pthread_mutex_t *I<mutex>); 5352pthread_mutex_t I<mutex> = PTHREAD_MUTEX_INITIALIZER; 5353 5354=head1 DESCRIPTION 5355 5356The 5357I<pthread_mutex_init()> 5358function initialises the mutex referenced by 5359I<mutex> 5360with attributes specified 5361by 5362I<attr>. 5363If 5364I<attr> 5365is NULL, 5366the default mutex attributes are used; the effect is the same as 5367passing the address of a default mutex attributes object. 5368Upon successful initialisation, the state of the mutex becomes 5369initialised and unlocked. 5370 5371Attempting to initialise an already initialised 5372mutex results in 5373undefined behaviour. 5374 5375The 5376I<pthread_mutex_destroy()> 5377function destroys the mutex object referenced by 5378I<mutex>; 5379the mutex object becomes, in effect, uninitialised. 5380An implementation may cause 5381I<pthread_mutex_destroy()> 5382to set the object referenced by 5383I<mutex> 5384to an invalid value. 5385A destroyed mutex object 5386can be re-initialised using 5387I<pthread_mutex_init()>; 5388the results of otherwise referencing the object after it has been destroyed 5389are undefined. 5390 5391It is safe to destroy an initialised mutex that is unlocked. 5392Attempting to destroy a locked mutex results in 5393undefined behaviour. 5394 5395In cases where default mutex attributes are appropriate, 5396the macro PTHREAD_MUTEX_INITIALIZER 5397can be used to initialise mutexes that are statically allocated. 5398The effect is equivalent to dynamic initialisation by a call to 5399I<pthread_mutex_init()> 5400with parameter 5401I<attr> 5402specified as NULL, 5403except that no error checks are performed. 5404 5405=head1 RETURN VALUE 5406 5407If successful, the 5408I<pthread_mutex_init()> 5409and 5410I<pthread_mutex_destroy()> 5411functions return zero. 5412Otherwise, an error number is returned to indicate the error. 5413The [EBUSY] and [EINVAL] error checks, if implemented, 5414act as if they were performed immediately 5415at the beginning of processing for the function 5416and cause an error return 5417prior to modifying the state of the mutex specified by 5418I<mutex>. 5419 5420=head1 ERRORS 5421 5422The 5423I<pthread_mutex_init()> 5424function will fail if: 5425 5426=over 4 5427 5428=item [EAGAIN] 5429 5430The system lacked the necessary resources (other than memory) 5431to initialise another mutex. 5432 5433=item [ENOMEM] 5434 5435Insufficient memory exists to initialise the mutex. 5436 5437=item [EPERM] 5438 5439The caller does not have the privilege to perform the operation. 5440 5441=back 5442 5443The 5444I<pthread_mutex_init()> 5445function may fail if: 5446 5447=over 4 5448 5449=item [EBUSY] 5450 5451The implementation has detected an attempt 5452to re-initialise the object referenced by 5453I<mutex>, 5454a previously initialised, but 5455not yet destroyed, mutex. 5456 5457=item [EINVAL] 5458 5459The value specified by 5460I<attr> 5461is invalid. 5462 5463=back 5464 5465The 5466I<pthread_mutex_destroy()> 5467function may fail if: 5468 5469=over 4 5470 5471=item [EBUSY] 5472 5473The implementation has detected an attempt to destroy 5474the object referenced by 5475I<mutex> 5476while it is locked or referenced 5477(for example, while being used in a 5478I<pthread_cond_wait()> 5479or 5480I<pthread_cond_timedwait()>) 5481by another thread. 5482 5483=item [EINVAL] 5484 5485The value specified by 5486I<mutex> 5487is invalid. 5488 5489=back 5490 5491These functions will not return an error code of [EINTR]. 5492 5493=head1 EXAMPLES 5494 5495None. 5496 5497=head1 APPLICATION USAGE 5498 5499None. 5500 5501=head1 FUTURE DIRECTIONS 5502 5503None. 5504 5505=head1 SEE ALSO 5506 5507I<pthread_mutex_getprioceiling()>, 5508I<pthread_mutex_lock()>, 5509I<pthread_mutex_unlock()>, 5510I<pthread_mutex_setprioceiling()>, 5511I<pthread_mutex_trylock()>, 5512I<pthread_mutexattr_getpshared()>, 5513I<pthread_mutexattr_setpshared()>, 5514I<<pthread.h>>. 5515 5516=head1 ______________________________________________________________________ 5517 5518=head1 NAME 5519 5520B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock> 5521- lock and unlock a mutex 5522 5523=head1 SYNOPSIS 5524 5525#include <pthread.h> 5526 5527int pthread_mutex_lock(pthread_mutex_t *I<mutex>); 5528int pthread_mutex_trylock(pthread_mutex_t *I<mutex>); 5529int pthread_mutex_unlock(pthread_mutex_t *I<mutex>); 5530 5531=head1 DESCRIPTION 5532 5533The mutex object referenced by 5534I<mutex> 5535is locked by calling 5536I<pthread_mutex_lock()>. 5537If the mutex is already locked, 5538the calling thread blocks until the mutex becomes available. 5539This operation returns with the mutex object referenced by 5540I<mutex> 5541in the locked state with the calling thread as its owner. 5542 5543If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not 5544provided. Attempting to 5545relock the mutex causes deadlock. If a thread attempts to unlock a 5546mutex that it has not locked or a mutex 5547which is unlocked, undefined behaviour results. 5548 5549If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then 5550error checking is provided. 5551If a thread attempts to relock a mutex that it has already 5552locked, an error will be returned. If a thread 5553attempts to unlock a mutex that it has not locked or a mutex which 5554is unlocked, an error will be returned. 5555 5556If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains 5557the concept of a lock count. 5558When a thread successfully acquires a mutex for the 5559first time, the lock count is set 5560to one. Every time a thread relocks this mutex, the lock count is 5561incremented by one. Each time the 5562thread unlocks the mutex, the lock count is decremented by one. 5563When the lock count reaches zero, the 5564mutex becomes available for other threads to acquire. If a thread 5565attempts to unlock a mutex that it has 5566not locked or a mutex which is unlocked, an error will be returned. 5567 5568If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively 5569lock the mutex results in 5570undefined behaviour. Attempting to unlock the mutex if it was not 5571locked by the calling thread results in 5572undefined behaviour. Attempting to unlock the mutex if it is not 5573locked results in undefined behaviour. 5574 5575The function 5576I<pthread_mutex_trylock()> 5577is identical to 5578I<pthread_mutex_lock()> 5579except that if the mutex object referenced by 5580I<mutex> 5581is currently locked (by any thread, including the 5582current thread), the call returns immediately. 5583 5584The 5585I<pthread_mutex_unlock()> 5586function releases the mutex object referenced by 5587I<mutex>. 5588The manner in which a mutex is released is dependent upon the mutex's 5589type attribute. 5590If there are threads blocked on the mutex object referenced by 5591I<mutex> when 5592I<pthread_mutex_unlock()> 5593is called, resulting in the mutex 5594becoming available, the scheduling policy is used to determine 5595which thread shall acquire the mutex. 5596(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes 5597available when the count reaches zero and the calling thread no 5598longer has any locks on this mutex). 5599 5600If a signal is delivered to a thread waiting for a mutex, 5601upon return from the signal handler the thread resumes waiting 5602for the mutex as if it was not interrupted. 5603 5604=head1 RETURN VALUE 5605 5606If successful, the 5607I<pthread_mutex_lock()> 5608and 5609I<pthread_mutex_unlock()> 5610functions return zero. 5611Otherwise, an error number is returned to indicate the error. 5612 5613The function 5614I<pthread_mutex_trylock()> 5615returns zero if a lock on the mutex object referenced by 5616I<mutex> 5617is acquired. 5618Otherwise, an error number is returned to indicate the error. 5619 5620=head1 ERRORS 5621 5622The 5623I<pthread_mutex_lock()> 5624and 5625I<pthread_mutex_trylock()> 5626functions will fail if: 5627 5628=over 4 5629 5630=item [EINVAL] 5631 5632The 5633I<mutex> 5634was created with the protocol attribute having the value 5635PTHREAD_PRIO_PROTECT 5636and the calling thread's priority is higher 5637than the mutex's current priority ceiling. 5638 5639=back 5640 5641The 5642I<pthread_mutex_trylock()> 5643function will fail if: 5644 5645=over 4 5646 5647=item [EBUSY] 5648 5649The 5650I<mutex> 5651could not be acquired because it was already locked. 5652 5653=back 5654 5655The 5656I<pthread_mutex_lock()>, 5657I<pthread_mutex_trylock()> 5658and 5659I<pthread_mutex_unlock()> 5660functions may fail if: 5661 5662=over 4 5663 5664=item [EINVAL] 5665 5666The value specified by 5667I<mutex> 5668does not refer to an initialised mutex object. 5669 5670=item [EAGAIN] 5671 5672The mutex could not be acquired because the maximum 5673number of recursive locks for I<mutex> has been exceeded. 5674 5675=back 5676 5677The 5678I<pthread_mutex_lock()> 5679function may fail if: 5680 5681=over 4 5682 5683=item [EDEADLK] 5684 5685The current thread already owns the mutex. 5686 5687=back 5688 5689The 5690I<pthread_mutex_unlock()> 5691function may fail if: 5692 5693=over 4 5694 5695=item [EPERM] 5696 5697The current thread does not own the mutex. 5698 5699=back 5700 5701These functions will not return an error code of [EINTR]. 5702 5703=head1 EXAMPLES 5704 5705None. 5706 5707=head1 APPLICATION USAGE 5708 5709None. 5710 5711=head1 FUTURE DIRECTIONS 5712 5713None. 5714 5715=head1 SEE ALSO 5716 5717I<pthread_mutex_init()>, 5718I<pthread_mutex_destroy()>, 5719I<<pthread.h>>. 5720 5721=head1 ______________________________________________________________________ 5722 5723=head1 NAME 5724 5725B<pthread_mutex_setprioceiling,> B<pthread_mutex_getprioceiling> 5726- change the priority ceiling of a mutex 5727(B<REALTIME THREADS>) 5728 5729=head1 SYNOPSIS 5730 5731#include <pthread.h> 5732 5733int pthread_mutex_setprioceiling(pthread_mutex_t *I<mutex>, int 5734I<prioceiling>, int *I<old_ceiling>); 5735 5736int pthread_mutex_getprioceiling(const pthread_mutex_t *I<mutex>, 5737int *I<prioceiling>); 5738 5739=head1 DESCRIPTION 5740 5741The 5742I<pthread_mutex_getprioceiling()> 5743function returns the current priority ceiling of the mutex. 5744 5745The 5746I<pthread_mutex_setprioceiling()> 5747function either locks the mutex if it is unlocked, or blocks until it can 5748successfully lock the mutex, then it 5749changes the mutex's priority ceiling and releases the mutex. 5750When the change is successful, the previous value of the 5751priority ceiling is returned in 5752I<old_ceiling>. 5753The process of locking the mutex need not adhere 5754to the priority protect protocol. 5755 5756If the 5757I<pthread_mutex_setprioceiling()> 5758function fails, the mutex priority ceiling is not changed. 5759 5760=head1 RETURN VALUE 5761 5762If successful, the 5763I<pthread_mutex_setprioceiling()> 5764and 5765I<pthread_mutex_getprioceiling()> 5766functions return zero. 5767Otherwise, an error number is returned to indicate the error. 5768 5769=head1 ERRORS 5770 5771The 5772I<pthread_mutex_getprioceiling()> 5773and 5774I<pthread_mutex_setprioceiling()> 5775functions will fail if: 5776 5777=over 4 5778 5779=item [ENOSYS] 5780 5781The option _POSIX_THREAD_PRIO_PROTECT is not defined and 5782the implementation does not support the function. 5783 5784=back 5785 5786The 5787I<pthread_mutex_setprioceiling()> 5788and 5789I<pthread_mutex_getprioceiling()> 5790functions may fail if: 5791 5792=over 4 5793 5794=item [EINVAL] 5795 5796The priority requested by 5797I<prioceiling> 5798is out of range. 5799 5800=item [EINVAL] 5801 5802The value specified by 5803I<mutex> 5804does not refer to a currently existing mutex. 5805 5806=item [ENOSYS] 5807 5808The implementation does not support the priority ceiling protocol for mutexes. 5809 5810=item [EPERM] 5811 5812The caller does not have the privilege to perform the operation. 5813 5814=back 5815 5816=head1 EXAMPLES 5817 5818None. 5819 5820=head1 APPLICATION USAGE 5821 5822None. 5823 5824=head1 FUTURE DIRECTIONS 5825 5826None. 5827 5828=head1 SEE ALSO 5829 5830I<pthread_mutex_init()>, 5831I<pthread_mutex_lock()>, 5832I<pthread_mutex_unlock()>, 5833I<pthread_mutex_trylock()>, 5834I<<pthread.h>>. 5835 5836 5837=head1 ______________________________________________________________________ 5838 5839=head1 NAME 5840 5841B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock> 5842- lock and unlock a mutex 5843 5844=head1 SYNOPSIS 5845 5846#include <pthread.h> 5847 5848int pthread_mutex_lock(pthread_mutex_t *I<mutex>); 5849int pthread_mutex_trylock(pthread_mutex_t *I<mutex>); 5850int pthread_mutex_unlock(pthread_mutex_t *I<mutex>); 5851 5852=head1 DESCRIPTION 5853 5854The mutex object referenced by 5855I<mutex> 5856is locked by calling 5857I<pthread_mutex_lock()>. 5858If the mutex is already locked, 5859the calling thread blocks until the mutex becomes available. 5860This operation returns with the mutex object referenced by 5861I<mutex> 5862in the locked state with the calling thread as its owner. 5863 5864If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not 5865provided. Attempting to 5866relock the mutex causes deadlock. If a thread attempts to unlock a 5867mutex that it has not locked or a mutex 5868which is unlocked, undefined behaviour results. 5869 5870If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then 5871error checking is provided. 5872If a thread attempts to relock a mutex that it has already 5873locked, an error will be returned. If a thread 5874attempts to unlock a mutex that it has not locked or a mutex which 5875is unlocked, an error will be returned. 5876 5877If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains 5878the concept of a lock count. 5879When a thread successfully acquires a mutex for the 5880first time, the lock count is set 5881to one. Every time a thread relocks this mutex, the lock count is 5882incremented by one. Each time the 5883thread unlocks the mutex, the lock count is decremented by one. 5884When the lock count reaches zero, the 5885mutex becomes available for other threads to acquire. If a thread 5886attempts to unlock a mutex that it has 5887not locked or a mutex which is unlocked, an error will be returned. 5888 5889If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively 5890lock the mutex results in 5891undefined behaviour. Attempting to unlock the mutex if it was not 5892locked by the calling thread results in 5893undefined behaviour. Attempting to unlock the mutex if it is not 5894locked results in undefined behaviour. 5895 5896The function 5897I<pthread_mutex_trylock()> 5898is identical to 5899I<pthread_mutex_lock()> 5900except that if the mutex object referenced by 5901I<mutex> 5902is currently locked (by any thread, including the 5903current thread), the call returns immediately. 5904 5905The 5906I<pthread_mutex_unlock()> 5907function releases the mutex object referenced by 5908I<mutex>. 5909The manner in which a mutex is released is dependent upon the mutex's 5910type attribute. 5911If there are threads blocked on the mutex object referenced by 5912I<mutex> when 5913I<pthread_mutex_unlock()> 5914is called, resulting in the mutex 5915becoming available, the scheduling policy is used to determine 5916which thread shall acquire the mutex. 5917(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes 5918available when the count reaches zero and the calling thread no 5919longer has any locks on this mutex). 5920 5921If a signal is delivered to a thread waiting for a mutex, 5922upon return from the signal handler the thread resumes waiting 5923for the mutex as if it was not interrupted. 5924 5925=head1 RETURN VALUE 5926 5927If successful, the 5928I<pthread_mutex_lock()> 5929and 5930I<pthread_mutex_unlock()> 5931functions return zero. 5932Otherwise, an error number is returned to indicate the error. 5933 5934The function 5935I<pthread_mutex_trylock()> 5936returns zero if a lock on the mutex object referenced by 5937I<mutex> 5938is acquired. 5939Otherwise, an error number is returned to indicate the error. 5940 5941=head1 ERRORS 5942 5943The 5944I<pthread_mutex_lock()> 5945and 5946I<pthread_mutex_trylock()> 5947functions will fail if: 5948 5949=over 4 5950 5951=item [EINVAL] 5952 5953The 5954I<mutex> 5955was created with the protocol attribute having the value 5956PTHREAD_PRIO_PROTECT 5957and the calling thread's priority is higher 5958than the mutex's current priority ceiling. 5959 5960=back 5961 5962The 5963I<pthread_mutex_trylock()> 5964function will fail if: 5965 5966=over 4 5967 5968=item [EBUSY] 5969 5970The 5971I<mutex> 5972could not be acquired because it was already locked. 5973 5974=back 5975 5976The 5977I<pthread_mutex_lock()>, 5978I<pthread_mutex_trylock()> 5979and 5980I<pthread_mutex_unlock()> 5981functions may fail if: 5982 5983=over 4 5984 5985=item [EINVAL] 5986 5987The value specified by 5988I<mutex> 5989does not refer to an initialised mutex object. 5990 5991=item [EAGAIN] 5992 5993The mutex could not be acquired because the maximum 5994number of recursive locks for I<mutex> has been exceeded. 5995 5996=back 5997 5998The 5999I<pthread_mutex_lock()> 6000function may fail if: 6001 6002=over 4 6003 6004=item [EDEADLK] 6005 6006The current thread already owns the mutex. 6007 6008=back 6009 6010The 6011I<pthread_mutex_unlock()> 6012function may fail if: 6013 6014=over 4 6015 6016=item [EPERM] 6017 6018The current thread does not own the mutex. 6019 6020=back 6021 6022These functions will not return an error code of [EINTR]. 6023 6024=head1 EXAMPLES 6025 6026None. 6027 6028=head1 APPLICATION USAGE 6029 6030None. 6031 6032=head1 FUTURE DIRECTIONS 6033 6034None. 6035 6036=head1 SEE ALSO 6037 6038I<pthread_mutex_init()>, 6039I<pthread_mutex_destroy()>, 6040I<<pthread.h>>. 6041 6042=head1 ______________________________________________________________________ 6043 6044=head1 NAME 6045 6046B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock> 6047- lock and unlock a mutex 6048 6049=head1 SYNOPSIS 6050 6051#include <pthread.h> 6052 6053int pthread_mutex_lock(pthread_mutex_t *I<mutex>); 6054int pthread_mutex_trylock(pthread_mutex_t *I<mutex>); 6055int pthread_mutex_unlock(pthread_mutex_t *I<mutex>); 6056 6057=head1 DESCRIPTION 6058 6059The mutex object referenced by 6060I<mutex> 6061is locked by calling 6062I<pthread_mutex_lock()>. 6063If the mutex is already locked, 6064the calling thread blocks until the mutex becomes available. 6065This operation returns with the mutex object referenced by 6066I<mutex> 6067in the locked state with the calling thread as its owner. 6068 6069If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not 6070provided. Attempting to 6071relock the mutex causes deadlock. If a thread attempts to unlock a 6072mutex that it has not locked or a mutex 6073which is unlocked, undefined behaviour results. 6074 6075If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then 6076error checking is provided. 6077If a thread attempts to relock a mutex that it has already 6078locked, an error will be returned. If a thread 6079attempts to unlock a mutex that it has not locked or a mutex which 6080is unlocked, an error will be returned. 6081 6082If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains 6083the concept of a lock count. 6084When a thread successfully acquires a mutex for the 6085first time, the lock count is set 6086to one. Every time a thread relocks this mutex, the lock count is 6087incremented by one. Each time the 6088thread unlocks the mutex, the lock count is decremented by one. 6089When the lock count reaches zero, the 6090mutex becomes available for other threads to acquire. If a thread 6091attempts to unlock a mutex that it has 6092not locked or a mutex which is unlocked, an error will be returned. 6093 6094If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively 6095lock the mutex results in 6096undefined behaviour. Attempting to unlock the mutex if it was not 6097locked by the calling thread results in 6098undefined behaviour. Attempting to unlock the mutex if it is not 6099locked results in undefined behaviour. 6100 6101The function 6102I<pthread_mutex_trylock()> 6103is identical to 6104I<pthread_mutex_lock()> 6105except that if the mutex object referenced by 6106I<mutex> 6107is currently locked (by any thread, including the 6108current thread), the call returns immediately. 6109 6110The 6111I<pthread_mutex_unlock()> 6112function releases the mutex object referenced by 6113I<mutex>. 6114The manner in which a mutex is released is dependent upon the mutex's 6115type attribute. 6116If there are threads blocked on the mutex object referenced by 6117I<mutex> when 6118I<pthread_mutex_unlock()> 6119is called, resulting in the mutex 6120becoming available, the scheduling policy is used to determine 6121which thread shall acquire the mutex. 6122(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes 6123available when the count reaches zero and the calling thread no 6124longer has any locks on this mutex). 6125 6126If a signal is delivered to a thread waiting for a mutex, 6127upon return from the signal handler the thread resumes waiting 6128for the mutex as if it was not interrupted. 6129 6130=head1 RETURN VALUE 6131 6132If successful, the 6133I<pthread_mutex_lock()> 6134and 6135I<pthread_mutex_unlock()> 6136functions return zero. 6137Otherwise, an error number is returned to indicate the error. 6138 6139The function 6140I<pthread_mutex_trylock()> 6141returns zero if a lock on the mutex object referenced by 6142I<mutex> 6143is acquired. 6144Otherwise, an error number is returned to indicate the error. 6145 6146=head1 ERRORS 6147 6148The 6149I<pthread_mutex_lock()> 6150and 6151I<pthread_mutex_trylock()> 6152functions will fail if: 6153 6154=over 4 6155 6156=item [EINVAL] 6157 6158The 6159I<mutex> 6160was created with the protocol attribute having the value 6161PTHREAD_PRIO_PROTECT 6162and the calling thread's priority is higher 6163than the mutex's current priority ceiling. 6164 6165=back 6166 6167The 6168I<pthread_mutex_trylock()> 6169function will fail if: 6170 6171=over 4 6172 6173=item [EBUSY] 6174 6175The 6176I<mutex> 6177could not be acquired because it was already locked. 6178 6179=back 6180 6181The 6182I<pthread_mutex_lock()>, 6183I<pthread_mutex_trylock()> 6184and 6185I<pthread_mutex_unlock()> 6186functions may fail if: 6187 6188=over 4 6189 6190=item [EINVAL] 6191 6192The value specified by 6193I<mutex> 6194does not refer to an initialised mutex object. 6195 6196=item [EAGAIN] 6197 6198The mutex could not be acquired because the maximum 6199number of recursive locks for I<mutex> has been exceeded. 6200 6201=back 6202 6203The 6204I<pthread_mutex_lock()> 6205function may fail if: 6206 6207=over 4 6208 6209=item [EDEADLK] 6210 6211The current thread already owns the mutex. 6212 6213=back 6214 6215The 6216I<pthread_mutex_unlock()> 6217function may fail if: 6218 6219=over 4 6220 6221=item [EPERM] 6222 6223The current thread does not own the mutex. 6224 6225=back 6226 6227These functions will not return an error code of [EINTR]. 6228 6229=head1 EXAMPLES 6230 6231None. 6232 6233=head1 APPLICATION USAGE 6234 6235None. 6236 6237=head1 FUTURE DIRECTIONS 6238 6239None. 6240 6241=head1 SEE ALSO 6242 6243I<pthread_mutex_init()>, 6244I<pthread_mutex_destroy()>, 6245I<<pthread.h>>. 6246 6247=head1 ______________________________________________________________________ 6248 6249=head1 NAME 6250 6251B<pthread_mutexattr_init,> B<pthread_mutexattr_destroy> 6252- initialise and destroy mutex attributes object 6253 6254=head1 SYNOPSIS 6255 6256#include <pthread.h> 6257 6258int pthread_mutexattr_init(pthread_mutexattr_t *I<attr>); 6259int pthread_mutexattr_destroy(pthread_mutexattr_t *I<attr>); 6260 6261=head1 DESCRIPTION 6262 6263The function 6264I<pthread_mutexattr_init()> 6265initialises a mutex attributes object 6266I<attr> 6267with the default value for all of the attributes 6268defined by the implementation. 6269 6270The effect of initialising an already initialised mutex 6271attributes object is undefined. 6272 6273After a mutex attributes object has been used 6274to initialise one or more mutexes, 6275any function affecting the attributes object (including destruction) 6276does not affect any previously initialised mutexes. 6277 6278The 6279I<pthread_mutexattr_destroy()> 6280function destroys a mutex attributes object; 6281the object becomes, in effect, uninitialised. 6282An implementation may cause 6283I<pthread_mutexattr_destroy()> 6284to set the object referenced by 6285I<attr> 6286to an invalid value. 6287A destroyed mutex attributes object 6288can be re-initialised using 6289I<pthread_mutexattr_init()>; 6290the results of otherwise referencing the object after it has been 6291destroyed are undefined. 6292 6293=head1 RETURN VALUE 6294 6295Upon successful completion, 6296I<pthread_mutexattr_init()> 6297and 6298I<pthread_mutexattr_destroy()> 6299return zero. 6300Otherwise, an error number is returned to indicate the error. 6301 6302=head1 ERRORS 6303 6304The 6305I<pthread_mutexattr_init()> 6306function may fail if: 6307 6308=over 4 6309 6310=item [ENOMEM] 6311 6312Insufficient memory exists to initialise the mutex attributes object. 6313 6314=back 6315 6316The 6317I<pthread_mutexattr_destroy()> 6318function may fail if: 6319 6320=over 4 6321 6322=item [EINVAL] 6323 6324The value specified by 6325I<attr> 6326is invalid. 6327 6328=back 6329 6330These functions will not return an error code of [EINTR]. 6331 6332=head1 EXAMPLES 6333 6334None. 6335 6336=head1 APPLICATION USAGE 6337 6338None. 6339 6340=head1 FUTURE DIRECTIONS 6341 6342None. 6343 6344=head1 SEE ALSO 6345 6346I<pthread_create()>, 6347I<pthread_mutex_init()>, 6348I<pthread_mutexattr_init()>, 6349I<pthread_cond_init()>, 6350I<<pthread.h>>. 6351 6352=head1 ______________________________________________________________________ 6353 6354=head1 NAME 6355 6356B<pthread_mutexattr_setprioceiling,> B<pthread_mutexattr_getprioceiling> 6357- set and get prioceiling attribute of mutex attribute object 6358(B<REALTIME THREADS>) 6359 6360=head1 SYNOPSIS 6361 6362#include <pthread.h> 6363 6364int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I<attr>, 6365int I<prioceiling>); 6366int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I<attr>, 6367int *I<prioceiling>); 6368 6369=head1 DESCRIPTION 6370 6371The 6372I<pthread_mutexattr_setprioceiling()> 6373and 6374I<pthread_mutexattr_getprioceiling()> 6375functions, respectively, set and get the priority ceiling attribute of 6376a mutex attribute object pointed to by 6377I<attr> 6378which was previously created by the function 6379I<pthread_mutexattr_init()>. 6380 6381The 6382I<prioceiling> 6383attribute contains the priority ceiling of initialised mutexes. 6384The values of 6385I<prioceiling> 6386will be within the maximum range of priorities defined by SCHED_FIFO. 6387 6388The 6389I<prioceiling> 6390attribute defines the priority ceiling of initialised mutexes, 6391which is the minimum priority level 6392at which the critical section guarded by the mutex is executed. 6393In order to avoid priority inversion, 6394the priority ceiling of the mutex will be set to a priority 6395higher than or equal to the highest priority of all the threads 6396that may lock that mutex. 6397The values of 6398I<prioceiling> 6399will be within the maximum range of priorities 6400defined under the SCHED_FIFO scheduling policy. 6401 6402=head1 RETURN VALUE 6403 6404Upon successful completion, the 6405I<pthread_mutexattr_setprioceiling()> 6406and 6407I<pthread_mutexattr_getprioceiling()> 6408functions return zero. 6409Otherwise, an error number is returned to indicate the error. 6410 6411=head1 ERRORS 6412 6413The 6414I<pthread_mutexattr_setprioceiling()> 6415and 6416I<pthread_mutexattr_getprioceiling()> 6417functions will fail if: 6418 6419=over 4 6420 6421=item [ENOSYS] 6422 6423The option _POSIX_THREAD_PRIO_PROTECT is not defined and the 6424implementation does not support the function. 6425 6426=back 6427 6428The 6429I<pthread_mutexattr_setprioceiling()> 6430and 6431I<pthread_mutexattr_getprioceiling()> 6432functions may fail if: 6433 6434=over 4 6435 6436=item [EINVAL] 6437 6438The value specified by 6439I<attr> 6440or 6441I<prioceiling> 6442is invalid. 6443 6444=item [EPERM] 6445 6446The caller does not have the privilege to perform the operation. 6447 6448=back 6449 6450=head1 EXAMPLES 6451 6452None. 6453 6454=head1 APPLICATION USAGE 6455 6456None. 6457 6458=head1 FUTURE DIRECTIONS 6459 6460None. 6461 6462=head1 SEE ALSO 6463 6464I<pthread_create()>, 6465I<pthread_mutex_init()>, 6466I<pthread_cond_init()>, 6467I<<pthread.h>>. 6468 6469 6470=head1 ______________________________________________________________________ 6471 6472=head1 NAME 6473 6474B<pthread_mutexattr_setprotocol,> B<pthread_mutexattr_getprotocol> 6475- set and get protocol attribute of mutex attribute object 6476(B<REALTIME THREADS>) 6477 6478=head1 SYNOPSIS 6479 6480#include <pthread.h> 6481 6482int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I<attr>, 6483int I<protocol>); 6484int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I<attr>, 6485int *I<protocol>); 6486 6487=head1 DESCRIPTION 6488 6489The 6490I<pthread_mutexattr_setprotocol()> 6491and 6492I<pthread_mutexattr_getprotocol()> 6493functions, respectively, set and get the protocol attribute of a mutex 6494attribute object pointed to by 6495I<attr> 6496which was previously created by the function 6497I<pthread_mutexattr_init()>. 6498 6499The 6500I<protocol> 6501attribute defines the protocol to be followed in utilising mutexes. 6502The value of 6503I<protocol> 6504may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or 6505PTHREAD_PRIO_PROTECT, which are defined by the header 6506I<<pthread.h>>. 6507 6508When a thread owns a mutex with the PTHREAD_PRIO_NONE 6509protocol attribute, its priority and scheduling are not affected 6510by its mutex ownership. 6511 6512When a thread is blocking higher priority threads because of owning one or 6513more mutexes with the PTHREAD_PRIO_INHERIT 6514protocol attribute, it executes at the higher of its priority 6515or the priority of the highest priority thread waiting on any of the mutexes 6516owned by this thread and initialised with this protocol. 6517 6518When a thread owns one or more mutexes initialised with the 6519PTHREAD_PRIO_PROTECT 6520protocol, it executes at the higher of its priority or the highest 6521of the priority ceilings of all the mutexes 6522owned by this thread and initialised with this attribute, 6523regardless of whether other threads are blocked on any of these 6524mutexes or not. 6525 6526While a thread is holding a mutex which has been initialised with the 6527PRIO_INHERIT or PRIO_PROTECT protocol attributes, 6528it will not be subject to being moved 6529to the tail of the scheduling queue at its priority 6530in the event that its original priority is changed, 6531such as by a call to 6532I<sched_setparam()>. 6533Likewise, 6534when a thread unlocks a mutex that has been initialised with the 6535PRIO_INHERIT or PRIO_PROTECT protocol attributes, 6536it will not be subject to being moved 6537to the tail of the scheduling queue at its priority 6538in the event that its original priority is changed. 6539 6540If a thread simultaneously owns several mutexes 6541initialised with different protocols, 6542it will execute at the highest of the priorities 6543that it would have obtained by each of these protocols. 6544 6545When a thread makes a call to 6546I<pthread_mutex_lock()>, 6547if the symbol _POSIX_THREAD_PRIO_INHERIT 6548is defined and the mutex was 6549initialised with the protocol attribute having the value 6550PTHREAD_PRIO_INHERIT, when the calling thread is blocked 6551because the mutex is owned by another thread, 6552that owner thread will inherit the priority level 6553of the calling thread as long as it continues to own the mutex. 6554The implementation updates its execution priority 6555to the maximum of its assigned priority and all its inherited priorities. 6556Furthermore, if this owner thread itself becomes blocked on another mutex, 6557the same priority inheritance effect will be propagated 6558to this other owner thread, in a recursive manner. 6559 6560=head1 RETURN VALUE 6561 6562Upon successful completion, the 6563I<pthread_mutexattr_setprotocol()> 6564and 6565I<pthread_mutexattr_getprotocol()> 6566functions return zero. 6567Otherwise, an error number is returned to indicate the error. 6568 6569=head1 ERRORS 6570 6571The 6572I<pthread_mutexattr_setprotocol()> 6573and 6574I<pthread_mutexattr_getprotocol()> 6575functions will fail if: 6576 6577=over 4 6578 6579=item [ENOSYS] 6580 6581Neither one of the options _POSIX_THREAD_PRIO_PROTECT and 6582_POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not 6583support the function. 6584 6585=item [ENOTSUP] 6586 6587The value specified by 6588I<protocol> 6589is an unsupported value. 6590 6591=back 6592 6593The 6594I<pthread_mutexattr_setprotocol()> 6595and 6596I<pthread_mutexattr_getprotocol()> 6597functions may fail if: 6598 6599=over 4 6600 6601=item [EINVAL] 6602 6603The value specified by 6604I<attr> 6605ro 6606I<protocol> 6607is invalid. 6608 6609=item [EPERM] 6610 6611The caller does not have the privilege to perform the operation. 6612 6613=back 6614 6615=head1 EXAMPLES 6616 6617None. 6618 6619=head1 APPLICATION USAGE 6620 6621None. 6622 6623=head1 FUTURE DIRECTIONS 6624 6625None. 6626 6627=head1 SEE ALSO 6628 6629I<pthread_create()>, 6630I<pthread_mutex_init()>, 6631I<pthread_cond_init()>, 6632I<<pthread.h>>. 6633 6634=head1 ______________________________________________________________________ 6635 6636=head1 NAME 6637 6638B<pthread_mutexattr_getpshared,> B<pthread_mutexattr_setpshared> 6639- set and get process-shared attribute 6640 6641=head1 SYNOPSIS 6642 6643#include <pthread.h> 6644 6645int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I<attr>, 6646int *I<pshared>); 6647int pthread_mutexattr_setpshared(pthread_mutexattr_t *I<attr>, 6648int I<pshared>); 6649 6650=head1 DESCRIPTION 6651 6652The 6653I<pthread_mutexattr_getpshared()> 6654function obtains the value of the 6655I<process-shared> 6656attribute from the attributes object referenced by 6657I<attr>. 6658The 6659I<pthread_mutexattr_setpshared()> 6660function is used to set the 6661I<process-shared> 6662attribute in an initialised attributes object referenced by 6663I<attr>. 6664 6665The 6666I<process-shared> 6667attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex 6668to be operated upon by any thread that has access to the memory 6669where the mutex is allocated, even if the mutex 6670is allocated in memory that is shared by multiple processes. 6671If the 6672I<process-shared> 6673attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon 6674by threads created within the same process as the thread 6675that initialised the mutex; 6676if threads of differing processes attempt to operate on such a mutex, 6677the behaviour is undefined. 6678The default value of the attribute is 6679PTHREAD_PROCESS_PRIVATE. 6680 6681=head1 RETURN VALUE 6682 6683Upon successful completion, 6684I<pthread_mutexattr_setpshared()> 6685returns zero. 6686Otherwise, an error number is returned to indicate the error. 6687 6688Upon successful completion, 6689I<pthread_mutexattr_getpshared()> 6690returns zero and stores the value of the 6691I<process-shared> 6692attribute of 6693I<attr> 6694into the object referenced by the 6695I<pshared> 6696parameter. 6697Otherwise, an error number is returned to indicate the error. 6698 6699=head1 ERRORS 6700 6701The 6702I<pthread_mutexattr_getpshared()> 6703and 6704I<pthread_mutexattr_setpshared()> 6705functions may fail if: 6706 6707=over 4 6708 6709=item [EINVAL] 6710 6711The value specified by 6712I<attr> 6713is invalid. 6714 6715=back 6716 6717The 6718I<pthread_mutexattr_setpshared()> 6719function may fail if: 6720 6721=over 4 6722 6723=item [EINVAL] 6724 6725The new value specified for the attribute 6726is outside the range of legal values for that attribute. 6727 6728=back 6729 6730These functions will not return an error code of [EINTR]. 6731 6732=head1 EXAMPLES 6733 6734None. 6735 6736=head1 APPLICATION USAGE 6737 6738None. 6739 6740=head1 FUTURE DIRECTIONS 6741 6742None. 6743 6744=head1 SEE ALSO 6745 6746I<pthread_create()>, 6747I<pthread_mutex_init()>, 6748I<pthread_mutexattr_init()>, 6749I<pthread_cond_init()>, 6750I<<pthread.h>>. 6751 6752 6753=head1 ______________________________________________________________________ 6754 6755=head1 NAME 6756 6757B<pthread_mutexattr_gettype,> B<pthread_mutexattr_settype> 6758- get or set a mutex type 6759 6760=head1 SYNOPSIS 6761 6762#include <pthread.h> 6763 6764int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>); 6765int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I<type>); 6766 6767=head1 DESCRIPTION 6768 6769The 6770I<pthread_mutexattr_gettype()> 6771and 6772I<pthread_mutexattr_settype()> 6773functions respectively get and set the mutex I<type> attribute. 6774This attribute is set in the I<type> parameter 6775to these functions. The default value of the I<type> 6776attribute is PTHREAD_MUTEX_DEFAULT. 6777 6778The type of mutex is contained in the I<type> attribute of the 6779mutex attributes. Valid mutex types include: 6780 6781=over 4 6782 6783=item PTHREAD_MUTEX_NORMAL 6784 6785This type of mutex does not detect deadlock. A thread 6786attempting to relock this mutex without first unlocking it 6787will deadlock. Attempting to unlock a 6788mutex locked by a different thread results in undefined behaviour. 6789Attempting to unlock an unlocked 6790mutex results in undefined behaviour. 6791 6792=item PTHREAD_MUTEX_ERRORCHECK 6793 6794This type of mutex provides error checking. A thread 6795attempting to relock this mutex without first unlocking it 6796will return with an error. 6797A thread attempting to unlock a mutex which another 6798thread has locked will return with an error. 6799A thread attempting to unlock an unlocked mutex will 6800return with an error. 6801 6802=item PTHREAD_MUTEX_RECURSIVE 6803 6804A thread attempting to relock this mutex without first 6805unlocking it will succeed in locking the mutex. The relocking 6806deadlock which can occur with 6807mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type 6808of mutex. Multiple 6809locks of this mutex require the same number of unlocks to release 6810the mutex before another thread 6811can acquire the mutex. 6812A thread attempting to unlock a mutex which another thread has 6813locked will return with an error. A thread attempting to 6814unlock an unlocked mutex will return with an error. 6815 6816=item PTHREAD_MUTEX_DEFAULT 6817 6818Attempting to recursively lock a mutex of this type results in 6819undefined behaviour. Attempting to unlock a mutex of this type which 6820was not locked by the calling 6821thread results in undefined behaviour. Attempting to unlock a mutex 6822of this type which is not locked results in undefined behaviour. 6823An implementation is allowed to map this mutex to one of the 6824other mutex types. 6825 6826=back 6827 6828=head1 RETURN VALUE 6829 6830If successful, the 6831I<pthread_mutexattr_settype()> 6832function 6833returns zero. Otherwise, an error number is 6834returned to indicate the error. 6835 6836Upon successful completion, the 6837I<pthread_mutexattr_gettype()> 6838function returns zero and stores the value of the 6839I<type> attribute of I<attr> into the object referenced by the 6840I<type> 6841parameter. Otherwise an error is returned to indicate 6842the error. 6843 6844 6845=head1 ERRORS 6846 6847The 6848I<pthread_mutexattr_gettype()> 6849and 6850I<pthread_mutexattr_settype()> 6851functions will fail if: 6852 6853=over 4 6854 6855=item [EINVAL] 6856 6857The value I<type> is invalid. 6858 6859=back 6860 6861The 6862I<pthread_mutexattr_gettype()> 6863and 6864I<pthread_mutexattr_settype()> 6865functions may fail if: 6866 6867=over 4 6868 6869=item [EINVAL] 6870 6871The value specified by I<attr> is invalid. 6872 6873=back 6874 6875=head1 EXAMPLES 6876 6877None. 6878 6879=head1 APPLICATION USAGE 6880 6881It is advised that an application should not use 6882a PTHREAD_MUTEX_RECURSIVE mutex with condition variables 6883because the implicit unlock performed for a 6884I<pthread_cond_wait()> 6885or 6886I<pthread_cond_timedwait()> 6887may not actually release the 6888mutex (if it had been locked multiple times). If this happens, 6889no other thread can satisfy the condition of the predicate. 6890 6891=head1 FUTURE DIRECTIONS 6892 6893None. 6894 6895=head1 SEE ALSO 6896 6897I<pthread_cond_wait()>, 6898I<pthread_cond_timedwait()>, 6899I<<pthread.h>>. 6900 6901=head1 ______________________________________________________________________ 6902 6903=head1 NAME 6904 6905B<pthread_mutexattr_init,> B<pthread_mutexattr_destroy> 6906- initialise and destroy mutex attributes object 6907 6908=head1 SYNOPSIS 6909 6910#include <pthread.h> 6911 6912int pthread_mutexattr_init(pthread_mutexattr_t *I<attr>); 6913int pthread_mutexattr_destroy(pthread_mutexattr_t *I<attr>); 6914 6915=head1 DESCRIPTION 6916 6917The function 6918I<pthread_mutexattr_init()> 6919initialises a mutex attributes object 6920I<attr> 6921with the default value for all of the attributes 6922defined by the implementation. 6923 6924The effect of initialising an already initialised mutex 6925attributes object is undefined. 6926 6927After a mutex attributes object has been used 6928to initialise one or more mutexes, 6929any function affecting the attributes object (including destruction) 6930does not affect any previously initialised mutexes. 6931 6932The 6933I<pthread_mutexattr_destroy()> 6934function destroys a mutex attributes object; 6935the object becomes, in effect, uninitialised. 6936An implementation may cause 6937I<pthread_mutexattr_destroy()> 6938to set the object referenced by 6939I<attr> 6940to an invalid value. 6941A destroyed mutex attributes object 6942can be re-initialised using 6943I<pthread_mutexattr_init()>; 6944the results of otherwise referencing the object after it has been 6945destroyed are undefined. 6946 6947=head1 RETURN VALUE 6948 6949Upon successful completion, 6950I<pthread_mutexattr_init()> 6951and 6952I<pthread_mutexattr_destroy()> 6953return zero. 6954Otherwise, an error number is returned to indicate the error. 6955 6956=head1 ERRORS 6957 6958The 6959I<pthread_mutexattr_init()> 6960function may fail if: 6961 6962=over 4 6963 6964=item [ENOMEM] 6965 6966Insufficient memory exists to initialise the mutex attributes object. 6967 6968=back 6969 6970The 6971I<pthread_mutexattr_destroy()> 6972function may fail if: 6973 6974=over 4 6975 6976=item [EINVAL] 6977 6978The value specified by 6979I<attr> 6980is invalid. 6981 6982=back 6983 6984These functions will not return an error code of [EINTR]. 6985 6986=head1 EXAMPLES 6987 6988None. 6989 6990=head1 APPLICATION USAGE 6991 6992None. 6993 6994=head1 FUTURE DIRECTIONS 6995 6996None. 6997 6998=head1 SEE ALSO 6999 7000I<pthread_create()>, 7001I<pthread_mutex_init()>, 7002I<pthread_mutexattr_init()>, 7003I<pthread_cond_init()>, 7004I<<pthread.h>>. 7005 7006=head1 ______________________________________________________________________ 7007 7008=head1 NAME 7009 7010B<pthread_mutexattr_setprioceiling,> B<pthread_mutexattr_getprioceiling> 7011- set and get prioceiling attribute of mutex attribute object 7012(B<REALTIME THREADS>) 7013 7014=head1 SYNOPSIS 7015 7016#include <pthread.h> 7017 7018int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I<attr>, 7019int I<prioceiling>); 7020int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I<attr>, 7021int *I<prioceiling>); 7022 7023=head1 DESCRIPTION 7024 7025The 7026I<pthread_mutexattr_setprioceiling()> 7027and 7028I<pthread_mutexattr_getprioceiling()> 7029functions, respectively, set and get the priority ceiling attribute of 7030a mutex attribute object pointed to by 7031I<attr> 7032which was previously created by the function 7033I<pthread_mutexattr_init()>. 7034 7035The 7036I<prioceiling> 7037attribute contains the priority ceiling of initialised mutexes. 7038The values of 7039I<prioceiling> 7040will be within the maximum range of priorities defined by SCHED_FIFO. 7041 7042The 7043I<prioceiling> 7044attribute defines the priority ceiling of initialised mutexes, 7045which is the minimum priority level 7046at which the critical section guarded by the mutex is executed. 7047In order to avoid priority inversion, 7048the priority ceiling of the mutex will be set to a priority 7049higher than or equal to the highest priority of all the threads 7050that may lock that mutex. 7051The values of 7052I<prioceiling> 7053will be within the maximum range of priorities 7054defined under the SCHED_FIFO scheduling policy. 7055 7056=head1 RETURN VALUE 7057 7058Upon successful completion, the 7059I<pthread_mutexattr_setprioceiling()> 7060and 7061I<pthread_mutexattr_getprioceiling()> 7062functions return zero. 7063Otherwise, an error number is returned to indicate the error. 7064 7065=head1 ERRORS 7066 7067The 7068I<pthread_mutexattr_setprioceiling()> 7069and 7070I<pthread_mutexattr_getprioceiling()> 7071functions will fail if: 7072 7073=over 4 7074 7075=item [ENOSYS] 7076 7077The option _POSIX_THREAD_PRIO_PROTECT is not defined and the 7078implementation does not support the function. 7079 7080=back 7081 7082The 7083I<pthread_mutexattr_setprioceiling()> 7084and 7085I<pthread_mutexattr_getprioceiling()> 7086functions may fail if: 7087 7088=over 4 7089 7090=item [EINVAL] 7091 7092The value specified by 7093I<attr> 7094or 7095I<prioceiling> 7096is invalid. 7097 7098=item [EPERM] 7099 7100The caller does not have the privilege to perform the operation. 7101 7102=back 7103 7104=head1 EXAMPLES 7105 7106None. 7107 7108=head1 APPLICATION USAGE 7109 7110None. 7111 7112=head1 FUTURE DIRECTIONS 7113 7114None. 7115 7116=head1 SEE ALSO 7117 7118I<pthread_create()>, 7119I<pthread_mutex_init()>, 7120I<pthread_cond_init()>, 7121I<<pthread.h>>. 7122 7123 7124=head1 ______________________________________________________________________ 7125 7126=head1 NAME 7127 7128B<pthread_mutexattr_setprotocol,> B<pthread_mutexattr_getprotocol> 7129- set and get protocol attribute of mutex attribute object 7130(B<REALTIME THREADS>) 7131 7132=head1 SYNOPSIS 7133 7134#include <pthread.h> 7135 7136int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I<attr>, 7137int I<protocol>); 7138int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I<attr>, 7139int *I<protocol>); 7140 7141=head1 DESCRIPTION 7142 7143The 7144I<pthread_mutexattr_setprotocol()> 7145and 7146I<pthread_mutexattr_getprotocol()> 7147functions, respectively, set and get the protocol attribute of a mutex 7148attribute object pointed to by 7149I<attr> 7150which was previously created by the function 7151I<pthread_mutexattr_init()>. 7152 7153The 7154I<protocol> 7155attribute defines the protocol to be followed in utilising mutexes. 7156The value of 7157I<protocol> 7158may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or 7159PTHREAD_PRIO_PROTECT, which are defined by the header 7160I<<pthread.h>>. 7161 7162When a thread owns a mutex with the PTHREAD_PRIO_NONE 7163protocol attribute, its priority and scheduling are not affected 7164by its mutex ownership. 7165 7166When a thread is blocking higher priority threads because of owning one or 7167more mutexes with the PTHREAD_PRIO_INHERIT 7168protocol attribute, it executes at the higher of its priority 7169or the priority of the highest priority thread waiting on any of the mutexes 7170owned by this thread and initialised with this protocol. 7171 7172When a thread owns one or more mutexes initialised with the 7173PTHREAD_PRIO_PROTECT 7174protocol, it executes at the higher of its priority or the highest 7175of the priority ceilings of all the mutexes 7176owned by this thread and initialised with this attribute, 7177regardless of whether other threads are blocked on any of these 7178mutexes or not. 7179 7180While a thread is holding a mutex which has been initialised with the 7181PRIO_INHERIT or PRIO_PROTECT protocol attributes, 7182it will not be subject to being moved 7183to the tail of the scheduling queue at its priority 7184in the event that its original priority is changed, 7185such as by a call to 7186I<sched_setparam()>. 7187Likewise, 7188when a thread unlocks a mutex that has been initialised with the 7189PRIO_INHERIT or PRIO_PROTECT protocol attributes, 7190it will not be subject to being moved 7191to the tail of the scheduling queue at its priority 7192in the event that its original priority is changed. 7193 7194If a thread simultaneously owns several mutexes 7195initialised with different protocols, 7196it will execute at the highest of the priorities 7197that it would have obtained by each of these protocols. 7198 7199When a thread makes a call to 7200I<pthread_mutex_lock()>, 7201if the symbol _POSIX_THREAD_PRIO_INHERIT 7202is defined and the mutex was 7203initialised with the protocol attribute having the value 7204PTHREAD_PRIO_INHERIT, when the calling thread is blocked 7205because the mutex is owned by another thread, 7206that owner thread will inherit the priority level 7207of the calling thread as long as it continues to own the mutex. 7208The implementation updates its execution priority 7209to the maximum of its assigned priority and all its inherited priorities. 7210Furthermore, if this owner thread itself becomes blocked on another mutex, 7211the same priority inheritance effect will be propagated 7212to this other owner thread, in a recursive manner. 7213 7214=head1 RETURN VALUE 7215 7216Upon successful completion, the 7217I<pthread_mutexattr_setprotocol()> 7218and 7219I<pthread_mutexattr_getprotocol()> 7220functions return zero. 7221Otherwise, an error number is returned to indicate the error. 7222 7223=head1 ERRORS 7224 7225The 7226I<pthread_mutexattr_setprotocol()> 7227and 7228I<pthread_mutexattr_getprotocol()> 7229functions will fail if: 7230 7231=over 4 7232 7233=item [ENOSYS] 7234 7235Neither one of the options _POSIX_THREAD_PRIO_PROTECT and 7236_POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not 7237support the function. 7238 7239=item [ENOTSUP] 7240 7241The value specified by 7242I<protocol> 7243is an unsupported value. 7244 7245=back 7246 7247The 7248I<pthread_mutexattr_setprotocol()> 7249and 7250I<pthread_mutexattr_getprotocol()> 7251functions may fail if: 7252 7253=over 4 7254 7255=item [EINVAL] 7256 7257The value specified by 7258I<attr> 7259ro 7260I<protocol> 7261is invalid. 7262 7263=item [EPERM] 7264 7265The caller does not have the privilege to perform the operation. 7266 7267=back 7268 7269=head1 EXAMPLES 7270 7271None. 7272 7273=head1 APPLICATION USAGE 7274 7275None. 7276 7277=head1 FUTURE DIRECTIONS 7278 7279None. 7280 7281=head1 SEE ALSO 7282 7283I<pthread_create()>, 7284I<pthread_mutex_init()>, 7285I<pthread_cond_init()>, 7286I<<pthread.h>>. 7287 7288=head1 ______________________________________________________________________ 7289 7290=head1 NAME 7291 7292B<pthread_mutexattr_getpshared,> B<pthread_mutexattr_setpshared> 7293- set and get process-shared attribute 7294 7295=head1 SYNOPSIS 7296 7297#include <pthread.h> 7298 7299int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I<attr>, 7300int *I<pshared>); 7301int pthread_mutexattr_setpshared(pthread_mutexattr_t *I<attr>, 7302int I<pshared>); 7303 7304=head1 DESCRIPTION 7305 7306The 7307I<pthread_mutexattr_getpshared()> 7308function obtains the value of the 7309I<process-shared> 7310attribute from the attributes object referenced by 7311I<attr>. 7312The 7313I<pthread_mutexattr_setpshared()> 7314function is used to set the 7315I<process-shared> 7316attribute in an initialised attributes object referenced by 7317I<attr>. 7318 7319The 7320I<process-shared> 7321attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex 7322to be operated upon by any thread that has access to the memory 7323where the mutex is allocated, even if the mutex 7324is allocated in memory that is shared by multiple processes. 7325If the 7326I<process-shared> 7327attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon 7328by threads created within the same process as the thread 7329that initialised the mutex; 7330if threads of differing processes attempt to operate on such a mutex, 7331the behaviour is undefined. 7332The default value of the attribute is 7333PTHREAD_PROCESS_PRIVATE. 7334 7335=head1 RETURN VALUE 7336 7337Upon successful completion, 7338I<pthread_mutexattr_setpshared()> 7339returns zero. 7340Otherwise, an error number is returned to indicate the error. 7341 7342Upon successful completion, 7343I<pthread_mutexattr_getpshared()> 7344returns zero and stores the value of the 7345I<process-shared> 7346attribute of 7347I<attr> 7348into the object referenced by the 7349I<pshared> 7350parameter. 7351Otherwise, an error number is returned to indicate the error. 7352 7353=head1 ERRORS 7354 7355The 7356I<pthread_mutexattr_getpshared()> 7357and 7358I<pthread_mutexattr_setpshared()> 7359functions may fail if: 7360 7361=over 4 7362 7363=item [EINVAL] 7364 7365The value specified by 7366I<attr> 7367is invalid. 7368 7369=back 7370 7371The 7372I<pthread_mutexattr_setpshared()> 7373function may fail if: 7374 7375=over 4 7376 7377=item [EINVAL] 7378 7379The new value specified for the attribute 7380is outside the range of legal values for that attribute. 7381 7382=back 7383 7384These functions will not return an error code of [EINTR]. 7385 7386=head1 EXAMPLES 7387 7388None. 7389 7390=head1 APPLICATION USAGE 7391 7392None. 7393 7394=head1 FUTURE DIRECTIONS 7395 7396None. 7397 7398=head1 SEE ALSO 7399 7400I<pthread_create()>, 7401I<pthread_mutex_init()>, 7402I<pthread_mutexattr_init()>, 7403I<pthread_cond_init()>, 7404I<<pthread.h>>. 7405 7406 7407=head1 ______________________________________________________________________ 7408 7409=head1 NAME 7410 7411B<pthread_mutexattr_gettype,> B<pthread_mutexattr_settype> 7412- get or set a mutex type 7413 7414=head1 SYNOPSIS 7415 7416#include <pthread.h> 7417 7418int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>); 7419int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I<type>); 7420 7421=head1 DESCRIPTION 7422 7423The 7424I<pthread_mutexattr_gettype()> 7425and 7426I<pthread_mutexattr_settype()> 7427functions respectively get and set the mutex I<type> attribute. 7428This attribute is set in the I<type> parameter 7429to these functions. The default value of the I<type> 7430attribute is PTHREAD_MUTEX_DEFAULT. 7431 7432The type of mutex is contained in the I<type> attribute of the 7433mutex attributes. Valid mutex types include: 7434 7435=over 4 7436 7437=item PTHREAD_MUTEX_NORMAL 7438 7439This type of mutex does not detect deadlock. A thread 7440attempting to relock this mutex without first unlocking it 7441will deadlock. Attempting to unlock a 7442mutex locked by a different thread results in undefined behaviour. 7443Attempting to unlock an unlocked 7444mutex results in undefined behaviour. 7445 7446=item PTHREAD_MUTEX_ERRORCHECK 7447 7448This type of mutex provides error checking. A thread 7449attempting to relock this mutex without first unlocking it 7450will return with an error. 7451A thread attempting to unlock a mutex which another 7452thread has locked will return with an error. 7453A thread attempting to unlock an unlocked mutex will 7454return with an error. 7455 7456=item PTHREAD_MUTEX_RECURSIVE 7457 7458A thread attempting to relock this mutex without first 7459unlocking it will succeed in locking the mutex. The relocking 7460deadlock which can occur with 7461mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type 7462of mutex. Multiple 7463locks of this mutex require the same number of unlocks to release 7464the mutex before another thread 7465can acquire the mutex. 7466A thread attempting to unlock a mutex which another thread has 7467locked will return with an error. A thread attempting to 7468unlock an unlocked mutex will return with an error. 7469 7470=item PTHREAD_MUTEX_DEFAULT 7471 7472Attempting to recursively lock a mutex of this type results in 7473undefined behaviour. Attempting to unlock a mutex of this type which 7474was not locked by the calling 7475thread results in undefined behaviour. Attempting to unlock a mutex 7476of this type which is not locked results in undefined behaviour. 7477An implementation is allowed to map this mutex to one of the 7478other mutex types. 7479 7480=back 7481 7482=head1 RETURN VALUE 7483 7484If successful, the 7485I<pthread_mutexattr_settype()> 7486function 7487returns zero. Otherwise, an error number is 7488returned to indicate the error. 7489 7490Upon successful completion, the 7491I<pthread_mutexattr_gettype()> 7492function returns zero and stores the value of the 7493I<type> attribute of I<attr> into the object referenced by the 7494I<type> 7495parameter. Otherwise an error is returned to indicate 7496the error. 7497 7498 7499=head1 ERRORS 7500 7501The 7502I<pthread_mutexattr_gettype()> 7503and 7504I<pthread_mutexattr_settype()> 7505functions will fail if: 7506 7507=over 4 7508 7509=item [EINVAL] 7510 7511The value I<type> is invalid. 7512 7513=back 7514 7515The 7516I<pthread_mutexattr_gettype()> 7517and 7518I<pthread_mutexattr_settype()> 7519functions may fail if: 7520 7521=over 4 7522 7523=item [EINVAL] 7524 7525The value specified by I<attr> is invalid. 7526 7527=back 7528 7529=head1 EXAMPLES 7530 7531None. 7532 7533=head1 APPLICATION USAGE 7534 7535It is advised that an application should not use 7536a PTHREAD_MUTEX_RECURSIVE mutex with condition variables 7537because the implicit unlock performed for a 7538I<pthread_cond_wait()> 7539or 7540I<pthread_cond_timedwait()> 7541may not actually release the 7542mutex (if it had been locked multiple times). If this happens, 7543no other thread can satisfy the condition of the predicate. 7544 7545=head1 FUTURE DIRECTIONS 7546 7547None. 7548 7549=head1 SEE ALSO 7550 7551I<pthread_cond_wait()>, 7552I<pthread_cond_timedwait()>, 7553I<<pthread.h>>. 7554 7555=head1 ______________________________________________________________________ 7556 7557=head1 NAME 7558 7559B<pthread_once> - dynamic package initialisation 7560 7561=head1 SYNOPSIS 7562 7563#include <pthread.h> 7564 7565int pthread_once(pthread_once_t *I<once_control>, 7566void (*I<init_routine>)(void)); 7567pthread_once_t I<once_control> = PTHREAD_ONCE_INIT; 7568 7569=head1 DESCRIPTION 7570 7571The first call to 7572I<pthread_once()> 7573by any thread in a process, with a given 7574I<once_control>, 7575will call the 7576I<init_routine()> 7577with no arguments. 7578Subsequent calls of 7579I<pthread_once()> 7580with the same 7581I<once_control> 7582will not call the 7583I<init_routine()>. 7584On return from 7585I<pthread_once()>, 7586it is guaranteed that 7587I<init_routine()> 7588has completed. 7589The 7590I<once_control> 7591parameter is used to determine whether 7592the associated initialisation routine has been called. 7593 7594The function 7595I<pthread_once()> 7596is not a cancellation point. 7597However, if 7598I<init_routine()> 7599is a cancellation point and is canceled, 7600the effect on 7601I<once_control> 7602is as if 7603I<pthread_once()> 7604was never called. 7605 7606The constant PTHREAD_ONCE_INIT 7607is defined by the header 7608I<<pthread.h>>. 7609 7610The behaviour of 7611I<pthread_once()> 7612is undefined if 7613I<once_control> 7614has automatic storage duration or is not initialised by 7615PTHREAD_ONCE_INIT. 7616 7617=head1 RETURN VALUE 7618 7619Upon successful completion, 7620I<pthread_once()> 7621returns zero. 7622Otherwise, an error number is returned to indicate the error. 7623 7624=head1 ERRORS 7625 7626No errors are defined. 7627 7628The 7629I<pthread_once()> 7630function will not return an error code of [EINTR]. 7631 7632=head1 EXAMPLES 7633 7634None. 7635 7636=head1 APPLICATION USAGE 7637 7638None. 7639 7640=head1 FUTURE DIRECTIONS 7641 7642None. 7643 7644=head1 SEE ALSO 7645 7646I<<pthread,h>>. 7647 7648=head1 ______________________________________________________________________ 7649 7650=head1 NAME 7651 7652B<pthread_rwlock_init,> B<pthread_rwlock_destroy> 7653- initialise or destroy a read-write lock object 7654 7655=head1 SYNOPSIS 7656 7657#include <pthread.h> 7658 7659int pthread_rwlock_init(pthread_rwlock_t *rwlock, 7660const pthread_rwlockattr_t I<*attr>); 7661int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>); 7662pthread_rwlock_t I<rwlock>=PTHREAD_RWLOCK_INITIALIZER; 7663 7664=head1 DESCRIPTION 7665 7666The 7667I<pthread_rwlock_init()> 7668function initialises the read-write lock referenced by I<rwlock> with 7669the attributes referenced by I<attr>. If I<attr> is NULL, the 7670default 7671read-write lock attributes are used; the effect is the same as 7672passing the address of a default read-write lock attributes object. 7673Once initialised, the lock can be used any 7674number of times without being re-initialised. 7675Upon successful initialisation, the state of the read-write lock 7676becomes initialised and unlocked. 7677Results are undefined if 7678I<pthread_rwlock_init()> 7679is called specifying an already initialised read-write lock. 7680Results are undefined if a read-write lock is used without first being 7681initialised. 7682 7683If the 7684I<pthread_rwlock_init()> 7685function fails, I<rwlock> is not initialised and the contents of 7686I<rwlock> are undefined. 7687 7688The 7689I<pthread_rwlock_destroy()> 7690function destroys the read-write lock object referenced by I<rwlock> 7691and 7692releases any resources used by the lock. 7693The effect of subsequent use of the lock is undefined until the lock 7694is re-initialised by another call to 7695I<pthread_rwlock_init()>. 7696An implementation may cause 7697I<pthread_rwlock_destroy()> 7698to set the object referenced by I<rwlock> to an invalid value. 7699Results are undefined if 7700I<pthread_rwlock_destroy()> 7701is called when any thread holds I<rwlock>. 7702Attempting to destroy an uninitialised 7703read-write lock results in undefined behaviour. 7704A destroyed read-write lock object can be re-initialised using 7705I<pthread_rwlock_init()>; 7706the results of otherwise referencing the read-write lock object after it 7707has been destroyed are undefined. 7708 7709In cases where default read-write lock attributes are appropriate, the 7710macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks 7711that are statically allocated. 7712The effect is equivalent to dynamic initialisation by a call to 7713I<pthread_rwlock_init()> 7714with the parameter I<attr> specified as NULL, except that no error 7715checks are performed. 7716 7717=head1 RETURN VALUE 7718 7719If successful, the 7720I<pthread_rwlock_init()> 7721and 7722I<pthread_rwlock_destroy()> 7723functions return zero. Otherwise, an 7724error number is returned to indicate the error. 7725The [EBUSY] and [EINVAL] error checks, if implemented, will 7726act as if they were performed immediately at the beginning of processing 7727for the function and caused an error return 7728prior to modifying the state of the read-write lock specified by 7729I<rwlock>. 7730 7731=head1 ERRORS 7732 7733The 7734I<pthread_rwlock_init()> 7735function will fail if: 7736 7737=over 4 7738 7739=item [EAGAIN] 7740 7741The system lacked the necessary resources (other than memory) 7742to initialise another read-write lock. 7743 7744=item [ENOMEM] 7745 7746Insufficient memory exists to initialise the read-write lock. 7747 7748=item [EPERM] 7749 7750The caller does not have the privilege to perform the operation. 7751 7752=back 7753 7754The 7755I<pthread_rwlock_init()> 7756function may fail if: 7757 7758=over 4 7759 7760=item [EBUSY] 7761 7762The implementation has detected an attempt to re-initialise the 7763object referenced by I<rwlock>, a previously initialised but 7764not yet destroyed read-write lock. 7765 7766=item [EINVAL] 7767 7768The value specified by I<attr> is invalid. 7769 7770=back 7771 7772The 7773I<pthread_rwlock_destroy()> 7774function may fail if: 7775 7776=over 4 7777 7778=item [EBUSY] 7779 7780The implementation has detected an attempt to destroy the 7781object referenced by I<rwlock> while it is locked. 7782 7783=item [EINVAL] 7784 7785The value specified by I<attr> is invalid. 7786 7787=back 7788 7789=head1 EXAMPLES 7790 7791None. 7792 7793=head1 APPLICATION USAGE 7794 7795Similar functions are being developed by IEEE PASC. 7796In keeping with its objective of ensuring that CAE 7797Specifications are fully aligned with formal standards, The Open Group 7798intends to add any new interfaces adopted by an official IEEE standard 7799in this area. 7800 7801=head1 FUTURE DIRECTIONS 7802 7803None. 7804 7805=head1 SEE ALSO 7806 7807I<<pthread.h>>, 7808I<pthread_rwlock_rdlock()>, 7809I<pthread_rwlock_wrlock()>, 7810I<pthread_rwlockattr_init()>, 7811I<pthread_rwlock_unlock()>. 7812 7813=head1 ______________________________________________________________________ 7814 7815=head1 NAME 7816 7817B<pthread_rwlock_init,> B<pthread_rwlock_destroy> 7818- initialise or destroy a read-write lock object 7819 7820=head1 SYNOPSIS 7821 7822#include <pthread.h> 7823 7824int pthread_rwlock_init(pthread_rwlock_t *rwlock, 7825const pthread_rwlockattr_t I<*attr>); 7826int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>); 7827pthread_rwlock_t I<rwlock>=PTHREAD_RWLOCK_INITIALIZER; 7828 7829=head1 DESCRIPTION 7830 7831The 7832I<pthread_rwlock_init()> 7833function initialises the read-write lock referenced by I<rwlock> with 7834the attributes referenced by I<attr>. If I<attr> is NULL, the 7835default 7836read-write lock attributes are used; the effect is the same as 7837passing the address of a default read-write lock attributes object. 7838Once initialised, the lock can be used any 7839number of times without being re-initialised. 7840Upon successful initialisation, the state of the read-write lock 7841becomes initialised and unlocked. 7842Results are undefined if 7843I<pthread_rwlock_init()> 7844is called specifying an already initialised read-write lock. 7845Results are undefined if a read-write lock is used without first being 7846initialised. 7847 7848If the 7849I<pthread_rwlock_init()> 7850function fails, I<rwlock> is not initialised and the contents of 7851I<rwlock> are undefined. 7852 7853The 7854I<pthread_rwlock_destroy()> 7855function destroys the read-write lock object referenced by I<rwlock> 7856and 7857releases any resources used by the lock. 7858The effect of subsequent use of the lock is undefined until the lock 7859is re-initialised by another call to 7860I<pthread_rwlock_init()>. 7861An implementation may cause 7862I<pthread_rwlock_destroy()> 7863to set the object referenced by I<rwlock> to an invalid value. 7864Results are undefined if 7865I<pthread_rwlock_destroy()> 7866is called when any thread holds I<rwlock>. 7867Attempting to destroy an uninitialised 7868read-write lock results in undefined behaviour. 7869A destroyed read-write lock object can be re-initialised using 7870I<pthread_rwlock_init()>; 7871the results of otherwise referencing the read-write lock object after it 7872has been destroyed are undefined. 7873 7874In cases where default read-write lock attributes are appropriate, the 7875macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks 7876that are statically allocated. 7877The effect is equivalent to dynamic initialisation by a call to 7878I<pthread_rwlock_init()> 7879with the parameter I<attr> specified as NULL, except that no error 7880checks are performed. 7881 7882=head1 RETURN VALUE 7883 7884If successful, the 7885I<pthread_rwlock_init()> 7886and 7887I<pthread_rwlock_destroy()> 7888functions return zero. Otherwise, an 7889error number is returned to indicate the error. 7890The [EBUSY] and [EINVAL] error checks, if implemented, will 7891act as if they were performed immediately at the beginning of processing 7892for the function and caused an error return 7893prior to modifying the state of the read-write lock specified by 7894I<rwlock>. 7895 7896=head1 ERRORS 7897 7898The 7899I<pthread_rwlock_init()> 7900function will fail if: 7901 7902=over 4 7903 7904=item [EAGAIN] 7905 7906The system lacked the necessary resources (other than memory) 7907to initialise another read-write lock. 7908 7909=item [ENOMEM] 7910 7911Insufficient memory exists to initialise the read-write lock. 7912 7913=item [EPERM] 7914 7915The caller does not have the privilege to perform the operation. 7916 7917=back 7918 7919The 7920I<pthread_rwlock_init()> 7921function may fail if: 7922 7923=over 4 7924 7925=item [EBUSY] 7926 7927The implementation has detected an attempt to re-initialise the 7928object referenced by I<rwlock>, a previously initialised but 7929not yet destroyed read-write lock. 7930 7931=item [EINVAL] 7932 7933The value specified by I<attr> is invalid. 7934 7935=back 7936 7937The 7938I<pthread_rwlock_destroy()> 7939function may fail if: 7940 7941=over 4 7942 7943=item [EBUSY] 7944 7945The implementation has detected an attempt to destroy the 7946object referenced by I<rwlock> while it is locked. 7947 7948=item [EINVAL] 7949 7950The value specified by I<attr> is invalid. 7951 7952=back 7953 7954=head1 EXAMPLES 7955 7956None. 7957 7958=head1 APPLICATION USAGE 7959 7960Similar functions are being developed by IEEE PASC. 7961In keeping with its objective of ensuring that CAE 7962Specifications are fully aligned with formal standards, The Open Group 7963intends to add any new interfaces adopted by an official IEEE standard 7964in this area. 7965 7966=head1 FUTURE DIRECTIONS 7967 7968None. 7969 7970=head1 SEE ALSO 7971 7972I<<pthread.h>>, 7973I<pthread_rwlock_rdlock()>, 7974I<pthread_rwlock_wrlock()>, 7975I<pthread_rwlockattr_init()>, 7976I<pthread_rwlock_unlock()>. 7977 7978=head1 ______________________________________________________________________ 7979 7980=head1 NAME 7981 7982B<pthread_rwlock_rdlock,> B<pthread_rwlock_tryrdlock> 7983- lock a read-write lock object for reading 7984 7985=head1 SYNOPSIS 7986 7987#include <pthread.h> 7988 7989int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>); 7990int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>); 7991 7992=head1 DESCRIPTION 7993 7994The 7995I<pthread_rwlock_rdlock()> 7996function applies a read lock to the read-write lock referenced by 7997I<rwlock>. 7998The calling thread acquires the read lock if a writer does not 7999hold the lock and there are no writers blocked 8000on the lock. It is unspecified whether the calling thread 8001acquires the lock when a writer does not hold the lock 8002and there are writers waiting for the lock. If a writer holds 8003the lock, the calling thread will not acquire the 8004read lock. If the read lock is not acquired, the calling 8005thread blocks (that is, it does not return from the 8006I<pthread_rwlock_rdlock()> 8007call) until it can acquire the lock. 8008Results are undefined if the calling thread holds 8009a write lock on I<rwlock> 8010at the time the call is made. 8011 8012Implementations are allowed to favour writers over readers 8013to avoid writer starvation. 8014 8015A thread may hold multiple concurrent read locks on I<rwlock> 8016(that is, successfully call the 8017I<pthread_rwlock_rdlock()> 8018function I<n> times). If so, the thread 8019must perform matching unlocks (that is, it must 8020call the 8021I<pthread_rwlock_unlock()> 8022function I<n> times). 8023 8024The function 8025I<pthread_rwlock_tryrdlock()> 8026applies a read lock 8027as in the 8028I<pthread_rwlock_rdlock()> 8029function 8030with the exception that the function fails if any thread holds a 8031write lock on I<rwlock> or there are writers blocked 8032on I<rwlock>. 8033 8034Results are undefined if any of these functions are called with 8035an uninitialised read-write lock. 8036 8037If a signal is delivered to a thread waiting for a read-write 8038lock for reading, upon return from the signal handler 8039the thread resumes waiting for the read-write lock for 8040reading as if it was not interrupted. 8041 8042=head1 RETURN VALUE 8043 8044If successful, the 8045I<pthread_rwlock_rdlock()> 8046function returns zero. 8047Otherwise, an error number is returned 8048to indicate the error. 8049 8050The function 8051I<pthread_rwlock_tryrdlock()> 8052returns zero if the 8053lock for reading on the read-write lock object 8054referenced by I<rwlock> is acquired. 8055Otherwise an error number 8056is returned to indicate the error. 8057 8058=head1 ERRORS 8059 8060The 8061I<pthread_rwlock_tryrdlock()> 8062function will fail if: 8063 8064=over 4 8065 8066=item [EBUSY] 8067 8068The read-write lock could not be acquired for reading because a 8069writer holds the 8070lock or was blocked on it. 8071 8072=back 8073 8074The 8075I<pthread_rwlock_rdlock()> 8076and 8077I<pthread_rwlock_tryrdlock()> 8078functions may fail if: 8079 8080=over 4 8081 8082=item [EINVAL] 8083 8084The value specified by I<rwlock> does not refer to an initialised 8085read-write lock object. 8086 8087=item [EDEADLK] 8088 8089The current thread already owns the read-write lock for writing. 8090 8091=item [EAGAIN] 8092 8093The read lock could not be acquired because the maximum number of 8094read locks 8095for I<rwlock> has been exceeded. 8096 8097=back 8098 8099=head1 EXAMPLES 8100 8101None. 8102 8103=head1 APPLICATION USAGE 8104 8105Similar functions are being developed by IEEE PASC. 8106In keeping with its objective of ensuring that CAE 8107Specifications are fully aligned with formal standards, The Open Group 8108intends to add any new interfaces adopted by an official IEEE standard 8109in this area. 8110 8111Realtime applications may encounter priority inversion when using 8112read-write locks. 8113The problem occurs when a high priority thread "locks" a read-write 8114lock that is about to be "unlocked" by a low priority thread, but 8115the low priority thread is preempted by a medium priority thread. 8116This scenario leads to priority inversion; a high priority thread is 8117blocked by lower priority threads for an unlimited period of time. 8118During system design, realtime programmers must take into account the 8119possibility of this kind of priority inversion. 8120They can deal with it in a number of ways, such as by having critical 8121sections that are guarded by read-write locks execute at a high 8122priority, so that a thread cannot be preempted while executing in its 8123critical section. 8124 8125=head1 FUTURE DIRECTIONS 8126 8127None. 8128 8129=head1 SEE ALSO 8130 8131I<<pthread.h>>, 8132I<pthread_rwlock_init()>, 8133I<pthread_rwlock_wrlock()>, 8134I<pthread_rwlockattr_init()>, 8135I<pthread_rwlock_unlock()>. 8136 8137=head1 ______________________________________________________________________ 8138 8139=head1 NAME 8140 8141B<pthread_rwlock_rdlock,> B<pthread_rwlock_tryrdlock> 8142- lock a read-write lock object for reading 8143 8144=head1 SYNOPSIS 8145 8146#include <pthread.h> 8147 8148int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>); 8149int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>); 8150 8151=head1 DESCRIPTION 8152 8153The 8154I<pthread_rwlock_rdlock()> 8155function applies a read lock to the read-write lock referenced by 8156I<rwlock>. 8157The calling thread acquires the read lock if a writer does not 8158hold the lock and there are no writers blocked 8159on the lock. It is unspecified whether the calling thread 8160acquires the lock when a writer does not hold the lock 8161and there are writers waiting for the lock. If a writer holds 8162the lock, the calling thread will not acquire the 8163read lock. If the read lock is not acquired, the calling 8164thread blocks (that is, it does not return from the 8165I<pthread_rwlock_rdlock()> 8166call) until it can acquire the lock. 8167Results are undefined if the calling thread holds 8168a write lock on I<rwlock> 8169at the time the call is made. 8170 8171Implementations are allowed to favour writers over readers 8172to avoid writer starvation. 8173 8174A thread may hold multiple concurrent read locks on I<rwlock> 8175(that is, successfully call the 8176I<pthread_rwlock_rdlock()> 8177function I<n> times). If so, the thread 8178must perform matching unlocks (that is, it must 8179call the 8180I<pthread_rwlock_unlock()> 8181function I<n> times). 8182 8183The function 8184I<pthread_rwlock_tryrdlock()> 8185applies a read lock 8186as in the 8187I<pthread_rwlock_rdlock()> 8188function 8189with the exception that the function fails if any thread holds a 8190write lock on I<rwlock> or there are writers blocked 8191on I<rwlock>. 8192 8193Results are undefined if any of these functions are called with 8194an uninitialised read-write lock. 8195 8196If a signal is delivered to a thread waiting for a read-write 8197lock for reading, upon return from the signal handler 8198the thread resumes waiting for the read-write lock for 8199reading as if it was not interrupted. 8200 8201=head1 RETURN VALUE 8202 8203If successful, the 8204I<pthread_rwlock_rdlock()> 8205function returns zero. 8206Otherwise, an error number is returned 8207to indicate the error. 8208 8209The function 8210I<pthread_rwlock_tryrdlock()> 8211returns zero if the 8212lock for reading on the read-write lock object 8213referenced by I<rwlock> is acquired. 8214Otherwise an error number 8215is returned to indicate the error. 8216 8217=head1 ERRORS 8218 8219The 8220I<pthread_rwlock_tryrdlock()> 8221function will fail if: 8222 8223=over 4 8224 8225=item [EBUSY] 8226 8227The read-write lock could not be acquired for reading because a 8228writer holds the 8229lock or was blocked on it. 8230 8231=back 8232 8233The 8234I<pthread_rwlock_rdlock()> 8235and 8236I<pthread_rwlock_tryrdlock()> 8237functions may fail if: 8238 8239=over 4 8240 8241=item [EINVAL] 8242 8243The value specified by I<rwlock> does not refer to an initialised 8244read-write lock object. 8245 8246=item [EDEADLK] 8247 8248The current thread already owns the read-write lock for writing. 8249 8250=item [EAGAIN] 8251 8252The read lock could not be acquired because the maximum number of 8253read locks 8254for I<rwlock> has been exceeded. 8255 8256=back 8257 8258=head1 EXAMPLES 8259 8260None. 8261 8262=head1 APPLICATION USAGE 8263 8264Similar functions are being developed by IEEE PASC. 8265In keeping with its objective of ensuring that CAE 8266Specifications are fully aligned with formal standards, The Open Group 8267intends to add any new interfaces adopted by an official IEEE standard 8268in this area. 8269 8270Realtime applications may encounter priority inversion when using 8271read-write locks. 8272The problem occurs when a high priority thread "locks" a read-write 8273lock that is about to be "unlocked" by a low priority thread, but 8274the low priority thread is preempted by a medium priority thread. 8275This scenario leads to priority inversion; a high priority thread is 8276blocked by lower priority threads for an unlimited period of time. 8277During system design, realtime programmers must take into account the 8278possibility of this kind of priority inversion. 8279They can deal with it in a number of ways, such as by having critical 8280sections that are guarded by read-write locks execute at a high 8281priority, so that a thread cannot be preempted while executing in its 8282critical section. 8283 8284=head1 FUTURE DIRECTIONS 8285 8286None. 8287 8288=head1 SEE ALSO 8289 8290I<<pthread.h>>, 8291I<pthread_rwlock_init()>, 8292I<pthread_rwlock_wrlock()>, 8293I<pthread_rwlockattr_init()>, 8294I<pthread_rwlock_unlock()>. 8295 8296=head1 ______________________________________________________________________ 8297 8298=head1 NAME 8299 8300B<pthread_rwlock_wrlock,> B<pthread_rwlock_trywrlock> 8301- lock a read-write lock object for writing 8302 8303=head1 SYNOPSIS 8304 8305#include <pthread.h> 8306 8307int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>); 8308int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>); 8309 8310=head1 DESCRIPTION 8311 8312The 8313I<pthread_rwlock_wrlock()> 8314function applies a write lock to 8315the read-write lock referenced by I<rwlock>. The 8316calling thread acquires the write lock if no other thread 8317(reader or writer) holds the read-write lock I<rwlock>. 8318Otherwise, the thread blocks (that is, does not return from the 8319I<pthread_rwlock_wrlock()> 8320call) until it can 8321acquire the lock. Results are undefined if the calling thread 8322holds the read-write lock (whether a read or write 8323lock) at the time the call is made. 8324 8325Implementations are allowed to favour writers over 8326readers to avoid writer starvation. 8327 8328The function 8329I<pthread_rwlock_trywrlock()> 8330applies a write lock 8331like the 8332I<pthread_rwlock_wrlock()> 8333function, with the exception that the function fails if any 8334thread currently holds I<rwlock> (for reading or writing). 8335 8336Results are undefined if any of these functions are called with 8337an uninitialised read-write lock. 8338 8339If a signal is delivered to a thread waiting for a read-write 8340lock for writing, upon return from the signal handler 8341the thread resumes waiting for the read-write lock for 8342writing as if it was not interrupted. 8343 8344=head1 RETURN VALUE 8345 8346If successful, the 8347I<pthread_rwlock_wrlock()> 8348function returns zero. 8349Otherwise, an error number is returned 8350to indicate the error. 8351 8352The function 8353I<pthread_rwlock_trywrlock()> 8354returns zero if the 8355lock for writing on the read-write lock object 8356referenced by I<rwlock> is acquired. 8357Otherwise an error number is 8358returned to indicate the error. 8359 8360=head1 ERRORS 8361 8362The 8363I<pthread_rwlock_trywrlock()> 8364function will fail if: 8365 8366=over 4 8367 8368=item [EBUSY] 8369 8370The read-write lock could not be acquired for writing because it 8371was already locked for reading or writing. 8372 8373=back 8374 8375The 8376I<pthread_rwlock_wrlock()> 8377and 8378I<pthread_rwlock_trywrlock()> 8379functions may fail if: 8380 8381=over 4 8382 8383=item [EINVAL] 8384 8385The value specified by I<rwlock> does not refer to an initialised 8386read-write lock object. 8387 8388=item [EDEADLK] 8389 8390The current thread already owns the read-write lock for writing or 8391reading. 8392 8393=back 8394 8395=head1 EXAMPLES 8396 8397None. 8398 8399=head1 APPLICATION USAGE 8400 8401Similar functions are being developed by IEEE PASC. 8402In keeping with its objective of ensuring that CAE 8403Specifications are fully aligned with formal standards, The Open Group 8404intends to add any new interfaces adopted by an official IEEE standard 8405in this area. 8406 8407Realtime applications may encounter priority inversion when using 8408read-write locks. 8409The problem occurs when a high priority thread "locks" a read-write 8410lock that is about to be "unlocked" by a low priority thread, but 8411the low priority thread is preempted by a medium priority thread. 8412This scenario leads to priority inversion; a high priority thread is 8413blocked by lower priority threads for an unlimited period of time. 8414During system design, realtime programmers must take into account the 8415possibility of this kind of priority inversion. 8416They can deal with it in a number of ways, such as by having critical 8417sections that are guarded by read-write locks execute at a high 8418priority, so that a thread cannot be preempted while executing in its 8419critical section. 8420 8421=head1 FUTURE DIRECTIONS 8422 8423None. 8424 8425=head1 SEE ALSO 8426 8427I<<pthread.h>>, 8428I<pthread_rwlock_init()>, 8429I<pthread_rwlock_unlock()>, 8430I<pthread_rwlockattr_init()>, 8431I<pthread_rwlock_rdlock()>. 8432 8433=head1 ______________________________________________________________________ 8434 8435=head1 NAME 8436 8437B<pthread_rwlock_unlock> - unlock a read-write lock object 8438 8439=head1 SYNOPSIS 8440 8441#include <pthread.h> 8442 8443int pthread_rwlock_unlock(pthread_rwlock_t I<*rwlock>); 8444 8445=head1 DESCRIPTION 8446 8447The 8448I<pthread_rwlock_unlock()> 8449function is called to release a lock held on the read-write lock 8450object referenced by I<rwlock>. 8451Results are undefined if the read-write lock I<rwlock> is not 8452held by the calling thread. 8453 8454If this function is called to release a read lock from the 8455read-write lock object and there are other read locks 8456currently held on this read-write lock object, the read-write 8457lock object remains in the read locked state. 8458If this function releases the calling thread's last read lock on this 8459read-write lock object, then the calling thread is no longer one of 8460the owners of the object. 8461If this function releases the last read lock for this read-write lock 8462object, the read-write lock object will be put in the unlocked state 8463with no owners. 8464 8465If this function is called to release a write lock for this 8466read-write lock object, the read-write lock object will 8467be put in the unlocked state with no owners. 8468 8469If the call to the 8470I<pthread_rwlock_unlock()> 8471function results in 8472the read-write lock object becoming unlocked 8473and there are multiple threads waiting to acquire the read-write 8474lock object for writing, the scheduling policy 8475is used to determine which thread acquires the read-write 8476lock object for writing. If there are multiple 8477threads waiting to acquire the read-write lock object for reading, 8478the scheduling policy is used to determine 8479the order in which the waiting threads acquire the 8480read-write lock object for reading. 8481If there are multiple threads blocked on I<rwlock> 8482for both read locks and write locks, it is 8483unspecified whether the readers acquire the lock first or whether 8484a writer acquires the lock first. 8485 8486Results are undefined if any of these functions are called with 8487an uninitialised read-write lock. 8488 8489=head1 RETURN VALUE 8490 8491If successful, the 8492I<pthread_rwlock_unlock()> 8493function returns zero. 8494Otherwise, an error number is returned 8495to indicate the error. 8496 8497=head1 ERRORS 8498 8499The 8500I<pthread_rwlock_unlock()> 8501function may fail if: 8502 8503=over 4 8504 8505=item [EINVAL] 8506 8507The value specified by I<rwlock> does not refer to an initialised 8508read-write lock object. 8509 8510=item [EPERM] 8511 8512The current thread does not own the read-write lock. 8513 8514=back 8515 8516=head1 EXAMPLES 8517 8518None. 8519 8520=head1 APPLICATION USAGE 8521 8522Similar functions are being developed by IEEE PASC. 8523In keeping with its objective of ensuring that CAE 8524Specifications are fully aligned with formal standards, The Open Group 8525intends to add any new interfaces adopted by an official IEEE standard 8526in this area. 8527 8528=head1 FUTURE DIRECTIONS 8529 8530None. 8531 8532=head1 SEE ALSO 8533 8534I<<pthread.h>>, 8535I<pthread_rwlock_init()>, 8536I<pthread_rwlock_wrlock()>, 8537I<pthread_rwlockattr_init()>, 8538I<pthread_rwlock_rdlock()>. 8539 8540=head1 ______________________________________________________________________ 8541 8542=head1 NAME 8543 8544B<pthread_rwlock_wrlock,> B<pthread_rwlock_trywrlock> 8545- lock a read-write lock object for writing 8546 8547=head1 SYNOPSIS 8548 8549#include <pthread.h> 8550 8551int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>); 8552int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>); 8553 8554=head1 DESCRIPTION 8555 8556The 8557I<pthread_rwlock_wrlock()> 8558function applies a write lock to 8559the read-write lock referenced by I<rwlock>. The 8560calling thread acquires the write lock if no other thread 8561(reader or writer) holds the read-write lock I<rwlock>. 8562Otherwise, the thread blocks (that is, does not return from the 8563I<pthread_rwlock_wrlock()> 8564call) until it can 8565acquire the lock. Results are undefined if the calling thread 8566holds the read-write lock (whether a read or write 8567lock) at the time the call is made. 8568 8569Implementations are allowed to favour writers over 8570readers to avoid writer starvation. 8571 8572The function 8573I<pthread_rwlock_trywrlock()> 8574applies a write lock 8575like the 8576I<pthread_rwlock_wrlock()> 8577function, with the exception that the function fails if any 8578thread currently holds I<rwlock> (for reading or writing). 8579 8580Results are undefined if any of these functions are called with 8581an uninitialised read-write lock. 8582 8583If a signal is delivered to a thread waiting for a read-write 8584lock for writing, upon return from the signal handler 8585the thread resumes waiting for the read-write lock for 8586writing as if it was not interrupted. 8587 8588=head1 RETURN VALUE 8589 8590If successful, the 8591I<pthread_rwlock_wrlock()> 8592function returns zero. 8593Otherwise, an error number is returned 8594to indicate the error. 8595 8596The function 8597I<pthread_rwlock_trywrlock()> 8598returns zero if the 8599lock for writing on the read-write lock object 8600referenced by I<rwlock> is acquired. 8601Otherwise an error number is 8602returned to indicate the error. 8603 8604=head1 ERRORS 8605 8606The 8607I<pthread_rwlock_trywrlock()> 8608function will fail if: 8609 8610=over 4 8611 8612=item [EBUSY] 8613 8614The read-write lock could not be acquired for writing because it 8615was already locked for reading or writing. 8616 8617=back 8618 8619The 8620I<pthread_rwlock_wrlock()> 8621and 8622I<pthread_rwlock_trywrlock()> 8623functions may fail if: 8624 8625=over 4 8626 8627=item [EINVAL] 8628 8629The value specified by I<rwlock> does not refer to an initialised 8630read-write lock object. 8631 8632=item [EDEADLK] 8633 8634The current thread already owns the read-write lock for writing or 8635reading. 8636 8637=back 8638 8639=head1 EXAMPLES 8640 8641None. 8642 8643=head1 APPLICATION USAGE 8644 8645Similar functions are being developed by IEEE PASC. 8646In keeping with its objective of ensuring that CAE 8647Specifications are fully aligned with formal standards, The Open Group 8648intends to add any new interfaces adopted by an official IEEE standard 8649in this area. 8650 8651Realtime applications may encounter priority inversion when using 8652read-write locks. 8653The problem occurs when a high priority thread "locks" a read-write 8654lock that is about to be "unlocked" by a low priority thread, but 8655the low priority thread is preempted by a medium priority thread. 8656This scenario leads to priority inversion; a high priority thread is 8657blocked by lower priority threads for an unlimited period of time. 8658During system design, realtime programmers must take into account the 8659possibility of this kind of priority inversion. 8660They can deal with it in a number of ways, such as by having critical 8661sections that are guarded by read-write locks execute at a high 8662priority, so that a thread cannot be preempted while executing in its 8663critical section. 8664 8665=head1 FUTURE DIRECTIONS 8666 8667None. 8668 8669=head1 SEE ALSO 8670 8671I<<pthread.h>>, 8672I<pthread_rwlock_init()>, 8673I<pthread_rwlock_unlock()>, 8674I<pthread_rwlockattr_init()>, 8675I<pthread_rwlock_rdlock()>. 8676 8677=head1 ______________________________________________________________________ 8678 8679=head1 NAME 8680 8681B<pthread_rwlockattr_init,> B<pthread_rwlockattr_destroy> 8682- initialise and destroy read-write lock attributes object 8683 8684=head1 SYNOPSIS 8685 8686#include <pthread.h> 8687 8688int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>); 8689int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>); 8690 8691=head1 DESCRIPTION 8692 8693The function 8694I<pthread_rwlockattr_init()> 8695initialises a read-write 8696lock attributes object I<attr> with the default 8697value for all of the attributes defined by the implementation. 8698 8699Results are undefined if 8700I<pthread_rwlockattr_init()> 8701is called 8702specifying an already initialised read-write lock 8703attributes object. 8704 8705After a read-write lock attributes object has been used to 8706initialise one or more read-write locks, any function 8707affecting the attributes object (including destruction) does not 8708affect any previously initialised read-write locks. 8709 8710The 8711I<pthread_rwlockattr_destroy()> 8712function destroys a read-write 8713lock attributes object. The effect of 8714subsequent use of the object is undefined until the object is 8715re-initialised by another call to 8716I<pthread_rwlockattr_init()>. 8717An implementation may cause 8718I<pthread_rwlockattr_destroy()> 8719to set the object 8720referenced by attr to an invalid value. 8721 8722=head1 RETURN VALUE 8723 8724If successful, the 8725I<pthread_rwlockattr_init()> 8726and 8727I<pthread_rwlockattr_destroy()> 8728functions return zero. 8729Otherwise, an error number is returned to 8730indicate the error. 8731 8732=head1 ERRORS 8733 8734The 8735I<pthread_rwlockattr_init()> 8736function will fail if: 8737 8738=over 4 8739 8740=item [ENOMEM] 8741 8742Insufficient memory exists to initialise the read-write 8743lock attributes object. 8744 8745=back 8746 8747The 8748I<pthread_rwlockattr_destroy()> 8749function may fail if: 8750 8751=over 4 8752 8753=item [EINVAL] 8754 8755The value specified by I<attr> is invalid. 8756 8757=back 8758 8759=head1 EXAMPLES 8760 8761None. 8762 8763=head1 APPLICATION USAGE 8764 8765Similar functions are being developed by IEEE PASC. 8766In keeping with its objective of ensuring that CAE 8767Specifications are fully aligned with formal standards, The Open Group 8768intends to add any new interfaces adopted by an official IEEE standard 8769in this area. 8770 8771=head1 FUTURE DIRECTIONS 8772 8773None. 8774 8775=head1 SEE ALSO 8776 8777I<<pthread.h>>, 8778I<pthread_rwlock_init()>, 8779I<pthread_rwlock_unlock()>, 8780I<pthread_rwlock_wrlock()>, 8781I<pthread_rwlock_rdlock()>, 8782I<pthread_rwlockattr_getpshared()>. 8783 8784=head1 ______________________________________________________________________ 8785 8786=head1 NAME 8787 8788B<pthread_rwlockattr_getpshared,> B<pthread_rwlockattr_setpshared> 8789- get and set process-shared attribute of read-write lock 8790attributes object 8791 8792=head1 SYNOPSIS 8793 8794#include <pthread.h> 8795 8796int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>, 8797int I<*pshared>); 8798int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>, 8799int I<pshared>); 8800 8801=head1 DESCRIPTION 8802 8803The 8804I<process-shared> 8805attribute is set to PTHREAD_PROCESS_SHARED to 8806permit a read-write lock to be operated upon by any thread that 8807has access to the memory where the read-write lock is allocated, 8808even if the read-write lock is allocated 8809in memory that is shared by multiple processes. 8810If the 8811I<process-shared> 8812attribute is PTHREAD_PROCESS_PRIVATE, the 8813read-write lock will only be 8814operated upon by threads created within the same process as the 8815thread that initialised the read-write lock; if 8816threads of differing processes attempt to operate on such a 8817read-write lock, the behaviour is undefined. The 8818default value of the 8819I<process-shared> 8820attribute is PTHREAD_PROCESS_PRIVATE. 8821 8822The 8823I<pthread_rwlockattr_getpshared()> 8824function obtains the value of the 8825I<process-shared> 8826attribute from the initialised attributes object referenced by I<attr>. 8827The 8828I<pthread_rwlockattr_setpshared()> 8829function is used to set the 8830I<process-shared> 8831attribute in an initialised attributes object referenced by attr. 8832 8833=head1 RETURN VALUE 8834 8835If successful, the 8836I<pthread_rwlockattr_setpshared()> 8837function returns zero. 8838Otherwise, an error number is returned to indicate the error. 8839 8840Upon successful completion, the 8841I<pthread_rwlockattr_getpshared()> 8842returns zero and stores the value of the 8843I<process-shared> 8844attribute of I<attr> into the object referenced by the 8845I<pshared> parameter. Otherwise an error number is 8846returned to indicate the error. 8847 8848=head1 ERRORS 8849 8850The 8851I<pthread_rwlockattr_getpshared()> 8852and 8853I<pthread_rwlockattr_setpshared()> 8854functions may fail if: 8855 8856=over 4 8857 8858=item [EINVAL] 8859 8860The value specified by I<attr> is invalid. 8861 8862=back 8863 8864The 8865I<pthread_rwlockattr_setpshared()> 8866function may fail if: 8867 8868=over 4 8869 8870=item [EINVAL] 8871 8872The new value specified for the attribute is outside the range 8873of legal values for 8874that attribute. 8875 8876=back 8877 8878=head1 EXAMPLES 8879 8880None. 8881 8882=head1 APPLICATION USAGE 8883 8884Similar functions are being developed by IEEE PASC. 8885In keeping with its objective of ensuring that CAE 8886Specifications are fully aligned with formal standards, The Open Group 8887intends to add any new interfaces adopted by an official IEEE standard 8888in this area. 8889 8890=head1 FUTURE DIRECTIONS 8891 8892None. 8893 8894=head1 SEE ALSO 8895 8896I<<pthread.h>>, 8897I<pthread_rwlock_init()>, 8898I<pthread_rwlock_unlock()>, 8899I<pthread_rwlock_wrlock()>, 8900I<pthread_rwlock_rdlock()>, 8901I<pthread_rwlockattr_init()>. 8902 8903=head1 ______________________________________________________________________ 8904 8905=head1 NAME 8906 8907B<pthread_rwlockattr_init,> B<pthread_rwlockattr_destroy> 8908- initialise and destroy read-write lock attributes object 8909 8910=head1 SYNOPSIS 8911 8912#include <pthread.h> 8913 8914int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>); 8915int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>); 8916 8917=head1 DESCRIPTION 8918 8919The function 8920I<pthread_rwlockattr_init()> 8921initialises a read-write 8922lock attributes object I<attr> with the default 8923value for all of the attributes defined by the implementation. 8924 8925Results are undefined if 8926I<pthread_rwlockattr_init()> 8927is called 8928specifying an already initialised read-write lock 8929attributes object. 8930 8931After a read-write lock attributes object has been used to 8932initialise one or more read-write locks, any function 8933affecting the attributes object (including destruction) does not 8934affect any previously initialised read-write locks. 8935 8936The 8937I<pthread_rwlockattr_destroy()> 8938function destroys a read-write 8939lock attributes object. The effect of 8940subsequent use of the object is undefined until the object is 8941re-initialised by another call to 8942I<pthread_rwlockattr_init()>. 8943An implementation may cause 8944I<pthread_rwlockattr_destroy()> 8945to set the object 8946referenced by attr to an invalid value. 8947 8948=head1 RETURN VALUE 8949 8950If successful, the 8951I<pthread_rwlockattr_init()> 8952and 8953I<pthread_rwlockattr_destroy()> 8954functions return zero. 8955Otherwise, an error number is returned to 8956indicate the error. 8957 8958=head1 ERRORS 8959 8960The 8961I<pthread_rwlockattr_init()> 8962function will fail if: 8963 8964=over 4 8965 8966=item [ENOMEM] 8967 8968Insufficient memory exists to initialise the read-write 8969lock attributes object. 8970 8971=back 8972 8973The 8974I<pthread_rwlockattr_destroy()> 8975function may fail if: 8976 8977=over 4 8978 8979=item [EINVAL] 8980 8981The value specified by I<attr> is invalid. 8982 8983=back 8984 8985=head1 EXAMPLES 8986 8987None. 8988 8989=head1 APPLICATION USAGE 8990 8991Similar functions are being developed by IEEE PASC. 8992In keeping with its objective of ensuring that CAE 8993Specifications are fully aligned with formal standards, The Open Group 8994intends to add any new interfaces adopted by an official IEEE standard 8995in this area. 8996 8997=head1 FUTURE DIRECTIONS 8998 8999None. 9000 9001=head1 SEE ALSO 9002 9003I<<pthread.h>>, 9004I<pthread_rwlock_init()>, 9005I<pthread_rwlock_unlock()>, 9006I<pthread_rwlock_wrlock()>, 9007I<pthread_rwlock_rdlock()>, 9008I<pthread_rwlockattr_getpshared()>. 9009 9010=head1 ______________________________________________________________________ 9011 9012=head1 NAME 9013 9014B<pthread_rwlockattr_getpshared,> B<pthread_rwlockattr_setpshared> 9015- get and set process-shared attribute of read-write lock 9016attributes object 9017 9018=head1 SYNOPSIS 9019 9020#include <pthread.h> 9021 9022int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>, 9023int I<*pshared>); 9024int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>, 9025int I<pshared>); 9026 9027=head1 DESCRIPTION 9028 9029The 9030I<process-shared> 9031attribute is set to PTHREAD_PROCESS_SHARED to 9032permit a read-write lock to be operated upon by any thread that 9033has access to the memory where the read-write lock is allocated, 9034even if the read-write lock is allocated 9035in memory that is shared by multiple processes. 9036If the 9037I<process-shared> 9038attribute is PTHREAD_PROCESS_PRIVATE, the 9039read-write lock will only be 9040operated upon by threads created within the same process as the 9041thread that initialised the read-write lock; if 9042threads of differing processes attempt to operate on such a 9043read-write lock, the behaviour is undefined. The 9044default value of the 9045I<process-shared> 9046attribute is PTHREAD_PROCESS_PRIVATE. 9047 9048The 9049I<pthread_rwlockattr_getpshared()> 9050function obtains the value of the 9051I<process-shared> 9052attribute from the initialised attributes object referenced by I<attr>. 9053The 9054I<pthread_rwlockattr_setpshared()> 9055function is used to set the 9056I<process-shared> 9057attribute in an initialised attributes object referenced by attr. 9058 9059=head1 RETURN VALUE 9060 9061If successful, the 9062I<pthread_rwlockattr_setpshared()> 9063function returns zero. 9064Otherwise, an error number is returned to indicate the error. 9065 9066Upon successful completion, the 9067I<pthread_rwlockattr_getpshared()> 9068returns zero and stores the value of the 9069I<process-shared> 9070attribute of I<attr> into the object referenced by the 9071I<pshared> parameter. Otherwise an error number is 9072returned to indicate the error. 9073 9074=head1 ERRORS 9075 9076The 9077I<pthread_rwlockattr_getpshared()> 9078and 9079I<pthread_rwlockattr_setpshared()> 9080functions may fail if: 9081 9082=over 4 9083 9084=item [EINVAL] 9085 9086The value specified by I<attr> is invalid. 9087 9088=back 9089 9090The 9091I<pthread_rwlockattr_setpshared()> 9092function may fail if: 9093 9094=over 4 9095 9096=item [EINVAL] 9097 9098The new value specified for the attribute is outside the range 9099of legal values for 9100that attribute. 9101 9102=back 9103 9104=head1 EXAMPLES 9105 9106None. 9107 9108=head1 APPLICATION USAGE 9109 9110Similar functions are being developed by IEEE PASC. 9111In keeping with its objective of ensuring that CAE 9112Specifications are fully aligned with formal standards, The Open Group 9113intends to add any new interfaces adopted by an official IEEE standard 9114in this area. 9115 9116=head1 FUTURE DIRECTIONS 9117 9118None. 9119 9120=head1 SEE ALSO 9121 9122I<<pthread.h>>, 9123I<pthread_rwlock_init()>, 9124I<pthread_rwlock_unlock()>, 9125I<pthread_rwlock_wrlock()>, 9126I<pthread_rwlock_rdlock()>, 9127I<pthread_rwlockattr_init()>. 9128 9129=head1 ______________________________________________________________________ 9130 9131=head1 NAME 9132 9133B<pthread_self> - get calling thread's ID 9134 9135=head1 SYNOPSIS 9136 9137#include <pthread.h> 9138 9139pthread_t pthread_self(void); 9140 9141=head1 DESCRIPTION 9142 9143The 9144I<pthread_self()> 9145function returns the thread ID of the calling thread. 9146 9147=head1 RETURN VALUE 9148 9149See DESCRIPTION above. 9150 9151=head1 ERRORS 9152 9153No errors are defined. 9154 9155The 9156I<pthread_self()> 9157function will not return an error code of [EINTR]. 9158 9159=head1 EXAMPLES 9160 9161None. 9162 9163=head1 APPLICATION USAGE 9164 9165None. 9166 9167=head1 FUTURE DIRECTIONS 9168 9169None. 9170 9171=head1 SEE ALSO 9172 9173I<pthread_create()>, 9174I<pthread_equal()>, 9175I<<pthread.h>>. 9176 9177=head1 ______________________________________________________________________ 9178 9179=head1 NAME 9180 9181B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel> 9182- set cancelability state 9183 9184=head1 SYNOPSIS 9185 9186#include <pthread.h> 9187 9188int pthread_setcancelstate(int I<state>, int *I<oldstate>); 9189int pthread_setcanceltype(int I<type>, int *I<oldtype>); 9190void pthread_testcancel(void); 9191 9192=head1 DESCRIPTION 9193 9194The 9195I<pthread_setcancelstate()> 9196function atomically both sets the calling thread's cancelability 9197state to the indicated 9198I<state> 9199and returns the previous cancelability state 9200at the location referenced by I<oldstate>. 9201Legal values for 9202I<state> 9203are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. 9204 9205The 9206I<pthread_setcanceltype()> 9207function atomically both sets the calling thread's cancelability 9208type to the indicated 9209I<type> 9210and returns the previous cancelability type 9211at the location referenced by I<oldtype>. 9212Legal values for 9213I<type> 9214are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. 9215 9216The cancelability state and type of any newly 9217created threads, including the thread in which 9218I<main()> 9219was first invoked, 9220are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED 9221respectively. 9222 9223The 9224I<pthread_testcancel()> 9225function creates a cancellation point in the calling thread. 9226The 9227I<pthread_testcancel()> 9228function has no effect if cancelability is disabled. 9229 9230=head1 RETURN VALUE 9231 9232If successful, the 9233I<pthread_setcancelstate()> 9234and 9235I<pthread_setcanceltype()> 9236functions return zero. 9237Otherwise, an error number is returned to indicate the error. 9238 9239=head1 ERRORS 9240 9241The 9242I<pthread_setcancelstate()> 9243function may fail if: 9244 9245=over 4 9246 9247=item [EINVAL] 9248 9249The specified state is not 9250PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. 9251 9252=back 9253 9254The 9255I<pthread_setcanceltype()> 9256function may fail if: 9257 9258=over 4 9259 9260=item [EINVAL] 9261 9262The specified type is not PTHREAD_CANCEL_DEFERRED 9263or PTHREAD_CANCEL_ASYNCHRONOUS. 9264 9265=back 9266 9267These functions will not return an error code of [EINTR]. 9268 9269=head1 EXAMPLES 9270 9271None. 9272 9273=head1 APPLICATION USAGE 9274 9275None. 9276 9277=head1 FUTURE DIRECTIONS 9278 9279None. 9280 9281=head1 SEE ALSO 9282 9283I<pthread_cancel()>, 9284I<<pthread.h>>. 9285 9286 9287=head1 ______________________________________________________________________ 9288 9289=head1 NAME 9290 9291B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel> 9292- set cancelability state 9293 9294=head1 SYNOPSIS 9295 9296#include <pthread.h> 9297 9298int pthread_setcancelstate(int I<state>, int *I<oldstate>); 9299int pthread_setcanceltype(int I<type>, int *I<oldtype>); 9300void pthread_testcancel(void); 9301 9302=head1 DESCRIPTION 9303 9304The 9305I<pthread_setcancelstate()> 9306function atomically both sets the calling thread's cancelability 9307state to the indicated 9308I<state> 9309and returns the previous cancelability state 9310at the location referenced by I<oldstate>. 9311Legal values for 9312I<state> 9313are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. 9314 9315The 9316I<pthread_setcanceltype()> 9317function atomically both sets the calling thread's cancelability 9318type to the indicated 9319I<type> 9320and returns the previous cancelability type 9321at the location referenced by I<oldtype>. 9322Legal values for 9323I<type> 9324are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. 9325 9326The cancelability state and type of any newly 9327created threads, including the thread in which 9328I<main()> 9329was first invoked, 9330are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED 9331respectively. 9332 9333The 9334I<pthread_testcancel()> 9335function creates a cancellation point in the calling thread. 9336The 9337I<pthread_testcancel()> 9338function has no effect if cancelability is disabled. 9339 9340=head1 RETURN VALUE 9341 9342If successful, the 9343I<pthread_setcancelstate()> 9344and 9345I<pthread_setcanceltype()> 9346functions return zero. 9347Otherwise, an error number is returned to indicate the error. 9348 9349=head1 ERRORS 9350 9351The 9352I<pthread_setcancelstate()> 9353function may fail if: 9354 9355=over 4 9356 9357=item [EINVAL] 9358 9359The specified state is not 9360PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. 9361 9362=back 9363 9364The 9365I<pthread_setcanceltype()> 9366function may fail if: 9367 9368=over 4 9369 9370=item [EINVAL] 9371 9372The specified type is not PTHREAD_CANCEL_DEFERRED 9373or PTHREAD_CANCEL_ASYNCHRONOUS. 9374 9375=back 9376 9377These functions will not return an error code of [EINTR]. 9378 9379=head1 EXAMPLES 9380 9381None. 9382 9383=head1 APPLICATION USAGE 9384 9385None. 9386 9387=head1 FUTURE DIRECTIONS 9388 9389None. 9390 9391=head1 SEE ALSO 9392 9393I<pthread_cancel()>, 9394I<<pthread.h>>. 9395 9396 9397=head1 ______________________________________________________________________ 9398 9399=head1 NAME 9400 9401B<pthread_setconcurrency> - get or set level of concurrency 9402 9403=head1 SYNOPSIS 9404 9405#include <pthread.h> 9406 9407int pthread_setconcurrency(int I<new_level>); 9408 9409=head1 DESCRIPTION 9410 9411Refer to 9412I<pthread_getconcurrency()>. 9413 9414=head1 ______________________________________________________________________ 9415 9416=head1 NAME 9417 9418B<pthread_getschedparam,> B<pthread_setschedparam> 9419- dynamic thread scheduling parameters access 9420(B<REALTIME THREADS>) 9421 9422=head1 SYNOPSIS 9423 9424#include <pthread.h> 9425 9426int pthread_getschedparam(pthread_t I<thread>, int *I<policy>, 9427struct sched_param *I<param>); 9428int pthread_setschedparam(pthread_t I<thread>, int I<policy>, 9429const struct sched_param *I<param>); 9430 9431=head1 DESCRIPTION 9432 9433The 9434I<pthread_getschedparam()> 9435and 9436I<pthread_setschedparam()> 9437allow the scheduling policy and scheduling parameters of individual threads 9438within a multi-threaded process to be retrieved and set. 9439For SCHED_FIFO and SCHED_RR, 9440the only required member of the 9441B<sched_param> 9442structure is the priority 9443I<sched_priority>. 9444For SCHED_OTHER, 9445the affected scheduling parameters are implementation-dependent. 9446 9447The 9448I<pthread_getschedparam()> 9449function retrieves the scheduling policy and scheduling parameters 9450for the thread whose thread ID is given by 9451I<thread> 9452and stores those values in 9453I<policy> 9454and 9455I<param>, 9456respectively. 9457The priority value returned from 9458I<pthread_getschedparam()> 9459is the value specified by the most recent 9460I<pthread_setschedparam()> 9461or 9462I<pthread_create()> 9463call affecting the target thread, 9464and reflects any temporary adjustments to its priority 9465as a result of any priority inheritance or ceiling functions. 9466The 9467I<pthread_setschedparam()> 9468function sets the scheduling policy 9469and associated scheduling parameters for the thread whose 9470thread ID is given by 9471I<thread> 9472to the policy and associated parameters provided in 9473I<policy> 9474and 9475I<param>, 9476respectively. 9477 9478The 9479I<policy> 9480parameter may have the value SCHED_OTHER, 9481that has implementation-dependent scheduling parameters, 9482SCHED_FIFO or SCHED_RR, 9483that have the single scheduling parameter, 9484I<priority.> 9485 9486If the 9487I<pthread_setschedparam()> 9488function fails, no scheduling parameters will be changed 9489for the target thread. 9490 9491=head1 RETURN VALUE 9492 9493If successful, the 9494I<pthread_getschedparam()> 9495and 9496I<pthread_setschedparam()> 9497functions return zero. 9498Otherwise, an error number is returned to indicate the error. 9499 9500=head1 ERRORS 9501 9502The 9503I<pthread_getschedparam()> 9504and 9505I<pthread_setschedparam()> 9506functions will fail if: 9507 9508=over 4 9509 9510=item [ENOSYS] 9511 9512The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the 9513implementation does not support the function. 9514 9515=back 9516 9517The 9518I<pthread_getschedparam()> 9519function may fail if: 9520 9521=over 4 9522 9523=item [ESRCH] 9524 9525The value specified by 9526I<thread> 9527does not refer to a existing thread. 9528 9529=back 9530 9531The 9532I<pthread_setschedparam()> 9533function may fail if: 9534 9535=over 4 9536 9537=item [EINVAL] 9538 9539The value specified by 9540I<policy> 9541or one of the scheduling parameters associated with 9542the scheduling policy 9543I<policy> 9544is invalid. 9545 9546=item [ENOTSUP] 9547 9548An attempt was made to set the policy or scheduling parameters to 9549an unsupported value. 9550 9551=item [EPERM] 9552 9553The caller does not have the appropriate permission to set 9554either the scheduling parameters or the scheduling policy of the 9555specified thread. 9556 9557=item [EPERM] 9558 9559The implementation does not allow the application to modify 9560one of the parameters to the value specified. 9561 9562=item [ESRCH] 9563 9564The value specified by 9565I<thread> 9566does not refer to a existing thread. 9567 9568=back 9569 9570=head1 EXAMPLES 9571 9572None. 9573 9574=head1 APPLICATION USAGE 9575 9576None. 9577 9578=head1 FUTURE DIRECTIONS 9579 9580None. 9581 9582=head1 SEE ALSO 9583 9584I<sched_setparam()>, 9585I<sched_getparam()>, 9586I<sched_setscheduler()>, 9587I<sched_getscheduler()>, 9588I<<pthread.h>>, 9589I<<sched.h>>. 9590 9591=head1 ______________________________________________________________________ 9592 9593=head1 NAME 9594 9595B<pthread_setspecific,> B<pthread_getspecific> - thread-specific data management 9596 9597=head1 SYNOPSIS 9598 9599#include <pthread.h> 9600 9601int pthread_setspecific(pthread_key_t I<key>, const void *I<value>); 9602void *pthread_getspecific(pthread_key_t I<key>); 9603 9604=head1 DESCRIPTION 9605 9606The 9607I<pthread_setspecific()> 9608function associates a thread-specific 9609I<value> 9610with a 9611I<key> 9612obtained via a previous call to 9613I<pthread_key_create()>. 9614Different threads may bind different values to the same key. 9615These values are typically pointers to blocks of dynamically allocated memory 9616that have been reserved for use by the calling thread. 9617 9618The 9619I<pthread_getspecific()> 9620function returns the value currently bound to the specified 9621I<key> 9622on behalf of the calling thread. 9623 9624The effect of calling 9625I<pthread_setspecific()> 9626or 9627I<pthread_getspecific()> 9628with a 9629I<key> 9630value not obtained from 9631I<pthread_key_create()> 9632or after 9633I<key> 9634has been deleted with 9635I<pthread_key_delete()> 9636is undefined. 9637 9638Both 9639I<pthread_setspecific()> 9640and 9641I<pthread_getspecific()> 9642may be called from a thread-specific data destructor function. 9643However, calling 9644I<pthread_setspecific()> 9645from a destructor may result in lost storage or infinite loops. 9646 9647Both functions may be implemented as macros. 9648 9649=head1 RETURN VALUE 9650 9651The function 9652I<pthread_getspecific()> 9653returns the thread-specific data value 9654associated with the given 9655I<key>. 9656If no thread-specific data value is associated with 9657I<key>, 9658then the value NULL is returned. 9659 9660If successful, the 9661I<pthread_setspecific()> 9662function returns zero. 9663Otherwise, an error number is returned to indicate the error. 9664 9665=head1 ERRORS 9666 9667The 9668I<pthread_setspecific()> 9669function will fail if: 9670 9671=over 4 9672 9673=item [ENOMEM] 9674 9675Insufficient memory exists to associate the value with the key. 9676 9677=back 9678 9679The 9680I<pthread_setspecific()> 9681function may fail if: 9682 9683=over 4 9684 9685=item [EINVAL] 9686 9687The key value is invalid. 9688 9689=back 9690 9691No errors are returned from 9692I<pthread_getspecific()>. 9693 9694These functions will not return an error code of [EINTR]. 9695 9696=head1 EXAMPLES 9697 9698None. 9699 9700=head1 APPLICATION USAGE 9701 9702None. 9703 9704=head1 FUTURE DIRECTIONS 9705 9706None. 9707 9708=head1 SEE ALSO 9709 9710I<pthread_key_create()>, 9711I<<pthread.h>>. 9712 9713 9714=head1 ______________________________________________________________________ 9715 9716=head1 NAME 9717 9718B<pthread_sigmask> - examine and change blocked signals 9719 9720=head1 SYNOPSIS 9721 9722#include <signal.h> 9723 9724int pthread_sigmask(int I<how>, const sigset_t *I<set>, sigset_t *I<oset>); 9725 9726=head1 DESCRIPTION 9727 9728Refer to 9729I<sigprocmask()>. 9730 9731=head1 ______________________________________________________________________ 9732 9733=head1 NAME 9734 9735B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel> 9736- set cancelability state 9737 9738=head1 SYNOPSIS 9739 9740#include <pthread.h> 9741 9742int pthread_setcancelstate(int I<state>, int *I<oldstate>); 9743int pthread_setcanceltype(int I<type>, int *I<oldtype>); 9744void pthread_testcancel(void); 9745 9746=head1 DESCRIPTION 9747 9748The 9749I<pthread_setcancelstate()> 9750function atomically both sets the calling thread's cancelability 9751state to the indicated 9752I<state> 9753and returns the previous cancelability state 9754at the location referenced by I<oldstate>. 9755Legal values for 9756I<state> 9757are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. 9758 9759The 9760I<pthread_setcanceltype()> 9761function atomically both sets the calling thread's cancelability 9762type to the indicated 9763I<type> 9764and returns the previous cancelability type 9765at the location referenced by I<oldtype>. 9766Legal values for 9767I<type> 9768are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. 9769 9770The cancelability state and type of any newly 9771created threads, including the thread in which 9772I<main()> 9773was first invoked, 9774are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED 9775respectively. 9776 9777The 9778I<pthread_testcancel()> 9779function creates a cancellation point in the calling thread. 9780The 9781I<pthread_testcancel()> 9782function has no effect if cancelability is disabled. 9783 9784=head1 RETURN VALUE 9785 9786If successful, the 9787I<pthread_setcancelstate()> 9788and 9789I<pthread_setcanceltype()> 9790functions return zero. 9791Otherwise, an error number is returned to indicate the error. 9792 9793=head1 ERRORS 9794 9795The 9796I<pthread_setcancelstate()> 9797function may fail if: 9798 9799=over 4 9800 9801=item [EINVAL] 9802 9803The specified state is not 9804PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. 9805 9806=back 9807 9808The 9809I<pthread_setcanceltype()> 9810function may fail if: 9811 9812=over 4 9813 9814=item [EINVAL] 9815 9816The specified type is not PTHREAD_CANCEL_DEFERRED 9817or PTHREAD_CANCEL_ASYNCHRONOUS. 9818 9819=back 9820 9821These functions will not return an error code of [EINTR]. 9822 9823=head1 EXAMPLES 9824 9825None. 9826 9827=head1 APPLICATION USAGE 9828 9829None. 9830 9831=head1 FUTURE DIRECTIONS 9832 9833None. 9834 9835=head1 SEE ALSO 9836 9837I<pthread_cancel()>, 9838I<<pthread.h>>. 9839 9840=cut 9841 9842