Yolinux.com

pthread_mutex_unlock manpage

Search topic Section
Get manual page for the search topic
List all commands matching the search topic
List all topics in the manpage index

PTHREAD_MUTEX_LOCK(P)	   POSIX Programmer's Manual	 PTHREAD_MUTEX_LOCK(P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock -  lock
       and unlock a mutex

SYNOPSIS
       #include <pthread.h>

       int pthread_mutex_lock(pthread_mutex_t *mutex);
       int pthread_mutex_trylock(pthread_mutex_t *mutex);
       int pthread_mutex_unlock(pthread_mutex_t *mutex);


DESCRIPTION
       The  mutex  object  referenced  by  mutex  shall	 be  locked by calling
       pthread_mutex_lock(). If the  mutex  is	already	 locked,  the  calling
       thread  shall  block until the mutex becomes available.	This operation
       shall return with the mutex object referenced by mutex  in  the	locked
       state with the calling thread as its owner.

       If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection shall not
       be 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  PTHREAD_MUTEX_ERRORCHECK,	 then  error  checking
       shall  be  provided. 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 which is unlocked, an
       error shall be returned.

       If the mutex type is  PTHREAD_MUTEX_RECURSIVE,  then  the  mutex	 shall
       maintain	 the  concept  of  a  lock  count.  When a thread successfully
       acquires a mutex for the first time, the lock count  shall  be  set  to
       one.  Every  time  a thread relocks this mutex, the lock count shall be
       incremented by one. Each time the thread unlocks the  mutex,  the  lock
       count  shall  be	 decremented by one. When the lock count 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 or a mutex
       which is unlocked, an error shall be returned.

       If the mutex type is PTHREAD_MUTEX_DEFAULT, 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 unlock the mutex if it is not locked results in
       undefined behavior.

       The   pthread_mutex_trylock()   function	  shall	  be   equivalent   to
       pthread_mutex_lock(),  except  that  if	the mutex object referenced by
       mutex is	 currently  locked  (by	 any  thread,  including  the  current
       thread),	 the  call  shall  return  immediately.	 If  the mutex type is
       PTHREAD_MUTEX_RECURSIVE and the mutex is currently owned by the calling
       thread,	the  mutex  lock  count	 shall	be  incremented by one and the
       pthread_mutex_trylock() function shall immediately return success.

       The pthread_mutex_unlock() function shall release the mutex object ref-
       erenced	by  mutex.     The  manner  in	which  a  mutex is released is
       dependent upon the  mutex's  type  attribute.   If  there  are  threads
       blocked	  on	the    mutex   object	referenced   by	  mutex	  when
       pthread_mutex_unlock() is  called,  resulting  in  the  mutex  becoming
       available,  the	scheduling  policy  shall determine which thread shall
       acquire the mutex.

       (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become
       available  when the count reaches zero and the calling thread no longer
       has any locks on this mutex.)

       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
       If  successful,	the  pthread_mutex_lock()  and	pthread_mutex_unlock()
       functions  shall	 return	 zero;	otherwise,  an	error  number shall be
       returned to indicate the error.

       The pthread_mutex_trylock() function shall return zero if a lock on the
       mutex  object referenced by mutex is acquired. Otherwise, an error num-
       ber is returned to indicate the error.

ERRORS
       The pthread_mutex_lock() and  pthread_mutex_trylock()  functions	 shall
       fail if:

       EINVAL The  mutex  was  created	with the protocol attribute having the
	      value PTHREAD_PRIO_PROTECT and the calling thread's priority  is
	      higher than the mutex's current priority ceiling.


       The pthread_mutex_trylock() function shall fail if:

       EBUSY  The mutex could not be acquired because it was already locked.


       The	 pthread_mutex_lock(),	     pthread_mutex_trylock(),	   and
       pthread_mutex_unlock() functions may fail if:

       EINVAL The value specified by mutex does not refer  to  an  initialized
	      mutex object.

       EAGAIN The  mutex  could	 not be acquired because the maximum number of
	      recursive locks for mutex has been exceeded.


       The pthread_mutex_lock() function may fail if:

       EDEADLK
	      The current thread already owns the mutex.


       The pthread_mutex_unlock() function may fail if:

       EPERM  The current thread does not own the mutex.


       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       Mutex objects are intended to serve as a low-level primitive from which
       other  thread  synchronization  functions  can  be  built. As such, the
       implementation of mutexes should be as efficient as possible, and  this
       has ramifications on the features available at the interface.

       The  mutex  functions  and the particular default settings of the mutex
       attributes have been motivated by the  desire  to  not  preclude	 fast,
       inlined implementations of mutex locking and unlocking.

       For  example, deadlocking on a double-lock is explicitly allowed behav-
       ior in order to avoid requiring more overhead in	 the  basic  mechanism
       than  is	 absolutely  necessary.	 (More	"friendly" mutexes that detect
       deadlock or that allow multiple locking by the same thread  are	easily
       constructed by the user via the other mechanisms provided. For example,
       pthread_self() can be used to record mutex ownership.)  Implementations
       might also choose to provide such extended features as options via spe-
       cial mutex attributes.

       Since most attributes only need to be checked when a thread is going to
       be  blocked,  the  use  of attributes does not slow the (common) mutex-
       locking case.

       Likewise, while being able to extract the thread ID of the owner	 of  a
       mutex  might  be desirable, it would require storing the current thread
       ID when each mutex is locked, and this could incur unacceptable	levels
       of overhead. Similar arguments apply to a mutex_tryunlock operation.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread_mutex_destroy()	, pthread_mutex_timedlock() , the Base Defini-
       tions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version 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 .



IEEE/The Open Group		     2003		 PTHREAD_MUTEX_LOCK(P)
YoLinux.com Home Page
YoLinux Tutorial Index
Privacy Policy | Advertise with us | Feedback Form |
Unauthorized copying or redistribution prohibited.
    Bookmark and Share