manual/macros.texi

   1 @c Define common macros used to keep phrasing consistent in the manual.
   2
   3 @ifclear MACROS
   4 @set MACROS
   5
   6 @c Names used to refer to the library, as noun phrases at the start or
   7 @c not at the start of a sentence.
   8 @macro Theglibc
   9 The GNU C Library
  10 @end macro
  11 @macro theglibc
  12 the GNU C Library
  13 @end macro
  14
  15 @c Name used to refer to the library as an adjective.
  16 @macro glibcadj
  17 GNU C Library
  18 @end macro
  19
  20 @c Description applying to all GNU systems; that is, used in
  21 @c describing a property of a system such that no system without that
  22 @c property would be considered a variant of the GNU system.
  23 @macro gnusystems
  24 GNU systems
  25 @end macro
  26
  27 @c Systems that are not GNU systems.
  28 @macro nongnusystems
  29 non-GNU systems
  30 @end macro
  31
  32 @c Description applying to GNU/Linux and GNU/Hurd systems, but not
  33 @c necessarily to other variants of the GNU system.
  34 @macro gnulinuxhurdsystems
  35 GNU/Linux and GNU/Hurd systems
  36 @end macro
  37
  38 @c Description applying to GNU/Hurd systems; that is, systems using the
  39 @c GNU Hurd with the GNU C Library.
  40 @macro gnuhurdsystems
  41 GNU/Hurd systems
  42 @end macro
  43
  44 @c Description applying to GNU/Linux systems; that is, systems using
  45 @c the Linux kernel with the GNU C Library.
  46 @macro gnulinuxsystems
  47 GNU/Linux systems
  48 @end macro
  49
  50 @c Document the safety functions as preliminary.  It does NOT expand its
  51 @c comments.
  52 @macro prelim {comments}
  53 Preliminary:
  54
  55 @end macro
  56 @c Document a function as thread safe.
  57 @macro mtsafe {comments}
  58 | MT-Safe \comments\
  59
  60 @end macro
  61 @c Document a function as thread unsafe.
  62 @macro mtunsafe {comments}
  63 | MT-Unsafe \comments\
  64
  65 @end macro
  66 @c Document a function as safe for use in asynchronous signal handlers.
  67 @macro assafe {comments}
  68 | AS-Safe \comments\
  69
  70 @end macro
  71 @c Document a function as unsafe for use in asynchronous signal
  72 @c handlers.  This distinguishes unmarked functions, for which this
  73 @c property has not been assessed, from those that have been analyzed.
  74 @macro asunsafe {comments}
  75 | AS-Unsafe \comments\
  76
  77 @end macro
  78 @c Document a function as safe for use when asynchronous cancellation is
  79 @c enabled.
  80 @macro acsafe {comments}
  81 | AC-Safe \comments\
  82
  83 @end macro
  84 @c Document a function as unsafe for use when asynchronous cancellation
  85 @c is enabled.  This distinguishes unmarked functions, for which this
  86 @c property has not been assessed, from those that have been analyzed.
  87 @macro acunsafe {comments}
  88 | AC-Unsafe \comments\
  89
  90 @end macro
  91 @c Format safety properties without referencing the section of the
  92 @c definitions.  To be used in the definitions of the properties
  93 @c themselves.
  94 @macro sampsafety {notes}
  95 @noindent
  96 \notes\|
  97
  98
  99 @end macro
 100 @c Format the safety properties of a function.
 101 @macro safety {notes}
 102 \notes\| @xref{POSIX Safety Concepts}.
 103
 104
 105 @end macro
 106 @c Function is MT- and AS-Unsafe due to an internal race.
 107 @macro mtasurace {comments}
 108 race\comments\
 109 @end macro
 110 @c Function is AS-Unsafe due to an internal race.
 111 @macro asurace {comments}
 112 race\comments\
 113 @end macro
 114 @c Function is MT-Safe, but with potential race on user-supplied object
 115 @c of opaque type.
 116 @macro mtsrace {comments}
 117 race\comments\
 118 @end macro
 119 @c Function is MT- and AS-Unsafe for modifying an object that is decreed
 120 @c MT-constant due to MT-Unsafe accesses elsewhere.
 121 @macro mtasuconst {comments}
 122 const\comments\
 123 @end macro
 124 @c Function accesses the assumed-constant locale object.
 125 @macro mtslocale {comments}
 126 locale\comments\
 127 @end macro
 128 @c Function accesses the assumed-constant environment.
 129 @macro mtsenv {comments}
 130 env\comments\
 131 @end macro
 132 @c Function accesses the assumed-constant hostid.
 133 @macro mtshostid {comments}
 134 hostid\comments\
 135 @end macro
 136 @c Function accesses the assumed-constant _sigintr variable.
 137 @macro mtssigintr {comments}
 138 sigintr\comments\
 139 @end macro
 140 @c Function performs MT-Unsafe initialization at the first call.
 141 @macro mtuinit {comments}
 142 init\comments\
 143 @end macro
 144 @c Function performs libc_once AS-Unsafe initialization.
 145 @macro asuinit {comments}
 146 init\comments\
 147 @end macro
 148 @c Function performs libc_once AC-Unsafe initialization.
 149 @macro acuinit {comments}
 150 init\comments\
 151 @end macro
 152 @c Function is AS-Unsafe because it takes a non-recursive mutex that may
 153 @c already be held by the function interrupted by the signal.
 154 @macro asulock {comments}
 155 lock\comments\
 156 @end macro
 157 @c Function is AC-Unsafe because it may fail to release a mutex.
 158 @macro aculock {comments}
 159 lock\comments\
 160 @end macro
 161 @c Function is AS-Unsafe because some data structure may be inconsistent
 162 @c due to an ongoing updated interrupted by a signal.
 163 @macro asucorrupt {comments}
 164 corrupt\comments\
 165 @end macro
 166 @c Function is AC-Unsafe because some data structure may be left
 167 @c inconsistent when cancelled.
 168 @macro acucorrupt {comments}
 169 corrupt\comments\
 170 @end macro
 171 @c Function is AS- and AC-Unsafe because of malloc/free.
 172 @macro ascuheap {comments}
 173 heap\comments\
 174 @end macro
 175 @c Function is AS-Unsafe because of malloc/free.
 176 @macro asuheap {comments}
 177 heap\comments\
 178 @end macro
 179 @c Function is AS- and AC-Unsafe because of dlopen/dlclose.
 180 @macro ascudlopen {comments}
 181 dlopen\comments\
 182 @end macro
 183 @c Function is AS- and AC-Unsafe because of unknown plugins.
 184 @macro ascuplugin {comments}
 185 plugin\comments\
 186 @end macro
 187 @c Function is AS- and AC-Unsafe because of i18n.
 188 @macro ascuintl {comments}
 189 i18n\comments\
 190 @end macro
 191 @c Function is AS--Unsafe because of i18n.
 192 @macro asuintl {comments}
 193 i18n\comments\
 194 @end macro
 195 @c Function may leak file descriptors if async-cancelled.
 196 @macro acsfd {comments}
 197 fd\comments\
 198 @end macro
 199 @c Function may leak memory if async-cancelled.
 200 @macro acsmem {comments}
 201 mem\comments\
 202 @end macro
 203 @c Function is unsafe due to temporary overriding a signal handler.
 204 @macro mtascusig {comments}
 205 sig\comments\
 206 @end macro
 207 @c Function is MT- and AS-Unsafe due to temporarily changing attributes
 208 @c of the controlling terminal.
 209 @macro mtasuterm {comments}
 210 term\comments\
 211 @end macro
 212 @c Function is AC-Unsafe for failing to restore attributes of the
 213 @c controlling terminal.
 214 @macro acuterm {comments}
 215 term\comments\
 216 @end macro
 217 @c Function sets timers atomically.
 218 @macro mtstimer {comments}
 219 timer\comments\
 220 @end macro
 221 @c Function sets and restores timers.
 222 @macro mtascutimer {comments}
 223 timer\comments\
 224 @end macro
 225 @c Function temporarily changes the current working directory.
 226 @macro mtasscwd {comments}
 227 cwd\comments\
 228 @end macro
 229 @c Function may fail to restore to the original current working
 230 @c directory after temporarily changing it.
 231 @macro acscwd {comments}
 232 cwd\comments\
 233 @end macro
 234 @c Function is MT-Safe while POSIX says it needn't be MT-Safe.
 235 @macro mtsposix {comments}
 236 !posix\comments\
 237 @end macro
 238 @c Function is MT-Unsafe while POSIX says it should be MT-Safe.
 239 @macro mtuposix {comments}
 240 !posix\comments\
 241 @end macro
 242 @c Function is AS-Safe while POSIX says it needn't be AS-Safe.
 243 @macro assposix {comments}
 244 !posix\comments\
 245 @end macro
 246 @c Function is AS-Unsafe while POSIX says it should be AS-Safe.
 247 @macro asuposix {comments}
 248 !posix\comments\
 249 @end macro
 250 @c Function is AC-Safe while POSIX says it needn't be AC-Safe.
 251 @macro acsposix {comments}
 252 !posix\comments\
 253 @end macro
 254 @c Function is AC-Unsafe while POSIX says it should be AC-Safe.
 255 @macro acuposix {comments}
 256 !posix\comments\
 257 @end macro
 258
 259 @iftex
 260 @macro twoexp{exp}
 261 @math{2^{{\exp\}}}
 262 @end macro
 263 @end iftex
 264 @ifnottex
 265 @macro twoexp{exp}
 266 2^\exp\
 267 @end macro
 268 @end ifnottex
 269
 270 @end ifclear