forked from osue-tuwien/sem182
-
Notifications
You must be signed in to change notification settings - Fork 0
/
msem182.3
209 lines (195 loc) · 6.42 KB
/
msem182.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
.TH MSEM182 3 "July 12, 2012" "MSEM182 User Manual"
.SH NAME
.PP
mseminit, msemgrab, msemrm, mV/msemup, mP/msemdown - semaphore field
convenience operations
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <msem182.h>
int\ mseminit(key_t\ key,\ int\ perm,\ int\ nsems,\ ...);
int\ msemgrab(key_t\ key,\ int\ nsems);
int\ msemrm(int\ semid);
int\ mV(int\ semid,\ int\ nsems,\ ...);
int\ mP(int\ semid,\ int\ nsems,\ ...);
Link\ with\ -lsem182.
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]mseminit\f[]() function creates a new semaphore field with the
given \f[I]key\f[] and permissions as specified in \f[I]perm\f[].
The number of semaphores is specified in \f[I]nsems\f[]; the ellipsis
represents the argument sequence of initial values for each of the
semaphores in the field.
The function fails if a semaphore field associated with \f[I]key\f[]
already exists.
.PP
The \f[B]msemgrab\f[]() function obtains the semaphore field associated
with the given \f[I]key\f[].
The \f[I]nsems\f[] argument is essentially superfluous and should be
specified as 0.
The function fails if a semaphore field associated with \f[I]key\f[] has
not been created yet.
.PP
The \f[B]msemrm\f[]() function removes the semaphore field identified by
\f[I]semid\f[].
It fails if a semaphore field by the given ID does not exist (or has
already been removed).
.PP
The \f[B]mV\f[]() function increments the value of some semaphores in
the field identified by \f[I]semid\f[] atomically by one.
The number of semaphores whose values to increment is specified in
\f[I]nsems\f[], which must be followed by a list of indices representing
these semaphores within the field.
If a process is waiting on any of the semaphores, this process is
unblocked; if multiple processes are waiting on it, exactly one is
unblocked; it is unspecified which.
.PP
The \f[B]mP\f[]() function attempts to decrement the value of some
semaphores in the field identified by \f[I]semid\f[] atomically by one.
The number of semaphores whose values to decrement is specified in
\f[I]nsems\f[], which must be followed by a list of indices representing
these semaphores within the field.
The atomicity extends to the whole operation: if the value of any of the
referenced semaphores is already zero, \f[B]mP\f[]() doesn\[aq]t
decrement any of the semaphores and blocks until the value of all
referenced semaphores is greater than zero, whereupon it decrements all
the values simultaneously and returns.
.PP
The \f[B]msemup\f[]() and \f[B]msemdown\f[]() functions are aliases to
\f[B]mV\f[]() and \f[B]mP\f[]().
.SH RETURN VALUE
.PP
On success, the \f[B]mseminit\f[]() function returns the ID of the newly
created semaphore field; the \f[B]msemgrab\f[]() function returns the ID
of the existing semaphore field associated with \f[I]key\f[].
On error, these functions return -1 and set \f[I]errno\f[] to indicate
the error.
.PP
The \f[B]msemrm\f[]() function returns 0 if the semaphore field was
successfully removed.
Otherwise, -1 is returned and \f[I]errno\f[] is set to indicate the
error.
.PP
The \f[B]mV\f[]() and \f[B]mP\f[]() functions return 0 if the values of
the semaphores have been successfully adjusted.
Otherwise, -1 is returned and \f[I]errno\f[] is set to indicate the
error.
.SH ERRORS
.PP
The \f[B]mseminit\f[]() function may fail and set \f[I]errno\f[] for any
of the errors specified for the routines \f[B]semget\f[](2) and
\f[B]semctl\f[](2).
.PP
The \f[B]msemgrab\f[]() function may fail and set \f[I]errno\f[] for any
of the errors specified for the routine \f[B]semget\f[](2).
.PP
The \f[B]msemrm\f[]() function may fail and set \f[I]errno\f[] for any
of the errors specified for the routine \f[B]semctl\f[](2).
.PP
The functions \f[B]mV\f[]() and \f[B]mP\f[]() may fail and set
\f[I]errno\f[] for any of the errors specified for the routine
\f[B]semop\f[](2).
.SH NOTES
.PP
The function \f[B]mP\f[]() may be interrupted by a signal.
It is important to check its return value to ensure proper
synchronization.
.PP
The command \f[B]ipcs\f[](1) can be used to list, among other things,
all active semaphores; its companion, \f[B]ipcrm\f[](1), to delete them.
.PP
Semaphores created by the companion library \f[B]sem182\f[](3) are
considered fields with one semaphore by \f[B]msem182\f[].
However, using \f[B]sem182\f[] and \f[B]msem182\f[] simultaneously is
strongly discouraged.
.SH EXAMPLE
.PP
The following example demonstrates turn-by-turn synchronization of two
processes.
The semaphores are created and destroyed by the server; the first turn
is made by the client.
.SS Server program
.IP
.nf
\f[C]
#include\ <stdio.h>
#include\ <errno.h>
#include\ <msem182.h>
int\ main(void)
{
\ \ \ int\ s\ =\ mseminit(0xE1820,\ 0600,\ 2,\ 0,\ 1);
\ \ \ if\ (s\ ==\ -1)\ {
\ \ \ \ \ \ perror("mseminit");
\ \ \ \ \ \ return\ 1;
\ \ \ }
\ \ \ for\ (;;)\ {
\ \ \ \ \ \ if\ (mP(s,\ 1,\ 0)\ !=\ 0)\ {
\ \ \ \ \ \ \ \ \ if\ (errno\ ==\ EINTR)\ {
\ \ \ \ \ \ \ \ \ \ \ \ /*\ syscall\ interrupted\ by\ signal,\ try\ again\ */
\ \ \ \ \ \ \ \ \ \ \ \ continue;
\ \ \ \ \ \ \ \ \ }
\ \ \ \ \ \ \ \ \ perror("mP(0)");
\ \ \ \ \ \ \ \ \ break;
\ \ \ \ \ \ }
\ \ \ \ \ \ /*\ critical\ section\ here\ */
\ \ \ \ \ \ if\ (mV(s,\ 1,\ 1)\ !=\ 0)\ {
\ \ \ \ \ \ \ \ \ perror("mV(1)");
\ \ \ \ \ \ \ \ \ break;
\ \ \ \ \ \ }
\ \ \ }
\ \ \ /*\ clean\ up\ semaphores\ */
\ \ \ if\ (msemrm(s)\ !=\ 0)\ {
\ \ \ \ \ \ perror("msemrm");
\ \ \ }
\ \ \ return\ 0;
}
\f[]
.fi
.SS Client program
.IP
.nf
\f[C]
#include\ <stdio.h>
#include\ <errno.h>
#include\ <msem182.h>
int\ main(void)
{
\ \ \ int\ s\ =\ msemgrab(0xE1820,\ 0);
\ \ \ if\ (s\ ==\ -1)\ {
\ \ \ \ \ \ perror("msemgrab");
\ \ \ \ \ \ return\ 1;
\ \ \ }
\ \ \ for\ (;;)\ {
\ \ \ \ \ \ if\ (mP(s,\ 1,\ 1)\ !=\ 0)\ {
\ \ \ \ \ \ \ \ \ if\ (errno\ ==\ EINTR)\ {
\ \ \ \ \ \ \ \ \ \ \ \ /*\ syscall\ interrupted\ by\ signal,\ try\ again\ */
\ \ \ \ \ \ \ \ \ \ \ \ continue;
\ \ \ \ \ \ \ \ \ }
\ \ \ \ \ \ \ \ \ perror("mP(1)");
\ \ \ \ \ \ \ \ \ break;
\ \ \ \ \ \ }
\ \ \ \ \ \ /*\ critical\ section\ here\ */
\ \ \ \ \ \ if\ (mV(s,\ 1,\ 0)\ !=\ 0)\ {
\ \ \ \ \ \ \ \ \ perror("mV(0)");
\ \ \ \ \ \ \ \ \ break;
\ \ \ \ \ \ }
\ \ \ }
\ \ \ return\ 0;
}
\f[]
.fi
.SH SEE ALSO
.PP
\f[B]ipcs\f[](1), \f[B]ipcrm\f[](1), \f[B]semctl\f[](2),
\f[B]semget\f[](2), \f[B]semop\f[](2), \f[B]sem182\f[](3)
.SH COLOPHON
.PP
The msem182 library was implemented by Peter Holzer, deriving work by
Guenther Leber, Heinz Kantz, Raimund Kirner and Gustav Pospischil.
The initial manual page was improved and rewritten by Ondrej Hosek and
pandoc\[aq]ed by Roland Kammerer.
.SH AUTHORS
Ondrej Hosek, Roland Kammerer.