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.