git.saurik.com Git - apple/libpthread.git/blob

3 .\"

4 .\" Redistribution and use in source and binary forms, with or without

5 .\" modification, are permitted provided that the following conditions

6 .\" are met:

7 .\" 1. Redistributions of source code must retain the above copyright

8 .\" notice, this list of conditions and the following disclaimer.

9 .\" 2. Redistributions in binary form must reproduce the above copyright

10 .\" notice, this list of conditions and the following disclaimer in the

11 .\" documentation and/or other materials provided with the distribution.

12 .\"

13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND

14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

23 .\" SUCH DAMAGE.

24 .\"

25 .\" $FreeBSD$

26 .\"

27 .Dd August 4, 1998

28 .Dt PTHREAD_RWLOCK_RDLOCK 3

29 .Os

30 .Sh NAME

31 .Nm pthread_rwlock_rdlock ,

32 .Nm pthread_rwlock_tryrdlock

33 .Nd acquire a read/write lock for reading

34 .Sh SYNOPSIS

35 .In pthread.h

36 .Ft int

37 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"

38 .Ft int

39 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"

40 .Sh DESCRIPTION

41 The

42 .Fn pthread_rwlock_rdlock

43 function acquires a read lock on

44 .Fa lock

45 provided that

46 .Fa lock

47 is not presently held for writing and no writer threads are

48 presently blocked on the lock.

49 If the read lock cannot be

50 immediately acquired, the calling thread blocks until it can

51 acquire the lock.

52 .Pp

53 The

54 .Fn pthread_rwlock_tryrdlock

55 function performs the same action, but does not block if the lock

56 cannot be immediately obtained (i.e., the lock is held for writing

57 or there are waiting writers).

58 .Pp

59 A thread may hold multiple concurrent read locks.

60 If so,

61 .Fn pthread_rwlock_unlock

62 must be called once for each lock obtained.

63 .Pp

64 The results of acquiring a read lock while the calling thread holds

65 a write lock are undefined.

66 .Sh IMPLEMENTATION NOTES

67 To prevent writer starvation, writers are favored over readers.

68 .Sh RETURN VALUES

69 If successful, the

70 .Fn pthread_rwlock_rdlock

71 and

72 .Fn pthread_rwlock_tryrdlock

73 functions will return zero.

74 Otherwise an error number will be returned

75 to indicate the error.

76 .Sh ERRORS

77 The

78 .Fn pthread_rwlock_tryrdlock

79 function will fail if:

80 .Bl -tag -width Er

81 .It Bq Er EBUSY

82 The lock could not be acquired because a writer holds the lock or

83 was blocked on it.

84 .El

85 .Pp

86 The

87 .Fn pthread_rwlock_rdlock

88 and

89 .Fn pthread_rwlock_tryrdlock

90 functions may fail if:

91 .Bl -tag -width Er

92 .It Bq Er EAGAIN

93 The lock could not be acquired because the maximum number of read locks

94 against

95 .Fa lock

96 has been exceeded.

97 .It Bq Er EDEADLK

98 The current thread already owns

99 .Fa lock

100 for writing.

101 .It Bq Er EINVAL

102 The value specified by

103 .Fa lock

104 is invalid.

105 .It Bq Er ENOMEM

106 Insufficient memory exists to initialize the lock (applies to

107 statically initialized locks only).

108 .El

109 .Sh SEE ALSO

110 .Xr pthread_rwlock_init 3 ,

111 .Xr pthread_rwlock_trywrlock 3 ,

112 .Xr pthread_rwlock_unlock 3 ,

113 .Xr pthread_rwlock_wrlock 3

114 .Sh STANDARDS

115 The

116 .Fn pthread_rwlock_rdlock

117 and

118 .Fn pthread_rwlock_tryrdlock

119 functions are expected to conform to

120 .St -susv2 .

121 .Sh HISTORY

122 The

123 .Fn pthread_rwlock_rdlock

124 function first appeared in

125 .Fx 3.0 .