1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   4 .\" Portions Copyright (c) 1995 IEEE  All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH MUTEX_INIT 3C "Jun 5, 2007"
  13 .SH NAME
  14 mutex_init, mutex_lock, mutex_trylock, mutex_unlock, mutex_consistent,
  15 mutex_destroy \- mutual exclusion locks
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  20 #include <thread.h>
  21 #include <synch.h>
  22 
  23 \fBint\fR \fBmutex_init\fR(\fBmutex_t *\fR\fImp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR \fIarg\fR);
  24 .fi
  25 
  26 .LP
  27 .nf
  28 \fBint\fR \fBmutex_lock\fR(\fBmutex_t *\fR\fImp\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBint\fR \fBmutex_trylock\fR(\fBmutex_t *\fR\fImp\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBint\fR \fBmutex_unlock\fR(\fBmutex_t *\fR\fImp\fR);
  39 .fi
  40 
  41 .LP
  42 .nf
  43 \fBint\fR \fBmutex_consistent\fR(\fBmutex_t *\fR\fImp\fR);
  44 .fi
  45 
  46 .LP
  47 .nf
  48 \fBint\fR \fBmutex_destroy\fR(\fBmutex_t *\fR\fImp\fR);
  49 .fi
  50 
  51 .SH DESCRIPTION
  52 .sp
  53 .LP
  54 Mutual exclusion locks (mutexes) prevent multiple threads from simultaneously
  55 executing critical sections of code that access shared data (that is, mutexes
  56 are used to serialize the execution of threads). All mutexes must be global. A
  57 successful call for a mutex lock by way of  \fBmutex_lock()\fR will cause
  58 another thread that is also trying to lock the same mutex to block until the
  59 owner thread unlocks it by way of  \fBmutex_unlock()\fR. Threads within the
  60 same process or within other processes can share mutexes.
  61 .sp
  62 .LP
  63 Mutexes can synchronize threads within the same process or in other  processes.
  64 Mutexes can be used to synchronize threads between processes if the mutexes are
  65 allocated in writable memory and shared among the cooperating processes (see
  66 \fBmmap\fR(2)), and have been initialized for this task.
  67 .SS "Initialize"
  68 .sp
  69 .LP
  70 Mutexes are either intra-process or inter-process, depending  upon the argument
  71 passed implicitly or explicitly  to the initialization of that mutex. A
  72 statically allocated mutex does not need to be explicitly  initialized; by
  73 default, a statically allocated mutex is initialized  with all zeros and its
  74 scope is set to be within the calling process.
  75 .sp
  76 .LP
  77 For inter-process synchronization, a mutex needs to be allocated  in memory
  78 shared between these processes. Since the memory for such a mutex must be
  79 allocated dynamically,  the mutex needs to be explicitly initialized using
  80 \fBmutex_init()\fR.
  81 .sp
  82 .LP
  83 The  \fBmutex_init()\fR function initializes the mutex referenced by \fImp\fR
  84 with the type specified by  \fItype\fR. Upon successful initialization the
  85 state of the mutex becomes initialized and unlocked. Only the attribute type
  86 \fBLOCK_PRIO_PROTECT\fR uses \fIarg\fR. The \fItype\fR argument must be one of
  87 the following:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBUSYNC_THREAD\fR\fR
  92 .ad
  93 .sp .6
  94 .RS 4n
  95 The mutex can synchronize threads only in this process.
  96 .RE
  97 
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBUSYNC_PROCESS\fR\fR
 102 .ad
 103 .sp .6
 104 .RS 4n
 105 The mutex can synchronize threads in this process and other processes. The
 106 object initialized with this attribute must be allocated in memory shared
 107 between processes, either in System V shared memory (see  \fBshmop\fR(2)) or in
 108 memory mapped to a file (see  \fBmmap\fR(2)). If the object is not allocated in
 109 such shared memory, it will not be shared between processes.
 110 .RE
 111 
 112 .sp
 113 .LP
 114 The \fItype\fR argument can be augmented by the bitwise-inclusive-\fBOR\fR of
 115 zero or more of the following flags:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBLOCK_ROBUST\fR\fR
 120 .ad
 121 .sp .6
 122 .RS 4n
 123 The mutex can synchronize threads robustly. At the time of thread or process
 124 death, either by calling \fBthr_exit()\fR or \fBexit()\fR or due to process
 125 abnormal termination, the lock is unlocked if is held by the thread or process.
 126 The next owner of the mutex will acquire it with an error return of
 127 \fBEOWNERDEAD\fR. The application must always check the return value from
 128 \fBmutex_lock()\fR for a mutex of this type. The new owner of this mutex should
 129 then attempt to make the state protected by the mutex consistent, since this
 130 state could have been left inconsistent when the last owner died. If the new
 131 owner is able to make the state consistent, it should call
 132 \fBmutex_consistent()\fR to restore the state of the mutex and then unlock the
 133 mutex. All subsequent calls to \fBmutex_lock()\fRwill then behave normally.
 134 Only the new owner can make the mutex consistent. If for any reason the new
 135 owner is not able to make the state consistent, it should not call
 136 \fBmutex_consistent()\fR but should simply unlock the mutex. All waiting
 137 processes will be awakened and all subsequent calls to \fBmutex_lock()\fR will
 138 fail in acquiring the mutex with an error value of \fBENOTRECOVERABLE\fR. If
 139 the thread or process that acquired the lock with \fBEOWNERDEAD\fR terminates
 140 without unlocking the mutex, the next owner will acquire the lock with an error
 141 value of \fBEOWNERDEAD\fR.
 142 .sp
 143 The memory for the object to be initialized with this attribute must be zeroed
 144 before initialization. Any thread or process interested in the robust lock can
 145 call \fBmutex_init()\fR to potentially initialize it, provided that all such
 146 callers of \fBmutex_init()\fR specify the same set of attribute flags. In this
 147 situation, if  \fBmutex_init()\fR is called on a previously initialized robust
 148 mutex, \fBmutex_init()\fR will not reinitialize the mutex and will return the
 149 error value \fBEBUSY\fR.
 150 .RE
 151 
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBLOCK_RECURSIVE\fR\fR
 156 .ad
 157 .sp .6
 158 .RS 4n
 159 A thread attempting to relock this mutex without first unlocking it will
 160 succeed in locking the mutex. The mutex must be unlocked as many times as it is
 161 locked.
 162 .RE
 163 
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBLOCK_ERRORCHECK\fR\fR
 168 .ad
 169 .sp .6
 170 .RS 4n
 171 Unless \fBLOCK_RECURSIVE\fR is also set, a thread attempting to relock this
 172 mutex without first unlocking it will return with an error rather than
 173 deadlocking itself.  A thread attempting to unlock this mutex without first
 174 owning it will return with an error.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBLOCK_PRIO_INHERIT\fR\fR
 181 .ad
 182 .sp .6
 183 .RS 4n
 184 When a thread is blocking higher priority threads because of owning one or more
 185 mutexes with the \fBLOCK_PRIO_INHERIT\fR attribute, it executes at the higher
 186 of its priority or the priority of the highest priority thread waiting on any
 187 of the mutexes owned by this thread and initialized with this attribute.
 188 .RE
 189 
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBLOCK_PRIO_PROTECT\fR\fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 When a thread owns one or more mutexes initialized with the
 198 \fBLOCK_PRIO_PROTECT\fR attribute, it executes at the higher of its priority or
 199 the highest of the priority ceilings of all the mutexes owned by this thread
 200 and initialized with this attribute, regardless of whether other threads are
 201 blocked on any of these mutexes.  When this attribute is specified, \fIarg\fR
 202 must point to an \fBint\fR containing the priority ceiling.
 203 .RE
 204 
 205 .sp
 206 .LP
 207 See \fBpthread_mutexattr_getrobust\fR(3C) for more information about robust
 208 mutexes. The \fBLOCK_ROBUST\fR attribute is the same as the POSIX
 209 \fBPTHREAD_MUTEX_ROBUST\fR attribute.
 210 .sp
 211 .LP
 212 See \fBpthread_mutexattr_settype\fR(3C) for more information on recursive and
 213 error checking mutex types. The combination (\fBLOCK_RECURSIVE\fR |
 214 \fBLOCK_ERRORCHECK\fR) is the same as the POSIX \fBPTHREAD_MUTEX_RECURSIVE\fR
 215 type. By itself, \fBLOCK_ERRORCHECK\fR is the same as the \fBPOSIX
 216 PTHREAD_MUTEX_ERRORCHECK\fR type.
 217 .sp
 218 .LP
 219 The \fBLOCK_PRIO_INHERIT\fR attribute is the same as the POSIX
 220 \fBPTHREAD_PRIO_INHERIT\fR attribute. The \fBLOCK_PRIO_PROTECT\fR attribute is
 221 the same as the POSIX \fBPTHREAD_PRIO_PROTECT\fR attribute. See
 222 \fBpthread_mutexattr_getprotocol\fR(3C),
 223 \fBpthread_mutexattr_getprioceiling\fR(3C), and
 224 \fBpthread_mutex_getprioceiling\fR(3C) for a full discussion. The
 225 \fBLOCK_PRIO_INHERIT\fR and \fBLOCK_PRIO_PROTECT\fR attributes are mutually
 226 exclusive. Specifying both of these attributes causes \fBmutex_init()\fR to
 227 fail with \fBEINVAL\fR.
 228 .sp
 229 .LP
 230 Initializing mutexes can also be accomplished  by allocating in zeroed memory
 231 (default), in which case a \fItype\fR of \fBUSYNC_THREAD\fR is assumed. In
 232 general, the following rules apply to mutex initialization:
 233 .RS +4
 234 .TP
 235 .ie t \(bu
 236 .el o
 237 The same mutex must not be simultaneously initialized by multiple threads.
 238 .RE
 239 .RS +4
 240 .TP
 241 .ie t \(bu
 242 .el o
 243 A mutex lock must not be reinitialized while in use by other threads.
 244 .RE
 245 .sp
 246 .LP
 247 These rules do not apply to \fBLOCK_ROBUST\fR mutexes. See the description for
 248 \fBLOCK_ROBUST\fRabove. If default mutex attributes are used, the macro
 249 \fBDEFAULTMUTEX\fR can be used to initialize mutexes that are statically
 250 allocated.
 251 .sp
 252 .LP
 253 Default mutex initialization (intra-process):
 254 .sp
 255 .in +2
 256 .nf
 257 mutex_t mp;
 258 mutex_init(&mp, USYNC_THREAD, NULL);
 259 .fi
 260 .in -2
 261 
 262 .sp
 263 .LP
 264 or
 265 .sp
 266 .in +2
 267 .nf
 268 mutex_t  mp  =  DEFAULTMUTEX;
 269 .fi
 270 .in -2
 271 
 272 .sp
 273 .LP
 274 Customized mutex initialization (inter-process):
 275 .sp
 276 .in +2
 277 .nf
 278 mutex_init(&mp, USYNC_PROCESS, NULL);
 279 .fi
 280 .in -2
 281 
 282 .sp
 283 .LP
 284 Customized mutex initialization (inter-process robust):
 285 .sp
 286 .in +2
 287 .nf
 288 mutex_init(&mp, USYNC_PROCESS | LOCK_ROBUST, NULL);
 289 .fi
 290 .in -2
 291 
 292 .sp
 293 .LP
 294 Statically allocated mutexes can also be initialized with macros specifying
 295 \fBLOCK_RECURSIVE\fR and/or \fBLOCK_ERRORCHECK\fR:
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBmutex_t mp = RECURSIVEMUTEX;\fR\fR
 300 .ad
 301 .sp .6
 302 .RS 4n
 303 Same as (\fBUSYNC_THREAD\fR | \fBLOCK_RECURSIVE\fR)
 304 .RE
 305 
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBmutex_t mp = ERRORCHECKMUTEX;\fR\fR
 310 .ad
 311 .sp .6
 312 .RS 4n
 313 Same as (\fBUSYNC_THREAD\fR | \fBLOCK_ERRORCHECK\fR)
 314 .RE
 315 
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fBmutex_t mp = RECURSIVE_ERRORCHECKMUTEX;\fR\fR
 320 .ad
 321 .sp .6
 322 .RS 4n
 323 Same as (\fBUSYNC_THREAD\fR | \fBLOCK_RECURSIVE\fR | \fBLOCK_ERRORCHECK\fR)
 324 .RE
 325 
 326 .SS "Lock and Unlock"
 327 .sp
 328 .LP
 329 A critical section of code is enclosed by  a the call to lock the mutex and the
 330 call to unlock the mutex to protect it from simultaneous access by multiple
 331 threads. Only one thread at a time may possess mutually exclusive access to
 332 the critical section of code that is enclosed by the mutex-locking call and the
 333 mutex-unlocking call, whether the mutex's scope  is intra-process or
 334 inter-process. A thread calling to lock the mutex either gets exclusive  access
 335 to the code starting from the successful locking until its call to unlock the
 336 mutex, or it waits until the mutex is unlocked by the thread that locked it.
 337 .sp
 338 .LP
 339 Mutexes have ownership, unlike semaphores. Although any thread, within the
 340 scope of a mutex, can get an unlocked mutex and lock access to the same
 341 critical section of code, only the thread that locked a mutex should unlock it.
 342 .sp
 343 .LP
 344 If a thread waiting for a mutex receives a signal, upon return from the signal
 345 handler, the thread resumes waiting for the mutex as if there was no interrupt.
 346 A mutex protects code, not data; therefore, strongly bind a mutex  with the
 347 data by putting both within the same structure, or at least within the same
 348 procedure.
 349 .sp
 350 .LP
 351 A call to \fBmutex_lock()\fR locks the mutex object referenced by \fImp\fR. If
 352 the mutex is already locked, the calling thread blocks until the mutex is
 353 freed; this will return with the mutex object referenced by \fImp\fR in the
 354 locked state with the calling thread as its owner. If the current owner of a
 355 mutex tries to relock the mutex, it will result in deadlock.
 356 .sp
 357 .LP
 358 The \fBmutex_trylock()\fR function is the same as \fBmutex_lock()\fR,
 359 respectively, except that if the mutex object referenced by \fImp\fR is locked
 360 (by any thread, including the current thread), the call returns immediately
 361 with an error.
 362 .sp
 363 .LP
 364 The \fBmutex_unlock()\fR function are called by the owner of the mutex object
 365 referenced by \fImp\fR to release it. The mutex must be locked and the calling
 366 thread must be the one that last locked the mutex (the owner). If there are
 367 threads blocked on the mutex object referenced by \fImp\fR when
 368 \fBmutex_unlock()\fR is called, the \fImp\fR is freed, and the scheduling
 369 policy will determine which thread gets the mutex. If the calling thread is not
 370 the owner of the lock, no error status is returned, and the behavior of the
 371 program is undefined.
 372 .SS "Destroy"
 373 .sp
 374 .LP
 375 The \fBmutex_destroy()\fR function destroys the mutex object referenced by
 376 \fImp\fR. The mutex object becomes uninitialized. The space used by the
 377 destroyed mutex variable is not freed. It needs to be explicitly reclaimed.
 378 .SH RETURN VALUES
 379 .sp
 380 .LP
 381 If successful, these functions return \fB0\fR. Otherwise, an error number is
 382 returned.
 383 .SH ERRORS
 384 .sp
 385 .LP
 386 The \fBmutex_init()\fR function will fail if:
 387 .sp
 388 .ne 2
 389 .na
 390 \fB\fBEINVAL\fR\fR
 391 .ad
 392 .RS 10n
 393 The value specified by \fItype\fR is invalid, or the \fBLOCK_PRIO_INHERIT\fR
 394 and \fBLOCK_PRIO_PROTECT\fR attributes are both specified.
 395 .RE
 396 
 397 .sp
 398 .LP
 399 The \fBmutex_init()\fR function will fail for  \fBLOCK_ROBUST\fR type mutex if:
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fBEBUSY\fR\fR
 404 .ad
 405 .RS 10n
 406 The mutex pointed to by  \fImp\fR was previously initialized and has not yet
 407 been destroyed.
 408 .RE
 409 
 410 .sp
 411 .ne 2
 412 .na
 413 \fB\fBEINVAL\fR\fR
 414 .ad
 415 .RS 10n
 416 The mutex pointed to by \fImp\fR was previously initialized with a different
 417 set of attribute flags.
 418 .RE
 419 
 420 .sp
 421 .LP
 422 The \fBmutex_trylock()\fR function will fail if:
 423 .sp
 424 .ne 2
 425 .na
 426 \fB\fBEBUSY\fR\fR
 427 .ad
 428 .RS 9n
 429 The mutex pointed to by \fImp\fR is already locked.
 430 .RE
 431 
 432 .sp
 433 .LP
 434 The \fBmutex_lock()\fR and \fBmutex_trylock()\fR functions will fail for a
 435 \fBLOCK_RECURSIVE\fR mutex if:
 436 .sp
 437 .ne 2
 438 .na
 439 \fB\fBEAGAIN\fR\fR
 440 .ad
 441 .RS 10n
 442 The mutex could not be acquired because the maximum number of recursive locks
 443 for the mutex has been reached.
 444 .RE
 445 
 446 .sp
 447 .LP
 448 The \fBmutex_lock()\fR function will fail for a \fBLOCK_ERRORCHECK\fR and
 449 non-\fBLOCK_RECURSIVE\fR mutex if:
 450 .sp
 451 .ne 2
 452 .na
 453 \fB\fBEDEADLK\fR\fR
 454 .ad
 455 .RS 11n
 456 The caller already owns the mutex.
 457 .RE
 458 
 459 .sp
 460 .LP
 461 The \fBmutex_lock()\fR function may fail for a non-\fBLOCK_ERRORCHECK\fR and
 462 non-\fBLOCK_RECURSIVE\fR mutex if:
 463 .sp
 464 .ne 2
 465 .na
 466 \fB\fBEDEADLK\fR\fR
 467 .ad
 468 .RS 11n
 469 The caller already owns the mutex.
 470 .RE
 471 
 472 .sp
 473 .LP
 474 The \fBmutex_unlock()\fR function will fail for a \fBLOCK_ERRORCHECK\fR mutex
 475 if:
 476 .sp
 477 .ne 2
 478 .na
 479 \fB\fBEPERM\fR\fR
 480 .ad
 481 .RS 9n
 482 The caller does not own the mutex.
 483 .RE
 484 
 485 .sp
 486 .LP
 487 The \fBmutex_lock()\fR or \fBmutex_trylock()\fR functions will fail for
 488 \fBLOCK_ROBUST\fR type mutex if:
 489 .sp
 490 .ne 2
 491 .na
 492 \fB\fBEOWNERDEAD\fR\fR
 493 .ad
 494 .RS 19n
 495 The last owner of this mutex died while holding the mutex. This mutex is now
 496 owned by the caller. The caller must now attempt to make the state protected by
 497 the mutex consistent. If it is able to clean up the state, then it should
 498 restore the state of the mutex by calling \fBmutex_consistent()\fR and unlock
 499 the mutex. Subsequent calls to \fBmutex_lock()\fR will behave normally, as
 500 before. If the caller is not able to clean up the state,
 501 \fBmutex_consistent()\fR should not be called but the mutex should be unlocked.
 502 Subsequent calls to \fBmutex_lock()\fR will fail to acquire the mutex,
 503 returning with the error value \fBENOTRECOVERABLE\fR. If the owner who acquired
 504 the lock with  \fBEOWNERDEAD\fR dies, the next owner will acquire the lock with
 505 \fBEOWNERDEAD\fR.
 506 .RE
 507 
 508 .sp
 509 .ne 2
 510 .na
 511 \fB\fBENOTRECOVERABLE\fR\fR
 512 .ad
 513 .RS 19n
 514 The mutex trying to be acquired was protecting the state that has been left
 515 unrecoverable when the mutex's last owner could not make the state protected by
 516 the mutex consistent. The mutex has not been acquired. This condition occurs
 517 when the lock was previously acquired with \fBEOWNERDEAD\fR and the owner was
 518 not able to clean up the state and unlocked the mutex without calling
 519 \fBmutex_consistent()\fR.
 520 .RE
 521 
 522 .sp
 523 .LP
 524 The \fBmutex_consistent()\fR function will fail if:
 525 .sp
 526 .ne 2
 527 .na
 528 \fB\fBEINVAL\fR\fR
 529 .ad
 530 .RS 10n
 531 The caller does not own the mutex or the mutex is not a \fBLOCK_ROBUST\fR mutex
 532 having an inconsistent state (\fBEOWNERDEAD\fR).
 533 .RE
 534 
 535 .SH EXAMPLES
 536 .SS "Single Gate"
 537 .sp
 538 .LP
 539 The following example uses one global mutex as a gate-keeper to permit each
 540 thread exclusive sequential access to the code within the user-defined
 541 function "change_global_data." This type of synchronization will protect the
 542 state of shared data,  but it also prohibits parallelism.
 543 .sp
 544 .in +2
 545 .nf
 546 /* cc thisfile.c -lthread */
 547 #define _REENTRANT
 548 #include <stdio.h>
 549 #include <thread.h>
 550 #define NUM_THREADS 12
 551 void *change_global_data(void *);     /*  for thr_create()   */
 552 main(int argc,char * argv[])    {
 553        int i=0;
 554        for (i=0; i< NUM_THREADS; i++)        {
 555                thr_create(NULL, 0, change_global_data, NULL, 0, NULL);
 556        }
 557        while ((thr_join(NULL, NULL, NULL) == 0));
 558 }
 559 
 560 void * change_global_data(void *null){
 561        static mutex_t   Global_mutex;
 562        static int       Global_data = 0;
 563        mutex_lock(&Global_mutex);
 564        Global_data++;
 565        sleep(1);
 566        printf("%d is global data\en",Global_data);
 567        mutex_unlock(&Global_mutex);
 568        return NULL;
 569 }
 570 .fi
 571 .in -2
 572 
 573 .SS "Multiple Instruction Single Data"
 574 .sp
 575 .LP
 576 The previous example, the mutex, the code it owns, and the data it protects was
 577 enclosed in one function. The next example uses C++ features to accommodate
 578 many functions that use just one mutex to protect one data:
 579 .sp
 580 .in +2
 581 .nf
 582 /* CC thisfile.c -lthread   use C++ to compile*/
 583 
 584 #define _REENTRANT
 585 #include <stdlib.h>
 586 #include <stdio.h>
 587 #include <thread.h>
 588 #include <errno.h>
 589 #include <iostream.h>
 590 #define NUM_THREADS 16
 591 void *change_global_data(void *);     /*  for thr_create()   */
 592 
 593 class Mutected {
 594        private:
 595                static mutex_t      Global_mutex;
 596                static int          Global_data;
 597        public:
 598                static int          add_to_global_data(void);
 599                static int          subtract_from_global_data(void);
 600 };
 601 
 602 int Mutected::Global_data = 0;
 603 mutex_t Mutected::Global_mutex;
 604 
 605 int Mutected::add_to_global_data()  {
 606        mutex_lock(&Global_mutex);   
 607        Global_data++;
 608        mutex_unlock(&Global_mutex); 
 609        return Global_data;
 610 }
 611 
 612 int Mutected::subtract_from_global_data()   {
 613        mutex_lock(&Global_mutex);   
 614        Global_data--;
 615        mutex_unlock(&Global_mutex);
 616        return Global_data;
 617 }
 618 
 619 void
 620 main(int argc,char * argv[])  {
 621        int i=0;
 622        for (i=0;i< NUM_THREADS;i++)  {
 623             thr_create(NULL,0,change_global_data,NULL,0,NULL);
 624        }
 625        while ((thr_join(NULL,NULL,NULL) == 0));
 626 }
 627 
 628 void * change_global_data(void *)       {
 629        static int switcher = 0;
 630        if ((switcher++ % 3) == 0)   /* one-in-three threads subtracts */
 631                cout << Mutected::subtract_from_global_data() << endl;       
 632        else
 633                cout << Mutected::add_to_global_data() << endl;              
 634        return NULL;
 635 }
 636 .fi
 637 .in -2
 638 
 639 .SS "Interprocess Locking"
 640 .sp
 641 .LP
 642 A mutex can protect data that is shared among processes. The mutex would need
 643 to be initialized as  \fBUSYNC_PROCESS\fR. One process initializes the
 644 process-shared mutex and writes it to a file to be  mapped into memory by all
 645 cooperating processes (see \fBmmap\fR(2)). Afterwards, other independent
 646 processes can run the same program (whether concurrently or not) and share
 647 mutex-protected data.
 648 .sp
 649 .in +2
 650 .nf
 651 /* cc thisfile.c -lthread */
 652 /* To execute, run the command line "a.out 0 &; a.out 1" */
 653 
 654 #define _REENTRANT
 655 #include <sys/types.h>
 656 #include <sys/mman.h>
 657 #include <sys/stat.h>
 658 #include <fcntl.h>
 659 #include <stdio.h>
 660 #include <thread.h>
 661 #define INTERPROCESS_FILE "ipc-sharedfile"
 662 #define NUM_ADDTHREADS 12
 663 #define NUM_SUBTRACTTHREADS 10
 664 #define INCREMENT '0'
 665 #define DECREMENT '1'
 666 typedef struct {
 667                mutex_t     Interprocess_mutex;
 668                int         Interprocess_data;
 669 } buffer_t;
 670 buffer_t *buffer;
 671 
 672 void *add_interprocess_data(), *subtract_interprocess_data();
 673 void create_shared_memory(), test_argv();
 674 int zeroed[sizeof(buffer_t)];
 675 int ipc_fd, i=0;
 676 
 677 void
 678 main(int argc,char * argv[]){
 679     test_argv(argv[1]);
 680 
 681     switch (*argv[1])  {
 682     case INCREMENT:
 683          /* Initializes the process-shared mutex */
 684          /* Should be run prior to running a DECREMENT process */
 685          create_shared_memory();
 686          ipc_fd = open(INTERPROCESS_FILE, O_RDWR);
 687          buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t),
 688              PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0);
 689          buffer->Interprocess_data = 0;
 690          mutex_init(&buffer->Interprocess_mutex, USYNC_PROCESS,0);
 691          for (i=0; i< NUM_ADDTHREADS; i++)
 692          thr_create(NULL, 0, add_interprocess_data, argv[1],
 693              0, NULL);
 694          break;
 695 
 696     case DECREMENT:
 697          /* Should be run after the INCREMENT process has run. */
 698          while(ipc_fd = open(INTERPROCESS_FILE, O_RDWR)) == -1)
 699              sleep(1);
 700          buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t),
 701              PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0);
 702          for (i=0; i< NUM_SUBTRACTTHREADS; i++)
 703          thr_create(NULL, 0, subtract_interprocess_data, argv[1],
 704              0, NULL);
 705          break;
 706     } /* end switch */
 707 
 708     while ((thr_join(NULL,NULL,NULL) == 0));
 709 } /* end main */
 710 
 711 void *add_interprocess_data(char argv_1[]){
 712     mutex_lock(&buffer->Interprocess_mutex);
 713     buffer->Interprocess_data++;
 714     sleep(2);
 715     printf("%d is add-interprocess data, and %c is argv1\en",
 716         buffer->Interprocess_data, argv_1[0]);
 717     mutex_unlock(&buffer->Interprocess_mutex);
 718     return NULL;
 719 }
 720 
 721 void *subtract_interprocess_data(char argv_1[]) {
 722     mutex_lock(&buffer->Interprocess_mutex);
 723     buffer->Interprocess_data--;
 724     sleep(2);
 725     printf("%d is subtract-interprocess data, and %c is argv1\en",
 726         buffer->Interprocess_data, argv_1[0]);
 727     mutex_unlock(&buffer->Interprocess_mutex);
 728     return NULL;
 729 }
 730 
 731 void create_shared_memory(){
 732     int i;
 733     ipc_fd = creat(INTERPROCESS_FILE, O_CREAT | O_RDWR );
 734     for (i=0; i<sizeof(buffer_t); i++){
 735         zeroed[i] = 0;
 736         write(ipc_fd, &zeroed[i],2);
 737     }
 738     close(ipc_fd);
 739     chmod(INTERPROCESS_FILE, S_IRWXU | S_IRWXG | S_IRWXO);
 740 }
 741 
 742 void test_argv(char argv1[])   {
 743     if (argv1 == NULL)   {
 744     printf("use 0 as arg1 for initial process\en \e
 745     or use 1 as arg1 for the second process\en");
 746     exit(NULL);
 747     }
 748 }
 749 .fi
 750 .in -2
 751 
 752 .SS "Solaris Interprocess Robust Locking"
 753 .sp
 754 .LP
 755 A mutex can protect data that is shared among processes robustly. The mutex
 756 would need to be initialized as \fBUSYNC_PROCESS\fR | \fBLOCK_ROBUST\fR. One
 757 process initializes the robust process-shared mutex and writes it to a file to
 758 be mapped into memory by all cooperating processes (see \fBmmap\fR(2)).
 759 Afterwards, other independent processes can run the same program (whether
 760 concurrently or not) and share mutex-protected data.
 761 .sp
 762 .LP
 763 The following example shows how to use a \fBUSYNC_PROCESS\fR |
 764 \fBLOCK_ROBUST\fR type mutex.
 765 .sp
 766 .in +2
 767 .nf
 768 /* cc thisfile.c -lthread */
 769  /* To execute, run the command line "a.out & a.out 1" */
 770  #include <sys/types.h>
 771  #include <sys/mman.h>
 772  #include <fcntl.h>
 773  #include <stdio.h>
 774  #include <thread.h>
 775  #define INTERPROCESS_FILE "ipc-sharedfile"
 776  typedef struct {
 777            mutex_t   Interprocess_mutex;
 778            int       Interprocess_data;
 779  } buffer_t;
 780  buffer_t *buffer;
 781  int make_date_consistent();
 782  void create_shared_memory();
 783  int zeroed[sizeof(buffer_t)];
 784  int ipc_fd, i=0;
 785  main(int argc,char * argv[])  {
 786      int rc;
 787      if (argc > 1) {
 788          while((ipc_fd = open(INTERPROCESS_FILE, O_RDWR)) == -1)
 789              sleep(1);
 790          buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t),
 791                    PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0);
 792          mutex_init(&buffer->Interprocess_mutex,
 793                      USYNC_PROCESS | LOCK_ROBUST,0);
 794      } else {
 795          create_shared_memory();
 796          ipc_fd = open(INTERPROCESS_FILE, O_RDWR);
 797          buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t),
 798                PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0);
 799          buffer->Interprocess_data = 0;
 800          mutex_init(&buffer->Interprocess_mutex,
 801                      USYNC_PROCESS | LOCK_ROBUST,0);
 802      }
 803      for(;;) {
 804          rc = mutex_lock(&buffer->Interprocess_mutex);
 805          switch (rc) {
 806              case EOWNERDEAD:
 807                /*
 808                 * The lock is acquired.
 809                 * The last owner died holding the lock.
 810                 * Try to make the state associated with
 811                 * the mutex consistent.
 812                 * If successful, make the robust lock consistent.
 813                 */
 814                if (make_data_consistent())
 815                    mutex_consistent(&buffer->Interprocess_mutex);
 816                    mutex_unlock(&buffer->Interprocess_mutex);
 817                    break;
 818              case ENOTRECOVERABLE:
 819                /*
 820                 * The lock is not acquired.
 821                 * The last owner got the mutex with EOWNERDEAD
 822                 * and failed to make the data consistent.
 823                 * There is no way to recover, so just exit.
 824                 */
 825                exit(1);
 826              case 0:
 827                /*
 828                 * There is no error - data is consistent.
 829                 * Do something with data.
 830                 */
 831                mutex_unlock(&buffer->Interprocess_mutex);
 832                break;
 833         }
 834    }
 835 } /* end main */
 836 void create_shared_memory() {
 837       int i;
 838       ipc_fd = creat(INTERPROCESS_FILE, O_CREAT | O_RDWR );
 839       for (i=0; i<sizeof(buffer_t); i++) {
 840            zeroed[i] = 0;
 841            write(ipc_fd, &zeroed[i],2);
 842       }
 843       close(ipc_fd);
 844       chmod(INTERPROCESS_FILE, S_IRWXU | S_IRWXG | S_IRWXO);
 845  }
 846 
 847  /* return 1 if able to make data consistent, otherwise 0. */
 848  int make_data_consistent () {
 849        buffer->Interprocess_data = 0;
 850        return (1);
 851  }
 852 .fi
 853 .in -2
 854 
 855 .SS "Dynamically Allocated Mutexes"
 856 .sp
 857 .LP
 858 The following example allocates and frees memory in which a mutex is embedded.
 859 .sp
 860 .in +2
 861 .nf
 862 struct record {
 863         int field1;
 864         int field2;
 865         mutex_t m;
 866 } *r;
 867 r = malloc(sizeof(struct record));
 868 mutex_init(&r->m, USYNC_THREAD, NULL);
 869 /*
 870   * The fields in this record are accessed concurrently
 871   * by acquiring the embedded lock.
 872   */
 873 .fi
 874 .in -2
 875 
 876 .sp
 877 .LP
 878 The thread execution in this example is as follows:
 879 .sp
 880 .in +2
 881 .nf
 882 \fIThread 1 executes:\fR                 \fIThread 2 executes:\fR
 883 
 884 \&...                                ...
 885 mutex_lock(&r->m);                 mutex_lock(&r->m);
 886 r->field1++;                       localvar = r->field1;
 887 mutex_unlock(&r->m);               mutex_unlock(&r->m);
 888 \&...                                ...
 889 .fi
 890 .in -2
 891 
 892 .sp
 893 .LP
 894 Later, when a thread decides to free the memory pointed to by  \fIr\fR, the
 895 thread  should call  \fBmutex_destroy\fR(\|) on the mutexes in this memory.
 896 .sp
 897 .LP
 898 In the following example, the main thread can do a  \fBthr_join\fR(\|) on both
 899 of the above threads. If there are no other threads using the memory in
 900 \fIr\fR, the main thread can now safely free \fIr\fR:
 901 .sp
 902 .in +2
 903 .nf
 904 for (i = 0; i < 2; i++)
 905        thr_join(0, 0, 0);
 906 mutex_destroy(&r->m);   /* first destroy mutex */
 907 free(r);                /* then free memory */
 908 .fi
 909 .in -2
 910 
 911 .sp
 912 .LP
 913 If the mutex is not destroyed, the program could have memory leaks.
 914 .SH ATTRIBUTES
 915 .sp
 916 .LP
 917 See \fBattributes\fR(5) for descriptions of the following attributes:
 918 .sp
 919 
 920 .sp
 921 .TS
 922 box;
 923 c | c
 924 l | l .
 925 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 926 _
 927 Interface Stability     Stable
 928 _
 929 MT-Level        MT-Safe
 930 .TE
 931 
 932 .SH SEE ALSO
 933 .sp
 934 .LP
 935 \fBmmap\fR(2), \fBshmop\fR(2), \fBpthread_mutexattr_getprioceiling\fR(3C),
 936 \fBpthread_mutexattr_getprotocol\fR(3C), \fBpthread_mutexattr_getrobust\fR(3C),
 937 \fBpthread_mutexattr_gettype\fR(3C), \fBpthread_mutex_getprioceiling\fR(3C),
 938 \fBpthread_mutex_init\fR(3C), \fBattributes\fR(5), \fBmutex\fR(5),
 939 \fBstandards\fR(5)
 940 .SH NOTES
 941 .sp
 942 .LP
 943 Previous releases of Solaris provided the \fBUSYNC_PROCESS_ROBUST\fR mutex
 944 type. This type is now deprecated but is still supported for source and binary
 945 compatibility. When passed to \fBmutex_init()\fR, it is transformed into
 946 (\fBUSYNC_PROCESS\fR | \fBLOCK_ROBUST\fR). The former method for restoring a
 947 \fBUSYNC_PROCESS_ROBUST\fR mutex to a consistent state was to reinitialize it
 948 by calling \fBmutex_init()\fR. This method is still supported for source and
 949 binary compatibility, but the proper method is to call
 950 \fBmutex_consistent()\fR.
 951 .sp
 952 .LP
 953 The \fBUSYNC_PROCESS_ROBUST\fR type permitted an alternate error value,
 954 \fBELOCKUNMAPPED\fR, to be returned by \fBmutex_lock()\fR if the process
 955 containing a locked robust mutex unmapped the memory containing the mutex or
 956 performed one of the \fBexec\fR(2) functions. The \fBELOCKUNMAPPED\fR error
 957 value implies all of the consequences of the \fBEOWNERDEAD\fR error value and
 958 as such is just a synonym for \fBEOWNERDEAD\fR. For full source and binary
 959 compatibility, the \fBELOCKUNMAPPED\fR error value is still returned from
 960 \fBmutex_lock()\fR in these circumstances, but only if the mutex was
 961 initialized with the \fBUSYNC_PROCESS_ROBUST\fR type. Otherwise,
 962 \fBEOWNERDEAD\fR is returned in these circumstances.
 963 .sp
 964 .LP
 965 The \fBmutex_lock()\fR, \fBmutex_unlock()\fR, and \fBmutex_trylock()\fR
 966 functions do not validate the mutex type. An uninitialized mutex or a mutex
 967 with an invalid type does not return \fBEINVAL\fR. Interfaces for mutexes with
 968 an invalid type have unspecified behavior.
 969 .sp
 970 .LP
 971 Uninitialized mutexes that are allocated locally could contain junk data. Such
 972 mutexes need to be initialized using \fBmutex_init()\fR.
 973 .sp
 974 .LP
 975 By default, if multiple threads are waiting for a mutex, the order of
 976 acquisition is undefined.