46 .\"
47 .TH PTHREAD_RWLOCK_RDLOCK 3C "Mar 23, 2005"
48 .SH NAME
49 pthread_rwlock_rdlock, pthread_rwlock_tryrdlock \- lock or attempt to lock
50 read-write lock object for reading
51 .SH SYNOPSIS
52 .LP
53 .nf
54 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
55 #include <pthread.h>
56
57 \fBint\fR \fBpthread_rwlock_rdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR);
58 .fi
59
60 .LP
61 .nf
62 \fBint\fR \fBpthread_rwlock_tryrdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR);
63 .fi
64
65 .SH DESCRIPTION
66 .sp
67 .LP
68 The \fBpthread_rwlock_rdlock()\fR function applies a read lock to the
69 read-write lock referenced by \fIrwlock\fR. The calling thread acquires the
70 read lock if a writer does not hold the lock and there are no writers blocked
71 on the lock.
72 .sp
73 .LP
74 The calling thread does not acquire the lock if a writer holds the lock or if
75 writers of higher or equal priority are blocked on the lock; otherwise, the
76 calling thread acquires the lock. If the read lock is not acquired, the calling
77 thread blocks until it can acquire the lock.
78 .sp
79 .LP
80 A thread can hold multiple concurrent read locks on \fIrwlock\fR (that is,
81 successfully call the \fBpthread_rwlock_rdlock()\fR function \fIn\fR times). If
82 so, the thread must perform matching unlocks (that is, it must call the
83 \fBpthread_rwlock_unlock()\fR function \fIn\fR times).
84 .sp
85 .LP
86 The maximum number of concurrent read locks that a thread can hold on one
87 read-write lock is currently set at 100,000, though this number could change in
88 a future release. There is no imposed limit on the number of different threads
89 that can apply a read lock to one read-write lock.
90 .sp
91 .LP
92 The \fBpthread_rwlock_tryrdlock()\fR function applies a read lock like the
93 \fBpthread_rwlock_rdlock()\fR function, with the exception that the function
94 fails if the equivalent \fBpthread_rwlock_rdlock()\fR call would have blocked
95 the calling thread. In no case will the \fBpthread_rwlock_tryrdlock()\fR
96 function ever bloc. It always either acquires the lock or fails and returns
97 immediately.
98 .sp
99 .LP
100 Results are undefined if any of these functions are called with an
101 uninitialized read-write lock.
102 .sp
103 .LP
104 If a signal is delivered to a thread waiting for a read-write lock for reading,
105 upon return from the signal handler the thread resumes waiting for the
106 read-write lock for reading as if it was not interrupted.
107 .SH RETURN VALUES
108 .sp
109 .LP
110 If successful, the \fBpthread_rwlock_rdlock()\fR function returns \fB0\fR.
111 Otherwise, an error number is returned to indicate the error.
112 .sp
113 .LP
114 The \fBpthread_rwlock_tryrdlock()\fR function returns \fB0\fR if the lock for
115 reading on the read-write lock object referenced by \fIrwlock\fR is acquired.
116 Otherwise an error number is returned to indicate the error.
117 .SH ERRORS
118 .sp
119 .LP
120 The \fBpthread_rwlock_rdlock()\fR and \fBpthread_rwlock_tryrdlock()\fR
121 functions will fail if:
122 .sp
123 .ne 2
124 .na
125 \fB\fBEAGAIN\fR\fR
126 .ad
127 .RS 10n
128 The read lock could not be acquired because the maximum number of read locks by
129 the current thread for \fIrwlock\fR has been exceeded.
130 .RE
131
132 .sp
133 .LP
134 The \fBpthread_rwlock_rdlock()\fR function will fail if:
135 .sp
136 .ne 2
137 .na
138 \fB\fBEDEADLK\fR\fR
139 .ad
140 .RS 11n
141 The current thread already owns the read-write lock for writing.
142 .RE
143
144 .sp
145 .LP
146 The \fBpthread_rwlock_tryrdlock()\fR function will fail if:
147 .sp
148 .ne 2
149 .na
150 \fB\fBEBUSY\fR\fR
151 .ad
152 .RS 9n
153 The read-write lock could not be acquired for reading because a writer holds
154 the lock or a writer with the appropriate priority was blocked on it.
155 .RE
156
157 .SH ATTRIBUTES
158 .sp
159 .LP
160 See \fBattributes\fR(5) for descriptions of the following attributes:
161 .sp
162
163 .sp
164 .TS
165 box;
166 c | c
167 l | l .
168 ATTRIBUTE TYPE ATTRIBUTE VALUE
169 _
170 Interface Stability Standard
171 _
172 MT-Level MT-Safe
173 .TE
174
175 .SH SEE ALSO
176 .sp
177 .LP
178 \fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_wrlock\fR(3C),
179 \fBpthread_rwlockattr_init\fR(3C), \fBpthread_rwlock_unlock\fR(3C),
180 \fBattributes\fR(5), \fBstandards\fR(5)
|
46 .\"
47 .TH PTHREAD_RWLOCK_RDLOCK 3C "Mar 23, 2005"
48 .SH NAME
49 pthread_rwlock_rdlock, pthread_rwlock_tryrdlock \- lock or attempt to lock
50 read-write lock object for reading
51 .SH SYNOPSIS
52 .LP
53 .nf
54 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
55 #include <pthread.h>
56
57 \fBint\fR \fBpthread_rwlock_rdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR);
58 .fi
59
60 .LP
61 .nf
62 \fBint\fR \fBpthread_rwlock_tryrdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR);
63 .fi
64
65 .SH DESCRIPTION
66 .LP
67 The \fBpthread_rwlock_rdlock()\fR function applies a read lock to the
68 read-write lock referenced by \fIrwlock\fR. The calling thread acquires the
69 read lock if a writer does not hold the lock and there are no writers blocked
70 on the lock.
71 .sp
72 .LP
73 The calling thread does not acquire the lock if a writer holds the lock or if
74 writers of higher or equal priority are blocked on the lock; otherwise, the
75 calling thread acquires the lock. If the read lock is not acquired, the calling
76 thread blocks until it can acquire the lock.
77 .sp
78 .LP
79 A thread can hold multiple concurrent read locks on \fIrwlock\fR (that is,
80 successfully call the \fBpthread_rwlock_rdlock()\fR function \fIn\fR times). If
81 so, the thread must perform matching unlocks (that is, it must call the
82 \fBpthread_rwlock_unlock()\fR function \fIn\fR times).
83 .sp
84 .LP
85 The maximum number of concurrent read locks that a thread can hold on one
86 read-write lock is currently set at 100,000, though this number could change in
87 a future release. There is no imposed limit on the number of different threads
88 that can apply a read lock to one read-write lock.
89 .sp
90 .LP
91 The \fBpthread_rwlock_tryrdlock()\fR function applies a read lock like the
92 \fBpthread_rwlock_rdlock()\fR function, with the exception that the function
93 fails if the equivalent \fBpthread_rwlock_rdlock()\fR call would have blocked
94 the calling thread. In no case will the \fBpthread_rwlock_tryrdlock()\fR
95 function ever block. It always either acquires the lock or fails and returns
96 immediately.
97 .sp
98 .LP
99 Results are undefined if any of these functions are called with an
100 uninitialized read-write lock.
101 .sp
102 .LP
103 If a signal is delivered to a thread waiting for a read-write lock for reading,
104 upon return from the signal handler the thread resumes waiting for the
105 read-write lock for reading as if it was not interrupted.
106 .SH RETURN VALUES
107 .LP
108 If successful, the \fBpthread_rwlock_rdlock()\fR function returns \fB0\fR.
109 Otherwise, an error number is returned to indicate the error.
110 .sp
111 .LP
112 The \fBpthread_rwlock_tryrdlock()\fR function returns \fB0\fR if the lock for
113 reading on the read-write lock object referenced by \fIrwlock\fR is acquired.
114 Otherwise an error number is returned to indicate the error.
115 .SH ERRORS
116 .LP
117 The \fBpthread_rwlock_rdlock()\fR and \fBpthread_rwlock_tryrdlock()\fR
118 functions will fail if:
119 .sp
120 .ne 2
121 .na
122 \fB\fBEAGAIN\fR\fR
123 .ad
124 .RS 10n
125 The read lock could not be acquired because the maximum number of read locks by
126 the current thread for \fIrwlock\fR has been exceeded.
127 .RE
128
129 .sp
130 .LP
131 The \fBpthread_rwlock_rdlock()\fR function will fail if:
132 .sp
133 .ne 2
134 .na
135 \fB\fBEDEADLK\fR\fR
136 .ad
137 .RS 11n
138 The current thread already owns the read-write lock for writing.
139 .RE
140
141 .sp
142 .LP
143 The \fBpthread_rwlock_tryrdlock()\fR function will fail if:
144 .sp
145 .ne 2
146 .na
147 \fB\fBEBUSY\fR\fR
148 .ad
149 .RS 9n
150 The read-write lock could not be acquired for reading because a writer holds
151 the lock or a writer with the appropriate priority was blocked on it.
152 .RE
153
154 .SH ATTRIBUTES
155 .LP
156 See \fBattributes\fR(5) for descriptions of the following attributes:
157 .sp
158
159 .sp
160 .TS
161 box;
162 c | c
163 l | l .
164 ATTRIBUTE TYPE ATTRIBUTE VALUE
165 _
166 Interface Stability Standard
167 _
168 MT-Level MT-Safe
169 .TE
170
171 .SH SEE ALSO
172 .LP
173 \fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_wrlock\fR(3C),
174 \fBpthread_rwlockattr_init\fR(3C), \fBpthread_rwlock_unlock\fR(3C),
175 \fBattributes\fR(5), \fBstandards\fR(5)
|