summary refs log tree commit diff
path: root/manual/macros.texi
blob: f32c86dc2290359af1910573df41df212770f6a4 (plain) (blame)
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
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@c Define common macros used to keep phrasing consistent in the manual.

@ifclear MACROS
@set MACROS

@c Names used to refer to the library, as noun phrases at the start or
@c not at the start of a sentence.
@macro Theglibc
The GNU C Library
@end macro
@macro theglibc
the GNU C Library
@end macro

@c Name used to refer to the library as an adjective.
@macro glibcadj
GNU C Library
@end macro

@c Description applying to all GNU systems; that is, used in
@c describing a property of a system such that no system without that
@c property would be considered a variant of the GNU system.
@macro gnusystems
GNU systems
@end macro

@c Systems that are not GNU systems.
@macro nongnusystems
non-GNU systems
@end macro

@c Description applying to GNU/Linux and GNU/Hurd systems, but not
@c necessarily to other variants of the GNU system.
@macro gnulinuxhurdsystems
GNU/Linux and GNU/Hurd systems
@end macro

@c Description applying to GNU/Hurd systems; that is, systems using the
@c GNU Hurd with the GNU C Library.
@macro gnuhurdsystems
GNU/Hurd systems
@end macro

@c Description applying to GNU/Linux systems; that is, systems using
@c the Linux kernel with the GNU C Library.
@macro gnulinuxsystems
GNU/Linux systems
@end macro

@c Document the safety functions as preliminary.  It does NOT expand its
@c comments.
@macro prelim {comments}
Preliminary:

@end macro
@c Document a function as thread safe.
@macro mtsafe {comments}
| MT-Safe \comments\

@end macro
@c Document a function as thread unsafe.
@macro mtunsafe {comments}
| MT-Unsafe \comments\

@end macro
@c Document a function as safe for use in asynchronous signal handlers.
@macro assafe {comments}
| AS-Safe \comments\

@end macro
@c Document a function as unsafe for use in asynchronous signal
@c handlers.  This distinguishes unmarked functions, for which this
@c property has not been assessed, from those that have been analyzed.
@macro asunsafe {comments}
| AS-Unsafe \comments\

@end macro
@c Document a function as safe for use when asynchronous cancellation is
@c enabled.
@macro acsafe {comments}
| AC-Safe \comments\

@end macro
@c Document a function as unsafe for use when asynchronous cancellation
@c is enabled.  This distinguishes unmarked functions, for which this
@c property has not been assessed, from those that have been analyzed.
@macro acunsafe {comments}
| AC-Unsafe \comments\

@end macro
@c Format safety properties without referencing the section of the
@c definitions.  To be used in the definitions of the properties
@c themselves.
@macro sampsafety {notes}
@noindent
\notes\|


@end macro
@c Format the safety properties of a function.
@macro safety {notes}
\notes\| @xref{POSIX Safety Concepts}.


@end macro
@c Function is MT- and AS-Unsafe due to an internal race.
@macro mtasurace {comments}
race\comments\
@end macro
@c Function is AS-Unsafe due to an internal race.
@macro asurace {comments}
race\comments\
@end macro
@c Function is MT-Safe, but with potential race on user-supplied object
@c of opaque type.
@macro mtsrace {comments}
race\comments\
@end macro
@c Function is MT- and AS-Unsafe for modifying an object that is decreed
@c MT-constant due to MT-Unsafe accesses elsewhere.
@macro mtasuconst {comments}
const\comments\
@end macro
@c Function accesses the assumed-constant locale object.
@macro mtslocale {comments}
locale\comments\
@end macro
@c Function accesses the assumed-constant environment.
@macro mtsenv {comments}
env\comments\
@end macro
@c Function accesses the assumed-constant hostid.
@macro mtshostid {comments}
hostid\comments\
@end macro
@c Function accesses the assumed-constant _sigintr variable.
@macro mtssigintr {comments}
sigintr\comments\
@end macro
@c Function performs MT-Unsafe initialization at the first call.
@macro mtuinit {comments}
init\comments\
@end macro
@c Function performs libc_once AS-Unsafe initialization.
@macro asuinit {comments}
init\comments\
@end macro
@c Function performs libc_once AC-Unsafe initialization.
@macro acuinit {comments}
init\comments\
@end macro
@c Function is AS-Unsafe because it takes a non-recursive mutex that may
@c already be held by the function interrupted by the signal.
@macro asulock {comments}
lock\comments\
@end macro
@c Function is AC-Unsafe because it may fail to release a mutex.
@macro aculock {comments}
lock\comments\
@end macro
@c Function is AS-Unsafe because some data structure may be inconsistent
@c due to an ongoing updated interrupted by a signal.
@macro asucorrupt {comments}
corrupt\comments\
@end macro
@c Function is AC-Unsafe because some data structure may be left
@c inconsistent when cancelled.
@macro acucorrupt {comments}
corrupt\comments\
@end macro
@c Function is AS- and AC-Unsafe because of malloc/free.
@macro ascuheap {comments}
heap\comments\
@end macro
@c Function is AS-Unsafe because of malloc/free.
@macro asuheap {comments}
heap\comments\
@end macro
@c Function is AS- and AC-Unsafe because of dlopen/dlclose.
@macro ascudlopen {comments}
dlopen\comments\
@end macro
@c Function is AS- and AC-Unsafe because of unknown plugins.
@macro ascuplugin {comments}
plugin\comments\
@end macro
@c Function is AS- and AC-Unsafe because of i18n.
@macro ascuintl {comments}
i18n\comments\
@end macro
@c Function is AS--Unsafe because of i18n.
@macro asuintl {comments}
i18n\comments\
@end macro
@c Function may leak file descriptors if async-cancelled.
@macro acsfd {comments}
fd\comments\
@end macro
@c Function may leak memory if async-cancelled.
@macro acsmem {comments}
mem\comments\
@end macro
@c Function is unsafe due to temporary overriding a signal handler.
@macro mtascusig {comments}
sig\comments\
@end macro
@c Function is MT- and AS-Unsafe due to temporarily changing attributes
@c of the controlling terminal.
@macro mtasuterm {comments}
term\comments\
@end macro
@c Function is AC-Unsafe for failing to restore attributes of the
@c controlling terminal.
@macro acuterm {comments}
term\comments\
@end macro
@c Function sets timers atomically.
@macro mtstimer {comments}
timer\comments\
@end macro
@c Function sets and restores timers.
@macro mtascutimer {comments}
timer\comments\
@end macro
@c Function temporarily changes the current working directory.
@macro mtasscwd {comments}
cwd\comments\
@end macro
@c Function may fail to restore to the original current working
@c directory after temporarily changing it.
@macro acscwd {comments}
cwd\comments\
@end macro
@c Function is MT-Safe while POSIX says it needn't be MT-Safe.
@macro mtsposix {comments}
!posix\comments\
@end macro
@c Function is MT-Unsafe while POSIX says it should be MT-Safe.
@macro mtuposix {comments}
!posix\comments\
@end macro
@c Function is AS-Safe while POSIX says it needn't be AS-Safe.
@macro assposix {comments}
!posix\comments\
@end macro
@c Function is AS-Unsafe while POSIX says it should be AS-Safe.
@macro asuposix {comments}
!posix\comments\
@end macro
@c Function is AC-Safe while POSIX says it needn't be AC-Safe.
@macro acsposix {comments}
!posix\comments\
@end macro
@c Function is AC-Unsafe while POSIX says it should be AC-Safe.
@macro acuposix {comments}
!posix\comments\
@end macro

@end ifclear