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