share/man/man3/pthread_spin_lock.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 January 22, 2004
  26 .Dt PTHREAD_SPIN_LOCK 3
  27 .Os
  28 .Sh NAME
  29 .Nm pthread_spin_lock , pthread_spin_trylock , pthread_spin_unlock
  30 .Nd "lock or unlock a spin lock"
  31 .Sh LIBRARY
  32 .Lb libpthread
  33 .Sh SYNOPSIS
  34 .In pthread.h
  35 .Ft int
  36 .Fn pthread_spin_lock "pthread_spinlock_t *lock"
  37 .Ft int
  38 .Fn pthread_spin_trylock "pthread_spinlock_t *lock"
  39 .Ft int
  40 .Fn pthread_spin_unlock "pthread_spinlock_t *lock"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn pthread_spin_lock
  44 function will acquire
  45 .Fa lock
  46 if it is not currently owned by another thread.
  47 If the lock cannot be acquired immediately, it will
  48 spin attempting to acquire the lock (it will not sleep) until
  49 it becomes available.
  50 .Pp
  51 The
  52 .Fn pthread_spin_trylock
  53 function is the same as
  54 .Fn pthread_spin_lock
  55 except that if it cannot acquire
  56 .Fa lock
  57 immediately it will return with an error.
  58 .Pp
  59 The
  60 .Fn pthread_spin_unlock
  61 function will release
  62 .Fa lock ,
  63 which must have been previously locked by a call to
  64 .Fn pthread_spin_lock
  65 or
  66 .Fn pthread_spin_trylock .
  67 .Sh RETURN VALUES
  68 If successful, all these functions will return zero.
  69 Otherwise, an error number will be returned to indicate the error.
  70 .Pp
  71 None of these functions will return
  72 .Er EINTR .
  73 .Sh ERRORS
  74 The
  75 .Fn pthread_spin_lock ,
  76 .Fn pthread_spin_trylock
  77 and
  78 .Fn pthread_spin_unlock
  79 functions will fail if:
  80 .Bl -tag -width Er
  81 .It Bq Er EINVAL
  82 The value specified by
  83 .Fa lock
  84 is invalid or is not initialized.
  85 .El
  86 .Pp
  87 The
  88 .Fn pthread_spin_lock
  89 function may fail if:
  90 .Bl -tag -width Er
  91 .It Bq Er EDEADLK
  92 The calling thread already owns the lock.
  93 .El
  94 .Pp
  95 The
  96 .Fn pthread_spin_trylock
  97 function will fail if:
  98 .Bl -tag -width Er
  99 .It Bq Er EBUSY
 100 Another thread currently holds
 101 .Fa lock .
 102 .El
 103 .Pp
 104 The
 105 .Fn pthread_spin_unlock
 106 function may fail if:
 107 .Bl -tag -width Er
 108 .It Bq Er EPERM
 109 The calling thread does not own
 110 .Fa lock .
 111 .El
 112 .Sh SEE ALSO
 113 .Xr pthread_spin_destroy 3 ,
 114 .Xr pthread_spin_init 3
 115 .Sh HISTORY
 116 The
 117 .Fn pthread_spin_lock ,
 118 .Fn pthread_spin_trylock
 119 and
 120 .Fn pthread_spin_unlock
 121 functions first appeared in
 122 .Lb libkse
 123 in
 124 .Fx 5.2 ,
 125 and in
 126 .Lb libthr
 127 in
 128 .Fx 5.3 .
 129 .Sh BUGS
 130 The implementation of
 131 .Fn pthread_spin_lock ,
 132 .Fn pthread_spin_trylock
 133 and
 134 .Fn pthread_spin_unlock
 135 is expected to conform to
 136 .St -p1003.2 .