[apple/libc.git] / pthreads / pthread_attr_set_getdetachstate.3

.\" Copyright (c) 2004-2007 Apple Inc. All rights reserved.
.Dd December 31, 2007
.Dt PTHREAD_ATTR 3
.Os
.Sh NAME
.Nm pthread_attr_getdetachstate ,
.Nm pthread_attr_setdetachstate
.Nd thread attribute operations
.Sh SYNOPSIS
.Fd #include <pthread.h>
.Ft int
.Fo pthread_attr_getdetachstate
.Fa "const pthread_attr_t *attr"
.Fa "int *detachstate"
.Fc
.Ft int
.Fo pthread_attr_setdetachstate
.Fa "pthread_attr_t *attr"
.Fa "int detachstate"
.Fc
.Sh DESCRIPTION
Thread attributes are used to specify parameters to
.Fn pthread_create .
One attribute object can be used in multiple calls to
.Fn pthread_create ,
with or without modifications between calls.
.Pp
One of these thread attributes governs the creation state of the new thread. The new thread
can be either created "detached" or "joinable". The constants corresponding to these states are PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE respectively.
Creating a "joinable" thread allows the user
to call
.Fn pthread_join 
and
.Fn pthread_detach ,
with the new thread's ID. A "detached" thread's ID cannot be used with
.Fn pthread_join 
and
.Fn pthread_detach .
The default value for the "detachstate" attribute is PTHREAD_CREATE_JOINABLE.
.Pp
The
.Fn pthread_attr_setdetachstate
function sets the thread's "detachstate" attribute.
.Pp
The "detachstate" attribute is set within the
.Fa attr
argument, which can subsequently be used as an argument to
.Fn pthread_create .
.Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
.Fn pthread_attr_getdetachstate ,
on success, will copy the value of the thread's "detachstate" attribute
to the location pointed to by the second function parameter.
.Sh ERRORS
.Fn pthread_attr_getdetachstate
will fail if:
.Bl -tag -width Er
.\" ========
.It Bq Er EINVAL
Invalid value for
.Fa attr
.El
.Pp
.Fn pthread_attr_setdetachstate
will fail if:
.Bl -tag -width Er
.\" ========
.It Bq Er EINVAL
Invalid value for
.Fa attr
or
.Fa detachstate .
.El
.Pp
.Sh SEE ALSO
.Xr pthread_create 3 ,
.Xr pthread_join 3 ,
.Xr pthread_attr_init 3 ,
.Xr pthread_detach 3
.Sh STANDARDS
.Fn pthread_attr_setdetachstate ,
.Fn pthread_attr_getdetachstate
conform to
.St -p1003.1-96
.Pp
Commit	Line	Data
34e8f829 A	1	.\" Copyright (c) 2004-2007 Apple Inc. All rights reserved.
	2	.Dd December 31, 2007
	3	.Dt PTHREAD_ATTR 3
	4	.Os
	5	.Sh NAME
	6	.Nm pthread_attr_getdetachstate ,
	7	.Nm pthread_attr_setdetachstate
	8	.Nd thread attribute operations
	9	.Sh SYNOPSIS
	10	.Fd #include <pthread.h>
	11	.Ft int
	12	.Fo pthread_attr_getdetachstate
	13	.Fa "const pthread_attr_t *attr"
	14	.Fa "int *detachstate"
	15	.Fc
	16	.Ft int
	17	.Fo pthread_attr_setdetachstate
	18	.Fa "pthread_attr_t *attr"
	19	.Fa "int detachstate"
	20	.Fc
	21	.Sh DESCRIPTION
	22	Thread attributes are used to specify parameters to
	23	.Fn pthread_create .
	24	One attribute object can be used in multiple calls to
	25	.Fn pthread_create ,
	26	with or without modifications between calls.
	27	.Pp
	28	One of these thread attributes governs the creation state of the new thread. The new thread
	29	can be either created "detached" or "joinable". The constants corresponding to these states are PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE respectively.
	30	Creating a "joinable" thread allows the user
	31	to call
	32	.Fn pthread_join
	33	and
	34	.Fn pthread_detach ,
	35	with the new thread's ID. A "detached" thread's ID cannot be used with
	36	.Fn pthread_join
	37	and
	38	.Fn pthread_detach .
	39	The default value for the "detachstate" attribute is PTHREAD_CREATE_JOINABLE.
	40	.Pp
	41	The
	42	.Fn pthread_attr_setdetachstate
	43	function sets the thread's "detachstate" attribute.
	44	.Pp
	45	The "detachstate" attribute is set within the
	46	.Fa attr
	47	argument, which can subsequently be used as an argument to
	48	.Fn pthread_create .
	49	.Sh RETURN VALUES
	50	If successful, these functions return 0.
	51	Otherwise, an error number is returned to indicate the error.
	52	.Fn pthread_attr_getdetachstate ,
	53	on success, will copy the value of the thread's "detachstate" attribute
	54	to the location pointed to by the second function parameter.
	55	.Sh ERRORS
	56	.Fn pthread_attr_getdetachstate
	57	will fail if:
	58	.Bl -tag -width Er
	59	.\" ========
	60	.It Bq Er EINVAL
	61	Invalid value for
	62	.Fa attr
	63	.El
	64	.Pp
65	.Fn pthread_attr_setdetachstate
66	will fail if:
67	.Bl -tag -width Er
68	.\" ========
69	.It Bq Er EINVAL
70	Invalid value for
71	.Fa attr
72	or
73	.Fa detachstate .
74	.El
75	.Pp
76	.Sh SEE ALSO
77	.Xr pthread_create 3 ,
78	.Xr pthread_join 3 ,
79	.Xr pthread_attr_init 3 ,
80	.Xr pthread_detach 3
81	.Sh STANDARDS
82	.Fn pthread_attr_setdetachstate ,
83	.Fn pthread_attr_getdetachstate
84	conform to
85	.St -p1003.1-96
86	.Pp