share/man/man3/pthread_barrierattr.3

   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$
  26 .\"
  27 .Dd February 19, 2004
  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 .Lb libthr
  37 .Sh SYNOPSIS
  38 .In pthread.h
  39 .Ft int
  40 .Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr"
  41 .Ft int
  42 .Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t *attr" "int *pshared"
  43 .Ft int
  44 .Fn pthread_barrierattr_init "pthread_barrierattr_t *attr"
  45 .Ft int
  46 .Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn pthread_barrierattr_init
  50 function will initialize
  51 .Fa attr
  52 with default attributes.
  53 The
  54 .Fn pthread_barrierattr_destroy
  55 function will destroy
  56 .Fa attr
  57 and release any resources that may have been allocated on its behalf.
  58 .Pp
  59 The
  60 .Fn pthread_barrierattr_getpshared
  61 function will put the value of the process-shared attribute from
  62 .Fa attr
  63 into the memory area pointed to by
  64 .Fa pshared .
  65 The
  66 .Fn pthread_barrierattr_setpshared
  67 function will set the process-shared attribute of
  68 .Fa attr
  69 to the value specified in
  70 .Fa pshared .
  71 The argument
  72 .Fa pshared
  73 may have one of the following values:
  74 .Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE"
  75 .It Dv PTHREAD_PROCESS_PRIVATE
  76 The barrier object it is attached to may only be accessed by
  77 threads in the same process as the one that created the object.
  78 .It Dv PTHREAD_PROCESS_SHARED
  79 The barrier object it is attached to may be accessed by
  80 threads in processes other than the one that created the object.
  81 .El
  82 .Sh RETURN VALUES
  83 If successful, all these functions will return zero.
  84 Otherwise, an error number will be returned to indicate the error.
  85 .Pp
  86 None of these functions will return
  87 .Er EINTR .
  88 .Sh ERRORS
  89 The
  90 .Fn pthread_barrierattr_destroy ,
  91 .Fn pthread_barrierattr_getpshared
  92 and
  93 .Fn pthread_barrierattr_setpshared
  94 functions may fail if:
  95 .Bl -tag -width Er
  96 .It Bq Er EINVAL
  97 The value specified by
  98 .Fa attr
  99 is invalid.
 100 .El
 101 .Pp
 102 The
 103 .Fn pthread_barrierattr_init
 104 function will fail if:
 105 .Bl -tag -width Er
 106 .It Bq Er ENOMEM
 107 Insufficient memory to initialize the barrier attribute object
 108 .Fa attr .
 109 .El
 110 .Pp
 111 The
 112 .Fn pthread_barrierattr_setpshared
 113 function will fail if:
 114 .Bl -tag -width Er
 115 .It Bq Er EINVAL
 116 The value specified in
 117 .Fa pshared
 118 is not one of the allowed values.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr pthread_barrier_destroy 3 ,
 122 .Xr pthread_barrier_init 3 ,
 123 .Xr pthread_barrier_wait 3
 124 .Sh HISTORY
 125 The
 126 .Fn pthread_barrierattr_*
 127 functions first appeared in
 128 .Lb libpthread
 129 in
 130 .Fx 5.2 ,
 131 and in
 132 .Lb libthr
 133 in
 134 .Fx 5.3 .
 135 .Sh BUGS
 136 The implementation of
 137 barriers
 138 does not fully conform to
 139 .St -p1003.2
 140 because the process-shared attribute is ignored in
 141 .Lb libthr ,
 142 and in
 143 .Lb libpthread ;
 144 if any value other than
 145 .Dv PTHREAD_PROCESSES_PRIVATE
 146 is specified in a call to
 147 .Fn pthread_barrierattr_setpshared ,
 148 it will return
 149 .Er EINVAL .