source: rtems/doc/posix_users/thread.t @ c4dddee

4.104.114.84.95
Last change on this file since c4dddee was c4dddee, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 19, 1998 at 4:06:46 PM

Major update/merge of POSIX manual.

  • Property mode set to 100644
File size: 15.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Thread Manager
10
11@section Introduction
12
13The thread manager ...
14
15The directives provided by the thread manager are:
16
17@itemize @bullet
18@item @code{pthread_attr_init} -
19@item @code{pthread_attr_destroy} -
20@item @code{pthread_attr_setdetachstate} -
21@item @code{pthread_attr_getdetachstate} -
22@item @code{pthread_attr_setstacksize} -
23@item @code{pthread_attr_getstacksize} -
24@item @code{pthread_attr_setstackaddr} -
25@item @code{pthread_attr_getstackaddr} -
26@item @code{pthread_attr_setscope} -
27@item @code{pthread_attr_getscope} -
28@item @code{pthread_attr_setinheritsched} -
29@item @code{pthread_attr_getinheritsched} -
30@item @code{pthread_attr_setschedpolicy} -
31@item @code{pthread_attr_getschedpolicy} -
32@item @code{pthread_attr_setschedparam} -
33@item @code{pthread_attr_getschedparam} -
34@item @code{pthread_create} -
35@item @code{pthread_exit} -
36@item @code{pthread_detach} -
37@item @code{pthread_join} -
38@item @code{pthread_self} -
39@item @code{pthread_equal} -
40@item @code{pthread_once} -
41@item @code{pthread_setschedparam} -
42@item @code{pthread_getschedparam} -
43@end itemize
44
45@section Background
46
47@subsection Thread Attributes
48
49Thread attributes are utilized only at thread creation time.
50
51@table @b
52@item stack address
53is the address of the optionally user specified stack area for this thread.
54If this value is NULL, then RTEMS allocates the memory for the thread stack
55from the RTEMS Workspace Area.  Otherwise, this is the user specified
56address for the memory to be used for the thread's stack.  Each thread must
57have a distinct stack area.  Each processor family has different alignment
58rules which should be followed.
59
60@item stack size
61is the minimum desired size for this thread's stack area.
62If the size of this area as specified by the stack size attribute
63is smaller than the minimum for this processor family and the stack
64is not user specified, then RTEMS will automatically allocate a
65stack of the minimum size for this processor family.
66
67@item contention scope
68specifies the scheduling contention scope.  RTEMS only supports the
69PTHREAD_SCOPE_PROCESS scheduling contention scope.
70
71@item scheduling inheritance
72specifies whether a user specified or the scheduling policy and
73parameters of the currently executing thread are to be used.  When
74this is PTHREAD_INHERIT_SCHED, then the scheduling policy and
75parameters of the currently executing thread are inherited by
76the newly created thread.
77
78@item scheduling policy and parameters
79specify the manner in which the thread will contend for the processor.
80The scheduling parameters are interpreted based on the specified policy.
81All policies utilize the thread priority parameter.
82
83@end table
84
85@section Operations
86
87There is currently no text in this section.
88
89@section Directives
90
91This section details the thread manager's directives.
92A subsection is dedicated to each of this manager's directives
93and describes the calling sequence, related constants, usage,
94and status codes.
95
96@page
97@subsection pthread_attr_init
98
99@subheading CALLING SEQUENCE:
100
101
102@example
103#include <pthread.h>
104
105int pthread_attr_init(
106  pthread_attr_t  *attr
107);
108@end example
109
110@subheading STATUS CODES:
111
112@table @b
113@item EINVAL
114The attribute pointer argument is invalid.
115
116@end table
117
118@subheading DESCRIPTION:
119
120@subheading NOTES:
121
122@page
123@subsection pthread_attr_destroy
124
125@subheading CALLING SEQUENCE:
126
127@example
128#include <pthread.h>
129 
130int pthread_attr_destroy(
131  pthread_attr_t  *attr
132);
133@end example
134
135@subheading STATUS CODES:
136 
137@table @b
138@item EINVAL
139The attribute pointer argument is invalid.
140
141@item EINVAL
142The attribute set is not initialized.
143 
144@end table
145 
146@subheading DESCRIPTION:
147
148@subheading NOTES:
149
150@page
151@subsection pthread_attr_setdetachstate
152
153@subheading CALLING SEQUENCE:
154
155@example
156#include <pthread.h>
157 
158int pthread_attr_setdetachstate(
159  pthread_attr_t  *attr,
160  int              detachstate
161);
162@end example
163
164@subheading STATUS CODES:
165 
166@table @b
167@item EINVAL
168The attribute pointer argument is invalid.
169
170@item EINVAL
171The attribute set is not initialized.
172 
173@item EINVAL
174The detachstate argument is invalid.
175 
176@end table
177
178@subheading DESCRIPTION:
179
180@subheading NOTES:
181
182@page
183@subsection pthread_attr_getdetachstate
184
185@subheading CALLING SEQUENCE:
186
187@example
188#include <pthread.h>
189 
190int pthread_attr_getdetachstate(
191  const pthread_attr_t  *attr,
192  int                   *detachstate
193);
194@end example
195
196@subheading STATUS CODES:
197 
198@table @b
199@item EINVAL
200The attribute pointer argument is invalid.
201
202@item EINVAL
203The attribute set is not initialized.
204 
205@item EINVAL
206The detatchstate pointer argument is invalid.
207
208@end table
209 
210@subheading DESCRIPTION:
211
212@subheading NOTES:
213
214@page
215@subsection pthread_attr_setstacksize
216
217@subheading CALLING SEQUENCE:
218
219@example
220#include <pthread.h>
221 
222int pthread_attr_setstacksize(
223  pthread_attr_t  *attr,
224  size_t           stacksize
225);
226@end example
227
228@subheading STATUS CODES:
229 
230@table @b
231@item EINVAL
232The attribute pointer argument is invalid.
233
234@item EINVAL
235The attribute set is not initialized.
236 
237@end table
238 
239@subheading DESCRIPTION:
240
241@subheading NOTES:
242
243If the specified stacksize is below the minimum required for this CPU, then
244the stacksize will be set to the minimum for this CPU.
245
246@page
247@subsection pthread_attr_getstacksize
248
249@subheading CALLING SEQUENCE:
250
251@example
252#include <pthread.h>
253
254int pthread_attr_getstacksize(
255  const pthread_attr_t  *attr,
256  size_t                *stacksize
257);
258@end example
259
260@subheading STATUS CODES:
261 
262@table @b
263@item EINVAL
264The attribute pointer argument is invalid.
265
266@item EINVAL
267The attribute set is not initialized.
268 
269@item EINVAL
270The stacksize pointer argument is invalid.
271
272@end table
273 
274@subheading DESCRIPTION:
275
276@subheading NOTES:
277
278@page
279@subsection pthread_attr_setstackaddr
280
281@subheading CALLING SEQUENCE:
282
283@example
284#include <pthread.h>
285 
286int pthread_attr_setstackaddr(
287  pthread_attr_t  *attr,
288  void            *stackaddr
289);
290@end example
291
292@subheading STATUS CODES:
293 
294@table @b
295@item EINVAL
296The attribute pointer argument is invalid.
297
298@item EINVAL
299The attribute set is not initialized.
300
301@end table
302 
303@subheading DESCRIPTION:
304
305@subheading NOTES:
306
307@page
308@subsection pthread_attr_getstackaddr
309
310@subheading CALLING SEQUENCE:
311
312@example
313#include <pthread.h>
314
315int pthread_attr_getstackaddr(
316  const pthread_attr_t  *attr,
317  void                 **stackaddr
318);
319@end example
320
321@subheading STATUS CODES:
322 
323@table @b
324@item EINVAL
325The attribute pointer argument is invalid.
326
327@item EINVAL
328The attribute set is not initialized.
329 
330@item EINVAL
331The stackaddr pointer argument is invalid.
332
333@end table
334 
335@subheading DESCRIPTION:
336
337@subheading NOTES:
338
339@page
340@subsection pthread_attr_setscope
341
342@subheading CALLING SEQUENCE:
343
344@example
345#include <pthread.h>
346
347int pthread_attr_setscope(
348  pthread_attr_t  *attr,
349  int              contentionscope
350);
351@end example
352
353@subheading STATUS CODES:
354
355@table @b
356@item EINVAL
357The attribute pointer argument is invalid.
358
359@item EINVAL
360The attribute set is not initialized.
361
362@item EINVAL
363The contention scope specified is not valid.
364
365@item ENOTSUP
366The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported.
367
368@end table
369
370@subheading DESCRIPTION:
371
372@subheading NOTES:
373
374@page
375@subsection pthread_attr_getscope
376
377@subheading CALLING SEQUENCE:
378
379@example
380#include <pthread.h>
381
382int pthread_attr_getscope(
383  const pthread_attr_t  *attr,
384  int                   *contentionscope
385);
386@end example
387
388@subheading STATUS CODES:
389
390@table @b
391@item EINVAL
392The attribute pointer argument is invalid.
393
394@item EINVAL
395The attribute set is not initialized.
396
397@item EINVAL
398The contentionscope pointer argument is invalid.
399
400@end table
401
402@subheading DESCRIPTION:
403
404@subheading NOTES:
405
406@page
407@subsection pthread_attr_setinheritsched
408
409@subheading CALLING SEQUENCE:
410
411@example
412#include <pthread.h>
413
414int pthread_attr_setinheritsched(
415  pthread_attr_t  *attr,
416  int              inheritsched
417);
418@end example
419
420@subheading STATUS CODES:
421
422@table @b
423@item EINVAL
424The attribute pointer argument is invalid.
425
426@item EINVAL
427The attribute set is not initialized.
428
429@item EINVAL
430The specified scheduler inheritance argument is invalid.
431
432@end table
433
434@subheading DESCRIPTION:
435
436@subheading NOTES:
437
438@page
439@subsection pthread_attr_getinheritsched
440
441@subheading CALLING SEQUENCE:
442
443@example
444#include <pthread.h>
445
446int pthread_attr_getinheritsched(
447  const pthread_attr_t  *attr,
448  int                   *inheritsched
449);
450@end example
451
452@subheading STATUS CODES:
453@table @b
454@item EINVAL
455The attribute pointer argument is invalid.
456
457@item EINVAL
458The attribute set is not initialized.
459
460@item EINVAL
461The inheritsched pointer argument is invalid.
462
463@end table
464
465@subheading DESCRIPTION:
466
467@subheading NOTES:
468
469@page
470@subsection pthread_attr_setschedpolicy
471
472@subheading CALLING SEQUENCE:
473
474@example
475#include <pthread.h>
476
477int pthread_attr_setschedpolicy(
478  pthread_attr_t  *attr,
479  int              policy
480);
481@end example
482
483@subheading STATUS CODES:
484@table @b
485@item EINVAL
486The attribute pointer argument is invalid.
487
488@item EINVAL
489The attribute set is not initialized.
490 
491@item ENOTSUP
492The specified scheduler policy argument is invalid.
493
494@end table
495
496@subheading DESCRIPTION:
497
498@subheading NOTES:
499
500@page
501@subsection pthread_attr_getschedpolicy
502
503@subheading CALLING SEQUENCE:
504
505@example
506#include <pthread.h>
507
508int pthread_attr_getschedpolicy(
509  const pthread_attr_t  *attr,
510  int                   *policy
511);
512@end example
513
514@subheading STATUS CODES:
515@table @b
516@item EINVAL
517The attribute pointer argument is invalid.
518
519@item EINVAL
520The attribute set is not initialized.
521
522@item EINVAL
523The specified scheduler policy argument pointer is invalid.
524
525@end table
526
527@subheading DESCRIPTION:
528
529@subheading NOTES:
530
531@page
532@subsection pthread_attr_setschedparam
533
534@subheading CALLING SEQUENCE:
535
536@example
537#include <pthread.h>
538
539int pthread_attr_setschedparam(
540  pthread_attr_t            *attr,
541  const struct sched_param   param
542);
543@end example
544
545@subheading STATUS CODES:
546@table @b
547@item EINVAL
548The attribute pointer argument is invalid.
549
550@item EINVAL
551The attribute set is not initialized.
552 
553@item EINVAL
554The specified scheduler parameter argument is invalid.
555
556@end table
557
558@subheading DESCRIPTION:
559
560@subheading NOTES:
561
562@page
563@subsection pthread_attr_getschedparam
564
565@subheading CALLING SEQUENCE:
566
567@example
568#include <pthread.h>
569
570int pthread_attr_getschedparam(
571  const pthread_attr_t  *attr,
572  struct sched_param    *param
573);
574@end example
575
576@subheading STATUS CODES:
577@table @b
578@item EINVAL
579The attribute pointer argument is invalid.
580
581@item EINVAL
582The attribute set is not initialized.
583
584@item EINVAL
585The specified scheduler parameter argument pointer is invalid.
586
587@end table
588
589@subheading DESCRIPTION:
590
591@subheading NOTES:
592
593@page
594@subsection pthread_create
595
596@subheading CALLING SEQUENCE:
597
598@example
599#include <pthread.h>
600
601int pthread_create(
602  pthread_t             *thread,
603  const pthread_attr_t  *attr,
604  void                 (*start_routine)( void * ),
605  void                  *arg
606);
607@end example
608
609@subheading STATUS CODES:
610
611@table @b
612
613@item EINVAL
614The attribute set is not initialized.
615
616@item EINVAL
617The user specified a stack address and the size of the area was not
618large enough to meet this processor's minimum stack requirements.
619
620@item EINVAL
621The specified scheduler inheritance policy was invalid.
622
623@item ENOTSUP
624The specified contention scope was PTHREAD_SCOPE_PROCESS.
625
626@item EINVAL
627The specified thread priority was invalid.
628
629@item EINVAL
630The specified scheduling policy was invalid.
631
632@item EINVAL
633The scheduling policy was SCHED_SPORADIC and the specified replenishment
634period is less than the initial budget.
635
636@item EINVAL
637The scheduling policy was SCHED_SPORADIC and the specified low priority
638is invalid.
639
640@item EAGAIN
641The system lacked the necessary resources to create another thread, or the
642self imposed limit on the total number of threads in a process
643PTHREAD_THREAD_MAX would be exceeded.
644 
645@item EINVAL
646Invalid argument passed.
647
648@end table
649 
650@subheading DESCRIPTION:
651
652@subheading NOTES:
653
654@page
655@subsection pthread_exit
656
657@subheading CALLING SEQUENCE:
658
659@example
660#include <pthread.h>
661
662void pthread_exit(
663  void   *status
664);
665@end example
666
667@subheading STATUS CODES:
668@table @b
669@item NONE
670 
671@end table
672
673@subheading DESCRIPTION:
674
675@subheading NOTES:
676
677@page
678@subsection pthread_detach
679
680@subheading CALLING SEQUENCE:
681
682@example
683#include <pthread.h>
684
685int pthread_detach(
686  pthread_t   thread
687);
688@end example
689
690@subheading STATUS CODES:
691@table @b
692@item ESRCH
693The thread specified is invalid.
694 
695@item EINVAL
696The thread specified is not a joinable thread.
697 
698@end table
699
700@subheading DESCRIPTION:
701
702@subheading NOTES:
703
704If any threads have previously joined with the specified thread, then they
705will remain joined with that thread.  Any subsequent calls to pthread_join
706on the specified thread will fail.
707
708@page
709@subsection pthread_join
710
711@subheading CALLING SEQUENCE:
712
713@example
714#include <pthread.h>
715
716int pthread_join(
717  pthread_t   thread,
718  void      **value_ptr
719);
720@end example
721
722@subheading STATUS CODES:
723@table @b
724@item ESRCH
725The thread specified is invalid.
726 
727@item EINVAL
728The thread specified is not a joinable thread.
729 
730@item EDEADLK
731A deadlock was detected or thread is the calling thread.
732 
733@end table
734
735@subheading DESCRIPTION:
736
737@subheading NOTES:
738
739If any threads have previously joined with the specified thread, then they
740will remain joined with that thread.  Any subsequent calls to pthread_join
741on the specified thread will fail.
742
743If value_ptr is NULL, then no value is returned.
744
745@page
746@subsection pthread_self
747
748@subheading CALLING SEQUENCE:
749
750@example
751#include <pthread.h>
752
753pthread_t pthread_self( void );
754@end example
755
756@subheading STATUS CODES:
757
758This routine returns the id of the calling thread.
759
760@subheading DESCRIPTION:
761
762@subheading NOTES:
763
764@page
765@subsection pthread_equal
766
767@subheading CALLING SEQUENCE:
768
769@example
770#include <pthread.h>
771
772int pthread_equal(
773  pthread_t  t1,
774  pthread_t  t2
775);
776@end example
777
778@subheading STATUS CODES:
779
780@table @b
781@item zero
782The thread ids are not equal.
783 
784@item non-zero
785The thread ids are equal.
786 
787@end table
788
789@subheading DESCRIPTION:
790
791@subheading NOTES:
792
793The behavior is undefined if the thread IDs are not valid.
794
795@page
796@subsection pthread_once
797
798@subheading CALLING SEQUENCE:
799
800@example
801#include <pthread.h>
802
803pthread_once_t once_control = PTHREAD_ONCE_INIT;
804
805int pthread_once(
806  pthread_once_t  *once_control,
807  void           (*init_routine)(void)
808);
809@end example
810
811@subheading STATUS CODES:
812
813NONE
814
815@subheading DESCRIPTION:
816
817@subheading NOTES:
818
819@page
820@subsection pthread_setschedparam
821
822@subheading CALLING SEQUENCE:
823
824@example
825#include <pthread.h>
826
827int pthread_setschedparam(
828  pthread_t           thread,
829  int                 policy,
830  struct sched_param *param
831);
832@end example
833
834@subheading STATUS CODES:
835
836@table @b
837@item EINVAL
838The scheduling parameters indicated by the parameter param is invalid.
839
840@item EINVAL
841The value specified by policy is invalid.
842
843@item EINVAL
844The scheduling policy was SCHED_SPORADIC and the specified replenishment
845period is less than the initial budget.
846
847@item EINVAL
848The scheduling policy was SCHED_SPORADIC and the specified low priority
849is invalid.
850
851@item ESRCH
852The thread indicated was invalid.
853
854@end table
855
856@subheading DESCRIPTION:
857
858@subheading NOTES:
859
860@page
861@subsection pthread_getschedparam
862
863@subheading CALLING SEQUENCE:
864
865@example
866#include <pthread.h>
867
868int pthread_getschedparam(
869  pthread_t           thread,
870  int                *policy,
871  struct sched_param *param
872);
873@end example
874
875@subheading STATUS CODES:
876 
877@table @b
878@item EINVAL
879The policy pointer argument is invalid.
880
881@item EINVAL
882The scheduling parameters pointer argument is invalid.
883
884@item ESRCH
885The thread indicated by the parameter thread is invalid.
886 
887@end table
888
889@subheading DESCRIPTION:
890
891@subheading NOTES:
892
Note: See TracBrowser for help on using the repository browser.