usr/src/man/man3c/pthread_mutexattr_getrobust.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2014, Joyent, Inc.
  13 .\"
  14 .Dd "Dec 22, 2014"
  15 .Dt PTHREAD_MUTEXATTR_GETROBUST 3C
  16 .Os
  17 .Sh NAME
  18 .Nm pthread_mutexattr_getrobust ,
  19 .Nm pthrad_mutexattr_setrobust
  20 .Nd get and set the mutex robust attribute
  21 .Sh SYNOPSIS
  22 .In pthread.h
  23 .Ft int
  24 .Fo pthread_mutexattr_getrobust
  25 .Fa "const pthread_mutexattr_t *attr"
  26 .Fa "int *robust"
  27 .Fc
  28 .Ft int
  29 .Fo pthread_mutexattr_setrobust
  30 .Fa "pthread_mutexattr_t *attr"
  31 .Fa "int robust"
  32 .Fc
  33 .Sh DESCRIPTION
  34 The
  35 .Fn pthread_mutexattr_getrobust
  36 and
  37 .Fn pthread_mtuexattr_setrobust
  38 functions obtain and set a mutex's
  39 .Em robust
  40 attribute, putting it in, or obtaining it from
  41 .Va robust .
  42 The valid values for
  43 .Va robust
  44 include:
  45 .Bl -tag -width Dv
  46 .It Sy PTHREAD_MUTEX_STALLED
  47 The mutex referred to by
  48 .Va attr
  49 is a traditional mutex.
  50 When a thread holding an intra-process lock or a process holding an
  51 inter-process lock crashes or terminates without unlocking the mutex, then the
  52 lock will be
  53 .Sy stalled .
  54 For another thread or process to obtain the lock, something else must
  55 unlock it.
  56 .It Sy PTHREAD_MUTEX_ROBUST
  57 The mutex referred to by
  58 .Va attr
  59 is considered a robust mutex.
  60 When a process holding an inter-process lock crashes or terminates without
  61 unlocking the mutex, the attempt to lock it will return
  62 .Er EOWNERDEAD .
  63 This allows the new owner the chance to fix the internal state and call
  64 .Xr pthread_mutex_consistent 3C
  65 prior to unlocking the lock, allowing normal operation to proceed.
  66 Any crashes while in this state cause the next owner to obtain
  67 .Er EOWNERDEAD .
  68 .El
  69 .Sh RETURN VALUES
  70 Upon successful completion, the
  71 .Fn pthread_mutexattr_getrobust
  72 function will return
  73 .Sy 0
  74 and update
  75 .Fa robust
  76 with the current value of the robust attribute.
  77 Upon successful completion, the
  78 .Fn pthread_mutexattr_setrobust
  79 function will return
  80 .Sy 0
  81 and update the robust property of the attributes pointed to by
  82 .Va attr
  83 to
  84 .Va robust .
  85 If either function fails, an error code will be returned to indicate the
  86 error.
  87 Valid errors are defined below.
  88 .Sh ERRORS
  89 The
  90 .Fn pthread_mutexattr_getrobust
  91 function will fail if:
  92 .Bl -tag -width Er
  93 .It Er EINVAL
  94 .Va attr
  95 is invalid or a null pointer,
  96 .Va robust
  97 is a null pointer.
  98 .El
  99 .Lp
 100 The
 101 .Fn pthread_mutexattr_setrobust
 102 function will fail if:
 103 .Bl -tag -width Er
 104 .It Er EINVAL
 105 .Va attr
 106 is invalid or a null pointer,
 107 .Va robust
 108 is not one of
 109 .Sy PTHREAD_MUTEX_STALLED
 110 or
 111 .Sy PTHREAD_MUTEX_ROBUST .
 112 .El
 113 .Sh INTERFACE STABILITY
 114 .Sy Committed
 115 .Sh MT-LEVEL
 116 .Sy MT-Safe
 117 .Sh SEE ALSO
 118 .Xr pthread_mutex_consistent 3C ,
 119 .Xr pthread 3HEAD ,
 120 .Xr libpthread 3LIB ,
 121 .Xr attributes 5 ,
 122 .Xr mutex 5