Formerly stdio/stdio.h.~30~
[kopensolaris-gnu/glibc.git] / stdio / stdio.h
1 /* Copyright (C) 1991, 1992 Free Software Foundation, Inc.
2 This file is part of the GNU C Library.
3
4 The GNU C Library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public License as
6 published by the Free Software Foundation; either version 2 of the
7 License, or (at your option) any later version.
8
9 The GNU C Library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public
15 License along with the GNU C Library; see the file COPYING.LIB.  If
16 not, write to the Free Software Foundation, Inc., 675 Mass Ave,
17 Cambridge, MA 02139, USA.  */
18
19 /*
20  *      ANSI Standard: 4.9 INPUT/OUTPUT <stdio.h>
21  */
22
23 #ifndef _STDIO_H
24
25 #if     !defined(__need_FILE)
26 #define _STDIO_H        1
27 #include <features.h>
28
29 #define __need_size_t
30 #define __need_NULL
31 #include <stddef.h>
32
33 #define __need___va_list
34 #include <stdarg.h>
35
36 #include <gnu/types.h>
37 #endif  /* Don't need FILE.  */
38 #undef  __need_FILE
39
40
41 #ifndef __FILE_defined
42
43 /* The opaque type of streams.  */
44 typedef struct __stdio_file FILE;
45
46 #define __FILE_defined  1
47 #endif  /* FILE not defined.  */
48
49
50 #ifdef  _STDIO_H
51
52 /* The type of the second argument to `fgetpos' and `fsetpos'.  */
53 typedef __off_t fpos_t;
54
55 /* The mode of I/O, as given in the MODE argument to fopen, etc.  */
56 typedef struct
57   {
58     unsigned int __read:1;      /* Open for reading.  */
59     unsigned int __write:1;     /* Open for writing.  */
60     unsigned int __append:1;    /* Open for appending.  */
61     unsigned int __binary:1;    /* Opened binary.  */
62     unsigned int __create:1;    /* Create the file.  */
63     unsigned int __exclusive:1; /* Error if it already exists.  */
64     unsigned int __truncate:1;  /* Truncate the file on opening.  */
65   } __io_mode;
66
67
68 /* Functions to do I/O and file management for a stream.  */
69
70 typedef __ssize_t EXFUN(__io_read, (PTR __cookie, char *__buf,
71                                     size_t __nbytes));
72 typedef __ssize_t EXFUN(__io_write, (PTR __cookie, CONST char *__buf,
73                                      size_t __n));
74 typedef int EXFUN(__io_seek, (PTR __cookie, fpos_t *__pos, int __w));
75 typedef int EXFUN(__io_close, (PTR __cookie));
76
77 /* Low level interface, independent of FILE representation.  */
78 typedef struct
79   {
80     __io_read *__read;          /* Read bytes.  */
81     __io_write *__write;        /* Write bytes.  */
82     __io_seek *__seek;          /* Seek/tell file position.  */
83     __io_close *__close;        /* Close file.  */
84   } __io_functions;
85
86 /* Higher level interface, dependent on FILE representation.  */
87 typedef struct
88   {
89     /* Make room in the input buffer.  */
90     int EXFUN((*__input), (FILE *__stream));
91     /* Make room in the output buffer.  */
92     void EXFUN((*__output), (FILE *__stream, int __c));
93   } __room_functions;
94
95 extern CONST __io_functions __default_io_functions;
96 extern CONST __room_functions __default_room_functions;
97
98
99 /* Default close function.  */
100 extern __io_close __stdio_close;
101 /* Open FILE with mode M, return cookie or NULL to use an int in *DP.  */
102 extern PTR EXFUN(__stdio_open, (CONST char *__file, __io_mode __m, int *__dp));
103 /* Put out an error message for when stdio needs to die.  */
104 extern void EXFUN(__stdio_errmsg, (CONST char *__msg, size_t __len));
105 /* Generate a unique file name.  */
106 extern char *EXFUN(__stdio_gen_tempname, (CONST char *__dir, CONST char *__pfx,
107                                           int __dir_search, size_t *__lenptr));
108
109 #ifndef __NORETURN
110 #ifdef  __GNUC__
111 #define __NORETURN      __volatile
112 #else   /* Not GCC.  */
113 #define __NORETURN
114 #endif  /* GCC.  */
115 #endif  /* __NORETURN not defined.  */
116
117 /* Print out MESSAGE on the error output and abort.  */
118 extern __NORETURN void EXFUN(__libc_fatal, (CONST char *__message));
119
120
121 /* The FILE structure.  */
122 struct __stdio_file
123   {
124     /* Magic number for validation.  Must be negative in open streams
125        for the glue to Unix stdio getc/putc to work.  */
126     int __magic;
127 #define _IOMAGIC        0xfedabeeb      /* Magic number to fill `__magic'.  */
128 #define _GLUEMAGIC      0xfeedbabe      /* Magic for glued Unix streams.  */
129
130     char *__bufp;                       /* Pointer into the buffer.  */
131     char *__get_limit;                  /* Reading limit.  */
132     char *__put_limit;                  /* Writing limit.  */
133     char *__buffer;                     /* Base of buffer.  */
134     size_t __bufsize;                   /* Size of the buffer.  */
135     FILE *__next;                       /* Next FILE in the linked list.  */
136     PTR __cookie;                       /* Magic cookie.  */
137     int __fileno;                       /* System file descriptor.  */
138     unsigned char __pushback;           /* Pushed-back character.  */
139     char *__pushback_bufp;              /* Old bufp if char pushed back.  */
140     unsigned int __pushed_back:1;       /* A char has been pushed back.  */
141     unsigned int __eof:1;               /* End of file encountered.  */
142     unsigned int __error:1;             /* Error encountered.  */
143     unsigned int __userbuf:1;           /* Buffer is from user.  */
144     unsigned int __linebuf:1;           /* Flush on newline.  */
145     unsigned int __seen:1;              /* This stream has been seen.  */
146     unsigned int __ispipe:1;            /* Nonzero if opened by popen.  */
147     __io_mode __mode;                   /* File access mode.  */
148     __io_functions __io_funcs;          /* I/O functions.  */
149     __room_functions __room_funcs;      /* I/O buffer room functions.  */
150     fpos_t __offset;                    /* Current file position.  */
151     fpos_t __target;                    /* Target file position.  */
152   };
153
154
155 /* All macros used internally by other macros here and by stdio functions begin
156    with `__'.  All of these may evaluate their arguments more than once.  */
157
158
159 /* Nonzero if STREAM is a valid stream.  */
160 #define __validfp(stream)                                                     \
161   (stream != NULL && ((stream->__magic == _GLUEMAGIC &&                       \
162                        (stream = (FILE *) &((int *) stream)[1])),             \
163                       (stream->__magic == _IOMAGIC)))                         \
164
165 /* Clear the error and EOF indicators of STREAM.  */
166 #define __clearerr(stream)      ((stream)->__error = (stream)->__eof = 0)
167
168 /* Nuke STREAM, making it unusable but available for reuse.  */
169 extern void EXFUN(__invalidate, (FILE *__stream));
170
171 /* Make sure STREAM->__offset and STREAM->__target are initialized.
172    Returns 0 if successful, or EOF on
173    error (but doesn't set STREAM->__error).  */
174 extern int EXFUN(__stdio_check_offset, (FILE *__stream));
175
176
177 /* The possibilities for the third argument to `setvbuf'.  */
178 #define _IOFBF  0x1     /* Full buffering.  */
179 #define _IOLBF  0x2     /* Line buffering.  */
180 #define _IONBF  0x4     /* No buffering.  */
181
182
183 /* Default buffer size.  */
184 #define BUFSIZ  1024
185
186
187 /* End of file character.
188    Some things throughout the library rely on this being -1.  */
189 #define EOF     (-1)
190
191
192 /* The possibilities for the third argument to `fseek'.
193    These values should not be changed.  */
194 #define SEEK_SET        0       /* Seek from beginning of file.  */
195 #define SEEK_CUR        1       /* Seek from current position.  */
196 #define SEEK_END        2       /* Seek from end of file.  */
197
198
199 #ifdef  __USE_SVID
200 /* Default path prefix for `tempnam' and `tmpnam'.  */
201 #define P_tmpdir        "/usr/tmp"
202 #endif
203
204
205 /* Get the values:
206    L_tmpnam     How long an array of chars must be to be passed to `tmpnam'.
207    TMP_MAX      The minimum number of unique filenames generated by tmpnam
208                 (and tempnam when it uses tmpnam's name space),
209                 or tempnam (the two are separate).
210    L_ctermid    How long an array to pass to `ctermid'.
211    L_cuserid    How long an array to pass to `cuserid'.
212    FOPEN_MAX    Mininum number of files that can be open at once.
213    FILENAME_MAX Maximum length of a filename.  */
214 #include <stdio_lim.h>
215
216
217 /* All the known streams are in a linked list
218    linked by the `next' field of the FILE structure.  */
219 extern FILE *__stdio_head;      /* Head of the list.  */
220
221 /* Standard streams.  */
222 extern FILE *stdin, *stdout, *stderr;
223
224
225 /* Remove file FILENAME.  */
226 extern int EXFUN(remove, (CONST char *__filename));
227 /* Rename file OLD to NEW.  */
228 extern int EXFUN(rename, (CONST char *__old, CONST char *__new));
229
230
231 /* Create a temporary file and open it read/write.  */
232 extern FILE *EXFUN(tmpfile, (NOARGS));
233 /* Generate a temporary filename.  */
234 extern char *EXFUN(tmpnam, (char *__s));
235
236
237 #ifdef  __USE_SVID
238 /* Generate a unique temporary filename using up to five characters of PFX
239    if it is not NULL.  The directory to put this file in is searched for
240    as follows: First the environment variable "TMPDIR" is checked.
241    If it contains the name of a writable directory, that directory is used.
242    If not and if DIR is not NULL, that value is checked.  If that fails,
243    P_tmpdir is tried and finally "/tmp".  The storage for the filename
244    is allocated by `malloc'.  */
245 extern char *EXFUN(tempnam, (CONST char *__dir, CONST char *__pfx));
246 #endif
247
248
249 /* This performs actual output when necessary, flushing
250    STREAM's buffer and optionally writing another character.  */
251 extern int EXFUN(__flshfp, (FILE *__stream, int __c));
252
253
254 /* Close STREAM, or all streams if STREAM is NULL.  */
255 extern int EXFUN(fclose, (FILE *__stream));
256 /* Flush STREAM, or all streams if STREAM is NULL.  */
257 extern int EXFUN(fflush, (FILE *__stream));
258
259
260 /* Open a file and create a new stream for it.  */
261 extern FILE *EXFUN(fopen, (CONST char *__filename, CONST char *__modes));
262 /* Open a file, replacing an existing stream with it. */
263 extern FILE *EXFUN(freopen, (CONST char *__filename,
264                              CONST char *__modes, FILE *__stream));
265
266 /* Return a new, zeroed, stream.
267    You must set its cookie and io_mode.
268    The first operation will give it a buffer unless you do.
269    It will also give it the default functions unless you set the `seen' flag.
270    The offset is set to -1, meaning it will be determined by doing a
271    stationary seek.  You can set it to avoid the initial tell call.
272    The target is set to -1, meaning it will be set to the offset
273    before the target is needed.
274    Returns NULL if a stream can't be created.  */
275 extern FILE *EXFUN(__newstream, (NOARGS));
276
277 #ifdef  __USE_POSIX
278 /* Create a new stream that refers to an existing system file descriptor.  */
279 extern FILE *EXFUN(fdopen, (int __fd, CONST char *__modes));
280 #endif
281
282 #ifdef  __USE_GNU
283 /* Create a new stream that refers to the given magic cookie,
284    and uses the given functions for input and output.  */
285 extern FILE *EXFUN(fopencookie, (PTR __magic_cookie, CONST char *__modes,
286                                  __io_functions __io_functions));
287
288 /* Create a new stream that refers to a memory buffer.  */
289 extern FILE *EXFUN(fmemopen, (PTR __s, size_t __len, CONST char *__modes));
290
291 /* Open a stream that writes into a malloc'd buffer that is expanded as
292    necessary.  *BUFLOC and *SIZELOC are updated with the buffer's location
293    and the number of characters written on fflush or fclose.  */
294 extern FILE *EXFUN(open_memstream, (char **__bufloc, size_t *sizeloc));
295 #endif
296
297
298 /* If BUF is NULL, make STREAM unbuffered.
299    Else make it use buffer BUF, of size BUFSIZ.  */
300 extern void EXFUN(setbuf, (FILE *__stream, char *__buf));
301 /* Make STREAM use buffering mode MODE.
302    If BUF is not NULL, use N bytes of it for buffering;
303    else allocate an internal buffer N bytes long.  */
304 extern int EXFUN(setvbuf, (FILE *__stream, char *__buf,
305                            int __modes, size_t __n));
306
307 #ifdef  __USE_BSD
308 /* If BUF is NULL, make STREAM unbuffered.
309    Else make it use SIZE bytes of BUF for buffering.  */
310 extern void     EXFUN(setbuffer, (FILE *__stream, char *__buf, size_t __size));
311
312 /* Make STREAM line-buffered.  */
313 extern void EXFUN(setlinebuf, (FILE *__stream));
314 #endif
315
316
317 /* Write formatted output to STREAM.  */
318 extern int EXFUN(fprintf, (FILE *__stream, CONST char *__format, ...));
319 /* Write formatted output to stdout.  */
320 extern int EXFUN(printf, (CONST char *__format, ...));
321 /* Write formatted output to S.  */
322 extern int EXFUN(sprintf, (char *__s, CONST char *__format, ...));
323
324 /* Write formatted output to S from argument list ARG.  */
325 extern int EXFUN(vfprintf, (FILE *__s, CONST char *__format, __va_list __arg));
326 /* Write formatted output to stdout from argument list ARG.  */
327 extern int EXFUN(vprintf, (CONST char *__format, __va_list __arg));
328 /* Write formatted output to S from argument list ARG.  */
329 extern int EXFUN(vsprintf, (char *__s, CONST char *__format, __va_list __arg));
330
331 #ifdef  __OPTIMIZE__
332 #define vprintf(fmt, arg)               vfprintf(stdout, (fmt), (arg))
333 #endif  /* Optimizing.  */
334
335 #ifdef  __USE_GNU
336 /* Maximum chars of output to write in MAXLEN.  */
337 extern int EXFUN(snprintf, (char *__s, size_t __maxlen,
338                             CONST char *__format, ...));
339
340 extern int EXFUN(vsnprintf, (char *__s, size_t __maxlen,
341                              CONST char *__format, __va_list __arg));
342
343 /* Write formatted output to a string dynamically allocated with `malloc'.
344    Store the address of the string in *PTR.  */
345 extern int EXFUN(vasprintf, (char **__ptr, CONST char *__f, __va_list __arg));
346 extern int EXFUN(asprintf, (char **__ptr, CONST char *__fmt, ...));
347
348 /* Write formatted output to a file descriptor.  */
349 extern int EXFUN(vdprintf, (int __fd, CONST char *__fmt, __va_list __arg));
350 extern int EXFUN(dprintf, (int __fd, CONST char *__fmt, ...));
351 #endif
352
353
354 /* Read formatted input from STREAM.  */
355 extern int EXFUN(fscanf, (FILE *__stream, CONST char *__format, ...));
356 /* Read formatted input from stdin.  */
357 extern int EXFUN(scanf, (CONST char *__format, ...));
358 /* Read formatted input from S.  */
359 extern int EXFUN(sscanf, (CONST char *__s, CONST char *__format, ...));
360
361 #ifdef  __USE_GNU
362 /* Read formatted input from S into argument list ARG.  */
363 extern int EXFUN(__vfscanf, (FILE *__s, CONST char *__format,
364                              __va_list __arg));
365 extern int EXFUN(vfscanf, (FILE *__s, CONST char *__format,
366                            __va_list __arg));
367
368 /* Read formatted input from stdin into argument list ARG.  */
369 extern int EXFUN(vscanf, (CONST char *__format, __va_list __arg));
370
371 /* Read formatted input from S into argument list ARG.  */
372 extern int EXFUN(__vsscanf, (CONST char *__s, CONST char *__format,
373                              __va_list __arg));
374 extern int EXFUN(vsscanf, (CONST char *__s, CONST char *__format,
375                            __va_list __arg));
376
377
378 #ifdef  __OPTIMIZE__
379 #define vfscanf(s, format, arg) __vfscanf((s), (format), (arg))
380 #define vscanf(format, arg)     __vfscanf(stdin, (format), (arg))
381 #define vsscanf(s, format, arg) __vsscanf((s), (format), (arg))
382 #endif  /* Optimizing.  */
383 #endif  /* Use GNU.  */
384
385
386 /* This does actual reading when necessary, filling STREAM's
387    buffer and returning the first character in it.  */
388 extern int EXFUN(__fillbf, (FILE *__stream));
389
390
391 /* Read a character from STREAM.  */
392 extern int EXFUN(fgetc, (FILE *__stream));
393 extern int EXFUN(getc, (FILE *__stream));
394
395 /* Read a character from stdin.  */
396 extern int EXFUN(getchar, (NOARGS));
397
398 /* The C standard explicitly says this can
399    re-evaluate its argument, so it does. */
400 #define __getc(stream)                                                        \
401   ((stream)->__bufp < (stream)->__get_limit ?                                 \
402    (int) ((unsigned char) *(stream)->__bufp++) : __fillbf(stream))
403
404 /* The C standard explicitly says this is a macro,
405    so we always do the optimization for it.  */
406 #define getc(stream)    __getc(stream)
407
408 #ifdef  __OPTIMIZE__
409 #define getchar()       __getc(stdin)
410 #endif  /* Optimizing.  */
411
412
413 /* Write a character to STREAM.  */
414 extern int EXFUN(fputc, (int __c, FILE *__stream));
415 extern int EXFUN(putc, (int __c, FILE *__stream));
416
417 /* Write a character to stdout.  */
418 extern int EXFUN(putchar, (int __c));
419
420 /* The C standard explicitly says this can
421    re-evaluate its arguments, so it does.  */
422 #define __putc(c, stream)                                                     \
423   ((stream)->__bufp < (stream)->__put_limit ?                                 \
424    (int) (unsigned char) (*(stream)->__bufp++ = (unsigned char) (c)) :        \
425    ((stream)->__linebuf && (c) != '\n' &&                                     \
426     (stream)->__bufp - (stream)->__buffer < (stream)->__bufsize) ?            \
427    (*(stream)->__bufp++ = (unsigned char) (c)) :                              \
428    __flshfp((stream), (unsigned char) (c)))
429
430 /* The C standard explicitly says this can be a macro,
431    so we always do the optimization for it.  */
432 #define putc(c, stream) __putc((c), (stream))
433
434 #ifdef  __OPTIMIZE__
435 #define putchar(c)      __putc((c), stdout)
436 #endif  /* Optimizing.  */
437
438
439 #if defined(__USE_SVID) || defined(__USE_MISC)
440 /* Get a word (int) from STREAM.  */
441 extern int EXFUN(getw, (FILE *__stream));
442
443 /* Write a word (int) to STREAM.  */
444 extern int EXFUN(putw, (int __w, FILE *__stream));
445 #endif
446
447
448 /* Get a newline-terminated string of finite length from STREAM.  */
449 extern char *EXFUN(fgets, (char *__s, size_t __n, FILE *__stream));
450
451 /* Get a newline-terminated string from stdin, removing the newline.
452    DO NOT USE THIS FUNCTION!!  There is no limit on how much it will read.  */
453 extern char *EXFUN(gets, (char *__s));
454
455
456 #ifdef  __USE_GNU
457 #include <sys/types.h>
458
459 /* Read up to (and including) a DELIMITER from STREAM into *LINEPTR
460    (and null-terminate it). *LINEPTR is a pointer returned from malloc (or
461    NULL), pointing to *N characters of space.  It is realloc'd as
462    necessary.  Returns the number of characters read (not including the
463    null terminator), or -1 on error or EOF.  */
464 ssize_t EXFUN(getdelim, (char **lineptr, size_t *n,
465                          int delimiter, FILE *stream));
466
467 /* Like `getdelim', but reads up to a newline.  */
468 ssize_t EXFUN(getline, (char **lineptr, size_t *n, FILE *stream));
469
470 #ifdef  __OPTIMIZE__
471 #define getline(lineptr, n, stream) getdelim ((lineptr), (n), '\n', (stream))
472 #endif  /* Optimizing.  */
473 #endif
474
475
476 /* Write a string to STREAM.  */
477 extern int EXFUN(fputs, (CONST char *__s, FILE *__stream));
478 /* Write a string, followed by a newline, to stdout.  */
479 extern int EXFUN(puts, (CONST char *__s));
480
481 #ifdef  __OPTIMIZE__
482 #define puts(s) ((fputs((s), stdout) || __putc('\n', stdout) == EOF) ? EOF : 0)
483 #endif  /* Optimizing.  */
484
485
486 /* Push a character back onto the input buffer of STREAM.  */
487 extern int EXFUN(ungetc, (int __c, FILE *__stream));
488
489
490 /* Read chunks of generic data from STREAM.  */
491 extern size_t EXFUN(fread, (PTR __ptr, size_t __size,
492                             size_t __n, FILE *__stream));
493 /* Write chunks of generic data to STREAM.  */
494 extern size_t EXFUN(fwrite, (CONST PTR __ptr, size_t __size,
495                              size_t __n, FILE *__s));
496
497
498 /* Seek to a certain position on STREAM.  */
499 extern int EXFUN(fseek, (FILE *__stream, long int __off, int __whence));
500 /* Return the current position of STREAM.  */
501 extern long int EXFUN(ftell, (FILE *__stream));
502 /* Rewind to the beginning of STREAM.  */
503 extern void EXFUN(rewind, (FILE *__stream));
504
505 /* Get STREAM's position.  */
506 extern int EXFUN(fgetpos, (FILE *__stream, fpos_t *__pos));
507 /* Set STREAM's position.  */
508 extern int EXFUN(fsetpos, (FILE *__stream, CONST fpos_t *__pos));
509
510
511 /* Clear the error and EOF indicators for STREAM.  */
512 extern void EXFUN(clearerr, (FILE *__stream));
513 /* Return the EOF indicator for STREAM.  */
514 extern int EXFUN(feof, (FILE *__stream));
515 /* Return the error indicator for STREAM.  */
516 extern int EXFUN(ferror, (FILE *__stream));
517
518 #ifdef  __OPTIMIZE__
519 #define feof(stream)    ((stream)->__eof != 0)
520 #define ferror(stream)  ((stream)->__error != 0)
521 #endif  /* Optimizing.  */
522
523
524 /* Print a message describing the meaning of the value of errno.  */
525 extern void EXFUN(perror, (CONST char *__s));
526
527 #ifdef  __USE_MISC
528 /* Print a message describing the meaning of the given signal number.  */
529 extern void EXFUN(psignal, (int __sig, CONST char *__s));
530 #endif  /* Non strict ANSI and not POSIX only.  */
531
532
533 #ifdef  __USE_POSIX
534 /* Return the system file descriptor for STREAM.  */
535 extern int EXFUN(fileno, (CONST FILE *__stream));
536
537 #ifdef  __OPTIMIZE__
538 /* The `+ 0' makes this not be an lvalue, so it can't be changed.  */
539 #define fileno(stream)  ((stream)->__fileno + 0)
540 #endif  /* Optimizing.  */
541
542 #endif  /* Use POSIX.  */
543
544
545 #if (defined (__USE_POSIX2) || defined(__USE_SVID) || defined(__USE_BSD) || \
546      defined(__USE_MISC))
547 /* Create a new stream connected to a pipe running the given command.  */
548 extern FILE *EXFUN(popen, (CONST char *__command, CONST char *__modes));
549
550 /* Close a stream opened by popen and return the status of its child.  */
551 extern int EXFUN(pclose, (FILE *__stream));
552 #endif
553
554
555 #ifdef  __USE_POSIX
556 /* Return the name of the controlling terminal.  */
557 extern char *EXFUN(ctermid, (char *__s));
558 /* Return the name of the current user.  */
559 extern char *EXFUN(cuserid, (char *__s));
560 #endif
561
562 #endif  /* <stdio.h> included.  */
563
564 #endif  /* stdio.h  */