pthread_mutex_trylock man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

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 depen‐
       dent 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  pol‐
       icy 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)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net