share/man/man3/pthread_spin_init.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 January 22, 2004
  28 .Dt PTHREAD_SPIN_INIT 3
  29 .Os
  30 .Sh NAME
  31 .Nm pthread_spin_init , pthread_spin_destroy
  32 .Nd "initialize or destroy a spin lock"
  33 .Sh LIBRARY
  34 .Lb libpthread
  35 .Lb libthr
  36 .Sh SYNOPSIS
  37 .In pthread.h
  38 .Ft int
  39 .Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared"
  40 .Ft int
  41 .Fn pthread_spin_destroy "pthread_spinlock_t *lock"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn pthread_spin_init
  45 function will initialize
  46 .Fa lock
  47 to an unlocked state and
  48 allocate any resources necessary to begin using it.
  49 If
  50 .Fa pshared
  51 is set to
  52 .Dv PTHREAD_PROCESS_SHARED ,
  53 any thread,
  54 whether belonging to the process in which the spinlock was created or not,
  55 that has access to the memory area where
  56 .Fa lock
  57 resides, can use
  58 .Fa lock .
  59 If it is set to
  60 .Dv PTHREAD_PROCESS_PRIVATE ,
  61 it can only be used by threads within the same process.
  62 .Pp
  63 The
  64 .Fn pthread_spin_destroy
  65 function will destroy
  66 .Fa lock
  67 and release any resources that may have been allocated on its behalf.
  68 .Sh RETURN VALUES
  69 If successful,
  70 both
  71 .Fn pthread_spin_init
  72 and
  73 .Fn pthread_spin_destroy
  74 will return zero.
  75 Otherwise, an error number will be returned to indicate the error.
  76 .Pp
  77 Neither of these functions will return
  78 .Er EINTR .
  79 .Sh ERRORS
  80 The
  81 .Fn pthread_spin_init
  82 and
  83 .Fn pthread_spin_destroy
  84 functions will fail if:
  85 .Bl -tag -width Er
  86 .It Bq Er EBUSY
  87 An attempt to initialize or destroy
  88 .Fa lock
  89 while it is in use.
  90 .It Bq Er EINVAL
  91 The value specified by
  92 .Fa lock
  93 is invalid.
  94 .El
  95 .Pp
  96 The
  97 .Fn pthread_spin_init
  98 function will fail if:
  99 .Bl -tag -width Er
 100 .It Bq Er EAGAIN
 101 Insufficient resources,
 102 other than memory,
 103 to initialize
 104 .Fa lock .
 105 .It Bq Er ENOMEM
 106 Insufficient memory to initialize
 107 .Fa lock .
 108 .El
 109 .Sh SEE ALSO
 110 .Xr pthread_spin_lock 3 ,
 111 .Xr pthread_spin_unlock 3
 112 .Sh HISTORY
 113 The
 114 .Fn pthread_spin_init
 115 and
 116 .Fn pthread_spin_destroy
 117 functions first appeared in
 118 .Lb libpthread
 119 in
 120 .Fx 5.2 ,
 121 and in
 122 .Lb libthr
 123 in
 124 .Fx 5.3 .
 125 .Sh BUGS
 126 The implementation of
 127 .Fn pthread_spin_init
 128 does not fully conform to
 129 .St -p1003.2
 130 because the
 131 .Fa pshared
 132 argument is ignored in
 133 .Lb libthr ,
 134 and in
 135 .Lb libpthread
 136 if any value other than
 137 .Dv PTHREAD_PROCESSES_PRIVATE
 138 is specified, it returns
 139 .Er EINVAL .