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. When a thread holding an intra-process lock or a
  50 process holding an inter-process lock crashes or terminates without
  51 unlocking the mutex, then the lock will be
  52 .Sy stalled .
  53 For another thread or process to obtain the lock, something else must
  54 unlock it.
  55 .It Sy PTHREAD_MUTEX_ROBUST
  56 The mutex referred to by
  57 .Va attr
  58 is considered a robust mutex. When a process holding an inter-process
  59 lock crashes or terminates without unlocking the mutex, the attempt to
  60 lock it will return
  61 .Er EOWNERDEAD .
  62 This allows the new owner the chance to fix the internal state and call
  63 .Xr pthread_mutex_consistent 3C
  64 prior to unlocking the lock, allowing normal operation to proceed. Any
  65 crashes while in this state cause the next owner to obtain
  66 .Er EOWNERDEAD .
  67 .El
  68 .Sh RETURN VALUES
  69 Upon successful completion, the
  70 .Fn pthread_mutexattr_getrobust
  71 function will return
  72 .Sy 0
  73 and update
  74 .Fa robust
  75 with the current value of the robust attribute. Upon successful
  76 completion, the
  77 .Fn pthread_mutexattr_setrobust
  78 function will return
  79 .Sy 0
  80 and update the robust property of the attributes pointed to by
  81 .Va attr
  82 to
  83 .Va robust .
  84 If either function fails, an error code will be returned to indicate the
  85 error. Valid errors are defined below.
  86 .Sh ERRORS
  87 The
  88 .Fn pthread_mutexattr_getrobust
  89 function will fail if:
  90 .Bl -tag -width Er
  91 .It Er EINVAL
  92 .Va attr
  93 is invalid or a null pointer,
  94 .Va robust
  95 is a null pointer.
  96 .El
  97 .Lp
  98 The
  99 .Fn pthread_mutexattr_setrobust
 100 function will fail if:
 101 .Bl -tag -width Er
 102 .It Er EINVAL
 103 .Va attr
 104 is invalid or a null pointer,
 105 .Va robust
 106 is not one of
 107 .Sy PTHREAD_MUTEX_STALLED
 108 or
 109 .Sy PTHREAD_MUTEX_ROBUST .
 110 .El
 111 .Sh INTERFACE STABILITY
 112 .Sy Committed
 113 .Sh MT-LEVEL
 114 .Sy MT-Safe
 115 .Sh SEE ALSO
 116 .Xr pthread_mutex_consistent 3C ,
 117 .Xr pthread 3HEAD ,
 118 .Xr libpthread 3LIB ,
 119 .Xr attributes 5 ,
 120 .Xr mutex 5