1rwlock(3C)               Standard C Library Functions               rwlock(3C)
2
3
4

NAME

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

SYNOPSIS

10       cc -mt [ flag... ] file...[ library... ]
11
12       #include <synch.h>
13
14       int rwlock_init(rwlock_t *rwlp, int type, void * arg);
15
16
17       int rwlock_destroy(rwlock_t *rwlp);
18
19
20       int rw_rdlock(rwlock_t *rwlp);
21
22
23       int rw_wrlock(rwlock_t *rwlp);
24
25
26       int rw_unlock(rwlock_t *rwlp);
27
28
29       int rw_tryrdlock(rwlock_t *rwlp);
30
31
32       int rw_trywrlock(rwlock_t *rwlp);
33
34

DESCRIPTION

36       Many threads can have simultaneous read-only access to data, while only
37       one  thread  can  have  write  access  at any given time. Multiple read
38       access with single write access is controlled by locks, which are  gen‐
39       erally used to protect data that is frequently searched.
40
41
42       Readers/writer  locks can synchronize threads in this process and other
43       processes if they are allocated in writable memory   and  shared  among
44       cooperating  processes (see mmap(2)), and are initialized for this pur‐
45       pose.
46
47
48       Additionally, readers/writer locks must be initialized  prior  to  use.
49       rwlock_init() The readers/writer lock pointed to by rwlp is initialized
50       by  rwlock_init(). A readers/writer lock is capable of  having  several
51       types  of  behavior,  which  is specified by type. arg is currently not
52       used, although a future type may define  new behavior parameters by way
53       of  arg.
54
55
56       The type argument can be one of the following:
57
58       USYNC_PROCESS     The  readers/writer  lock  can synchronize threads in
59                         this process and other processes. The  readers/writer
60                         lock  should  be initialized by only one process. arg
61                         is ignored. A readers/writer  lock  initialized  with
62                         this type, must be allocated in memory shared between
63                         processses, i.e. either in Sys V shared  memory  (see
64                         shmop(2))   or  in  memory  mapped  to  a  file  (see
65                         mmap(2)). It is illegal to initialize the object this
66                         way and to not allocate it in such shared memory.
67
68
69       USYNC_THREAD      The  readers/writer  lock can synchronize  threads in
70                         this process, only. arg is ignored.
71
72
73
74       Additionally, readers/writer locks can be initialized by allocation  in
75       zeroed memory. A type of USYNC_THREAD is assumed in this case. Multiple
76       threads must not simultaneously  initialize  the  same   readers/writer
77       lock. And a readers/writer lock must not be re-initialized while in use
78       by other threads.
79
80
81       The following are default readers/writer  lock  initialization  (intra-
82       process):
83
84         rwlock_t rwlp;
85         rwlock_init(&rwlp, NULL, NULL);
86
87
88
89
90       or
91
92         rwlock_init(&rwlp, USYNC_THREAD, NULL);
93
94
95
96       or
97
98         rwlock_t  rwlp  =  DEFAULTRWLOCK;
99
100
101
102       The  following  is  a  customized  readers/writer  lock  initialization
103       (inter-process):
104
105         rwlock_init(&rwlp, USYNC_PROCESS, NULL);
106
107
108
109       Any state associated with the readers/writer lock pointed  to  by  rwlp
110       are  destroyed by  rwlock_destroy() and the readers/writer lock storage
111       space is not released.
112
113
114       rw_rdlock() gets a read lock on the readers/writer lock pointed  to  by
115       rwlp.  If  the readers/writer lock is currently locked for writing, the
116       calling thread blocks until the write lock is freed.  Multiple  threads
117       may simultaneously hold a read lock on a  readers/writer lock.
118
119
120       rw_tryrdlock()  trys  to  get  a  read  lock on the readers/writer lock
121       pointed to by rwlp. If the readers/writer lock is locked  for  writing,
122       it returns an error; otherwise, the read lock is acquired.
123
124
125       rw_wrlock()  gets a write lock on the readers/writer lock pointed to by
126       rwlp. If the readers/writer lock is currently  locked  for  reading  or
127       writing,  the  calling thread blocks until all the read and write locks
128       are freed. At any given time, only one thread may have a write lock  on
129       a  readers/writer lock.
130
131
132       rw_trywrlock()  trys  to  get  a  write lock on the readers/writer lock
133       pointed to by rwlp. If the readers/writer lock is currently locked  for
134       reading or writing, it returns an error.
135
136
137       rw_unlock()  unlocks  a readers/writer lock pointed to by  rwlp, if the
138       readers/writer lock is locked and the calling thread holds the lock for
139       either reading or writing. One of the other threads that is waiting for
140       the readers/writer  lock to be freed will be unblocked, provided  there
141       is  other waiting threads. If the calling thread does not hold the lock
142       for either reading or writing, no error status  is  returned,  and  the
143       program's behavior is unknown.
144

RETURN VALUES

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

ERRORS

150       The rwlock_init() function will fail if:
151
152       EINVAL     type is invalid.
153
154
155
156       The  rw_tryrdlock() or rw_trywrlock() functions will fail if:
157
158       EBUSY     The reader or writer lock pointed  to  by  rwlp  was  already
159                 locked.
160
161
162
163       These functions may fail if:
164
165       EFAULT     rwlp or arg points to an illegal address.
166
167

ATTRIBUTES

169       See attributes(5) for descriptions of the following attributes:
170
171
172
173
174       ┌─────────────────────────────┬─────────────────────────────┐
175       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
176       ├─────────────────────────────┼─────────────────────────────┤
177       │MT-Level                     │MT-Safe                      │
178       └─────────────────────────────┴─────────────────────────────┘
179

SEE ALSO

181       mmap(2), attributes(5)
182

NOTES

184       These interfaces also available by way of:
185
186
187       #include <thread.h>
188
189
190       If multiple threads are waiting for a readers/writer lock, the acquisi‐
191       tion order is random by default. However, some implementations may bias
192       acquisition  order  to avoid depriving writers. The current implementa‐
193       tion favors writers over readers.
194
195
196
197SunOS 5.11                        14 May 1998                       rwlock(3C)
Impressum