pthread_mutex_trylock man page on SmartOS

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

PTHREAD_MUTEX_LOCK(3C)					PTHREAD_MUTEX_LOCK(3C)

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

SYNOPSIS
       cc -mt [ flag... ] file... -lpthread [ library... ]
       #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   is	 locked	  by   calling
       pthread_mutex_lock().  If  the  mutex  is  already  locked, the calling
       thread blocks until the mutex becomes available. 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  PTHREAD_MUTEX_NORMAL, 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  that  is
       unlocked, undefined behavior results.

       If  the mutex type is  PTHREAD_MUTEX_ERRORCHECK, then error checking is
       provided. If a thread attempts to relock a mutex that  it  has  already
       locked,	an  error  will	 be returned. If a thread attempts to unlock a
       mutex that it has not locked or a mutex which  is  unlocked,  an	 error
       will be returned.

       If  the	mutex  type is	PTHREAD_MUTEX_RECURSIVE, then the mutex	 main‐
       tains the concept of a lock count. When a thread successfully  acquires
       a  mutex	 for  the first time, the lock count is set to 1. Every time a
       thread relocks this mutex, the lock count is  incremented by one.  Each
       time  the  thread  unlocks  the mutex, the lock count is decremented by
       one. When the lock count reaches 0, the	mutex  becomes	available  for
       other  threads  to acquire. If a thread attempts to unlock a mutex that
       it has not locked or a  mutex  that  is	unlocked,  an  error  will  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	is     identical    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 fails immediately with EBUSY.

       The pthread_mutex_unlock() function releases the	 mutex	object	refer‐
       enced  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  is
       used to determine  which thread will acquire the mutex. (In the case of
       PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available  when  the
       count reaches  0 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 resumes waiting for the mutex as if
       it was not interrupted.

RETURN VALUES
       If successful,  the   pthread_mutex_lock()  and	pthread_mutex_unlock()
       functions return	 0. Otherwise, an error number is returned to indicate
       the error.

       The  pthread_mutex_trylock() function returns  0 if a lock on the mutex
       object  referenced  by mutex is acquired. Otherwise, an error number is
       returned to indicate the error.

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

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

       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.

       EPERM
		 The mutex was created with the protocol attribute having  the
		 value	PTHREAD_PRIO_PROTECT  and the calling thread is not in
		 the  real-time	 class	(SCHED_RR  or  SCHED_FIFO   scheduling
		 class).

       The  pthread_mutex_trylock() function will 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.

       The  pthread_mutex_lock() function may fail if:

       EDEADLK
		  The current thread already owns the mutex.

       ENOMEM
		  The  limit  on the number of simultaneously held mutexes has
		  been exceeded.

       The  pthread_mutex_unlock() function will fail if:

       EPERM
		The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex	 is  a
		robust mutex, and the current thread does not own the mutex.

       When    a    thread   makes   a	 call	to   pthread_mutex_lock()   or
       pthread_mutex_trylock(), if the mutex is initialized with  the  robust‐
       ness    attribute    having   the   value   PTHREAD_MUTEX_ROBUST	  (see
       pthread_mutexattr_getrobust(3C)), the call will return these error val‐
       ues if:

       EOWNERDEAD
			  The  last owner of this mutex died while holding the
			  mutex, or the process containing the	owner  of  the
			  mutex	 unmapped  the	memory containing the mutex or
			  performed one of the exec(2) functions.  This	 mutex
			  is  now  owned  by  the  caller. The caller must now
			  attempt to make the state  protected	by  the	 mutex
			  consistent.  If  it  is  able to clean up the state,
			  then it should call  pthread_mutex_consistent()  for
			  the  mutex and unlock the mutex. Subsequent calls to
			  pthread_mutex_lock()	 and   pthread_mutex_trylock()
			  will	behave	normally,  as before. If the caller is
			  not able to clean up the  state,  pthread_mutex_con‐
			  sistent()  should  not  be called for the mutex, but
			  the mutex should be unlocked.	 Subsequent  calls  to
			  pthread_mutex_lock()	 and   pthread_mutex_trylock()
			  will fail to acquire the mutex with the error	 value
			  ENOTRECOVERABLE.  If the owner who acquired the lock
			  with EOWNERDEAD dies, the next  owner	 will  acquire
			  the lock with EOWNERDEAD.

       ENOTRECOVERABLE
			  The  mutex  trying to be acquired was protecting the
			  state	 that  has  been  left	irrecoverable  by  the
			  mutex's last owner. The mutex has not been acquired.
			  This condition can occur when the  lock  was	previ‐
			  ously	 acquired  with	 EOWNERDEAD, and the owner was
			  not able to clean up	the  state  and	 unlocked  the
			  mutex without calling pthread_mutex_consistent().

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬───────────────────┐
       │  ATTRIBUTE TYPE    │  ATTRIBUTE VALUE	│
       ├────────────────────┼───────────────────┤
       │Interface Stability │ Committed		│
       ├────────────────────┼───────────────────┤
       │MT-Level	    │ MT-Safe		│
       ├────────────────────┼───────────────────┤
       │Standard	    │ See standards(5). │
       └────────────────────┴───────────────────┘

SEE ALSO
       pthread_mutex_consistent(3C),   pthread_mutex_init(3C),	pthread_mutex‐
       attr_setprotocol(3C),  pthread_mutexattr_setrobust(3C),	pthread_mutex‐
       attr_settype(3C), attributes(5), standards(5)

NOTES
       In   the	  current  implementation  of  threads,	 pthread_mutex_lock(),
       pthread_mutex_unlock(),		mutex_lock(),	       mutex_unlock(),
       pthread_mutex_trylock(),	 and mutex_trylock() do not validate the mutex
       type.  Therefore, an uninitialized mutex or a  mutex  with  an  invalid
       type  does  not	return	EINVAL. Interfaces for mutexes with an invalid
       type have unspecified behavior.

       Uninitialized mutexes that are allocated locally may contain junk data.
       Such  mutexes  need  to	be  initialized using  pthread_mutex_init() or
       mutex_init().

				 Nov 11, 2008		PTHREAD_MUTEX_LOCK(3C)
[top]

List of man pages available for SmartOS

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