1 #pragma force_top_level
2 #pragma include_only_once
4 /* stdio.h: ANSI 'C' (X3J11 Oct 88) library header, section 4.9 */
5 /* Copyright (C) Codemist Ltd. */
6 /* Copyright (C) Acorn Computers Ltd., 1990, 1992 */
9 /* AM July-88 changes to all prototypes so that */
10 /* #define mode 3; #include <stdio.h> can work as ANSI require. */
13 * stdio.h declares two types, several macros, and many functions for
14 * performing input and output. For a discussion on Streams and Files
15 * refer to sections 4.9.2 and 4.9.3 in the above ANSI draft, or to a
16 * modern textbook on C.
22 #define __LIB_VERSION 310 /* 3.10, but int for PP inequality test */
26 typedef unsigned int size_t; /* from <stddef.h> */
29 /* ANSI forbids va_list to be defined here */
30 typedef char *__va_list[1]; /* keep in step with <stdarg.h> */
33 # define NULL 0 /* see <stddef.h> */
36 typedef struct __fpos_t_struct
37 { unsigned long __lo; /* add hi one day */
40 * fpos_t is an object capable of recording all information needed to
41 * specify uniquely every position within a file.
44 typedef struct __FILE_struct
45 { unsigned char *__ptr;
46 int __icnt; /* two separate _cnt fields so we can police ... */
47 int __ocnt; /* ... restrictions that read/write are fseek separated */
49 /* AM: the following things do NOT need __ prefixes as they are */
50 /* are invisible in an ANSI-conforming program. */
51 unsigned char *__base; /* buffer base */
52 int __file; /* RISCOS/Arthur/Brazil file handle */
53 long __pos; /* position in file */
54 int __bufsiz; /* maximum buffer size */
55 int __signature; /* used with temporary files */
56 struct __extradata *__extrap; /* pointer to information about stream */
59 * FILE is an object capable of recording all information needed to control
60 * a stream, such as its file position indicator, a pointer to its
61 * associated buffer, an error indicator that records whether a read/write
62 * error has occurred and an end-of-file indicator that records whether the
63 * end-of-file has been reached.
64 * N.B. the objects contained in the #ifdef __system_io clause are for
68 # define _IOREAD 0x01 /* system use - open for input */
69 # define _IOWRITE 0x02 /* system use - open for output */
70 # define _IOBIN 0x04 /* system use - binary stream */
71 # define _IOSTRG 0x08 /* system use - string stream */
72 # define _IOSEEK 0x10 /* system use - physical seek required before IO */
73 # define _IOLAZY 0x20 /* system use - possible seek pending */
74 # define _IOSBF 0x800 /* system use - system allocated buffer */
75 # define _IOAPPEND 0x08000 /* system use - must seek to eof before write */
76 #define _IOEOF 0x40 /* end-of-file reached */
77 #define _IOERR 0x80 /* error occurred on stream */
78 #define _IOFBF 0x100 /* fully buffered IO */
79 #define _IOLBF 0x200 /* line buffered IO */
80 #define _IONBF 0x400 /* unbuffered IO */
82 #define BUFSIZ (4096) /* system buffer size (as used by setbuf) */
85 * negative integral constant, indicates end-of-file, that is, no more input
88 /* It is not clear to me what value FOPEN_MAX should have, so I will
89 err in the cautious direction - ANSI requires it to be at least 8 */
90 #define FOPEN_MAX 8 /* check re arthur/unix/mvs */
92 * an integral constant expression that is the minimum number of files that
93 * this implementation guarantees can be open simultaneously.
95 /* _SYS_OPEN defines a limit on the number of open files that is imposed
98 #define FILENAME_MAX 80
100 * an integral constant expression that is the size of an array of char
101 * large enough to hold the longest filename string
103 #define L_tmpnam FILENAME_MAX
105 * an integral constant expression that is the size of an array of char
106 * large enough to hold a temporary file name string generated by the
111 #define SEEK_SET 0 /* start of stream (see fseek) */
112 #define SEEK_CUR 1 /* current position in stream (see fseek) */
113 #define SEEK_END 2 /* end of stream (see fseek) */
116 #define TMP_MAX 1000000000
118 * an integral constant expression that is the minimum number of unique
119 * file names that shall be generated by the tmpnam function.
127 extern FILE *_dll_iob(void);
128 #define __iob (_dll_iob())
131 /* an array of file objects for use by the system. */
134 #ifdef SYSTEM_STATICS
139 #define stdin (&__iob[0])
140 /* pointer to a FILE object associated with standard input stream */
141 #define stdout (&__iob[1])
142 /* pointer to a FILE object associated with standard output stream */
143 #define stderr (&__iob[2])
144 /* pointer to a FILE object associated with standard error stream */
147 extern int remove(const char * /*filename*/);
149 * causes the file whose name is the string pointed to by filename to be
150 * removed. Subsequent attempts to open the file will fail, unless it is
151 * created anew. If the file is open, the behaviour of the remove function
152 * is implementation-defined (under RISCOS/Arthur/Brazil the operation
154 * Returns: zero if the operation succeeds, nonzero if it fails.
156 extern int rename(const char * /*old*/, const char * /*new*/);
158 * causes the file whose name is the string pointed to by old to be
159 * henceforth known by the name given by the string pointed to by new. The
160 * file named old is effectively removed. If a file named by the string
161 * pointed to by new exists prior to the call of the rename function, the
162 * behaviour is implementation-defined (under RISCOS/Arthur/Brazil, the
164 * Returns: zero if the operation succeeds, nonzero if it fails, in which
165 * case if the file existed previously it is still known by its
168 extern FILE *tmpfile(void);
170 * creates a temporary binary file that will be automatically removed when
171 * it is closed or at program termination. The file is opened for update.
172 * Returns: a pointer to the stream of the file that it created. If the file
173 * cannot be created, a null pointer is returned.
175 extern char *tmpnam(char * /*s*/);
177 * generates a string that is not the same as the name of an existing file.
178 * The tmpnam function generates a different string each time it is called,
179 * up to TMP_MAX times. If it is called more than TMP_MAX times, the
180 * behaviour is implementation-defined (under RISCOS/Arthur/Brazil the
181 * algorithm for the name generation works just as well after tmpnam has
182 * been called more than TMP_MAX times as before; a name clash is impossible
183 * in any single half year period).
184 * Returns: If the argument is a null pointer, the tmpnam function leaves
185 * its result in an internal static object and returns a pointer to
186 * that object. Subsequent calls to the tmpnam function may modify
187 * the same object. if the argument is not a null pointer, it is
188 * assumed to point to an array of at least L_tmpnam characters;
189 * the tmpnam function writes its result in that array and returns
190 * the argument as its value.
193 extern int fclose(FILE * /*stream*/);
195 * causes the stream pointed to by stream to be flushed and the associated
196 * file to be closed. Any unwritten buffered data for the stream are
197 * delivered to the host environment to be written to the file; any unread
198 * buffered data are discarded. The stream is disassociated from the file.
199 * If the associated buffer was automatically allocated, it is deallocated.
200 * Returns: zero if the stream was succesfully closed, or nonzero if any
201 * errors were detected or if the stream was already closed.
203 extern int fflush(FILE * /*stream*/);
205 * If the stream points to an output or update stream in which the most
206 * recent operation was output, the fflush function causes any unwritten
207 * data for that stream to be delivered to the host environment to be
208 * written to the file. If the stream points to an input or update stream,
209 * the fflush function undoes the effect of any preceding ungetc operation
211 * Returns: nonzero if a write error occurs.
213 extern FILE *fopen(const char * /*filename*/, const char * /*mode*/);
215 * opens the file whose name is the string pointed to by filename, and
216 * associates a stream with it.
217 * The argument mode points to a string beginning with one of the following
219 * "r" open text file for reading
220 * "w" create text file for writing, or truncate to zero length
221 * "a" append; open text file or create for writing at eof
222 * "rb" open binary file for reading
223 * "wb" create binary file for writing, or truncate to zero length
224 * "ab" append; open binary file or create for writing at eof
225 * "r+" open text file for update (reading and writing)
226 * "w+" create text file for update, or truncate to zero length
227 * "a+" append; open text file or create for update, writing at eof
228 * "r+b"/"rb+" open binary file for update (reading and writing)
229 * "w+b"/"wb+" create binary file for update, or truncate to zero length
230 * "a+b"/"ab+" append; open binary file or create for update, writing at eof
232 * Opening a file with read mode ('r' as the first character in the mode
233 * argument) fails if the file does not exist or cannot be read.
234 * Opening a file with append mode ('a' as the first character in the mode
235 * argument) causes all subsequent writes to be forced to the current end of
236 * file, regardless of intervening calls to the fseek function. In some
237 * implementations, opening a binary file with append mode ('b' as the
238 * second or third character in the mode argument) may initially position
239 * the file position indicator beyond the last data written, because of the
240 * NUL padding (but not under RISCOS/Arthur/Brazil).
241 * When a file is opened with update mode ('+' as the second or third
242 * character in the mode argument), both input and output may be performed
243 * on the associated stream. However, output may not be directly followed by
244 * input without an intervening call to the fflush fuction or to a file
245 * positioning function (fseek, fsetpos, or rewind), and input be not be
246 * directly followed by output without an intervening call to the fflush
247 * fuction or to a file positioning function, unless the input operation
248 * encounters end-of-file. Opening a file with update mode may open or
249 * create a binary stream in some implementations (but not under RISCOS/
250 * Arthur/Brazil). When opened, a stream is fully buffered if and only if
251 * it does not refer to an interactive device. The error and end-of-file
252 * indicators for the stream are cleared.
253 * Returns: a pointer to the object controlling the stream. If the open
254 * operation fails, fopen returns a null pointer.
256 extern FILE *freopen(const char * /*filename*/, const char * /*mode*/,
259 * opens the file whose name is the string pointed to by filename and
260 * associates the stream pointed to by stream with it. The mode argument is
261 * used just as in the fopen function.
262 * The freopen function first attempts to close any file that is associated
263 * with the specified stream. Failure to close the file successfully is
264 * ignored. The error and end-of-file indicators for the stream are cleared.
265 * Returns: a null pointer if the operation fails. Otherwise, freopen
266 * returns the value of the stream.
268 extern void setbuf(FILE * /*stream*/, char * /*buf*/);
270 * Except that it returns no value, the setbuf function is equivalent to the
271 * setvbuf function invoked with the values _IOFBF for mode and BUFSIZ for
272 * size, or (if buf is a null pointer), with the value _IONBF for mode.
275 extern int setvbuf(FILE * /*stream*/, char * /*buf*/,
276 int /*mode*/, size_t /*size*/);
278 * may be used after the stream pointed to by stream has been associated
279 * with an open file but before it is read or written. The argument mode
280 * determines how stream will be buffered, as follows: _IOFBF causes
281 * input/output to be fully buffered; _IOLBF causes output to be line
282 * buffered (the buffer will be flushed when a new-line character is
283 * written, when the buffer is full, or when input is requested); _IONBF
284 * causes input/output to be completely unbuffered. If buf is not the null
285 * pointer, the array it points to may be used instead of an automatically
286 * allocated buffer (the buffer must have a lifetime at least as great as
287 * the open stream, so the stream should be closed before a buffer that has
288 * automatic storage duration is deallocated upon block exit). The argument
289 * size specifies the size of the array. The contents of the array at any
290 * time are indeterminate.
291 * Returns: zero on success, or nonzero if an invalid value is given for
292 * mode or size, or if the request cannot be honoured.
295 #pragma -v1 /* hint to the compiler to check f/s/printf format */
296 extern int fprintf(FILE * /*stream*/, const char * /*format*/, ...);
298 * writes output to the stream pointed to by stream, under control of the
299 * string pointed to by format that specifies how subsequent arguments are
300 * converted for output. If there are insufficient arguments for the format,
301 * the behaviour is undefined. If the format is exhausted while arguments
302 * remain, the excess arguments are evaluated but otherwise ignored. The
303 * fprintf function returns when the end of the format string is reached.
304 * The format shall be a multibyte character sequence, beginning and ending
305 * in its initial shift state. The format is composed of zero or more
306 * directives: ordinary multibyte characters (not %), which are copied
307 * unchanged to the output stream; and conversion specifiers, each of which
308 * results in fetching zero or more subsequent arguments. Each conversion
309 * specification is introduced by the character %. For a description of the
310 * available conversion specifiers refer to section 4.9.6.1 in the ANSI
311 * draft mentioned at the start of this file or to any modern textbook on C.
312 * The minimum value for the maximum number of characters producable by any
313 * single conversion is at least 509.
314 * Returns: the number of characters transmitted, or a negative value if an
315 * output error occurred.
317 extern int printf(const char * /*format*/, ...);
319 * is equivalent to fprintf with the argument stdout interposed before the
320 * arguments to printf.
321 * Returns: the number of characters transmitted, or a negative value if an
322 * output error occurred.
324 extern int sprintf(char * /*s*/, const char * /*format*/, ...);
326 * is equivalent to fprintf, except that the argument s specifies an array
327 * into which the generated output is to be written, rather than to a
328 * stream. A null character is written at the end of the characters written;
329 * it is not counted as part of the returned sum.
330 * Returns: the number of characters written to the array, not counting the
331 * terminating null character.
333 #pragma -v2 /* hint to the compiler to check f/s/scanf format */
334 extern int fscanf(FILE * /*stream*/, const char * /*format*/, ...);
336 * reads input from the stream pointed to by stream, under control of the
337 * string pointed to by format that specifies the admissible input sequences
338 * and how thay are to be converted for assignment, using subsequent
339 * arguments as pointers to the objects to receive the converted input. If
340 * there are insufficient arguments for the format, the behaviour is
341 * undefined. If the format is exhausted while arguments remain, the excess
342 * arguments are evaluated but otherwise ignored.
343 * The format is composed of zero or more directives: one or more
344 * white-space characters; an ordinary character (not %); or a conversion
345 * specification. Each conversion specification is introduced by the
346 * character %. For a description of the available conversion specifiers
347 * refer to section 4.9.6.2 in the ANSI draft mentioned at the start of this
348 * file, or to any modern textbook on C.
349 * If end-of-file is encountered during input, conversion is terminated. If
350 * end-of-file occurs before any characters matching the current directive
351 * have been read (other than leading white space, where permitted),
352 * execution of the current directive terminates with an input failure;
353 * otherwise, unless execution of the current directive is terminated with a
354 * matching failure, execution of the following directive (if any) is
355 * terminated with an input failure.
356 * If conversions terminates on a conflicting input character, the offending
357 * input character is left unread in the input strem. Trailing white space
358 * (including new-line characters) is left unread unless matched by a
359 * directive. The success of literal matches and suppressed asignments is
360 * not directly determinable other than via the %n directive.
361 * Returns: the value of the macro EOF if an input failure occurs before any
362 * conversion. Otherwise, the fscanf function returns the number of
363 * input items assigned, which can be fewer than provided for, or
364 * even zero, in the event of an early conflict between an input
365 * character and the format.
367 extern int scanf(const char * /*format*/, ...);
369 * is equivalent to fscanf with the argument stdin interposed before the
370 * arguments to scanf.
371 * Returns: the value of the macro EOF if an input failure occurs before any
372 * conversion. Otherwise, the scanf function returns the number of
373 * input items assigned, which can be fewer than provided for, or
374 * even zero, in the event of an early matching failure.
376 extern int sscanf(const char * /*s*/, const char * /*format*/, ...);
378 * is equivalent to fscanf except that the argument s specifies a string
379 * from which the input is to be obtained, rather than from a stream.
380 * Reaching the end of the string is equivalent to encountering end-of-file
381 * for the fscanf function.
382 * Returns: the value of the macro EOF if an input failure occurs before any
383 * conversion. Otherwise, the scanf function returns the number of
384 * input items assigned, which can be fewer than provided for, or
385 * even zero, in the event of an early matching failure.
387 #pragma -v0 /* back to default */
388 extern int vprintf(const char * /*format*/, __va_list /*arg*/);
390 * is equivalent to printf, with the variable argument list replaced by arg,
391 * which has been initialised by the va_start macro (and possibly subsequent
392 * va_arg calls). The vprintf function does not invoke the va_end function.
393 * Returns: the number of characters transmitted, or a negative value if an
394 * output error occurred.
396 extern int vfprintf(FILE * /*stream*/,
397 const char * /*format*/, __va_list /*arg*/);
399 * is equivalent to fprintf, with the variable argument list replaced by
400 * arg, which has been initialised by the va_start macro (and possibly
401 * subsequent va_arg calls). The vfprintf function does not invoke the
403 * Returns: the number of characters transmitted, or a negative value if an
404 * output error occurred.
406 extern int vsprintf(char * /*s*/, const char * /*format*/, __va_list /*arg*/);
408 * is equivalent to sprintf, with the variable argument list replaced by
409 * arg, which has been initialised by the va_start macro (and possibly
410 * subsequent va_arg calls). The vsprintf function does not invoke the
412 * Returns: the number of characters written in the array, not counting the
413 * terminating null character.
416 extern int fgetc(FILE * /*stream*/);
418 * obtains the next character (if present) as an unsigned char converted to
419 * an int, from the input stream pointed to by stream, and advances the
420 * associated file position indicator (if defined).
421 * Returns: the next character from the input stream pointed to by stream.
422 * If the stream is at end-of-file, the end-of-file indicator is
423 * set and fgetc returns EOF. If a read error occurs, the error
424 * indicator is set and fgetc returns EOF.
426 extern char *fgets(char * /*s*/, int /*n*/, FILE * /*stream*/);
428 * reads at most one less than the number of characters specified by n from
429 * the stream pointed to by stream into the array pointed to by s. No
430 * additional characters are read after a new-line character (which is
431 * retained) or after end-of-file. A null character is written immediately
432 * after the last character read into the array.
433 * Returns: s if successful. If end-of-file is encountered and no characters
434 * have been read into the array, the contents of the array remain
435 * unchanged and a null pointer is returned. If a read error occurs
436 * during the operation, the array contents are indeterminate and a
437 * null pointer is returned.
439 extern int fputc(int /*c*/, FILE * /*stream*/);
441 * writes the character specified by c (converted to an unsigned char) to
442 * the output stream pointed to by stream, at the position indicated by the
443 * asociated file position indicator (if defined), and advances the
444 * indicator appropriately. If the file position indicator is not defined,
445 * the character is appended to the output stream.
446 * Returns: the character written. If a write error occurs, the error
447 * indicator is set and fputc returns EOF.
449 extern int fputs(const char * /*s*/, FILE * /*stream*/);
451 * writes the string pointed to by s to the stream pointed to by stream.
452 * The terminating null character is not written.
453 * Returns: EOF if a write error occurs; otherwise it returns a nonnegative
456 extern int __filbuf(FILE * /*stream*/);
458 * SYSTEM USE ONLY, called by getc to refill buffer and or sort out flags.
459 * Returns: first character put into buffer or EOF on error.
462 (--((p)->__icnt) >= 0 ? *((p)->__ptr)++ : __filbuf(p))
464 extern int (getc)(FILE * /*stream*/);
467 * is equivalent to fgetc except that it may be (and is under
468 * RISCOS/Arthur/Brazil) implemented as a macro. stream may be evaluated
469 * more than once, so the argument should never be an expression with side
471 * Returns: the next character from the input stream pointed to by stream.
472 * If the stream is at end-of-file, the end-of-file indicator is
473 * set and getc returns EOF. If a read error occurs, the error
474 * indicator is set and getc returns EOF.
476 #define getchar() getc(stdin)
478 extern int (getchar)(void);
481 * is equivalent to getc with the argument stdin.
482 * Returns: the next character from the input stream pointed to by stdin.
483 * If the stream is at end-of-file, the end-of-file indicator is
484 * set and getchar returns EOF. If a read error occurs, the error
485 * indicator is set and getchar returns EOF.
487 extern char *gets(char * /*s*/);
489 * reads characters from the input stream pointed to by stdin into the array
490 * pointed to by s, until end-of-file is encountered or a new-line character
491 * is read. Any new-line character is discarded, and a null character is
492 * written immediately after the last character read into the array.
493 * Returns: s if successful. If end-of-file is encountered and no characters
494 * have been read into the array, the contents of the array remain
495 * unchanged and a null pointer is returned. If a read error occurs
496 * during the operation, the array contents are indeterminate and a
497 * null pointer is returned.
499 extern int __flsbuf(int /*c*/, FILE * /*stream*/);
501 * SYSTEM USE ONLY, called by putc to flush buffer and or sort out flags.
502 * Returns: character put into buffer or EOF on error.
504 #define putc(ch, p) \
505 (--((p)->__ocnt) >= 0 ? (*((p)->__ptr)++ = (ch)) : __flsbuf(ch,p))
507 extern int (putc)(int /*c*/, FILE * /*stream*/);
510 * is equivalent to fputc except that it may be (and is under
511 * RISCOS/Arthur/Brazil) implemented as a macro. stream may be evaluated
512 * more than once, so the argument should never be an expression with side
514 * Returns: the character written. If a write error occurs, the error
515 * indicator is set and putc returns EOF.
517 #define putchar(ch) putc(ch, stdout)
519 extern int (putchar)(int /*c*/);
522 * is equivalent to putc with the second argument stdout.
523 * Returns: the character written. If a write error occurs, the error
524 * indicator is set and putc returns EOF.
526 extern int puts(const char * /*s*/);
528 * writes the string pointed to by s to the stream pointed to by stdout, and
529 * appends a new-line character to the output. The terminating null
530 * character is not written.
531 * Returns: EOF if a write error occurs; otherwise it returns a nonnegative
534 extern int ungetc(int /*c*/, FILE * /*stream*/);
536 * pushes the character specified by c (converted to an unsigned char) back
537 * onto the input stream pointed to by stream. The character will be
538 * returned by the next read on that stream. An intervening call to the
539 * fflush function or to a file positioning function (fseek, fsetpos,
540 * rewind) discards any pushed-back characters. The external storage
541 * corresponding to the stream is unchanged.
542 * One character pushback is guaranteed. If the unget function is called too
543 * many times on the same stream without an intervening read or file
544 * positioning operation on that stream, the operation may fail.
545 * If the value of c equals that of the macro EOF, the operation fails and
546 * the input stream is unchanged.
547 * A successful call to the ungetc function clears the end-of-file
548 * indicator. The value of the file position indicator after reading or
549 * discarding all pushed-back characters shall be the same as it was before
550 * the characters were pushed back. For a text stream, the value of the file
551 * position indicator after a successful call to the ungetc function is
552 * unspecified until all pushed-back characters are read or discarded. For a
553 * binary stream, the file position indicator is decremented by each
554 * successful call to the ungetc function; if its value was zero before a
555 * call, it is indeterminate after the call.
556 * Returns: the character pushed back after conversion, or EOF if the
560 extern size_t fread(void * /*ptr*/,
561 size_t /*size*/, size_t /*nmemb*/, FILE * /*stream*/);
563 * reads into the array pointed to by ptr, up to nmemb members whose size is
564 * specified by size, from the stream pointed to by stream. The file
565 * position indicator (if defined) is advanced by the number of characters
566 * successfully read. If an error occurs, the resulting value of the file
567 * position indicator is indeterminate. If a partial member is read, its
568 * value is indeterminate. The ferror or feof function shall be used to
569 * distinguish between a read error and end-of-file.
570 * Returns: the number of members successfully read, which may be less than
571 * nmemb if a read error or end-of-file is encountered. If size or
572 * nmemb is zero, fread returns zero and the contents of the array
573 * and the state of the stream remain unchanged.
575 extern size_t fwrite(const void * /*ptr*/,
576 size_t /*size*/, size_t /*nmemb*/, FILE * /*stream*/);
578 * writes, from the array pointed to by ptr up to nmemb members whose size
579 * is specified by size, to the stream pointed to by stream. The file
580 * position indicator (if defined) is advanced by the number of characters
581 * successfully written. If an error occurs, the resulting value of the file
582 * position indicator is indeterminate.
583 * Returns: the number of members successfully written, which will be less
584 * than nmemb only if a write error is encountered.
587 extern int fgetpos(FILE * /*stream*/, fpos_t * /*pos*/);
589 * stores the current value of the file position indicator for the stream
590 * pointed to by stream in the object pointed to by pos. The value stored
591 * contains unspecified information usable by the fsetpos function for
592 * repositioning the stream to its position at the time of the call to the
594 * Returns: zero, if successful. Otherwise nonzero is returned and the
595 * integer expression errno is set to an implementation-defined
596 * nonzero value (under RISCOS/Arthur/Brazil fgetpos cannot fail).
598 extern int fseek(FILE * /*stream*/, long int /*offset*/, int /*whence*/);
600 * sets the file position indicator for the stream pointed to by stream.
601 * For a binary stream, the new position is at the signed number of
602 * characters specified by offset away from the point specified by whence.
603 * The specified point is the beginning of the file for SEEK_SET, the
604 * current position in the file for SEEK_CUR, or end-of-file for SEEK_END.
605 * A binary stream need not meaningfully support fseek calls with a whence
607 * For a text stream, either offset shall be zero, or offset shall be a
608 * value returned by an earlier call to the ftell function on the same
609 * stream and whence shall be SEEK_SET.
610 * The fseek function clears the end-of-file indicator and undoes any
611 * effects of the ungetc function on the same stream. After an fseek call,
612 * the next operation on an update stream may be either input or output.
613 * Returns: nonzero only for a request that cannot be satisfied.
615 extern int fsetpos(FILE * /*stream*/, const fpos_t * /*pos*/);
617 * sets the file position indicator for the stream pointed to by stream
618 * according to the value of the object pointed to by pos, which shall be a
619 * value returned by an earlier call to the fgetpos function on the same
621 * The fsetpos function clears the end-of-file indicator and undoes any
622 * effects of the ungetc function on the same stream. After an fsetpos call,
623 * the next operation on an update stream may be either input or output.
624 * Returns: zero, if successful. Otherwise nonzero is returned and the
625 * integer expression errno is set to an implementation-defined
626 * nonzero value (under RISCOS/Arthur/Brazil the value that of EDOM
629 extern long int ftell(FILE * /*stream*/);
631 * obtains the current value of the file position indicator for the stream
632 * pointed to by stream. For a binary stream, the value is the number of
633 * characters from the beginning of the file. For a text stream, the file
634 * position indicator contains unspecified information, usable by the fseek
635 * function for returning the file position indicator to its position at the
636 * time of the ftell call; the difference between two such return values is
637 * not necessarily a meaningful measure of the number of characters written
639 * Returns: if successful, the current value of the file position indicator.
640 * On failure, the ftell function returns -1L and sets the integer
641 * expression errno to an implementation-defined nonzero value
642 * (under RISCOS/Arthur/Brazil ftell cannot fail).
644 extern void rewind(FILE * /*stream*/);
646 * sets the file position indicator for the stream pointed to by stream to
647 * the beginning of the file. It is equivalent to
648 * (void)fseek(stream, 0L, SEEK_SET)
649 * except that the error indicator for the stream is also cleared.
653 extern void clearerr(FILE * /*stream*/);
655 * clears the end-of-file and error indicators for the stream pointed to by
656 * stream. These indicators are cleared only when the file is opened or by
657 * an explicit call to the clearerr function or to the rewind function.
661 #define feof(stream) ((stream)->__flag & _IOEOF)
663 extern int (feof)(FILE * /*stream*/);
666 * tests the end-of-file indicator for the stream pointed to by stream.
667 * Returns: nonzero iff the end-of-file indicator is set for stream.
669 #define ferror(stream) ((stream)->__flag & _IOERR)
671 extern int (ferror)(FILE * /*stream*/);
674 * tests the error indicator for the stream pointed to by stream.
675 * Returns: nonzero iff the error indicator is set for stream.
677 extern void perror(const char * /*s*/);
679 * maps the error number in the integer expression errno to an error
680 * message. It writes a sequence of characters to the standard error stream
681 * thus: first (if s is not a null pointer and the character pointed to by
682 * s is not the null character), the string pointed to by s followed by a
683 * colon and a space; then an appropriate error message string followed by
684 * a new-line character. The contents of the error message strings are the
685 * same as those returned by the strerror function with argument errno,
686 * which are implementation-defined.