xref: /freebsd/share/man/man3/pthread_barrierattr.3 (revision 3e9ed1efb85a632c2b4bee70f3ae37a464aba6ad)

.\" 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$
.\"
.Dd February 19, 2004
.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 HISTORY
The
.Fn pthread_barrierattr_*
functions first appeared in
.Lb libkse
in
.Fx 5.2 ,
and in
.Lb libthr
in
.Fx 5.3 .
.Sh BUGS
The implementation of
barriers
does not fully conform to
.St -p1003.2
because the process-shared attribute is ignored in
.Lb libthr ,
and in
.Lb libkse ;
if any value other than
.Dv PTHREAD_PROCESSES_PRIVATE
is specified in a call to
.Fn pthread_barrierattr_setpshared ,
it will return
.Er EINVAL .