[dragonfly.git] / lib / libpthread / pthread_barrierattr.3

.\" Copyright (c) 2004 Michael Telahun Makonnen
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man3/pthread_barrierattr.3,v 1.3 2007/10/22 10:08:00 ru Exp $
.\"
.Dd July 10, 2009
.Dt PTHREAD_BARRIERATTR 3
.Os
.Sh NAME
.Nm pthread_barrierattr_destroy , pthread_barrierattr_getpshared ,
.Nm pthread_barrierattr_init , pthread_barrierattr_setpshared
.Nd "manipulate a barrier attribute object"
.Sh LIBRARY
.Lb libpthread
.Sh SYNOPSIS
.In pthread.h
.Ft int
.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr"
.Ft int
.Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t *attr" "int *pshared"
.Ft int
.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr"
.Ft int
.Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared"
.Sh DESCRIPTION
The
.Fn pthread_barrierattr_init
function will initialize
.Fa attr
with default attributes.
The
.Fn pthread_barrierattr_destroy
function will destroy
.Fa attr
and release any resources that may have been allocated on its behalf.
.Pp
The
.Fn pthread_barrierattr_getpshared
function will put the value of the process-shared attribute from
.Fa attr
into the memory area pointed to by
.Fa pshared .
The
.Fn pthread_barrierattr_setpshared
function will set the process-shared attribute of
.Fa attr
to the value specified in
.Fa pshared .
The argument
.Fa pshared
may have one of the following values:
.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE"
.It Dv PTHREAD_PROCESS_PRIVATE
The barrier object it is attached to may only be accessed by
threads in the same process as the one that created the object.
.It Dv PTHREAD_PROCESS_SHARED
The barrier object it is attached to may be accessed by
threads in processes other than the one that created the object.
.El
.Sh RETURN VALUES
If successful, all these functions will return zero.
Otherwise, an error number will be returned to indicate the error.
.Pp
None of these functions will return
.Er EINTR .
.Sh ERRORS
The
.Fn pthread_barrierattr_destroy ,
.Fn pthread_barrierattr_getpshared
and
.Fn pthread_barrierattr_setpshared
functions may fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The value specified by
.Fa attr
is invalid.
.El
.Pp
The
.Fn pthread_barrierattr_init
function will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Insufficient memory to initialize the barrier attribute object
.Fa attr .
.El
.Pp
The
.Fn pthread_barrierattr_setpshared
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The value specified in
.Fa pshared
is not one of the allowed values.
.El
.Sh SEE ALSO
.Xr pthread_barrier_destroy 3 ,
.Xr pthread_barrier_init 3 ,
.Xr pthread_barrier_wait 3
.Sh BUGS
The implementation of
barriers
does not fully conform to
.St -p1003.2
because the process-shared attribute is ignored;
if any value other than
.Dv PTHREAD_PROCESS_PRIVATE
is specified in a call to
.Fn pthread_barrierattr_setpshared ,
it will return
.Er EINVAL .
Commit	Line	Data
15acf97d SW	1	.\" Copyright (c) 2004 Michael Telahun Makonnen
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/share/man/man3/pthread_barrierattr.3,v 1.3 2007/10/22 10:08:00 ru Exp $
	26	.\"
	27	.Dd July 10, 2009
	28	.Dt PTHREAD_BARRIERATTR 3
	29	.Os
	30	.Sh NAME
	31	.Nm pthread_barrierattr_destroy , pthread_barrierattr_getpshared ,
	32	.Nm pthread_barrierattr_init , pthread_barrierattr_setpshared
	33	.Nd "manipulate a barrier attribute object"
	34	.Sh LIBRARY
	35	.Lb libpthread
	36	.Sh SYNOPSIS
	37	.In pthread.h
	38	.Ft int
	39	.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr"
	40	.Ft int
	41	.Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t attr" "int pshared"
	42	.Ft int
	43	.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr"
	44	.Ft int
	45	.Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared"
	46	.Sh DESCRIPTION
	47	The
	48	.Fn pthread_barrierattr_init
	49	function will initialize
	50	.Fa attr
	51	with default attributes.
	52	The
	53	.Fn pthread_barrierattr_destroy
	54	function will destroy
	55	.Fa attr
	56	and release any resources that may have been allocated on its behalf.
	57	.Pp
	58	The
	59	.Fn pthread_barrierattr_getpshared
	60	function will put the value of the process-shared attribute from
	61	.Fa attr
	62	into the memory area pointed to by
	63	.Fa pshared .
	64	The
65	.Fn pthread_barrierattr_setpshared
66	function will set the process-shared attribute of
67	.Fa attr
68	to the value specified in
69	.Fa pshared .
70	The argument
71	.Fa pshared
72	may have one of the following values:
73	.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE"
74	.It Dv PTHREAD_PROCESS_PRIVATE
75	The barrier object it is attached to may only be accessed by
76	threads in the same process as the one that created the object.
77	.It Dv PTHREAD_PROCESS_SHARED
78	The barrier object it is attached to may be accessed by
79	threads in processes other than the one that created the object.
80	.El
81	.Sh RETURN VALUES
82	If successful, all these functions will return zero.
83	Otherwise, an error number will be returned to indicate the error.
84	.Pp
85	None of these functions will return
86	.Er EINTR .
87	.Sh ERRORS
88	The
89	.Fn pthread_barrierattr_destroy ,
90	.Fn pthread_barrierattr_getpshared
91	and
92	.Fn pthread_barrierattr_setpshared
93	functions may fail if:
94	.Bl -tag -width Er
95	.It Bq Er EINVAL
96	The value specified by
97	.Fa attr
98	is invalid.
99	.El
100	.Pp
101	The
102	.Fn pthread_barrierattr_init
103	function will fail if:
104	.Bl -tag -width Er
105	.It Bq Er ENOMEM
106	Insufficient memory to initialize the barrier attribute object
107	.Fa attr .
108	.El
109	.Pp
110	The
111	.Fn pthread_barrierattr_setpshared
112	function will fail if:
113	.Bl -tag -width Er
114	.It Bq Er EINVAL
115	The value specified in
116	.Fa pshared
117	is not one of the allowed values.
118	.El
119	.Sh SEE ALSO
120	.Xr pthread_barrier_destroy 3 ,
121	.Xr pthread_barrier_init 3 ,
122	.Xr pthread_barrier_wait 3
15acf97d SW	123	.Sh BUGS
	124	The implementation of
	125	barriers
	126	does not fully conform to
	127	.St -p1003.2
	128	because the process-shared attribute is ignored;
	129	if any value other than
	130	.Dv PTHREAD_PROCESS_PRIVATE
	131	is specified in a call to
	132	.Fn pthread_barrierattr_setpshared ,
	133	it will return
	134	.Er EINVAL .