RWLOCK man page on SmartOS

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

RWLOCK(3C)							    RWLOCK(3C)

NAME
       rwlock,	rwlock_init,  rwlock_destroy,  rw_rdlock, rw_wrlock, rw_tryrd‐
       lock, rw_trywrlock, rw_unlock - multiple readers, single writer locks

SYNOPSIS
       cc -mt [ flag... ] file...[ library... ]

       #include <synch.h>

       int rwlock_init(rwlock_t *rwlp, int type, void *arg);

       int rwlock_destroy(rwlock_t *rwlp);

       int rw_rdlock(rwlock_t *rwlp);

       int rw_wrlock(rwlock_t *rwlp);

       int rw_unlock(rwlock_t *rwlp);

       int rw_tryrdlock(rwlock_t *rwlp);

       int rw_trywrlock(rwlock_t *rwlp);

DESCRIPTION
       Many threads can have simultaneous read-only access to data, while only
       one  thread  can	 have  write  access  at any given time. Multiple read
       access with single write access is controlled by locks, which are  gen‐
       erally used to protect data that is frequently searched.

       Readers/writer  locks can synchronize threads in this process and other
       processes if they are allocated in writable memory   and	 shared	 among
       cooperating  processes (see mmap(2)), and are initialized for this pur‐
       pose.

       Additionally, readers/writer locks must be initialized  prior  to  use.
       The   readers/writer   lock  pointed  to	 by  rwlp  is  initialized  by
       rwlock_init(). A readers/writer lock is capable of having several types
       of  behavior,  which  is	 specified by type. arg is currently not used,
       although a future type may define  new behavior parameters  by  way  of
       arg.

       The type argument can be one of the following:

       USYNC_PROCESS
			 The  readers/writer  lock  can synchronize threads in
			 this process and other processes. The	readers/writer
			 lock  should be initialized by only one process.  arg
			 is ignored. A readers/writer  lock  initialized  with
			 this type, must be allocated in memory shared between
			 processses, i.e. either in Sys V shared  memory  (see
			 shmop(2))   or	 in  memory  mapped  to	 a  file  (see
			 mmap(2)).  It is illegal  to  initialize  the	object
			 this  way  and to not allocate it in such shared mem‐
			 ory.

       USYNC_THREAD
			 The readers/writer lock can synchronize   threads  in
			 this process, only.  arg is ignored.

       Additionally, readers/writer locks can be initialized by allocation  in
       zeroed memory. A type of USYNC_THREAD is assumed in this case. Multiple
       threads	must  not  simultaneously  initialize the same	readers/writer
       lock. And a readers/writer lock must not be re-initialized while in use
       by other threads.

       The  following  are  default readers/writer lock initialization (intra-
       process):

	 rwlock_t rwlp;
	 rwlock_init(&rwlp, NULL, NULL);

       or

	 rwlock_init(&rwlp, USYNC_THREAD, NULL);

       or

	 rwlock_t  rwlp	 =  DEFAULTRWLOCK;

       The following  is  a  customized	 readers/writer	 lock	initialization
       (inter-process):

	 rwlock_init(&rwlp, USYNC_PROCESS, NULL);

       Any  state  associated  with the readers/writer lock pointed to by rwlp
       are destroyed by	 rwlock_destroy() and the readers/writer lock  storage
       space is not released.

       rw_rdlock()  gets  a read lock on the readers/writer lock pointed to by
       rwlp. If the readers/writer lock is currently locked for	 writing,  the
       calling	thread	blocks until the write lock is freed. Multiple threads
       may simultaneously hold a read lock on a	 readers/writer lock.

       rw_tryrdlock() tries to get a read  lock	 on  the  readers/writer  lock
       pointed	to  by rwlp. If the readers/writer lock is locked for writing,
       it returns an error; otherwise, the read lock is acquired.

       rw_wrlock() gets a write lock on the readers/writer lock pointed to  by
       rwlp.  If  the  readers/writer  lock is currently locked for reading or
       writing, the calling thread blocks until all the read and  write	 locks
       are  freed. At any given time, only one thread may have a write lock on
       a readers/writer lock.

       rw_trywrlock() tries to get a write lock	 on  the  readers/writer  lock
       pointed	to by rwlp. If the readers/writer lock is currently locked for
       reading or writing, it returns an error.

       rw_unlock() unlocks a readers/writer lock pointed to by	rwlp,  if  the
       readers/writer lock is locked and the calling thread holds the lock for
       either reading or writing. One of the other threads that is waiting for
       the  readers/writer  lock to be freed will be unblocked, provided there
       are other waiting threads. If the calling thread does not hold the lock
       for  either  reading  or	 writing, no error status is returned, and the
       program's behavior is unknown.

RETURN VALUES
       If successful, these functions return 0. Otherwise, a non-zero value is
       returned to indicate the error.

ERRORS
       The rwlock_init() function will fail if:

       EINVAL
		  type is invalid.

       The  rw_tryrdlock() or rw_trywrlock() functions will fail if:

       EBUSY
		 The  readers/writer  lock  pointed  to	 by  rwlp  was already
		 locked.

       These functions may fail if:

       EFAULT
		  rwlp or arg points to an illegal address.

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

       ┌───────────────┬─────────────────┐
       │ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
       ├───────────────┼─────────────────┤
       │MT-Level       │ MT-Safe	 │
       └───────────────┴─────────────────┘

SEE ALSO
       mmap(2), attributes(5)

NOTES
       These interfaces also available by way of:

       #include <thread.h>

       If multiple threads are waiting for a readers/writer lock, the acquisi‐
       tion order is random by default. However, some implementations may bias
       acquisition order to avoid depriving writers. The  current  implementa‐
       tion favors writers over readers.

				 Dec 19, 2013			    RWLOCK(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