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