1rwlock(3C) Standard C Library Functions rwlock(3C)
2
6 rwlock, rwlock_init, rwlock_destroy, rw_rdlock, rw_wrlock, rw_tryrd‐
7 lock, rw_trywrlock, rw_unlock - multiple readers, single writer locks
8
10 cc -mt [ flag... ] file...[ library... ]
11 #include <synch.h>
13 int rwlock_init(rwlock_t *rwlp, int type, void * arg);
15 int rwlock_destroy(rwlock_t *rwlp);
18 int rw_rdlock(rwlock_t *rwlp);
21 int rw_wrlock(rwlock_t *rwlp);
24 int rw_unlock(rwlock_t *rwlp);
27 int rw_tryrdlock(rwlock_t *rwlp);
30 int rw_trywrlock(rwlock_t *rwlp);
33
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 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 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 The type argument can be one of the following:
57 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 USYNC_THREAD The readers/writer lock can synchronize threads in
70 this process, only. arg is ignored.
71 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 The following are default readers/writer lock initialization (intra-
82 process):
83 rwlock_t rwlp;
85 rwlock_init(&rwlp, NULL, NULL);
86 or
91 rwlock_init(&rwlp, USYNC_THREAD, NULL);
93 or
97 rwlock_t rwlp = DEFAULTRWLOCK;
99 The following is a customized readers/writer lock initialization
103 (inter-process):
104 rwlock_init(&rwlp, USYNC_PROCESS, NULL);
106 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 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 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 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 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 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
146 If successful, these functions return 0. Otherwise, a non-zero value is
147 returned to indicate the error.
148
150 The rwlock_init() function will fail if:
151 EINVAL type is invalid.
153 The rw_tryrdlock() or rw_trywrlock() functions will fail if:
157 EBUSY The reader or writer lock pointed to by rwlp was already
159 locked.
160 These functions may fail if:
164 EFAULT rwlp or arg points to an illegal address.
166
169 See attributes(5) for descriptions of the following attributes:
170 ┌─────────────────────────────┬─────────────────────────────┐
175 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
176 ├─────────────────────────────┼─────────────────────────────┤
177 │MT-Level │MT-Safe │
178 └─────────────────────────────┴─────────────────────────────┘
179
181 mmap(2), attributes(5)
182
184 These interfaces also available by way of:
185 #include <thread.h>
188 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.
194SunOS 5.11 14 May 1998 rwlock(3C)