Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for pthread_mutex_lock (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


       pthread_mutex_init,   pthread_mutex_lock,   pthread_mutex_trylock,   pthread_mutex_unlock,
       pthread_mutex_destroy - operations on mutexes

       #include <pthread.h>

       pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;

       pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;

       pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;

       int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr);

       int pthread_mutex_lock(pthread_mutex_t *mutex);

       int pthread_mutex_trylock(pthread_mutex_t *mutex);

       int pthread_mutex_unlock(pthread_mutex_t *mutex);

       int pthread_mutex_destroy(pthread_mutex_t *mutex);

       A mutex is a MUTual EXclusion device, and is useful for protecting shared data  structures
       from concurrent modifications, and implementing critical sections and monitors.

       A  mutex has two possible states: unlocked (not owned by any thread), and locked (owned by
       one thread). A mutex can never be owned by two different threads simultaneously. A  thread
       attempting to lock a mutex that is already locked by another thread is suspended until the
       owning thread unlocks the mutex first.

       pthread_mutex_init initializes the mutex object pointed to by mutex according to the mutex
       attributes  specified  in  mutexattr.   If  mutexattr is NULL, default attributes are used

       The LinuxThreads implementation supports only one mutex attributes, the mutex kind,  which
       is  either  ``fast'', ``recursive'', or ``error checking''. The kind of a mutex determines
       whether it can be locked again by a thread that already owns  it.   The	default  kind  is
       ``fast''. See pthread_mutexattr_init(3) for more information on mutex attributes.

       Variables  of type pthread_mutex_t can also be initialized statically, using the constants
       recursive   mutexes),  and  PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP  (for  error  checking

       pthread_mutex_lock locks the given mutex. If the mutex is currently unlocked,  it  becomes
       locked and owned by the calling thread, and pthread_mutex_lock returns immediately. If the
       mutex is already locked by another thread, pthread_mutex_lock suspends the calling  thread
       until the mutex is unlocked.

       If  the	mutex is already locked by the calling thread, the behavior of pthread_mutex_lock
       depends on the kind of the mutex. If the mutex is of the ``fast'' kind, the calling thread
       is  suspended  until the mutex is unlocked, thus effectively causing the calling thread to
       deadlock. If the mutex is of the ``error checking'' kind, pthread_mutex_lock returns imme-
       diately	with  the  error  code	EDEADLK.   If  the  mutex  is  of the ``recursive'' kind,
       pthread_mutex_lock succeeds and returns immediately, recording the  number  of  times  the
       calling	thread	has  locked the mutex. An equal number of pthread_mutex_unlock operations
       must be performed before the mutex returns to the unlocked state.

       pthread_mutex_trylock behaves identically to pthread_mutex_lock, except that it	does  not
       block the calling thread if the mutex is already locked by another thread (or by the call-
       ing thread in the case of a ``fast'' mutex). Instead, pthread_mutex_trylock returns  imme-
       diately with the error code EBUSY.

       pthread_mutex_unlock  unlocks the given mutex. The mutex is assumed to be locked and owned
       by the calling thread on entrance  to  pthread_mutex_unlock.   If  the  mutex  is  of  the
       ``fast''  kind,	pthread_mutex_unlock always returns it to the unlocked state. If it is of
       the ``recursive''  kind,  it  decrements  the  locking  count  of  the  mutex  (number  of
       pthread_mutex_lock  operations  performed on it by the calling thread), and only when this
       count reaches zero is the mutex actually unlocked.

       On ``error checking'' mutexes, pthread_mutex_unlock actually checks at run-time	that  the
       mutex is locked on entrance, and that it was locked by the same thread that is now calling
       pthread_mutex_unlock.  If these conditions are not met, an error code is returned and  the
       mutex  remains unchanged.  ``Fast'' and ``recursive'' mutexes perform no such checks, thus
       allowing a locked mutex to be unlocked by a thread other than its owner. This is  non-por-
       table behavior and must not be relied upon.

       pthread_mutex_destroy  destroys	a  mutex object, freeing the resources it might hold. The
       mutex must be unlocked on entrance. In the LinuxThreads implementation, no  resources  are
       associated  with  mutex	objects,  thus pthread_mutex_destroy actually does nothing except
       checking that the mutex is unlocked.

       None of the mutex functions is a cancellation point, not even pthread_mutex_lock, in spite
       of  the fact that it can suspend a thread for arbitrary durations. This way, the status of
       mutexes at cancellation points is predictable, allowing cancellation  handlers  to  unlock
       precisely those mutexes that need to be unlocked before the thread stops executing. Conse-
       quently, threads using deferred cancellation should never hold a mutex for extended  peri-
       ods of time.

       The  mutex functions are not async-signal safe. What this means is that they should not be
       called  from  a	 signal   handler.   In   particular,	calling   pthread_mutex_lock   or
       pthread_mutex_unlock from a signal handler may deadlock the calling thread.

       pthread_mutex_init  always  returns 0. The other mutex functions return 0 on success and a
       non-zero error code on error.

       The pthread_mutex_lock function returns the following error code on error:

	      EINVAL the mutex has not been properly initialized.

		     the mutex is already  locked  by  the  calling  thread  (``error  checking''
		     mutexes only).

       The pthread_mutex_trylock function returns the following error codes on error:

	      EBUSY  the mutex could not be acquired because it was currently locked.

	      EINVAL the mutex has not been properly initialized.

       The pthread_mutex_unlock function returns the following error code on error:

	      EINVAL the mutex has not been properly initialized.

	      EPERM  the calling thread does not own the mutex (``error checking'' mutexes only).

       The pthread_mutex_destroy function returns the following error code on error:

	      EBUSY  the mutex is currently locked.

       Xavier Leroy <Xavier.Leroy@inria.fr>

       pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3), pthread_cancel(3).

       A shared global variable x can be protected by a mutex as follows:

	      int x;
	      pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

       All accesses and modifications to x should be bracketed by calls to pthread_mutex_lock and
       pthread_mutex_unlock as follows:

	      /* operate on x */

					   LinuxThreads 			 PTHREAD_MUTEX(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 10:40 PM.