pthread_mutex_lock(3) [osf1 man page]

pthread_mutex_lock(3)					     Library Functions Manual					     pthread_mutex_lock(3)

NAME

       pthread_mutex_lock - Locks an unlocked mutex.

LIBRARY

       DECthreads POSIX 1003.1c Library (libpthread.so)

SYNOPSIS

       #include <pthread.h>

       int   pthread_mutex_lock(
			      pthread_mutex_t	*mutex);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS

       Mutex to be locked.

DESCRIPTION

       This  routine  locks  a	mutex  with behavior that depends upon the type of mutex, as follows: If a normal or default mutex is specified, a
       deadlock can result if the current owner of the mutex calls this routine in an attempt to lock the mutex a second time.	(The  deadlock	is
       not  detected  or reported.)  If a recursive mutex is specified, the current owner of the mutex can relock the same mutex without blocking.
       The lock count is incremented for each recursive lock within the thread.  If an errorcheck mutex is specified and the current  owner  tries
       to  lock  the  mutex a second time, this routine reports the [EDEADLK] error.  If the mutex is locked by another thread, the calling thread
       waits for the mutex to become available.

       Use the pthread_mutexattr_settype(3) routine to set the type of the mutex to normal, default, recursive, or errorcheck. For  more  informa-
       tion about types of mutexes, see the desciption of pthread_mutexattr_settype(3).

       The  thread  that  has  locked a mutex becomes its current owner and remains its owner until the same thread has unlocked it.  This routine
       returns with the mutex in the locked state and with the current thread as the mutex's current owner.

       A recursive or errorcheck mutex records the identity of the thread that locks it, allowing debuggers to display this information.  In  most
       cases, normal and default mutexes do not record the owning thread's identity.

RETURN VALUES

       If  an  error condition occurs, this routine returns an integer value indicating the type of error.  Possible return values are as follows:
       Successful completion.  A deadlock condition is detected.  The value specified by mutex is not a valid mutex.

ERRORS

       None

RELATED INFORMATION

       Functions: pthread_mutexattr_settype(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_trylock(3), pthread_mutex_unlock(3)

       Manuals: Guide to DECthreads and Programmer's Guide

       delim off

															     pthread_mutex_lock(3)

pthread_mutex_lock(3T)													    pthread_mutex_lock(3T)

NAME

       pthread_mutex_lock(), pthread_mutex_trylock() - lock or attempt to lock a mutex

SYNOPSIS

PARAMETERS

	      mutex	Pointer to the mutex to be locked.

DESCRIPTION

       The  mutex  object mutex is locked by calling the function.  How the calling thread acquires the mutex is dependent upon the type attribute
       for the mutex.  This operation returns with the mutex object referenced by mutex in the locked state with the calling thread as its owner.

       If the mutex type is deadlock detection is not provided.  Attempting to relock the mutex causes deadlock.  If a thread attempts to unlock a
       mutex that it has not locked or a mutex which is unlocked, undefined behavior results.

       If  the	mutex  type is the mutex maintains the concept of an owner.  If a thread attempts to relock a mutex that it has already locked, an
       error shall be returned.  If a thread attempts to unlock a mutex that it has not locked or a mutex that is  unlocked,  an  error  shall	be
       returned.

       If  the	mutex  type is then the mutex maintains the concept of an owner and a lock count.  When a thread successfully acquires a mutex for
       the first time, the count field shall be set to one.  Every time a thread relocks this mutex, the count field shall be incremented by  one.
       Each  time  the	thread unlocks the mutex, the count field shall be decremented by one.	When the count field reaches zero, the mutex shall
       become available for other threads to acquire.  If a thread attempts to unlock a mutex that it has not locked, an error shall be returned.

       If the mutex type is deadlock detection is not provided.  Attempting to relock the mutex causes deadlock.  A thread can unlock a mutex that
       it has not locked.  Attempting to unlock an unlocked mutex results in undefined behavior.

       If  the mutex type is attempting to recursively lock the mutex results in undefined behavior.  Attempting to unlock the mutex if it was not
       locked by the calling thread results in undefined behavior.  Attempting to unlocked the mutex if it is  not  locked  results  in  undefined
       behavior.

       The  function  is  identical  to the function except that if the mutex object referenced by mutex cannot be acquired after one attempt, the
       call returns immediately with an error.

       If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler, the thread  shall  resume  waiting  for  the
       mutex as if it was not interrupted.

RETURN VALUE

       Upon successful completion, and return zero.  Otherwise, an error number is returned to indicate the error (the variable is not set).

ERRORS

       If any of the following occur, the and functions return the corresponding error number:

	      [EINVAL]	     mutex is a mutex and the caller's priority is higher than mutex's priority ceiling.

       If any of the following occur, the function returns the corresponding error number:

	      [EBUSY]	     mutex is currently locked by another thread.

       If any of the following occur, the and functions return the corresponding error number:

	      [EAGAIN]	     mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.  This error is
			     not detected on HP-UX.

	      [EINVAL]	     mutex is not an initialized mutex.

	      [EFAULT]	     mutex parameter points to an illegal address.

       If any of the following occur, the function returns the corresponding error number:

	      [EDEADLK]      The current thread already owns the mutex.  This error will be detected only for mutexes on HP-UX.

WARNINGS

       A recursive mutex can be locked more than once by the same thread without causing that thread to deadlock.  Undefined behavior  may  result
       if the owner of a recursive mutex tries to lock the mutex too many times.

AUTHOR

       and was derived from the IEEE POSIX P1003.1c standard and X/Open

SEE ALSO

       pthread_mutex_init(3T), pthread_mutex_destroy(3T), pthread_mutex_unlock(3T).

STANDARDS CONFORMANCE

								  Pthread Library					    pthread_mutex_lock(3T)