« back to all changes in this revision
Viewing changes to manual/libc.info-3
- browse files at revision 42
- compare with another revision
- download diff
- download tarball
- view history from revision 42
- Committer: Bazaar Package Importer
- Author(s): Matthias Klose
- Date: 2010-05-01 14:30:23 UTC
- Revision ID: james.westby@ubuntu.com-20100501143023-hpdks84mak9t4q2c
Tags: 2.11.1-0ubuntu8
* Apply from the 2.11-x86 branch:
- x86-64 SSE4 optimized memcmp.
* [armel] make syscalls out-of-line to improve debugging. LP: #571647 .
- x86-64 SSE4 optimized memcmp.
* [armel] make syscalls out-of-line to improve debugging. LP: #571647 .
- files added:
- debian/patches/any/arm-syscalls-out-of-line.diff
- files modified:
- debian/changelog
added
removed
manual/libc.info-3
1
This is libc.info, produced by makeinfo version 4.13 from libc.texinfo.
2
3
INFO-DIR-SECTION Software libraries
4
START-INFO-DIR-ENTRY
5
* Libc: (libc). C library.
6
END-INFO-DIR-ENTRY
7
8
INFO-DIR-SECTION GNU C library functions and macros
9
START-INFO-DIR-ENTRY
10
* ALTWERASE: (libc)Local Modes.
11
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
12
* ARG_MAX: (libc)General Limits.
13
* BC_BASE_MAX: (libc)Utility Limits.
14
* BC_DIM_MAX: (libc)Utility Limits.
15
* BC_SCALE_MAX: (libc)Utility Limits.
16
* BC_STRING_MAX: (libc)Utility Limits.
17
* BRKINT: (libc)Input Modes.
18
* BUFSIZ: (libc)Controlling Buffering.
19
* CCTS_OFLOW: (libc)Control Modes.
20
* CHILD_MAX: (libc)General Limits.
21
* CIGNORE: (libc)Control Modes.
22
* CLK_TCK: (libc)CPU Time.
23
* CLOCAL: (libc)Control Modes.
24
* CLOCKS_PER_SEC: (libc)CPU Time.
25
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
26
* CPU_CLR: (libc)CPU Affinity.
27
* CPU_ISSET: (libc)CPU Affinity.
28
* CPU_SET: (libc)CPU Affinity.
29
* CPU_SETSIZE: (libc)CPU Affinity.
30
* CPU_ZERO: (libc)CPU Affinity.
31
* CREAD: (libc)Control Modes.
32
* CRTS_IFLOW: (libc)Control Modes.
33
* CS5: (libc)Control Modes.
34
* CS6: (libc)Control Modes.
35
* CS7: (libc)Control Modes.
36
* CS8: (libc)Control Modes.
37
* CSIZE: (libc)Control Modes.
38
* CSTOPB: (libc)Control Modes.
39
* DES_FAILED: (libc)DES Encryption.
40
* DTTOIF: (libc)Directory Entries.
41
* E2BIG: (libc)Error Codes.
42
* EACCES: (libc)Error Codes.
43
* EADDRINUSE: (libc)Error Codes.
44
* EADDRNOTAVAIL: (libc)Error Codes.
45
* EADV: (libc)Error Codes.
46
* EAFNOSUPPORT: (libc)Error Codes.
47
* EAGAIN: (libc)Error Codes.
48
* EALREADY: (libc)Error Codes.
49
* EAUTH: (libc)Error Codes.
50
* EBACKGROUND: (libc)Error Codes.
51
* EBADE: (libc)Error Codes.
52
* EBADF: (libc)Error Codes.
53
* EBADFD: (libc)Error Codes.
54
* EBADMSG: (libc)Error Codes.
55
* EBADR: (libc)Error Codes.
56
* EBADRPC: (libc)Error Codes.
57
* EBADRQC: (libc)Error Codes.
58
* EBADSLT: (libc)Error Codes.
59
* EBFONT: (libc)Error Codes.
60
* EBUSY: (libc)Error Codes.
61
* ECANCELED: (libc)Error Codes.
62
* ECHILD: (libc)Error Codes.
63
* ECHO: (libc)Local Modes.
64
* ECHOCTL: (libc)Local Modes.
65
* ECHOE: (libc)Local Modes.
66
* ECHOK: (libc)Local Modes.
67
* ECHOKE: (libc)Local Modes.
68
* ECHONL: (libc)Local Modes.
69
* ECHOPRT: (libc)Local Modes.
70
* ECHRNG: (libc)Error Codes.
71
* ECOMM: (libc)Error Codes.
72
* ECONNABORTED: (libc)Error Codes.
73
* ECONNREFUSED: (libc)Error Codes.
74
* ECONNRESET: (libc)Error Codes.
75
* ED: (libc)Error Codes.
76
* EDEADLK: (libc)Error Codes.
77
* EDEADLOCK: (libc)Error Codes.
78
* EDESTADDRREQ: (libc)Error Codes.
79
* EDIED: (libc)Error Codes.
80
* EDOM: (libc)Error Codes.
81
* EDOTDOT: (libc)Error Codes.
82
* EDQUOT: (libc)Error Codes.
83
* EEXIST: (libc)Error Codes.
84
* EFAULT: (libc)Error Codes.
85
* EFBIG: (libc)Error Codes.
86
* EFTYPE: (libc)Error Codes.
87
* EGRATUITOUS: (libc)Error Codes.
88
* EGREGIOUS: (libc)Error Codes.
89
* EHOSTDOWN: (libc)Error Codes.
90
* EHOSTUNREACH: (libc)Error Codes.
91
* EIDRM: (libc)Error Codes.
92
* EIEIO: (libc)Error Codes.
93
* EILSEQ: (libc)Error Codes.
94
* EINPROGRESS: (libc)Error Codes.
95
* EINTR: (libc)Error Codes.
96
* EINVAL: (libc)Error Codes.
97
* EIO: (libc)Error Codes.
98
* EISCONN: (libc)Error Codes.
99
* EISDIR: (libc)Error Codes.
100
* EISNAM: (libc)Error Codes.
101
* EKEYEXPIRED: (libc)Error Codes.
102
* EKEYREJECTED: (libc)Error Codes.
103
* EKEYREVOKED: (libc)Error Codes.
104
* EL2HLT: (libc)Error Codes.
105
* EL2NSYNC: (libc)Error Codes.
106
* EL3HLT: (libc)Error Codes.
107
* EL3RST: (libc)Error Codes.
108
* ELIBACC: (libc)Error Codes.
109
* ELIBBAD: (libc)Error Codes.
110
* ELIBEXEC: (libc)Error Codes.
111
* ELIBMAX: (libc)Error Codes.
112
* ELIBSCN: (libc)Error Codes.
113
* ELNRNG: (libc)Error Codes.
114
* ELOOP: (libc)Error Codes.
115
* EMEDIUMTYPE: (libc)Error Codes.
116
* EMFILE: (libc)Error Codes.
117
* EMLINK: (libc)Error Codes.
118
* EMSGSIZE: (libc)Error Codes.
119
* EMULTIHOP: (libc)Error Codes.
120
* ENAMETOOLONG: (libc)Error Codes.
121
* ENAVAIL: (libc)Error Codes.
122
* ENEEDAUTH: (libc)Error Codes.
123
* ENETDOWN: (libc)Error Codes.
124
* ENETRESET: (libc)Error Codes.
125
* ENETUNREACH: (libc)Error Codes.
126
* ENFILE: (libc)Error Codes.
127
* ENOANO: (libc)Error Codes.
128
* ENOBUFS: (libc)Error Codes.
129
* ENOCSI: (libc)Error Codes.
130
* ENODATA: (libc)Error Codes.
131
* ENODEV: (libc)Error Codes.
132
* ENOENT: (libc)Error Codes.
133
* ENOEXEC: (libc)Error Codes.
134
* ENOKEY: (libc)Error Codes.
135
* ENOLCK: (libc)Error Codes.
136
* ENOLINK: (libc)Error Codes.
137
* ENOMEDIUM: (libc)Error Codes.
138
* ENOMEM: (libc)Error Codes.
139
* ENOMSG: (libc)Error Codes.
140
* ENONET: (libc)Error Codes.
141
* ENOPKG: (libc)Error Codes.
142
* ENOPROTOOPT: (libc)Error Codes.
143
* ENOSPC: (libc)Error Codes.
144
* ENOSR: (libc)Error Codes.
145
* ENOSTR: (libc)Error Codes.
146
* ENOSYS: (libc)Error Codes.
147
* ENOTBLK: (libc)Error Codes.
148
* ENOTCONN: (libc)Error Codes.
149
* ENOTDIR: (libc)Error Codes.
150
* ENOTEMPTY: (libc)Error Codes.
151
* ENOTNAM: (libc)Error Codes.
152
* ENOTRECOVERABLE: (libc)Error Codes.
153
* ENOTSOCK: (libc)Error Codes.
154
* ENOTSUP: (libc)Error Codes.
155
* ENOTTY: (libc)Error Codes.
156
* ENOTUNIQ: (libc)Error Codes.
157
* ENXIO: (libc)Error Codes.
158
* EOF: (libc)EOF and Errors.
159
* EOPNOTSUPP: (libc)Error Codes.
160
* EOVERFLOW: (libc)Error Codes.
161
* EOWNERDEAD: (libc)Error Codes.
162
* EPERM: (libc)Error Codes.
163
* EPFNOSUPPORT: (libc)Error Codes.
164
* EPIPE: (libc)Error Codes.
165
* EPROCLIM: (libc)Error Codes.
166
* EPROCUNAVAIL: (libc)Error Codes.
167
* EPROGMISMATCH: (libc)Error Codes.
168
* EPROGUNAVAIL: (libc)Error Codes.
169
* EPROTO: (libc)Error Codes.
170
* EPROTONOSUPPORT: (libc)Error Codes.
171
* EPROTOTYPE: (libc)Error Codes.
172
* EQUIV_CLASS_MAX: (libc)Utility Limits.
173
* ERANGE: (libc)Error Codes.
174
* EREMCHG: (libc)Error Codes.
175
* EREMOTE: (libc)Error Codes.
176
* EREMOTEIO: (libc)Error Codes.
177
* ERESTART: (libc)Error Codes.
178
* EROFS: (libc)Error Codes.
179
* ERPCMISMATCH: (libc)Error Codes.
180
* ESHUTDOWN: (libc)Error Codes.
181
* ESOCKTNOSUPPORT: (libc)Error Codes.
182
* ESPIPE: (libc)Error Codes.
183
* ESRCH: (libc)Error Codes.
184
* ESRMNT: (libc)Error Codes.
185
* ESTALE: (libc)Error Codes.
186
* ESTRPIPE: (libc)Error Codes.
187
* ETIME: (libc)Error Codes.
188
* ETIMEDOUT: (libc)Error Codes.
189
* ETOOMANYREFS: (libc)Error Codes.
190
* ETXTBSY: (libc)Error Codes.
191
* EUCLEAN: (libc)Error Codes.
192
* EUNATCH: (libc)Error Codes.
193
* EUSERS: (libc)Error Codes.
194
* EWOULDBLOCK: (libc)Error Codes.
195
* EXDEV: (libc)Error Codes.
196
* EXFULL: (libc)Error Codes.
197
* EXIT_FAILURE: (libc)Exit Status.
198
* EXIT_SUCCESS: (libc)Exit Status.
199
* EXPR_NEST_MAX: (libc)Utility Limits.
200
* FD_CLOEXEC: (libc)Descriptor Flags.
201
* FD_CLR: (libc)Waiting for I/O.
202
* FD_ISSET: (libc)Waiting for I/O.
203
* FD_SET: (libc)Waiting for I/O.
204
* FD_SETSIZE: (libc)Waiting for I/O.
205
* FD_ZERO: (libc)Waiting for I/O.
206
* FILENAME_MAX: (libc)Limits for Files.
207
* FLUSHO: (libc)Local Modes.
208
* FOPEN_MAX: (libc)Opening Streams.
209
* FP_ILOGB0: (libc)Exponents and Logarithms.
210
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
211
* F_DUPFD: (libc)Duplicating Descriptors.
212
* F_GETFD: (libc)Descriptor Flags.
213
* F_GETFL: (libc)Getting File Status Flags.
214
* F_GETLK: (libc)File Locks.
215
* F_GETOWN: (libc)Interrupt Input.
216
* F_OK: (libc)Testing File Access.
217
* F_SETFD: (libc)Descriptor Flags.
218
* F_SETFL: (libc)Getting File Status Flags.
219
* F_SETLK: (libc)File Locks.
220
* F_SETLKW: (libc)File Locks.
221
* F_SETOWN: (libc)Interrupt Input.
222
* HUGE_VAL: (libc)Math Error Reporting.
223
* HUGE_VALF: (libc)Math Error Reporting.
224
* HUGE_VALL: (libc)Math Error Reporting.
225
* HUPCL: (libc)Control Modes.
226
* I: (libc)Complex Numbers.
227
* ICANON: (libc)Local Modes.
228
* ICRNL: (libc)Input Modes.
229
* IEXTEN: (libc)Local Modes.
230
* IFNAMSIZ: (libc)Interface Naming.
231
* IFTODT: (libc)Directory Entries.
232
* IGNBRK: (libc)Input Modes.
233
* IGNCR: (libc)Input Modes.
234
* IGNPAR: (libc)Input Modes.
235
* IMAXBEL: (libc)Input Modes.
236
* INADDR_ANY: (libc)Host Address Data Type.
237
* INADDR_BROADCAST: (libc)Host Address Data Type.
238
* INADDR_LOOPBACK: (libc)Host Address Data Type.
239
* INADDR_NONE: (libc)Host Address Data Type.
240
* INFINITY: (libc)Infinity and NaN.
241
* INLCR: (libc)Input Modes.
242
* INPCK: (libc)Input Modes.
243
* IPPORT_RESERVED: (libc)Ports.
244
* IPPORT_USERRESERVED: (libc)Ports.
245
* ISIG: (libc)Local Modes.
246
* ISTRIP: (libc)Input Modes.
247
* IXANY: (libc)Input Modes.
248
* IXOFF: (libc)Input Modes.
249
* IXON: (libc)Input Modes.
250
* LINE_MAX: (libc)Utility Limits.
251
* LINK_MAX: (libc)Limits for Files.
252
* L_ctermid: (libc)Identifying the Terminal.
253
* L_cuserid: (libc)Who Logged In.
254
* L_tmpnam: (libc)Temporary Files.
255
* MAXNAMLEN: (libc)Limits for Files.
256
* MAXSYMLINKS: (libc)Symbolic Links.
257
* MAX_CANON: (libc)Limits for Files.
258
* MAX_INPUT: (libc)Limits for Files.
259
* MB_CUR_MAX: (libc)Selecting the Conversion.
260
* MB_LEN_MAX: (libc)Selecting the Conversion.
261
* MDMBUF: (libc)Control Modes.
262
* MSG_DONTROUTE: (libc)Socket Data Options.
263
* MSG_OOB: (libc)Socket Data Options.
264
* MSG_PEEK: (libc)Socket Data Options.
265
* NAME_MAX: (libc)Limits for Files.
266
* NAN: (libc)Infinity and NaN.
267
* NCCS: (libc)Mode Data Types.
268
* NGROUPS_MAX: (libc)General Limits.
269
* NOFLSH: (libc)Local Modes.
270
* NOKERNINFO: (libc)Local Modes.
271
* NSIG: (libc)Standard Signals.
272
* NULL: (libc)Null Pointer Constant.
273
* ONLCR: (libc)Output Modes.
274
* ONOEOT: (libc)Output Modes.
275
* OPEN_MAX: (libc)General Limits.
276
* OPOST: (libc)Output Modes.
277
* OXTABS: (libc)Output Modes.
278
* O_ACCMODE: (libc)Access Modes.
279
* O_APPEND: (libc)Operating Modes.
280
* O_ASYNC: (libc)Operating Modes.
281
* O_CREAT: (libc)Open-time Flags.
282
* O_EXCL: (libc)Open-time Flags.
283
* O_EXEC: (libc)Access Modes.
284
* O_EXLOCK: (libc)Open-time Flags.
285
* O_FSYNC: (libc)Operating Modes.
286
* O_IGNORE_CTTY: (libc)Open-time Flags.
287
* O_NDELAY: (libc)Operating Modes.
288
* O_NOATIME: (libc)Operating Modes.
289
* O_NOCTTY: (libc)Open-time Flags.
290
* O_NOLINK: (libc)Open-time Flags.
291
* O_NONBLOCK: (libc)Open-time Flags.
292
* O_NONBLOCK: (libc)Operating Modes.
293
* O_NOTRANS: (libc)Open-time Flags.
294
* O_RDONLY: (libc)Access Modes.
295
* O_RDWR: (libc)Access Modes.
296
* O_READ: (libc)Access Modes.
297
* O_SHLOCK: (libc)Open-time Flags.
298
* O_SYNC: (libc)Operating Modes.
299
* O_TRUNC: (libc)Open-time Flags.
300
* O_WRITE: (libc)Access Modes.
301
* O_WRONLY: (libc)Access Modes.
302
* PARENB: (libc)Control Modes.
303
* PARMRK: (libc)Input Modes.
304
* PARODD: (libc)Control Modes.
305
* PATH_MAX: (libc)Limits for Files.
306
* PA_FLAG_MASK: (libc)Parsing a Template String.
307
* PENDIN: (libc)Local Modes.
308
* PF_FILE: (libc)Local Namespace Details.
309
* PF_INET6: (libc)Internet Namespace.
310
* PF_INET: (libc)Internet Namespace.
311
* PF_LOCAL: (libc)Local Namespace Details.
312
* PF_UNIX: (libc)Local Namespace Details.
313
* PIPE_BUF: (libc)Limits for Files.
314
* P_tmpdir: (libc)Temporary Files.
315
* RAND_MAX: (libc)ISO Random.
316
* RE_DUP_MAX: (libc)General Limits.
317
* RLIM_INFINITY: (libc)Limits on Resources.
318
* R_OK: (libc)Testing File Access.
319
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
320
* SA_ONSTACK: (libc)Flags for Sigaction.
321
* SA_RESTART: (libc)Flags for Sigaction.
322
* SEEK_CUR: (libc)File Positioning.
323
* SEEK_END: (libc)File Positioning.
324
* SEEK_SET: (libc)File Positioning.
325
* SIGABRT: (libc)Program Error Signals.
326
* SIGALRM: (libc)Alarm Signals.
327
* SIGBUS: (libc)Program Error Signals.
328
* SIGCHLD: (libc)Job Control Signals.
329
* SIGCLD: (libc)Job Control Signals.
330
* SIGCONT: (libc)Job Control Signals.
331
* SIGEMT: (libc)Program Error Signals.
332
* SIGFPE: (libc)Program Error Signals.
333
* SIGHUP: (libc)Termination Signals.
334
* SIGILL: (libc)Program Error Signals.
335
* SIGINFO: (libc)Miscellaneous Signals.
336
* SIGINT: (libc)Termination Signals.
337
* SIGIO: (libc)Asynchronous I/O Signals.
338
* SIGIOT: (libc)Program Error Signals.
339
* SIGKILL: (libc)Termination Signals.
340
* SIGLOST: (libc)Operation Error Signals.
341
* SIGPIPE: (libc)Operation Error Signals.
342
* SIGPOLL: (libc)Asynchronous I/O Signals.
343
* SIGPROF: (libc)Alarm Signals.
344
* SIGQUIT: (libc)Termination Signals.
345
* SIGSEGV: (libc)Program Error Signals.
346
* SIGSTOP: (libc)Job Control Signals.
347
* SIGSYS: (libc)Program Error Signals.
348
* SIGTERM: (libc)Termination Signals.
349
* SIGTRAP: (libc)Program Error Signals.
350
* SIGTSTP: (libc)Job Control Signals.
351
* SIGTTIN: (libc)Job Control Signals.
352
* SIGTTOU: (libc)Job Control Signals.
353
* SIGURG: (libc)Asynchronous I/O Signals.
354
* SIGUSR1: (libc)Miscellaneous Signals.
355
* SIGUSR2: (libc)Miscellaneous Signals.
356
* SIGVTALRM: (libc)Alarm Signals.
357
* SIGWINCH: (libc)Miscellaneous Signals.
358
* SIGXCPU: (libc)Operation Error Signals.
359
* SIGXFSZ: (libc)Operation Error Signals.
360
* SIG_ERR: (libc)Basic Signal Handling.
361
* SOCK_DGRAM: (libc)Communication Styles.
362
* SOCK_RAW: (libc)Communication Styles.
363
* SOCK_RDM: (libc)Communication Styles.
364
* SOCK_SEQPACKET: (libc)Communication Styles.
365
* SOCK_STREAM: (libc)Communication Styles.
366
* SOL_SOCKET: (libc)Socket-Level Options.
367
* SSIZE_MAX: (libc)General Limits.
368
* STREAM_MAX: (libc)General Limits.
369
* SUN_LEN: (libc)Local Namespace Details.
370
* SV_INTERRUPT: (libc)BSD Handler.
371
* SV_ONSTACK: (libc)BSD Handler.
372
* SV_RESETHAND: (libc)BSD Handler.
373
* S_IFMT: (libc)Testing File Type.
374
* S_ISBLK: (libc)Testing File Type.
375
* S_ISCHR: (libc)Testing File Type.
376
* S_ISDIR: (libc)Testing File Type.
377
* S_ISFIFO: (libc)Testing File Type.
378
* S_ISLNK: (libc)Testing File Type.
379
* S_ISREG: (libc)Testing File Type.
380
* S_ISSOCK: (libc)Testing File Type.
381
* S_TYPEISMQ: (libc)Testing File Type.
382
* S_TYPEISSEM: (libc)Testing File Type.
383
* S_TYPEISSHM: (libc)Testing File Type.
384
* TMP_MAX: (libc)Temporary Files.
385
* TOSTOP: (libc)Local Modes.
386
* TZNAME_MAX: (libc)General Limits.
387
* VDISCARD: (libc)Other Special.
388
* VDSUSP: (libc)Signal Characters.
389
* VEOF: (libc)Editing Characters.
390
* VEOL2: (libc)Editing Characters.
391
* VEOL: (libc)Editing Characters.
392
* VERASE: (libc)Editing Characters.
393
* VINTR: (libc)Signal Characters.
394
* VKILL: (libc)Editing Characters.
395
* VLNEXT: (libc)Other Special.
396
* VMIN: (libc)Noncanonical Input.
397
* VQUIT: (libc)Signal Characters.
398
* VREPRINT: (libc)Editing Characters.
399
* VSTART: (libc)Start/Stop Characters.
400
* VSTATUS: (libc)Other Special.
401
* VSTOP: (libc)Start/Stop Characters.
402
* VSUSP: (libc)Signal Characters.
403
* VTIME: (libc)Noncanonical Input.
404
* VWERASE: (libc)Editing Characters.
405
* WCHAR_MAX: (libc)Extended Char Intro.
406
* WCHAR_MIN: (libc)Extended Char Intro.
407
* WCOREDUMP: (libc)Process Completion Status.
408
* WEOF: (libc)EOF and Errors.
409
* WEOF: (libc)Extended Char Intro.
410
* WEXITSTATUS: (libc)Process Completion Status.
411
* WIFEXITED: (libc)Process Completion Status.
412
* WIFSIGNALED: (libc)Process Completion Status.
413
* WIFSTOPPED: (libc)Process Completion Status.
414
* WSTOPSIG: (libc)Process Completion Status.
415
* WTERMSIG: (libc)Process Completion Status.
416
* W_OK: (libc)Testing File Access.
417
* X_OK: (libc)Testing File Access.
418
* _Complex_I: (libc)Complex Numbers.
419
* _Exit: (libc)Termination Internals.
420
* _IOFBF: (libc)Controlling Buffering.
421
* _IOLBF: (libc)Controlling Buffering.
422
* _IONBF: (libc)Controlling Buffering.
423
* _Imaginary_I: (libc)Complex Numbers.
424
* _PATH_UTMP: (libc)Manipulating the Database.
425
* _PATH_WTMP: (libc)Manipulating the Database.
426
* _POSIX2_C_DEV: (libc)System Options.
427
* _POSIX2_C_VERSION: (libc)Version Supported.
428
* _POSIX2_FORT_DEV: (libc)System Options.
429
* _POSIX2_FORT_RUN: (libc)System Options.
430
* _POSIX2_LOCALEDEF: (libc)System Options.
431
* _POSIX2_SW_DEV: (libc)System Options.
432
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
433
* _POSIX_JOB_CONTROL: (libc)System Options.
434
* _POSIX_NO_TRUNC: (libc)Options for Files.
435
* _POSIX_SAVED_IDS: (libc)System Options.
436
* _POSIX_VDISABLE: (libc)Options for Files.
437
* _POSIX_VERSION: (libc)Version Supported.
438
* __fbufsize: (libc)Controlling Buffering.
439
* __flbf: (libc)Controlling Buffering.
440
* __fpending: (libc)Controlling Buffering.
441
* __fpurge: (libc)Flushing Buffers.
442
* __freadable: (libc)Opening Streams.
443
* __freading: (libc)Opening Streams.
444
* __fsetlocking: (libc)Streams and Threads.
445
* __fwritable: (libc)Opening Streams.
446
* __fwriting: (libc)Opening Streams.
447
* __gconv_end_fct: (libc)glibc iconv Implementation.
448
* __gconv_fct: (libc)glibc iconv Implementation.
449
* __gconv_init_fct: (libc)glibc iconv Implementation.
450
* __va_copy: (libc)Argument Macros.
451
* _exit: (libc)Termination Internals.
452
* _flushlbf: (libc)Flushing Buffers.
453
* _tolower: (libc)Case Conversion.
454
* _toupper: (libc)Case Conversion.
455
* a64l: (libc)Encode Binary Data.
456
* abort: (libc)Aborting a Program.
457
* abs: (libc)Absolute Value.
458
* accept: (libc)Accepting Connections.
459
* access: (libc)Testing File Access.
460
* acos: (libc)Inverse Trig Functions.
461
* acosf: (libc)Inverse Trig Functions.
462
* acosh: (libc)Hyperbolic Functions.
463
* acoshf: (libc)Hyperbolic Functions.
464
* acoshl: (libc)Hyperbolic Functions.
465
* acosl: (libc)Inverse Trig Functions.
466
* addmntent: (libc)mtab.
467
* addseverity: (libc)Adding Severity Classes.
468
* adjtime: (libc)High-Resolution Calendar.
469
* adjtimex: (libc)High-Resolution Calendar.
470
* aio_cancel64: (libc)Cancel AIO Operations.
471
* aio_cancel: (libc)Cancel AIO Operations.
472
* aio_error64: (libc)Status of AIO Operations.
473
* aio_error: (libc)Status of AIO Operations.
474
* aio_fsync64: (libc)Synchronizing AIO Operations.
475
* aio_fsync: (libc)Synchronizing AIO Operations.
476
* aio_init: (libc)Configuration of AIO.
477
* aio_read64: (libc)Asynchronous Reads/Writes.
478
* aio_read: (libc)Asynchronous Reads/Writes.
479
* aio_return64: (libc)Status of AIO Operations.
480
* aio_return: (libc)Status of AIO Operations.
481
* aio_suspend64: (libc)Synchronizing AIO Operations.
482
* aio_suspend: (libc)Synchronizing AIO Operations.
483
* aio_write64: (libc)Asynchronous Reads/Writes.
484
* aio_write: (libc)Asynchronous Reads/Writes.
485
* alarm: (libc)Setting an Alarm.
486
* alloca: (libc)Variable Size Automatic.
487
* alphasort64: (libc)Scanning Directory Content.
488
* alphasort: (libc)Scanning Directory Content.
489
* argp_error: (libc)Argp Helper Functions.
490
* argp_failure: (libc)Argp Helper Functions.
491
* argp_help: (libc)Argp Help.
492
* argp_parse: (libc)Argp.
493
* argp_state_help: (libc)Argp Helper Functions.
494
* argp_usage: (libc)Argp Helper Functions.
495
* argz_add: (libc)Argz Functions.
496
* argz_add_sep: (libc)Argz Functions.
497
* argz_append: (libc)Argz Functions.
498
* argz_count: (libc)Argz Functions.
499
* argz_create: (libc)Argz Functions.
500
* argz_create_sep: (libc)Argz Functions.
501
* argz_delete: (libc)Argz Functions.
502
* argz_extract: (libc)Argz Functions.
503
* argz_insert: (libc)Argz Functions.
504
* argz_next: (libc)Argz Functions.
505
* argz_replace: (libc)Argz Functions.
506
* argz_stringify: (libc)Argz Functions.
507
* asctime: (libc)Formatting Calendar Time.
508
* asctime_r: (libc)Formatting Calendar Time.
509
* asin: (libc)Inverse Trig Functions.
510
* asinf: (libc)Inverse Trig Functions.
511
* asinh: (libc)Hyperbolic Functions.
512
* asinhf: (libc)Hyperbolic Functions.
513
* asinhl: (libc)Hyperbolic Functions.
514
* asinl: (libc)Inverse Trig Functions.
515
* asprintf: (libc)Dynamic Output.
516
* assert: (libc)Consistency Checking.
517
* assert_perror: (libc)Consistency Checking.
518
* atan2: (libc)Inverse Trig Functions.
519
* atan2f: (libc)Inverse Trig Functions.
520
* atan2l: (libc)Inverse Trig Functions.
521
* atan: (libc)Inverse Trig Functions.
522
* atanf: (libc)Inverse Trig Functions.
523
* atanh: (libc)Hyperbolic Functions.
524
* atanhf: (libc)Hyperbolic Functions.
525
* atanhl: (libc)Hyperbolic Functions.
526
* atanl: (libc)Inverse Trig Functions.
527
* atexit: (libc)Cleanups on Exit.
528
* atof: (libc)Parsing of Floats.
529
* atoi: (libc)Parsing of Integers.
530
* atol: (libc)Parsing of Integers.
531
* atoll: (libc)Parsing of Integers.
532
* backtrace: (libc)Backtraces.
533
* backtrace_symbols: (libc)Backtraces.
534
* backtrace_symbols_fd: (libc)Backtraces.
535
* basename: (libc)Finding Tokens in a String.
536
* basename: (libc)Finding Tokens in a String.
537
* bcmp: (libc)String/Array Comparison.
538
* bcopy: (libc)Copying and Concatenation.
539
* bind: (libc)Setting Address.
540
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
541
* bindtextdomain: (libc)Locating gettext catalog.
542
* brk: (libc)Resizing the Data Segment.
543
* bsearch: (libc)Array Search Function.
544
* btowc: (libc)Converting a Character.
545
* bzero: (libc)Copying and Concatenation.
546
* cabs: (libc)Absolute Value.
547
* cabsf: (libc)Absolute Value.
548
* cabsl: (libc)Absolute Value.
549
* cacos: (libc)Inverse Trig Functions.
550
* cacosf: (libc)Inverse Trig Functions.
551
* cacosh: (libc)Hyperbolic Functions.
552
* cacoshf: (libc)Hyperbolic Functions.
553
* cacoshl: (libc)Hyperbolic Functions.
554
* cacosl: (libc)Inverse Trig Functions.
555
* calloc: (libc)Allocating Cleared Space.
556
* canonicalize_file_name: (libc)Symbolic Links.
557
* carg: (libc)Operations on Complex.
558
* cargf: (libc)Operations on Complex.
559
* cargl: (libc)Operations on Complex.
560
* casin: (libc)Inverse Trig Functions.
561
* casinf: (libc)Inverse Trig Functions.
562
* casinh: (libc)Hyperbolic Functions.
563
* casinhf: (libc)Hyperbolic Functions.
564
* casinhl: (libc)Hyperbolic Functions.
565
* casinl: (libc)Inverse Trig Functions.
566
* catan: (libc)Inverse Trig Functions.
567
* catanf: (libc)Inverse Trig Functions.
568
* catanh: (libc)Hyperbolic Functions.
569
* catanhf: (libc)Hyperbolic Functions.
570
* catanhl: (libc)Hyperbolic Functions.
571
* catanl: (libc)Inverse Trig Functions.
572
* catclose: (libc)The catgets Functions.
573
* catgets: (libc)The catgets Functions.
574
* catopen: (libc)The catgets Functions.
575
* cbc_crypt: (libc)DES Encryption.
576
* cbrt: (libc)Exponents and Logarithms.
577
* cbrtf: (libc)Exponents and Logarithms.
578
* cbrtl: (libc)Exponents and Logarithms.
579
* ccos: (libc)Trig Functions.
580
* ccosf: (libc)Trig Functions.
581
* ccosh: (libc)Hyperbolic Functions.
582
* ccoshf: (libc)Hyperbolic Functions.
583
* ccoshl: (libc)Hyperbolic Functions.
584
* ccosl: (libc)Trig Functions.
585
* ceil: (libc)Rounding Functions.
586
* ceilf: (libc)Rounding Functions.
587
* ceill: (libc)Rounding Functions.
588
* cexp: (libc)Exponents and Logarithms.
589
* cexpf: (libc)Exponents and Logarithms.
590
* cexpl: (libc)Exponents and Logarithms.
591
* cfgetispeed: (libc)Line Speed.
592
* cfgetospeed: (libc)Line Speed.
593
* cfmakeraw: (libc)Noncanonical Input.
594
* cfree: (libc)Freeing after Malloc.
595
* cfsetispeed: (libc)Line Speed.
596
* cfsetospeed: (libc)Line Speed.
597
* cfsetspeed: (libc)Line Speed.
598
* chdir: (libc)Working Directory.
599
* chmod: (libc)Setting Permissions.
600
* chown: (libc)File Owner.
601
* cimag: (libc)Operations on Complex.
602
* cimagf: (libc)Operations on Complex.
603
* cimagl: (libc)Operations on Complex.
604
* clearenv: (libc)Environment Access.
605
* clearerr: (libc)Error Recovery.
606
* clearerr_unlocked: (libc)Error Recovery.
607
* clock: (libc)CPU Time.
608
* clog10: (libc)Exponents and Logarithms.
609
* clog10f: (libc)Exponents and Logarithms.
610
* clog10l: (libc)Exponents and Logarithms.
611
* clog: (libc)Exponents and Logarithms.
612
* clogf: (libc)Exponents and Logarithms.
613
* clogl: (libc)Exponents and Logarithms.
614
* close: (libc)Opening and Closing Files.
615
* closedir: (libc)Reading/Closing Directory.
616
* closelog: (libc)closelog.
617
* confstr: (libc)String Parameters.
618
* conj: (libc)Operations on Complex.
619
* conjf: (libc)Operations on Complex.
620
* conjl: (libc)Operations on Complex.
621
* connect: (libc)Connecting.
622
* copysign: (libc)FP Bit Twiddling.
623
* copysignf: (libc)FP Bit Twiddling.
624
* copysignl: (libc)FP Bit Twiddling.
625
* cos: (libc)Trig Functions.
626
* cosf: (libc)Trig Functions.
627
* cosh: (libc)Hyperbolic Functions.
628
* coshf: (libc)Hyperbolic Functions.
629
* coshl: (libc)Hyperbolic Functions.
630
* cosl: (libc)Trig Functions.
631
* cpow: (libc)Exponents and Logarithms.
632
* cpowf: (libc)Exponents and Logarithms.
633
* cpowl: (libc)Exponents and Logarithms.
634
* cproj: (libc)Operations on Complex.
635
* cprojf: (libc)Operations on Complex.
636
* cprojl: (libc)Operations on Complex.
637
* creal: (libc)Operations on Complex.
638
* crealf: (libc)Operations on Complex.
639
* creall: (libc)Operations on Complex.
640
* creat64: (libc)Opening and Closing Files.
641
* creat: (libc)Opening and Closing Files.
642
* crypt: (libc)crypt.
643
* crypt_r: (libc)crypt.
644
* csin: (libc)Trig Functions.
645
* csinf: (libc)Trig Functions.
646
* csinh: (libc)Hyperbolic Functions.
647
* csinhf: (libc)Hyperbolic Functions.
648
* csinhl: (libc)Hyperbolic Functions.
649
* csinl: (libc)Trig Functions.
650
* csqrt: (libc)Exponents and Logarithms.
651
* csqrtf: (libc)Exponents and Logarithms.
652
* csqrtl: (libc)Exponents and Logarithms.
653
* ctan: (libc)Trig Functions.
654
* ctanf: (libc)Trig Functions.
655
* ctanh: (libc)Hyperbolic Functions.
656
* ctanhf: (libc)Hyperbolic Functions.
657
* ctanhl: (libc)Hyperbolic Functions.
658
* ctanl: (libc)Trig Functions.
659
* ctermid: (libc)Identifying the Terminal.
660
* ctime: (libc)Formatting Calendar Time.
661
* ctime_r: (libc)Formatting Calendar Time.
662
* cuserid: (libc)Who Logged In.
663
* dcgettext: (libc)Translation with gettext.
664
* dcngettext: (libc)Advanced gettext functions.
665
* des_setparity: (libc)DES Encryption.
666
* dgettext: (libc)Translation with gettext.
667
* difftime: (libc)Elapsed Time.
668
* dirfd: (libc)Opening a Directory.
669
* dirname: (libc)Finding Tokens in a String.
670
* div: (libc)Integer Division.
671
* dngettext: (libc)Advanced gettext functions.
672
* drand48: (libc)SVID Random.
673
* drand48_r: (libc)SVID Random.
674
* drem: (libc)Remainder Functions.
675
* dremf: (libc)Remainder Functions.
676
* dreml: (libc)Remainder Functions.
677
* dup2: (libc)Duplicating Descriptors.
678
* dup: (libc)Duplicating Descriptors.
679
* ecb_crypt: (libc)DES Encryption.
680
* ecvt: (libc)System V Number Conversion.
681
* ecvt_r: (libc)System V Number Conversion.
682
* encrypt: (libc)DES Encryption.
683
* encrypt_r: (libc)DES Encryption.
684
* endfsent: (libc)fstab.
685
* endgrent: (libc)Scanning All Groups.
686
* endhostent: (libc)Host Names.
687
* endmntent: (libc)mtab.
688
* endnetent: (libc)Networks Database.
689
* endnetgrent: (libc)Lookup Netgroup.
690
* endprotoent: (libc)Protocols Database.
691
* endpwent: (libc)Scanning All Users.
692
* endservent: (libc)Services Database.
693
* endutent: (libc)Manipulating the Database.
694
* endutxent: (libc)XPG Functions.
695
* envz_add: (libc)Envz Functions.
696
* envz_entry: (libc)Envz Functions.
697
* envz_get: (libc)Envz Functions.
698
* envz_merge: (libc)Envz Functions.
699
* envz_strip: (libc)Envz Functions.
700
* erand48: (libc)SVID Random.
701
* erand48_r: (libc)SVID Random.
702
* erf: (libc)Special Functions.
703
* erfc: (libc)Special Functions.
704
* erfcf: (libc)Special Functions.
705
* erfcl: (libc)Special Functions.
706
* erff: (libc)Special Functions.
707
* erfl: (libc)Special Functions.
708
* err: (libc)Error Messages.
709
* errno: (libc)Checking for Errors.
710
* error: (libc)Error Messages.
711
* error_at_line: (libc)Error Messages.
712
* errx: (libc)Error Messages.
713
* execl: (libc)Executing a File.
714
* execle: (libc)Executing a File.
715
* execlp: (libc)Executing a File.
716
* execv: (libc)Executing a File.
717
* execve: (libc)Executing a File.
718
* execvp: (libc)Executing a File.
719
* exit: (libc)Normal Termination.
720
* exp10: (libc)Exponents and Logarithms.
721
* exp10f: (libc)Exponents and Logarithms.
722
* exp10l: (libc)Exponents and Logarithms.
723
* exp2: (libc)Exponents and Logarithms.
724
* exp2f: (libc)Exponents and Logarithms.
725
* exp2l: (libc)Exponents and Logarithms.
726
* exp: (libc)Exponents and Logarithms.
727
* expf: (libc)Exponents and Logarithms.
728
* expl: (libc)Exponents and Logarithms.
729
* expm1: (libc)Exponents and Logarithms.
730
* expm1f: (libc)Exponents and Logarithms.
731
* expm1l: (libc)Exponents and Logarithms.
732
* fabs: (libc)Absolute Value.
733
* fabsf: (libc)Absolute Value.
734
* fabsl: (libc)Absolute Value.
735
* fchdir: (libc)Working Directory.
736
* fchmod: (libc)Setting Permissions.
737
* fchown: (libc)File Owner.
738
* fclean: (libc)Cleaning Streams.
739
* fclose: (libc)Closing Streams.
740
* fcloseall: (libc)Closing Streams.
741
* fcntl: (libc)Control Operations.
742
* fcvt: (libc)System V Number Conversion.
743
* fcvt_r: (libc)System V Number Conversion.
744
* fdatasync: (libc)Synchronizing I/O.
745
* fdim: (libc)Misc FP Arithmetic.
746
* fdimf: (libc)Misc FP Arithmetic.
747
* fdiml: (libc)Misc FP Arithmetic.
748
* fdopen: (libc)Descriptors and Streams.
749
* fdopendir: (libc)Opening a Directory.
750
* feclearexcept: (libc)Status bit operations.
751
* fedisableexcept: (libc)Control Functions.
752
* feenableexcept: (libc)Control Functions.
753
* fegetenv: (libc)Control Functions.
754
* fegetexcept: (libc)Control Functions.
755
* fegetexceptflag: (libc)Status bit operations.
756
* fegetround: (libc)Rounding.
757
* feholdexcept: (libc)Control Functions.
758
* feof: (libc)EOF and Errors.
759
* feof_unlocked: (libc)EOF and Errors.
760
* feraiseexcept: (libc)Status bit operations.
761
* ferror: (libc)EOF and Errors.
762
* ferror_unlocked: (libc)EOF and Errors.
763
* fesetenv: (libc)Control Functions.
764
* fesetexceptflag: (libc)Status bit operations.
765
* fesetround: (libc)Rounding.
766
* fetestexcept: (libc)Status bit operations.
767
* feupdateenv: (libc)Control Functions.
768
* fflush: (libc)Flushing Buffers.
769
* fflush_unlocked: (libc)Flushing Buffers.
770
* fgetc: (libc)Character Input.
771
* fgetc_unlocked: (libc)Character Input.
772
* fgetgrent: (libc)Scanning All Groups.
773
* fgetgrent_r: (libc)Scanning All Groups.
774
* fgetpos64: (libc)Portable Positioning.
775
* fgetpos: (libc)Portable Positioning.
776
* fgetpwent: (libc)Scanning All Users.
777
* fgetpwent_r: (libc)Scanning All Users.
778
* fgets: (libc)Line Input.
779
* fgets_unlocked: (libc)Line Input.
780
* fgetwc: (libc)Character Input.
781
* fgetwc_unlocked: (libc)Character Input.
782
* fgetws: (libc)Line Input.
783
* fgetws_unlocked: (libc)Line Input.
784
* fileno: (libc)Descriptors and Streams.
785
* fileno_unlocked: (libc)Descriptors and Streams.
786
* finite: (libc)Floating Point Classes.
787
* finitef: (libc)Floating Point Classes.
788
* finitel: (libc)Floating Point Classes.
789
* flockfile: (libc)Streams and Threads.
790
* floor: (libc)Rounding Functions.
791
* floorf: (libc)Rounding Functions.
792
* floorl: (libc)Rounding Functions.
793
* fma: (libc)Misc FP Arithmetic.
794
* fmaf: (libc)Misc FP Arithmetic.
795
* fmal: (libc)Misc FP Arithmetic.
796
* fmax: (libc)Misc FP Arithmetic.
797
* fmaxf: (libc)Misc FP Arithmetic.
798
* fmaxl: (libc)Misc FP Arithmetic.
799
* fmemopen: (libc)String Streams.
800
* fmin: (libc)Misc FP Arithmetic.
801
* fminf: (libc)Misc FP Arithmetic.
802
* fminl: (libc)Misc FP Arithmetic.
803
* fmod: (libc)Remainder Functions.
804
* fmodf: (libc)Remainder Functions.
805
* fmodl: (libc)Remainder Functions.
806
* fmtmsg: (libc)Printing Formatted Messages.
807
* fnmatch: (libc)Wildcard Matching.
808
* fopen64: (libc)Opening Streams.
809
* fopen: (libc)Opening Streams.
810
* fopencookie: (libc)Streams and Cookies.
811
* fork: (libc)Creating a Process.
812
* forkpty: (libc)Pseudo-Terminal Pairs.
813
* fpathconf: (libc)Pathconf.
814
* fpclassify: (libc)Floating Point Classes.
815
* fprintf: (libc)Formatted Output Functions.
816
* fputc: (libc)Simple Output.
817
* fputc_unlocked: (libc)Simple Output.
818
* fputs: (libc)Simple Output.
819
* fputs_unlocked: (libc)Simple Output.
820
* fputwc: (libc)Simple Output.
821
* fputwc_unlocked: (libc)Simple Output.
822
* fputws: (libc)Simple Output.
823
* fputws_unlocked: (libc)Simple Output.
824
* fread: (libc)Block Input/Output.
825
* fread_unlocked: (libc)Block Input/Output.
826
* free: (libc)Freeing after Malloc.
827
* freopen64: (libc)Opening Streams.
828
* freopen: (libc)Opening Streams.
829
* frexp: (libc)Normalization Functions.
830
* frexpf: (libc)Normalization Functions.
831
* frexpl: (libc)Normalization Functions.
832
* fscanf: (libc)Formatted Input Functions.
833
* fseek: (libc)File Positioning.
834
* fseeko64: (libc)File Positioning.
835
* fseeko: (libc)File Positioning.
836
* fsetpos64: (libc)Portable Positioning.
837
* fsetpos: (libc)Portable Positioning.
838
* fstat64: (libc)Reading Attributes.
839
* fstat: (libc)Reading Attributes.
840
* fsync: (libc)Synchronizing I/O.
841
* ftell: (libc)File Positioning.
842
* ftello64: (libc)File Positioning.
843
* ftello: (libc)File Positioning.
844
* ftruncate64: (libc)File Size.
845
* ftruncate: (libc)File Size.
846
* ftrylockfile: (libc)Streams and Threads.
847
* ftw64: (libc)Working with Directory Trees.
848
* ftw: (libc)Working with Directory Trees.
849
* funlockfile: (libc)Streams and Threads.
850
* futimes: (libc)File Times.
851
* fwide: (libc)Streams and I18N.
852
* fwprintf: (libc)Formatted Output Functions.
853
* fwrite: (libc)Block Input/Output.
854
* fwrite_unlocked: (libc)Block Input/Output.
855
* fwscanf: (libc)Formatted Input Functions.
856
* gamma: (libc)Special Functions.
857
* gammaf: (libc)Special Functions.
858
* gammal: (libc)Special Functions.
859
* gcvt: (libc)System V Number Conversion.
860
* get_avphys_pages: (libc)Query Memory Parameters.
861
* get_current_dir_name: (libc)Working Directory.
862
* get_nprocs: (libc)Processor Resources.
863
* get_nprocs_conf: (libc)Processor Resources.
864
* get_phys_pages: (libc)Query Memory Parameters.
865
* getc: (libc)Character Input.
866
* getc_unlocked: (libc)Character Input.
867
* getchar: (libc)Character Input.
868
* getchar_unlocked: (libc)Character Input.
869
* getcontext: (libc)System V contexts.
870
* getcwd: (libc)Working Directory.
871
* getdate: (libc)General Time String Parsing.
872
* getdate_r: (libc)General Time String Parsing.
873
* getdelim: (libc)Line Input.
874
* getdomainnname: (libc)Host Identification.
875
* getegid: (libc)Reading Persona.
876
* getenv: (libc)Environment Access.
877
* geteuid: (libc)Reading Persona.
878
* getfsent: (libc)fstab.
879
* getfsfile: (libc)fstab.
880
* getfsspec: (libc)fstab.
881
* getgid: (libc)Reading Persona.
882
* getgrent: (libc)Scanning All Groups.
883
* getgrent_r: (libc)Scanning All Groups.
884
* getgrgid: (libc)Lookup Group.
885
* getgrgid_r: (libc)Lookup Group.
886
* getgrnam: (libc)Lookup Group.
887
* getgrnam_r: (libc)Lookup Group.
888
* getgrouplist: (libc)Setting Groups.
889
* getgroups: (libc)Reading Persona.
890
* gethostbyaddr: (libc)Host Names.
891
* gethostbyaddr_r: (libc)Host Names.
892
* gethostbyname2: (libc)Host Names.
893
* gethostbyname2_r: (libc)Host Names.
894
* gethostbyname: (libc)Host Names.
895
* gethostbyname_r: (libc)Host Names.
896
* gethostent: (libc)Host Names.
897
* gethostid: (libc)Host Identification.
898
* gethostname: (libc)Host Identification.
899
* getitimer: (libc)Setting an Alarm.
900
* getline: (libc)Line Input.
901
* getloadavg: (libc)Processor Resources.
902
* getlogin: (libc)Who Logged In.
903
* getmntent: (libc)mtab.
904
* getmntent_r: (libc)mtab.
905
* getnetbyaddr: (libc)Networks Database.
906
* getnetbyname: (libc)Networks Database.
907
* getnetent: (libc)Networks Database.
908
* getnetgrent: (libc)Lookup Netgroup.
909
* getnetgrent_r: (libc)Lookup Netgroup.
910
* getopt: (libc)Using Getopt.
911
* getopt_long: (libc)Getopt Long Options.
912
* getopt_long_only: (libc)Getopt Long Options.
913
* getpagesize: (libc)Query Memory Parameters.
914
* getpass: (libc)getpass.
915
* getpeername: (libc)Who is Connected.
916
* getpgid: (libc)Process Group Functions.
917
* getpgrp: (libc)Process Group Functions.
918
* getpgrp: (libc)Process Group Functions.
919
* getpid: (libc)Process Identification.
920
* getppid: (libc)Process Identification.
921
* getpriority: (libc)Traditional Scheduling Functions.
922
* getprotobyname: (libc)Protocols Database.
923
* getprotobynumber: (libc)Protocols Database.
924
* getprotoent: (libc)Protocols Database.
925
* getpt: (libc)Allocation.
926
* getpwent: (libc)Scanning All Users.
927
* getpwent_r: (libc)Scanning All Users.
928
* getpwnam: (libc)Lookup User.
929
* getpwnam_r: (libc)Lookup User.
930
* getpwuid: (libc)Lookup User.
931
* getpwuid_r: (libc)Lookup User.
932
* getrlimit64: (libc)Limits on Resources.
933
* getrlimit: (libc)Limits on Resources.
934
* getrusage: (libc)Resource Usage.
935
* gets: (libc)Line Input.
936
* getservbyname: (libc)Services Database.
937
* getservbyport: (libc)Services Database.
938
* getservent: (libc)Services Database.
939
* getsid: (libc)Process Group Functions.
940
* getsockname: (libc)Reading Address.
941
* getsockopt: (libc)Socket Option Functions.
942
* getsubopt: (libc)Suboptions.
943
* gettext: (libc)Translation with gettext.
944
* gettimeofday: (libc)High-Resolution Calendar.
945
* getuid: (libc)Reading Persona.
946
* getumask: (libc)Setting Permissions.
947
* getutent: (libc)Manipulating the Database.
948
* getutent_r: (libc)Manipulating the Database.
949
* getutid: (libc)Manipulating the Database.
950
* getutid_r: (libc)Manipulating the Database.
951
* getutline: (libc)Manipulating the Database.
952
* getutline_r: (libc)Manipulating the Database.
953
* getutmp: (libc)XPG Functions.
954
* getutmpx: (libc)XPG Functions.
955
* getutxent: (libc)XPG Functions.
956
* getutxid: (libc)XPG Functions.
957
* getutxline: (libc)XPG Functions.
958
* getw: (libc)Character Input.
959
* getwc: (libc)Character Input.
960
* getwc_unlocked: (libc)Character Input.
961
* getwchar: (libc)Character Input.
962
* getwchar_unlocked: (libc)Character Input.
963
* getwd: (libc)Working Directory.
964
* glob64: (libc)Calling Glob.
965
* glob: (libc)Calling Glob.
966
* globfree64: (libc)More Flags for Globbing.
967
* globfree: (libc)More Flags for Globbing.
968
* gmtime: (libc)Broken-down Time.
969
* gmtime_r: (libc)Broken-down Time.
970
* grantpt: (libc)Allocation.
971
* gsignal: (libc)Signaling Yourself.
972
* gtty: (libc)BSD Terminal Modes.
973
* hasmntopt: (libc)mtab.
974
* hcreate: (libc)Hash Search Function.
975
* hcreate_r: (libc)Hash Search Function.
976
* hdestroy: (libc)Hash Search Function.
977
* hdestroy_r: (libc)Hash Search Function.
978
* hsearch: (libc)Hash Search Function.
979
* hsearch_r: (libc)Hash Search Function.
980
* htonl: (libc)Byte Order.
981
* htons: (libc)Byte Order.
982
* hypot: (libc)Exponents and Logarithms.
983
* hypotf: (libc)Exponents and Logarithms.
984
* hypotl: (libc)Exponents and Logarithms.
985
* iconv: (libc)Generic Conversion Interface.
986
* iconv_close: (libc)Generic Conversion Interface.
987
* iconv_open: (libc)Generic Conversion Interface.
988
* if_freenameindex: (libc)Interface Naming.
989
* if_indextoname: (libc)Interface Naming.
990
* if_nameindex: (libc)Interface Naming.
991
* if_nametoindex: (libc)Interface Naming.
992
* ilogb: (libc)Exponents and Logarithms.
993
* ilogbf: (libc)Exponents and Logarithms.
994
* ilogbl: (libc)Exponents and Logarithms.
995
* imaxabs: (libc)Absolute Value.
996
* imaxdiv: (libc)Integer Division.
997
* in6addr_any: (libc)Host Address Data Type.
998
* in6addr_loopback: (libc)Host Address Data Type.
999
* index: (libc)Search Functions.
1000
* inet_addr: (libc)Host Address Functions.
1001
* inet_aton: (libc)Host Address Functions.
1002
* inet_lnaof: (libc)Host Address Functions.
1003
* inet_makeaddr: (libc)Host Address Functions.
1004
* inet_netof: (libc)Host Address Functions.
1005
* inet_network: (libc)Host Address Functions.
1006
* inet_ntoa: (libc)Host Address Functions.
1007
* inet_ntop: (libc)Host Address Functions.
1008
* inet_pton: (libc)Host Address Functions.
1009
* initgroups: (libc)Setting Groups.
1010
* initstate: (libc)BSD Random.
1011
* initstate_r: (libc)BSD Random.
1012
* innetgr: (libc)Netgroup Membership.
1013
* int: (libc)Random Access Directory.
1014
* ioctl: (libc)IOCTLs.
1015
* isalnum: (libc)Classification of Characters.
1016
* isalpha: (libc)Classification of Characters.
1017
* isascii: (libc)Classification of Characters.
1018
* isatty: (libc)Is It a Terminal.
1019
* isblank: (libc)Classification of Characters.
1020
* iscntrl: (libc)Classification of Characters.
1021
* isdigit: (libc)Classification of Characters.
1022
* isfinite: (libc)Floating Point Classes.
1023
* isgraph: (libc)Classification of Characters.
1024
* isgreater: (libc)FP Comparison Functions.
1025
* isgreaterequal: (libc)FP Comparison Functions.
1026
* isinf: (libc)Floating Point Classes.
1027
* isinff: (libc)Floating Point Classes.
1028
* isinfl: (libc)Floating Point Classes.
1029
* isless: (libc)FP Comparison Functions.
1030
* islessequal: (libc)FP Comparison Functions.
1031
* islessgreater: (libc)FP Comparison Functions.
1032
* islower: (libc)Classification of Characters.
1033
* isnan: (libc)Floating Point Classes.
1034
* isnan: (libc)Floating Point Classes.
1035
* isnanf: (libc)Floating Point Classes.
1036
* isnanl: (libc)Floating Point Classes.
1037
* isnormal: (libc)Floating Point Classes.
1038
* isprint: (libc)Classification of Characters.
1039
* ispunct: (libc)Classification of Characters.
1040
* isspace: (libc)Classification of Characters.
1041
* isunordered: (libc)FP Comparison Functions.
1042
* isupper: (libc)Classification of Characters.
1043
* iswalnum: (libc)Classification of Wide Characters.
1044
* iswalpha: (libc)Classification of Wide Characters.
1045
* iswblank: (libc)Classification of Wide Characters.
1046
* iswcntrl: (libc)Classification of Wide Characters.
1047
* iswctype: (libc)Classification of Wide Characters.
1048
* iswdigit: (libc)Classification of Wide Characters.
1049
* iswgraph: (libc)Classification of Wide Characters.
1050
* iswlower: (libc)Classification of Wide Characters.
1051
* iswprint: (libc)Classification of Wide Characters.
1052
* iswpunct: (libc)Classification of Wide Characters.
1053
* iswspace: (libc)Classification of Wide Characters.
1054
* iswupper: (libc)Classification of Wide Characters.
1055
* iswxdigit: (libc)Classification of Wide Characters.
1056
* isxdigit: (libc)Classification of Characters.
1057
* j0: (libc)Special Functions.
1058
* j0f: (libc)Special Functions.
1059
* j0l: (libc)Special Functions.
1060
* j1: (libc)Special Functions.
1061
* j1f: (libc)Special Functions.
1062
* j1l: (libc)Special Functions.
1063
* jn: (libc)Special Functions.
1064
* jnf: (libc)Special Functions.
1065
* jnl: (libc)Special Functions.
1066
* jrand48: (libc)SVID Random.
1067
* jrand48_r: (libc)SVID Random.
1068
* kill: (libc)Signaling Another Process.
1069
* killpg: (libc)Signaling Another Process.
1070
* l64a: (libc)Encode Binary Data.
1071
* labs: (libc)Absolute Value.
1072
* lcong48: (libc)SVID Random.
1073
* lcong48_r: (libc)SVID Random.
1074
* ldexp: (libc)Normalization Functions.
1075
* ldexpf: (libc)Normalization Functions.
1076
* ldexpl: (libc)Normalization Functions.
1077
* ldiv: (libc)Integer Division.
1078
* lfind: (libc)Array Search Function.
1079
* lgamma: (libc)Special Functions.
1080
* lgamma_r: (libc)Special Functions.
1081
* lgammaf: (libc)Special Functions.
1082
* lgammaf_r: (libc)Special Functions.
1083
* lgammal: (libc)Special Functions.
1084
* lgammal_r: (libc)Special Functions.
1085
* link: (libc)Hard Links.
1086
* lio_listio64: (libc)Asynchronous Reads/Writes.
1087
* lio_listio: (libc)Asynchronous Reads/Writes.
1088
* listen: (libc)Listening.
1089
* llabs: (libc)Absolute Value.
1090
* lldiv: (libc)Integer Division.
1091
* llrint: (libc)Rounding Functions.
1092
* llrintf: (libc)Rounding Functions.
1093
* llrintl: (libc)Rounding Functions.
1094
* llround: (libc)Rounding Functions.
1095
* llroundf: (libc)Rounding Functions.
1096
* llroundl: (libc)Rounding Functions.
1097
* localeconv: (libc)The Lame Way to Locale Data.
1098
* localtime: (libc)Broken-down Time.
1099
* localtime_r: (libc)Broken-down Time.
1100
* log10: (libc)Exponents and Logarithms.
1101
* log10f: (libc)Exponents and Logarithms.
1102
* log10l: (libc)Exponents and Logarithms.
1103
* log1p: (libc)Exponents and Logarithms.
1104
* log1pf: (libc)Exponents and Logarithms.
1105
* log1pl: (libc)Exponents and Logarithms.
1106
* log2: (libc)Exponents and Logarithms.
1107
* log2f: (libc)Exponents and Logarithms.
1108
* log2l: (libc)Exponents and Logarithms.
1109
* log: (libc)Exponents and Logarithms.
1110
* logb: (libc)Exponents and Logarithms.
1111
* logbf: (libc)Exponents and Logarithms.
1112
* logbl: (libc)Exponents and Logarithms.
1113
* logf: (libc)Exponents and Logarithms.
1114
* login: (libc)Logging In and Out.
1115
* login_tty: (libc)Logging In and Out.
1116
* logl: (libc)Exponents and Logarithms.
1117
* logout: (libc)Logging In and Out.
1118
* logwtmp: (libc)Logging In and Out.
1119
* longjmp: (libc)Non-Local Details.
1120
* lrand48: (libc)SVID Random.
1121
* lrand48_r: (libc)SVID Random.
1122
* lrint: (libc)Rounding Functions.
1123
* lrintf: (libc)Rounding Functions.
1124
* lrintl: (libc)Rounding Functions.
1125
* lround: (libc)Rounding Functions.
1126
* lroundf: (libc)Rounding Functions.
1127
* lroundl: (libc)Rounding Functions.
1128
* lsearch: (libc)Array Search Function.
1129
* lseek64: (libc)File Position Primitive.
1130
* lseek: (libc)File Position Primitive.
1131
* lstat64: (libc)Reading Attributes.
1132
* lstat: (libc)Reading Attributes.
1133
* lutimes: (libc)File Times.
1134
* madvise: (libc)Memory-mapped I/O.
1135
* makecontext: (libc)System V contexts.
1136
* mallinfo: (libc)Statistics of Malloc.
1137
* malloc: (libc)Basic Allocation.
1138
* mallopt: (libc)Malloc Tunable Parameters.
1139
* mblen: (libc)Non-reentrant Character Conversion.
1140
* mbrlen: (libc)Converting a Character.
1141
* mbrtowc: (libc)Converting a Character.
1142
* mbsinit: (libc)Keeping the state.
1143
* mbsnrtowcs: (libc)Converting Strings.
1144
* mbsrtowcs: (libc)Converting Strings.
1145
* mbstowcs: (libc)Non-reentrant String Conversion.
1146
* mbtowc: (libc)Non-reentrant Character Conversion.
1147
* mcheck: (libc)Heap Consistency Checking.
1148
* memalign: (libc)Aligned Memory Blocks.
1149
* memccpy: (libc)Copying and Concatenation.
1150
* memchr: (libc)Search Functions.
1151
* memcmp: (libc)String/Array Comparison.
1152
* memcpy: (libc)Copying and Concatenation.
1153
* memfrob: (libc)Trivial Encryption.
1154
* memmem: (libc)Search Functions.
1155
* memmove: (libc)Copying and Concatenation.
1156
* mempcpy: (libc)Copying and Concatenation.
1157
* memrchr: (libc)Search Functions.
1158
* memset: (libc)Copying and Concatenation.
1159
* mkdir: (libc)Creating Directories.
1160
* mkdtemp: (libc)Temporary Files.
1161
* mkfifo: (libc)FIFO Special Files.
1162
* mknod: (libc)Making Special Files.
1163
* mkstemp: (libc)Temporary Files.
1164
* mktemp: (libc)Temporary Files.
1165
* mktime: (libc)Broken-down Time.
1166
* mlock: (libc)Page Lock Functions.
1167
* mlockall: (libc)Page Lock Functions.
1168
* mmap64: (libc)Memory-mapped I/O.
1169
* mmap: (libc)Memory-mapped I/O.
1170
* modf: (libc)Rounding Functions.
1171
* modff: (libc)Rounding Functions.
1172
* modfl: (libc)Rounding Functions.
1173
* mount: (libc)Mount-Unmount-Remount.
1174
* mprobe: (libc)Heap Consistency Checking.
1175
* mrand48: (libc)SVID Random.
1176
* mrand48_r: (libc)SVID Random.
1177
* mremap: (libc)Memory-mapped I/O.
1178
* msync: (libc)Memory-mapped I/O.
1179
* mtrace: (libc)Tracing malloc.
1180
* munlock: (libc)Page Lock Functions.
1181
* munlockall: (libc)Page Lock Functions.
1182
* munmap: (libc)Memory-mapped I/O.
1183
* muntrace: (libc)Tracing malloc.
1184
* nan: (libc)FP Bit Twiddling.
1185
* nanf: (libc)FP Bit Twiddling.
1186
* nanl: (libc)FP Bit Twiddling.
1187
* nanosleep: (libc)Sleeping.
1188
* nearbyint: (libc)Rounding Functions.
1189
* nearbyintf: (libc)Rounding Functions.
1190
* nearbyintl: (libc)Rounding Functions.
1191
* nextafter: (libc)FP Bit Twiddling.
1192
* nextafterf: (libc)FP Bit Twiddling.
1193
* nextafterl: (libc)FP Bit Twiddling.
1194
* nexttoward: (libc)FP Bit Twiddling.
1195
* nexttowardf: (libc)FP Bit Twiddling.
1196
* nexttowardl: (libc)FP Bit Twiddling.
1197
* nftw64: (libc)Working with Directory Trees.
1198
* nftw: (libc)Working with Directory Trees.
1199
* ngettext: (libc)Advanced gettext functions.
1200
* nice: (libc)Traditional Scheduling Functions.
1201
* nl_langinfo: (libc)The Elegant and Fast Way.
1202
* nrand48: (libc)SVID Random.
1203
* nrand48_r: (libc)SVID Random.
1204
* ntohl: (libc)Byte Order.
1205
* ntohs: (libc)Byte Order.
1206
* ntp_adjtime: (libc)High Accuracy Clock.
1207
* ntp_gettime: (libc)High Accuracy Clock.
1208
* obstack_1grow: (libc)Growing Objects.
1209
* obstack_1grow_fast: (libc)Extra Fast Growing.
1210
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
1211
* obstack_alloc: (libc)Allocation in an Obstack.
1212
* obstack_base: (libc)Status of an Obstack.
1213
* obstack_blank: (libc)Growing Objects.
1214
* obstack_blank_fast: (libc)Extra Fast Growing.
1215
* obstack_chunk_size: (libc)Obstack Chunks.
1216
* obstack_copy0: (libc)Allocation in an Obstack.
1217
* obstack_copy: (libc)Allocation in an Obstack.
1218
* obstack_finish: (libc)Growing Objects.
1219
* obstack_free: (libc)Freeing Obstack Objects.
1220
* obstack_grow0: (libc)Growing Objects.
1221
* obstack_grow: (libc)Growing Objects.
1222
* obstack_init: (libc)Preparing for Obstacks.
1223
* obstack_int_grow: (libc)Growing Objects.
1224
* obstack_int_grow_fast: (libc)Extra Fast Growing.
1225
* obstack_next_free: (libc)Status of an Obstack.
1226
* obstack_object_size: (libc)Growing Objects.
1227
* obstack_object_size: (libc)Status of an Obstack.
1228
* obstack_printf: (libc)Dynamic Output.
1229
* obstack_ptr_grow: (libc)Growing Objects.
1230
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
1231
* obstack_room: (libc)Extra Fast Growing.
1232
* obstack_vprintf: (libc)Variable Arguments Output.
1233
* offsetof: (libc)Structure Measurement.
1234
* on_exit: (libc)Cleanups on Exit.
1235
* open64: (libc)Opening and Closing Files.
1236
* open: (libc)Opening and Closing Files.
1237
* open_memstream: (libc)String Streams.
1238
* open_obstack_stream: (libc)Obstack Streams.
1239
* opendir: (libc)Opening a Directory.
1240
* openlog: (libc)openlog.
1241
* openpty: (libc)Pseudo-Terminal Pairs.
1242
* parse_printf_format: (libc)Parsing a Template String.
1243
* pathconf: (libc)Pathconf.
1244
* pause: (libc)Using Pause.
1245
* pclose: (libc)Pipe to a Subprocess.
1246
* perror: (libc)Error Messages.
1247
* pipe: (libc)Creating a Pipe.
1248
* popen: (libc)Pipe to a Subprocess.
1249
* posix_memalign: (libc)Aligned Memory Blocks.
1250
* pow10: (libc)Exponents and Logarithms.
1251
* pow10f: (libc)Exponents and Logarithms.
1252
* pow10l: (libc)Exponents and Logarithms.
1253
* pow: (libc)Exponents and Logarithms.
1254
* powf: (libc)Exponents and Logarithms.
1255
* powl: (libc)Exponents and Logarithms.
1256
* pread64: (libc)I/O Primitives.
1257
* pread: (libc)I/O Primitives.
1258
* printf: (libc)Formatted Output Functions.
1259
* printf_size: (libc)Predefined Printf Handlers.
1260
* printf_size_info: (libc)Predefined Printf Handlers.
1261
* psignal: (libc)Signal Messages.
1262
* ptsname: (libc)Allocation.
1263
* ptsname_r: (libc)Allocation.
1264
* putc: (libc)Simple Output.
1265
* putc_unlocked: (libc)Simple Output.
1266
* putchar: (libc)Simple Output.
1267
* putchar_unlocked: (libc)Simple Output.
1268
* putenv: (libc)Environment Access.
1269
* putpwent: (libc)Writing a User Entry.
1270
* puts: (libc)Simple Output.
1271
* pututline: (libc)Manipulating the Database.
1272
* pututxline: (libc)XPG Functions.
1273
* putw: (libc)Simple Output.
1274
* putwc: (libc)Simple Output.
1275
* putwc_unlocked: (libc)Simple Output.
1276
* putwchar: (libc)Simple Output.
1277
* putwchar_unlocked: (libc)Simple Output.
1278
* pwrite64: (libc)I/O Primitives.
1279
* pwrite: (libc)I/O Primitives.
1280
* qecvt: (libc)System V Number Conversion.
1281
* qecvt_r: (libc)System V Number Conversion.
1282
* qfcvt: (libc)System V Number Conversion.
1283
* qfcvt_r: (libc)System V Number Conversion.
1284
* qgcvt: (libc)System V Number Conversion.
1285
* qsort: (libc)Array Sort Function.
1286
* raise: (libc)Signaling Yourself.
1287
* rand: (libc)ISO Random.
1288
* rand_r: (libc)ISO Random.
1289
* random: (libc)BSD Random.
1290
* random_r: (libc)BSD Random.
1291
* rawmemchr: (libc)Search Functions.
1292
* read: (libc)I/O Primitives.
1293
* readdir64: (libc)Reading/Closing Directory.
1294
* readdir64_r: (libc)Reading/Closing Directory.
1295
* readdir: (libc)Reading/Closing Directory.
1296
* readdir_r: (libc)Reading/Closing Directory.
1297
* readlink: (libc)Symbolic Links.
1298
* readv: (libc)Scatter-Gather.
1299
* realloc: (libc)Changing Block Size.
1300
* realpath: (libc)Symbolic Links.
1301
* recv: (libc)Receiving Data.
1302
* recvfrom: (libc)Receiving Datagrams.
1303
* recvmsg: (libc)Receiving Datagrams.
1304
* regcomp: (libc)POSIX Regexp Compilation.
1305
* regerror: (libc)Regexp Cleanup.
1306
* regexec: (libc)Matching POSIX Regexps.
1307
* regfree: (libc)Regexp Cleanup.
1308
* register_printf_function: (libc)Registering New Conversions.
1309
* remainder: (libc)Remainder Functions.
1310
* remainderf: (libc)Remainder Functions.
1311
* remainderl: (libc)Remainder Functions.
1312
* remove: (libc)Deleting Files.
1313
* rename: (libc)Renaming Files.
1314
* rewind: (libc)File Positioning.
1315
* rewinddir: (libc)Random Access Directory.
1316
* rindex: (libc)Search Functions.
1317
* rint: (libc)Rounding Functions.
1318
* rintf: (libc)Rounding Functions.
1319
* rintl: (libc)Rounding Functions.
1320
* rmdir: (libc)Deleting Files.
1321
* round: (libc)Rounding Functions.
1322
* roundf: (libc)Rounding Functions.
1323
* roundl: (libc)Rounding Functions.
1324
* rpmatch: (libc)Yes-or-No Questions.
1325
* sbrk: (libc)Resizing the Data Segment.
1326
* scalb: (libc)Normalization Functions.
1327
* scalbf: (libc)Normalization Functions.
1328
* scalbl: (libc)Normalization Functions.
1329
* scalbln: (libc)Normalization Functions.
1330
* scalblnf: (libc)Normalization Functions.
1331
* scalblnl: (libc)Normalization Functions.
1332
* scalbn: (libc)Normalization Functions.
1333
* scalbnf: (libc)Normalization Functions.
1334
* scalbnl: (libc)Normalization Functions.
1335
* scandir64: (libc)Scanning Directory Content.
1336
* scandir: (libc)Scanning Directory Content.
1337
* scanf: (libc)Formatted Input Functions.
1338
* sched_get_priority_max: (libc)Basic Scheduling Functions.
1339
* sched_get_priority_min: (libc)Basic Scheduling Functions.
1340
* sched_getaffinity: (libc)CPU Affinity.
1341
* sched_getparam: (libc)Basic Scheduling Functions.
1342
* sched_getscheduler: (libc)Basic Scheduling Functions.
1343
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
1344
* sched_setaffinity: (libc)CPU Affinity.
1345
* sched_setparam: (libc)Basic Scheduling Functions.
1346
* sched_setscheduler: (libc)Basic Scheduling Functions.
1347
* sched_yield: (libc)Basic Scheduling Functions.
1348
* seed48: (libc)SVID Random.
1349
* seed48_r: (libc)SVID Random.
1350
* seekdir: (libc)Random Access Directory.
1351
* select: (libc)Waiting for I/O.
1352
* send: (libc)Sending Data.
1353
* sendmsg: (libc)Receiving Datagrams.
1354
* sendto: (libc)Sending Datagrams.
1355
* setbuf: (libc)Controlling Buffering.
1356
* setbuffer: (libc)Controlling Buffering.
1357
* setcontext: (libc)System V contexts.
1358
* setdomainname: (libc)Host Identification.
1359
* setegid: (libc)Setting Groups.
1360
* setenv: (libc)Environment Access.
1361
* seteuid: (libc)Setting User ID.
1362
* setfsent: (libc)fstab.
1363
* setgid: (libc)Setting Groups.
1364
* setgrent: (libc)Scanning All Groups.
1365
* setgroups: (libc)Setting Groups.
1366
* sethostent: (libc)Host Names.
1367
* sethostid: (libc)Host Identification.
1368
* sethostname: (libc)Host Identification.
1369
* setitimer: (libc)Setting an Alarm.
1370
* setjmp: (libc)Non-Local Details.
1371
* setkey: (libc)DES Encryption.
1372
* setkey_r: (libc)DES Encryption.
1373
* setlinebuf: (libc)Controlling Buffering.
1374
* setlocale: (libc)Setting the Locale.
1375
* setlogmask: (libc)setlogmask.
1376
* setmntent: (libc)mtab.
1377
* setnetent: (libc)Networks Database.
1378
* setnetgrent: (libc)Lookup Netgroup.
1379
* setpgid: (libc)Process Group Functions.
1380
* setpgrp: (libc)Process Group Functions.
1381
* setpriority: (libc)Traditional Scheduling Functions.
1382
* setprotoent: (libc)Protocols Database.
1383
* setpwent: (libc)Scanning All Users.
1384
* setregid: (libc)Setting Groups.
1385
* setreuid: (libc)Setting User ID.
1386
* setrlimit64: (libc)Limits on Resources.
1387
* setrlimit: (libc)Limits on Resources.
1388
* setservent: (libc)Services Database.
1389
* setsid: (libc)Process Group Functions.
1390
* setsockopt: (libc)Socket Option Functions.
1391
* setstate: (libc)BSD Random.
1392
* setstate_r: (libc)BSD Random.
1393
* settimeofday: (libc)High-Resolution Calendar.
1394
* setuid: (libc)Setting User ID.
1395
* setutent: (libc)Manipulating the Database.
1396
* setutxent: (libc)XPG Functions.
1397
* setvbuf: (libc)Controlling Buffering.
1398
* shutdown: (libc)Closing a Socket.
1399
* sigaction: (libc)Advanced Signal Handling.
1400
* sigaddset: (libc)Signal Sets.
1401
* sigaltstack: (libc)Signal Stack.
1402
* sigblock: (libc)Blocking in BSD.
1403
* sigdelset: (libc)Signal Sets.
1404
* sigemptyset: (libc)Signal Sets.
1405
* sigfillset: (libc)Signal Sets.
1406
* siginterrupt: (libc)BSD Handler.
1407
* sigismember: (libc)Signal Sets.
1408
* siglongjmp: (libc)Non-Local Exits and Signals.
1409
* sigmask: (libc)Blocking in BSD.
1410
* signal: (libc)Basic Signal Handling.
1411
* signbit: (libc)FP Bit Twiddling.
1412
* significand: (libc)Normalization Functions.
1413
* significandf: (libc)Normalization Functions.
1414
* significandl: (libc)Normalization Functions.
1415
* sigpause: (libc)Blocking in BSD.
1416
* sigpending: (libc)Checking for Pending Signals.
1417
* sigprocmask: (libc)Process Signal Mask.
1418
* sigsetjmp: (libc)Non-Local Exits and Signals.
1419
* sigsetmask: (libc)Blocking in BSD.
1420
* sigstack: (libc)Signal Stack.
1421
* sigsuspend: (libc)Sigsuspend.
1422
* sigvec: (libc)BSD Handler.
1423
* sin: (libc)Trig Functions.
1424
* sincos: (libc)Trig Functions.
1425
* sincosf: (libc)Trig Functions.
1426
* sincosl: (libc)Trig Functions.
1427
* sinf: (libc)Trig Functions.
1428
* sinh: (libc)Hyperbolic Functions.
1429
* sinhf: (libc)Hyperbolic Functions.
1430
* sinhl: (libc)Hyperbolic Functions.
1431
* sinl: (libc)Trig Functions.
1432
* sleep: (libc)Sleeping.
1433
* snprintf: (libc)Formatted Output Functions.
1434
* socket: (libc)Creating a Socket.
1435
* socketpair: (libc)Socket Pairs.
1436
* sprintf: (libc)Formatted Output Functions.
1437
* sqrt: (libc)Exponents and Logarithms.
1438
* sqrtf: (libc)Exponents and Logarithms.
1439
* sqrtl: (libc)Exponents and Logarithms.
1440
* srand48: (libc)SVID Random.
1441
* srand48_r: (libc)SVID Random.
1442
* srand: (libc)ISO Random.
1443
* srandom: (libc)BSD Random.
1444
* srandom_r: (libc)BSD Random.
1445
* sscanf: (libc)Formatted Input Functions.
1446
* ssignal: (libc)Basic Signal Handling.
1447
* stat64: (libc)Reading Attributes.
1448
* stat: (libc)Reading Attributes.
1449
* stime: (libc)Simple Calendar Time.
1450
* stpcpy: (libc)Copying and Concatenation.
1451
* stpncpy: (libc)Copying and Concatenation.
1452
* strcasecmp: (libc)String/Array Comparison.
1453
* strcasestr: (libc)Search Functions.
1454
* strcat: (libc)Copying and Concatenation.
1455
* strchr: (libc)Search Functions.
1456
* strchrnul: (libc)Search Functions.
1457
* strcmp: (libc)String/Array Comparison.
1458
* strcoll: (libc)Collation Functions.
1459
* strcpy: (libc)Copying and Concatenation.
1460
* strcspn: (libc)Search Functions.
1461
* strdup: (libc)Copying and Concatenation.
1462
* strdupa: (libc)Copying and Concatenation.
1463
* strerror: (libc)Error Messages.
1464
* strerror_r: (libc)Error Messages.
1465
* strfmon: (libc)Formatting Numbers.
1466
* strfry: (libc)strfry.
1467
* strftime: (libc)Formatting Calendar Time.
1468
* strlen: (libc)String Length.
1469
* strncasecmp: (libc)String/Array Comparison.
1470
* strncat: (libc)Copying and Concatenation.
1471
* strncmp: (libc)String/Array Comparison.
1472
* strncpy: (libc)Copying and Concatenation.
1473
* strndup: (libc)Copying and Concatenation.
1474
* strndupa: (libc)Copying and Concatenation.
1475
* strnlen: (libc)String Length.
1476
* strpbrk: (libc)Search Functions.
1477
* strptime: (libc)Low-Level Time String Parsing.
1478
* strrchr: (libc)Search Functions.
1479
* strsep: (libc)Finding Tokens in a String.
1480
* strsignal: (libc)Signal Messages.
1481
* strspn: (libc)Search Functions.
1482
* strstr: (libc)Search Functions.
1483
* strtod: (libc)Parsing of Floats.
1484
* strtof: (libc)Parsing of Floats.
1485
* strtoimax: (libc)Parsing of Integers.
1486
* strtok: (libc)Finding Tokens in a String.
1487
* strtok_r: (libc)Finding Tokens in a String.
1488
* strtol: (libc)Parsing of Integers.
1489
* strtold: (libc)Parsing of Floats.
1490
* strtoll: (libc)Parsing of Integers.
1491
* strtoq: (libc)Parsing of Integers.
1492
* strtoul: (libc)Parsing of Integers.
1493
* strtoull: (libc)Parsing of Integers.
1494
* strtoumax: (libc)Parsing of Integers.
1495
* strtouq: (libc)Parsing of Integers.
1496
* strverscmp: (libc)String/Array Comparison.
1497
* strxfrm: (libc)Collation Functions.
1498
* stty: (libc)BSD Terminal Modes.
1499
* swapcontext: (libc)System V contexts.
1500
* swprintf: (libc)Formatted Output Functions.
1501
* swscanf: (libc)Formatted Input Functions.
1502
* symlink: (libc)Symbolic Links.
1503
* sync: (libc)Synchronizing I/O.
1504
* syscall: (libc)System Calls.
1505
* sysconf: (libc)Sysconf Definition.
1506
* sysctl: (libc)System Parameters.
1507
* syslog: (libc)syslog; vsyslog.
1508
* system: (libc)Running a Command.
1509
* sysv_signal: (libc)Basic Signal Handling.
1510
* tan: (libc)Trig Functions.
1511
* tanf: (libc)Trig Functions.
1512
* tanh: (libc)Hyperbolic Functions.
1513
* tanhf: (libc)Hyperbolic Functions.
1514
* tanhl: (libc)Hyperbolic Functions.
1515
* tanl: (libc)Trig Functions.
1516
* tcdrain: (libc)Line Control.
1517
* tcflow: (libc)Line Control.
1518
* tcflush: (libc)Line Control.
1519
* tcgetattr: (libc)Mode Functions.
1520
* tcgetpgrp: (libc)Terminal Access Functions.
1521
* tcgetsid: (libc)Terminal Access Functions.
1522
* tcsendbreak: (libc)Line Control.
1523
* tcsetattr: (libc)Mode Functions.
1524
* tcsetpgrp: (libc)Terminal Access Functions.
1525
* tdelete: (libc)Tree Search Function.
1526
* tdestroy: (libc)Tree Search Function.
1527
* tempnam: (libc)Temporary Files.
1528
* textdomain: (libc)Locating gettext catalog.
1529
* tfind: (libc)Tree Search Function.
1530
* tgamma: (libc)Special Functions.
1531
* tgammaf: (libc)Special Functions.
1532
* tgammal: (libc)Special Functions.
1533
* time: (libc)Simple Calendar Time.
1534
* timegm: (libc)Broken-down Time.
1535
* timelocal: (libc)Broken-down Time.
1536
* times: (libc)Processor Time.
1537
* tmpfile64: (libc)Temporary Files.
1538
* tmpfile: (libc)Temporary Files.
1539
* tmpnam: (libc)Temporary Files.
1540
* tmpnam_r: (libc)Temporary Files.
1541
* toascii: (libc)Case Conversion.
1542
* tolower: (libc)Case Conversion.
1543
* toupper: (libc)Case Conversion.
1544
* towctrans: (libc)Wide Character Case Conversion.
1545
* towlower: (libc)Wide Character Case Conversion.
1546
* towupper: (libc)Wide Character Case Conversion.
1547
* trunc: (libc)Rounding Functions.
1548
* truncate64: (libc)File Size.
1549
* truncate: (libc)File Size.
1550
* truncf: (libc)Rounding Functions.
1551
* truncl: (libc)Rounding Functions.
1552
* tsearch: (libc)Tree Search Function.
1553
* ttyname: (libc)Is It a Terminal.
1554
* ttyname_r: (libc)Is It a Terminal.
1555
* twalk: (libc)Tree Search Function.
1556
* tzset: (libc)Time Zone Functions.
1557
* ulimit: (libc)Limits on Resources.
1558
* umask: (libc)Setting Permissions.
1559
* umount2: (libc)Mount-Unmount-Remount.
1560
* umount: (libc)Mount-Unmount-Remount.
1561
* uname: (libc)Platform Type.
1562
* ungetc: (libc)How Unread.
1563
* ungetwc: (libc)How Unread.
1564
* unlink: (libc)Deleting Files.
1565
* unlockpt: (libc)Allocation.
1566
* unsetenv: (libc)Environment Access.
1567
* updwtmp: (libc)Manipulating the Database.
1568
* utime: (libc)File Times.
1569
* utimes: (libc)File Times.
1570
* utmpname: (libc)Manipulating the Database.
1571
* utmpxname: (libc)XPG Functions.
1572
* va_arg: (libc)Argument Macros.
1573
* va_end: (libc)Argument Macros.
1574
* va_start: (libc)Argument Macros.
1575
* va_start: (libc)Old Varargs.
1576
* valloc: (libc)Aligned Memory Blocks.
1577
* vasprintf: (libc)Variable Arguments Output.
1578
* verr: (libc)Error Messages.
1579
* verrx: (libc)Error Messages.
1580
* versionsort64: (libc)Scanning Directory Content.
1581
* versionsort: (libc)Scanning Directory Content.
1582
* vfork: (libc)Creating a Process.
1583
* vfprintf: (libc)Variable Arguments Output.
1584
* vfscanf: (libc)Variable Arguments Input.
1585
* vfwprintf: (libc)Variable Arguments Output.
1586
* vfwscanf: (libc)Variable Arguments Input.
1587
* vlimit: (libc)Limits on Resources.
1588
* vprintf: (libc)Variable Arguments Output.
1589
* vscanf: (libc)Variable Arguments Input.
1590
* vsnprintf: (libc)Variable Arguments Output.
1591
* vsprintf: (libc)Variable Arguments Output.
1592
* vsscanf: (libc)Variable Arguments Input.
1593
* vswprintf: (libc)Variable Arguments Output.
1594
* vswscanf: (libc)Variable Arguments Input.
1595
* vsyslog: (libc)syslog; vsyslog.
1596
* vtimes: (libc)Resource Usage.
1597
* vwarn: (libc)Error Messages.
1598
* vwarnx: (libc)Error Messages.
1599
* vwprintf: (libc)Variable Arguments Output.
1600
* vwscanf: (libc)Variable Arguments Input.
1601
* wait3: (libc)BSD Wait Functions.
1602
* wait4: (libc)Process Completion.
1603
* wait: (libc)Process Completion.
1604
* waitpid: (libc)Process Completion.
1605
* warn: (libc)Error Messages.
1606
* warnx: (libc)Error Messages.
1607
* wcpcpy: (libc)Copying and Concatenation.
1608
* wcpncpy: (libc)Copying and Concatenation.
1609
* wcrtomb: (libc)Converting a Character.
1610
* wcscasecmp: (libc)String/Array Comparison.
1611
* wcscat: (libc)Copying and Concatenation.
1612
* wcschr: (libc)Search Functions.
1613
* wcschrnul: (libc)Search Functions.
1614
* wcscmp: (libc)String/Array Comparison.
1615
* wcscoll: (libc)Collation Functions.
1616
* wcscpy: (libc)Copying and Concatenation.
1617
* wcscspn: (libc)Search Functions.
1618
* wcsdup: (libc)Copying and Concatenation.
1619
* wcsftime: (libc)Formatting Calendar Time.
1620
* wcslen: (libc)String Length.
1621
* wcsncasecmp: (libc)String/Array Comparison.
1622
* wcsncat: (libc)Copying and Concatenation.
1623
* wcsncmp: (libc)String/Array Comparison.
1624
* wcsncpy: (libc)Copying and Concatenation.
1625
* wcsnlen: (libc)String Length.
1626
* wcsnrtombs: (libc)Converting Strings.
1627
* wcspbrk: (libc)Search Functions.
1628
* wcsrchr: (libc)Search Functions.
1629
* wcsrtombs: (libc)Converting Strings.
1630
* wcsspn: (libc)Search Functions.
1631
* wcsstr: (libc)Search Functions.
1632
* wcstod: (libc)Parsing of Floats.
1633
* wcstof: (libc)Parsing of Floats.
1634
* wcstoimax: (libc)Parsing of Integers.
1635
* wcstok: (libc)Finding Tokens in a String.
1636
* wcstol: (libc)Parsing of Integers.
1637
* wcstold: (libc)Parsing of Floats.
1638
* wcstoll: (libc)Parsing of Integers.
1639
* wcstombs: (libc)Non-reentrant String Conversion.
1640
* wcstoq: (libc)Parsing of Integers.
1641
* wcstoul: (libc)Parsing of Integers.
1642
* wcstoull: (libc)Parsing of Integers.
1643
* wcstoumax: (libc)Parsing of Integers.
1644
* wcstouq: (libc)Parsing of Integers.
1645
* wcswcs: (libc)Search Functions.
1646
* wcsxfrm: (libc)Collation Functions.
1647
* wctob: (libc)Converting a Character.
1648
* wctomb: (libc)Non-reentrant Character Conversion.
1649
* wctrans: (libc)Wide Character Case Conversion.
1650
* wctype: (libc)Classification of Wide Characters.
1651
* wmemchr: (libc)Search Functions.
1652
* wmemcmp: (libc)String/Array Comparison.
1653
* wmemcpy: (libc)Copying and Concatenation.
1654
* wmemmove: (libc)Copying and Concatenation.
1655
* wmempcpy: (libc)Copying and Concatenation.
1656
* wmemset: (libc)Copying and Concatenation.
1657
* wordexp: (libc)Calling Wordexp.
1658
* wordfree: (libc)Calling Wordexp.
1659
* wprintf: (libc)Formatted Output Functions.
1660
* write: (libc)I/O Primitives.
1661
* writev: (libc)Scatter-Gather.
1662
* wscanf: (libc)Formatted Input Functions.
1663
* y0: (libc)Special Functions.
1664
* y0f: (libc)Special Functions.
1665
* y0l: (libc)Special Functions.
1666
* y1: (libc)Special Functions.
1667
* y1f: (libc)Special Functions.
1668
* y1l: (libc)Special Functions.
1669
* yn: (libc)Special Functions.
1670
* ynf: (libc)Special Functions.
1671
* ynl: (libc)Special Functions.
1672
END-INFO-DIR-ENTRY
1673
1674
This file documents the GNU C library.
1675
1676
This is Edition 0.12, last updated 2007-10-27, of `The GNU C Library
1677
Reference Manual', for version 2.8 (Ubuntu EGLIBC 2.11.1-0ubuntu6).
1678
1679
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
1680
2003, 2007, 2008 Free Software Foundation, Inc.
1681
1682
Permission is granted to copy, distribute and/or modify this document
1683
under the terms of the GNU Free Documentation License, Version 1.2 or
1684
any later version published by the Free Software Foundation; with the
1685
Invariant Sections being "Free Software Needs Free Documentation" and
1686
"GNU Lesser General Public License", the Front-Cover texts being "A GNU
1687
Manual", and with the Back-Cover Texts as in (a) below. A copy of the
1688
license is included in the section entitled "GNU Free Documentation
1689
License".
1690
1691
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
1692
modify this GNU manual. Buying copies from the FSF supports it in
1693
developing GNU and promoting software freedom."
1694
1695
1696
File: libc.info, Node: GUI program problems, Next: Using gettextized software, Prev: Charset conversion in gettext, Up: Message catalogs with gettext
1697
1698
8.2.1.5 How to use `gettext' in GUI programs
1699
............................................
1700
1701
One place where the `gettext' functions, if used normally, have big
1702
problems is within programs with graphical user interfaces (GUIs). The
1703
problem is that many of the strings which have to be translated are very
1704
short. They have to appear in pull-down menus which restricts the
1705
length. But strings which are not containing entire sentences or at
1706
least large fragments of a sentence may appear in more than one
1707
situation in the program but might have different translations. This is
1708
especially true for the one-word strings which are frequently used in
1709
GUI programs.
1710
1711
As a consequence many people say that the `gettext' approach is
1712
wrong and instead `catgets' should be used which indeed does not have
1713
this problem. But there is a very simple and powerful method to handle
1714
these kind of problems with the `gettext' functions.
1715
1716
As as example consider the following fictional situation. A GUI program
1717
has a menu bar with the following entries:
1718
1719
+------------+------------+--------------------------------------+
1720
| File | Printer | |
1721
+------------+------------+--------------------------------------+
1722
| Open | | Select |
1723
| New | | Open |
1724
+----------+ | Connect |
1725
+----------+
1726
1727
To have the strings `File', `Printer', `Open', `New', `Select', and
1728
`Connect' translated there has to be at some point in the code a call
1729
to a function of the `gettext' family. But in two places the string
1730
passed into the function would be `Open'. The translations might not
1731
be the same and therefore we are in the dilemma described above.
1732
1733
One solution to this problem is to artificially enlengthen the
1734
strings to make them unambiguous. But what would the program do if no
1735
translation is available? The enlengthened string is not what should be
1736
printed. So we should use a little bit modified version of the
1737
functions.
1738
1739
To enlengthen the strings a uniform method should be used. E.g., in
1740
the example above the strings could be chosen as
1741
1742
Menu|File
1743
Menu|Printer
1744
Menu|File|Open
1745
Menu|File|New
1746
Menu|Printer|Select
1747
Menu|Printer|Open
1748
Menu|Printer|Connect
1749
1750
Now all the strings are different and if now instead of `gettext'
1751
the following little wrapper function is used, everything works just
1752
fine:
1753
1754
char *
1755
sgettext (const char *msgid)
1756
{
1757
char *msgval = gettext (msgid);
1758
if (msgval == msgid)
1759
msgval = strrchr (msgid, '|') + 1;
1760
return msgval;
1761
}
1762
1763
What this little function does is to recognize the case when no
1764
translation is available. This can be done very efficiently by a
1765
pointer comparison since the return value is the input value. If there
1766
is no translation we know that the input string is in the format we used
1767
for the Menu entries and therefore contains a `|' character. We simply
1768
search for the last occurrence of this character and return a pointer
1769
to the character following it. That's it!
1770
1771
If one now consistently uses the enlengthened string form and
1772
replaces the `gettext' calls with calls to `sgettext' (this is normally
1773
limited to very few places in the GUI implementation) then it is
1774
possible to produce a program which can be internationalized.
1775
1776
With advanced compilers (such as GNU C) one can write the `sgettext'
1777
functions as an inline function or as a macro like this:
1778
1779
#define sgettext(msgid) \
1780
({ const char *__msgid = (msgid); \
1781
char *__msgstr = gettext (__msgid); \
1782
if (__msgval == __msgid) \
1783
__msgval = strrchr (__msgid, '|') + 1; \
1784
__msgval; })
1785
1786
The other `gettext' functions (`dgettext', `dcgettext' and the
1787
`ngettext' equivalents) can and should have corresponding functions as
1788
well which look almost identical, except for the parameters and the
1789
call to the underlying function.
1790
1791
Now there is of course the question why such functions do not exist
1792
in the GNU C library? There are two parts of the answer to this
1793
question.
1794
1795
* They are easy to write and therefore can be provided by the
1796
project they are used in. This is not an answer by itself and
1797
must be seen together with the second part which is:
1798
1799
* There is no way the C library can contain a version which can work
1800
everywhere. The problem is the selection of the character to
1801
separate the prefix from the actual string in the enlenghtened
1802
string. The examples above used `|' which is a quite good choice
1803
because it resembles a notation frequently used in this context
1804
and it also is a character not often used in message strings.
1805
1806
But what if the character is used in message strings. Or if the
1807
chose character is not available in the character set on the
1808
machine one compiles (e.g., `|' is not required to exist for
1809
ISO C; this is why the `iso646.h' file exists in ISO C programming
1810
environments).
1811
1812
There is only one more comment to make left. The wrapper function
1813
above require that the translations strings are not enlengthened
1814
themselves. This is only logical. There is no need to disambiguate
1815
the strings (since they are never used as keys for a search) and one
1816
also saves quite some memory and disk space by doing this.
1817
1818
1819
File: libc.info, Node: Using gettextized software, Prev: GUI program problems, Up: Message catalogs with gettext
1820
1821
8.2.1.6 User influence on `gettext'
1822
...................................
1823
1824
The last sections described what the programmer can do to
1825
internationalize the messages of the program. But it is finally up to
1826
the user to select the message s/he wants to see. S/He must understand
1827
them.
1828
1829
The POSIX locale model uses the environment variables `LC_COLLATE',
1830
`LC_CTYPE', `LC_MESSAGES', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME'
1831
to select the locale which is to be used. This way the user can
1832
influence lots of functions. As we mentioned above the `gettext'
1833
functions also take advantage of this.
1834
1835
To understand how this happens it is necessary to take a look at the
1836
various components of the filename which gets computed to locate a
1837
message catalog. It is composed as follows:
1838
1839
DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
1840
1841
The default value for DIR_NAME is system specific. It is computed
1842
from the value given as the prefix while configuring the C library.
1843
This value normally is `/usr' or `/'. For the former the complete
1844
DIR_NAME is:
1845
1846
/usr/share/locale
1847
1848
We can use `/usr/share' since the `.mo' files containing the message
1849
catalogs are system independent, so all systems can use the same files.
1850
If the program executed the `bindtextdomain' function for the message
1851
domain that is currently handled, the `dir_name' component is exactly
1852
the value which was given to the function as the second parameter.
1853
I.e., `bindtextdomain' allows overwriting the only system dependent and
1854
fixed value to make it possible to address files anywhere in the
1855
filesystem.
1856
1857
The CATEGORY is the name of the locale category which was selected
1858
in the program code. For `gettext' and `dgettext' this is always
1859
`LC_MESSAGES', for `dcgettext' this is selected by the value of the
1860
third parameter. As said above it should be avoided to ever use a
1861
category other than `LC_MESSAGES'.
1862
1863
The LOCALE component is computed based on the category used. Just
1864
like for the `setlocale' function here comes the user selection into
1865
the play. Some environment variables are examined in a fixed order and
1866
the first environment variable set determines the return value of the
1867
lookup process. In detail, for the category `LC_xxx' the following
1868
variables in this order are examined:
1869
1870
`LANGUAGE'
1871
1872
`LC_ALL'
1873
1874
`LC_xxx'
1875
1876
`LANG'
1877
1878
This looks very familiar. With the exception of the `LANGUAGE'
1879
environment variable this is exactly the lookup order the `setlocale'
1880
function uses. But why introducing the `LANGUAGE' variable?
1881
1882
The reason is that the syntax of the values these variables can have
1883
is different to what is expected by the `setlocale' function. If we
1884
would set `LC_ALL' to a value following the extended syntax that would
1885
mean the `setlocale' function will never be able to use the value of
1886
this variable as well. An additional variable removes this problem
1887
plus we can select the language independently of the locale setting
1888
which sometimes is useful.
1889
1890
While for the `LC_xxx' variables the value should consist of exactly
1891
one specification of a locale the `LANGUAGE' variable's value can
1892
consist of a colon separated list of locale names. The attentive
1893
reader will realize that this is the way we manage to implement one of
1894
our additional demands above: we want to be able to specify an ordered
1895
list of language.
1896
1897
Back to the constructed filename we have only one component missing.
1898
The DOMAIN_NAME part is the name which was either registered using the
1899
`textdomain' function or which was given to `dgettext' or `dcgettext'
1900
as the first parameter. Now it becomes obvious that a good choice for
1901
the domain name in the program code is a string which is closely
1902
related to the program/package name. E.g., for the GNU C Library the
1903
domain name is `libc'.
1904
1905
A limit piece of example code should show how the programmer is supposed
1906
to work:
1907
1908
{
1909
setlocale (LC_ALL, "");
1910
textdomain ("test-package");
1911
bindtextdomain ("test-package", "/usr/local/share/locale");
1912
puts (gettext ("Hello, world!"));
1913
}
1914
1915
At the program start the default domain is `messages', and the
1916
default locale is "C". The `setlocale' call sets the locale according
1917
to the user's environment variables; remember that correct functioning
1918
of `gettext' relies on the correct setting of the `LC_MESSAGES' locale
1919
(for looking up the message catalog) and of the `LC_CTYPE' locale (for
1920
the character set conversion). The `textdomain' call changes the
1921
default domain to `test-package'. The `bindtextdomain' call specifies
1922
that the message catalogs for the domain `test-package' can be found
1923
below the directory `/usr/local/share/locale'.
1924
1925
If now the user set in her/his environment the variable `LANGUAGE'
1926
to `de' the `gettext' function will try to use the translations from
1927
the file
1928
1929
/usr/local/share/locale/de/LC_MESSAGES/test-package.mo
1930
1931
From the above descriptions it should be clear which component of
1932
this filename is determined by which source.
1933
1934
In the above example we assumed that the `LANGUAGE' environment
1935
variable to `de'. This might be an appropriate selection but what
1936
happens if the user wants to use `LC_ALL' because of the wider
1937
usability and here the required value is `de_DE.ISO-8859-1'? We
1938
already mentioned above that a situation like this is not infrequent.
1939
E.g., a person might prefer reading a dialect and if this is not
1940
available fall back on the standard language.
1941
1942
The `gettext' functions know about situations like this and can
1943
handle them gracefully. The functions recognize the format of the value
1944
of the environment variable. It can split the value is different pieces
1945
and by leaving out the only or the other part it can construct new
1946
values. This happens of course in a predictable way. To understand
1947
this one must know the format of the environment variable value. There
1948
is one more or less standardized form, originally from the X/Open
1949
specification:
1950
1951
`language[_territory[.codeset]][@modifier]'
1952
1953
Less specific locale names will be stripped of in the order of the
1954
following list:
1955
1956
1. `codeset'
1957
1958
2. `normalized codeset'
1959
1960
3. `territory'
1961
1962
4. `modifier'
1963
1964
The `language' field will never be dropped for obvious reasons.
1965
1966
The only new thing is the `normalized codeset' entry. This is
1967
another goodie which is introduced to help reducing the chaos which
1968
derives from the inability of the people to standardize the names of
1969
character sets. Instead of ISO-8859-1 one can often see 8859-1, 88591,
1970
iso8859-1, or iso_8859-1. The `normalized codeset' value is generated
1971
from the user-provided character set name by applying the following
1972
rules:
1973
1974
1. Remove all characters beside numbers and letters.
1975
1976
2. Fold letters to lowercase.
1977
1978
3. If the same only contains digits prepend the string `"iso"'.
1979
1980
So all of the above name will be normalized to `iso88591'. This allows
1981
the program user much more freely choosing the locale name.
1982
1983
Even this extended functionality still does not help to solve the
1984
problem that completely different names can be used to denote the same
1985
locale (e.g., `de' and `german'). To be of help in this situation the
1986
locale implementation and also the `gettext' functions know about
1987
aliases.
1988
1989
The file `/usr/share/locale/locale.alias' (replace `/usr' with
1990
whatever prefix you used for configuring the C library) contains a
1991
mapping of alternative names to more regular names. The system manager
1992
is free to add new entries to fill her/his own needs. The selected
1993
locale from the environment is compared with the entries in the first
1994
column of this file ignoring the case. If they match the value of the
1995
second column is used instead for the further handling.
1996
1997
In the description of the format of the environment variables we
1998
already mentioned the character set as a factor in the selection of the
1999
message catalog. In fact, only catalogs which contain text written
2000
using the character set of the system/program can be used (directly;
2001
there will come a solution for this some day). This means for the user
2002
that s/he will always have to take care for this. If in the collection
2003
of the message catalogs there are files for the same language but coded
2004
using different character sets the user has to be careful.
2005
2006
2007
File: libc.info, Node: Helper programs for gettext, Prev: Message catalogs with gettext, Up: The Uniforum approach
2008
2009
8.2.2 Programs to handle message catalogs for `gettext'
2010
-------------------------------------------------------
2011
2012
The GNU C Library does not contain the source code for the programs to
2013
handle message catalogs for the `gettext' functions. As part of the
2014
GNU project the GNU gettext package contains everything the developer
2015
needs. The functionality provided by the tools in this package by far
2016
exceeds the abilities of the `gencat' program described above for the
2017
`catgets' functions.
2018
2019
There is a program `msgfmt' which is the equivalent program to the
2020
`gencat' program. It generates from the human-readable and -editable
2021
form of the message catalog a binary file which can be used by the
2022
`gettext' functions. But there are several more programs available.
2023
2024
The `xgettext' program can be used to automatically extract the
2025
translatable messages from a source file. I.e., the programmer need not
2026
take care for the translations and the list of messages which have to be
2027
translated. S/He will simply wrap the translatable string in calls to
2028
`gettext' et.al and the rest will be done by `xgettext'. This program
2029
has a lot of option which help to customize the output or do help to
2030
understand the input better.
2031
2032
Other programs help to manage development cycle when new messages
2033
appear in the source files or when a new translation of the messages
2034
appear. Here it should only be noted that using all the tools in GNU
2035
gettext it is possible to _completely_ automate the handling of message
2036
catalog. Beside marking the translatable string in the source code and
2037
generating the translations the developers do not have anything to do
2038
themselves.
2039
2040
2041
File: libc.info, Node: Searching and Sorting, Next: Pattern Matching, Prev: Message Translation, Up: Top
2042
2043
9 Searching and Sorting
2044
***********************
2045
2046
This chapter describes functions for searching and sorting arrays of
2047
arbitrary objects. You pass the appropriate comparison function to be
2048
applied as an argument, along with the size of the objects in the array
2049
and the total number of elements.
2050
2051
* Menu:
2052
2053
* Comparison Functions:: Defining how to compare two objects.
2054
Since the sort and search facilities
2055
are general, you have to specify the
2056
ordering.
2057
* Array Search Function:: The `bsearch' function.
2058
* Array Sort Function:: The `qsort' function.
2059
* Search/Sort Example:: An example program.
2060
* Hash Search Function:: The `hsearch' function.
2061
* Tree Search Function:: The `tsearch' function.
2062
2063
2064
File: libc.info, Node: Comparison Functions, Next: Array Search Function, Up: Searching and Sorting
2065
2066
9.1 Defining the Comparison Function
2067
====================================
2068
2069
In order to use the sorted array library functions, you have to describe
2070
how to compare the elements of the array.
2071
2072
To do this, you supply a comparison function to compare two elements
2073
of the array. The library will call this function, passing as arguments
2074
pointers to two array elements to be compared. Your comparison function
2075
should return a value the way `strcmp' (*note String/Array
2076
Comparison::) does: negative if the first argument is "less" than the
2077
second, zero if they are "equal", and positive if the first argument is
2078
"greater".
2079
2080
Here is an example of a comparison function which works with an
2081
array of numbers of type `double':
2082
2083
int
2084
compare_doubles (const void *a, const void *b)
2085
{
2086
const double *da = (const double *) a;
2087
const double *db = (const double *) b;
2088
2089
return (*da > *db) - (*da < *db);
2090
}
2091
2092
The header file `stdlib.h' defines a name for the data type of
2093
comparison functions. This type is a GNU extension.
2094
2095
int comparison_fn_t (const void *, const void *);
2096
2097
2098
File: libc.info, Node: Array Search Function, Next: Array Sort Function, Prev: Comparison Functions, Up: Searching and Sorting
2099
2100
9.2 Array Search Function
2101
=========================
2102
2103
Generally searching for a specific element in an array means that
2104
potentially all elements must be checked. The GNU C library contains
2105
functions to perform linear search. The prototypes for the following
2106
two functions can be found in `search.h'.
2107
2108
-- Function: void * lfind (const void *KEY, void *BASE, size_t *NMEMB,
2109
size_t SIZE, comparison_fn_t COMPAR)
2110
The `lfind' function searches in the array with `*NMEMB' elements
2111
of SIZE bytes pointed to by BASE for an element which matches the
2112
one pointed to by KEY. The function pointed to by COMPAR is used
2113
decide whether two elements match.
2114
2115
The return value is a pointer to the matching element in the array
2116
starting at BASE if it is found. If no matching element is
2117
available `NULL' is returned.
2118
2119
The mean runtime of this function is `*NMEMB'/2. This function
2120
should only be used if elements often get added to or deleted from
2121
the array in which case it might not be useful to sort the array
2122
before searching.
2123
2124
-- Function: void * lsearch (const void *KEY, void *BASE, size_t
2125
*NMEMB, size_t SIZE, comparison_fn_t COMPAR)
2126
The `lsearch' function is similar to the `lfind' function. It
2127
searches the given array for an element and returns it if found.
2128
The difference is that if no matching element is found the
2129
`lsearch' function adds the object pointed to by KEY (with a size
2130
of SIZE bytes) at the end of the array and it increments the value
2131
of `*NMEMB' to reflect this addition.
2132
2133
This means for the caller that if it is not sure that the array
2134
contains the element one is searching for the memory allocated for
2135
the array starting at BASE must have room for at least SIZE more
2136
bytes. If one is sure the element is in the array it is better to
2137
use `lfind' so having more room in the array is always necessary
2138
when calling `lsearch'.
2139
2140
To search a sorted array for an element matching the key, use the
2141
`bsearch' function. The prototype for this function is in the header
2142
file `stdlib.h'.
2143
2144
-- Function: void * bsearch (const void *KEY, const void *ARRAY,
2145
size_t COUNT, size_t SIZE, comparison_fn_t COMPARE)
2146
The `bsearch' function searches the sorted array ARRAY for an
2147
object that is equivalent to KEY. The array contains COUNT
2148
elements, each of which is of size SIZE bytes.
2149
2150
The COMPARE function is used to perform the comparison. This
2151
function is called with two pointer arguments and should return an
2152
integer less than, equal to, or greater than zero corresponding to
2153
whether its first argument is considered less than, equal to, or
2154
greater than its second argument. The elements of the ARRAY must
2155
already be sorted in ascending order according to this comparison
2156
function.
2157
2158
The return value is a pointer to the matching array element, or a
2159
null pointer if no match is found. If the array contains more
2160
than one element that matches, the one that is returned is
2161
unspecified.
2162
2163
This function derives its name from the fact that it is implemented
2164
using the binary search algorithm.
2165
2166
2167
File: libc.info, Node: Array Sort Function, Next: Search/Sort Example, Prev: Array Search Function, Up: Searching and Sorting
2168
2169
9.3 Array Sort Function
2170
=======================
2171
2172
To sort an array using an arbitrary comparison function, use the
2173
`qsort' function. The prototype for this function is in `stdlib.h'.
2174
2175
-- Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
2176
comparison_fn_t COMPARE)
2177
The QSORT function sorts the array ARRAY. The array contains
2178
COUNT elements, each of which is of size SIZE.
2179
2180
The COMPARE function is used to perform the comparison on the
2181
array elements. This function is called with two pointer
2182
arguments and should return an integer less than, equal to, or
2183
greater than zero corresponding to whether its first argument is
2184
considered less than, equal to, or greater than its second
2185
argument.
2186
2187
*Warning:* If two objects compare as equal, their order after
2188
sorting is unpredictable. That is to say, the sorting is not
2189
stable. This can make a difference when the comparison considers
2190
only part of the elements. Two elements with the same sort key
2191
may differ in other respects.
2192
2193
If you want the effect of a stable sort, you can get this result by
2194
writing the comparison function so that, lacking other reason
2195
distinguish between two elements, it compares them by their
2196
addresses. Note that doing this may make the sorting algorithm
2197
less efficient, so do it only if necessary.
2198
2199
Here is a simple example of sorting an array of doubles in
2200
numerical order, using the comparison function defined above
2201
(*note Comparison Functions::):
2202
2203
{
2204
double *array;
2205
int size;
2206
...
2207
qsort (array, size, sizeof (double), compare_doubles);
2208
}
2209
2210
The `qsort' function derives its name from the fact that it was
2211
originally implemented using the "quick sort" algorithm.
2212
2213
The implementation of `qsort' in this library might not be an
2214
in-place sort and might thereby use an extra amount of memory to
2215
store the array.
2216
2217
2218
File: libc.info, Node: Search/Sort Example, Next: Hash Search Function, Prev: Array Sort Function, Up: Searching and Sorting
2219
2220
9.4 Searching and Sorting Example
2221
=================================
2222
2223
Here is an example showing the use of `qsort' and `bsearch' with an
2224
array of structures. The objects in the array are sorted by comparing
2225
their `name' fields with the `strcmp' function. Then, we can look up
2226
individual objects based on their names.
2227
2228
#include <stdlib.h>
2229
#include <stdio.h>
2230
#include <string.h>
2231
2232
/* Define an array of critters to sort. */
2233
2234
struct critter
2235
{
2236
const char *name;
2237
const char *species;
2238
};
2239
2240
struct critter muppets[] =
2241
{
2242
{"Kermit", "frog"},
2243
{"Piggy", "pig"},
2244
{"Gonzo", "whatever"},
2245
{"Fozzie", "bear"},
2246
{"Sam", "eagle"},
2247
{"Robin", "frog"},
2248
{"Animal", "animal"},
2249
{"Camilla", "chicken"},
2250
{"Sweetums", "monster"},
2251
{"Dr. Strangepork", "pig"},
2252
{"Link Hogthrob", "pig"},
2253
{"Zoot", "human"},
2254
{"Dr. Bunsen Honeydew", "human"},
2255
{"Beaker", "human"},
2256
{"Swedish Chef", "human"}
2257
};
2258
2259
int count = sizeof (muppets) / sizeof (struct critter);
2260
2261
2262
2263
/* This is the comparison function used for sorting and searching. */
2264
2265
int
2266
critter_cmp (const struct critter *c1, const struct critter *c2)
2267
{
2268
return strcmp (c1->name, c2->name);
2269
}
2270
2271
2272
/* Print information about a critter. */
2273
2274
void
2275
print_critter (const struct critter *c)
2276
{
2277
printf ("%s, the %s\n", c->name, c->species);
2278
}
2279
2280
2281
/* Do the lookup into the sorted array. */
2282
2283
void
2284
find_critter (const char *name)
2285
{
2286
struct critter target, *result;
2287
target.name = name;
2288
result = bsearch (&target, muppets, count, sizeof (struct critter),
2289
critter_cmp);
2290
if (result)
2291
print_critter (result);
2292
else
2293
printf ("Couldn't find %s.\n", name);
2294
}
2295
2296
/* Main program. */
2297
2298
int
2299
main (void)
2300
{
2301
int i;
2302
2303
for (i = 0; i < count; i++)
2304
print_critter (&muppets[i]);
2305
printf ("\n");
2306
2307
qsort (muppets, count, sizeof (struct critter), critter_cmp);
2308
2309
for (i = 0; i < count; i++)
2310
print_critter (&muppets[i]);
2311
printf ("\n");
2312
2313
find_critter ("Kermit");
2314
find_critter ("Gonzo");
2315
find_critter ("Janice");
2316
2317
return 0;
2318
}
2319
2320
The output from this program looks like:
2321
2322
Kermit, the frog
2323
Piggy, the pig
2324
Gonzo, the whatever
2325
Fozzie, the bear
2326
Sam, the eagle
2327
Robin, the frog
2328
Animal, the animal
2329
Camilla, the chicken
2330
Sweetums, the monster
2331
Dr. Strangepork, the pig
2332
Link Hogthrob, the pig
2333
Zoot, the human
2334
Dr. Bunsen Honeydew, the human
2335
Beaker, the human
2336
Swedish Chef, the human
2337
2338
Animal, the animal
2339
Beaker, the human
2340
Camilla, the chicken
2341
Dr. Bunsen Honeydew, the human
2342
Dr. Strangepork, the pig
2343
Fozzie, the bear
2344
Gonzo, the whatever
2345
Kermit, the frog
2346
Link Hogthrob, the pig
2347
Piggy, the pig
2348
Robin, the frog
2349
Sam, the eagle
2350
Swedish Chef, the human
2351
Sweetums, the monster
2352
Zoot, the human
2353
2354
Kermit, the frog
2355
Gonzo, the whatever
2356
Couldn't find Janice.
2357
2358
2359
File: libc.info, Node: Hash Search Function, Next: Tree Search Function, Prev: Search/Sort Example, Up: Searching and Sorting
2360
2361
9.5 The `hsearch' function.
2362
===========================
2363
2364
The functions mentioned so far in this chapter are for searching in a
2365
sorted or unsorted array. There are other methods to organize
2366
information which later should be searched. The costs of insert,
2367
delete and search differ. One possible implementation is using hashing
2368
tables. The following functions are declared in the header file
2369
`search.h'.
2370
2371
-- Function: int hcreate (size_t NEL)
2372
The `hcreate' function creates a hashing table which can contain at
2373
least NEL elements. There is no possibility to grow this table so
2374
it is necessary to choose the value for NEL wisely. The method
2375
used to implement this function might make it necessary to make the
2376
number of elements in the hashing table larger than the expected
2377
maximal number of elements. Hashing tables usually work
2378
inefficiently if they are filled 80% or more. The constant access
2379
time guaranteed by hashing can only be achieved if few collisions
2380
exist. See Knuth's "The Art of Computer Programming, Part 3:
2381
Searching and Sorting" for more information.
2382
2383
The weakest aspect of this function is that there can be at most
2384
one hashing table used through the whole program. The table is
2385
allocated in local memory out of control of the programmer. As an
2386
extension the GNU C library provides an additional set of
2387
functions with an reentrant interface which provide a similar
2388
interface but which allow to keep arbitrarily many hashing tables.
2389
2390
It is possible to use more than one hashing table in the program
2391
run if the former table is first destroyed by a call to `hdestroy'.
2392
2393
The function returns a non-zero value if successful. If it return
2394
zero something went wrong. This could either mean there is
2395
already a hashing table in use or the program runs out of memory.
2396
2397
-- Function: void hdestroy (void)
2398
The `hdestroy' function can be used to free all the resources
2399
allocated in a previous call of `hcreate'. After a call to this
2400
function it is again possible to call `hcreate' and allocate a new
2401
table with possibly different size.
2402
2403
It is important to remember that the elements contained in the
2404
hashing table at the time `hdestroy' is called are _not_ freed by
2405
this function. It is the responsibility of the program code to
2406
free those strings (if necessary at all). Freeing all the element
2407
memory is not possible without extra, separately kept information
2408
since there is no function to iterate through all available
2409
elements in the hashing table. If it is really necessary to free
2410
a table and all elements the programmer has to keep a list of all
2411
table elements and before calling `hdestroy' s/he has to free all
2412
element's data using this list. This is a very unpleasant
2413
mechanism and it also shows that this kind of hashing tables is
2414
mainly meant for tables which are created once and used until the
2415
end of the program run.
2416
2417
Entries of the hashing table and keys for the search are defined
2418
using this type:
2419
2420
-- Data type: struct ENTRY
2421
Both elements of this structure are pointers to zero-terminated
2422
strings. This is a limiting restriction of the functionality of
2423
the `hsearch' functions. They can only be used for data sets
2424
which use the NUL character always and solely to terminate the
2425
records. It is not possible to handle general binary data.
2426
2427
`char *key'
2428
Pointer to a zero-terminated string of characters describing
2429
the key for the search or the element in the hashing table.
2430
2431
`char *data'
2432
Pointer to a zero-terminated string of characters describing
2433
the data. If the functions will be called only for searching
2434
an existing entry this element might stay undefined since it
2435
is not used.
2436
2437
-- Function: ENTRY * hsearch (ENTRY ITEM, ACTION ACTION)
2438
To search in a hashing table created using `hcreate' the `hsearch'
2439
function must be used. This function can perform simple search
2440
for an element (if ACTION has the `FIND') or it can alternatively
2441
insert the key element into the hashing table. Entries are never
2442
replaced.
2443
2444
The key is denoted by a pointer to an object of type `ENTRY'. For
2445
locating the corresponding position in the hashing table only the
2446
`key' element of the structure is used.
2447
2448
If an entry with matching key is found the ACTION parameter is
2449
irrelevant. The found entry is returned. If no matching entry is
2450
found and the ACTION parameter has the value `FIND' the function
2451
returns a `NULL' pointer. If no entry is found and the ACTION
2452
parameter has the value `ENTER' a new entry is added to the
2453
hashing table which is initialized with the parameter ITEM. A
2454
pointer to the newly added entry is returned.
2455
2456
As mentioned before the hashing table used by the functions
2457
described so far is global and there can be at any time at most one
2458
hashing table in the program. A solution is to use the following
2459
functions which are a GNU extension. All have in common that they
2460
operate on a hashing table which is described by the content of an
2461
object of the type `struct hsearch_data'. This type should be treated
2462
as opaque, none of its members should be changed directly.
2463
2464
-- Function: int hcreate_r (size_t NEL, struct hsearch_data *HTAB)
2465
The `hcreate_r' function initializes the object pointed to by HTAB
2466
to contain a hashing table with at least NEL elements. So this
2467
function is equivalent to the `hcreate' function except that the
2468
initialized data structure is controlled by the user.
2469
2470
This allows having more than one hashing table at one time. The
2471
memory necessary for the `struct hsearch_data' object can be
2472
allocated dynamically. It must be initialized with zero before
2473
calling this function.
2474
2475
The return value is non-zero if the operation was successful. If
2476
the return value is zero, something went wrong, which probably
2477
means the programs ran out of memory.
2478
2479
-- Function: void hdestroy_r (struct hsearch_data *HTAB)
2480
The `hdestroy_r' function frees all resources allocated by the
2481
`hcreate_r' function for this very same object HTAB. As for
2482
`hdestroy' it is the programs responsibility to free the strings
2483
for the elements of the table.
2484
2485
-- Function: int hsearch_r (ENTRY ITEM, ACTION ACTION, ENTRY **RETVAL,
2486
struct hsearch_data *HTAB)
2487
The `hsearch_r' function is equivalent to `hsearch'. The meaning
2488
of the first two arguments is identical. But instead of operating
2489
on a single global hashing table the function works on the table
2490
described by the object pointed to by HTAB (which is initialized
2491
by a call to `hcreate_r').
2492
2493
Another difference to `hcreate' is that the pointer to the found
2494
entry in the table is not the return value of the functions. It is
2495
returned by storing it in a pointer variables pointed to by the
2496
RETVAL parameter. The return value of the function is an integer
2497
value indicating success if it is non-zero and failure if it is
2498
zero. In the latter case the global variable ERRNO signals the
2499
reason for the failure.
2500
2501
`ENOMEM'
2502
The table is filled and `hsearch_r' was called with an so far
2503
unknown key and ACTION set to `ENTER'.
2504
2505
`ESRCH'
2506
The ACTION parameter is `FIND' and no corresponding element
2507
is found in the table.
2508
2509
2510
File: libc.info, Node: Tree Search Function, Prev: Hash Search Function, Up: Searching and Sorting
2511
2512
9.6 The `tsearch' function.
2513
===========================
2514
2515
Another common form to organize data for efficient search is to use
2516
trees. The `tsearch' function family provides a nice interface to
2517
functions to organize possibly large amounts of data by providing a mean
2518
access time proportional to the logarithm of the number of elements.
2519
The GNU C library implementation even guarantees that this bound is
2520
never exceeded even for input data which cause problems for simple
2521
binary tree implementations.
2522
2523
The functions described in the chapter are all described in the
2524
System V and X/Open specifications and are therefore quite portable.
2525
2526
In contrast to the `hsearch' functions the `tsearch' functions can
2527
be used with arbitrary data and not only zero-terminated strings.
2528
2529
The `tsearch' functions have the advantage that no function to
2530
initialize data structures is necessary. A simple pointer of type
2531
`void *' initialized to `NULL' is a valid tree and can be extended or
2532
searched. The prototypes for these functions can be found in the
2533
header file `search.h'.
2534
2535
-- Function: void * tsearch (const void *KEY, void **ROOTP,
2536
comparison_fn_t COMPAR)
2537
The `tsearch' function searches in the tree pointed to by `*ROOTP'
2538
for an element matching KEY. The function pointed to by COMPAR is
2539
used to determine whether two elements match. *Note Comparison
2540
Functions::, for a specification of the functions which can be
2541
used for the COMPAR parameter.
2542
2543
If the tree does not contain a matching entry the KEY value will
2544
be added to the tree. `tsearch' does not make a copy of the object
2545
pointed to by KEY (how could it since the size is unknown).
2546
Instead it adds a reference to this object which means the object
2547
must be available as long as the tree data structure is used.
2548
2549
The tree is represented by a pointer to a pointer since it is
2550
sometimes necessary to change the root node of the tree. So it
2551
must not be assumed that the variable pointed to by ROOTP has the
2552
same value after the call. This also shows that it is not safe to
2553
call the `tsearch' function more than once at the same time using
2554
the same tree. It is no problem to run it more than once at a
2555
time on different trees.
2556
2557
The return value is a pointer to the matching element in the tree.
2558
If a new element was created the pointer points to the new data
2559
(which is in fact KEY). If an entry had to be created and the
2560
program ran out of space `NULL' is returned.
2561
2562
-- Function: void * tfind (const void *KEY, void *const *ROOTP,
2563
comparison_fn_t COMPAR)
2564
The `tfind' function is similar to the `tsearch' function. It
2565
locates an element matching the one pointed to by KEY and returns
2566
a pointer to this element. But if no matching element is
2567
available no new element is entered (note that the ROOTP parameter
2568
points to a constant pointer). Instead the function returns
2569
`NULL'.
2570
2571
Another advantage of the `tsearch' function in contrast to the
2572
`hsearch' functions is that there is an easy way to remove elements.
2573
2574
-- Function: void * tdelete (const void *KEY, void **ROOTP,
2575
comparison_fn_t COMPAR)
2576
To remove a specific element matching KEY from the tree `tdelete'
2577
can be used. It locates the matching element using the same
2578
method as `tfind'. The corresponding element is then removed and
2579
a pointer to the parent of the deleted node is returned by the
2580
function. If there is no matching entry in the tree nothing can be
2581
deleted and the function returns `NULL'. If the root of the tree
2582
is deleted `tdelete' returns some unspecified value not equal to
2583
`NULL'.
2584
2585
-- Function: void tdestroy (void *VROOT, __free_fn_t FREEFCT)
2586
If the complete search tree has to be removed one can use
2587
`tdestroy'. It frees all resources allocated by the `tsearch'
2588
function to generate the tree pointed to by VROOT.
2589
2590
For the data in each tree node the function FREEFCT is called.
2591
The pointer to the data is passed as the argument to the function.
2592
If no such work is necessary FREEFCT must point to a function doing
2593
nothing. It is called in any case.
2594
2595
This function is a GNU extension and not covered by the System V or
2596
X/Open specifications.
2597
2598
In addition to the function to create and destroy the tree data
2599
structure, there is another function which allows you to apply a
2600
function to all elements of the tree. The function must have this type:
2601
2602
void __action_fn_t (const void *nodep, VISIT value, int level);
2603
2604
The NODEP is the data value of the current node (once given as the
2605
KEY argument to `tsearch'). LEVEL is a numeric value which corresponds
2606
to the depth of the current node in the tree. The root node has the
2607
depth 0 and its children have a depth of 1 and so on. The `VISIT' type
2608
is an enumeration type.
2609
2610
-- Data Type: VISIT
2611
The `VISIT' value indicates the status of the current node in the
2612
tree and how the function is called. The status of a node is
2613
either `leaf' or `internal node'. For each leaf node the function
2614
is called exactly once, for each internal node it is called three
2615
times: before the first child is processed, after the first child
2616
is processed and after both children are processed. This makes it
2617
possible to handle all three methods of tree traversal (or even a
2618
combination of them).
2619
2620
`preorder'
2621
The current node is an internal node and the function is
2622
called before the first child was processed.
2623
2624
`postorder'
2625
The current node is an internal node and the function is
2626
called after the first child was processed.
2627
2628
`endorder'
2629
The current node is an internal node and the function is
2630
called after the second child was processed.
2631
2632
`leaf'
2633
The current node is a leaf.
2634
2635
-- Function: void twalk (const void *ROOT, __action_fn_t ACTION)
2636
For each node in the tree with a node pointed to by ROOT, the
2637
`twalk' function calls the function provided by the parameter
2638
ACTION. For leaf nodes the function is called exactly once with
2639
VALUE set to `leaf'. For internal nodes the function is called
2640
three times, setting the VALUE parameter or ACTION to the
2641
appropriate value. The LEVEL argument for the ACTION function is
2642
computed while descending the tree with increasing the value by
2643
one for the descend to a child, starting with the value 0 for the
2644
root node.
2645
2646
Since the functions used for the ACTION parameter to `twalk' must
2647
not modify the tree data, it is safe to run `twalk' in more than
2648
one thread at the same time, working on the same tree. It is also
2649
safe to call `tfind' in parallel. Functions which modify the tree
2650
must not be used, otherwise the behavior is undefined.
2651
2652
2653
File: libc.info, Node: Pattern Matching, Next: I/O Overview, Prev: Searching and Sorting, Up: Top
2654
2655
10 Pattern Matching
2656
*******************
2657
2658
The GNU C Library provides pattern matching facilities for two kinds of
2659
patterns: regular expressions and file-name wildcards. The library also
2660
provides a facility for expanding variable and command references and
2661
parsing text into words in the way the shell does.
2662
2663
* Menu:
2664
2665
* Wildcard Matching:: Matching a wildcard pattern against a single string.
2666
* Globbing:: Finding the files that match a wildcard pattern.
2667
* Regular Expressions:: Matching regular expressions against strings.
2668
* Word Expansion:: Expanding shell variables, nested commands,
2669
arithmetic, and wildcards.
2670
This is what the shell does with shell commands.
2671
2672
2673
File: libc.info, Node: Wildcard Matching, Next: Globbing, Up: Pattern Matching
2674
2675
10.1 Wildcard Matching
2676
======================
2677
2678
This section describes how to match a wildcard pattern against a
2679
particular string. The result is a yes or no answer: does the string
2680
fit the pattern or not. The symbols described here are all declared in
2681
`fnmatch.h'.
2682
2683
-- Function: int fnmatch (const char *PATTERN, const char *STRING, int
2684
FLAGS)
2685
This function tests whether the string STRING matches the pattern
2686
PATTERN. It returns `0' if they do match; otherwise, it returns
2687
the nonzero value `FNM_NOMATCH'. The arguments PATTERN and STRING
2688
are both strings.
2689
2690
The argument FLAGS is a combination of flag bits that alter the
2691
details of matching. See below for a list of the defined flags.
2692
2693
In the GNU C Library, `fnmatch' cannot experience an "error"--it
2694
always returns an answer for whether the match succeeds. However,
2695
other implementations of `fnmatch' might sometimes report "errors".
2696
They would do so by returning nonzero values that are not equal to
2697
`FNM_NOMATCH'.
2698
2699
These are the available flags for the FLAGS argument:
2700
2701
`FNM_FILE_NAME'
2702
Treat the `/' character specially, for matching file names. If
2703
this flag is set, wildcard constructs in PATTERN cannot match `/'
2704
in STRING. Thus, the only way to match `/' is with an explicit
2705
`/' in PATTERN.
2706
2707
`FNM_PATHNAME'
2708
This is an alias for `FNM_FILE_NAME'; it comes from POSIX.2. We
2709
don't recommend this name because we don't use the term "pathname"
2710
for file names.
2711
2712
`FNM_PERIOD'
2713
Treat the `.' character specially if it appears at the beginning of
2714
STRING. If this flag is set, wildcard constructs in PATTERN
2715
cannot match `.' as the first character of STRING.
2716
2717
If you set both `FNM_PERIOD' and `FNM_FILE_NAME', then the special
2718
treatment applies to `.' following `/' as well as to `.' at the
2719
beginning of STRING. (The shell uses the `FNM_PERIOD' and
2720
`FNM_FILE_NAME' flags together for matching file names.)
2721
2722
`FNM_NOESCAPE'
2723
Don't treat the `\' character specially in patterns. Normally,
2724
`\' quotes the following character, turning off its special meaning
2725
(if any) so that it matches only itself. When quoting is enabled,
2726
the pattern `\?' matches only the string `?', because the question
2727
mark in the pattern acts like an ordinary character.
2728
2729
If you use `FNM_NOESCAPE', then `\' is an ordinary character.
2730
2731
`FNM_LEADING_DIR'
2732
Ignore a trailing sequence of characters starting with a `/' in
2733
STRING; that is to say, test whether STRING starts with a
2734
directory name that PATTERN matches.
2735
2736
If this flag is set, either `foo*' or `foobar' as a pattern would
2737
match the string `foobar/frobozz'.
2738
2739
`FNM_CASEFOLD'
2740
Ignore case in comparing STRING to PATTERN.
2741
2742
`FNM_EXTMATCH'
2743
Recognize beside the normal patterns also the extended patterns
2744
introduced in `ksh'. The patterns are written in the form
2745
explained in the following table where PATTERN-LIST is a `|'
2746
separated list of patterns.
2747
2748
`?(PATTERN-LIST)'
2749
The pattern matches if zero or one occurrences of any of the
2750
patterns in the PATTERN-LIST allow matching the input string.
2751
2752
`*(PATTERN-LIST)'
2753
The pattern matches if zero or more occurrences of any of the
2754
patterns in the PATTERN-LIST allow matching the input string.
2755
2756
`+(PATTERN-LIST)'
2757
The pattern matches if one or more occurrences of any of the
2758
patterns in the PATTERN-LIST allow matching the input string.
2759
2760
`@(PATTERN-LIST)'
2761
The pattern matches if exactly one occurrence of any of the
2762
patterns in the PATTERN-LIST allows matching the input string.
2763
2764
`!(PATTERN-LIST)'
2765
The pattern matches if the input string cannot be matched
2766
with any of the patterns in the PATTERN-LIST.
2767
2768
2769
File: libc.info, Node: Globbing, Next: Regular Expressions, Prev: Wildcard Matching, Up: Pattern Matching
2770
2771
10.2 Globbing
2772
=============
2773
2774
The archetypal use of wildcards is for matching against the files in a
2775
directory, and making a list of all the matches. This is called
2776
"globbing".
2777
2778
You could do this using `fnmatch', by reading the directory entries
2779
one by one and testing each one with `fnmatch'. But that would be slow
2780
(and complex, since you would have to handle subdirectories by hand).
2781
2782
The library provides a function `glob' to make this particular use
2783
of wildcards convenient. `glob' and the other symbols in this section
2784
are declared in `glob.h'.
2785
2786
* Menu:
2787
2788
* Calling Glob:: Basic use of `glob'.
2789
* Flags for Globbing:: Flags that enable various options in `glob'.
2790
* More Flags for Globbing:: GNU specific extensions to `glob'.
2791
2792
2793
File: libc.info, Node: Calling Glob, Next: Flags for Globbing, Up: Globbing
2794
2795
10.2.1 Calling `glob'
2796
---------------------
2797
2798
The result of globbing is a vector of file names (strings). To return
2799
this vector, `glob' uses a special data type, `glob_t', which is a
2800
structure. You pass `glob' the address of the structure, and it fills
2801
in the structure's fields to tell you about the results.
2802
2803
-- Data Type: glob_t
2804
This data type holds a pointer to a word vector. More precisely,
2805
it records both the address of the word vector and its size. The
2806
GNU implementation contains some more fields which are non-standard
2807
extensions.
2808
2809
`gl_pathc'
2810
The number of elements in the vector, excluding the initial
2811
null entries if the GLOB_DOOFFS flag is used (see gl_offs
2812
below).
2813
2814
`gl_pathv'
2815
The address of the vector. This field has type `char **'.
2816
2817
`gl_offs'
2818
The offset of the first real element of the vector, from its
2819
nominal address in the `gl_pathv' field. Unlike the other
2820
fields, this is always an input to `glob', rather than an
2821
output from it.
2822
2823
If you use a nonzero offset, then that many elements at the
2824
beginning of the vector are left empty. (The `glob' function
2825
fills them with null pointers.)
2826
2827
The `gl_offs' field is meaningful only if you use the
2828
`GLOB_DOOFFS' flag. Otherwise, the offset is always zero
2829
regardless of what is in this field, and the first real
2830
element comes at the beginning of the vector.
2831
2832
`gl_closedir'
2833
The address of an alternative implementation of the `closedir'
2834
function. It is used if the `GLOB_ALTDIRFUNC' bit is set in
2835
the flag parameter. The type of this field is
2836
`void (*) (void *)'.
2837
2838
This is a GNU extension.
2839
2840
`gl_readdir'
2841
The address of an alternative implementation of the `readdir'
2842
function used to read the contents of a directory. It is
2843
used if the `GLOB_ALTDIRFUNC' bit is set in the flag
2844
parameter. The type of this field is
2845
`struct dirent *(*) (void *)'.
2846
2847
This is a GNU extension.
2848
2849
`gl_opendir'
2850
The address of an alternative implementation of the `opendir'
2851
function. It is used if the `GLOB_ALTDIRFUNC' bit is set in
2852
the flag parameter. The type of this field is
2853
`void *(*) (const char *)'.
2854
2855
This is a GNU extension.
2856
2857
`gl_stat'
2858
The address of an alternative implementation of the `stat'
2859
function to get information about an object in the
2860
filesystem. It is used if the `GLOB_ALTDIRFUNC' bit is set
2861
in the flag parameter. The type of this field is
2862
`int (*) (const char *, struct stat *)'.
2863
2864
This is a GNU extension.
2865
2866
`gl_lstat'
2867
The address of an alternative implementation of the `lstat'
2868
function to get information about an object in the
2869
filesystems, not following symbolic links. It is used if the
2870
`GLOB_ALTDIRFUNC' bit is set in the flag parameter. The type
2871
of this field is `int (*) (const char *, struct stat *)'.
2872
2873
This is a GNU extension.
2874
2875
For use in the `glob64' function `glob.h' contains another
2876
definition for a very similar type. `glob64_t' differs from `glob_t'
2877
only in the types of the members `gl_readdir', `gl_stat', and
2878
`gl_lstat'.
2879
2880
-- Data Type: glob64_t
2881
This data type holds a pointer to a word vector. More precisely,
2882
it records both the address of the word vector and its size. The
2883
GNU implementation contains some more fields which are non-standard
2884
extensions.
2885
2886
`gl_pathc'
2887
The number of elements in the vector, excluding the initial
2888
null entries if the GLOB_DOOFFS flag is used (see gl_offs
2889
below).
2890
2891
`gl_pathv'
2892
The address of the vector. This field has type `char **'.
2893
2894
`gl_offs'
2895
The offset of the first real element of the vector, from its
2896
nominal address in the `gl_pathv' field. Unlike the other
2897
fields, this is always an input to `glob', rather than an
2898
output from it.
2899
2900
If you use a nonzero offset, then that many elements at the
2901
beginning of the vector are left empty. (The `glob' function
2902
fills them with null pointers.)
2903
2904
The `gl_offs' field is meaningful only if you use the
2905
`GLOB_DOOFFS' flag. Otherwise, the offset is always zero
2906
regardless of what is in this field, and the first real
2907
element comes at the beginning of the vector.
2908
2909
`gl_closedir'
2910
The address of an alternative implementation of the `closedir'
2911
function. It is used if the `GLOB_ALTDIRFUNC' bit is set in
2912
the flag parameter. The type of this field is
2913
`void (*) (void *)'.
2914
2915
This is a GNU extension.
2916
2917
`gl_readdir'
2918
The address of an alternative implementation of the
2919
`readdir64' function used to read the contents of a
2920
directory. It is used if the `GLOB_ALTDIRFUNC' bit is set in
2921
the flag parameter. The type of this field is
2922
`struct dirent64 *(*) (void *)'.
2923
2924
This is a GNU extension.
2925
2926
`gl_opendir'
2927
The address of an alternative implementation of the `opendir'
2928
function. It is used if the `GLOB_ALTDIRFUNC' bit is set in
2929
the flag parameter. The type of this field is
2930
`void *(*) (const char *)'.
2931
2932
This is a GNU extension.
2933
2934
`gl_stat'
2935
The address of an alternative implementation of the `stat64'
2936
function to get information about an object in the
2937
filesystem. It is used if the `GLOB_ALTDIRFUNC' bit is set
2938
in the flag parameter. The type of this field is
2939
`int (*) (const char *, struct stat64 *)'.
2940
2941
This is a GNU extension.
2942
2943
`gl_lstat'
2944
The address of an alternative implementation of the `lstat64'
2945
function to get information about an object in the
2946
filesystems, not following symbolic links. It is used if the
2947
`GLOB_ALTDIRFUNC' bit is set in the flag parameter. The type
2948
of this field is `int (*) (const char *, struct stat64 *)'.
2949
2950
This is a GNU extension.
2951
2952
-- Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
2953
(const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
2954
The function `glob' does globbing using the pattern PATTERN in the
2955
current directory. It puts the result in a newly allocated
2956
vector, and stores the size and address of this vector into
2957
`*VECTOR-PTR'. The argument FLAGS is a combination of bit flags;
2958
see *note Flags for Globbing::, for details of the flags.
2959
2960
The result of globbing is a sequence of file names. The function
2961
`glob' allocates a string for each resulting word, then allocates
2962
a vector of type `char **' to store the addresses of these
2963
strings. The last element of the vector is a null pointer. This
2964
vector is called the "word vector".
2965
2966
To return this vector, `glob' stores both its address and its
2967
length (number of elements, not counting the terminating null
2968
pointer) into `*VECTOR-PTR'.
2969
2970
Normally, `glob' sorts the file names alphabetically before
2971
returning them. You can turn this off with the flag `GLOB_NOSORT'
2972
if you want to get the information as fast as possible. Usually
2973
it's a good idea to let `glob' sort them--if you process the files
2974
in alphabetical order, the users will have a feel for the rate of
2975
progress that your application is making.
2976
2977
If `glob' succeeds, it returns 0. Otherwise, it returns one of
2978
these error codes:
2979
2980
`GLOB_ABORTED'
2981
There was an error opening a directory, and you used the flag
2982
`GLOB_ERR' or your specified ERRFUNC returned a nonzero value.
2983
*Note Flags for Globbing::, for an explanation of the
2984
`GLOB_ERR' flag and ERRFUNC.
2985
2986
`GLOB_NOMATCH'
2987
The pattern didn't match any existing files. If you use the
2988
`GLOB_NOCHECK' flag, then you never get this error code,
2989
because that flag tells `glob' to _pretend_ that the pattern
2990
matched at least one file.
2991
2992
`GLOB_NOSPACE'
2993
It was impossible to allocate memory to hold the result.
2994
2995
In the event of an error, `glob' stores information in
2996
`*VECTOR-PTR' about all the matches it has found so far.
2997
2998
It is important to notice that the `glob' function will not fail if
2999
it encounters directories or files which cannot be handled without
3000
the LFS interfaces. The implementation of `glob' is supposed to
3001
use these functions internally. This at least is the assumptions
3002
made by the Unix standard. The GNU extension of allowing the user
3003
to provide own directory handling and `stat' functions complicates
3004
things a bit. If these callback functions are used and a large
3005
file or directory is encountered `glob' _can_ fail.
3006
3007
-- Function: int glob64 (const char *PATTERN, int FLAGS, int
3008
(*ERRFUNC) (const char *FILENAME, int ERROR-CODE), glob64_t
3009
*VECTOR-PTR)
3010
The `glob64' function was added as part of the Large File Summit
3011
extensions but is not part of the original LFS proposal. The
3012
reason for this is simple: it is not necessary. The necessity for
3013
a `glob64' function is added by the extensions of the GNU `glob'
3014
implementation which allows the user to provide own directory
3015
handling and `stat' functions. The `readdir' and `stat' functions
3016
do depend on the choice of `_FILE_OFFSET_BITS' since the definition
3017
of the types `struct dirent' and `struct stat' will change
3018
depending on the choice.
3019
3020
Beside this difference the `glob64' works just like `glob' in all
3021
aspects.
3022
3023
This function is a GNU extension.
3024
3025
3026
File: libc.info, Node: Flags for Globbing, Next: More Flags for Globbing, Prev: Calling Glob, Up: Globbing
3027
3028
10.2.2 Flags for Globbing
3029
-------------------------
3030
3031
This section describes the flags that you can specify in the FLAGS
3032
argument to `glob'. Choose the flags you want, and combine them with
3033
the C bitwise OR operator `|'.
3034
3035
`GLOB_APPEND'
3036
Append the words from this expansion to the vector of words
3037
produced by previous calls to `glob'. This way you can
3038
effectively expand several words as if they were concatenated with
3039
spaces between them.
3040
3041
In order for appending to work, you must not modify the contents
3042
of the word vector structure between calls to `glob'. And, if you
3043
set `GLOB_DOOFFS' in the first call to `glob', you must also set
3044
it when you append to the results.
3045
3046
Note that the pointer stored in `gl_pathv' may no longer be valid
3047
after you call `glob' the second time, because `glob' might have
3048
relocated the vector. So always fetch `gl_pathv' from the
3049
`glob_t' structure after each `glob' call; *never* save the
3050
pointer across calls.
3051
3052
`GLOB_DOOFFS'
3053
Leave blank slots at the beginning of the vector of words. The
3054
`gl_offs' field says how many slots to leave. The blank slots
3055
contain null pointers.
3056
3057
`GLOB_ERR'
3058
Give up right away and report an error if there is any difficulty
3059
reading the directories that must be read in order to expand
3060
PATTERN fully. Such difficulties might include a directory in
3061
which you don't have the requisite access. Normally, `glob' tries
3062
its best to keep on going despite any errors, reading whatever
3063
directories it can.
3064
3065
You can exercise even more control than this by specifying an
3066
error-handler function ERRFUNC when you call `glob'. If ERRFUNC
3067
is not a null pointer, then `glob' doesn't give up right away when
3068
it can't read a directory; instead, it calls ERRFUNC with two
3069
arguments, like this:
3070
3071
(*ERRFUNC) (FILENAME, ERROR-CODE)
3072
3073
The argument FILENAME is the name of the directory that `glob'
3074
couldn't open or couldn't read, and ERROR-CODE is the `errno'
3075
value that was reported to `glob'.
3076
3077
If the error handler function returns nonzero, then `glob' gives up
3078
right away. Otherwise, it continues.
3079
3080
`GLOB_MARK'
3081
If the pattern matches the name of a directory, append `/' to the
3082
directory's name when returning it.
3083
3084
`GLOB_NOCHECK'
3085
If the pattern doesn't match any file names, return the pattern
3086
itself as if it were a file name that had been matched.
3087
(Normally, when the pattern doesn't match anything, `glob' returns
3088
that there were no matches.)
3089
3090
`GLOB_NOSORT'
3091
Don't sort the file names; return them in no particular order.
3092
(In practice, the order will depend on the order of the entries in
3093
the directory.) The only reason _not_ to sort is to save time.
3094
3095
`GLOB_NOESCAPE'
3096
Don't treat the `\' character specially in patterns. Normally,
3097
`\' quotes the following character, turning off its special meaning
3098
(if any) so that it matches only itself. When quoting is enabled,
3099
the pattern `\?' matches only the string `?', because the question
3100
mark in the pattern acts like an ordinary character.
3101
3102
If you use `GLOB_NOESCAPE', then `\' is an ordinary character.
3103
3104
`glob' does its work by calling the function `fnmatch' repeatedly.
3105
It handles the flag `GLOB_NOESCAPE' by turning on the
3106
`FNM_NOESCAPE' flag in calls to `fnmatch'.
3107
3108
3109
File: libc.info, Node: More Flags for Globbing, Prev: Flags for Globbing, Up: Globbing
3110
3111
10.2.3 More Flags for Globbing
3112
------------------------------
3113
3114
Beside the flags described in the last section, the GNU implementation
3115
of `glob' allows a few more flags which are also defined in the
3116
`glob.h' file. Some of the extensions implement functionality which is
3117
available in modern shell implementations.
3118
3119
`GLOB_PERIOD'
3120
The `.' character (period) is treated special. It cannot be
3121
matched by wildcards. *Note Wildcard Matching::, `FNM_PERIOD'.
3122
3123
`GLOB_MAGCHAR'
3124
The `GLOB_MAGCHAR' value is not to be given to `glob' in the FLAGS
3125
parameter. Instead, `glob' sets this bit in the GL_FLAGS element
3126
of the GLOB_T structure provided as the result if the pattern used
3127
for matching contains any wildcard character.
3128
3129
`GLOB_ALTDIRFUNC'
3130
Instead of the using the using the normal functions for accessing
3131
the filesystem the `glob' implementation uses the user-supplied
3132
functions specified in the structure pointed to by PGLOB
3133
parameter. For more information about the functions refer to the
3134
sections about directory handling see *note Accessing
3135
Directories::, and *note Reading Attributes::.
3136
3137
`GLOB_BRACE'
3138
If this flag is given the handling of braces in the pattern is
3139
changed. It is now required that braces appear correctly grouped.
3140
I.e., for each opening brace there must be a closing one. Braces
3141
can be used recursively. So it is possible to define one brace
3142
expression in another one. It is important to note that the range
3143
of each brace expression is completely contained in the outer
3144
brace expression (if there is one).
3145
3146
The string between the matching braces is separated into single
3147
expressions by splitting at `,' (comma) characters. The commas
3148
themselves are discarded. Please note what we said above about
3149
recursive brace expressions. The commas used to separate the
3150
subexpressions must be at the same level. Commas in brace
3151
subexpressions are not matched. They are used during expansion of
3152
the brace expression of the deeper level. The example below shows
3153
this
3154
3155
glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)
3156
3157
is equivalent to the sequence
3158
3159
glob ("foo/", GLOB_BRACE, NULL, &result)
3160
glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
3161
glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
3162
glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
3163
3164
if we leave aside error handling.
3165
3166
`GLOB_NOMAGIC'
3167
If the pattern contains no wildcard constructs (it is a literal
3168
file name), return it as the sole "matching" word, even if no file
3169
exists by that name.
3170
3171
`GLOB_TILDE'
3172
If this flag is used the character `~' (tilde) is handled special
3173
if it appears at the beginning of the pattern. Instead of being
3174
taken verbatim it is used to represent the home directory of a
3175
known user.
3176
3177
If `~' is the only character in pattern or it is followed by a `/'
3178
(slash), the home directory of the process owner is substituted.
3179
Using `getlogin' and `getpwnam' the information is read from the
3180
system databases. As an example take user `bart' with his home
3181
directory at `/home/bart'. For him a call like
3182
3183
glob ("~/bin/*", GLOB_TILDE, NULL, &result)
3184
3185
would return the contents of the directory `/home/bart/bin'.
3186
Instead of referring to the own home directory it is also possible
3187
to name the home directory of other users. To do so one has to
3188
append the user name after the tilde character. So the contents
3189
of user `homer''s `bin' directory can be retrieved by
3190
3191
glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
3192
3193
If the user name is not valid or the home directory cannot be
3194
determined for some reason the pattern is left untouched and
3195
itself used as the result. I.e., if in the last example `home' is
3196
not available the tilde expansion yields to `"~homer/bin/*"' and
3197
`glob' is not looking for a directory named `~homer'.
3198
3199
This functionality is equivalent to what is available in C-shells
3200
if the `nonomatch' flag is set.
3201
3202
`GLOB_TILDE_CHECK'
3203
If this flag is used `glob' behaves like as if `GLOB_TILDE' is
3204
given. The only difference is that if the user name is not
3205
available or the home directory cannot be determined for other
3206
reasons this leads to an error. `glob' will return `GLOB_NOMATCH'
3207
instead of using the pattern itself as the name.
3208
3209
This functionality is equivalent to what is available in C-shells
3210
if `nonomatch' flag is not set.
3211
3212
`GLOB_ONLYDIR'
3213
If this flag is used the globbing function takes this as a *hint*
3214
that the caller is only interested in directories matching the
3215
pattern. If the information about the type of the file is easily
3216
available non-directories will be rejected but no extra work will
3217
be done to determine the information for each file. I.e., the
3218
caller must still be able to filter directories out.
3219
3220
This functionality is only available with the GNU `glob'
3221
implementation. It is mainly used internally to increase the
3222
performance but might be useful for a user as well and therefore is
3223
documented here.
3224
3225
Calling `glob' will in most cases allocate resources which are used
3226
to represent the result of the function call. If the same object of
3227
type `glob_t' is used in multiple call to `glob' the resources are
3228
freed or reused so that no leaks appear. But this does not include the
3229
time when all `glob' calls are done.
3230
3231
-- Function: void globfree (glob_t *PGLOB)
3232
The `globfree' function frees all resources allocated by previous
3233
calls to `glob' associated with the object pointed to by PGLOB.
3234
This function should be called whenever the currently used
3235
`glob_t' typed object isn't used anymore.
3236
3237
-- Function: void globfree64 (glob64_t *PGLOB)
3238
This function is equivalent to `globfree' but it frees records of
3239
type `glob64_t' which were allocated by `glob64'.
3240
3241
3242
File: libc.info, Node: Regular Expressions, Next: Word Expansion, Prev: Globbing, Up: Pattern Matching
3243
3244
10.3 Regular Expression Matching
3245
================================
3246
3247
The GNU C library supports two interfaces for matching regular
3248
expressions. One is the standard POSIX.2 interface, and the other is
3249
what the GNU system has had for many years.
3250
3251
Both interfaces are declared in the header file `regex.h'. If you
3252
define `_POSIX_C_SOURCE', then only the POSIX.2 functions, structures,
3253
and constants are declared.
3254
3255
* Menu:
3256
3257
* POSIX Regexp Compilation:: Using `regcomp' to prepare to match.
3258
* Flags for POSIX Regexps:: Syntax variations for `regcomp'.
3259
* Matching POSIX Regexps:: Using `regexec' to match the compiled
3260
pattern that you get from `regcomp'.
3261
* Regexp Subexpressions:: Finding which parts of the string were matched.
3262
* Subexpression Complications:: Find points of which parts were matched.
3263
* Regexp Cleanup:: Freeing storage; reporting errors.
3264
3265
3266
File: libc.info, Node: POSIX Regexp Compilation, Next: Flags for POSIX Regexps, Up: Regular Expressions
3267
3268
10.3.1 POSIX Regular Expression Compilation
3269
-------------------------------------------
3270
3271
Before you can actually match a regular expression, you must "compile"
3272
it. This is not true compilation--it produces a special data
3273
structure, not machine instructions. But it is like ordinary
3274
compilation in that its purpose is to enable you to "execute" the
3275
pattern fast. (*Note Matching POSIX Regexps::, for how to use the
3276
compiled regular expression for matching.)
3277
3278
There is a special data type for compiled regular expressions:
3279
3280
-- Data Type: regex_t
3281
This type of object holds a compiled regular expression. It is
3282
actually a structure. It has just one field that your programs
3283
should look at:
3284
3285
`re_nsub'
3286
This field holds the number of parenthetical subexpressions
3287
in the regular expression that was compiled.
3288
3289
There are several other fields, but we don't describe them here,
3290
because only the functions in the library should use them.
3291
3292
After you create a `regex_t' object, you can compile a regular
3293
expression into it by calling `regcomp'.
3294
3295
-- Function: int regcomp (regex_t *restrict COMPILED, const char
3296
*restrict PATTERN, int CFLAGS)
3297
The function `regcomp' "compiles" a regular expression into a data
3298
structure that you can use with `regexec' to match against a
3299
string. The compiled regular expression format is designed for
3300
efficient matching. `regcomp' stores it into `*COMPILED'.
3301
3302
It's up to you to allocate an object of type `regex_t' and pass its
3303
address to `regcomp'.
3304
3305
The argument CFLAGS lets you specify various options that control
3306
the syntax and semantics of regular expressions. *Note Flags for
3307
POSIX Regexps::.
3308
3309
If you use the flag `REG_NOSUB', then `regcomp' omits from the
3310
compiled regular expression the information necessary to record
3311
how subexpressions actually match. In this case, you might as well
3312
pass `0' for the MATCHPTR and NMATCH arguments when you call
3313
`regexec'.
3314
3315
If you don't use `REG_NOSUB', then the compiled regular expression
3316
does have the capacity to record how subexpressions match. Also,
3317
`regcomp' tells you how many subexpressions PATTERN has, by
3318
storing the number in `COMPILED->re_nsub'. You can use that value
3319
to decide how long an array to allocate to hold information about
3320
subexpression matches.
3321
3322
`regcomp' returns `0' if it succeeds in compiling the regular
3323
expression; otherwise, it returns a nonzero error code (see the
3324
table below). You can use `regerror' to produce an error message
3325
string describing the reason for a nonzero value; see *note Regexp
3326
Cleanup::.
3327
3328
3329
Here are the possible nonzero values that `regcomp' can return:
3330
3331
`REG_BADBR'
3332
There was an invalid `\{...\}' construct in the regular
3333
expression. A valid `\{...\}' construct must contain either a
3334
single number, or two numbers in increasing order separated by a
3335
comma.
3336
3337
`REG_BADPAT'
3338
There was a syntax error in the regular expression.
3339
3340
`REG_BADRPT'
3341
A repetition operator such as `?' or `*' appeared in a bad
3342
position (with no preceding subexpression to act on).
3343
3344
`REG_ECOLLATE'
3345
The regular expression referred to an invalid collating element
3346
(one not defined in the current locale for string collation).
3347
*Note Locale Categories::.
3348
3349
`REG_ECTYPE'
3350
The regular expression referred to an invalid character class name.
3351
3352
`REG_EESCAPE'
3353
The regular expression ended with `\'.
3354
3355
`REG_ESUBREG'
3356
There was an invalid number in the `\DIGIT' construct.
3357
3358
`REG_EBRACK'
3359
There were unbalanced square brackets in the regular expression.
3360
3361
`REG_EPAREN'
3362
An extended regular expression had unbalanced parentheses, or a
3363
basic regular expression had unbalanced `\(' and `\)'.
3364
3365
`REG_EBRACE'
3366
The regular expression had unbalanced `\{' and `\}'.
3367
3368
`REG_ERANGE'
3369
One of the endpoints in a range expression was invalid.
3370
3371
`REG_ESPACE'
3372
`regcomp' ran out of memory.
3373
3374
3375
File: libc.info, Node: Flags for POSIX Regexps, Next: Matching POSIX Regexps, Prev: POSIX Regexp Compilation, Up: Regular Expressions
3376
3377
10.3.2 Flags for POSIX Regular Expressions
3378
------------------------------------------
3379
3380
These are the bit flags that you can use in the CFLAGS operand when
3381
compiling a regular expression with `regcomp'.
3382
3383
`REG_EXTENDED'
3384
Treat the pattern as an extended regular expression, rather than
3385
as a basic regular expression.
3386
3387
`REG_ICASE'
3388
Ignore case when matching letters.
3389
3390
`REG_NOSUB'
3391
Don't bother storing the contents of the MATCHES-PTR array.
3392
3393
`REG_NEWLINE'
3394
Treat a newline in STRING as dividing STRING into multiple lines,
3395
so that `$' can match before the newline and `^' can match after.
3396
Also, don't permit `.' to match a newline, and don't permit
3397
`[^...]' to match a newline.
3398
3399
Otherwise, newline acts like any other ordinary character.
3400
3401
3402
File: libc.info, Node: Matching POSIX Regexps, Next: Regexp Subexpressions, Prev: Flags for POSIX Regexps, Up: Regular Expressions
3403
3404
10.3.3 Matching a Compiled POSIX Regular Expression
3405
---------------------------------------------------
3406
3407
Once you have compiled a regular expression, as described in *note
3408
POSIX Regexp Compilation::, you can match it against strings using
3409
`regexec'. A match anywhere inside the string counts as success,
3410
unless the regular expression contains anchor characters (`^' or `$').
3411
3412
-- Function: int regexec (const regex_t *restrict COMPILED, const char
3413
*restrict STRING, size_t NMATCH, regmatch_t
3414
MATCHPTR[restrict], int EFLAGS)
3415
This function tries to match the compiled regular expression
3416
`*COMPILED' against STRING.
3417
3418
`regexec' returns `0' if the regular expression matches;
3419
otherwise, it returns a nonzero value. See the table below for
3420
what nonzero values mean. You can use `regerror' to produce an
3421
error message string describing the reason for a nonzero value;
3422
see *note Regexp Cleanup::.
3423
3424
The argument EFLAGS is a word of bit flags that enable various
3425
options.
3426
3427
If you want to get information about what part of STRING actually
3428
matched the regular expression or its subexpressions, use the
3429
arguments MATCHPTR and NMATCH. Otherwise, pass `0' for NMATCH,
3430
and `NULL' for MATCHPTR. *Note Regexp Subexpressions::.
3431
3432
You must match the regular expression with the same set of current
3433
locales that were in effect when you compiled the regular expression.
3434
3435
The function `regexec' accepts the following flags in the EFLAGS
3436
argument:
3437
3438
`REG_NOTBOL'
3439
Do not regard the beginning of the specified string as the
3440
beginning of a line; more generally, don't make any assumptions
3441
about what text might precede it.
3442
3443
`REG_NOTEOL'
3444
Do not regard the end of the specified string as the end of a
3445
line; more generally, don't make any assumptions about what text
3446
might follow it.
3447
3448
Here are the possible nonzero values that `regexec' can return:
3449
3450
`REG_NOMATCH'
3451
The pattern didn't match the string. This isn't really an error.
3452
3453
`REG_ESPACE'
3454
`regexec' ran out of memory.
3455
3456
3457
File: libc.info, Node: Regexp Subexpressions, Next: Subexpression Complications, Prev: Matching POSIX Regexps, Up: Regular Expressions
3458
3459
10.3.4 Match Results with Subexpressions
3460
----------------------------------------
3461
3462
When `regexec' matches parenthetical subexpressions of PATTERN, it
3463
records which parts of STRING they match. It returns that information
3464
by storing the offsets into an array whose elements are structures of
3465
type `regmatch_t'. The first element of the array (index `0') records
3466
the part of the string that matched the entire regular expression.
3467
Each other element of the array records the beginning and end of the
3468
part that matched a single parenthetical subexpression.
3469
3470
-- Data Type: regmatch_t
3471
This is the data type of the MATCHARRAY array that you pass to
3472
`regexec'. It contains two structure fields, as follows:
3473
3474
`rm_so'
3475
The offset in STRING of the beginning of a substring. Add
3476
this value to STRING to get the address of that part.
3477
3478
`rm_eo'
3479
The offset in STRING of the end of the substring.
3480
3481
-- Data Type: regoff_t
3482
`regoff_t' is an alias for another signed integer type. The
3483
fields of `regmatch_t' have type `regoff_t'.
3484
3485
The `regmatch_t' elements correspond to subexpressions positionally;
3486
the first element (index `1') records where the first subexpression
3487
matched, the second element records the second subexpression, and so
3488
on. The order of the subexpressions is the order in which they begin.
3489
3490
When you call `regexec', you specify how long the MATCHPTR array is,
3491
with the NMATCH argument. This tells `regexec' how many elements to
3492
store. If the actual regular expression has more than NMATCH
3493
subexpressions, then you won't get offset information about the rest of
3494
them. But this doesn't alter whether the pattern matches a particular
3495
string or not.
3496
3497
If you don't want `regexec' to return any information about where
3498
the subexpressions matched, you can either supply `0' for NMATCH, or
3499
use the flag `REG_NOSUB' when you compile the pattern with `regcomp'.
3500
3501
3502
File: libc.info, Node: Subexpression Complications, Next: Regexp Cleanup, Prev: Regexp Subexpressions, Up: Regular Expressions
3503
3504
10.3.5 Complications in Subexpression Matching
3505
----------------------------------------------
3506
3507
Sometimes a subexpression matches a substring of no characters. This
3508
happens when `f\(o*\)' matches the string `fum'. (It really matches
3509
just the `f'.) In this case, both of the offsets identify the point in
3510
the string where the null substring was found. In this example, the
3511
offsets are both `1'.
3512
3513
Sometimes the entire regular expression can match without using some
3514
of its subexpressions at all--for example, when `ba\(na\)*' matches the
3515
string `ba', the parenthetical subexpression is not used. When this
3516
happens, `regexec' stores `-1' in both fields of the element for that
3517
subexpression.
3518
3519
Sometimes matching the entire regular expression can match a
3520
particular subexpression more than once--for example, when `ba\(na\)*'
3521
matches the string `bananana', the parenthetical subexpression matches
3522
three times. When this happens, `regexec' usually stores the offsets
3523
of the last part of the string that matched the subexpression. In the
3524
case of `bananana', these offsets are `6' and `8'.
3525
3526
But the last match is not always the one that is chosen. It's more
3527
accurate to say that the last _opportunity_ to match is the one that
3528
takes precedence. What this means is that when one subexpression
3529
appears within another, then the results reported for the inner
3530
subexpression reflect whatever happened on the last match of the outer
3531
subexpression. For an example, consider `\(ba\(na\)*s \)*' matching
3532
the string `bananas bas '. The last time the inner expression actually
3533
matches is near the end of the first word. But it is _considered_
3534
again in the second word, and fails to match there. `regexec' reports
3535
nonuse of the "na" subexpression.
3536
3537
Another place where this rule applies is when the regular expression
3538
\(ba\(na\)*s \|nefer\(ti\)* \)*
3539
matches `bananas nefertiti'. The "na" subexpression does match in
3540
the first word, but it doesn't match in the second word because the
3541
other alternative is used there. Once again, the second repetition of
3542
the outer subexpression overrides the first, and within that second
3543
repetition, the "na" subexpression is not used. So `regexec' reports
3544
nonuse of the "na" subexpression.
3545
3546
3547
File: libc.info, Node: Regexp Cleanup, Prev: Subexpression Complications, Up: Regular Expressions
3548
3549
10.3.6 POSIX Regexp Matching Cleanup
3550
------------------------------------
3551
3552
When you are finished using a compiled regular expression, you can free
3553
the storage it uses by calling `regfree'.
3554
3555
-- Function: void regfree (regex_t *COMPILED)
3556
Calling `regfree' frees all the storage that `*COMPILED' points
3557
to. This includes various internal fields of the `regex_t'
3558
structure that aren't documented in this manual.
3559
3560
`regfree' does not free the object `*COMPILED' itself.
3561
3562
You should always free the space in a `regex_t' structure with
3563
`regfree' before using the structure to compile another regular
3564
expression.
3565
3566
When `regcomp' or `regexec' reports an error, you can use the
3567
function `regerror' to turn it into an error message string.
3568
3569
-- Function: size_t regerror (int ERRCODE, const regex_t *restrict
3570
COMPILED, char *restrict BUFFER, size_t LENGTH)
3571
This function produces an error message string for the error code
3572
ERRCODE, and stores the string in LENGTH bytes of memory starting
3573
at BUFFER. For the COMPILED argument, supply the same compiled
3574
regular expression structure that `regcomp' or `regexec' was
3575
working with when it got the error. Alternatively, you can supply
3576
`NULL' for COMPILED; you will still get a meaningful error
3577
message, but it might not be as detailed.
3578
3579
If the error message can't fit in LENGTH bytes (including a
3580
terminating null character), then `regerror' truncates it. The
3581
string that `regerror' stores is always null-terminated even if it
3582
has been truncated.
3583
3584
The return value of `regerror' is the minimum length needed to
3585
store the entire error message. If this is less than LENGTH, then
3586
the error message was not truncated, and you can use it.
3587
Otherwise, you should call `regerror' again with a larger buffer.
3588
3589
Here is a function which uses `regerror', but always dynamically
3590
allocates a buffer for the error message:
3591
3592
char *get_regerror (int errcode, regex_t *compiled)
3593
{
3594
size_t length = regerror (errcode, compiled, NULL, 0);
3595
char *buffer = xmalloc (length);
3596
(void) regerror (errcode, compiled, buffer, length);
3597
return buffer;
3598
}
3599
3600
3601
File: libc.info, Node: Word Expansion, Prev: Regular Expressions, Up: Pattern Matching
3602
3603
10.4 Shell-Style Word Expansion
3604
===============================
3605
3606
"Word expansion" means the process of splitting a string into "words"
3607
and substituting for variables, commands, and wildcards just as the
3608
shell does.
3609
3610
For example, when you write `ls -l foo.c', this string is split into
3611
three separate words--`ls', `-l' and `foo.c'. This is the most basic
3612
function of word expansion.
3613
3614
When you write `ls *.c', this can become many words, because the
3615
word `*.c' can be replaced with any number of file names. This is
3616
called "wildcard expansion", and it is also a part of word expansion.
3617
3618
When you use `echo $PATH' to print your path, you are taking
3619
advantage of "variable substitution", which is also part of word
3620
expansion.
3621
3622
Ordinary programs can perform word expansion just like the shell by
3623
calling the library function `wordexp'.
3624
3625
* Menu:
3626
3627
* Expansion Stages:: What word expansion does to a string.
3628
* Calling Wordexp:: How to call `wordexp'.
3629
* Flags for Wordexp:: Options you can enable in `wordexp'.
3630
* Wordexp Example:: A sample program that does word expansion.
3631
* Tilde Expansion:: Details of how tilde expansion works.
3632
* Variable Substitution:: Different types of variable substitution.
3633
3634
3635
File: libc.info, Node: Expansion Stages, Next: Calling Wordexp, Up: Word Expansion
3636
3637
10.4.1 The Stages of Word Expansion
3638
-----------------------------------
3639
3640
When word expansion is applied to a sequence of words, it performs the
3641
following transformations in the order shown here:
3642
3643
1. "Tilde expansion": Replacement of `~foo' with the name of the home
3644
directory of `foo'.
3645
3646
2. Next, three different transformations are applied in the same step,
3647
from left to right:
3648
3649
* "Variable substitution": Environment variables are
3650
substituted for references such as `$foo'.
3651
3652
* "Command substitution": Constructs such as ``cat foo`' and
3653
the equivalent `$(cat foo)' are replaced with the output from
3654
the inner command.
3655
3656
* "Arithmetic expansion": Constructs such as `$(($x-1))' are
3657
replaced with the result of the arithmetic computation.
3658
3659
3. "Field splitting": subdivision of the text into "words".
3660
3661
4. "Wildcard expansion": The replacement of a construct such as `*.c'
3662
with a list of `.c' file names. Wildcard expansion applies to an
3663
entire word at a time, and replaces that word with 0 or more file
3664
names that are themselves words.
3665
3666
5. "Quote removal": The deletion of string-quotes, now that they have
3667
done their job by inhibiting the above transformations when
3668
appropriate.
3669
3670
For the details of these transformations, and how to write the
3671
constructs that use them, see `The BASH Manual' (to appear).
3672
3673
3674
File: libc.info, Node: Calling Wordexp, Next: Flags for Wordexp, Prev: Expansion Stages, Up: Word Expansion
3675
3676
10.4.2 Calling `wordexp'
3677
------------------------
3678
3679
All the functions, constants and data types for word expansion are
3680
declared in the header file `wordexp.h'.
3681
3682
Word expansion produces a vector of words (strings). To return this
3683
vector, `wordexp' uses a special data type, `wordexp_t', which is a
3684
structure. You pass `wordexp' the address of the structure, and it
3685
fills in the structure's fields to tell you about the results.
3686
3687
-- Data Type: wordexp_t
3688
This data type holds a pointer to a word vector. More precisely,
3689
it records both the address of the word vector and its size.
3690
3691
`we_wordc'
3692
The number of elements in the vector.
3693
3694
`we_wordv'
3695
The address of the vector. This field has type `char **'.
3696
3697
`we_offs'
3698
The offset of the first real element of the vector, from its
3699
nominal address in the `we_wordv' field. Unlike the other
3700
fields, this is always an input to `wordexp', rather than an
3701
output from it.
3702
3703
If you use a nonzero offset, then that many elements at the
3704
beginning of the vector are left empty. (The `wordexp'
3705
function fills them with null pointers.)
3706
3707
The `we_offs' field is meaningful only if you use the
3708
`WRDE_DOOFFS' flag. Otherwise, the offset is always zero
3709
regardless of what is in this field, and the first real
3710
element comes at the beginning of the vector.
3711
3712
-- Function: int wordexp (const char *WORDS, wordexp_t
3713
*WORD-VECTOR-PTR, int FLAGS)
3714
Perform word expansion on the string WORDS, putting the result in
3715
a newly allocated vector, and store the size and address of this
3716
vector into `*WORD-VECTOR-PTR'. The argument FLAGS is a
3717
combination of bit flags; see *note Flags for Wordexp::, for
3718
details of the flags.
3719
3720
You shouldn't use any of the characters `|&;<>' in the string
3721
WORDS unless they are quoted; likewise for newline. If you use
3722
these characters unquoted, you will get the `WRDE_BADCHAR' error
3723
code. Don't use parentheses or braces unless they are quoted or
3724
part of a word expansion construct. If you use quotation
3725
characters `'"`', they should come in pairs that balance.
3726
3727
The results of word expansion are a sequence of words. The
3728
function `wordexp' allocates a string for each resulting word, then
3729
allocates a vector of type `char **' to store the addresses of
3730
these strings. The last element of the vector is a null pointer.
3731
This vector is called the "word vector".
3732
3733
To return this vector, `wordexp' stores both its address and its
3734
length (number of elements, not counting the terminating null
3735
pointer) into `*WORD-VECTOR-PTR'.
3736
3737
If `wordexp' succeeds, it returns 0. Otherwise, it returns one of
3738
these error codes:
3739
3740
`WRDE_BADCHAR'
3741
The input string WORDS contains an unquoted invalid character
3742
such as `|'.
3743
3744
`WRDE_BADVAL'
3745
The input string refers to an undefined shell variable, and
3746
you used the flag `WRDE_UNDEF' to forbid such references.
3747
3748
`WRDE_CMDSUB'
3749
The input string uses command substitution, and you used the
3750
flag `WRDE_NOCMD' to forbid command substitution.
3751
3752
`WRDE_NOSPACE'
3753
It was impossible to allocate memory to hold the result. In
3754
this case, `wordexp' can store part of the results--as much
3755
as it could allocate room for.
3756
3757
`WRDE_SYNTAX'
3758
There was a syntax error in the input string. For example,
3759
an unmatched quoting character is a syntax error.
3760
3761
-- Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
3762
Free the storage used for the word-strings and vector that
3763
`*WORD-VECTOR-PTR' points to. This does not free the structure
3764
`*WORD-VECTOR-PTR' itself--only the other data it points to.
3765
3766
3767
File: libc.info, Node: Flags for Wordexp, Next: Wordexp Example, Prev: Calling Wordexp, Up: Word Expansion
3768
3769
10.4.3 Flags for Word Expansion
3770
-------------------------------
3771
3772
This section describes the flags that you can specify in the FLAGS
3773
argument to `wordexp'. Choose the flags you want, and combine them
3774
with the C operator `|'.
3775
3776
`WRDE_APPEND'
3777
Append the words from this expansion to the vector of words
3778
produced by previous calls to `wordexp'. This way you can
3779
effectively expand several words as if they were concatenated with
3780
spaces between them.
3781
3782
In order for appending to work, you must not modify the contents
3783
of the word vector structure between calls to `wordexp'. And, if
3784
you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
3785
set it when you append to the results.
3786
3787
`WRDE_DOOFFS'
3788
Leave blank slots at the beginning of the vector of words. The
3789
`we_offs' field says how many slots to leave. The blank slots
3790
contain null pointers.
3791
3792
`WRDE_NOCMD'
3793
Don't do command substitution; if the input requests command
3794
substitution, report an error.
3795
3796
`WRDE_REUSE'
3797
Reuse a word vector made by a previous call to `wordexp'. Instead
3798
of allocating a new vector of words, this call to `wordexp' will
3799
use the vector that already exists (making it larger if necessary).
3800
3801
Note that the vector may move, so it is not safe to save an old
3802
pointer and use it again after calling `wordexp'. You must fetch
3803
`we_pathv' anew after each call.
3804
3805
`WRDE_SHOWERR'
3806
Do show any error messages printed by commands run by command
3807
substitution. More precisely, allow these commands to inherit the
3808
standard error output stream of the current process. By default,
3809
`wordexp' gives these commands a standard error stream that
3810
discards all output.
3811
3812
`WRDE_UNDEF'
3813
If the input refers to a shell variable that is not defined,
3814
report an error.
3815
3816
3817
File: libc.info, Node: Wordexp Example, Next: Tilde Expansion, Prev: Flags for Wordexp, Up: Word Expansion
3818
3819
10.4.4 `wordexp' Example
3820
------------------------
3821
3822
Here is an example of using `wordexp' to expand several strings and use
3823
the results to run a shell command. It also shows the use of
3824
`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
3825
the space allocated by `wordexp'.
3826
3827
int
3828
expand_and_execute (const char *program, const char **options)
3829
{
3830
wordexp_t result;
3831
pid_t pid
3832
int status, i;
3833
3834
/* Expand the string for the program to run. */
3835
switch (wordexp (program, &result, 0))
3836
{
3837
case 0: /* Successful. */
3838
break;
3839
case WRDE_NOSPACE:
3840
/* If the error was `WRDE_NOSPACE',
3841
then perhaps part of the result was allocated. */
3842
wordfree (&result);
3843
default: /* Some other error. */
3844
return -1;
3845
}
3846
3847
/* Expand the strings specified for the arguments. */
3848
for (i = 0; options[i] != NULL; i++)
3849
{
3850
if (wordexp (options[i], &result, WRDE_APPEND))
3851
{
3852
wordfree (&result);
3853
return -1;
3854
}
3855
}
3856
3857
pid = fork ();
3858
if (pid == 0)
3859
{
3860
/* This is the child process. Execute the command. */
3861
execv (result.we_wordv[0], result.we_wordv);
3862
exit (EXIT_FAILURE);
3863
}
3864
else if (pid < 0)
3865
/* The fork failed. Report failure. */
3866
status = -1;
3867
else
3868
/* This is the parent process. Wait for the child to complete. */
3869
if (waitpid (pid, &status, 0) != pid)
3870
status = -1;
3871
3872
wordfree (&result);
3873
return status;
3874
}
3875
3876
3877
File: libc.info, Node: Tilde Expansion, Next: Variable Substitution, Prev: Wordexp Example, Up: Word Expansion
3878
3879
10.4.5 Details of Tilde Expansion
3880
---------------------------------
3881
3882
It's a standard part of shell syntax that you can use `~' at the
3883
beginning of a file name to stand for your own home directory. You can
3884
use `~USER' to stand for USER's home directory.
3885
3886
"Tilde expansion" is the process of converting these abbreviations
3887
to the directory names that they stand for.
3888
3889
Tilde expansion applies to the `~' plus all following characters up
3890
to whitespace or a slash. It takes place only at the beginning of a
3891
word, and only if none of the characters to be transformed is quoted in
3892
any way.
3893
3894
Plain `~' uses the value of the environment variable `HOME' as the
3895
proper home directory name. `~' followed by a user name uses
3896
`getpwname' to look up that user in the user database, and uses
3897
whatever directory is recorded there. Thus, `~' followed by your own
3898
name can give different results from plain `~', if the value of `HOME'
3899
is not really your home directory.
3900
3901
3902
File: libc.info, Node: Variable Substitution, Prev: Tilde Expansion, Up: Word Expansion
3903
3904
10.4.6 Details of Variable Substitution
3905
---------------------------------------
3906
3907
Part of ordinary shell syntax is the use of `$VARIABLE' to substitute
3908
the value of a shell variable into a command. This is called "variable
3909
substitution", and it is one part of doing word expansion.
3910
3911
There are two basic ways you can write a variable reference for
3912
substitution:
3913
3914
`${VARIABLE}'
3915
If you write braces around the variable name, then it is completely
3916
unambiguous where the variable name ends. You can concatenate
3917
additional letters onto the end of the variable value by writing
3918
them immediately after the close brace. For example, `${foo}s'
3919
expands into `tractors'.
3920
3921
`$VARIABLE'
3922
If you do not put braces around the variable name, then the
3923
variable name consists of all the alphanumeric characters and
3924
underscores that follow the `$'. The next punctuation character
3925
ends the variable name. Thus, `$foo-bar' refers to the variable
3926
`foo' and expands into `tractor-bar'.
3927
3928
When you use braces, you can also use various constructs to modify
3929
the value that is substituted, or test it in various ways.
3930
3931
`${VARIABLE:-DEFAULT}'
3932
Substitute the value of VARIABLE, but if that is empty or
3933
undefined, use DEFAULT instead.
3934
3935
`${VARIABLE:=DEFAULT}'
3936
Substitute the value of VARIABLE, but if that is empty or
3937
undefined, use DEFAULT instead and set the variable to DEFAULT.
3938
3939
`${VARIABLE:?MESSAGE}'
3940
If VARIABLE is defined and not empty, substitute its value.
3941
3942
Otherwise, print MESSAGE as an error message on the standard error
3943
stream, and consider word expansion a failure.
3944
3945
`${VARIABLE:+REPLACEMENT}'
3946
Substitute REPLACEMENT, but only if VARIABLE is defined and
3947
nonempty. Otherwise, substitute nothing for this construct.
3948
3949
`${#VARIABLE}'
3950
Substitute a numeral which expresses in base ten the number of
3951
characters in the value of VARIABLE. `${#foo}' stands for `7',
3952
because `tractor' is seven characters.
3953
3954
These variants of variable substitution let you remove part of the
3955
variable's value before substituting it. The PREFIX and SUFFIX are not
3956
mere strings; they are wildcard patterns, just like the patterns that
3957
you use to match multiple file names. But in this context, they match
3958
against parts of the variable value rather than against file names.
3959
3960
`${VARIABLE%%SUFFIX}'
3961
Substitute the value of VARIABLE, but first discard from that
3962
variable any portion at the end that matches the pattern SUFFIX.
3963
3964
If there is more than one alternative for how to match against
3965
SUFFIX, this construct uses the longest possible match.
3966
3967
Thus, `${foo%%r*}' substitutes `t', because the largest match for
3968
`r*' at the end of `tractor' is `ractor'.
3969
3970
`${VARIABLE%SUFFIX}'
3971
Substitute the value of VARIABLE, but first discard from that
3972
variable any portion at the end that matches the pattern SUFFIX.
3973
3974
If there is more than one alternative for how to match against
3975
SUFFIX, this construct uses the shortest possible alternative.
3976
3977
Thus, `${foo%r*}' substitutes `tracto', because the shortest match
3978
for `r*' at the end of `tractor' is just `r'.
3979
3980
`${VARIABLE##PREFIX}'
3981
Substitute the value of VARIABLE, but first discard from that
3982
variable any portion at the beginning that matches the pattern
3983
PREFIX.
3984
3985
If there is more than one alternative for how to match against
3986
PREFIX, this construct uses the longest possible match.
3987
3988
Thus, `${foo##*t}' substitutes `or', because the largest match for
3989
`*t' at the beginning of `tractor' is `tract'.
3990
3991
`${VARIABLE#PREFIX}'
3992
Substitute the value of VARIABLE, but first discard from that
3993
variable any portion at the beginning that matches the pattern
3994
PREFIX.
3995
3996
If there is more than one alternative for how to match against
3997
PREFIX, this construct uses the shortest possible alternative.
3998
3999
Thus, `${foo#*t}' substitutes `ractor', because the shortest match
4000
for `*t' at the beginning of `tractor' is just `t'.
4001
4002
4003
4004
File: libc.info, Node: I/O Overview, Next: I/O on Streams, Prev: Pattern Matching, Up: Top
4005
4006
11 Input/Output Overview
4007
************************
4008
4009
Most programs need to do either input (reading data) or output (writing
4010
data), or most frequently both, in order to do anything useful. The GNU
4011
C library provides such a large selection of input and output functions
4012
that the hardest part is often deciding which function is most
4013
appropriate!
4014
4015
This chapter introduces concepts and terminology relating to input
4016
and output. Other chapters relating to the GNU I/O facilities are:
4017
4018
* *note I/O on Streams::, which covers the high-level functions that
4019
operate on streams, including formatted input and output.
4020
4021
* *note Low-Level I/O::, which covers the basic I/O and control
4022
functions on file descriptors.
4023
4024
* *note File System Interface::, which covers functions for
4025
operating on directories and for manipulating file attributes such
4026
as access modes and ownership.
4027
4028
* *note Pipes and FIFOs::, which includes information on the basic
4029
interprocess communication facilities.
4030
4031
* *note Sockets::, which covers a more complicated interprocess
4032
communication facility with support for networking.
4033
4034
* *note Low-Level Terminal Interface::, which covers functions for
4035
changing how input and output to terminals or other serial devices
4036
are processed.
4037
4038
* Menu:
4039
4040
* I/O Concepts:: Some basic information and terminology.
4041
* File Names:: How to refer to a file.
4042
4043
4044
File: libc.info, Node: I/O Concepts, Next: File Names, Up: I/O Overview
4045
4046
11.1 Input/Output Concepts
4047
==========================
4048
4049
Before you can read or write the contents of a file, you must establish
4050
a connection or communications channel to the file. This process is
4051
called "opening" the file. You can open a file for reading, writing,
4052
or both.
4053
4054
The connection to an open file is represented either as a stream or
4055
as a file descriptor. You pass this as an argument to the functions
4056
that do the actual read or write operations, to tell them which file to
4057
operate on. Certain functions expect streams, and others are designed
4058
to operate on file descriptors.
4059
4060
When you have finished reading to or writing from the file, you can
4061
terminate the connection by "closing" the file. Once you have closed a
4062
stream or file descriptor, you cannot do any more input or output
4063
operations on it.
4064
4065
* Menu:
4066
4067
* Streams and File Descriptors:: The GNU Library provides two ways
4068
to access the contents of files.
4069
* File Position:: The number of bytes from the
4070
beginning of the file.
4071
4072
4073
File: libc.info, Node: Streams and File Descriptors, Next: File Position, Up: I/O Concepts
4074
4075
11.1.1 Streams and File Descriptors
4076
-----------------------------------
4077
4078
When you want to do input or output to a file, you have a choice of two
4079
basic mechanisms for representing the connection between your program
4080
and the file: file descriptors and streams. File descriptors are
4081
represented as objects of type `int', while streams are represented as
4082
`FILE *' objects.
4083
4084
File descriptors provide a primitive, low-level interface to input
4085
and output operations. Both file descriptors and streams can represent
4086
a connection to a device (such as a terminal), or a pipe or socket for
4087
communicating with another process, as well as a normal file. But, if
4088
you want to do control operations that are specific to a particular kind
4089
of device, you must use a file descriptor; there are no facilities to
4090
use streams in this way. You must also use file descriptors if your
4091
program needs to do input or output in special modes, such as
4092
nonblocking (or polled) input (*note File Status Flags::).
4093
4094
Streams provide a higher-level interface, layered on top of the
4095
primitive file descriptor facilities. The stream interface treats all
4096
kinds of files pretty much alike--the sole exception being the three
4097
styles of buffering that you can choose (*note Stream Buffering::).
4098
4099
The main advantage of using the stream interface is that the set of
4100
functions for performing actual input and output operations (as opposed
4101
to control operations) on streams is much richer and more powerful than
4102
the corresponding facilities for file descriptors. The file descriptor
4103
interface provides only simple functions for transferring blocks of
4104
characters, but the stream interface also provides powerful formatted
4105
input and output functions (`printf' and `scanf') as well as functions
4106
for character- and line-oriented input and output.
4107
4108
Since streams are implemented in terms of file descriptors, you can
4109
extract the file descriptor from a stream and perform low-level
4110
operations directly on the file descriptor. You can also initially open
4111
a connection as a file descriptor and then make a stream associated with
4112
that file descriptor.
4113
4114
In general, you should stick with using streams rather than file
4115
descriptors, unless there is some specific operation you want to do that
4116
can only be done on a file descriptor. If you are a beginning
4117
programmer and aren't sure what functions to use, we suggest that you
4118
concentrate on the formatted input functions (*note Formatted Input::)
4119
and formatted output functions (*note Formatted Output::).
4120
4121
If you are concerned about portability of your programs to systems
4122
other than GNU, you should also be aware that file descriptors are not
4123
as portable as streams. You can expect any system running ISO C to
4124
support streams, but non-GNU systems may not support file descriptors at
4125
all, or may only implement a subset of the GNU functions that operate on
4126
file descriptors. Most of the file descriptor functions in the GNU
4127
library are included in the POSIX.1 standard, however.
4128
4129
4130
File: libc.info, Node: File Position, Prev: Streams and File Descriptors, Up: I/O Concepts
4131
4132
11.1.2 File Position
4133
--------------------
4134
4135
One of the attributes of an open file is its "file position" that keeps
4136
track of where in the file the next character is to be read or written.
4137
In the GNU system, and all POSIX.1 systems, the file position is simply
4138
an integer representing the number of bytes from the beginning of the
4139
file.
4140
4141
The file position is normally set to the beginning of the file when
4142
it is opened, and each time a character is read or written, the file
4143
position is incremented. In other words, access to the file is normally
4144
"sequential".
4145
4146
Ordinary files permit read or write operations at any position within
4147
the file. Some other kinds of files may also permit this. Files which
4148
do permit this are sometimes referred to as "random-access" files. You
4149
can change the file position using the `fseek' function on a stream
4150
(*note File Positioning::) or the `lseek' function on a file descriptor
4151
(*note I/O Primitives::). If you try to change the file position on a
4152
file that doesn't support random access, you get the `ESPIPE' error.
4153
4154
Streams and descriptors that are opened for "append access" are
4155
treated specially for output: output to such files is _always_ appended
4156
sequentially to the _end_ of the file, regardless of the file position.
4157
However, the file position is still used to control where in the file
4158
reading is done.
4159
4160
If you think about it, you'll realize that several programs can read
4161
a given file at the same time. In order for each program to be able to
4162
read the file at its own pace, each program must have its own file
4163
pointer, which is not affected by anything the other programs do.
4164
4165
In fact, each opening of a file creates a separate file position.
4166
Thus, if you open a file twice even in the same program, you get two
4167
streams or descriptors with independent file positions.
4168
4169
By contrast, if you open a descriptor and then duplicate it to get
4170
another descriptor, these two descriptors share the same file position:
4171
changing the file position of one descriptor will affect the other.
4172
4173
4174
File: libc.info, Node: File Names, Prev: I/O Concepts, Up: I/O Overview
4175
4176
11.2 File Names
4177
===============
4178
4179
In order to open a connection to a file, or to perform other operations
4180
such as deleting a file, you need some way to refer to the file. Nearly
4181
all files have names that are strings--even files which are actually
4182
devices such as tape drives or terminals. These strings are called
4183
"file names". You specify the file name to say which file you want to
4184
open or operate on.
4185
4186
This section describes the conventions for file names and how the
4187
operating system works with them.
4188
4189
* Menu:
4190
4191
* Directories:: Directories contain entries for files.
4192
* File Name Resolution:: A file name specifies how to look up a file.
4193
* File Name Errors:: Error conditions relating to file names.
4194
* File Name Portability:: File name portability and syntax issues.
4195
4196
4197
File: libc.info, Node: Directories, Next: File Name Resolution, Up: File Names
4198
4199
11.2.1 Directories
4200
------------------
4201
4202
In order to understand the syntax of file names, you need to understand
4203
how the file system is organized into a hierarchy of directories.
4204
4205
A "directory" is a file that contains information to associate other
4206
files with names; these associations are called "links" or "directory
4207
entries". Sometimes, people speak of "files in a directory", but in
4208
reality, a directory only contains pointers to files, not the files
4209
themselves.
4210
4211
The name of a file contained in a directory entry is called a "file
4212
name component". In general, a file name consists of a sequence of one
4213
or more such components, separated by the slash character (`/'). A
4214
file name which is just one component names a file with respect to its
4215
directory. A file name with multiple components names a directory, and
4216
then a file in that directory, and so on.
4217
4218
Some other documents, such as the POSIX standard, use the term
4219
"pathname" for what we call a file name, and either "filename" or
4220
"pathname component" for what this manual calls a file name component.
4221
We don't use this terminology because a "path" is something completely
4222
different (a list of directories to search), and we think that
4223
"pathname" used for something else will confuse users. We always use
4224
"file name" and "file name component" (or sometimes just "component",
4225
where the context is obvious) in GNU documentation. Some macros use
4226
the POSIX terminology in their names, such as `PATH_MAX'. These macros
4227
are defined by the POSIX standard, so we cannot change their names.
4228
4229
You can find more detailed information about operations on
4230
directories in *note File System Interface::.
4231
4232
4233
File: libc.info, Node: File Name Resolution, Next: File Name Errors, Prev: Directories, Up: File Names
4234
4235
11.2.2 File Name Resolution
4236
---------------------------
4237
4238
A file name consists of file name components separated by slash (`/')
4239
characters. On the systems that the GNU C library supports, multiple
4240
successive `/' characters are equivalent to a single `/' character.
4241
4242
The process of determining what file a file name refers to is called
4243
"file name resolution". This is performed by examining the components
4244
that make up a file name in left-to-right order, and locating each
4245
successive component in the directory named by the previous component.
4246
Of course, each of the files that are referenced as directories must
4247
actually exist, be directories instead of regular files, and have the
4248
appropriate permissions to be accessible by the process; otherwise the
4249
file name resolution fails.
4250
4251
If a file name begins with a `/', the first component in the file
4252
name is located in the "root directory" of the process (usually all
4253
processes on the system have the same root directory). Such a file name
4254
is called an "absolute file name".
4255
4256
Otherwise, the first component in the file name is located in the
4257
current working directory (*note Working Directory::). This kind of
4258
file name is called a "relative file name".
4259
4260
The file name components `.' ("dot") and `..' ("dot-dot") have
4261
special meanings. Every directory has entries for these file name
4262
components. The file name component `.' refers to the directory
4263
itself, while the file name component `..' refers to its "parent
4264
directory" (the directory that contains the link for the directory in
4265
question). As a special case, `..' in the root directory refers to the
4266
root directory itself, since it has no parent; thus `/..' is the same
4267
as `/'.
4268
4269
Here are some examples of file names:
4270
4271
`/a'
4272
The file named `a', in the root directory.
4273
4274
`/a/b'
4275
The file named `b', in the directory named `a' in the root
4276
directory.
4277
4278
`a'
4279
The file named `a', in the current working directory.
4280
4281
`/a/./b'
4282
This is the same as `/a/b'.
4283
4284
`./a'
4285
The file named `a', in the current working directory.
4286
4287
`../a'
4288
The file named `a', in the parent directory of the current working
4289
directory.
4290
4291
A file name that names a directory may optionally end in a `/'. You
4292
can specify a file name of `/' to refer to the root directory, but the
4293
empty string is not a meaningful file name. If you want to refer to
4294
the current working directory, use a file name of `.' or `./'.
4295
4296
Unlike some other operating systems, the GNU system doesn't have any
4297
built-in support for file types (or extensions) or file versions as part
4298
of its file name syntax. Many programs and utilities use conventions
4299
for file names--for example, files containing C source code usually
4300
have names suffixed with `.c'--but there is nothing in the file system
4301
itself that enforces this kind of convention.
4302
4303
4304
File: libc.info, Node: File Name Errors, Next: File Name Portability, Prev: File Name Resolution, Up: File Names
4305
4306
11.2.3 File Name Errors
4307
-----------------------
4308
4309
Functions that accept file name arguments usually detect these `errno'
4310
error conditions relating to the file name syntax or trouble finding
4311
the named file. These errors are referred to throughout this manual as
4312
the "usual file name errors".
4313
4314
`EACCES'
4315
The process does not have search permission for a directory
4316
component of the file name.
4317
4318
`ENAMETOOLONG'
4319
This error is used when either the total length of a file name is
4320
greater than `PATH_MAX', or when an individual file name component
4321
has a length greater than `NAME_MAX'. *Note Limits for Files::.
4322
4323
In the GNU system, there is no imposed limit on overall file name
4324
length, but some file systems may place limits on the length of a
4325
component.
4326
4327
`ENOENT'
4328
This error is reported when a file referenced as a directory
4329
component in the file name doesn't exist, or when a component is a
4330
symbolic link whose target file does not exist. *Note Symbolic
4331
Links::.
4332
4333
`ENOTDIR'
4334
A file that is referenced as a directory component in the file name
4335
exists, but it isn't a directory.
4336
4337
`ELOOP'
4338
Too many symbolic links were resolved while trying to look up the
4339
file name. The system has an arbitrary limit on the number of
4340
symbolic links that may be resolved in looking up a single file
4341
name, as a primitive way to detect loops. *Note Symbolic Links::.
4342
4343
4344
File: libc.info, Node: File Name Portability, Prev: File Name Errors, Up: File Names
4345
4346
11.2.4 Portability of File Names
4347
--------------------------------
4348
4349
The rules for the syntax of file names discussed in *note File Names::,
4350
are the rules normally used by the GNU system and by other POSIX
4351
systems. However, other operating systems may use other conventions.
4352
4353
There are two reasons why it can be important for you to be aware of
4354
file name portability issues:
4355
4356
* If your program makes assumptions about file name syntax, or
4357
contains embedded literal file name strings, it is more difficult
4358
to get it to run under other operating systems that use different
4359
syntax conventions.
4360
4361
* Even if you are not concerned about running your program on
4362
machines that run other operating systems, it may still be
4363
possible to access files that use different naming conventions.
4364
For example, you may be able to access file systems on another
4365
computer running a different operating system over a network, or
4366
read and write disks in formats used by other operating systems.
4367
4368
The ISO C standard says very little about file name syntax, only that
4369
file names are strings. In addition to varying restrictions on the
4370
length of file names and what characters can validly appear in a file
4371
name, different operating systems use different conventions and syntax
4372
for concepts such as structured directories and file types or
4373
extensions. Some concepts such as file versions might be supported in
4374
some operating systems and not by others.
4375
4376
The POSIX.1 standard allows implementations to put additional
4377
restrictions on file name syntax, concerning what characters are
4378
permitted in file names and on the length of file name and file name
4379
component strings. However, in the GNU system, you do not need to worry
4380
about these restrictions; any character except the null character is
4381
permitted in a file name string, and there are no limits on the length
4382
of file name strings.
4383
4384
4385
File: libc.info, Node: I/O on Streams, Next: Low-Level I/O, Prev: I/O Overview, Up: Top
4386
4387
12 Input/Output on Streams
4388
**************************
4389
4390
This chapter describes the functions for creating streams and performing
4391
input and output operations on them. As discussed in *note I/O
4392
Overview::, a stream is a fairly abstract, high-level concept
4393
representing a communications channel to a file, device, or process.
4394
4395
* Menu:
4396
4397
* Streams:: About the data type representing a stream.
4398
* Standard Streams:: Streams to the standard input and output
4399
devices are created for you.
4400
* Opening Streams:: How to create a stream to talk to a file.
4401
* Closing Streams:: Close a stream when you are finished with it.
4402
* Streams and Threads:: Issues with streams in threaded programs.
4403
* Streams and I18N:: Streams in internationalized applications.
4404
* Simple Output:: Unformatted output by characters and lines.
4405
* Character Input:: Unformatted input by characters and words.
4406
* Line Input:: Reading a line or a record from a stream.
4407
* Unreading:: Peeking ahead/pushing back input just read.
4408
* Block Input/Output:: Input and output operations on blocks of data.
4409
* Formatted Output:: `printf' and related functions.
4410
* Customizing Printf:: You can define new conversion specifiers for
4411
`printf' and friends.
4412
* Formatted Input:: `scanf' and related functions.
4413
* EOF and Errors:: How you can tell if an I/O error happens.
4414
* Error Recovery:: What you can do about errors.
4415
* Binary Streams:: Some systems distinguish between text files
4416
and binary files.
4417
* File Positioning:: About random-access streams.
4418
* Portable Positioning:: Random access on peculiar ISO C systems.
4419
* Stream Buffering:: How to control buffering of streams.
4420
* Other Kinds of Streams:: Streams that do not necessarily correspond
4421
to an open file.
4422
* Formatted Messages:: Print strictly formatted messages.
4423
4424
4425
File: libc.info, Node: Streams, Next: Standard Streams, Up: I/O on Streams
4426
4427
12.1 Streams
4428
============
4429
4430
For historical reasons, the type of the C data structure that represents
4431
a stream is called `FILE' rather than "stream". Since most of the
4432
library functions deal with objects of type `FILE *', sometimes the
4433
term "file pointer" is also used to mean "stream". This leads to
4434
unfortunate confusion over terminology in many books on C. This
4435
manual, however, is careful to use the terms "file" and "stream" only
4436
in the technical sense.
4437
4438
The `FILE' type is declared in the header file `stdio.h'.
4439
4440
-- Data Type: FILE
4441
This is the data type used to represent stream objects. A `FILE'
4442
object holds all of the internal state information about the
4443
connection to the associated file, including such things as the
4444
file position indicator and buffering information. Each stream
4445
also has error and end-of-file status indicators that can be
4446
tested with the `ferror' and `feof' functions; see *note EOF and
4447
Errors::.
4448
4449
`FILE' objects are allocated and managed internally by the
4450
input/output library functions. Don't try to create your own objects of
4451
type `FILE'; let the library do it. Your programs should deal only
4452
with pointers to these objects (that is, `FILE *' values) rather than
4453
the objects themselves.
4454
4455
4456
File: libc.info, Node: Standard Streams, Next: Opening Streams, Prev: Streams, Up: I/O on Streams
4457
4458
12.2 Standard Streams
4459
=====================
4460
4461
When the `main' function of your program is invoked, it already has
4462
three predefined streams open and available for use. These represent
4463
the "standard" input and output channels that have been established for
4464
the process.
4465
4466
These streams are declared in the header file `stdio.h'.
4467
4468
-- Variable: FILE * stdin
4469
The "standard input" stream, which is the normal source of input
4470
for the program.
4471
4472
-- Variable: FILE * stdout
4473
The "standard output" stream, which is used for normal output from
4474
the program.
4475
4476
-- Variable: FILE * stderr
4477
The "standard error" stream, which is used for error messages and
4478
diagnostics issued by the program.
4479
4480
In the GNU system, you can specify what files or processes
4481
correspond to these streams using the pipe and redirection facilities
4482
provided by the shell. (The primitives shells use to implement these
4483
facilities are described in *note File System Interface::.) Most other
4484
operating systems provide similar mechanisms, but the details of how to
4485
use them can vary.
4486
4487
In the GNU C library, `stdin', `stdout', and `stderr' are normal
4488
variables which you can set just like any others. For example, to
4489
redirect the standard output to a file, you could do:
4490
4491
fclose (stdout);
4492
stdout = fopen ("standard-output-file", "w");
4493
4494
Note however, that in other systems `stdin', `stdout', and `stderr'
4495
are macros that you cannot assign to in the normal way. But you can
4496
use `freopen' to get the effect of closing one and reopening it. *Note
4497
Opening Streams::.
4498
4499
The three streams `stdin', `stdout', and `stderr' are not unoriented
4500
at program start (*note Streams and I18N::).
4501
4502
4503
File: libc.info, Node: Opening Streams, Next: Closing Streams, Prev: Standard Streams, Up: I/O on Streams
4504
4505
12.3 Opening Streams
4506
====================
4507
4508
Opening a file with the `fopen' function creates a new stream and
4509
establishes a connection between the stream and a file. This may
4510
involve creating a new file.
4511
4512
Everything described in this section is declared in the header file
4513
`stdio.h'.
4514
4515
-- Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
4516
The `fopen' function opens a stream for I/O to the file FILENAME,
4517
and returns a pointer to the stream.
4518
4519
The OPENTYPE argument is a string that controls how the file is
4520
opened and specifies attributes of the resulting stream. It must
4521
begin with one of the following sequences of characters:
4522
4523
`r'
4524
Open an existing file for reading only.
4525
4526
`w'
4527
Open the file for writing only. If the file already exists,
4528
it is truncated to zero length. Otherwise a new file is
4529
created.
4530
4531
`a'
4532
Open a file for append access; that is, writing at the end of
4533
file only. If the file already exists, its initial contents
4534
are unchanged and output to the stream is appended to the end
4535
of the file. Otherwise, a new, empty file is created.
4536
4537
`r+'
4538
Open an existing file for both reading and writing. The
4539
initial contents of the file are unchanged and the initial
4540
file position is at the beginning of the file.
4541
4542
`w+'
4543
Open a file for both reading and writing. If the file
4544
already exists, it is truncated to zero length. Otherwise, a
4545
new file is created.
4546
4547
`a+'
4548
Open or create file for both reading and appending. If the
4549
file exists, its initial contents are unchanged. Otherwise,
4550
a new file is created. The initial file position for reading
4551
is at the beginning of the file, but output is always
4552
appended to the end of the file.
4553
4554
As you can see, `+' requests a stream that can do both input and
4555
output. The ISO standard says that when using such a stream, you
4556
must call `fflush' (*note Stream Buffering::) or a file positioning
4557
function such as `fseek' (*note File Positioning::) when switching
4558
from reading to writing or vice versa. Otherwise, internal buffers
4559
might not be emptied properly. The GNU C library does not have
4560
this limitation; you can do arbitrary reading and writing
4561
operations on a stream in whatever order.
4562
4563
Additional characters may appear after these to specify flags for
4564
the call. Always put the mode (`r', `w+', etc.) first; that is
4565
the only part you are guaranteed will be understood by all systems.
4566
4567
The GNU C library defines one additional character for use in
4568
OPENTYPE: the character `x' insists on creating a new file--if a
4569
file FILENAME already exists, `fopen' fails rather than opening
4570
it. If you use `x' you are guaranteed that you will not clobber
4571
an existing file. This is equivalent to the `O_EXCL' option to
4572
the `open' function (*note Opening and Closing Files::).
4573
4574
The character `b' in OPENTYPE has a standard meaning; it requests
4575
a binary stream rather than a text stream. But this makes no
4576
difference in POSIX systems (including the GNU system). If both
4577
`+' and `b' are specified, they can appear in either order. *Note
4578
Binary Streams::.
4579
4580
If the OPENTYPE string contains the sequence `,ccs=STRING' then
4581
STRING is taken as the name of a coded character set and `fopen'
4582
will mark the stream as wide-oriented which appropriate conversion
4583
functions in place to convert from and to the character set STRING
4584
is place. Any other stream is opened initially unoriented and the
4585
orientation is decided with the first file operation. If the
4586
first operation is a wide character operation, the stream is not
4587
only marked as wide-oriented, also the conversion functions to
4588
convert to the coded character set used for the current locale are
4589
loaded. This will not change anymore from this point on even if
4590
the locale selected for the `LC_CTYPE' category is changed.
4591
4592
Any other characters in OPENTYPE are simply ignored. They may be
4593
meaningful in other systems.
4594
4595
If the open fails, `fopen' returns a null pointer.
4596
4597
When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
4598
32 bit machine this function is in fact `fopen64' since the LFS
4599
interface replaces transparently the old interface.
4600
4601
You can have multiple streams (or file descriptors) pointing to the
4602
same file open at the same time. If you do only input, this works
4603
straightforwardly, but you must be careful if any output streams are
4604
included. *Note Stream/Descriptor Precautions::. This is equally true
4605
whether the streams are in one program (not usual) or in several
4606
programs (which can easily happen). It may be advantageous to use the
4607
file locking facilities to avoid simultaneous access. *Note File
4608
Locks::.
4609
4610
-- Function: FILE * fopen64 (const char *FILENAME, const char
4611
*OPENTYPE)
4612
This function is similar to `fopen' but the stream it returns a
4613
pointer for is opened using `open64'. Therefore this stream can be
4614
used even on files larger then 2^31 bytes on 32 bit machines.
4615
4616
Please note that the return type is still `FILE *'. There is no
4617
special `FILE' type for the LFS interface.
4618
4619
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
4620
bits machine this function is available under the name `fopen' and
4621
so transparently replaces the old interface.
4622
4623
-- Macro: int FOPEN_MAX
4624
The value of this macro is an integer constant expression that
4625
represents the minimum number of streams that the implementation
4626
guarantees can be open simultaneously. You might be able to open
4627
more than this many streams, but that is not guaranteed. The
4628
value of this constant is at least eight, which includes the three
4629
standard streams `stdin', `stdout', and `stderr'. In POSIX.1
4630
systems this value is determined by the `OPEN_MAX' parameter;
4631
*note General Limits::. In BSD and GNU, it is controlled by the
4632
`RLIMIT_NOFILE' resource limit; *note Limits on Resources::.
4633
4634
-- Function: FILE * freopen (const char *FILENAME, const char
4635
*OPENTYPE, FILE *STREAM)
4636
This function is like a combination of `fclose' and `fopen'. It
4637
first closes the stream referred to by STREAM, ignoring any errors
4638
that are detected in the process. (Because errors are ignored,
4639
you should not use `freopen' on an output stream if you have
4640
actually done any output using the stream.) Then the file named by
4641
FILENAME is opened with mode OPENTYPE as for `fopen', and
4642
associated with the same stream object STREAM.
4643
4644
If the operation fails, a null pointer is returned; otherwise,
4645
`freopen' returns STREAM.
4646
4647
`freopen' has traditionally been used to connect a standard stream
4648
such as `stdin' with a file of your own choice. This is useful in
4649
programs in which use of a standard stream for certain purposes is
4650
hard-coded. In the GNU C library, you can simply close the
4651
standard streams and open new ones with `fopen'. But other
4652
systems lack this ability, so using `freopen' is more portable.
4653
4654
When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
4655
32 bit machine this function is in fact `freopen64' since the LFS
4656
interface replaces transparently the old interface.
4657
4658
-- Function: FILE * freopen64 (const char *FILENAME, const char
4659
*OPENTYPE, FILE *STREAM)
4660
This function is similar to `freopen'. The only difference is that
4661
on 32 bit machine the stream returned is able to read beyond the
4662
2^31 bytes limits imposed by the normal interface. It should be
4663
noted that the stream pointed to by STREAM need not be opened
4664
using `fopen64' or `freopen64' since its mode is not important for
4665
this function.
4666
4667
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
4668
bits machine this function is available under the name `freopen'
4669
and so transparently replaces the old interface.
4670
4671
In some situations it is useful to know whether a given stream is
4672
available for reading or writing. This information is normally not
4673
available and would have to be remembered separately. Solaris
4674
introduced a few functions to get this information from the stream
4675
descriptor and these functions are also available in the GNU C library.
4676
4677
-- Function: int __freadable (FILE *STREAM)
4678
The `__freadable' function determines whether the stream STREAM
4679
was opened to allow reading. In this case the return value is
4680
nonzero. For write-only streams the function returns zero.
4681
4682
This function is declared in `stdio_ext.h'.
4683
4684
-- Function: int __fwritable (FILE *STREAM)
4685
The `__fwritable' function determines whether the stream STREAM
4686
was opened to allow writing. In this case the return value is
4687
nonzero. For read-only streams the function returns zero.
4688
4689
This function is declared in `stdio_ext.h'.
4690
4691
For slightly different kind of problems there are two more functions.
4692
They provide even finer-grained information.
4693
4694
-- Function: int __freading (FILE *STREAM)
4695
The `__freading' function determines whether the stream STREAM was
4696
last read from or whether it is opened read-only. In this case
4697
the return value is nonzero, otherwise it is zero. Determining
4698
whether a stream opened for reading and writing was last used for
4699
writing allows to draw conclusions about the content about the
4700
buffer, among other things.
4701
4702
This function is declared in `stdio_ext.h'.
4703
4704
-- Function: int __fwriting (FILE *STREAM)
4705
The `__fwriting' function determines whether the stream STREAM was
4706
last written to or whether it is opened write-only. In this case
4707
the return value is nonzero, otherwise it is zero.
4708
4709
This function is declared in `stdio_ext.h'.
4710
4711
4712
File: libc.info, Node: Closing Streams, Next: Streams and Threads, Prev: Opening Streams, Up: I/O on Streams
4713
4714
12.4 Closing Streams
4715
====================
4716
4717
When a stream is closed with `fclose', the connection between the
4718
stream and the file is canceled. After you have closed a stream, you
4719
cannot perform any additional operations on it.
4720
4721
-- Function: int fclose (FILE *STREAM)
4722
This function causes STREAM to be closed and the connection to the
4723
corresponding file to be broken. Any buffered output is written
4724
and any buffered input is discarded. The `fclose' function returns
4725
a value of `0' if the file was closed successfully, and `EOF' if
4726
an error was detected.
4727
4728
It is important to check for errors when you call `fclose' to close
4729
an output stream, because real, everyday errors can be detected at
4730
this time. For example, when `fclose' writes the remaining
4731
buffered output, it might get an error because the disk is full.
4732
Even if you know the buffer is empty, errors can still occur when
4733
closing a file if you are using NFS.
4734
4735
The function `fclose' is declared in `stdio.h'.
4736
4737
To close all streams currently available the GNU C Library provides
4738
another function.
4739
4740
-- Function: int fcloseall (void)
4741
This function causes all open streams of the process to be closed
4742
and the connection to corresponding files to be broken. All
4743
buffered data is written and any buffered input is discarded. The
4744
`fcloseall' function returns a value of `0' if all the files were
4745
closed successfully, and `EOF' if an error was detected.
4746
4747
This function should be used only in special situations, e.g.,
4748
when an error occurred and the program must be aborted. Normally
4749
each single stream should be closed separately so that problems
4750
with individual streams can be identified. It is also problematic
4751
since the standard streams (*note Standard Streams::) will also be
4752
closed.
4753
4754
The function `fcloseall' is declared in `stdio.h'.
4755
4756
If the `main' function to your program returns, or if you call the
4757
`exit' function (*note Normal Termination::), all open streams are
4758
automatically closed properly. If your program terminates in any other
4759
manner, such as by calling the `abort' function (*note Aborting a
4760
Program::) or from a fatal signal (*note Signal Handling::), open
4761
streams might not be closed properly. Buffered output might not be
4762
flushed and files may be incomplete. For more information on buffering
4763
of streams, see *note Stream Buffering::.
4764
4765
4766
File: libc.info, Node: Streams and Threads, Next: Streams and I18N, Prev: Closing Streams, Up: I/O on Streams
4767
4768
12.5 Streams and Threads
4769
========================
4770
4771
Streams can be used in multi-threaded applications in the same way they
4772
are used in single-threaded applications. But the programmer must be
4773
aware of the possible complications. It is important to know about
4774
these also if the program one writes never use threads since the design
4775
and implementation of many stream functions is heavily influenced by the
4776
requirements added by multi-threaded programming.
4777
4778
The POSIX standard requires that by default the stream operations are
4779
atomic. I.e., issuing two stream operations for the same stream in two
4780
threads at the same time will cause the operations to be executed as if
4781
they were issued sequentially. The buffer operations performed while
4782
reading or writing are protected from other uses of the same stream. To
4783
do this each stream has an internal lock object which has to be
4784
(implicitly) acquired before any work can be done.
4785
4786
But there are situations where this is not enough and there are also
4787
situations where this is not wanted. The implicit locking is not enough
4788
if the program requires more than one stream function call to happen
4789
atomically. One example would be if an output line a program wants to
4790
generate is created by several function calls. The functions by
4791
themselves would ensure only atomicity of their own operation, but not
4792
atomicity over all the function calls. For this it is necessary to
4793
perform the stream locking in the application code.
4794
4795
-- Function: void flockfile (FILE *STREAM)
4796
The `flockfile' function acquires the internal locking object
4797
associated with the stream STREAM. This ensures that no other
4798
thread can explicitly through `flockfile'/`ftrylockfile' or
4799
implicit through a call of a stream function lock the stream. The
4800
thread will block until the lock is acquired. An explicit call to
4801
`funlockfile' has to be used to release the lock.
4802
4803
-- Function: int ftrylockfile (FILE *STREAM)
4804
The `ftrylockfile' function tries to acquire the internal locking
4805
object associated with the stream STREAM just like `flockfile'.
4806
But unlike `flockfile' this function does not block if the lock is
4807
not available. `ftrylockfile' returns zero if the lock was
4808
successfully acquired. Otherwise the stream is locked by another
4809
thread.
4810
4811
-- Function: void funlockfile (FILE *STREAM)
4812
The `funlockfile' function releases the internal locking object of
4813
the stream STREAM. The stream must have been locked before by a
4814
call to `flockfile' or a successful call of `ftrylockfile'. The
4815
implicit locking performed by the stream operations do not count.
4816
The `funlockfile' function does not return an error status and the
4817
behavior of a call for a stream which is not locked by the current
4818
thread is undefined.
4819
4820
The following example shows how the functions above can be used to
4821
generate an output line atomically even in multi-threaded applications
4822
(yes, the same job could be done with one `fprintf' call but it is
4823
sometimes not possible):
4824
4825
FILE *fp;
4826
{
4827
...
4828
flockfile (fp);
4829
fputs ("This is test number ", fp);
4830
fprintf (fp, "%d\n", test);
4831
funlockfile (fp)
4832
}
4833
4834
Without the explicit locking it would be possible for another thread
4835
to use the stream FP after the `fputs' call return and before `fprintf'
4836
was called with the result that the number does not follow the word
4837
`number'.
4838
4839
From this description it might already be clear that the locking
4840
objects in streams are no simple mutexes. Since locking the same
4841
stream twice in the same thread is allowed the locking objects must be
4842
equivalent to recursive mutexes. These mutexes keep track of the owner
4843
and the number of times the lock is acquired. The same number of
4844
`funlockfile' calls by the same threads is necessary to unlock the
4845
stream completely. For instance:
4846
4847
void
4848
foo (FILE *fp)
4849
{
4850
ftrylockfile (fp);
4851
fputs ("in foo\n", fp);
4852
/* This is very wrong!!! */
4853
funlockfile (fp);
4854
}
4855
4856
It is important here that the `funlockfile' function is only called
4857
if the `ftrylockfile' function succeeded in locking the stream. It is
4858
therefore always wrong to ignore the result of `ftrylockfile'. And it
4859
makes no sense since otherwise one would use `flockfile'. The result
4860
of code like that above is that either `funlockfile' tries to free a
4861
stream that hasn't been locked by the current thread or it frees the
4862
stream prematurely. The code should look like this:
4863
4864
void
4865
foo (FILE *fp)
4866
{
4867
if (ftrylockfile (fp) == 0)
4868
{
4869
fputs ("in foo\n", fp);
4870
funlockfile (fp);
4871
}
4872
}
4873
4874
Now that we covered why it is necessary to have these locking it is
4875
necessary to talk about situations when locking is unwanted and what can
4876
be done. The locking operations (explicit or implicit) don't come for
4877
free. Even if a lock is not taken the cost is not zero. The operations
4878
which have to be performed require memory operations that are safe in
4879
multi-processor environments. With the many local caches involved in
4880
such systems this is quite costly. So it is best to avoid the locking
4881
completely if it is not needed - because the code in question is never
4882
used in a context where two or more threads may use a stream at a time.
4883
This can be determined most of the time for application code; for
4884
library code which can be used in many contexts one should default to be
4885
conservative and use locking.
4886
4887
There are two basic mechanisms to avoid locking. The first is to use
4888
the `_unlocked' variants of the stream operations. The POSIX standard
4889
defines quite a few of those and the GNU library adds a few more.
4890
These variants of the functions behave just like the functions with the
4891
name without the suffix except that they do not lock the stream. Using
4892
these functions is very desirable since they are potentially much
4893
faster. This is not only because the locking operation itself is
4894
avoided. More importantly, functions like `putc' and `getc' are very
4895
simple and traditionally (before the introduction of threads) were
4896
implemented as macros which are very fast if the buffer is not empty.
4897
With the addition of locking requirements these functions are no longer
4898
implemented as macros since they would would expand to too much code.
4899
But these macros are still available with the same functionality under
4900
the new names `putc_unlocked' and `getc_unlocked'. This possibly huge
4901
difference of speed also suggests the use of the `_unlocked' functions
4902
even if locking is required. The difference is that the locking then
4903
has to be performed in the program:
4904
4905
void
4906
foo (FILE *fp, char *buf)
4907
{
4908
flockfile (fp);
4909
while (*buf != '/')
4910
putc_unlocked (*buf++, fp);
4911
funlockfile (fp);
4912
}
4913
4914
If in this example the `putc' function would be used and the
4915
explicit locking would be missing the `putc' function would have to
4916
acquire the lock in every call, potentially many times depending on when
4917
the loop terminates. Writing it the way illustrated above allows the
4918
`putc_unlocked' macro to be used which means no locking and direct
4919
manipulation of the buffer of the stream.
4920
4921
A second way to avoid locking is by using a non-standard function
4922
which was introduced in Solaris and is available in the GNU C library
4923
as well.
4924
4925
-- Function: int __fsetlocking (FILE *STREAM, int TYPE)
4926
The `__fsetlocking' function can be used to select whether the
4927
stream operations will implicitly acquire the locking object of the
4928
stream STREAM. By default this is done but it can be disabled and
4929
reinstated using this function. There are three values defined
4930
for the TYPE parameter.
4931
4932
`FSETLOCKING_INTERNAL'
4933
The stream `stream' will from now on use the default internal
4934
locking. Every stream operation with exception of the
4935
`_unlocked' variants will implicitly lock the stream.
4936
4937
`FSETLOCKING_BYCALLER'
4938
After the `__fsetlocking' function returns the user is
4939
responsible for locking the stream. None of the stream
4940
operations will implicitly do this anymore until the state is
4941
set back to `FSETLOCKING_INTERNAL'.
4942
4943
`FSETLOCKING_QUERY'
4944
`__fsetlocking' only queries the current locking state of the
4945
stream. The return value will be `FSETLOCKING_INTERNAL' or
4946
`FSETLOCKING_BYCALLER' depending on the state.
4947
4948
The return value of `__fsetlocking' is either
4949
`FSETLOCKING_INTERNAL' or `FSETLOCKING_BYCALLER' depending on the
4950
state of the stream before the call.
4951
4952
This function and the values for the TYPE parameter are declared
4953
in `stdio_ext.h'.
4954
4955
This function is especially useful when program code has to be used
4956
which is written without knowledge about the `_unlocked' functions (or
4957
if the programmer was too lazy to use them).
4958
4959
4960
File: libc.info, Node: Streams and I18N, Next: Simple Output, Prev: Streams and Threads, Up: I/O on Streams
4961
4962
12.6 Streams in Internationalized Applications
4963
==============================================
4964
4965
ISO C90 introduced the new type `wchar_t' to allow handling larger
4966
character sets. What was missing was a possibility to output strings
4967
of `wchar_t' directly. One had to convert them into multibyte strings
4968
using `mbstowcs' (there was no `mbsrtowcs' yet) and then use the normal
4969
stream functions. While this is doable it is very cumbersome since
4970
performing the conversions is not trivial and greatly increases program
4971
complexity and size.
4972
4973
The Unix standard early on (I think in XPG4.2) introduced two
4974
additional format specifiers for the `printf' and `scanf' families of
4975
functions. Printing and reading of single wide characters was made
4976
possible using the `%C' specifier and wide character strings can be
4977
handled with `%S'. These modifiers behave just like `%c' and `%s' only
4978
that they expect the corresponding argument to have the wide character
4979
type and that the wide character and string are transformed into/from
4980
multibyte strings before being used.
4981
4982
This was a beginning but it is still not good enough. Not always is
4983
it desirable to use `printf' and `scanf'. The other, smaller and
4984
faster functions cannot handle wide characters. Second, it is not
4985
possible to have a format string for `printf' and `scanf' consisting of
4986
wide characters. The result is that format strings would have to be
4987
generated if they have to contain non-basic characters.
4988
4989
In the Amendment 1 to ISO C90 a whole new set of functions was added
4990
to solve the problem. Most of the stream functions got a counterpart
4991
which take a wide character or wide character string instead of a
4992
character or string respectively. The new functions operate on the
4993
same streams (like `stdout'). This is different from the model of the
4994
C++ runtime library where separate streams for wide and normal I/O are
4995
used.
4996
4997
Being able to use the same stream for wide and normal operations
4998
comes with a restriction: a stream can be used either for wide
4999
operations or for normal operations. Once it is decided there is no
5000
way back. Only a call to `freopen' or `freopen64' can reset the
5001
"orientation". The orientation can be decided in three ways:
5002
5003
* If any of the normal character functions is used (this includes the
5004
`fread' and `fwrite' functions) the stream is marked as not wide
5005
oriented.
5006
5007
* If any of the wide character functions is used the stream is
5008
marked as wide oriented.
5009
5010
* The `fwide' function can be used to set the orientation either way.
5011
5012
It is important to never mix the use of wide and not wide operations
5013
on a stream. There are no diagnostics issued. The application behavior
5014
will simply be strange or the application will simply crash. The
5015
`fwide' function can help avoiding this.
5016
5017
-- Function: int fwide (FILE *STREAM, int MODE)
5018
The `fwide' function can be used to set and query the state of the
5019
orientation of the stream STREAM. If the MODE parameter has a
5020
positive value the streams get wide oriented, for negative values
5021
narrow oriented. It is not possible to overwrite previous
5022
orientations with `fwide'. I.e., if the stream STREAM was already
5023
oriented before the call nothing is done.
5024
5025
If MODE is zero the current orientation state is queried and
5026
nothing is changed.
5027
5028
The `fwide' function returns a negative value, zero, or a positive
5029
value if the stream is narrow, not at all, or wide oriented
5030
respectively.
5031
5032
This function was introduced in Amendment 1 to ISO C90 and is
5033
declared in `wchar.h'.
5034
5035
It is generally a good idea to orient a stream as early as possible.
5036
This can prevent surprise especially for the standard streams `stdin',
5037
`stdout', and `stderr'. If some library function in some situations
5038
uses one of these streams and this use orients the stream in a
5039
different way the rest of the application expects it one might end up
5040
with hard to reproduce errors. Remember that no errors are signal if
5041
the streams are used incorrectly. Leaving a stream unoriented after
5042
creation is normally only necessary for library functions which create
5043
streams which can be used in different contexts.
5044
5045
When writing code which uses streams and which can be used in
5046
different contexts it is important to query the orientation of the
5047
stream before using it (unless the rules of the library interface
5048
demand a specific orientation). The following little, silly function
5049
illustrates this.
5050
5051
void
5052
print_f (FILE *fp)
5053
{
5054
if (fwide (fp, 0) > 0)
5055
/* Positive return value means wide orientation. */
5056
fputwc (L'f', fp);
5057
else
5058
fputc ('f', fp);
5059
}
5060
5061
Note that in this case the function `print_f' decides about the
5062
orientation of the stream if it was unoriented before (will not happen
5063
if the advise above is followed).
5064
5065
The encoding used for the `wchar_t' values is unspecified and the
5066
user must not make any assumptions about it. For I/O of `wchar_t'
5067
values this means that it is impossible to write these values directly
5068
to the stream. This is not what follows from the ISO C locale model
5069
either. What happens instead is that the bytes read from or written to
5070
the underlying media are first converted into the internal encoding
5071
chosen by the implementation for `wchar_t'. The external encoding is
5072
determined by the `LC_CTYPE' category of the current locale or by the
5073
`ccs' part of the mode specification given to `fopen', `fopen64',
5074
`freopen', or `freopen64'. How and when the conversion happens is
5075
unspecified and it happens invisible to the user.
5076
5077
Since a stream is created in the unoriented state it has at that
5078
point no conversion associated with it. The conversion which will be
5079
used is determined by the `LC_CTYPE' category selected at the time the
5080
stream is oriented. If the locales are changed at the runtime this
5081
might produce surprising results unless one pays attention. This is
5082
just another good reason to orient the stream explicitly as soon as
5083
possible, perhaps with a call to `fwide'.
5084
5085
5086
File: libc.info, Node: Simple Output, Next: Character Input, Prev: Streams and I18N, Up: I/O on Streams
5087
5088
12.7 Simple Output by Characters or Lines
5089
=========================================
5090
5091
This section describes functions for performing character- and
5092
line-oriented output.
5093
5094
These narrow streams functions are declared in the header file
5095
`stdio.h' and the wide stream functions in `wchar.h'.
5096
5097
-- Function: int fputc (int C, FILE *STREAM)
5098
The `fputc' function converts the character C to type `unsigned
5099
char', and writes it to the stream STREAM. `EOF' is returned if a
5100
write error occurs; otherwise the character C is returned.
5101
5102
-- Function: wint_t fputwc (wchar_t WC, FILE *STREAM)
5103
The `fputwc' function writes the wide character WC to the stream
5104
STREAM. `WEOF' is returned if a write error occurs; otherwise the
5105
character WC is returned.
5106
5107
-- Function: int fputc_unlocked (int C, FILE *STREAM)
5108
The `fputc_unlocked' function is equivalent to the `fputc'
5109
function except that it does not implicitly lock the stream.
5110
5111
-- Function: wint_t fputwc_unlocked (wint_t WC, FILE *STREAM)
5112
The `fputwc_unlocked' function is equivalent to the `fputwc'
5113
function except that it does not implicitly lock the stream.
5114
5115
This function is a GNU extension.
5116
5117
-- Function: int putc (int C, FILE *STREAM)
5118
This is just like `fputc', except that most systems implement it as
5119
a macro, making it faster. One consequence is that it may
5120
evaluate the STREAM argument more than once, which is an exception
5121
to the general rule for macros. `putc' is usually the best
5122
function to use for writing a single character.
5123
5124
-- Function: wint_t putwc (wchar_t WC, FILE *STREAM)
5125
This is just like `fputwc', except that it can be implement as a
5126
macro, making it faster. One consequence is that it may evaluate
5127
the STREAM argument more than once, which is an exception to the
5128
general rule for macros. `putwc' is usually the best function to
5129
use for writing a single wide character.
5130
5131
-- Function: int putc_unlocked (int C, FILE *STREAM)
5132
The `putc_unlocked' function is equivalent to the `putc' function
5133
except that it does not implicitly lock the stream.
5134
5135
-- Function: wint_t putwc_unlocked (wchar_t WC, FILE *STREAM)
5136
The `putwc_unlocked' function is equivalent to the `putwc'
5137
function except that it does not implicitly lock the stream.
5138
5139
This function is a GNU extension.
5140
5141
-- Function: int putchar (int C)
5142
The `putchar' function is equivalent to `putc' with `stdout' as
5143
the value of the STREAM argument.
5144
5145
-- Function: wint_t putwchar (wchar_t WC)
5146
The `putwchar' function is equivalent to `putwc' with `stdout' as
5147
the value of the STREAM argument.
5148
5149
-- Function: int putchar_unlocked (int C)
5150
The `putchar_unlocked' function is equivalent to the `putchar'
5151
function except that it does not implicitly lock the stream.
5152
5153
-- Function: wint_t putwchar_unlocked (wchar_t WC)
5154
The `putwchar_unlocked' function is equivalent to the `putwchar'
5155
function except that it does not implicitly lock the stream.
5156
5157
This function is a GNU extension.
5158
5159
-- Function: int fputs (const char *S, FILE *STREAM)
5160
The function `fputs' writes the string S to the stream STREAM.
5161
The terminating null character is not written. This function does
5162
_not_ add a newline character, either. It outputs only the
5163
characters in the string.
5164
5165
This function returns `EOF' if a write error occurs, and otherwise
5166
a non-negative value.
5167
5168
For example:
5169
5170
fputs ("Are ", stdout);
5171
fputs ("you ", stdout);
5172
fputs ("hungry?\n", stdout);
5173
5174
outputs the text `Are you hungry?' followed by a newline.
5175
5176
-- Function: int fputws (const wchar_t *WS, FILE *STREAM)
5177
The function `fputws' writes the wide character string WS to the
5178
stream STREAM. The terminating null character is not written.
5179
This function does _not_ add a newline character, either. It
5180
outputs only the characters in the string.
5181
5182
This function returns `WEOF' if a write error occurs, and otherwise
5183
a non-negative value.
5184
5185
-- Function: int fputs_unlocked (const char *S, FILE *STREAM)
5186
The `fputs_unlocked' function is equivalent to the `fputs'
5187
function except that it does not implicitly lock the stream.
5188
5189
This function is a GNU extension.
5190
5191
-- Function: int fputws_unlocked (const wchar_t *WS, FILE *STREAM)
5192
The `fputws_unlocked' function is equivalent to the `fputws'
5193
function except that it does not implicitly lock the stream.
5194
5195
This function is a GNU extension.
5196
5197
-- Function: int puts (const char *S)
5198
The `puts' function writes the string S to the stream `stdout'
5199
followed by a newline. The terminating null character of the
5200
string is not written. (Note that `fputs' does _not_ write a
5201
newline as this function does.)
5202
5203
`puts' is the most convenient function for printing simple
5204
messages. For example:
5205
5206
puts ("This is a message.");
5207
5208
outputs the text `This is a message.' followed by a newline.
5209
5210
-- Function: int putw (int W, FILE *STREAM)
5211
This function writes the word W (that is, an `int') to STREAM. It
5212
is provided for compatibility with SVID, but we recommend you use
5213
`fwrite' instead (*note Block Input/Output::).
5214
5215
5216
File: libc.info, Node: Character Input, Next: Line Input, Prev: Simple Output, Up: I/O on Streams
5217
5218
12.8 Character Input
5219
====================
5220
5221
This section describes functions for performing character-oriented
5222
input. These narrow streams functions are declared in the header file
5223
`stdio.h' and the wide character functions are declared in `wchar.h'.
5224
5225
These functions return an `int' or `wint_t' value (for narrow and
5226
wide stream functions respectively) that is either a character of
5227
input, or the special value `EOF'/`WEOF' (usually -1). For the narrow
5228
stream functions it is important to store the result of these functions
5229
in a variable of type `int' instead of `char', even when you plan to
5230
use it only as a character. Storing `EOF' in a `char' variable
5231
truncates its value to the size of a character, so that it is no longer
5232
distinguishable from the valid character `(char) -1'. So always use an
5233
`int' for the result of `getc' and friends, and check for `EOF' after
5234
the call; once you've verified that the result is not `EOF', you can be
5235
sure that it will fit in a `char' variable without loss of information.
5236
5237
-- Function: int fgetc (FILE *STREAM)
5238
This function reads the next character as an `unsigned char' from
5239
the stream STREAM and returns its value, converted to an `int'.
5240
If an end-of-file condition or read error occurs, `EOF' is
5241
returned instead.
5242
5243
-- Function: wint_t fgetwc (FILE *STREAM)
5244
This function reads the next wide character from the stream STREAM
5245
and returns its value. If an end-of-file condition or read error
5246
occurs, `WEOF' is returned instead.
5247
5248
-- Function: int fgetc_unlocked (FILE *STREAM)
5249
The `fgetc_unlocked' function is equivalent to the `fgetc'
5250
function except that it does not implicitly lock the stream.
5251
5252
-- Function: wint_t fgetwc_unlocked (FILE *STREAM)
5253
The `fgetwc_unlocked' function is equivalent to the `fgetwc'
5254
function except that it does not implicitly lock the stream.
5255
5256
This function is a GNU extension.
5257
5258
-- Function: int getc (FILE *STREAM)
5259
This is just like `fgetc', except that it is permissible (and
5260
typical) for it to be implemented as a macro that evaluates the
5261
STREAM argument more than once. `getc' is often highly optimized,
5262
so it is usually the best function to use to read a single
5263
character.
5264
5265
-- Function: wint_t getwc (FILE *STREAM)
5266
This is just like `fgetwc', except that it is permissible for it to
5267
be implemented as a macro that evaluates the STREAM argument more
5268
than once. `getwc' can be highly optimized, so it is usually the
5269
best function to use to read a single wide character.
5270
5271
-- Function: int getc_unlocked (FILE *STREAM)
5272
The `getc_unlocked' function is equivalent to the `getc' function
5273
except that it does not implicitly lock the stream.
5274
5275
-- Function: wint_t getwc_unlocked (FILE *STREAM)
5276
The `getwc_unlocked' function is equivalent to the `getwc'
5277
function except that it does not implicitly lock the stream.
5278
5279
This function is a GNU extension.
5280
5281
-- Function: int getchar (void)
5282
The `getchar' function is equivalent to `getc' with `stdin' as the
5283
value of the STREAM argument.
5284
5285
-- Function: wint_t getwchar (void)
5286
The `getwchar' function is equivalent to `getwc' with `stdin' as
5287
the value of the STREAM argument.
5288
5289
-- Function: int getchar_unlocked (void)
5290
The `getchar_unlocked' function is equivalent to the `getchar'
5291
function except that it does not implicitly lock the stream.
5292
5293
-- Function: wint_t getwchar_unlocked (void)
5294
The `getwchar_unlocked' function is equivalent to the `getwchar'
5295
function except that it does not implicitly lock the stream.
5296
5297
This function is a GNU extension.
5298
5299
Here is an example of a function that does input using `fgetc'. It
5300
would work just as well using `getc' instead, or using `getchar ()'
5301
instead of `fgetc (stdin)'. The code would also work the same for the
5302
wide character stream functions.
5303
5304
int
5305
y_or_n_p (const char *question)
5306
{
5307
fputs (question, stdout);
5308
while (1)
5309
{
5310
int c, answer;
5311
/* Write a space to separate answer from question. */
5312
fputc (' ', stdout);
5313
/* Read the first character of the line.
5314
This should be the answer character, but might not be. */
5315
c = tolower (fgetc (stdin));
5316
answer = c;
5317
/* Discard rest of input line. */
5318
while (c != '\n' && c != EOF)
5319
c = fgetc (stdin);
5320
/* Obey the answer if it was valid. */
5321
if (answer == 'y')
5322
return 1;
5323
if (answer == 'n')
5324
return 0;
5325
/* Answer was invalid: ask for valid answer. */
5326
fputs ("Please answer y or n:", stdout);
5327
}
5328
}
5329
5330
-- Function: int getw (FILE *STREAM)
5331
This function reads a word (that is, an `int') from STREAM. It's
5332
provided for compatibility with SVID. We recommend you use
5333
`fread' instead (*note Block Input/Output::). Unlike `getc', any
5334
`int' value could be a valid result. `getw' returns `EOF' when it
5335
encounters end-of-file or an error, but there is no way to
5336
distinguish this from an input word with value -1.
5337
5338
5339
File: libc.info, Node: Line Input, Next: Unreading, Prev: Character Input, Up: I/O on Streams
5340
5341
12.9 Line-Oriented Input
5342
========================
5343
5344
Since many programs interpret input on the basis of lines, it is
5345
convenient to have functions to read a line of text from a stream.
5346
5347
Standard C has functions to do this, but they aren't very safe: null
5348
characters and even (for `gets') long lines can confuse them. So the
5349
GNU library provides the nonstandard `getline' function that makes it
5350
easy to read lines reliably.
5351
5352
Another GNU extension, `getdelim', generalizes `getline'. It reads
5353
a delimited record, defined as everything through the next occurrence
5354
of a specified delimiter character.
5355
5356
All these functions are declared in `stdio.h'.
5357
5358
-- Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
5359
This function reads an entire line from STREAM, storing the text
5360
(including the newline and a terminating null character) in a
5361
buffer and storing the buffer address in `*LINEPTR'.
5362
5363
Before calling `getline', you should place in `*LINEPTR' the
5364
address of a buffer `*N' bytes long, allocated with `malloc'. If
5365
this buffer is long enough to hold the line, `getline' stores the
5366
line in this buffer. Otherwise, `getline' makes the buffer bigger
5367
using `realloc', storing the new buffer address back in `*LINEPTR'
5368
and the increased size back in `*N'. *Note Unconstrained
5369
Allocation::.
5370
5371
If you set `*LINEPTR' to a null pointer, and `*N' to zero, before
5372
the call, then `getline' allocates the initial buffer for you by
5373
calling `malloc'.
5374
5375
In either case, when `getline' returns, `*LINEPTR' is a `char *'
5376
which points to the text of the line.
5377
5378
When `getline' is successful, it returns the number of characters
5379
read (including the newline, but not including the terminating
5380
null). This value enables you to distinguish null characters that
5381
are part of the line from the null character inserted as a
5382
terminator.
5383
5384
This function is a GNU extension, but it is the recommended way to
5385
read lines from a stream. The alternative standard functions are
5386
unreliable.
5387
5388
If an error occurs or end of file is reached without any bytes
5389
read, `getline' returns `-1'.
5390
5391
-- Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
5392
DELIMITER, FILE *STREAM)
5393
This function is like `getline' except that the character which
5394
tells it to stop reading is not necessarily newline. The argument
5395
DELIMITER specifies the delimiter character; `getdelim' keeps
5396
reading until it sees that character (or end of file).
5397
5398
The text is stored in LINEPTR, including the delimiter character
5399
and a terminating null. Like `getline', `getdelim' makes LINEPTR
5400
bigger if it isn't big enough.
5401
5402
`getline' is in fact implemented in terms of `getdelim', just like
5403
this:
5404
5405
ssize_t
5406
getline (char **lineptr, size_t *n, FILE *stream)
5407
{
5408
return getdelim (lineptr, n, '\n', stream);
5409
}
5410
5411
-- Function: char * fgets (char *S, int COUNT, FILE *STREAM)
5412
The `fgets' function reads characters from the stream STREAM up to
5413
and including a newline character and stores them in the string S,
5414
adding a null character to mark the end of the string. You must
5415
supply COUNT characters worth of space in S, but the number of
5416
characters read is at most COUNT - 1. The extra character space
5417
is used to hold the null character at the end of the string.
5418
5419
If the system is already at end of file when you call `fgets', then
5420
the contents of the array S are unchanged and a null pointer is
5421
returned. A null pointer is also returned if a read error occurs.
5422
Otherwise, the return value is the pointer S.
5423
5424
*Warning:* If the input data has a null character, you can't tell.
5425
So don't use `fgets' unless you know the data cannot contain a
5426
null. Don't use it to read files edited by the user because, if
5427
the user inserts a null character, you should either handle it
5428
properly or print a clear error message. We recommend using
5429
`getline' instead of `fgets'.
5430
5431
-- Function: wchar_t * fgetws (wchar_t *WS, int COUNT, FILE *STREAM)
5432
The `fgetws' function reads wide characters from the stream STREAM
5433
up to and including a newline character and stores them in the
5434
string WS, adding a null wide character to mark the end of the
5435
string. You must supply COUNT wide characters worth of space in
5436
WS, but the number of characters read is at most COUNT - 1. The
5437
extra character space is used to hold the null wide character at
5438
the end of the string.
5439
5440
If the system is already at end of file when you call `fgetws',
5441
then the contents of the array WS are unchanged and a null pointer
5442
is returned. A null pointer is also returned if a read error
5443
occurs. Otherwise, the return value is the pointer WS.
5444
5445
*Warning:* If the input data has a null wide character (which are
5446
null bytes in the input stream), you can't tell. So don't use
5447
`fgetws' unless you know the data cannot contain a null. Don't use
5448
it to read files edited by the user because, if the user inserts a
5449
null character, you should either handle it properly or print a
5450
clear error message.
5451
5452
-- Function: char * fgets_unlocked (char *S, int COUNT, FILE *STREAM)
5453
The `fgets_unlocked' function is equivalent to the `fgets'
5454
function except that it does not implicitly lock the stream.
5455
5456
This function is a GNU extension.
5457
5458
-- Function: wchar_t * fgetws_unlocked (wchar_t *WS, int COUNT, FILE
5459
*STREAM)
5460
The `fgetws_unlocked' function is equivalent to the `fgetws'
5461
function except that it does not implicitly lock the stream.
5462
5463
This function is a GNU extension.
5464
5465
-- Deprecated function: char * gets (char *S)
5466
The function `gets' reads characters from the stream `stdin' up to
5467
the next newline character, and stores them in the string S. The
5468
newline character is discarded (note that this differs from the
5469
behavior of `fgets', which copies the newline character into the
5470
string). If `gets' encounters a read error or end-of-file, it
5471
returns a null pointer; otherwise it returns S.
5472
5473
*Warning:* The `gets' function is *very dangerous* because it
5474
provides no protection against overflowing the string S. The GNU
5475
library includes it for compatibility only. You should *always*
5476
use `fgets' or `getline' instead. To remind you of this, the
5477
linker (if using GNU `ld') will issue a warning whenever you use
5478
`gets'.
5479
5480
5481
File: libc.info, Node: Unreading, Next: Block Input/Output, Prev: Line Input, Up: I/O on Streams
5482
5483
12.10 Unreading
5484
===============
5485
5486
In parser programs it is often useful to examine the next character in
5487
the input stream without removing it from the stream. This is called
5488
"peeking ahead" at the input because your program gets a glimpse of the
5489
input it will read next.
5490
5491
Using stream I/O, you can peek ahead at input by first reading it and
5492
then "unreading" it (also called "pushing it back" on the stream).
5493
Unreading a character makes it available to be input again from the
5494
stream, by the next call to `fgetc' or other input function on that
5495
stream.
5496
5497
* Menu:
5498
5499
* Unreading Idea:: An explanation of unreading with pictures.
5500
* How Unread:: How to call `ungetc' to do unreading.
5501
5502
5503
File: libc.info, Node: Unreading Idea, Next: How Unread, Up: Unreading
5504
5505
12.10.1 What Unreading Means
5506
----------------------------
5507
5508
Here is a pictorial explanation of unreading. Suppose you have a
5509
stream reading a file that contains just six characters, the letters
5510
`foobar'. Suppose you have read three characters so far. The
5511
situation looks like this:
5512
5513
f o o b a r
5514
^
5515
5516
so the next input character will be `b'.
5517
5518
If instead of reading `b' you unread the letter `o', you get a
5519
situation like this:
5520
5521
f o o b a r
5522
|
5523
o--
5524
^
5525
5526
so that the next input characters will be `o' and `b'.
5527
5528
If you unread `9' instead of `o', you get this situation:
5529
5530
f o o b a r
5531
|
5532
9--
5533
^
5534
5535
so that the next input characters will be `9' and `b'.
5536
5537
5538
File: libc.info, Node: How Unread, Prev: Unreading Idea, Up: Unreading
5539
5540
12.10.2 Using `ungetc' To Do Unreading
5541
--------------------------------------
5542
5543
The function to unread a character is called `ungetc', because it
5544
reverses the action of `getc'.
5545
5546
-- Function: int ungetc (int C, FILE *STREAM)
5547
The `ungetc' function pushes back the character C onto the input
5548
stream STREAM. So the next input from STREAM will read C before
5549
anything else.
5550
5551
If C is `EOF', `ungetc' does nothing and just returns `EOF'. This
5552
lets you call `ungetc' with the return value of `getc' without
5553
needing to check for an error from `getc'.
5554
5555
The character that you push back doesn't have to be the same as
5556
the last character that was actually read from the stream. In
5557
fact, it isn't necessary to actually read any characters from the
5558
stream before unreading them with `ungetc'! But that is a strange
5559
way to write a program; usually `ungetc' is used only to unread a
5560
character that was just read from the same stream. The GNU C
5561
library supports this even on files opened in binary mode, but
5562
other systems might not.
5563
5564
The GNU C library only supports one character of pushback--in other
5565
words, it does not work to call `ungetc' twice without doing input
5566
in between. Other systems might let you push back multiple
5567
characters; then reading from the stream retrieves the characters
5568
in the reverse order that they were pushed.
5569
5570
Pushing back characters doesn't alter the file; only the internal
5571
buffering for the stream is affected. If a file positioning
5572
function (such as `fseek', `fseeko' or `rewind'; *note File
5573
Positioning::) is called, any pending pushed-back characters are
5574
discarded.
5575
5576
Unreading a character on a stream that is at end of file clears the
5577
end-of-file indicator for the stream, because it makes the
5578
character of input available. After you read that character,
5579
trying to read again will encounter end of file.
5580
5581
-- Function: wint_t ungetwc (wint_t WC, FILE *STREAM)
5582
The `ungetwc' function behaves just like `ungetc' just that it
5583
pushes back a wide character.
5584
5585
Here is an example showing the use of `getc' and `ungetc' to skip
5586
over whitespace characters. When this function reaches a
5587
non-whitespace character, it unreads that character to be seen again on
5588
the next read operation on the stream.
5589
5590
#include <stdio.h>
5591
#include <ctype.h>
5592
5593
void
5594
skip_whitespace (FILE *stream)
5595
{
5596
int c;
5597
do
5598
/* No need to check for `EOF' because it is not
5599
`isspace', and `ungetc' ignores `EOF'. */
5600
c = getc (stream);
5601
while (isspace (c));
5602
ungetc (c, stream);
5603
}
5604
5605
5606
File: libc.info, Node: Block Input/Output, Next: Formatted Output, Prev: Unreading, Up: I/O on Streams
5607
5608
12.11 Block Input/Output
5609
========================
5610
5611
This section describes how to do input and output operations on blocks
5612
of data. You can use these functions to read and write binary data, as
5613
well as to read and write text in fixed-size blocks instead of by
5614
characters or lines.
5615
5616
Binary files are typically used to read and write blocks of data in
5617
the same format as is used to represent the data in a running program.
5618
In other words, arbitrary blocks of memory--not just character or string
5619
objects--can be written to a binary file, and meaningfully read in
5620
again by the same program.
5621
5622
Storing data in binary form is often considerably more efficient than
5623
using the formatted I/O functions. Also, for floating-point numbers,
5624
the binary form avoids possible loss of precision in the conversion
5625
process. On the other hand, binary files can't be examined or modified
5626
easily using many standard file utilities (such as text editors), and
5627
are not portable between different implementations of the language, or
5628
different kinds of computers.
5629
5630
These functions are declared in `stdio.h'.
5631
5632
-- Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE
5633
*STREAM)
5634
This function reads up to COUNT objects of size SIZE into the
5635
array DATA, from the stream STREAM. It returns the number of
5636
objects actually read, which might be less than COUNT if a read
5637
error occurs or the end of the file is reached. This function
5638
returns a value of zero (and doesn't read anything) if either SIZE
5639
or COUNT is zero.
5640
5641
If `fread' encounters end of file in the middle of an object, it
5642
returns the number of complete objects read, and discards the
5643
partial object. Therefore, the stream remains at the actual end
5644
of the file.
5645
5646
-- Function: size_t fread_unlocked (void *DATA, size_t SIZE, size_t
5647
COUNT, FILE *STREAM)
5648
The `fread_unlocked' function is equivalent to the `fread'
5649
function except that it does not implicitly lock the stream.
5650
5651
This function is a GNU extension.
5652
5653
-- Function: size_t fwrite (const void *DATA, size_t SIZE, size_t
5654
COUNT, FILE *STREAM)
5655
This function writes up to COUNT objects of size SIZE from the
5656
array DATA, to the stream STREAM. The return value is normally
5657
COUNT, if the call succeeds. Any other value indicates some sort
5658
of error, such as running out of space.
5659
5660
-- Function: size_t fwrite_unlocked (const void *DATA, size_t SIZE,
5661
size_t COUNT, FILE *STREAM)
5662
The `fwrite_unlocked' function is equivalent to the `fwrite'
5663
function except that it does not implicitly lock the stream.
5664
5665
This function is a GNU extension.
5666
5667
5668
File: libc.info, Node: Formatted Output, Next: Customizing Printf, Prev: Block Input/Output, Up: I/O on Streams
5669
5670
12.12 Formatted Output
5671
======================
5672
5673
The functions described in this section (`printf' and related
5674
functions) provide a convenient way to perform formatted output. You
5675
call `printf' with a "format string" or "template string" that
5676
specifies how to format the values of the remaining arguments.
5677
5678
Unless your program is a filter that specifically performs line- or
5679
character-oriented processing, using `printf' or one of the other
5680
related functions described in this section is usually the easiest and
5681
most concise way to perform output. These functions are especially
5682
useful for printing error messages, tables of data, and the like.
5683
5684
* Menu:
5685
5686
* Formatted Output Basics:: Some examples to get you started.
5687
* Output Conversion Syntax:: General syntax of conversion
5688
specifications.
5689
* Table of Output Conversions:: Summary of output conversions and
5690
what they do.
5691
* Integer Conversions:: Details about formatting of integers.
5692
* Floating-Point Conversions:: Details about formatting of
5693
floating-point numbers.
5694
* Other Output Conversions:: Details about formatting of strings,
5695
characters, pointers, and the like.
5696
* Formatted Output Functions:: Descriptions of the actual functions.
5697
* Dynamic Output:: Functions that allocate memory for the output.
5698
* Variable Arguments Output:: `vprintf' and friends.
5699
* Parsing a Template String:: What kinds of args does a given template
5700
call for?
5701
* Example of Parsing:: Sample program using `parse_printf_format'.
5702
5703
5704
File: libc.info, Node: Formatted Output Basics, Next: Output Conversion Syntax, Up: Formatted Output
5705
5706
12.12.1 Formatted Output Basics
5707
-------------------------------
5708
5709
The `printf' function can be used to print any number of arguments.
5710
The template string argument you supply in a call provides information
5711
not only about the number of additional arguments, but also about their
5712
types and what style should be used for printing them.
5713
5714
Ordinary characters in the template string are simply written to the
5715
output stream as-is, while "conversion specifications" introduced by a
5716
`%' character in the template cause subsequent arguments to be
5717
formatted and written to the output stream. For example,
5718
5719
int pct = 37;
5720
char filename[] = "foo.txt";
5721
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
5722
filename, pct);
5723
5724
produces output like
5725
5726
Processing of `foo.txt' is 37% finished.
5727
Please be patient.
5728
5729
This example shows the use of the `%d' conversion to specify that an
5730
`int' argument should be printed in decimal notation, the `%s'
5731
conversion to specify printing of a string argument, and the `%%'
5732
conversion to print a literal `%' character.
5733
5734
There are also conversions for printing an integer argument as an
5735
unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or
5736
`%x', respectively); or as a character value (`%c').
5737
5738
Floating-point numbers can be printed in normal, fixed-point notation
5739
using the `%f' conversion or in exponential notation using the `%e'
5740
conversion. The `%g' conversion uses either `%e' or `%f' format,
5741
depending on what is more appropriate for the magnitude of the
5742
particular number.
5743
5744
You can control formatting more precisely by writing "modifiers"
5745
between the `%' and the character that indicates which conversion to
5746
apply. These slightly alter the ordinary behavior of the conversion.
5747
For example, most conversion specifications permit you to specify a
5748
minimum field width and a flag indicating whether you want the result
5749
left- or right-justified within the field.
5750
5751
The specific flags and modifiers that are permitted and their
5752
interpretation vary depending on the particular conversion. They're all
5753
described in more detail in the following sections. Don't worry if this
5754
all seems excessively complicated at first; you can almost always get
5755
reasonable free-format output without using any of the modifiers at all.
5756
The modifiers are mostly used to make the output look "prettier" in
5757
tables.
5758
5759
5760
File: libc.info, Node: Output Conversion Syntax, Next: Table of Output Conversions, Prev: Formatted Output Basics, Up: Formatted Output
5761
5762
12.12.2 Output Conversion Syntax
5763
--------------------------------
5764
5765
This section provides details about the precise syntax of conversion
5766
specifications that can appear in a `printf' template string.
5767
5768
Characters in the template string that are not part of a conversion
5769
specification are printed as-is to the output stream. Multibyte
5770
character sequences (*note Character Set Handling::) are permitted in a
5771
template string.
5772
5773
The conversion specifications in a `printf' template string have the
5774
general form:
5775
5776
% [ PARAM-NO $] FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION
5777
5778
or
5779
5780
% [ PARAM-NO $] FLAGS WIDTH . * [ PARAM-NO $] TYPE CONVERSION
5781
5782
For example, in the conversion specifier `%-10.8ld', the `-' is a
5783
flag, `10' specifies the field width, the precision is `8', the letter
5784
`l' is a type modifier, and `d' specifies the conversion style. (This
5785
particular type specifier says to print a `long int' argument in
5786
decimal notation, with a minimum of 8 digits left-justified in a field
5787
at least 10 characters wide.)
5788
5789
In more detail, output conversion specifications consist of an
5790
initial `%' character followed in sequence by:
5791
5792
* An optional specification of the parameter used for this format.
5793
Normally the parameters to the `printf' function are assigned to
5794
the formats in the order of appearance in the format string. But
5795
in some situations (such as message translation) this is not
5796
desirable and this extension allows an explicit parameter to be
5797
specified.
5798
5799
The PARAM-NO parts of the format must be integers in the range of
5800
1 to the maximum number of arguments present to the function call.
5801
Some implementations limit this number to a certainly upper bound.
5802
The exact limit can be retrieved by the following constant.
5803
5804
-- Macro: NL_ARGMAX
5805
The value of `NL_ARGMAX' is the maximum value allowed for the
5806
specification of an positional parameter in a `printf' call.
5807
The actual value in effect at runtime can be retrieved by
5808
using `sysconf' using the `_SC_NL_ARGMAX' parameter *note
5809
Sysconf Definition::.
5810
5811
Some system have a quite low limit such as 9 for System V
5812
systems. The GNU C library has no real limit.
5813
5814
If any of the formats has a specification for the parameter
5815
position all of them in the format string shall have one.
5816
Otherwise the behavior is undefined.
5817
5818
* Zero or more "flag characters" that modify the normal behavior of
5819
the conversion specification.
5820
5821
* An optional decimal integer specifying the "minimum field width".
5822
If the normal conversion produces fewer characters than this, the
5823
field is padded with spaces to the specified width. This is a
5824
_minimum_ value; if the normal conversion produces more characters
5825
than this, the field is _not_ truncated. Normally, the output is
5826
right-justified within the field.
5827
5828
You can also specify a field width of `*'. This means that the
5829
next argument in the argument list (before the actual value to be
5830
printed) is used as the field width. The value must be an `int'.
5831
If the value is negative, this means to set the `-' flag (see
5832
below) and to use the absolute value as the field width.
5833
5834
* An optional "precision" to specify the number of digits to be
5835
written for the numeric conversions. If the precision is
5836
specified, it consists of a period (`.') followed optionally by a
5837
decimal integer (which defaults to zero if omitted).
5838
5839
You can also specify a precision of `*'. This means that the next
5840
argument in the argument list (before the actual value to be
5841
printed) is used as the precision. The value must be an `int',
5842
and is ignored if it is negative. If you specify `*' for both the
5843
field width and precision, the field width argument precedes the
5844
precision argument. Other C library versions may not recognize
5845
this syntax.
5846
5847
* An optional "type modifier character", which is used to specify the
5848
data type of the corresponding argument if it differs from the
5849
default type. (For example, the integer conversions assume a type
5850
of `int', but you can specify `h', `l', or `L' for other integer
5851
types.)
5852
5853
* A character that specifies the conversion to be applied.
5854
5855
The exact options that are permitted and how they are interpreted
5856
vary between the different conversion specifiers. See the descriptions
5857
of the individual conversions for information about the particular
5858
options that they use.
5859
5860
With the `-Wformat' option, the GNU C compiler checks calls to
5861
`printf' and related functions. It examines the format string and
5862
verifies that the correct number and types of arguments are supplied.
5863
There is also a GNU C syntax to tell the compiler that a function you
5864
write uses a `printf'-style format string. *Note Declaring Attributes
5865
of Functions: (gcc.info)Function Attributes, for more information.
5866
5867
5868
File: libc.info, Node: Table of Output Conversions, Next: Integer Conversions, Prev: Output Conversion Syntax, Up: Formatted Output
5869
5870
12.12.3 Table of Output Conversions
5871
-----------------------------------
5872
5873
Here is a table summarizing what all the different conversions do:
5874
5875
`%d', `%i'
5876
Print an integer as a signed decimal number. *Note Integer
5877
Conversions::, for details. `%d' and `%i' are synonymous for
5878
output, but are different when used with `scanf' for input (*note
5879
Table of Input Conversions::).
5880
5881
`%o'
5882
Print an integer as an unsigned octal number. *Note Integer
5883
Conversions::, for details.
5884
5885
`%u'
5886
Print an integer as an unsigned decimal number. *Note Integer
5887
Conversions::, for details.
5888
5889
`%x', `%X'
5890
Print an integer as an unsigned hexadecimal number. `%x' uses
5891
lower-case letters and `%X' uses upper-case. *Note Integer
5892
Conversions::, for details.
5893
5894
`%f'
5895
Print a floating-point number in normal (fixed-point) notation.
5896
*Note Floating-Point Conversions::, for details.
5897
5898
`%e', `%E'
5899
Print a floating-point number in exponential notation. `%e' uses
5900
lower-case letters and `%E' uses upper-case. *Note Floating-Point
5901
Conversions::, for details.
5902
5903
`%g', `%G'
5904
Print a floating-point number in either normal or exponential
5905
notation, whichever is more appropriate for its magnitude. `%g'
5906
uses lower-case letters and `%G' uses upper-case. *Note
5907
Floating-Point Conversions::, for details.
5908
5909
`%a', `%A'
5910
Print a floating-point number in a hexadecimal fractional notation
5911
which the exponent to base 2 represented in decimal digits. `%a'
5912
uses lower-case letters and `%A' uses upper-case. *Note
5913
Floating-Point Conversions::, for details.
5914
5915
`%c'
5916
Print a single character. *Note Other Output Conversions::.
5917
5918
`%C'
5919
This is an alias for `%lc' which is supported for compatibility
5920
with the Unix standard.
5921
5922
`%s'
5923
Print a string. *Note Other Output Conversions::.
5924
5925
`%S'
5926
This is an alias for `%ls' which is supported for compatibility
5927
with the Unix standard.
5928
5929
`%p'
5930
Print the value of a pointer. *Note Other Output Conversions::.
5931
5932
`%n'
5933
Get the number of characters printed so far. *Note Other Output
5934
Conversions::. Note that this conversion specification never
5935
produces any output.
5936
5937
`%m'
5938
Print the string corresponding to the value of `errno'. (This is
5939
a GNU extension.) *Note Other Output Conversions::.
5940
5941
`%%'
5942
Print a literal `%' character. *Note Other Output Conversions::.
5943
5944
If the syntax of a conversion specification is invalid, unpredictable
5945
things will happen, so don't do this. If there aren't enough function
5946
arguments provided to supply values for all the conversion
5947
specifications in the template string, or if the arguments are not of
5948
the correct types, the results are unpredictable. If you supply more
5949
arguments than conversion specifications, the extra argument values are
5950
simply ignored; this is sometimes useful.
5951
5952
5953
File: libc.info, Node: Integer Conversions, Next: Floating-Point Conversions, Prev: Table of Output Conversions, Up: Formatted Output
5954
5955
12.12.4 Integer Conversions
5956
---------------------------
5957
5958
This section describes the options for the `%d', `%i', `%o', `%u',
5959
`%x', and `%X' conversion specifications. These conversions print
5960
integers in various formats.
5961
5962
The `%d' and `%i' conversion specifications both print an `int'
5963
argument as a signed decimal number; while `%o', `%u', and `%x' print
5964
the argument as an unsigned octal, decimal, or hexadecimal number
5965
(respectively). The `%X' conversion specification is just like `%x'
5966
except that it uses the characters `ABCDEF' as digits instead of
5967
`abcdef'.
5968
5969
The following flags are meaningful:
5970
5971
`-'
5972
Left-justify the result in the field (instead of the normal
5973
right-justification).
5974
5975
`+'
5976
For the signed `%d' and `%i' conversions, print a plus sign if the
5977
value is positive.
5978
5979
` '
5980
For the signed `%d' and `%i' conversions, if the result doesn't
5981
start with a plus or minus sign, prefix it with a space character
5982
instead. Since the `+' flag ensures that the result includes a
5983
sign, this flag is ignored if you supply both of them.
5984
5985
`#'
5986
For the `%o' conversion, this forces the leading digit to be `0',
5987
as if by increasing the precision. For `%x' or `%X', this
5988
prefixes a leading `0x' or `0X' (respectively) to the result.
5989
This doesn't do anything useful for the `%d', `%i', or `%u'
5990
conversions. Using this flag produces output which can be parsed
5991
by the `strtoul' function (*note Parsing of Integers::) and
5992
`scanf' with the `%i' conversion (*note Numeric Input
5993
Conversions::).
5994
5995
`''
5996
Separate the digits into groups as specified by the locale
5997
specified for the `LC_NUMERIC' category; *note General Numeric::.
5998
This flag is a GNU extension.
5999
6000
`0'
6001
Pad the field with zeros instead of spaces. The zeros are placed
6002
after any indication of sign or base. This flag is ignored if the
6003
`-' flag is also specified, or if a precision is specified.
6004
6005
If a precision is supplied, it specifies the minimum number of
6006
digits to appear; leading zeros are produced if necessary. If you
6007
don't specify a precision, the number is printed with as many digits as
6008
it needs. If you convert a value of zero with an explicit precision of
6009
zero, then no characters at all are produced.
6010
6011
Without a type modifier, the corresponding argument is treated as an
6012
`int' (for the signed conversions `%i' and `%d') or `unsigned int' (for
6013
the unsigned conversions `%o', `%u', `%x', and `%X'). Recall that
6014
since `printf' and friends are variadic, any `char' and `short'
6015
arguments are automatically converted to `int' by the default argument
6016
promotions. For arguments of other integer types, you can use these
6017
modifiers:
6018
6019
`hh'
6020
Specifies that the argument is a `signed char' or `unsigned char',
6021
as appropriate. A `char' argument is converted to an `int' or
6022
`unsigned int' by the default argument promotions anyway, but the
6023
`h' modifier says to convert it back to a `char' again.
6024
6025
This modifier was introduced in ISO C99.
6026
6027
`h'
6028
Specifies that the argument is a `short int' or `unsigned short
6029
int', as appropriate. A `short' argument is converted to an `int'
6030
or `unsigned int' by the default argument promotions anyway, but
6031
the `h' modifier says to convert it back to a `short' again.
6032
6033
`j'
6034
Specifies that the argument is a `intmax_t' or `uintmax_t', as
6035
appropriate.
6036
6037
This modifier was introduced in ISO C99.
6038
6039
`l'
6040
Specifies that the argument is a `long int' or `unsigned long
6041
int', as appropriate. Two `l' characters is like the `L'
6042
modifier, below.
6043
6044
If used with `%c' or `%s' the corresponding parameter is
6045
considered as a wide character or wide character string
6046
respectively. This use of `l' was introduced in Amendment 1 to
6047
ISO C90.
6048
6049
`L'
6050
`ll'
6051
`q'
6052
Specifies that the argument is a `long long int'. (This type is
6053
an extension supported by the GNU C compiler. On systems that
6054
don't support extra-long integers, this is the same as `long int'.)
6055
6056
The `q' modifier is another name for the same thing, which comes
6057
from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
6058
6059
`t'
6060
Specifies that the argument is a `ptrdiff_t'.
6061
6062
This modifier was introduced in ISO C99.
6063
6064
`z'
6065
`Z'
6066
Specifies that the argument is a `size_t'.
6067
6068
`z' was introduced in ISO C99. `Z' is a GNU extension predating
6069
this addition and should not be used in new code.
6070
6071
Here is an example. Using the template string:
6072
6073
"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
6074
6075
to print numbers using the different options for the `%d' conversion
6076
gives results like:
6077
6078
| 0|0 | +0|+0 | 0|00000| | 00|0|
6079
| 1|1 | +1|+1 | 1|00001| 1| 01|1|
6080
| -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
6081
|100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
6082
6083
In particular, notice what happens in the last case where the number
6084
is too large to fit in the minimum field width specified.
6085
6086
Here are some more examples showing how unsigned integers print under
6087
various format options, using the template string:
6088
6089
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
6090
6091
| 0| 0| 0| 0| 0| 0| 0| 00000000|
6092
| 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
6093
|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
6094
6095
6096
File: libc.info, Node: Floating-Point Conversions, Next: Other Output Conversions, Prev: Integer Conversions, Up: Formatted Output
6097
6098
12.12.5 Floating-Point Conversions
6099
----------------------------------
6100
6101
This section discusses the conversion specifications for floating-point
6102
numbers: the `%f', `%e', `%E', `%g', and `%G' conversions.
6103
6104
The `%f' conversion prints its argument in fixed-point notation,
6105
producing output of the form [`-']DDD`.'DDD, where the number of digits
6106
following the decimal point is controlled by the precision you specify.
6107
6108
The `%e' conversion prints its argument in exponential notation,
6109
producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD. Again, the
6110
number of digits following the decimal point is controlled by the
6111
precision. The exponent always contains at least two digits. The `%E'
6112
conversion is similar but the exponent is marked with the letter `E'
6113
instead of `e'.
6114
6115
The `%g' and `%G' conversions print the argument in the style of
6116
`%e' or `%E' (respectively) if the exponent would be less than -4 or
6117
greater than or equal to the precision; otherwise they use the `%f'
6118
style. A precision of `0', is taken as 1. Trailing zeros are removed
6119
from the fractional portion of the result and a decimal-point character
6120
appears only if it is followed by a digit.
6121
6122
The `%a' and `%A' conversions are meant for representing
6123
floating-point numbers exactly in textual form so that they can be
6124
exchanged as texts between different programs and/or machines. The
6125
numbers are represented is the form [`-']`0x'H`.'HHH`p'[`+'|`-']DD. At
6126
the left of the decimal-point character exactly one digit is print.
6127
This character is only `0' if the number is denormalized. Otherwise
6128
the value is unspecified; it is implementation dependent how many bits
6129
are used. The number of hexadecimal digits on the right side of the
6130
decimal-point character is equal to the precision. If the precision is
6131
zero it is determined to be large enough to provide an exact
6132
representation of the number (or it is large enough to distinguish two
6133
adjacent values if the `FLT_RADIX' is not a power of 2, *note Floating
6134
Point Parameters::). For the `%a' conversion lower-case characters are
6135
used to represent the hexadecimal number and the prefix and exponent
6136
sign are printed as `0x' and `p' respectively. Otherwise upper-case
6137
characters are used and `0X' and `P' are used for the representation of
6138
prefix and exponent string. The exponent to the base of two is printed
6139
as a decimal number using at least one digit but at most as many digits
6140
as necessary to represent the value exactly.
6141
6142
If the value to be printed represents infinity or a NaN, the output
6143
is [`-']`inf' or `nan' respectively if the conversion specifier is
6144
`%a', `%e', `%f', or `%g' and it is [`-']`INF' or `NAN' respectively if
6145
the conversion is `%A', `%E', or `%G'.
6146
6147
The following flags can be used to modify the behavior:
6148
6149
`-'
6150
Left-justify the result in the field. Normally the result is
6151
right-justified.
6152
6153
`+'
6154
Always include a plus or minus sign in the result.
6155
6156
` '
6157
If the result doesn't start with a plus or minus sign, prefix it
6158
with a space instead. Since the `+' flag ensures that the result
6159
includes a sign, this flag is ignored if you supply both of them.
6160
6161
`#'
6162
Specifies that the result should always include a decimal point,
6163
even if no digits follow it. For the `%g' and `%G' conversions,
6164
this also forces trailing zeros after the decimal point to be left
6165
in place where they would otherwise be removed.
6166
6167
`''
6168
Separate the digits of the integer part of the result into groups
6169
as specified by the locale specified for the `LC_NUMERIC' category;
6170
*note General Numeric::. This flag is a GNU extension.
6171
6172
`0'
6173
Pad the field with zeros instead of spaces; the zeros are placed
6174
after any sign. This flag is ignored if the `-' flag is also
6175
specified.
6176
6177
The precision specifies how many digits follow the decimal-point
6178
character for the `%f', `%e', and `%E' conversions. For these
6179
conversions, the default precision is `6'. If the precision is
6180
explicitly `0', this suppresses the decimal point character entirely.
6181
For the `%g' and `%G' conversions, the precision specifies how many
6182
significant digits to print. Significant digits are the first digit
6183
before the decimal point, and all the digits after it. If the
6184
precision is `0' or not specified for `%g' or `%G', it is treated like
6185
a value of `1'. If the value being printed cannot be expressed
6186
accurately in the specified number of digits, the value is rounded to
6187
the nearest number that fits.
6188
6189
Without a type modifier, the floating-point conversions use an
6190
argument of type `double'. (By the default argument promotions, any
6191
`float' arguments are automatically converted to `double'.) The
6192
following type modifier is supported:
6193
6194
`L'
6195
An uppercase `L' specifies that the argument is a `long double'.
6196
6197
Here are some examples showing how numbers print using the various
6198
floating-point conversions. All of the numbers were printed using this
6199
template string:
6200
6201
"|%13.4a|%13.4f|%13.4e|%13.4g|\n"
6202
6203
Here is the output:
6204
6205
| 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
6206
| 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
6207
| 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
6208
| -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
6209
| 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
6210
| 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
6211
| 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
6212
| 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
6213
| 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
6214
| 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
6215
6216
Notice how the `%g' conversion drops trailing zeros.
6217
6218
6219
File: libc.info, Node: Other Output Conversions, Next: Formatted Output Functions, Prev: Floating-Point Conversions, Up: Formatted Output
6220
6221
12.12.6 Other Output Conversions
6222
--------------------------------
6223
6224
This section describes miscellaneous conversions for `printf'.
6225
6226
The `%c' conversion prints a single character. In case there is no
6227
`l' modifier the `int' argument is first converted to an `unsigned
6228
char'. Then, if used in a wide stream function, the character is
6229
converted into the corresponding wide character. The `-' flag can be
6230
used to specify left-justification in the field, but no other flags are
6231
defined, and no precision or type modifier can be given. For example:
6232
6233
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
6234
6235
prints `hello'.
6236
6237
If there is a `l' modifier present the argument is expected to be of
6238
type `wint_t'. If used in a multibyte function the wide character is
6239
converted into a multibyte character before being added to the output.
6240
In this case more than one output byte can be produced.
6241
6242
The `%s' conversion prints a string. If no `l' modifier is present
6243
the corresponding argument must be of type `char *' (or `const char
6244
*'). If used in a wide stream function the string is first converted
6245
in a wide character string. A precision can be specified to indicate
6246
the maximum number of characters to write; otherwise characters in the
6247
string up to but not including the terminating null character are
6248
written to the output stream. The `-' flag can be used to specify
6249
left-justification in the field, but no other flags or type modifiers
6250
are defined for this conversion. For example:
6251
6252
printf ("%3s%-6s", "no", "where");
6253
6254
prints ` nowhere '.
6255
6256
If there is a `l' modifier present the argument is expected to be of
6257
type `wchar_t' (or `const wchar_t *').
6258
6259
If you accidentally pass a null pointer as the argument for a `%s'
6260
conversion, the GNU library prints it as `(null)'. We think this is
6261
more useful than crashing. But it's not good practice to pass a null
6262
argument intentionally.
6263
6264
The `%m' conversion prints the string corresponding to the error
6265
code in `errno'. *Note Error Messages::. Thus:
6266
6267
fprintf (stderr, "can't open `%s': %m\n", filename);
6268
6269
is equivalent to:
6270
6271
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
6272
6273
The `%m' conversion is a GNU C library extension.
6274
6275
The `%p' conversion prints a pointer value. The corresponding
6276
argument must be of type `void *'. In practice, you can use any type
6277
of pointer.
6278
6279
In the GNU system, non-null pointers are printed as unsigned
6280
integers, as if a `%#x' conversion were used. Null pointers print as
6281
`(nil)'. (Pointers might print differently in other systems.)
6282
6283
For example:
6284
6285
printf ("%p", "testing");
6286
6287
prints `0x' followed by a hexadecimal number--the address of the string
6288
constant `"testing"'. It does not print the word `testing'.
6289
6290
You can supply the `-' flag with the `%p' conversion to specify
6291
left-justification, but no other flags, precision, or type modifiers
6292
are defined.
6293
6294
The `%n' conversion is unlike any of the other output conversions.
6295
It uses an argument which must be a pointer to an `int', but instead of
6296
printing anything it stores the number of characters printed so far by
6297
this call at that location. The `h' and `l' type modifiers are
6298
permitted to specify that the argument is of type `short int *' or
6299
`long int *' instead of `int *', but no flags, field width, or
6300
precision are permitted.
6301
6302
For example,
6303
6304
int nchar;
6305
printf ("%d %s%n\n", 3, "bears", &nchar);
6306
6307
prints:
6308
6309
3 bears
6310
6311
and sets `nchar' to `7', because `3 bears' is seven characters.
6312
6313
The `%%' conversion prints a literal `%' character. This conversion
6314
doesn't use an argument, and no flags, field width, precision, or type
6315
modifiers are permitted.
6316
6317
6318
File: libc.info, Node: Formatted Output Functions, Next: Dynamic Output, Prev: Other Output Conversions, Up: Formatted Output
6319
6320
12.12.7 Formatted Output Functions
6321
----------------------------------
6322
6323
This section describes how to call `printf' and related functions.
6324
Prototypes for these functions are in the header file `stdio.h'.
6325
Because these functions take a variable number of arguments, you _must_
6326
declare prototypes for them before using them. Of course, the easiest
6327
way to make sure you have all the right prototypes is to just include
6328
`stdio.h'.
6329
6330
-- Function: int printf (const char *TEMPLATE, ...)
6331
The `printf' function prints the optional arguments under the
6332
control of the template string TEMPLATE to the stream `stdout'.
6333
It returns the number of characters printed, or a negative value
6334
if there was an output error.
6335
6336
-- Function: int wprintf (const wchar_t *TEMPLATE, ...)
6337
The `wprintf' function prints the optional arguments under the
6338
control of the wide template string TEMPLATE to the stream
6339
`stdout'. It returns the number of wide characters printed, or a
6340
negative value if there was an output error.
6341
6342
-- Function: int fprintf (FILE *STREAM, const char *TEMPLATE, ...)
6343
This function is just like `printf', except that the output is
6344
written to the stream STREAM instead of `stdout'.
6345
6346
-- Function: int fwprintf (FILE *STREAM, const wchar_t *TEMPLATE, ...)
6347
This function is just like `wprintf', except that the output is
6348
written to the stream STREAM instead of `stdout'.
6349
6350
-- Function: int sprintf (char *S, const char *TEMPLATE, ...)
6351
This is like `printf', except that the output is stored in the
6352
character array S instead of written to a stream. A null
6353
character is written to mark the end of the string.
6354
6355
The `sprintf' function returns the number of characters stored in
6356
the array S, not including the terminating null character.
6357
6358
The behavior of this function is undefined if copying takes place
6359
between objects that overlap--for example, if S is also given as
6360
an argument to be printed under control of the `%s' conversion.
6361
*Note Copying and Concatenation::.
6362
6363
*Warning:* The `sprintf' function can be *dangerous* because it
6364
can potentially output more characters than can fit in the
6365
allocation size of the string S. Remember that the field width
6366
given in a conversion specification is only a _minimum_ value.
6367
6368
To avoid this problem, you can use `snprintf' or `asprintf',
6369
described below.
6370
6371
-- Function: int swprintf (wchar_t *S, size_t SIZE, const wchar_t
6372
*TEMPLATE, ...)
6373
This is like `wprintf', except that the output is stored in the
6374
wide character array WS instead of written to a stream. A null
6375
wide character is written to mark the end of the string. The SIZE
6376
argument specifies the maximum number of characters to produce.
6377
The trailing null character is counted towards this limit, so you
6378
should allocate at least SIZE wide characters for the string WS.
6379
6380
The return value is the number of characters generated for the
6381
given input, excluding the trailing null. If not all output fits
6382
into the provided buffer a negative value is returned. You should
6383
try again with a bigger output string. _Note:_ this is different
6384
from how `snprintf' handles this situation.
6385
6386
Note that the corresponding narrow stream function takes fewer
6387
parameters. `swprintf' in fact corresponds to the `snprintf'
6388
function. Since the `sprintf' function can be dangerous and should
6389
be avoided the ISO C committee refused to make the same mistake
6390
again and decided to not define an function exactly corresponding
6391
to `sprintf'.
6392
6393
-- Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE,
6394
...)
6395
The `snprintf' function is similar to `sprintf', except that the
6396
SIZE argument specifies the maximum number of characters to
6397
produce. The trailing null character is counted towards this
6398
limit, so you should allocate at least SIZE characters for the
6399
string S.
6400
6401
The return value is the number of characters which would be
6402
generated for the given input, excluding the trailing null. If
6403
this value is greater or equal to SIZE, not all characters from
6404
the result have been stored in S. You should try again with a
6405
bigger output string. Here is an example of doing this:
6406
6407
/* Construct a message describing the value of a variable
6408
whose name is NAME and whose value is VALUE. */
6409
char *
6410
make_message (char *name, char *value)
6411
{
6412
/* Guess we need no more than 100 chars of space. */
6413
int size = 100;
6414
char *buffer = (char *) xmalloc (size);
6415
int nchars;
6416
if (buffer == NULL)
6417
return NULL;
6418
6419
/* Try to print in the allocated space. */
6420
nchars = snprintf (buffer, size, "value of %s is %s",
6421
name, value);
6422
if (nchars >= size)
6423
{
6424
/* Reallocate buffer now that we know
6425
how much space is needed. */
6426
size = nchars + 1;
6427
buffer = (char *) xrealloc (buffer, size);
6428
6429
if (buffer != NULL)
6430
/* Try again. */
6431
snprintf (buffer, size, "value of %s is %s",
6432
name, value);
6433
}
6434
/* The last call worked, return the string. */
6435
return buffer;
6436
}
6437
6438
In practice, it is often easier just to use `asprintf', below.
6439
6440
*Attention:* In versions of the GNU C library prior to 2.1 the
6441
return value is the number of characters stored, not including the
6442
terminating null; unless there was not enough space in S to store
6443
the result in which case `-1' is returned. This was changed in
6444
order to comply with the ISO C99 standard.
6445
6446
6447
File: libc.info, Node: Dynamic Output, Next: Variable Arguments Output, Prev: Formatted Output Functions, Up: Formatted Output
6448
6449
12.12.8 Dynamically Allocating Formatted Output
6450
-----------------------------------------------
6451
6452
The functions in this section do formatted output and place the results
6453
in dynamically allocated memory.
6454
6455
-- Function: int asprintf (char **PTR, const char *TEMPLATE, ...)
6456
This function is similar to `sprintf', except that it dynamically
6457
allocates a string (as with `malloc'; *note Unconstrained
6458
Allocation::) to hold the output, instead of putting the output in
6459
a buffer you allocate in advance. The PTR argument should be the
6460
address of a `char *' object, and a successful call to `asprintf'
6461
stores a pointer to the newly allocated string at that location.
6462
6463
The return value is the number of characters allocated for the
6464
buffer, or less than zero if an error occurred. Usually this means
6465
that the buffer could not be allocated.
6466
6467
Here is how to use `asprintf' to get the same result as the
6468
`snprintf' example, but more easily:
6469
6470
/* Construct a message describing the value of a variable
6471
whose name is NAME and whose value is VALUE. */
6472
char *
6473
make_message (char *name, char *value)
6474
{
6475
char *result;
6476
if (asprintf (&result, "value of %s is %s", name, value) < 0)
6477
return NULL;
6478
return result;
6479
}
6480
6481
-- Function: int obstack_printf (struct obstack *OBSTACK, const char
6482
*TEMPLATE, ...)
6483
This function is similar to `asprintf', except that it uses the
6484
obstack OBSTACK to allocate the space. *Note Obstacks::.
6485
6486
The characters are written onto the end of the current object. To
6487
get at them, you must finish the object with `obstack_finish'
6488
(*note Growing Objects::).
6489
6490
6491
File: libc.info, Node: Variable Arguments Output, Next: Parsing a Template String, Prev: Dynamic Output, Up: Formatted Output
6492
6493
12.12.9 Variable Arguments Output Functions
6494
-------------------------------------------
6495
6496
The functions `vprintf' and friends are provided so that you can define
6497
your own variadic `printf'-like functions that make use of the same
6498
internals as the built-in formatted output functions.
6499
6500
The most natural way to define such functions would be to use a
6501
language construct to say, "Call `printf' and pass this template plus
6502
all of my arguments after the first five." But there is no way to do
6503
this in C, and it would be hard to provide a way, since at the C
6504
language level there is no way to tell how many arguments your function
6505
received.
6506
6507
Since that method is impossible, we provide alternative functions,
6508
the `vprintf' series, which lets you pass a `va_list' to describe "all
6509
of my arguments after the first five."
6510
6511
When it is sufficient to define a macro rather than a real function,
6512
the GNU C compiler provides a way to do this much more easily with
6513
macros. For example:
6514
6515
#define myprintf(a, b, c, d, e, rest...) \
6516
printf (mytemplate , ## rest)
6517
6518
*Note Variadic Macros: (cpp)Variadic Macros, for details. But this is
6519
limited to macros, and does not apply to real functions at all.
6520
6521
Before calling `vprintf' or the other functions listed in this
6522
section, you _must_ call `va_start' (*note Variadic Functions::) to
6523
initialize a pointer to the variable arguments. Then you can call
6524
`va_arg' to fetch the arguments that you want to handle yourself. This
6525
advances the pointer past those arguments.
6526
6527
Once your `va_list' pointer is pointing at the argument of your
6528
choice, you are ready to call `vprintf'. That argument and all
6529
subsequent arguments that were passed to your function are used by
6530
`vprintf' along with the template that you specified separately.
6531
6532
In some other systems, the `va_list' pointer may become invalid
6533
after the call to `vprintf', so you must not use `va_arg' after you
6534
call `vprintf'. Instead, you should call `va_end' to retire the
6535
pointer from service. However, you can safely call `va_start' on
6536
another pointer variable and begin fetching the arguments again through
6537
that pointer. Calling `vprintf' does not destroy the argument list of
6538
your function, merely the particular pointer that you passed to it.
6539
6540
GNU C does not have such restrictions. You can safely continue to
6541
fetch arguments from a `va_list' pointer after passing it to `vprintf',
6542
and `va_end' is a no-op. (Note, however, that subsequent `va_arg'
6543
calls will fetch the same arguments which `vprintf' previously used.)
6544
6545
Prototypes for these functions are declared in `stdio.h'.
6546
6547
-- Function: int vprintf (const char *TEMPLATE, va_list AP)
6548
This function is similar to `printf' except that, instead of taking
6549
a variable number of arguments directly, it takes an argument list
6550
pointer AP.
6551
6552
-- Function: int vwprintf (const wchar_t *TEMPLATE, va_list AP)
6553
This function is similar to `wprintf' except that, instead of
6554
taking a variable number of arguments directly, it takes an
6555
argument list pointer AP.
6556
6557
-- Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list
6558
AP)
6559
This is the equivalent of `fprintf' with the variable argument list
6560
specified directly as for `vprintf'.
6561
6562
-- Function: int vfwprintf (FILE *STREAM, const wchar_t *TEMPLATE,
6563
va_list AP)
6564
This is the equivalent of `fwprintf' with the variable argument
6565
list specified directly as for `vwprintf'.
6566
6567
-- Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP)
6568
This is the equivalent of `sprintf' with the variable argument list
6569
specified directly as for `vprintf'.
6570
6571
-- Function: int vswprintf (wchar_t *S, size_t SIZE, const wchar_t
6572
*TEMPLATE, va_list AP)
6573
This is the equivalent of `swprintf' with the variable argument
6574
list specified directly as for `vwprintf'.
6575
6576
-- Function: int vsnprintf (char *S, size_t SIZE, const char
6577
*TEMPLATE, va_list AP)
6578
This is the equivalent of `snprintf' with the variable argument
6579
list specified directly as for `vprintf'.
6580
6581
-- Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list
6582
AP)
6583
The `vasprintf' function is the equivalent of `asprintf' with the
6584
variable argument list specified directly as for `vprintf'.
6585
6586
-- Function: int obstack_vprintf (struct obstack *OBSTACK, const char
6587
*TEMPLATE, va_list AP)
6588
The `obstack_vprintf' function is the equivalent of
6589
`obstack_printf' with the variable argument list specified directly
6590
as for `vprintf'.
6591
6592
Here's an example showing how you might use `vfprintf'. This is a
6593
function that prints error messages to the stream `stderr', along with
6594
a prefix indicating the name of the program (*note Error Messages::,
6595
for a description of `program_invocation_short_name').
6596
6597
#include <stdio.h>
6598
#include <stdarg.h>
6599
6600
void
6601
eprintf (const char *template, ...)
6602
{
6603
va_list ap;
6604
extern char *program_invocation_short_name;
6605
6606
fprintf (stderr, "%s: ", program_invocation_short_name);
6607
va_start (ap, template);
6608
vfprintf (stderr, template, ap);
6609
va_end (ap);
6610
}
6611
6612
You could call `eprintf' like this:
6613
6614
eprintf ("file `%s' does not exist\n", filename);
6615
6616
In GNU C, there is a special construct you can use to let the
6617
compiler know that a function uses a `printf'-style format string.
6618
Then it can check the number and types of arguments in each call to the
6619
function, and warn you when they do not match the format string. For
6620
example, take this declaration of `eprintf':
6621
6622
void eprintf (const char *template, ...)
6623
__attribute__ ((format (printf, 1, 2)));
6624
6625
This tells the compiler that `eprintf' uses a format string like
6626
`printf' (as opposed to `scanf'; *note Formatted Input::); the format
6627
string appears as the first argument; and the arguments to satisfy the
6628
format begin with the second. *Note Declaring Attributes of Functions:
6629
(gcc.info)Function Attributes, for more information.
6630
6631
6632
File: libc.info, Node: Parsing a Template String, Next: Example of Parsing, Prev: Variable Arguments Output, Up: Formatted Output
6633
6634
12.12.10 Parsing a Template String
6635
----------------------------------
6636
6637
You can use the function `parse_printf_format' to obtain information
6638
about the number and types of arguments that are expected by a given
6639
template string. This function permits interpreters that provide
6640
interfaces to `printf' to avoid passing along invalid arguments from
6641
the user's program, which could cause a crash.
6642
6643
All the symbols described in this section are declared in the header
6644
file `printf.h'.
6645
6646
-- Function: size_t parse_printf_format (const char *TEMPLATE, size_t
6647
N, int *ARGTYPES)
6648
This function returns information about the number and types of
6649
arguments expected by the `printf' template string TEMPLATE. The
6650
information is stored in the array ARGTYPES; each element of this
6651
array describes one argument. This information is encoded using
6652
the various `PA_' macros, listed below.
6653
6654
The argument N specifies the number of elements in the array
6655
ARGTYPES. This is the maximum number of elements that
6656
`parse_printf_format' will try to write.
6657
6658
`parse_printf_format' returns the total number of arguments
6659
required by TEMPLATE. If this number is greater than N, then the
6660
information returned describes only the first N arguments. If you
6661
want information about additional arguments, allocate a bigger
6662
array and call `parse_printf_format' again.
6663
6664
The argument types are encoded as a combination of a basic type and
6665
modifier flag bits.
6666
6667
-- Macro: int PA_FLAG_MASK
6668
This macro is a bitmask for the type modifier flag bits. You can
6669
write the expression `(argtypes[i] & PA_FLAG_MASK)' to extract
6670
just the flag bits for an argument, or `(argtypes[i] &
6671
~PA_FLAG_MASK)' to extract just the basic type code.
6672
6673
Here are symbolic constants that represent the basic types; they
6674
stand for integer values.
6675
6676
`PA_INT'
6677
This specifies that the base type is `int'.
6678
6679
`PA_CHAR'
6680
This specifies that the base type is `int', cast to `char'.
6681
6682
`PA_STRING'
6683
This specifies that the base type is `char *', a null-terminated
6684
string.
6685
6686
`PA_POINTER'
6687
This specifies that the base type is `void *', an arbitrary
6688
pointer.
6689
6690
`PA_FLOAT'
6691
This specifies that the base type is `float'.
6692
6693
`PA_DOUBLE'
6694
This specifies that the base type is `double'.
6695
6696
`PA_LAST'
6697
You can define additional base types for your own programs as
6698
offsets from `PA_LAST'. For example, if you have data types `foo'
6699
and `bar' with their own specialized `printf' conversions, you
6700
could define encodings for these types as:
6701
6702
#define PA_FOO PA_LAST
6703
#define PA_BAR (PA_LAST + 1)
6704
6705
Here are the flag bits that modify a basic type. They are combined
6706
with the code for the basic type using inclusive-or.
6707
6708
`PA_FLAG_PTR'
6709
If this bit is set, it indicates that the encoded type is a
6710
pointer to the base type, rather than an immediate value. For
6711
example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.
6712
6713
`PA_FLAG_SHORT'
6714
If this bit is set, it indicates that the base type is modified
6715
with `short'. (This corresponds to the `h' type modifier.)
6716
6717
`PA_FLAG_LONG'
6718
If this bit is set, it indicates that the base type is modified
6719
with `long'. (This corresponds to the `l' type modifier.)
6720
6721
`PA_FLAG_LONG_LONG'
6722
If this bit is set, it indicates that the base type is modified
6723
with `long long'. (This corresponds to the `L' type modifier.)
6724
6725
`PA_FLAG_LONG_DOUBLE'
6726
This is a synonym for `PA_FLAG_LONG_LONG', used by convention with
6727
a base type of `PA_DOUBLE' to indicate a type of `long double'.
6728
6729
For an example of using these facilities, see *note Example of
6730
Parsing::.
6731
6732
6733
File: libc.info, Node: Example of Parsing, Prev: Parsing a Template String, Up: Formatted Output
6734
6735
12.12.11 Example of Parsing a Template String
6736
---------------------------------------------
6737
6738
Here is an example of decoding argument types for a format string. We
6739
assume this is part of an interpreter which contains arguments of type
6740
`NUMBER', `CHAR', `STRING' and `STRUCTURE' (and perhaps others which
6741
are not valid here).
6742
6743
/* Test whether the NARGS specified objects
6744
in the vector ARGS are valid
6745
for the format string FORMAT:
6746
if so, return 1.
6747
If not, return 0 after printing an error message. */
6748
6749
int
6750
validate_args (char *format, int nargs, OBJECT *args)
6751
{
6752
int *argtypes;
6753
int nwanted;
6754
6755
/* Get the information about the arguments.
6756
Each conversion specification must be at least two characters
6757
long, so there cannot be more specifications than half the
6758
length of the string. */
6759
6760
argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
6761
nwanted = parse_printf_format (string, nelts, argtypes);
6762
6763
/* Check the number of arguments. */
6764
if (nwanted > nargs)
6765
{
6766
error ("too few arguments (at least %d required)", nwanted);
6767
return 0;
6768
}
6769
6770
/* Check the C type wanted for each argument
6771
and see if the object given is suitable. */
6772
for (i = 0; i < nwanted; i++)
6773
{
6774
int wanted;
6775
6776
if (argtypes[i] & PA_FLAG_PTR)
6777
wanted = STRUCTURE;
6778
else
6779
switch (argtypes[i] & ~PA_FLAG_MASK)
6780
{
6781
case PA_INT:
6782
case PA_FLOAT:
6783
case PA_DOUBLE:
6784
wanted = NUMBER;
6785
break;
6786
case PA_CHAR:
6787
wanted = CHAR;
6788
break;
6789
case PA_STRING:
6790
wanted = STRING;
6791
break;
6792
case PA_POINTER:
6793
wanted = STRUCTURE;
6794
break;
6795
}
6796
if (TYPE (args[i]) != wanted)
6797
{
6798
error ("type mismatch for arg number %d", i);
6799
return 0;
6800
}
6801
}
6802
return 1;
6803
}
6804
6805
6806
File: libc.info, Node: Customizing Printf, Next: Formatted Input, Prev: Formatted Output, Up: I/O on Streams
6807
6808
12.13 Customizing `printf'
6809
==========================
6810
6811
The GNU C library lets you define your own custom conversion specifiers
6812
for `printf' template strings, to teach `printf' clever ways to print
6813
the important data structures of your program.
6814
6815
The way you do this is by registering the conversion with the
6816
function `register_printf_function'; see *note Registering New
6817
Conversions::. One of the arguments you pass to this function is a
6818
pointer to a handler function that produces the actual output; see
6819
*note Defining the Output Handler::, for information on how to write
6820
this function.
6821
6822
You can also install a function that just returns information about
6823
the number and type of arguments expected by the conversion specifier.
6824
*Note Parsing a Template String::, for information about this.
6825
6826
The facilities of this section are declared in the header file
6827
`printf.h'.
6828
6829
* Menu:
6830
6831
* Registering New Conversions:: Using `register_printf_function'
6832
to register a new output conversion.
6833
* Conversion Specifier Options:: The handler must be able to get
6834
the options specified in the
6835
template when it is called.
6836
* Defining the Output Handler:: Defining the handler and arginfo
6837
functions that are passed as arguments
6838
to `register_printf_function'.
6839
* Printf Extension Example:: How to define a `printf'
6840
handler function.
6841
* Predefined Printf Handlers:: Predefined `printf' handlers.
6842
6843
*Portability Note:* The ability to extend the syntax of `printf'
6844
template strings is a GNU extension. ISO standard C has nothing
6845
similar.
6846
6847
6848
File: libc.info, Node: Registering New Conversions, Next: Conversion Specifier Options, Up: Customizing Printf
6849
6850
12.13.1 Registering New Conversions
6851
-----------------------------------
6852
6853
The function to register a new output conversion is
6854
`register_printf_function', declared in `printf.h'.
6855
6856
-- Function: int register_printf_function (int SPEC, printf_function
6857
HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION)
6858
This function defines the conversion specifier character SPEC.
6859
Thus, if SPEC is `'Y'', it defines the conversion `%Y'. You can
6860
redefine the built-in conversions like `%s', but flag characters
6861
like `#' and type modifiers like `l' can never be used as
6862
conversions; calling `register_printf_function' for those
6863
characters has no effect. It is advisable not to use lowercase
6864
letters, since the ISO C standard warns that additional lowercase
6865
letters may be standardized in future editions of the standard.
6866
6867
The HANDLER-FUNCTION is the function called by `printf' and
6868
friends when this conversion appears in a template string. *Note
6869
Defining the Output Handler::, for information about how to define
6870
a function to pass as this argument. If you specify a null
6871
pointer, any existing handler function for SPEC is removed.
6872
6873
The ARGINFO-FUNCTION is the function called by
6874
`parse_printf_format' when this conversion appears in a template
6875
string. *Note Parsing a Template String::, for information about
6876
this.
6877
6878
*Attention:* In the GNU C library versions before 2.0 the
6879
ARGINFO-FUNCTION function did not need to be installed unless the
6880
user used the `parse_printf_format' function. This has changed.
6881
Now a call to any of the `printf' functions will call this
6882
function when this format specifier appears in the format string.
6883
6884
The return value is `0' on success, and `-1' on failure (which
6885
occurs if SPEC is out of range).
6886
6887
You can redefine the standard output conversions, but this is
6888
probably not a good idea because of the potential for confusion.
6889
Library routines written by other people could break if you do
6890
this.
6891
6892
6893
File: libc.info, Node: Conversion Specifier Options, Next: Defining the Output Handler, Prev: Registering New Conversions, Up: Customizing Printf
6894
6895
12.13.2 Conversion Specifier Options
6896
------------------------------------
6897
6898
If you define a meaning for `%A', what if the template contains `%+23A'
6899
or `%-#A'? To implement a sensible meaning for these, the handler when
6900
called needs to be able to get the options specified in the template.
6901
6902
Both the HANDLER-FUNCTION and ARGINFO-FUNCTION accept an argument
6903
that points to a `struct printf_info', which contains information about
6904
the options appearing in an instance of the conversion specifier. This
6905
data type is declared in the header file `printf.h'.
6906
6907
-- Type: struct printf_info
6908
This structure is used to pass information about the options
6909
appearing in an instance of a conversion specifier in a `printf'
6910
template string to the handler and arginfo functions for that
6911
specifier. It contains the following members:
6912
6913
`int prec'
6914
This is the precision specified. The value is `-1' if no
6915
precision was specified. If the precision was given as `*',
6916
the `printf_info' structure passed to the handler function
6917
contains the actual value retrieved from the argument list.
6918
But the structure passed to the arginfo function contains a
6919
value of `INT_MIN', since the actual value is not known.
6920
6921
`int width'
6922
This is the minimum field width specified. The value is `0'
6923
if no width was specified. If the field width was given as
6924
`*', the `printf_info' structure passed to the handler
6925
function contains the actual value retrieved from the
6926
argument list. But the structure passed to the arginfo
6927
function contains a value of `INT_MIN', since the actual
6928
value is not known.
6929
6930
`wchar_t spec'
6931
This is the conversion specifier character specified. It's
6932
stored in the structure so that you can register the same
6933
handler function for multiple characters, but still have a
6934
way to tell them apart when the handler function is called.
6935
6936
`unsigned int is_long_double'
6937
This is a boolean that is true if the `L', `ll', or `q' type
6938
modifier was specified. For integer conversions, this
6939
indicates `long long int', as opposed to `long double' for
6940
floating point conversions.
6941
6942
`unsigned int is_char'
6943
This is a boolean that is true if the `hh' type modifier was
6944
specified.
6945
6946
`unsigned int is_short'
6947
This is a boolean that is true if the `h' type modifier was
6948
specified.
6949
6950
`unsigned int is_long'
6951
This is a boolean that is true if the `l' type modifier was
6952
specified.
6953
6954
`unsigned int alt'
6955
This is a boolean that is true if the `#' flag was specified.
6956
6957
`unsigned int space'
6958
This is a boolean that is true if the ` ' flag was specified.
6959
6960
`unsigned int left'
6961
This is a boolean that is true if the `-' flag was specified.
6962
6963
`unsigned int showsign'
6964
This is a boolean that is true if the `+' flag was specified.
6965
6966
`unsigned int group'
6967
This is a boolean that is true if the `'' flag was specified.
6968
6969
`unsigned int extra'
6970
This flag has a special meaning depending on the context. It
6971
could be used freely by the user-defined handlers but when
6972
called from the `printf' function this variable always
6973
contains the value `0'.
6974
6975
`unsigned int wide'
6976
This flag is set if the stream is wide oriented.
6977
6978
`wchar_t pad'
6979
This is the character to use for padding the output to the
6980
minimum field width. The value is `'0'' if the `0' flag was
6981
specified, and `' '' otherwise.
6982
6983
6984
File: libc.info, Node: Defining the Output Handler, Next: Printf Extension Example, Prev: Conversion Specifier Options, Up: Customizing Printf
6985
6986
12.13.3 Defining the Output Handler
6987
-----------------------------------
6988
6989
Now let's look at how to define the handler and arginfo functions which
6990
are passed as arguments to `register_printf_function'.
6991
6992
*Compatibility Note:* The interface changed in GNU libc version 2.0.
6993
Previously the third argument was of type `va_list *'.
6994
6995
You should define your handler functions with a prototype like:
6996
6997
int FUNCTION (FILE *stream, const struct printf_info *info,
6998
const void *const *args)
6999
7000
The STREAM argument passed to the handler function is the stream to
7001
which it should write output.
7002
7003
The INFO argument is a pointer to a structure that contains
7004
information about the various options that were included with the
7005
conversion in the template string. You should not modify this structure
7006
inside your handler function. *Note Conversion Specifier Options::, for
7007
a description of this data structure.
7008
7009
The ARGS is a vector of pointers to the arguments data. The number
7010
of arguments was determined by calling the argument information
7011
function provided by the user.
7012
7013
Your handler function should return a value just like `printf' does:
7014
it should return the number of characters it has written, or a negative
7015
value to indicate an error.
7016
7017
-- Data Type: printf_function
7018
This is the data type that a handler function should have.
7019
7020
If you are going to use `parse_printf_format' in your application,
7021
you must also define a function to pass as the ARGINFO-FUNCTION
7022
argument for each new conversion you install with
7023
`register_printf_function'.
7024
7025
You have to define these functions with a prototype like:
7026
7027
int FUNCTION (const struct printf_info *info,
7028
size_t n, int *argtypes)
7029
7030
The return value from the function should be the number of arguments
7031
the conversion expects. The function should also fill in no more than
7032
N elements of the ARGTYPES array with information about the types of
7033
each of these arguments. This information is encoded using the various
7034
`PA_' macros. (You will notice that this is the same calling
7035
convention `parse_printf_format' itself uses.)
7036
7037
-- Data Type: printf_arginfo_function
7038
This type is used to describe functions that return information
7039
about the number and type of arguments used by a conversion
7040
specifier.
7041
7042
7043
File: libc.info, Node: Printf Extension Example, Next: Predefined Printf Handlers, Prev: Defining the Output Handler, Up: Customizing Printf
7044
7045
12.13.4 `printf' Extension Example
7046
----------------------------------
7047
7048
Here is an example showing how to define a `printf' handler function.
7049
This program defines a data structure called a `Widget' and defines the
7050
`%W' conversion to print information about `Widget *' arguments,
7051
including the pointer value and the name stored in the data structure.
7052
The `%W' conversion supports the minimum field width and
7053
left-justification options, but ignores everything else.
7054
7055
#include <stdio.h>
7056
#include <stdlib.h>
7057
#include <printf.h>
7058
7059
typedef struct
7060
{
7061
char *name;
7062
}
7063
Widget;
7064
7065
int
7066
print_widget (FILE *stream,
7067
const struct printf_info *info,
7068
const void *const *args)
7069
{
7070
const Widget *w;
7071
char *buffer;
7072
int len;
7073
7074
/* Format the output into a string. */
7075
w = *((const Widget **) (args[0]));
7076
len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
7077
if (len == -1)
7078
return -1;
7079
7080
/* Pad to the minimum field width and print to the stream. */
7081
len = fprintf (stream, "%*s",
7082
(info->left ? -info->width : info->width),
7083
buffer);
7084
7085
/* Clean up and return. */
7086
free (buffer);
7087
return len;
7088
}
7089
7090
7091
int
7092
print_widget_arginfo (const struct printf_info *info, size_t n,
7093
int *argtypes)
7094
{
7095
/* We always take exactly one argument and this is a pointer to the
7096
structure.. */
7097
if (n > 0)
7098
argtypes[0] = PA_POINTER;
7099
return 1;
7100
}
7101
7102
7103
int
7104
main (void)
7105
{
7106
/* Make a widget to print. */
7107
Widget mywidget;
7108
mywidget.name = "mywidget";
7109
7110
/* Register the print function for widgets. */
7111
register_printf_function ('W', print_widget, print_widget_arginfo);
7112
7113
/* Now print the widget. */
7114
printf ("|%W|\n", &mywidget);
7115
printf ("|%35W|\n", &mywidget);
7116
printf ("|%-35W|\n", &mywidget);
7117
7118
return 0;
7119
}
7120
7121
The output produced by this program looks like:
7122
7123
|<Widget 0xffeffb7c: mywidget>|
7124
| <Widget 0xffeffb7c: mywidget>|
7125
|<Widget 0xffeffb7c: mywidget> |
7126
7127
7128
File: libc.info, Node: Predefined Printf Handlers, Prev: Printf Extension Example, Up: Customizing Printf
7129
7130
12.13.5 Predefined `printf' Handlers
7131
------------------------------------
7132
7133
The GNU libc also contains a concrete and useful application of the
7134
`printf' handler extension. There are two functions available which
7135
implement a special way to print floating-point numbers.
7136
7137
-- Function: int printf_size (FILE *FP, const struct printf_info
7138
*INFO, const void *const *ARGS)
7139
Print a given floating point number as for the format `%f' except
7140
that there is a postfix character indicating the divisor for the
7141
number to make this less than 1000. There are two possible
7142
divisors: powers of 1024 or powers of 1000. Which one is used
7143
depends on the format character specified while registered this
7144
handler. If the character is of lower case, 1024 is used. For
7145
upper case characters, 1000 is used.
7146
7147
The postfix tag corresponds to bytes, kilobytes, megabytes,
7148
gigabytes, etc. The full table is:
7149
7150
+------+--------------+--------+--------+---------------+
7151
|low|Multiplier|From|Upper|Multiplier|
7152
|' '|1||' '|1|
7153
|k|2^10 (1024)|kilo|K|10^3 (1000)|
7154
|m|2^20|mega|M|10^6|
7155
|g|2^30|giga|G|10^9|
7156
|t|2^40|tera|T|10^12|
7157
|p|2^50|peta|P|10^15|
7158
|e|2^60|exa|E|10^18|
7159
|z|2^70|zetta|Z|10^21|
7160
|y|2^80|yotta|Y|10^24|
7161
7162
The default precision is 3, i.e., 1024 is printed with a lower-case
7163
format character as if it were `%.3fk' and will yield `1.000k'.
7164
7165
Due to the requirements of `register_printf_function' we must also
7166
provide the function which returns information about the arguments.
7167
7168
-- Function: int printf_size_info (const struct printf_info *INFO,
7169
size_t N, int *ARGTYPES)
7170
This function will return in ARGTYPES the information about the
7171
used parameters in the way the `vfprintf' implementation expects
7172
it. The format always takes one argument.
7173
7174
To use these functions both functions must be registered with a call
7175
like
7176
7177
register_printf_function ('B', printf_size, printf_size_info);
7178
7179
Here we register the functions to print numbers as powers of 1000
7180
since the format character `'B'' is an upper-case character. If we
7181
would additionally use `'b'' in a line like
7182
7183
register_printf_function ('b', printf_size, printf_size_info);
7184
7185
we could also print using a power of 1024. Please note that all that is
7186
different in these two lines is the format specifier. The
7187
`printf_size' function knows about the difference between lower and
7188
upper case format specifiers.
7189
7190
The use of `'B'' and `'b'' is no coincidence. Rather it is the
7191
preferred way to use this functionality since it is available on some
7192
other systems which also use format specifiers.
7193
7194
7195
File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev: Customizing Printf, Up: I/O on Streams
7196
7197
12.14 Formatted Input
7198
=====================
7199
7200
The functions described in this section (`scanf' and related functions)
7201
provide facilities for formatted input analogous to the formatted
7202
output facilities. These functions provide a mechanism for reading
7203
arbitrary values under the control of a "format string" or "template
7204
string".
7205
7206
* Menu:
7207
7208
* Formatted Input Basics:: Some basics to get you started.
7209
* Input Conversion Syntax:: Syntax of conversion specifications.
7210
* Table of Input Conversions:: Summary of input conversions and what they do.
7211
* Numeric Input Conversions:: Details of conversions for reading numbers.
7212
* String Input Conversions:: Details of conversions for reading strings.
7213
* Dynamic String Input:: String conversions that `malloc' the buffer.
7214
* Other Input Conversions:: Details of miscellaneous other conversions.
7215
* Formatted Input Functions:: Descriptions of the actual functions.
7216
* Variable Arguments Input:: `vscanf' and friends.
7217
7218
7219
File: libc.info, Node: Formatted Input Basics, Next: Input Conversion Syntax, Up: Formatted Input
7220
7221
12.14.1 Formatted Input Basics
7222
------------------------------
7223
7224
Calls to `scanf' are superficially similar to calls to `printf' in that
7225
arbitrary arguments are read under the control of a template string.
7226
While the syntax of the conversion specifications in the template is
7227
very similar to that for `printf', the interpretation of the template
7228
is oriented more towards free-format input and simple pattern matching,
7229
rather than fixed-field formatting. For example, most `scanf'
7230
conversions skip over any amount of "white space" (including spaces,
7231
tabs, and newlines) in the input file, and there is no concept of
7232
precision for the numeric input conversions as there is for the
7233
corresponding output conversions. Ordinarily, non-whitespace
7234
characters in the template are expected to match characters in the
7235
input stream exactly, but a matching failure is distinct from an input
7236
error on the stream.
7237
7238
Another area of difference between `scanf' and `printf' is that you
7239
must remember to supply pointers rather than immediate values as the
7240
optional arguments to `scanf'; the values that are read are stored in
7241
the objects that the pointers point to. Even experienced programmers
7242
tend to forget this occasionally, so if your program is getting strange
7243
errors that seem to be related to `scanf', you might want to
7244
double-check this.
7245
7246
When a "matching failure" occurs, `scanf' returns immediately,
7247
leaving the first non-matching character as the next character to be
7248
read from the stream. The normal return value from `scanf' is the
7249
number of values that were assigned, so you can use this to determine if
7250
a matching error happened before all the expected values were read.
7251
7252
The `scanf' function is typically used for things like reading in
7253
the contents of tables. For example, here is a function that uses
7254
`scanf' to initialize an array of `double':
7255
7256
void
7257
readarray (double *array, int n)
7258
{
7259
int i;
7260
for (i=0; i<n; i++)
7261
if (scanf (" %lf", &(array[i])) != 1)
7262
invalid_input_error ();
7263
}
7264
7265
The formatted input functions are not used as frequently as the
7266
formatted output functions. Partly, this is because it takes some care
7267
to use them properly. Another reason is that it is difficult to recover
7268
from a matching error.
7269
7270
If you are trying to read input that doesn't match a single, fixed
7271
pattern, you may be better off using a tool such as Flex to generate a
7272
lexical scanner, or Bison to generate a parser, rather than using
7273
`scanf'. For more information about these tools, see *note Top:
7274
(flex.info)Top, and *note Top: (bison.info)Top.
7275
7276
7277
File: libc.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input Basics, Up: Formatted Input
7278
7279
12.14.2 Input Conversion Syntax
7280
-------------------------------
7281
7282
A `scanf' template string is a string that contains ordinary multibyte
7283
characters interspersed with conversion specifications that start with
7284
`%'.
7285
7286
Any whitespace character (as defined by the `isspace' function;
7287
*note Classification of Characters::) in the template causes any number
7288
of whitespace characters in the input stream to be read and discarded.
7289
The whitespace characters that are matched need not be exactly the same
7290
whitespace characters that appear in the template string. For example,
7291
write ` , ' in the template to recognize a comma with optional
7292
whitespace before and after.
7293
7294
Other characters in the template string that are not part of
7295
conversion specifications must match characters in the input stream
7296
exactly; if this is not the case, a matching failure occurs.
7297
7298
The conversion specifications in a `scanf' template string have the
7299
general form:
7300
7301
% FLAGS WIDTH TYPE CONVERSION
7302
7303
In more detail, an input conversion specification consists of an
7304
initial `%' character followed in sequence by:
7305
7306
* An optional "flag character" `*', which says to ignore the text
7307
read for this specification. When `scanf' finds a conversion
7308
specification that uses this flag, it reads input as directed by
7309
the rest of the conversion specification, but it discards this
7310
input, does not use a pointer argument, and does not increment the
7311
count of successful assignments.
7312
7313
* An optional flag character `a' (valid with string conversions only)
7314
which requests allocation of a buffer long enough to store the
7315
string in. (This is a GNU extension.) *Note Dynamic String
7316
Input::.
7317
7318
* An optional decimal integer that specifies the "maximum field
7319
width". Reading of characters from the input stream stops either
7320
when this maximum is reached or when a non-matching character is
7321
found, whichever happens first. Most conversions discard initial
7322
whitespace characters (those that don't are explicitly
7323
documented), and these discarded characters don't count towards
7324
the maximum field width. String input conversions store a null
7325
character to mark the end of the input; the maximum field width
7326
does not include this terminator.
7327
7328
* An optional "type modifier character". For example, you can
7329
specify a type modifier of `l' with integer conversions such as
7330
`%d' to specify that the argument is a pointer to a `long int'
7331
rather than a pointer to an `int'.
7332
7333
* A character that specifies the conversion to be applied.
7334
7335
The exact options that are permitted and how they are interpreted
7336
vary between the different conversion specifiers. See the descriptions
7337
of the individual conversions for information about the particular
7338
options that they allow.
7339
7340
With the `-Wformat' option, the GNU C compiler checks calls to
7341
`scanf' and related functions. It examines the format string and
7342
verifies that the correct number and types of arguments are supplied.
7343
There is also a GNU C syntax to tell the compiler that a function you
7344
write uses a `scanf'-style format string. *Note Declaring Attributes
7345
of Functions: (gcc.info)Function Attributes, for more information.
7346
7347
7348
File: libc.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: Formatted Input
7349
7350
12.14.3 Table of Input Conversions
7351
----------------------------------
7352
7353
Here is a table that summarizes the various conversion specifications:
7354
7355
`%d'
7356
Matches an optionally signed integer written in decimal. *Note
7357
Numeric Input Conversions::.
7358
7359
`%i'
7360
Matches an optionally signed integer in any of the formats that
7361
the C language defines for specifying an integer constant. *Note
7362
Numeric Input Conversions::.
7363
7364
`%o'
7365
Matches an unsigned integer written in octal radix. *Note Numeric
7366
Input Conversions::.
7367
7368
`%u'
7369
Matches an unsigned integer written in decimal radix. *Note
7370
Numeric Input Conversions::.
7371
7372
`%x', `%X'
7373
Matches an unsigned integer written in hexadecimal radix. *Note
7374
Numeric Input Conversions::.
7375
7376
`%e', `%f', `%g', `%E', `%G'
7377
Matches an optionally signed floating-point number. *Note Numeric
7378
Input Conversions::.
7379
7380
`%s'
7381
Matches a string containing only non-whitespace characters. *Note
7382
String Input Conversions::. The presence of the `l' modifier
7383
determines whether the output is stored as a wide character string
7384
or a multibyte string. If `%s' is used in a wide character
7385
function the string is converted as with multiple calls to
7386
`wcrtomb' into a multibyte string. This means that the buffer
7387
must provide room for `MB_CUR_MAX' bytes for each wide character
7388
read. In case `%ls' is used in a multibyte function the result is
7389
converted into wide characters as with multiple calls of `mbrtowc'
7390
before being stored in the user provided buffer.
7391
7392
`%S'
7393
This is an alias for `%ls' which is supported for compatibility
7394
with the Unix standard.
7395
7396
`%['
7397
Matches a string of characters that belong to a specified set.
7398
*Note String Input Conversions::. The presence of the `l' modifier
7399
determines whether the output is stored as a wide character string
7400
or a multibyte string. If `%[' is used in a wide character
7401
function the string is converted as with multiple calls to
7402
`wcrtomb' into a multibyte string. This means that the buffer
7403
must provide room for `MB_CUR_MAX' bytes for each wide character
7404
read. In case `%l[' is used in a multibyte function the result is
7405
converted into wide characters as with multiple calls of `mbrtowc'
7406
before being stored in the user provided buffer.
7407
7408
`%c'
7409
Matches a string of one or more characters; the number of
7410
characters read is controlled by the maximum field width given for
7411
the conversion. *Note String Input Conversions::.
7412
7413
If the `%c' is used in a wide stream function the read value is
7414
converted from a wide character to the corresponding multibyte
7415
character before storing it. Note that this conversion can
7416
produce more than one byte of output and therefore the provided
7417
buffer be large enough for up to `MB_CUR_MAX' bytes for each
7418
character. If `%lc' is used in a multibyte function the input is
7419
treated as a multibyte sequence (and not bytes) and the result is
7420
converted as with calls to `mbrtowc'.
7421
7422
`%C'
7423
This is an alias for `%lc' which is supported for compatibility
7424
with the Unix standard.
7425
7426
`%p'
7427
Matches a pointer value in the same implementation-defined format
7428
used by the `%p' output conversion for `printf'. *Note Other
7429
Input Conversions::.
7430
7431
`%n'
7432
This conversion doesn't read any characters; it records the number
7433
of characters read so far by this call. *Note Other Input
7434
Conversions::.
7435
7436
`%%'
7437
This matches a literal `%' character in the input stream. No
7438
corresponding argument is used. *Note Other Input Conversions::.
7439
7440
If the syntax of a conversion specification is invalid, the behavior
7441
is undefined. If there aren't enough function arguments provided to
7442
supply addresses for all the conversion specifications in the template
7443
strings that perform assignments, or if the arguments are not of the
7444
correct types, the behavior is also undefined. On the other hand, extra
7445
arguments are simply ignored.
7446
7447
7448
File: libc.info, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: Formatted Input
7449
7450
12.14.4 Numeric Input Conversions
7451
---------------------------------
7452
7453
This section describes the `scanf' conversions for reading numeric
7454
values.
7455
7456
The `%d' conversion matches an optionally signed integer in decimal
7457
radix. The syntax that is recognized is the same as that for the
7458
`strtol' function (*note Parsing of Integers::) with the value `10' for
7459
the BASE argument.
7460
7461
The `%i' conversion matches an optionally signed integer in any of
7462
the formats that the C language defines for specifying an integer
7463
constant. The syntax that is recognized is the same as that for the
7464
`strtol' function (*note Parsing of Integers::) with the value `0' for
7465
the BASE argument. (You can print integers in this syntax with
7466
`printf' by using the `#' flag character with the `%x', `%o', or `%d'
7467
conversion. *Note Integer Conversions::.)
7468
7469
For example, any of the strings `10', `0xa', or `012' could be read
7470
in as integers under the `%i' conversion. Each of these specifies a
7471
number with decimal value `10'.
7472
7473
The `%o', `%u', and `%x' conversions match unsigned integers in
7474
octal, decimal, and hexadecimal radices, respectively. The syntax that
7475
is recognized is the same as that for the `strtoul' function (*note
7476
Parsing of Integers::) with the appropriate value (`8', `10', or `16')
7477
for the BASE argument.
7478
7479
The `%X' conversion is identical to the `%x' conversion. They both
7480
permit either uppercase or lowercase letters to be used as digits.
7481
7482
The default type of the corresponding argument for the `%d' and `%i'
7483
conversions is `int *', and `unsigned int *' for the other integer
7484
conversions. You can use the following type modifiers to specify other
7485
sizes of integer:
7486
7487
`hh'
7488
Specifies that the argument is a `signed char *' or `unsigned char
7489
*'.
7490
7491
This modifier was introduced in ISO C99.
7492
7493
`h'
7494
Specifies that the argument is a `short int *' or `unsigned short
7495
int *'.
7496
7497
`j'
7498
Specifies that the argument is a `intmax_t *' or `uintmax_t *'.
7499
7500
This modifier was introduced in ISO C99.
7501
7502
`l'
7503
Specifies that the argument is a `long int *' or `unsigned long
7504
int *'. Two `l' characters is like the `L' modifier, below.
7505
7506
If used with `%c' or `%s' the corresponding parameter is
7507
considered as a pointer to a wide character or wide character
7508
string respectively. This use of `l' was introduced in
7509
Amendment 1 to ISO C90.
7510
7511
`ll'
7512
`L'
7513
`q'
7514
Specifies that the argument is a `long long int *' or `unsigned
7515
long long int *'. (The `long long' type is an extension supported
7516
by the GNU C compiler. For systems that don't provide extra-long
7517
integers, this is the same as `long int'.)
7518
7519
The `q' modifier is another name for the same thing, which comes
7520
from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
7521
7522
`t'
7523
Specifies that the argument is a `ptrdiff_t *'.
7524
7525
This modifier was introduced in ISO C99.
7526
7527
`z'
7528
Specifies that the argument is a `size_t *'.
7529
7530
This modifier was introduced in ISO C99.
7531
7532
All of the `%e', `%f', `%g', `%E', and `%G' input conversions are
7533
interchangeable. They all match an optionally signed floating point
7534
number, in the same syntax as for the `strtod' function (*note Parsing
7535
of Floats::).
7536
7537
For the floating-point input conversions, the default argument type
7538
is `float *'. (This is different from the corresponding output
7539
conversions, where the default type is `double'; remember that `float'
7540
arguments to `printf' are converted to `double' by the default argument
7541
promotions, but `float *' arguments are not promoted to `double *'.)
7542
You can specify other sizes of float using these type modifiers:
7543
7544
`l'
7545
Specifies that the argument is of type `double *'.
7546
7547
`L'
7548
Specifies that the argument is of type `long double *'.
7549
7550
For all the above number parsing formats there is an additional
7551
optional flag `''. When this flag is given the `scanf' function
7552
expects the number represented in the input string to be formatted
7553
according to the grouping rules of the currently selected locale (*note
7554
General Numeric::).
7555
7556
If the `"C"' or `"POSIX"' locale is selected there is no difference.
7557
But for a locale which specifies values for the appropriate fields in
7558
the locale the input must have the correct form in the input.
7559
Otherwise the longest prefix with a correct form is processed.
7560
7561
7562
File: libc.info, Node: String Input Conversions, Next: Dynamic String Input, Prev: Numeric Input Conversions, Up: Formatted Input
7563
7564
12.14.5 String Input Conversions
7565
--------------------------------
7566
7567
This section describes the `scanf' input conversions for reading string
7568
and character values: `%s', `%S', `%[', `%c', and `%C'.
7569
7570
You have two options for how to receive the input from these
7571
conversions:
7572
7573
* Provide a buffer to store it in. This is the default. You should
7574
provide an argument of type `char *' or `wchar_t *' (the latter of
7575
the `l' modifier is present).
7576
7577
*Warning:* To make a robust program, you must make sure that the
7578
input (plus its terminating null) cannot possibly exceed the size
7579
of the buffer you provide. In general, the only way to do this is
7580
to specify a maximum field width one less than the buffer size.
7581
*If you provide the buffer, always specify a maximum field width
7582
to prevent overflow.*
7583
7584
* Ask `scanf' to allocate a big enough buffer, by specifying the `a'
7585
flag character. This is a GNU extension. You should provide an
7586
argument of type `char **' for the buffer address to be stored in.
7587
*Note Dynamic String Input::.
7588
7589
The `%c' conversion is the simplest: it matches a fixed number of
7590
characters, always. The maximum field width says how many characters to
7591
read; if you don't specify the maximum, the default is 1. This
7592
conversion doesn't append a null character to the end of the text it
7593
reads. It also does not skip over initial whitespace characters. It
7594
reads precisely the next N characters, and fails if it cannot get that
7595
many. Since there is always a maximum field width with `%c' (whether
7596
specified, or 1 by default), you can always prevent overflow by making
7597
the buffer long enough.
7598
7599
If the format is `%lc' or `%C' the function stores wide characters
7600
which are converted using the conversion determined at the time the
7601
stream was opened from the external byte stream. The number of bytes
7602
read from the medium is limited by `MB_CUR_LEN * N' but at most N wide
7603
character get stored in the output string.
7604
7605
The `%s' conversion matches a string of non-whitespace characters.
7606
It skips and discards initial whitespace, but stops when it encounters
7607
more whitespace after having read something. It stores a null character
7608
at the end of the text that it reads.
7609
7610
For example, reading the input:
7611
7612
hello, world
7613
7614
with the conversion `%10c' produces `" hello, wo"', but reading the
7615
same input with the conversion `%10s' produces `"hello,"'.
7616
7617
*Warning:* If you do not specify a field width for `%s', then the
7618
number of characters read is limited only by where the next whitespace
7619
character appears. This almost certainly means that invalid input can
7620
make your program crash--which is a bug.
7621
7622
The `%ls' and `%S' format are handled just like `%s' except that the
7623
external byte sequence is converted using the conversion associated
7624
with the stream to wide characters with their own encoding. A width or
7625
precision specified with the format do not directly determine how many
7626
bytes are read from the stream since they measure wide characters. But
7627
an upper limit can be computed by multiplying the value of the width or
7628
precision by `MB_CUR_MAX'.
7629
7630
To read in characters that belong to an arbitrary set of your choice,
7631
use the `%[' conversion. You specify the set between the `[' character
7632
and a following `]' character, using the same syntax used in regular
7633
expressions. As special cases:
7634
7635
* A literal `]' character can be specified as the first character of
7636
the set.
7637
7638
* An embedded `-' character (that is, one that is not the first or
7639
last character of the set) is used to specify a range of
7640
characters.
7641
7642
* If a caret character `^' immediately follows the initial `[', then
7643
the set of allowed input characters is the everything _except_ the
7644
characters listed.
7645
7646
The `%[' conversion does not skip over initial whitespace characters.
7647
7648
Here are some examples of `%[' conversions and what they mean:
7649
7650
`%25[1234567890]'
7651
Matches a string of up to 25 digits.
7652
7653
`%25[][]'
7654
Matches a string of up to 25 square brackets.
7655
7656
`%25[^ \f\n\r\t\v]'
7657
Matches a string up to 25 characters long that doesn't contain any
7658
of the standard whitespace characters. This is slightly different
7659
from `%s', because if the input begins with a whitespace character,
7660
`%[' reports a matching failure while `%s' simply discards the
7661
initial whitespace.
7662
7663
`%25[a-z]'
7664
Matches up to 25 lowercase characters.
7665
7666
As for `%c' and `%s' the `%[' format is also modified to produce
7667
wide characters if the `l' modifier is present. All what is said about
7668
`%ls' above is true for `%l['.
7669
7670
One more reminder: the `%s' and `%[' conversions are *dangerous* if
7671
you don't specify a maximum width or use the `a' flag, because input
7672
too long would overflow whatever buffer you have provided for it. No
7673
matter how long your buffer is, a user could supply input that is
7674
longer. A well-written program reports invalid input with a
7675
comprehensible error message, not with a crash.
7676
7677
7678
File: libc.info, Node: Dynamic String Input, Next: Other Input Conversions, Prev: String Input Conversions, Up: Formatted Input
7679
7680
12.14.6 Dynamically Allocating String Conversions
7681
-------------------------------------------------
7682
7683
A GNU extension to formatted input lets you safely read a string with no
7684
maximum size. Using this feature, you don't supply a buffer; instead,
7685
`scanf' allocates a buffer big enough to hold the data and gives you
7686
its address. To use this feature, write `a' as a flag character, as in
7687
`%as' or `%a[0-9a-z]'.
7688
7689
The pointer argument you supply for where to store the input should
7690
have type `char **'. The `scanf' function allocates a buffer and
7691
stores its address in the word that the argument points to. You should
7692
free the buffer with `free' when you no longer need it.
7693
7694
Here is an example of using the `a' flag with the `%[...]'
7695
conversion specification to read a "variable assignment" of the form
7696
`VARIABLE = VALUE'.
7697
7698
{
7699
char *variable, *value;
7700
7701
if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
7702
&variable, &value))
7703
{
7704
invalid_input_error ();
7705
return 0;
7706
}
7707
7708
...
7709
}
7710
7711
7712
File: libc.info, Node: Other Input Conversions, Next: Formatted Input Functions, Prev: Dynamic String Input, Up: Formatted Input
7713
7714
12.14.7 Other Input Conversions
7715
-------------------------------
7716
7717
This section describes the miscellaneous input conversions.
7718
7719
The `%p' conversion is used to read a pointer value. It recognizes
7720
the same syntax used by the `%p' output conversion for `printf' (*note
7721
Other Output Conversions::); that is, a hexadecimal number just as the
7722
`%x' conversion accepts. The corresponding argument should be of type
7723
`void **'; that is, the address of a place to store a pointer.
7724
7725
The resulting pointer value is not guaranteed to be valid if it was
7726
not originally written during the same program execution that reads it
7727
in.
7728
7729
The `%n' conversion produces the number of characters read so far by
7730
this call. The corresponding argument should be of type `int *'. This
7731
conversion works in the same way as the `%n' conversion for `printf';
7732
see *note Other Output Conversions::, for an example.
7733
7734
The `%n' conversion is the only mechanism for determining the
7735
success of literal matches or conversions with suppressed assignments.
7736
If the `%n' follows the locus of a matching failure, then no value is
7737
stored for it since `scanf' returns before processing the `%n'. If you
7738
store `-1' in that argument slot before calling `scanf', the presence
7739
of `-1' after `scanf' indicates an error occurred before the `%n' was
7740
reached.
7741
7742
Finally, the `%%' conversion matches a literal `%' character in the
7743
input stream, without using an argument. This conversion does not
7744
permit any flags, field width, or type modifier to be specified.
7745
7746
7747
File: libc.info, Node: Formatted Input Functions, Next: Variable Arguments Input, Prev: Other Input Conversions, Up: Formatted Input
7748
7749
12.14.8 Formatted Input Functions
7750
---------------------------------
7751
7752
Here are the descriptions of the functions for performing formatted
7753
input. Prototypes for these functions are in the header file `stdio.h'.
7754
7755
-- Function: int scanf (const char *TEMPLATE, ...)
7756
The `scanf' function reads formatted input from the stream `stdin'
7757
under the control of the template string TEMPLATE. The optional
7758
arguments are pointers to the places which receive the resulting
7759
values.
7760
7761
The return value is normally the number of successful assignments.
7762
If an end-of-file condition is detected before any matches are
7763
performed, including matches against whitespace and literal
7764
characters in the template, then `EOF' is returned.
7765
7766
-- Function: int wscanf (const wchar_t *TEMPLATE, ...)
7767
The `wscanf' function reads formatted input from the stream
7768
`stdin' under the control of the template string TEMPLATE. The
7769
optional arguments are pointers to the places which receive the
7770
resulting values.
7771
7772
The return value is normally the number of successful assignments.
7773
If an end-of-file condition is detected before any matches are
7774
performed, including matches against whitespace and literal
7775
characters in the template, then `WEOF' is returned.
7776
7777
-- Function: int fscanf (FILE *STREAM, const char *TEMPLATE, ...)
7778
This function is just like `scanf', except that the input is read
7779
from the stream STREAM instead of `stdin'.
7780
7781
-- Function: int fwscanf (FILE *STREAM, const wchar_t *TEMPLATE, ...)
7782
This function is just like `wscanf', except that the input is read
7783
from the stream STREAM instead of `stdin'.
7784
7785
-- Function: int sscanf (const char *S, const char *TEMPLATE, ...)
7786
This is like `scanf', except that the characters are taken from the
7787
null-terminated string S instead of from a stream. Reaching the
7788
end of the string is treated as an end-of-file condition.
7789
7790
The behavior of this function is undefined if copying takes place
7791
between objects that overlap--for example, if S is also given as
7792
an argument to receive a string read under control of the `%s',
7793
`%S', or `%[' conversion.
7794
7795
-- Function: int swscanf (const wchar_t *WS, const char *TEMPLATE, ...)
7796
This is like `wscanf', except that the characters are taken from
7797
the null-terminated string WS instead of from a stream. Reaching
7798
the end of the string is treated as an end-of-file condition.
7799
7800
The behavior of this function is undefined if copying takes place
7801
between objects that overlap--for example, if WS is also given as
7802
an argument to receive a string read under control of the `%s',
7803
`%S', or `%[' conversion.
7804
7805
7806
File: libc.info, Node: Variable Arguments Input, Prev: Formatted Input Functions, Up: Formatted Input
7807
7808
12.14.9 Variable Arguments Input Functions
7809
------------------------------------------
7810
7811
The functions `vscanf' and friends are provided so that you can define
7812
your own variadic `scanf'-like functions that make use of the same
7813
internals as the built-in formatted output functions. These functions
7814
are analogous to the `vprintf' series of output functions. *Note
7815
Variable Arguments Output::, for important information on how to use
7816
them.
7817
7818
*Portability Note:* The functions listed in this section were
7819
introduced in ISO C99 and were before available as GNU extensions.
7820
7821
-- Function: int vscanf (const char *TEMPLATE, va_list AP)
7822
This function is similar to `scanf', but instead of taking a
7823
variable number of arguments directly, it takes an argument list
7824
pointer AP of type `va_list' (*note Variadic Functions::).
7825
7826
-- Function: int vwscanf (const wchar_t *TEMPLATE, va_list AP)
7827
This function is similar to `wscanf', but instead of taking a
7828
variable number of arguments directly, it takes an argument list
7829
pointer AP of type `va_list' (*note Variadic Functions::).
7830
7831
-- Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
7832
AP)
7833
This is the equivalent of `fscanf' with the variable argument list
7834
specified directly as for `vscanf'.
7835
7836
-- Function: int vfwscanf (FILE *STREAM, const wchar_t *TEMPLATE,
7837
va_list AP)
7838
This is the equivalent of `fwscanf' with the variable argument list
7839
specified directly as for `vwscanf'.
7840
7841
-- Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
7842
AP)
7843
This is the equivalent of `sscanf' with the variable argument list
7844
specified directly as for `vscanf'.
7845
7846
-- Function: int vswscanf (const wchar_t *S, const wchar_t *TEMPLATE,
7847
va_list AP)
7848
This is the equivalent of `swscanf' with the variable argument list
7849
specified directly as for `vwscanf'.
7850
7851
In GNU C, there is a special construct you can use to let the
7852
compiler know that a function uses a `scanf'-style format string. Then
7853
it can check the number and types of arguments in each call to the
7854
function, and warn you when they do not match the format string. For
7855
details, see *note Declaring Attributes of Functions:
7856
(gcc.info)Function Attributes.
7857
7858
7859
File: libc.info, Node: EOF and Errors, Next: Error Recovery, Prev: Formatted Input, Up: I/O on Streams
7860
7861
12.15 End-Of-File and Errors
7862
============================
7863
7864
Many of the functions described in this chapter return the value of the
7865
macro `EOF' to indicate unsuccessful completion of the operation.
7866
Since `EOF' is used to report both end of file and random errors, it's
7867
often better to use the `feof' function to check explicitly for end of
7868
file and `ferror' to check for errors. These functions check
7869
indicators that are part of the internal state of the stream object,
7870
indicators set if the appropriate condition was detected by a previous
7871
I/O operation on that stream.
7872
7873
-- Macro: int EOF
7874
This macro is an integer value that is returned by a number of
7875
narrow stream functions to indicate an end-of-file condition, or
7876
some other error situation. With the GNU library, `EOF' is `-1'.
7877
In other libraries, its value may be some other negative number.
7878
7879
This symbol is declared in `stdio.h'.
7880
7881
-- Macro: int WEOF
7882
This macro is an integer value that is returned by a number of wide
7883
stream functions to indicate an end-of-file condition, or some
7884
other error situation. With the GNU library, `WEOF' is `-1'. In
7885
other libraries, its value may be some other negative number.
7886
7887
This symbol is declared in `wchar.h'.
7888
7889
-- Function: int feof (FILE *STREAM)
7890
The `feof' function returns nonzero if and only if the end-of-file
7891
indicator for the stream STREAM is set.
7892
7893
This symbol is declared in `stdio.h'.
7894
7895
-- Function: int feof_unlocked (FILE *STREAM)
7896
The `feof_unlocked' function is equivalent to the `feof' function
7897
except that it does not implicitly lock the stream.
7898
7899
This function is a GNU extension.
7900
7901
This symbol is declared in `stdio.h'.
7902
7903
-- Function: int ferror (FILE *STREAM)
7904
The `ferror' function returns nonzero if and only if the error
7905
indicator for the stream STREAM is set, indicating that an error
7906
has occurred on a previous operation on the stream.
7907
7908
This symbol is declared in `stdio.h'.
7909
7910
-- Function: int ferror_unlocked (FILE *STREAM)
7911
The `ferror_unlocked' function is equivalent to the `ferror'
7912
function except that it does not implicitly lock the stream.
7913
7914
This function is a GNU extension.
7915
7916
This symbol is declared in `stdio.h'.
7917
7918
In addition to setting the error indicator associated with the
7919
stream, the functions that operate on streams also set `errno' in the
7920
same way as the corresponding low-level functions that operate on file
7921
descriptors. For example, all of the functions that perform output to a
7922
stream--such as `fputc', `printf', and `fflush'--are implemented in
7923
terms of `write', and all of the `errno' error conditions defined for
7924
`write' are meaningful for these functions. For more information about
7925
the descriptor-level I/O functions, see *note Low-Level I/O::.
7926
7927
7928
File: libc.info, Node: Error Recovery, Next: Binary Streams, Prev: EOF and Errors, Up: I/O on Streams
7929
7930
12.16 Recovering from errors
7931
============================
7932
7933
You may explicitly clear the error and EOF flags with the `clearerr'
7934
function.
7935
7936
-- Function: void clearerr (FILE *STREAM)
7937
This function clears the end-of-file and error indicators for the
7938
stream STREAM.
7939
7940
The file positioning functions (*note File Positioning::) also
7941
clear the end-of-file indicator for the stream.
7942
7943
-- Function: void clearerr_unlocked (FILE *STREAM)
7944
The `clearerr_unlocked' function is equivalent to the `clearerr'
7945
function except that it does not implicitly lock the stream.
7946
7947
This function is a GNU extension.
7948
7949
Note that it is _not_ correct to just clear the error flag and retry
7950
a failed stream operation. After a failed write, any number of
7951
characters since the last buffer flush may have been committed to the
7952
file, while some buffered data may have been discarded. Merely retrying
7953
can thus cause lost or repeated data.
7954
7955
A failed read may leave the file pointer in an inappropriate
7956
position for a second try. In both cases, you should seek to a known
7957
position before retrying.
7958
7959
Most errors that can happen are not recoverable -- a second try will
7960
always fail again in the same way. So usually it is best to give up and
7961
report the error to the user, rather than install complicated recovery
7962
logic.
7963
7964
One important exception is `EINTR' (*note Interrupted Primitives::).
7965
Many stream I/O implementations will treat it as an ordinary error,
7966
which can be quite inconvenient. You can avoid this hassle by
7967
installing all signals with the `SA_RESTART' flag.
7968
7969
For similar reasons, setting nonblocking I/O on a stream's file
7970
descriptor is not usually advisable.
7971
7972
7973
File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: Error Recovery, Up: I/O on Streams
7974
7975
12.17 Text and Binary Streams
7976
=============================
7977
7978
The GNU system and other POSIX-compatible operating systems organize all
7979
files as uniform sequences of characters. However, some other systems
7980
make a distinction between files containing text and files containing
7981
binary data, and the input and output facilities of ISO C provide for
7982
this distinction. This section tells you how to write programs portable
7983
to such systems.
7984
7985
When you open a stream, you can specify either a "text stream" or a
7986
"binary stream". You indicate that you want a binary stream by
7987
specifying the `b' modifier in the OPENTYPE argument to `fopen'; see
7988
*note Opening Streams::. Without this option, `fopen' opens the file
7989
as a text stream.
7990
7991
Text and binary streams differ in several ways:
7992
7993
* The data read from a text stream is divided into "lines" which are
7994
terminated by newline (`'\n'') characters, while a binary stream is
7995
simply a long series of characters. A text stream might on some
7996
systems fail to handle lines more than 254 characters long
7997
(including the terminating newline character).
7998
7999
* On some systems, text files can contain only printing characters,
8000
horizontal tab characters, and newlines, and so text streams may
8001
not support other characters. However, binary streams can handle
8002
any character value.
8003
8004
* Space characters that are written immediately preceding a newline
8005
character in a text stream may disappear when the file is read in
8006
again.
8007
8008
* More generally, there need not be a one-to-one mapping between
8009
characters that are read from or written to a text stream, and the
8010
characters in the actual file.
8011
8012
Since a binary stream is always more capable and more predictable
8013
than a text stream, you might wonder what purpose text streams serve.
8014
Why not simply always use binary streams? The answer is that on these
8015
operating systems, text and binary streams use different file formats,
8016
and the only way to read or write "an ordinary file of text" that can
8017
work with other text-oriented programs is through a text stream.
8018
8019
In the GNU library, and on all POSIX systems, there is no difference
8020
between text streams and binary streams. When you open a stream, you
8021
get the same kind of stream regardless of whether you ask for binary.
8022
This stream can handle any file content, and has none of the
8023
restrictions that text streams sometimes have.
8024
8025
8026
File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev: Binary Streams, Up: I/O on Streams
8027
8028
12.18 File Positioning
8029
======================
8030
8031
The "file position" of a stream describes where in the file the stream
8032
is currently reading or writing. I/O on the stream advances the file
8033
position through the file. In the GNU system, the file position is
8034
represented as an integer, which counts the number of bytes from the
8035
beginning of the file. *Note File Position::.
8036
8037
During I/O to an ordinary disk file, you can change the file position
8038
whenever you wish, so as to read or write any portion of the file. Some
8039
other kinds of files may also permit this. Files which support changing
8040
the file position are sometimes referred to as "random-access" files.
8041
8042
You can use the functions in this section to examine or modify the
8043
file position indicator associated with a stream. The symbols listed
8044
below are declared in the header file `stdio.h'.
8045
8046
-- Function: long int ftell (FILE *STREAM)
8047
This function returns the current file position of the stream
8048
STREAM.
8049
8050
This function can fail if the stream doesn't support file
8051
positioning, or if the file position can't be represented in a
8052
`long int', and possibly for other reasons as well. If a failure
8053
occurs, a value of `-1' is returned.
8054
8055
-- Function: off_t ftello (FILE *STREAM)
8056
The `ftello' function is similar to `ftell', except that it
8057
returns a value of type `off_t'. Systems which support this type
8058
use it to describe all file positions, unlike the POSIX
8059
specification which uses a long int. The two are not necessarily
8060
the same size. Therefore, using ftell can lead to problems if the
8061
implementation is written on top of a POSIX compliant low-level
8062
I/O implementation, and using `ftello' is preferable whenever it
8063
is available.
8064
8065
If this function fails it returns `(off_t) -1'. This can happen
8066
due to missing support for file positioning or internal errors.
8067
Otherwise the return value is the current file position.
8068
8069
The function is an extension defined in the Unix Single
8070
Specification version 2.
8071
8072
When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
8073
32 bit system this function is in fact `ftello64'. I.e., the LFS
8074
interface transparently replaces the old interface.
8075
8076
-- Function: off64_t ftello64 (FILE *STREAM)
8077
This function is similar to `ftello' with the only difference that
8078
the return value is of type `off64_t'. This also requires that the
8079
stream STREAM was opened using either `fopen64', `freopen64', or
8080
`tmpfile64' since otherwise the underlying file operations to
8081
position the file pointer beyond the 2^31 bytes limit might fail.
8082
8083
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
8084
bits machine this function is available under the name `ftello'
8085
and so transparently replaces the old interface.
8086
8087
-- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
8088
The `fseek' function is used to change the file position of the
8089
stream STREAM. The value of WHENCE must be one of the constants
8090
`SEEK_SET', `SEEK_CUR', or `SEEK_END', to indicate whether the
8091
OFFSET is relative to the beginning of the file, the current file
8092
position, or the end of the file, respectively.
8093
8094
This function returns a value of zero if the operation was
8095
successful, and a nonzero value to indicate failure. A successful
8096
call also clears the end-of-file indicator of STREAM and discards
8097
any characters that were "pushed back" by the use of `ungetc'.
8098
8099
`fseek' either flushes any buffered output before setting the file
8100
position or else remembers it so it will be written later in its
8101
proper place in the file.
8102
8103
-- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE)
8104
This function is similar to `fseek' but it corrects a problem with
8105
`fseek' in a system with POSIX types. Using a value of type `long
8106
int' for the offset is not compatible with POSIX. `fseeko' uses
8107
the correct type `off_t' for the OFFSET parameter.
8108
8109
For this reason it is a good idea to prefer `ftello' whenever it is
8110
available since its functionality is (if different at all) closer
8111
the underlying definition.
8112
8113
The functionality and return value is the same as for `fseek'.
8114
8115
The function is an extension defined in the Unix Single
8116
Specification version 2.
8117
8118
When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
8119
32 bit system this function is in fact `fseeko64'. I.e., the LFS
8120
interface transparently replaces the old interface.
8121
8122
-- Function: int fseeko64 (FILE *STREAM, off64_t OFFSET, int WHENCE)
8123
This function is similar to `fseeko' with the only difference that
8124
the OFFSET parameter is of type `off64_t'. This also requires
8125
that the stream STREAM was opened using either `fopen64',
8126
`freopen64', or `tmpfile64' since otherwise the underlying file
8127
operations to position the file pointer beyond the 2^31 bytes
8128
limit might fail.
8129
8130
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
8131
bits machine this function is available under the name `fseeko'
8132
and so transparently replaces the old interface.
8133
8134
*Portability Note:* In non-POSIX systems, `ftell', `ftello', `fseek'
8135
and `fseeko' might work reliably only on binary streams. *Note Binary
8136
Streams::.
8137
8138
The following symbolic constants are defined for use as the WHENCE
8139
argument to `fseek'. They are also used with the `lseek' function
8140
(*note I/O Primitives::) and to specify offsets for file locks (*note
8141
Control Operations::).
8142
8143
-- Macro: int SEEK_SET
8144
This is an integer constant which, when used as the WHENCE
8145
argument to the `fseek' or `fseeko' function, specifies that the
8146
offset provided is relative to the beginning of the file.
8147
8148
-- Macro: int SEEK_CUR
8149
This is an integer constant which, when used as the WHENCE
8150
argument to the `fseek' or `fseeko' function, specifies that the
8151
offset provided is relative to the current file position.
8152
8153
-- Macro: int SEEK_END
8154
This is an integer constant which, when used as the WHENCE
8155
argument to the `fseek' or `fseeko' function, specifies that the
8156
offset provided is relative to the end of the file.
8157
8158
-- Function: void rewind (FILE *STREAM)
8159
The `rewind' function positions the stream STREAM at the beginning
8160
of the file. It is equivalent to calling `fseek' or `fseeko' on
8161
the STREAM with an OFFSET argument of `0L' and a WHENCE argument
8162
of `SEEK_SET', except that the return value is discarded and the
8163
error indicator for the stream is reset.
8164
8165
These three aliases for the `SEEK_...' constants exist for the sake
8166
of compatibility with older BSD systems. They are defined in two
8167
different header files: `fcntl.h' and `sys/file.h'.
8168
8169
`L_SET'
8170
An alias for `SEEK_SET'.
8171
8172
`L_INCR'
8173
An alias for `SEEK_CUR'.
8174
8175
`L_XTND'
8176
An alias for `SEEK_END'.
8177
8178
8179
File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams
8180
8181
12.19 Portable File-Position Functions
8182
======================================
8183
8184
On the GNU system, the file position is truly a character count. You
8185
can specify any character count value as an argument to `fseek' or
8186
`fseeko' and get reliable results for any random access file. However,
8187
some ISO C systems do not represent file positions in this way.
8188
8189
On some systems where text streams truly differ from binary streams,
8190
it is impossible to represent the file position of a text stream as a
8191
count of characters from the beginning of the file. For example, the
8192
file position on some systems must encode both a record offset within
8193
the file, and a character offset within the record.
8194
8195
As a consequence, if you want your programs to be portable to these
8196
systems, you must observe certain rules:
8197
8198
* The value returned from `ftell' on a text stream has no predictable
8199
relationship to the number of characters you have read so far.
8200
The only thing you can rely on is that you can use it subsequently
8201
as the OFFSET argument to `fseek' or `fseeko' to move back to the
8202
same file position.
8203
8204
* In a call to `fseek' or `fseeko' on a text stream, either the
8205
OFFSET must be zero, or WHENCE must be `SEEK_SET' and and the
8206
OFFSET must be the result of an earlier call to `ftell' on the
8207
same stream.
8208
8209
* The value of the file position indicator of a text stream is
8210
undefined while there are characters that have been pushed back
8211
with `ungetc' that haven't been read or discarded. *Note
8212
Unreading::.
8213
8214
But even if you observe these rules, you may still have trouble for
8215
long files, because `ftell' and `fseek' use a `long int' value to
8216
represent the file position. This type may not have room to encode all
8217
the file positions in a large file. Using the `ftello' and `fseeko'
8218
functions might help here since the `off_t' type is expected to be able
8219
to hold all file position values but this still does not help to handle
8220
additional information which must be associated with a file position.
8221
8222
So if you do want to support systems with peculiar encodings for the
8223
file positions, it is better to use the functions `fgetpos' and
8224
`fsetpos' instead. These functions represent the file position using
8225
the data type `fpos_t', whose internal representation varies from
8226
system to system.
8227
8228
These symbols are declared in the header file `stdio.h'.
8229
8230
-- Data Type: fpos_t
8231
This is the type of an object that can encode information about the
8232
file position of a stream, for use by the functions `fgetpos' and
8233
`fsetpos'.
8234
8235
In the GNU system, `fpos_t' is an opaque data structure that
8236
contains internal data to represent file offset and conversion
8237
state information. In other systems, it might have a different
8238
internal representation.
8239
8240
When compiling with `_FILE_OFFSET_BITS == 64' on a 32 bit machine
8241
this type is in fact equivalent to `fpos64_t' since the LFS
8242
interface transparently replaces the old interface.
8243
8244
-- Data Type: fpos64_t
8245
This is the type of an object that can encode information about the
8246
file position of a stream, for use by the functions `fgetpos64' and
8247
`fsetpos64'.
8248
8249
In the GNU system, `fpos64_t' is an opaque data structure that
8250
contains internal data to represent file offset and conversion
8251
state information. In other systems, it might have a different
8252
internal representation.
8253
8254
-- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
8255
This function stores the value of the file position indicator for
8256
the stream STREAM in the `fpos_t' object pointed to by POSITION.
8257
If successful, `fgetpos' returns zero; otherwise it returns a
8258
nonzero value and stores an implementation-defined positive value
8259
in `errno'.
8260
8261
When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
8262
32 bit system the function is in fact `fgetpos64'. I.e., the LFS
8263
interface transparently replaces the old interface.
8264
8265
-- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION)
8266
This function is similar to `fgetpos' but the file position is
8267
returned in a variable of type `fpos64_t' to which POSITION points.
8268
8269
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
8270
bits machine this function is available under the name `fgetpos'
8271
and so transparently replaces the old interface.
8272
8273
-- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION)
8274
This function sets the file position indicator for the stream
8275
STREAM to the position POSITION, which must have been set by a
8276
previous call to `fgetpos' on the same stream. If successful,
8277
`fsetpos' clears the end-of-file indicator on the stream, discards
8278
any characters that were "pushed back" by the use of `ungetc', and
8279
returns a value of zero. Otherwise, `fsetpos' returns a nonzero
8280
value and stores an implementation-defined positive value in
8281
`errno'.
8282
8283
When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
8284
32 bit system the function is in fact `fsetpos64'. I.e., the LFS
8285
interface transparently replaces the old interface.
8286
8287
-- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION)
8288
This function is similar to `fsetpos' but the file position used
8289
for positioning is provided in a variable of type `fpos64_t' to
8290
which POSITION points.
8291
8292
If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
8293
bits machine this function is available under the name `fsetpos'
8294
and so transparently replaces the old interface.
8295
8296
8297
File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams
8298
8299
12.20 Stream Buffering
8300
======================
8301
8302
Characters that are written to a stream are normally accumulated and
8303
transmitted asynchronously to the file in a block, instead of appearing
8304
as soon as they are output by the application program. Similarly,
8305
streams often retrieve input from the host environment in blocks rather
8306
than on a character-by-character basis. This is called "buffering".
8307
8308
If you are writing programs that do interactive input and output
8309
using streams, you need to understand how buffering works when you
8310
design the user interface to your program. Otherwise, you might find
8311
that output (such as progress or prompt messages) doesn't appear when
8312
you intended it to, or displays some other unexpected behavior.
8313
8314
This section deals only with controlling when characters are
8315
transmitted between the stream and the file or device, and _not_ with
8316
how things like echoing, flow control, and the like are handled on
8317
specific classes of devices. For information on common control
8318
operations on terminal devices, see *note Low-Level Terminal
8319
Interface::.
8320
8321
You can bypass the stream buffering facilities altogether by using
8322
the low-level input and output functions that operate on file
8323
descriptors instead. *Note Low-Level I/O::.
8324
8325
* Menu:
8326
8327
* Buffering Concepts:: Terminology is defined here.
8328
* Flushing Buffers:: How to ensure that output buffers are flushed.
8329
* Controlling Buffering:: How to specify what kind of buffering to use.
8330
8331
8332
File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering
8333
8334
12.20.1 Buffering Concepts
8335
--------------------------
8336
8337
There are three different kinds of buffering strategies:
8338
8339
* Characters written to or read from an "unbuffered" stream are
8340
transmitted individually to or from the file as soon as possible.
8341
8342
* Characters written to a "line buffered" stream are transmitted to
8343
the file in blocks when a newline character is encountered.
8344
8345
* Characters written to or read from a "fully buffered" stream are
8346
transmitted to or from the file in blocks of arbitrary size.
8347
8348
Newly opened streams are normally fully buffered, with one
8349
exception: a stream connected to an interactive device such as a
8350
terminal is initially line buffered. *Note Controlling Buffering::,
8351
for information on how to select a different kind of buffering.
8352
Usually the automatic selection gives you the most convenient kind of
8353
buffering for the file or device you open.
8354
8355
The use of line buffering for interactive devices implies that output
8356
messages ending in a newline will appear immediately--which is usually
8357
what you want. Output that doesn't end in a newline might or might not
8358
show up immediately, so if you want them to appear immediately, you
8359
should flush buffered output explicitly with `fflush', as described in
8360
*note Flushing Buffers::.
8361
8362
8363
File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering
8364
8365
12.20.2 Flushing Buffers
8366
------------------------
8367
8368
"Flushing" output on a buffered stream means transmitting all
8369
accumulated characters to the file. There are many circumstances when
8370
buffered output on a stream is flushed automatically:
8371
8372
* When you try to do output and the output buffer is full.
8373
8374
* When the stream is closed. *Note Closing Streams::.
8375
8376
* When the program terminates by calling `exit'. *Note Normal
8377
Termination::.
8378
8379
* When a newline is written, if the stream is line buffered.
8380
8381
* Whenever an input operation on _any_ stream actually reads data
8382
from its file.
8383
8384
If you want to flush the buffered output at another time, call
8385
`fflush', which is declared in the header file `stdio.h'.
8386
8387
-- Function: int fflush (FILE *STREAM)
8388
This function causes any buffered output on STREAM to be delivered
8389
to the file. If STREAM is a null pointer, then `fflush' causes
8390
buffered output on _all_ open output streams to be flushed.
8391
8392
This function returns `EOF' if a write error occurs, or zero
8393
otherwise.
8394
8395
-- Function: int fflush_unlocked (FILE *STREAM)
8396
The `fflush_unlocked' function is equivalent to the `fflush'
8397
function except that it does not implicitly lock the stream.
8398
8399
The `fflush' function can be used to flush all streams currently
8400
opened. While this is useful in some situations it does often more than
8401
necessary since it might be done in situations when terminal input is
8402
required and the program wants to be sure that all output is visible on
8403
the terminal. But this means that only line buffered streams have to be
8404
flushed. Solaris introduced a function especially for this. It was
8405
always available in the GNU C library in some form but never officially
8406
exported.
8407
8408
-- Function: void _flushlbf (void)
8409
The `_flushlbf' function flushes all line buffered streams
8410
currently opened.
8411
8412
This function is declared in the `stdio_ext.h' header.
8413
8414
*Compatibility Note:* Some brain-damaged operating systems have been
8415
known to be so thoroughly fixated on line-oriented input and output
8416
that flushing a line buffered stream causes a newline to be written!
8417
Fortunately, this "feature" seems to be becoming less common. You do
8418
not need to worry about this in the GNU system.
8419
8420
In some situations it might be useful to not flush the output pending
8421
for a stream but instead simply forget it. If transmission is costly
8422
and the output is not needed anymore this is valid reasoning. In this
8423
situation a non-standard function introduced in Solaris and available in
8424
the GNU C library can be used.
8425
8426
-- Function: void __fpurge (FILE *STREAM)
8427
The `__fpurge' function causes the buffer of the stream STREAM to
8428
be emptied. If the stream is currently in read mode all input in
8429
the buffer is lost. If the stream is in output mode the buffered
8430
output is not written to the device (or whatever other underlying
8431
storage) and the buffer the cleared.
8432
8433
This function is declared in `stdio_ext.h'.
8434
8435
8436
File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering
8437
8438
12.20.3 Controlling Which Kind of Buffering
8439
-------------------------------------------
8440
8441
After opening a stream (but before any other operations have been
8442
performed on it), you can explicitly specify what kind of buffering you
8443
want it to have using the `setvbuf' function.
8444
8445
The facilities listed in this section are declared in the header
8446
file `stdio.h'.
8447
8448
-- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
8449
SIZE)
8450
This function is used to specify that the stream STREAM should
8451
have the buffering mode MODE, which can be either `_IOFBF' (for
8452
full buffering), `_IOLBF' (for line buffering), or `_IONBF' (for
8453
unbuffered input/output).
8454
8455
If you specify a null pointer as the BUF argument, then `setvbuf'
8456
allocates a buffer itself using `malloc'. This buffer will be
8457
freed when you close the stream.
8458
8459
Otherwise, BUF should be a character array that can hold at least
8460
SIZE characters. You should not free the space for this array as
8461
long as the stream remains open and this array remains its buffer.
8462
You should usually either allocate it statically, or `malloc'
8463
(*note Unconstrained Allocation::) the buffer. Using an automatic
8464
array is not a good idea unless you close the file before exiting
8465
the block that declares the array.
8466
8467
While the array remains a stream buffer, the stream I/O functions
8468
will use the buffer for their internal purposes. You shouldn't
8469
try to access the values in the array directly while the stream is
8470
using it for buffering.
8471
8472
The `setvbuf' function returns zero on success, or a nonzero value
8473
if the value of MODE is not valid or if the request could not be
8474
honored.
8475
8476
-- Macro: int _IOFBF
8477
The value of this macro is an integer constant expression that can
8478
be used as the MODE argument to the `setvbuf' function to specify
8479
that the stream should be fully buffered.
8480
8481
-- Macro: int _IOLBF
8482
The value of this macro is an integer constant expression that can
8483
be used as the MODE argument to the `setvbuf' function to specify
8484
that the stream should be line buffered.
8485
8486
-- Macro: int _IONBF
8487
The value of this macro is an integer constant expression that can
8488
be used as the MODE argument to the `setvbuf' function to specify
8489
that the stream should be unbuffered.
8490
8491
-- Macro: int BUFSIZ
8492
The value of this macro is an integer constant expression that is
8493
good to use for the SIZE argument to `setvbuf'. This value is
8494
guaranteed to be at least `256'.
8495
8496
The value of `BUFSIZ' is chosen on each system so as to make stream
8497
I/O efficient. So it is a good idea to use `BUFSIZ' as the size
8498
for the buffer when you call `setvbuf'.
8499
8500
Actually, you can get an even better value to use for the buffer
8501
size by means of the `fstat' system call: it is found in the
8502
`st_blksize' field of the file attributes. *Note Attribute
8503
Meanings::.
8504
8505
Sometimes people also use `BUFSIZ' as the allocation size of
8506
buffers used for related purposes, such as strings used to receive
8507
a line of input with `fgets' (*note Character Input::). There is
8508
no particular reason to use `BUFSIZ' for this instead of any other
8509
integer, except that it might lead to doing I/O in chunks of an
8510
efficient size.
8511
8512
-- Function: void setbuf (FILE *STREAM, char *BUF)
8513
If BUF is a null pointer, the effect of this function is
8514
equivalent to calling `setvbuf' with a MODE argument of `_IONBF'.
8515
Otherwise, it is equivalent to calling `setvbuf' with BUF, and a
8516
MODE of `_IOFBF' and a SIZE argument of `BUFSIZ'.
8517
8518
The `setbuf' function is provided for compatibility with old code;
8519
use `setvbuf' in all new programs.
8520
8521
-- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
8522
If BUF is a null pointer, this function makes STREAM unbuffered.
8523
Otherwise, it makes STREAM fully buffered using BUF as the buffer.
8524
The SIZE argument specifies the length of BUF.
8525
8526
This function is provided for compatibility with old BSD code. Use
8527
`setvbuf' instead.
8528
8529
-- Function: void setlinebuf (FILE *STREAM)
8530
This function makes STREAM be line buffered, and allocates the
8531
buffer for you.
8532
8533
This function is provided for compatibility with old BSD code. Use
8534
`setvbuf' instead.
8535
8536
It is possible to query whether a given stream is line buffered or
8537
not using a non-standard function introduced in Solaris and available
8538
in the GNU C library.
8539
8540
-- Function: int __flbf (FILE *STREAM)
8541
The `__flbf' function will return a nonzero value in case the
8542
stream STREAM is line buffered. Otherwise the return value is
8543
zero.
8544
8545
This function is declared in the `stdio_ext.h' header.
8546
8547
Two more extensions allow to determine the size of the buffer and how
8548
much of it is used. These functions were also introduced in Solaris.
8549
8550
-- Function: size_t __fbufsize (FILE *STREAM)
8551
The `__fbufsize' function return the size of the buffer in the
8552
stream STREAM. This value can be used to optimize the use of the
8553
stream.
8554
8555
This function is declared in the `stdio_ext.h' header.
8556
8557
-- Function: size_t __fpending (FILE *STREAM) The `__fpending'
8558
function returns the number of bytes currently in the output
8559
buffer. For wide-oriented stream the measuring unit is wide
8560
characters. This function should not be used on buffers in read
8561
mode or opened read-only.
8562
8563
This function is declared in the `stdio_ext.h' header.
8564
8565
8566
File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams
8567
8568
12.21 Other Kinds of Streams
8569
============================
8570
8571
The GNU library provides ways for you to define additional kinds of
8572
streams that do not necessarily correspond to an open file.
8573
8574
One such type of stream takes input from or writes output to a
8575
string. These kinds of streams are used internally to implement the
8576
`sprintf' and `sscanf' functions. You can also create such a stream
8577
explicitly, using the functions described in *note String Streams::.
8578
8579
More generally, you can define streams that do input/output to
8580
arbitrary objects using functions supplied by your program. This
8581
protocol is discussed in *note Custom Streams::.
8582
8583
*Portability Note:* The facilities described in this section are
8584
specific to GNU. Other systems or C implementations might or might not
8585
provide equivalent functionality.
8586
8587
* Menu:
8588
8589
* String Streams:: Streams that get data from or put data in
8590
a string or memory buffer.
8591
* Obstack Streams:: Streams that store data in an obstack.
8592
* Custom Streams:: Defining your own streams with an arbitrary
8593
input data source and/or output data sink.
8594
Loggerhead is a web-based interface for Breezy
Version: 2.0.1