usr/src/man/man3c/pthread_mutex_consistent.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_MUTEX_CONSISTENT 3C
  16 .Os
  17 .Sh NAME
  18 .Nm pthread_mutex_consistent
  19 .Nd mark state protected by robust mutex as consistent
  20 .Sh SYNOPSIS
  21 .In pthread.h
  22 .Ft int
  23 .Fo pthread_mutex_consistent
  24 .Fa "pthread_mutex_t *mutex"
  25 .Fc
  26 .Sh DESCRIPTION
  27 The
  28 .Fn pthread_mutex_consistent
  29 function is used to indicate that a robust lock that is in an
  30 inconsistent state no longer is.
  31 .Lp
  32 A robust lock enters into an inconsistent state when a process or thread
  33 holding a robust lock exits, such as by calling
  34 .Xr exit 2
  35 or
  36 .Xr thr_exit 3C ,
  37 or crashes without unlocking the lock.
  38 At that point, if another process or thread is currently in a call, or calls
  39 .Xr pthread_mutex_lock 3C ,
  40 it will obtain the lock; however, the error code
  41 .Er EOWNERDEAD
  42 will be returned.
  43 In such cases, that thread will own the lock and must check and clean up any
  44 inconsistent state that is protected by the lock.
  45 When finished, it must call
  46 .Fn pthread_mutex_consistent
  47 to indicate that it is in a consistent state again.
  48 .Lp
  49 If a process or thread obtains a robust lock while it is in an
  50 inconsistent state and it crashes or terminates before marking the lock
  51 as consistent, the next process or thread that obtains the lock will
  52 receive
  53 .Er EOWNERDEAD .
  54 .Sh RETURN VALUES
  55 Upon successful completion, the
  56 .Fn pthread_mutex_consistent
  57 returns zero and marks
  58 .Va mutex
  59 as consistent.
  60 Callers of
  61 .Fn pthread_mutex_lock
  62 will not have
  63 .Er EOWNERDEAD
  64 returned until another process or thread exits without unlocking.
  65 Upon failure, an error will be returned which corresponds to one of the errors
  66 listed below.
  67 .Sh ERRORS
  68 The
  69 .Fn pthread_mutex_consistent
  70 function will fail if:
  71 .Bl -tag -width Er
  72 .It Er EINVAL
  73 .Va mutex
  74 is an uninitialized mutex, not a robust mutex, or not in an inconsistent
  75 state.
  76 .El
  77 .Sh INTERFACE STABILITY
  78 .Sy Committed
  79 .Sh MT-LEVEL
  80 .Sy MT-Safe
  81 .Sh SEE ALSO
  82 .Xr pthread_mutex_destroy 3C ,
  83 .Xr pthread_mutex_init 3C ,
  84 .Xr pthread_mutex_lock 3C ,
  85 .Xr pthread_mutexattr_getrobust 3C ,
  86 .Xr pthread 3HEAD ,
  87 .Xr libpthread 3LIB ,
  88 .Xr attributes 5 ,
  89 .Xr mutex 5