Print this page
4327 rwlock(3c): Formatting issues and typos
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/rwlock.3c
+++ new/usr/src/man/man3c/rwlock.3c
1 1 '\" te
2 2 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved
3 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH RWLOCK 3C "May 14, 1998"
6 +.TH RWLOCK 3C "Dec 19, 2013"
7 7 .SH NAME
8 8 rwlock, rwlock_init, rwlock_destroy, rw_rdlock, rw_wrlock, rw_tryrdlock,
9 9 rw_trywrlock, rw_unlock \- multiple readers, single writer locks
10 10 .SH SYNOPSIS
11 11 .LP
12 12 .nf
13 13 cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ]
14 14
15 15 #include <synch.h>
16 16
17 -\fBint\fR \fBrwlock_init\fR(\fBrwlock_t *\fR\fIrwlp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR \fIarg\fR);
17 +\fBint\fR \fBrwlock_init\fR(\fBrwlock_t *\fR\fIrwlp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
18 18 .fi
19 19
20 20 .LP
21 21 .nf
22 22 \fBint\fR \fBrwlock_destroy\fR(\fBrwlock_t *\fR\fIrwlp\fR);
23 23 .fi
24 24
25 25 .LP
26 26 .nf
27 27 \fBint\fR \fBrw_rdlock\fR(\fBrwlock_t *\fR\fIrwlp\fR);
28 28 .fi
29 29
30 30 .LP
31 31 .nf
32 32 \fBint\fR \fBrw_wrlock\fR(\fBrwlock_t *\fR\fIrwlp\fR);
33 33 .fi
34 34
35 35 .LP
36 36 .nf
37 37 \fBint\fR \fBrw_unlock\fR(\fBrwlock_t *\fR\fIrwlp\fR);
38 38 .fi
39 39
40 40 .LP
41 41 .nf
42 42 \fBint\fR \fBrw_tryrdlock\fR(\fBrwlock_t *\fR\fIrwlp\fR);
43 43 .fi
44 44
45 45 .LP
46 46 .nf
47 47 \fBint\fR \fBrw_trywrlock\fR(\fBrwlock_t *\fR\fIrwlp\fR);
48 48 .fi
49 49
50 50 .SH DESCRIPTION
51 51 .sp
52 52 .LP
53 53 Many threads can have simultaneous read-only access to data, while only one
54 54 thread can have write access at any given time. Multiple read access with
55 55 single write access is controlled by locks, which are generally used to protect
|
↓ open down ↓ |
28 lines elided |
↑ open up ↑ |
56 56 data that is frequently searched.
57 57 .sp
58 58 .LP
59 59 Readers/writer locks can synchronize threads in this process and other
60 60 processes if they are allocated in writable memory and shared among
61 61 cooperating processes (see \fBmmap\fR(2)), and are initialized for this
62 62 purpose.
63 63 .sp
64 64 .LP
65 65 Additionally, readers/writer locks must be initialized prior to use.
66 -\fBrwlock_init()\fR The readers/writer lock pointed to by \fIrwlp\fR is
66 +The readers/writer lock pointed to by \fIrwlp\fR is
67 67 initialized by \fBrwlock_init()\fR. A readers/writer lock is capable of having
68 -several types of behavior, which is specified by \fBtype\fR. \fIarg\fR is
68 +several types of behavior, which is specified by \fItype\fR. \fIarg\fR is
69 69 currently not used, although a future type may define new behavior parameters
70 70 by way of \fIarg\fR.
71 71 .sp
72 72 .LP
73 73 The \fItype\fR argument can be one of the following:
74 74 .sp
75 75 .ne 2
76 76 .na
77 77 \fB\fBUSYNC_PROCESS\fR \fR
78 78 .ad
79 79 .RS 18n
80 80 The readers/writer lock can synchronize threads in this process and other
81 81 processes. The readers/writer lock should be initialized by only one process.
82 82 \fIarg\fR is ignored. A readers/writer lock initialized with this type, must be
83 83 allocated in memory shared between processses, i.e. either in Sys V shared
84 84 memory (see \fBshmop\fR(2)) or in memory mapped to a file (see \fBmmap\fR(2)).
85 85 It is illegal to initialize the object this way and to not allocate it in such
86 86 shared memory.
87 87 .RE
88 88
89 89 .sp
90 90 .ne 2
91 91 .na
|
↓ open down ↓ |
13 lines elided |
↑ open up ↑ |
92 92 \fB\fBUSYNC_THREAD\fR \fR
93 93 .ad
94 94 .RS 18n
95 95 The readers/writer lock can synchronize threads in this process, only.
96 96 \fIarg\fR is ignored.
97 97 .RE
98 98
99 99 .sp
100 100 .LP
101 101 Additionally, readers/writer locks can be initialized by allocation in zeroed
102 -memory. A \fBtype\fR of \fBUSYNC_THREAD\fR is assumed in this case. Multiple
102 +memory. A \fItype\fR of \fBUSYNC_THREAD\fR is assumed in this case. Multiple
103 103 threads must not simultaneously initialize the same readers/writer lock. And a
104 104 readers/writer lock must not be re-initialized while in use by other threads.
105 105 .sp
106 106 .LP
107 107 The following are default readers/writer lock initialization (intra-process):
108 108 .sp
109 109 .in +2
110 110 .nf
111 111 rwlock_t rwlp;
112 112 rwlock_init(&rwlp, NULL, NULL);
113 113
114 114 .fi
115 115 .in -2
116 116
117 117 .sp
118 118 .LP
119 119 or
120 120 .sp
121 121 .in +2
122 122 .nf
123 123 rwlock_init(&rwlp, USYNC_THREAD, NULL);
124 124 .fi
125 125 .in -2
126 126
127 127 .sp
128 128 .LP
129 129 or
130 130 .sp
131 131 .in +2
132 132 .nf
133 133 rwlock_t rwlp = DEFAULTRWLOCK;
134 134 .fi
135 135 .in -2
136 136
137 137 .sp
138 138 .LP
139 139 The following is a customized readers/writer lock initialization
140 140 (inter-process):
141 141 .sp
142 142 .in +2
143 143 .nf
144 144 rwlock_init(&rwlp, USYNC_PROCESS, NULL);
145 145 .fi
146 146 .in -2
147 147
148 148 .sp
149 149 .LP
150 150 Any state associated with the readers/writer lock pointed to by \fIrwlp\fR are
|
↓ open down ↓ |
38 lines elided |
↑ open up ↑ |
151 151 destroyed by \fBrwlock_destroy()\fR and the readers/writer lock storage space
152 152 is not released.
153 153 .sp
154 154 .LP
155 155 \fBrw_rdlock()\fR gets a read lock on the readers/writer lock pointed to by
156 156 \fIrwlp\fR. If the readers/writer lock is currently locked for writing, the
157 157 calling thread blocks until the write lock is freed. Multiple threads may
158 158 simultaneously hold a read lock on a readers/writer lock.
159 159 .sp
160 160 .LP
161 -\fBrw_tryrdlock()\fR trys to get a read lock on the readers/writer lock pointed
161 +\fBrw_tryrdlock()\fR tries to get a read lock on the readers/writer lock pointed
162 162 to by \fIrwlp\fR. If the readers/writer lock is locked for writing, it returns
163 163 an error; otherwise, the read lock is acquired.
164 164 .sp
165 165 .LP
166 166 \fBrw_wrlock()\fR gets a write lock on the readers/writer lock pointed to by
167 167 \fIrwlp\fR. If the readers/writer lock is currently locked for reading or
168 168 writing, the calling thread blocks until all the read and write locks are
169 169 freed. At any given time, only one thread may have a write lock on a
170 170 readers/writer lock.
171 171 .sp
172 172 .LP
173 -\fBrw_trywrlock()\fR trys to get a write lock on the readers/writer lock
173 +\fBrw_trywrlock()\fR tries to get a write lock on the readers/writer lock
174 174 pointed to by \fIrwlp\fR. If the readers/writer lock is currently locked for
175 175 reading or writing, it returns an error.
176 176 .sp
177 177 .LP
178 178 \fBrw_unlock()\fR unlocks a readers/writer lock pointed to by \fIrwlp\fR, if
179 179 the readers/writer lock is locked and the calling thread holds the lock for
180 180 either reading or writing. One of the other threads that is waiting for the
181 -readers/writer lock to be freed will be unblocked, provided there is other
181 +readers/writer lock to be freed will be unblocked, provided there are other
182 182 waiting threads. If the calling thread does not hold the lock for either
183 183 reading or writing, no error status is returned, and the program's behavior is
184 184 unknown.
185 185 .SH RETURN VALUES
186 186 .sp
187 187 .LP
188 188 If successful, these functions return \fB0\fR. Otherwise, a non-zero value is
189 189 returned to indicate the error.
190 190 .SH ERRORS
191 191 .sp
192 192 .LP
193 193 The \fBrwlock_init()\fR function will fail if:
194 194 .sp
195 195 .ne 2
196 196 .na
197 197 \fB\fBEINVAL\fR \fR
198 198 .ad
199 199 .RS 11n
200 -\fBtype\fR is invalid.
200 +\fItype\fR is invalid.
201 201 .RE
202 202
203 203 .sp
204 204 .LP
205 205 The \fBrw_tryrdlock()\fR or \fBrw_trywrlock()\fR functions will fail if:
206 206 .sp
207 207 .ne 2
208 208 .na
209 209 \fB\fBEBUSY\fR \fR
210 210 .ad
211 211 .RS 10n
212 -The reader or writer lock pointed to by \fIrwlp\fR was already locked.
212 +The readers/writer lock pointed to by \fIrwlp\fR was already locked.
213 213 .RE
214 214
215 215 .sp
216 216 .LP
217 217 These functions may fail if:
218 218 .sp
219 219 .ne 2
220 220 .na
221 221 \fB\fBEFAULT\fR \fR
222 222 .ad
223 223 .RS 11n
224 224 \fIrwlp\fR or \fIarg\fR points to an illegal address.
225 225 .RE
226 226
227 227 .SH ATTRIBUTES
228 228 .sp
229 229 .LP
230 230 See \fBattributes\fR(5) for descriptions of the following attributes:
231 231 .sp
232 232
233 233 .sp
234 234 .TS
235 235 box;
236 236 c | c
237 237 l | l .
238 238 ATTRIBUTE TYPE ATTRIBUTE VALUE
239 239 _
240 240 MT-Level MT-Safe
241 241 .TE
242 242
243 243 .SH SEE ALSO
244 244 .sp
245 245 .LP
246 246 \fBmmap\fR(2), \fBattributes\fR(5)
247 247 .SH NOTES
248 248 .sp
249 249 .LP
250 250 These interfaces also available by way of:
251 251 .sp
252 252 .LP
253 253 \fB#include\fR \fB<thread.h>\fR
254 254 .sp
255 255 .LP
256 256 If multiple threads are waiting for a readers/writer lock, the acquisition
257 257 order is random by default. However, some implementations may bias acquisition
258 258 order to avoid depriving writers. The current implementation favors writers
259 259 over readers.
|
↓ open down ↓ |
37 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX