2062fa4f23d6b7928ff674a5e01d93a87e77d443
[kopensolaris-gnu/glibc.git] / libio / stdio.h
1 /* Define ISO C stdio on top of C++ iostreams.
2    Copyright (C) 1991, 1994, 1995, 1996, 1997 Free Software Foundation, Inc.
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 not,
16    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17    Boston, MA 02111-1307, USA.  */
18
19 /*
20  *      ISO C 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 __BEGIN_DECLS
30
31 #define __need_size_t
32 #define __need_NULL
33 #include <stddef.h>
34
35 #include <bits/types.h>
36 #endif /* Don't need FILE.  */
37 #undef  __need_FILE
38
39
40 #ifndef __FILE_defined
41
42 /* The opaque type of streams.  */
43 typedef struct _IO_FILE FILE;
44
45 #define __FILE_defined  1
46 #endif /* FILE not defined.  */
47
48
49 #ifdef  _STDIO_H
50 #define _STDIO_USES_IOSTREAM
51
52 #include <libio.h>
53
54 #ifdef __cplusplus
55 # define __STDIO_INLINE __inline
56 #else
57 # define __STDIO_INLINE extern __inline
58 #endif
59
60 /* The type of the second argument to `fgetpos' and `fsetpos'.  */
61 typedef _G_fpos_t fpos_t;
62
63
64 /* Generate a unique file name (and possibly open it with mode "w+b").  */
65 extern char *__stdio_gen_tempname __P ((char *__buf, size_t __bufsize,
66                                         __const char *__dir,
67                                         __const char *__pfx,
68                                         int __dir_search,
69                                         size_t *__lenptr,
70                                         FILE **__streamptr));
71
72
73 /* Print out MESSAGE on the error output and abort.  */
74 extern void __libc_fatal __P ((__const char *__message))
75      __attribute__ ((__noreturn__));
76
77
78 /* The possibilities for the third argument to `setvbuf'.  */
79 #define _IOFBF 0                /* Fully buffered.  */
80 #define _IOLBF 1                /* Line buffered.  */
81 #define _IONBF 2                /* No buffering.  */
82
83
84 /* Default buffer size.  */
85 #ifndef BUFSIZ
86 #define BUFSIZ _IO_BUFSIZ
87 #endif
88
89
90 /* End of file character.
91    Some things throughout the library rely on this being -1.  */
92 #ifndef EOF
93 #define EOF (-1)
94 #endif
95
96
97 /* The possibilities for the third argument to `fseek'.
98    These values should not be changed.  */
99 #define SEEK_SET        0       /* Seek from beginning of file.  */
100 #define SEEK_CUR        1       /* Seek from current position.  */
101 #define SEEK_END        2       /* Seek from end of file.  */
102
103
104 #ifdef  __USE_SVID
105 /* Default path prefix for `tempnam' and `tmpnam'.  */
106 #define P_tmpdir      "/tmp"
107 #endif
108
109
110 /* Get the values:
111    L_tmpnam     How long an array of chars must be to be passed to `tmpnam'.
112    TMP_MAX      The minimum number of unique filenames generated by tmpnam
113                 (and tempnam when it uses tmpnam's name space),
114                 or tempnam (the two are separate).
115    L_ctermid    How long an array to pass to `ctermid'.
116    L_cuserid    How long an array to pass to `cuserid'.
117    FOPEN_MAX    Minimum number of files that can be open at once.
118    FILENAME_MAX Maximum length of a filename.  */
119 #include <bits/stdio_lim.h>
120
121
122 /* Standard streams.  */
123 extern FILE *stdin, *stdout, *stderr;
124 /* Refer to the real names by default.  */
125 #define stdin _IO_stdin
126 #define stdout _IO_stdout
127 #define stderr _IO_stderr
128
129
130 /* Remove file FILENAME.  */
131 extern int remove __P ((__const char *__filename));
132 /* Rename file OLD to NEW.  */
133 extern int rename __P ((__const char *__old, __const char *__new));
134
135
136 /* Create a temporary file and open it read/write.  */
137 extern FILE *tmpfile __P ((void));
138 /* Generate a temporary filename.  */
139 extern char *tmpnam __P ((char *__s));
140
141 #ifdef __USE_MISC
142 /* This is the reentrant variant of `tmpnam'.  The only difference is
143    that it does not allow S to be NULL.  */
144 extern char *tmpnam_r __P ((char *__s));
145 #endif
146
147
148 #if defined __USE_SVID || defined __USE_XOPEN
149 /* Generate a unique temporary filename using up to five characters of PFX
150    if it is not NULL.  The directory to put this file in is searched for
151    as follows: First the environment variable "TMPDIR" is checked.
152    If it contains the name of a writable directory, that directory is used.
153    If not and if DIR is not NULL, that value is checked.  If that fails,
154    P_tmpdir is tried and finally "/tmp".  The storage for the filename
155    is allocated by `malloc'.  */
156 extern char *tempnam __P ((__const char *__dir, __const char *__pfx));
157 #endif
158
159
160 /* Close STREAM.  */
161 extern int fclose __P ((FILE *__stream));
162 /* Flush STREAM, or all streams if STREAM is NULL.  */
163 extern int fflush __P ((FILE *__stream));
164
165 #ifdef __USE_MISC
166 /* Faster versions when locking is not required.  */
167 extern int fclose_unlocked __P ((FILE *__stream));
168 extern int fflush_unlocked __P ((FILE *__stream));
169 #endif
170
171 #ifdef __USE_GNU
172 /* Close all streams.  */
173 extern int __fcloseall __P ((void));
174 extern int fcloseall __P ((void));
175 #endif
176
177
178 /* Open a file and create a new stream for it.  */
179 extern FILE *fopen __P ((__const char *__filename, __const char *__modes));
180 /* Open a file, replacing an existing stream with it. */
181 extern FILE *freopen __P ((__const char *__restrict __filename,
182                            __const char *__restrict __modes,
183                            FILE *__restrict __stream));
184
185 #ifdef  __USE_POSIX
186 /* Create a new stream that refers to an existing system file descriptor.  */
187 extern FILE *fdopen __P ((int __fd, __const char *__modes));
188 #endif
189
190 #ifdef  __USE_GNU
191 /* Create a new stream that refers to the given magic cookie,
192    and uses the given functions for input and output.  */
193 extern FILE *fopencookie __P ((void *__magic_cookie, __const char *__modes,
194                                _IO_cookie_io_functions_t __io_funcs));
195
196 /* Open a stream that writes into a malloc'd buffer that is expanded as
197    necessary.  *BUFLOC and *SIZELOC are updated with the buffer's location
198    and the number of characters written on fflush or fclose.  */
199 extern FILE *open_memstream __P ((char **__bufloc, size_t *__sizeloc));
200 #endif
201
202
203 /* If BUF is NULL, make STREAM unbuffered.
204    Else make it use buffer BUF, of size BUFSIZ.  */
205 extern void setbuf __P ((FILE *__restrict __stream, char *__restrict __buf));
206 /* Make STREAM use buffering mode MODE.
207    If BUF is not NULL, use N bytes of it for buffering;
208    else allocate an internal buffer N bytes long.  */
209 extern int setvbuf __P ((FILE *__restrict __stream, char *__restrict __buf,
210                          int __modes, size_t __n));
211
212 #ifdef  __USE_BSD
213 /* If BUF is NULL, make STREAM unbuffered.
214    Else make it use SIZE bytes of BUF for buffering.  */
215 extern void setbuffer __P ((FILE *__stream, char *__buf, size_t __size));
216
217 /* Make STREAM line-buffered.  */
218 extern void setlinebuf __P ((FILE *__stream));
219 #endif
220
221
222 /* Write formatted output to STREAM.  */
223 extern int fprintf __P ((FILE *__restrict __stream,
224                          __const char *__restrict __format, ...));
225 /* Write formatted output to stdout.  */
226 extern int printf __P ((__const char *__restrict __format, ...));
227 /* Write formatted output to S.  */
228 extern int sprintf __P ((char *__restrict __s,
229                          __const char *__restrict __format, ...));
230
231 /* Write formatted output to S from argument list ARG.  */
232 extern int vfprintf __P ((FILE *__restrict __s,
233                           __const char *__restrict __format,
234                           _G_va_list __arg));
235 /* Write formatted output to stdout from argument list ARG.  */
236 extern int vprintf __P ((__const char *__restrict __format,
237                          _G_va_list __arg));
238 /* Write formatted output to S from argument list ARG.  */
239 extern int vsprintf __P ((char *__restrict __s,
240                           __const char *__restrict __format,
241                           _G_va_list __arg));
242
243 #ifdef  __OPTIMIZE__
244 __STDIO_INLINE int
245 vprintf (const char *__restrict __fmt, _G_va_list __arg)
246 {
247   return vfprintf (stdout, __fmt, __arg);
248 }
249 #endif /* Optimizing.  */
250
251 #if defined __USE_BSD || defined __USE_ISOC9X
252 /* Maximum chars of output to write in MAXLEN.  */
253 extern int __snprintf __P ((char *__restrict __s, size_t __maxlen,
254                             __const char *__restrict __format, ...));
255 extern int snprintf __P ((char *__restrict __s, size_t __maxlen,
256                           __const char *__restrict __format, ...));
257
258 extern int __vsnprintf __P ((char *__restrict __s, size_t __maxlen,
259                              __const char *__restrict __format,
260                              _G_va_list __arg));
261 extern int vsnprintf __P ((char *__restrict __s, size_t __maxlen,
262                            __const char *__restrict __format,
263                            _G_va_list __arg));
264 #endif
265
266 #ifdef __USE_GNU
267 /* Write formatted output to a string dynamically allocated with `malloc'.
268    Store the address of the string in *PTR.  */
269 extern int vasprintf __P ((char **__restrict __ptr,
270                            __const char *__restrict __f, _G_va_list __arg));
271 extern int asprintf __P ((char **__restrict __ptr,
272                           __const char *__restrict __fmt, ...));
273
274 /* Write formatted output to a file descriptor.  */
275 extern int vdprintf __P ((int __fd, __const char *__restrict __fmt,
276                           _G_va_list __arg));
277 extern int dprintf __P ((int __fd, __const char *__restrict __fmt, ...));
278 #endif
279
280
281 /* Read formatted input from STREAM.  */
282 extern int fscanf __P ((FILE *__restrict __stream,
283                         __const char *__restrict __format, ...));
284 /* Read formatted input from stdin.  */
285 extern int scanf __P ((__const char *__restrict __format, ...));
286 /* Read formatted input from S.  */
287 extern int sscanf __P ((__const char *__restrict __s,
288                         __const char *__restrict __format, ...));
289
290 #ifdef  __USE_GNU
291 /* Read formatted input from S into argument list ARG.  */
292 extern int __vfscanf __P ((FILE *__restrict __s,
293                            __const char *__restrict __format,
294                            _G_va_list __arg));
295 extern int vfscanf __P ((FILE *__restrict __s,
296                          __const char *__restrict __format,
297                          _G_va_list __arg));
298
299 /* Read formatted input from stdin into argument list ARG.  */
300 extern int __vscanf __P ((__const char *__restrict __format,
301                           _G_va_list __arg));
302 extern int vscanf __P ((__const char *__restrict __format, _G_va_list __arg));
303
304 /* Read formatted input from S into argument list ARG.  */
305 extern int __vsscanf __P ((__const char *__restrict __s,
306                            __const char *__restrict __format,
307                            _G_va_list __arg));
308 extern int vsscanf __P ((__const char *__restrict __s,
309                          __const char *__restrict __format,
310                          _G_va_list __arg));
311 #endif /* Use GNU.  */
312
313
314 /* Read a character from STREAM.  */
315 extern int fgetc __P ((FILE *__stream));
316 extern int getc __P ((FILE *__stream));
317
318 /* Read a character from stdin.  */
319 extern int getchar __P ((void));
320
321 /* The C standard explicitly says this is a macro, so we always do the
322    optimization for it.  */
323 #define getc(_fp) _IO_getc (_fp)
324
325 #ifdef  __OPTIMIZE__
326 __STDIO_INLINE int
327 getchar (void)
328 {
329   return _IO_getc (stdin);
330 }
331 #endif /* Optimizing.  */
332
333 #if defined __USE_POSIX || defined __USE_MISC
334 /* These are defined in POSIX.1:1996.  */
335 extern int getc_unlocked __P ((FILE *__stream));
336 extern int getchar_unlocked __P ((void));
337
338 #ifdef __OPTIMIZE__
339 __STDIO_INLINE int
340 getc_unlocked (FILE *__fp)
341 {
342   return _IO_getc_unlocked (__fp);
343 }
344
345 __STDIO_INLINE int
346 getchar_unlocked (void)
347 {
348   return _IO_getc_unlocked (stdin);
349 }
350 #endif /* Optimizing.  */
351 #endif /* Use POSIX or MISC.  */
352
353
354 /* Write a character to STREAM.  */
355 extern int fputc __P ((int __c, FILE *__stream));
356 extern int putc __P ((int __c, FILE *__stream));
357
358 /* Write a character to stdout.  */
359 extern int putchar __P ((int __c));
360
361 /* The C standard explicitly says this can be a macro,
362    so we always do the optimization for it.  */
363 #define putc(_ch, _fp) _IO_putc (_ch, _fp)
364
365 #ifdef __OPTIMIZE__
366 __STDIO_INLINE int
367 putchar (int __c)
368 {
369   return _IO_putc (__c, stdout);
370 }
371 #endif
372
373 #ifdef __USE_MISC
374 /* Faster version when locking is not necessary.  */
375 extern int fputc_unlocked __P ((int __c, FILE *__stream));
376
377 #ifdef __OPTIMIZE__
378 __STDIO_INLINE int
379 fputc_unlocked (int __c, FILE *__stream)
380 {
381   return _IO_putc_unlocked (__c, __stream);
382 }
383 #endif /* Optimizing.  */
384 #endif /* Use MISC.  */
385
386 #if defined __USE_POSIX || defined __USE_MISC
387 /* These are defined in POSIX.1:1996.  */
388 extern int putc_unlocked __P ((int __c, FILE *__stream));
389 extern int putchar_unlocked __P ((int __c));
390
391 #ifdef __OPTIMIZE__
392 __STDIO_INLINE int
393 putc_unlocked (int __c, FILE *__stream)
394 {
395   return _IO_putc_unlocked (__c, __stream);
396 }
397
398 __STDIO_INLINE int
399 putchar_unlocked (int __c)
400 {
401   return _IO_putc_unlocked (__c, stdout);
402 }
403 #endif /* Optimizing.  */
404 #endif /* Use POSIX or MISc.  */
405
406
407 #if defined __USE_SVID || defined __USE_MISC
408 /* Get a word (int) from STREAM.  */
409 extern int getw __P ((FILE *__stream));
410
411 /* Write a word (int) to STREAM.  */
412 extern int putw __P ((int __w, FILE *__stream));
413 #endif
414
415
416 /* Get a newline-terminated string of finite length from STREAM.  */
417 extern char *fgets __P ((char *__restrict __s, int __n,
418                          FILE *__restrict __stream));
419
420 /* Get a newline-terminated string from stdin, removing the newline.
421    DO NOT USE THIS FUNCTION!!  There is no limit on how much it will read.  */
422 extern char *gets __P ((char *__s));
423
424
425 #ifdef  __USE_GNU
426 /* Read up to (and including) a DELIMITER from STREAM into *LINEPTR
427    (and null-terminate it). *LINEPTR is a pointer returned from malloc (or
428    NULL), pointing to *N characters of space.  It is realloc'd as
429    necessary.  Returns the number of characters read (not including the
430    null terminator), or -1 on error or EOF.  */
431 _IO_ssize_t __getdelim __P ((char **__lineptr, size_t *__n,
432                              int __delimiter, FILE *__stream));
433 _IO_ssize_t getdelim __P ((char **__lineptr, size_t *__n,
434                            int __delimiter, FILE *__stream));
435
436 /* Like `getdelim', but reads up to a newline.  */
437 _IO_ssize_t __getline __P ((char **__lineptr, size_t *__n, FILE *__stream));
438 _IO_ssize_t getline __P ((char **__lineptr, size_t *__n, FILE *__stream));
439
440 #ifdef  __OPTIMIZE__
441 __STDIO_INLINE _IO_ssize_t
442 getline (char **__lineptr, size_t *__n, FILE *__stream)
443 {
444   return __getdelim (__lineptr, __n, '\n', __stream);
445 }
446 #endif /* Optimizing.  */
447 #endif
448
449
450 /* Write a string to STREAM.  */
451 extern int fputs __P ((__const char *__restrict __s,
452                        FILE *__restrict __stream));
453 /* Write a string, followed by a newline, to stdout.  */
454 extern int puts __P ((__const char *__s));
455
456
457 /* Push a character back onto the input buffer of STREAM.  */
458 extern int ungetc __P ((int __c, FILE *__stream));
459
460
461 /* Read chunks of generic data from STREAM.  */
462 extern size_t fread __P ((void *__restrict __ptr, size_t __size,
463                           size_t __n, FILE *__restrict __stream));
464 /* Write chunks of generic data to STREAM.  */
465 extern size_t fwrite __P ((__const void *__restrict __ptr, size_t __size,
466                            size_t __n, FILE *__restrict __s));
467
468 #ifdef __USE_MISC
469 /* Faster versions when locking is not necessary.  */
470 extern size_t fread_unlocked __P ((void *__restrict __ptr, size_t __size,
471                                    size_t __n, FILE *__restrict __stream));
472 extern size_t fwrite_unlocked __P ((__const void *__restrict __ptr,
473                                     size_t __size, size_t __n,
474                                     FILE *__restrict __stream));
475 #endif
476
477
478 /* Seek to a certain position on STREAM.  */
479 extern int fseek __P ((FILE *__stream, long int __off, int __whence));
480 /* Return the current position of STREAM.  */
481 extern long int ftell __P ((FILE *__stream));
482 /* Rewind to the beginning of STREAM.  */
483 extern void rewind __P ((FILE *__stream));
484
485 /* Get STREAM's position.  */
486 extern int fgetpos __P ((FILE *__restrict __stream,
487                          fpos_t *__restrict __pos));
488 /* Set STREAM's position.  */
489 extern int fsetpos __P ((FILE *__stream, __const fpos_t *__pos));
490
491
492 /* Clear the error and EOF indicators for STREAM.  */
493 extern void clearerr __P ((FILE *__stream));
494 /* Return the EOF indicator for STREAM.  */
495 extern int feof __P ((FILE *__stream));
496 /* Return the error indicator for STREAM.  */
497 extern int ferror __P ((FILE *__stream));
498
499 #ifdef __USE_MISC
500 /* Faster versions when locking is not required.  */
501 extern void clearerr_unlocked __P ((FILE *__stream));
502 extern int feof_unlocked __P ((FILE *__stream));
503 extern int ferror_unlocked __P ((FILE *__stream));
504
505 #ifdef __OPTIMIZE__
506 __STDIO_INLINE int
507 feof_unlocked (FILE *__stream)
508 {
509   return _IO_feof_unlocked (__stream);
510 }
511
512 __STDIO_INLINE int
513 ferror_unlocked (FILE *__stream)
514 {
515   return _IO_ferror_unlocked (__stream);
516 }
517 #endif /* Optimizing.  */
518 #endif
519
520
521 /* Print a message describing the meaning of the value of errno.  */
522 extern void perror __P ((__const char *__s));
523
524 /* These variables normally should not be used directly.  The `strftime'
525    function provides all the needed functionality.  */
526 #ifdef  __USE_BSD
527 extern int sys_nerr;
528 extern __const char *__const sys_errlist[];
529 #endif
530 #ifdef  __USE_GNU
531 extern int _sys_nerr;
532 extern __const char *__const _sys_errlist[];
533 #endif
534
535
536 #ifdef  __USE_POSIX
537 /* Return the system file descriptor for STREAM.  */
538 extern int fileno __P ((FILE *__stream));
539 #endif /* Use POSIX.  */
540
541 #ifdef __USE_MISC
542 /* Faster version when locking is not required.  */
543 extern int fileno_unlocked __P ((FILE *__stream));
544 #endif
545
546
547 #if (defined __USE_POSIX2 || defined __USE_SVID  || defined __USE_BSD || \
548      defined __USE_MISC)
549 /* Create a new stream connected to a pipe running the given command.  */
550 extern FILE *popen __P ((__const char *__command, __const char *__modes));
551
552 /* Close a stream opened by popen and return the status of its child.  */
553 extern int pclose __P ((FILE *__stream));
554 #endif
555
556
557 #ifdef  __USE_POSIX
558 /* Return the name of the controlling terminal.  */
559 extern char *ctermid __P ((char *__s));
560 #endif /* Use POSIX.  */
561
562
563 #ifdef __USE_XOPEN
564 /* Return the name of the current user.  */
565 extern char *cuserid __P ((char *__s));
566 #endif /* Use X/Open.  */
567
568
569 #ifdef  __USE_GNU
570 struct obstack;                 /* See <obstack.h>.  */
571
572 /* Write formatted output to an obstack.  */
573 extern int obstack_printf __P ((struct obstack *__obstack,
574                                 __const char *__format, ...));
575 extern int obstack_vprintf __P ((struct obstack *__obstack,
576                                  __const char *__format,
577                                  _G_va_list __args));
578 #endif /* Use GNU.  */
579
580
581 #if defined __USE_POSIX || defined __USE_MISC
582 /* These are defined in POSIX.1:1996.  */
583
584 /* Acquire ownership of STREAM.  */
585 extern void flockfile __P ((FILE *__stream));
586
587 /* Try to acquire ownership of STREAM but do not block if it is not
588    possible.  */
589 extern int ftrylockfile __P ((FILE *__stream));
590
591 /* Relinquish the ownership granted for STREAM.  */
592 extern void funlockfile __P ((FILE *__stream));
593 #endif /* POSIX || misc */
594
595 __END_DECLS
596
597 /* Define helper macro.  */
598 #undef __STDIO_INLINE
599
600 #endif /* <stdio.h> included.  */
601
602 #endif /* !_STDIO_H */