a430bdb1 |
1 | /** @file\r |
2 | Macros, types, and functions for performing I/O.\r |
3 | \r |
4 | The following functions are declared in this file:<BR>\r |
5 | @verbatim\r |
6 | ################### Operations on files. ####\r |
7 | int remove (const char *FileName);\r |
8 | int rename (const char *, const char *);\r |
9 | FILE *tmpfile (void);\r |
10 | char *tmpnam (char *);\r |
11 | \r |
12 | ################### File access functions. ####\r |
13 | int fclose (FILE *);\r |
14 | int fflush (FILE *);\r |
15 | FILE *fopen (const char * __restrict ,\r |
16 | const char * __restrict);\r |
17 | FILE *freopen (const char * __restrict,\r |
18 | const char * __restrict, FILE * __restrict);\r |
19 | void setbuf (FILE * __restrict, char * __restrict);\r |
20 | int setvbuf (FILE * __restrict, char * __restrict,\r |
21 | int, size_t);\r |
22 | \r |
23 | ################### Formatted Input/Output Functions. ####\r |
24 | int fprintf (FILE * __restrict stream,\r |
25 | const char * __restrict format, ...);\r |
26 | int fscanf (FILE * __restrict, const char * __restrict, ...);\r |
27 | int printf (const char * __restrict, ...);\r |
28 | int scanf (const char * __restrict, ...);\r |
29 | int sprintf (char * __restrict, const char * __restrict, ...);\r |
30 | int sscanf (const char * __restrict,\r |
31 | const char * __restrict, ...);\r |
32 | int vfprintf (FILE * __restrict,\r |
33 | const char * __restrict, va_list);\r |
34 | int vprintf (const char * __restrict, va_list);\r |
35 | int vsprintf (char * __restrict,\r |
36 | const char * __restrict, va_list);\r |
37 | \r |
38 | ################### Character Input/Output Functions. ####\r |
39 | int fgetc (FILE *);\r |
40 | char *fgets (char * __restrict, int, FILE * __restrict);\r |
41 | int fputc (int, FILE *);\r |
42 | int fputs (const char * __restrict, FILE * __restrict);\r |
43 | int getc (FILE *);\r |
44 | int getchar (void);\r |
45 | char *gets (char *);\r |
46 | int putc (int, FILE *);\r |
47 | int putchar (int);\r |
48 | int puts (const char *);\r |
49 | int ungetc (int, FILE *);\r |
50 | \r |
51 | ################### Direct Input/Output Functions. ####\r |
52 | size_t fread (void * __restrict, size_t, size_t,\r |
53 | FILE * __restrict);\r |
54 | size_t fwrite (const void * __restrict, size_t, size_t,\r |
55 | FILE * __restrict);\r |
56 | \r |
57 | ################### File Positioning Functions. ####\r |
58 | int fgetpos (FILE * __restrict, fpos_t * __restrict);\r |
59 | int fseek (FILE *, long, int);\r |
60 | int fsetpos (FILE *, const fpos_t *);\r |
61 | long ftell (FILE *);\r |
62 | void rewind (FILE *);\r |
63 | \r |
64 | ################### Error-handling Functions. ####\r |
65 | void clearerr (FILE *);\r |
66 | int feof (FILE *);\r |
67 | int ferror (FILE *);\r |
68 | void perror (const char *);\r |
69 | \r |
70 | ################### Functions NOT specified by C95 ####\r |
71 | \r |
72 | FILE *fdopen (int, const char *);\r |
73 | void flockfile (FILE *);\r |
74 | int ftrylockfile (FILE *);\r |
75 | void funlockfile (FILE *);\r |
76 | int getc_unlocked (FILE *);\r |
77 | int getchar_unlocked(void);\r |
78 | int putc_unlocked (int, FILE *);\r |
79 | int putchar_unlocked(int);\r |
80 | int pclose (FILE *);\r |
81 | FILE *popen (const char *, const char *);\r |
82 | int snprintf (char * __restrict, size_t,\r |
83 | const char * __restrict, ...);\r |
84 | int vsnprintf (char * __restrict, size_t,\r |
85 | const char * __restrict, va_list);\r |
86 | char *mkdtemp (char *);\r |
87 | int mkstemp (char *);\r |
88 | char *mktemp (char *);\r |
89 | char *tempnam (const char *, const char *);\r |
90 | int fseeko (FILE *, off_t, int);\r |
91 | char *fgetln (FILE * __restrict, size_t * __restrict);\r |
92 | char *fparseln (FILE *, size_t *, size_t *, const char[3], int);\r |
93 | int fpurge (FILE *);\r |
94 | void setbuffer (FILE *, char *, int);\r |
95 | int setlinebuf (FILE *);\r |
96 | int vasprintf (char ** __restrict, const char * __restrict,\r |
97 | va_list);\r |
98 | int vscanf (const char * __restrict, va_list);\r |
99 | int vsscanf (const char * __restrict,\r |
100 | const char * __restrict, va_list);\r |
101 | @endverbatim\r |
102 | \r |
103 | @note To fit things in six character monocase externals, the stdio\r |
104 | code uses the prefix `__s' for stdio objects, typically followed\r |
105 | by a three-character attempt at a mnemonic.\r |
106 | \r |
107 | \r |
a7a8363d |
108 | Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>\r |
a430bdb1 |
109 | This program and the accompanying materials are licensed and made available under\r |
110 | the terms and conditions of the BSD License that accompanies this distribution.\r |
111 | The full text of the license may be found at\r |
112 | http://opensource.org/licenses/bsd-license.\r |
113 | \r |
114 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r |
115 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r |
116 | \r |
2aa62f2b |
117 | * Copyright (c) 1990, 1993\r |
118 | * The Regents of the University of California. All rights reserved.\r |
119 | *\r |
120 | * This code is derived from software contributed to Berkeley by\r |
121 | * Chris Torek.\r |
122 | *\r |
123 | * Redistribution and use in source and binary forms, with or without\r |
124 | * modification, are permitted provided that the following conditions\r |
125 | * are met:\r |
126 | * 1. Redistributions of source code must retain the above copyright\r |
127 | * notice, this list of conditions and the following disclaimer.\r |
128 | * 2. Redistributions in binary form must reproduce the above copyright\r |
129 | * notice, this list of conditions and the following disclaimer in the\r |
130 | * documentation and/or other materials provided with the distribution.\r |
131 | * 3. Neither the name of the University nor the names of its contributors\r |
132 | * may be used to endorse or promote products derived from this software\r |
133 | * without specific prior written permission.\r |
134 | *\r |
135 | * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND\r |
136 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\r |
137 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\r |
138 | * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE\r |
139 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r |
140 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r |
141 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r |
142 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\r |
143 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\r |
144 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\r |
145 | * SUCH DAMAGE.\r |
146 | *\r |
147 | * @(#)stdio.h 8.5 (Berkeley) 4/29/95\r |
a430bdb1 |
148 | NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp\r |
2aa62f2b |
149 | */\r |
2aa62f2b |
150 | #ifndef _STDIO_H_\r |
151 | #define _STDIO_H_\r |
152 | \r |
d7ce7006 |
153 | #include <stdarg.h>\r |
2aa62f2b |
154 | #include <limits.h>\r |
155 | #include <sys/ansi.h>\r |
156 | #include <machine/ansi.h>\r |
157 | \r |
158 | #ifdef _EFI_SIZE_T_\r |
a430bdb1 |
159 | /** size_t is the unsigned integer type of the result of the sizeof operator. **/\r |
2aa62f2b |
160 | typedef _EFI_SIZE_T_ size_t;\r |
161 | #undef _EFI_SIZE_T_\r |
53e1e5c6 |
162 | #undef _BSD_SIZE_T_\r |
2aa62f2b |
163 | #endif\r |
164 | \r |
a430bdb1 |
165 | /** @{\r |
166 | An object type capable of holding all information necessary to specify any\r |
167 | position within a file.\r |
168 | \r |
169 | Each wide-oriented stream has an associated mbstate_t object that stores the\r |
170 | current parse state of the stream. A successful call to fgetpos stores a\r |
171 | representation of the value of this mbstate_t object as part of the value\r |
172 | of the fpos_t object. A later successful call to fsetpos using the same\r |
173 | stored fpos_t value restores the value of the associated mbstate_t object\r |
174 | as well as the position within the controlled stream.\r |
175 | \r |
176 | This is fairly grotesque, but pure ANSI code must not inspect the\r |
177 | innards of an fpos_t anyway. The library internally uses off_t,\r |
178 | which we assume is exactly as big as eight chars.\r |
179 | **/\r |
2aa62f2b |
180 | #if (!defined(_ANSI_SOURCE) && !defined(__STRICT_ANSI__)) || defined(_LIBC)\r |
181 | typedef __off_t fpos_t;\r |
182 | #else\r |
183 | typedef struct __sfpos {\r |
184 | __off_t _pos;\r |
185 | } fpos_t;\r |
186 | #endif\r |
a430bdb1 |
187 | /*@}*/\r |
2aa62f2b |
188 | \r |
189 | /* stdio buffers */\r |
190 | struct __sbuf {\r |
191 | unsigned char *_base;\r |
192 | int _size;\r |
193 | };\r |
194 | \r |
a430bdb1 |
195 | /** Structure which holds all the information needed to control a stream or file.\r |
2aa62f2b |
196 | *\r |
a430bdb1 |
197 | * The following always hold:<BR>\r |
2aa62f2b |
198 | *\r |
a430bdb1 |
199 | * - if (_flags&(__SLBF|__SWR)) == (__SLBF|__SWR),\r |
200 | * - _lbfsize is -_bf._size, else _lbfsize is 0\r |
201 | * - if _flags&__SRD, _w is 0\r |
202 | * - if _flags&__SWR, _r is 0\r |
2aa62f2b |
203 | *\r |
204 | * This ensures that the getc and putc macros (or inline functions) never\r |
205 | * try to write or read from a file that is in `read' or `write' mode.\r |
206 | * (Moreover, they can, and do, automatically switch from read mode to\r |
207 | * write mode, and back, on "r+" and "w+" files.)\r |
208 | *\r |
209 | * _lbfsize is used only to make the inline line-buffered output stream\r |
210 | * code as compact as possible.\r |
211 | *\r |
212 | * _ub, _up, and _ur are used when ungetc() pushes back more characters\r |
213 | * than fit in the current _bf, or when ungetc() pushes back a character\r |
214 | * that does not match the previous one in _bf. When this happens,\r |
215 | * _ub._base becomes non-nil (i.e., a stream has ungetc() data iff\r |
216 | * _ub._base!=NULL) and _up and _ur save the current values of _p and _r.\r |
217 | *\r |
2aa62f2b |
218 | */\r |
219 | typedef struct __sFILE {\r |
a430bdb1 |
220 | unsigned char *_p; /**< current position in (some) buffer */\r |
221 | int _r; /**< read space left for getc() */\r |
222 | int _w; /**< write space left for putc() */\r |
223 | unsigned short _flags; /**< flags, below; this FILE is free if 0 */\r |
224 | short _file; /**< fileno, if Unix descriptor, else -1 */\r |
225 | struct __sbuf _bf; /**< the buffer (at least 1 byte, if !NULL) */\r |
226 | int _lbfsize; /**< 0 or -_bf._size, for inline putc */\r |
2aa62f2b |
227 | \r |
228 | /* operations */\r |
a430bdb1 |
229 | void *_cookie; /**< cookie passed to io functions */\r |
2aa62f2b |
230 | int (*_close)(void *);\r |
231 | int (*_read) (void *, char *, int);\r |
232 | fpos_t (*_seek) (void *, fpos_t, int);\r |
233 | int (*_write)(void *, const char *, int);\r |
234 | \r |
a430bdb1 |
235 | /** file extension */\r |
2aa62f2b |
236 | struct __sbuf _ext;\r |
237 | \r |
a430bdb1 |
238 | /** @{\r |
239 | Separate buffer for long sequences of ungetc().\r |
240 | **/\r |
241 | unsigned char *_up; /**< saved _p when _p is doing ungetc data */\r |
242 | int _ur; /**< saved _r when _r is counting ungetc data */\r |
243 | /*@}*/\r |
2aa62f2b |
244 | \r |
245 | /* tricks to meet minimum requirements even when malloc() fails */\r |
a7a8363d |
246 | unsigned char _ubuf[3 * MB_LEN_MAX]; /**< guarantee an ungetc() buffer */\r |
247 | unsigned char _nbuf[1 * MB_LEN_MAX]; /**< guarantee a getc() buffer */\r |
2aa62f2b |
248 | \r |
a430bdb1 |
249 | /** separate buffer for fgetln() when line crosses buffer boundary */\r |
2aa62f2b |
250 | struct __sbuf _lb; /* buffer for fgetln() */\r |
251 | \r |
252 | /* Unix stdio files get aligned to block boundaries on fseek() */\r |
a430bdb1 |
253 | int _blksize; /**< stat.st_blksize (may be != _bf._size) */\r |
254 | fpos_t _offset; /**< current lseek offset */\r |
2aa62f2b |
255 | } FILE;\r |
256 | \r |
257 | __BEGIN_DECLS\r |
258 | extern FILE __sF[];\r |
259 | __END_DECLS\r |
260 | \r |
a430bdb1 |
261 | #define __SLBF 0x0001 /**< line buffered */\r |
262 | #define __SNBF 0x0002 /**< unbuffered */\r |
263 | #define __SRD 0x0004 /**< OK to read */\r |
264 | #define __SWR 0x0008 /**< OK to write */\r |
2aa62f2b |
265 | /* RD and WR are never simultaneously asserted */\r |
a430bdb1 |
266 | #define __SRW 0x0010 /**< open for reading & writing */\r |
267 | #define __SEOF 0x0020 /**< found EOF */\r |
268 | #define __SERR 0x0040 /**< found error */\r |
269 | #define __SMBF 0x0080 /**< _buf is from malloc */\r |
270 | #define __SAPP 0x0100 /**< fdopen()ed in append mode */\r |
271 | #define __SSTR 0x0200 /**< this is an sprintf/snprintf string */\r |
272 | #define __SOPT 0x0400 /**< do fseek() optimization */\r |
273 | #define __SNPT 0x0800 /**< do not do fseek() optimization */\r |
274 | #define __SOFF 0x1000 /**< set iff _offset is in fact correct */\r |
275 | #define __SMOD 0x2000 /**< true => fgetln modified _p text */\r |
276 | #define __SALC 0x4000 /**< allocate string space dynamically */\r |
2aa62f2b |
277 | \r |
a430bdb1 |
278 | /* The following three definitions are for ANSI C, which took them\r |
279 | from System V, which brilliantly took internal interface macros and\r |
280 | made them official arguments to setvbuf(), without renaming them.\r |
281 | Hence, these ugly _IOxxx names are *supposed* to appear in user code.\r |
282 | \r |
283 | Although numbered as their counterparts above, the implementation\r |
284 | does not rely on this.\r |
2aa62f2b |
285 | */\r |
a430bdb1 |
286 | #define _IOFBF 0 /**< setvbuf should set fully buffered */\r |
287 | #define _IOLBF 1 /**< setvbuf should set line buffered */\r |
288 | #define _IONBF 2 /**< setvbuf should set unbuffered */\r |
2aa62f2b |
289 | \r |
a430bdb1 |
290 | #define BUFSIZ 1024 /**< size of buffer used by setbuf */\r |
291 | #define EOF (-1) /**< A constant integer expression indicating end-of-file. */\r |
2aa62f2b |
292 | \r |
a430bdb1 |
293 | /** FOPEN_MAX is a minimum maximum, and is the number of streams that\r |
294 | stdio can provide without attempting to allocate further resources\r |
295 | (which could fail). Do not use this for anything.\r |
2aa62f2b |
296 | */\r |
297 | #define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */\r |
a430bdb1 |
298 | \r |
299 | /** Size needed for an array of char large enough to hold the longest file name string. */\r |
2aa62f2b |
300 | #define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */\r |
301 | \r |
a430bdb1 |
302 | /** Size needed for an array of char large enough to hold the file name string\r |
303 | generated by the tmpname() function.\r |
304 | **/\r |
2aa62f2b |
305 | #define L_tmpnam PATH_MAX /* must be == PATH_MAX */\r |
306 | \r |
307 | #ifndef TMP_MAX\r |
a430bdb1 |
308 | #define TMP_MAX 308915776 /**< The maximum number of unique file names\r |
309 | that can be generated by tmpnam(). **/\r |
2aa62f2b |
310 | #endif\r |
311 | \r |
312 | /* Always ensure that these are consistent with <fcntl.h>! */\r |
313 | #ifndef SEEK_SET\r |
a430bdb1 |
314 | #define SEEK_SET 0 /**< set file offset to offset */\r |
2aa62f2b |
315 | #endif\r |
316 | #ifndef SEEK_CUR\r |
a430bdb1 |
317 | #define SEEK_CUR 1 /**< set file offset to current plus offset */\r |
2aa62f2b |
318 | #endif\r |
319 | #ifndef SEEK_END\r |
a430bdb1 |
320 | #define SEEK_END 2 /**< set file offset to EOF plus offset */\r |
2aa62f2b |
321 | #endif\r |
322 | \r |
a430bdb1 |
323 | #define stdin (&__sF[0]) /**< FILE reference for the STanDard INput stream. */\r |
324 | #define stdout (&__sF[1]) /**< FILE reference for the STanDard OUTput stream. */\r |
325 | #define stderr (&__sF[2]) /**< FILE reference for the STanDard ERRor stream. */\r |
2aa62f2b |
326 | \r |
2aa62f2b |
327 | __BEGIN_DECLS\r |
a430bdb1 |
328 | /* Functions defined in C95 standard. ###################################### */\r |
329 | \r |
330 | /* ################ Operations on files. */\r |
331 | \r |
332 | /** Remove (delete) a file.\r |
333 | \r |
334 | @param[in] FileName The path to the file to be removed.\r |
335 | \r |
336 | @retval Zero The operation succeeded.\r |
337 | @retval Non-zero The operation failed.\r |
338 | **/\r |
339 | int remove (const char *FileName);\r |
340 | \r |
341 | /** Rename the file named OldName to NewName.\r |
342 | \r |
343 | @param[in] OldName The name of the existing file to be renamed.\r |
344 | @param[in] NewName The new name of the file.\r |
345 | \r |
346 | @retval Zero The operation succeeded.\r |
347 | @retval Non-zero The operation failed. OldName still exists and has been unmodified.\r |
348 | If OldName does not exist, or a file named NewName already exists,\r |
349 | rename() will fail are return a non-zero value.\r |
350 | **/\r |
351 | int rename (const char *OldName, const char *NewName);\r |
352 | \r |
353 | /** Create a guaranteed unique temporary file.\r |
354 | A binary file is created in the _PATH_TMP directory that is guaranteed to\r |
355 | have a unique name. The file will be open for update with mode "wb+" and\r |
356 | its FILE pointer returned upon successfull completion. When the file is\r |
357 | closed, or when the creating program terminates, the file will be removed.\r |
358 | \r |
359 | @retval NULL The temporary file could not be created.\r |
360 | @retval non-NULL The returned value is a pointer to the FILE object\r |
361 | associated with the newly created and open temporary file.\r |
362 | **/\r |
363 | FILE *tmpfile (void);\r |
364 | \r |
365 | /** Generate a string that is a valid file name, in the _PATH_TMP directory, that\r |
366 | is not the same as the name of an existing file. The function can potentially\r |
367 | generate up to TMP_MAX different strings.\r |
368 | \r |
369 | @param[out] Buffer A pointer to an array of at least L_tmpnam char elements.\r |
370 | or NULL. If non-NULL, the tmpnam function writes its\r |
371 | result into that array and returns the argument\r |
372 | as its value.\r |
373 | \r |
374 | @return If no suitable string can be generated a NULL pointer is returned.\r |
375 | Otherwise, if Buffer is NULL, the result is produced in an internal\r |
376 | static object and a pointer to that object is returned. If Buffer\r |
377 | is non-null, the results are written into the array pointed to by\r |
378 | Buffer and Buffer is returned.\r |
379 | **/\r |
380 | char *tmpnam (char *Buffer);\r |
381 | \r |
382 | /* ################ File access functions. */\r |
383 | \r |
384 | /** Close the open stream, specified by fp, and de-associate it from any file or device.\r |
385 | \r |
386 | @param[in] fp Pointer to a stream object, of type FILE, associated with a\r |
387 | file or device.\r |
388 | \r |
389 | @retval Zero The stream was successfully closed.\r |
390 | @retval Non-zero There was an error closing the stream.\r |
391 | **/\r |
392 | int fclose (FILE *fp);\r |
393 | \r |
394 | /** Empties any buffers associated with the stream specified by fp.\r |
395 | \r |
396 | @param[in] fp Pointer to a stream object, of type FILE, associated with a\r |
397 | file or device.\r |
398 | \r |
399 | @retval Zero The stream's buffers were successfully emptied.\r |
400 | @retval EOF There was an error writing to the stream.\r |
401 | **/\r |
402 | int fflush (FILE *fp);\r |
403 | \r |
404 | /** Associates a file, named by Path, with a stream and prepares it for subsequent\r |
405 | operations.\r |
406 | \r |
407 | The parameter Mode points to a string specifying behavior characteristics for\r |
408 | the opened file. The recognized Mode strings are:\r |
409 | - r Open text file for reading.\r |
410 | - w Truncate file to zero length or create text file for writing.\r |
411 | - a Open or create a text file for writing at end-of-file (append).\r |
412 | - rb Open binary file for reading.\r |
413 | - wb Truncate file to zero length or create binary file for writing.\r |
414 | - ab Open or create a binary file for writing at end-of-file (append).\r |
415 | - r+ Open text file for update (reading and writing).\r |
416 | - w+ Truncate file to zero length or create text file for update.\r |
417 | - a+ Open or create a text file for update, writing at end-of-file.\r |
418 | - r+b or rb+ Open binary file for update (reading and writing).\r |
419 | - w+b or wb+ Truncate file to zero length or create binary file for update.\r |
420 | - a+b or ab+ Open or create a binary file for update, writing at end-of-file.\r |
421 | \r |
422 | Opening a file with read mode fails if the file does not exist.\r |
423 | \r |
424 | Opening a file with append mode causes all writes to the file to be forced to\r |
425 | the current end-of-file, regardless of any intervening calls to fseek.\r |
426 | \r |
427 | @param[in] Path The path or name of the file or device to open.\r |
428 | @param[in] Mode The mode in which the file is to be opened.\r |
429 | \r |
430 | @return A pointer to a FILE object associated with the opened file is returned\r |
431 | if the file was opened successfully. Otherwise, NULL is returned.\r |
432 | **/\r |
433 | FILE *fopen (const char * __restrict Path, const char * __restrict Mode);\r |
434 | \r |
435 | /** Closes the file associated with Ofp then opens the file specified by Path and associates it with\r |
436 | stream Ofp.\r |
437 | \r |
438 | Any errors that occur when closing Ofp are ignored. The file specified by Path is opened with mode Mode\r |
439 | and associated with stream Ofp instead of producing a new stream object.\r |
440 | \r |
441 | If Path is NULL, the mode of the file associated with Ofp is changed to Mode.\r |
442 | \r |
443 | @param[in] Path The path or name of the file or device to open.\r |
444 | @param[in] Mode The mode in which the file is to be opened.\r |
445 | @param[in] Ofp Pointer to the FILE object to be closed and associated with the new file.\r |
446 | \r |
447 | @return If Path was not able to be opened, or the mode changed, NULL is returned;\r |
448 | otherwise Ofp is returned.\r |
449 | **/\r |
450 | FILE *freopen (const char * __restrict Path, const char * __restrict Mode, FILE * __restrict Ofp);\r |
451 | \r |
452 | /** Establishes Fully Buffered or Non-buffered mode for a stream, fp, using Buff as the buffer.\r |
453 | \r |
454 | The file associated with fp must have been successfully opened with no operations, other than\r |
455 | possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.\r |
456 | \r |
457 | If Buff is non-NULL, the stream associated with fp is set to Fully Buffered mode using the\r |
458 | array pointed to by Buff as the buffer. The buffer is assumed to be BUFSIZ char long.\r |
459 | This is equivalent to calling setvbuf(fp, Buff, _IOFBF, BUFSIZ);\r |
460 | \r |
461 | If Buff is NULL, stream fp is set to Non-buffered mode.\r |
462 | This is equivalent to calling setvbuf(fp, NULL, _IONBF, 0);\r |
463 | \r |
464 | @param[in] fp Pointer to the FILE object which will have its buffer set.\r |
465 | @param[in] Buff The buffer to use for fp, or NULL.\r |
466 | **/\r |
467 | void setbuf (FILE * __restrict fp, char * __restrict Buff);\r |
468 | \r |
469 | /** Establishes a buffering mode and buffer for use by operations performed on the file associated with fp.\r |
470 | \r |
471 | The file associated with fp must have been successfully opened with no operations, other than\r |
472 | possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.\r |
473 | \r |
474 | Parameter BufMode determines how stream fp will be buffered:\r |
475 | - _IOFBF causes I/O to be fully buffered.\r |
476 | - _IOLBF causes I/O to be line buffered.\r |
477 | - _IONBF causes I/O to be unbuffered.\r |
478 | \r |
479 | If Buff is not NULL, it points to an array to be used as an I/O buffer for stream fp. The\r |
480 | buffer is set to BufSize char in length. Otherwise, an array of BufSize char is allocated\r |
481 | by the setvbuf function if BufMode is not _IONBF.\r |
482 | \r |
483 | It is an error for BufSize to be zero unless BufMode is _IONBF, in which case BufSize is ignored.\r |
484 | \r |
485 | @param[in] fp Pointer to the FILE object which will have its buffer set.\r |
486 | @param[in] Buff The buffer to use for fp, or NULL.\r |
487 | @param[in] BufMode The buffering mode to use.\r |
488 | @param[in] BufSize The size of the buffer to use, specified in char.\r |
489 | \r |
490 | @retval Zero The buffer and mode were established successfully.\r |
491 | @retval Non-zero The request can not be honored, or an invalid value for BufMode was given.\r |
492 | **/\r |
493 | int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, size_t BufSize);\r |
494 | \r |
495 | /* ################ Formatted Input/Output Functions. */\r |
2aa62f2b |
496 | \r |
497 | /** The fprintf function writes output to the stream pointed to by stream,\r |
498 | under control of the string pointed to by format that specifies how\r |
499 | subsequent arguments are converted for output. If there are insufficient\r |
a430bdb1 |
500 | arguments for the format, the behavior is indeterminate. If the format is\r |
2aa62f2b |
501 | exhausted while arguments remain, the excess arguments are evaluated\r |
502 | (as always) but are otherwise ignored. The fprintf function returns when\r |
503 | the end of the format string is encountered.\r |
504 | \r |
a430bdb1 |
505 | The format is interpreted as a multibyte character sequence, beginning and ending\r |
506 | in its initial shift state. The format is composed of zero or more directives:\r |
2aa62f2b |
507 | ordinary multibyte characters (not %), which are copied unchanged to the\r |
508 | output stream; and conversion specifications, each of which results in\r |
509 | fetching zero or more subsequent arguments, converting them, if applicable,\r |
510 | according to the corresponding conversion specifier, and then writing the\r |
511 | result to the output stream.\r |
512 | \r |
513 | Each conversion specification is introduced by the character %. After\r |
514 | the %, the following appear in sequence:\r |
515 | - Zero or more flags (in any order) that modify the meaning of the\r |
516 | conversion specification.\r |
517 | - An optional minimum field width. If the converted value has fewer\r |
518 | characters than the field width, it is padded with spaces (by default)\r |
519 | on the left (or right, if the left adjustment flag, described later,\r |
520 | has been given) to the field width. The field width takes the form of\r |
521 | an asterisk * (described later) or a nonnegative decimal integer.\r |
522 | - An optional precision that gives the minimum number of digits to appear\r |
523 | for the d, i, o, u, x, and X conversions, the number of digits to\r |
524 | appear after the decimal-point character for e, E, f, and F\r |
525 | conversions, the maximum number of significant digits for the g and G\r |
526 | conversions, or the maximum number of bytes to be written for s\r |
527 | conversions. The precision takes the form of a period (.) followed\r |
528 | either by an asterisk * (described later) or by an optional decimal\r |
529 | integer; if only the period is specified, the precision is taken as\r |
a430bdb1 |
530 | zero. If a precision appears with any other conversion specifier, it\r |
531 | is ignored.\r |
2aa62f2b |
532 | - An optional length modifier that specifies the size of the argument.\r |
533 | - A conversion specifier character that specifies the type of conversion\r |
534 | to be applied.\r |
535 | \r |
536 | As noted above, a field width, or precision, or both, may be indicated by\r |
537 | an asterisk. In this case, an int argument supplies the field width or\r |
538 | precision. The arguments specifying field width, or precision, or both, shall\r |
539 | appear (in that order) before the argument (if any) to be converted. A negative\r |
540 | field width argument is taken as a - flag followed by a positive field width.\r |
a430bdb1 |
541 | A negative precision argument is interpreted as if the precision were omitted.\r |
2aa62f2b |
542 | \r |
543 | The flag characters and their meanings are:\r |
544 | - The result of the conversion is left-justified within the field.\r |
545 | (It is right-justified if this flag is not specified.)\r |
546 | + The result of a signed conversion always begins with a plus or\r |
547 | minus sign. (It begins with a sign only when a negative value is\r |
548 | converted if this flag is not specified.)\r |
549 | space If the first character of a signed conversion is not a sign, or\r |
550 | if a signed conversion results in no characters, a space is\r |
551 | prefixed to the result. If the space and + flags both appear, the\r |
552 | space flag is ignored.\r |
a430bdb1 |
553 | # The result is converted to an "alternative form".\r |
554 | - For o conversion, it increases the precision, if and only if necessary,\r |
555 | to force the first digit of the result to be a zero (if the value\r |
556 | and precision are both 0, a single 0 is printed).\r |
557 | - For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it.\r |
558 | - For e, E, f, F, g, and G conversions, the result of converting a\r |
559 | floating-point number always contains a decimal-point character,\r |
560 | even if no digits follow it. (Normally, a decimal-point character\r |
561 | appears in the result of these conversions only if a digit follows\r |
562 | it.)\r |
563 | - For g and G conversions, trailing zeros are not removed from\r |
564 | the result. For other conversions, it is ignored.\r |
2aa62f2b |
565 | 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading\r |
566 | zeros (following any indication of sign or base) are used to pad to\r |
567 | the field width rather than performing space padding, except when\r |
568 | converting an infinity or NaN. If the 0 and - flags both appear,\r |
569 | the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a\r |
a430bdb1 |
570 | precision is specified, the 0 flag is ignored.\r |
2aa62f2b |
571 | \r |
572 | The length modifiers and their meanings are:\r |
573 | hh Specifies that a following d, i, o, u, x, or X conversion specifier\r |
574 | applies to a signed char or unsigned char argument (the argument\r |
575 | will have been promoted according to the integer promotions, but\r |
576 | its value shall be converted to signed char or unsigned char before\r |
577 | printing); or that a following n conversion specifier applies to a\r |
578 | pointer to a signed char argument.\r |
579 | h Specifies that a following d, i, o, u, x, or X conversion specifier\r |
580 | applies to a short int or unsigned short int argument (the argument\r |
581 | will have been promoted according to the integer promotions, but\r |
582 | its value shall be converted to short int or unsigned short int\r |
583 | before printing); or that a following n conversion specifier\r |
584 | applies to a pointer to a short int argument.\r |
585 | l (ell) Specifies that a following d, i, o, u, x, or X conversion\r |
586 | specifier applies to a long int or unsigned long int argument; that\r |
587 | a following n conversion specifier applies to a pointer to a long\r |
588 | int argument; that a following c conversion specifier applies to a\r |
589 | wint_t argument; that a following s conversion specifier applies to\r |
590 | a pointer to a wchar_t argument; or has no effect on a following e,\r |
591 | E, f, F, g, or G conversion specifier.\r |
592 | ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion\r |
593 | specifier applies to a long long int or unsigned long long int\r |
594 | argument; or that a following n conversion specifier applies to a\r |
595 | pointer to a long long int argument.\r |
596 | j Specifies that a following d, i, o, u, x, or X conversion specifier\r |
597 | applies to an intmax_t or uintmax_t argument; or that a following n\r |
598 | conversion specifier applies to a pointer to an intmax_t argument.\r |
599 | z Specifies that a following d, i, o, u, x, or X conversion specifier\r |
600 | applies to a size_t or the corresponding signed integer type\r |
601 | argument; or that a following n conversion specifier applies to a\r |
602 | pointer to a signed integer type corresponding to size_t argument.\r |
603 | t Specifies that a following d, i, o, u, x, or X conversion specifier\r |
604 | applies to a ptrdiff_t or the corresponding unsigned integer type\r |
605 | argument; or that a following n conversion specifier applies to a\r |
606 | pointer to a ptrdiff_t argument.\r |
607 | L Specifies that a following e, E, f, F, g, or G conversion specifier\r |
608 | applies to a long double argument.\r |
609 | \r |
610 | If a length modifier appears with any conversion specifier other than as\r |
a430bdb1 |
611 | specified above, it is ignored.\r |
2aa62f2b |
612 | \r |
613 | The conversion specifiers and their meanings are:\r |
614 | d,i The int argument is converted to signed decimal in the style\r |
615 | [-]dddd. The precision specifies the minimum number of digits to\r |
616 | appear; if the value being converted can be represented in fewer\r |
617 | digits, it is expanded with leading zeros. The default precision\r |
618 | is 1. The result of converting a zero value with a precision of\r |
619 | zero is no characters.\r |
620 | o,u,x,X The unsigned int argument is converted to unsigned octal (o),\r |
621 | unsigned decimal (u), or unsigned hexadecimal notation (x or X) in\r |
622 | the style dddd; the letters abcdef are used for x conversion and\r |
623 | the letters ABCDEF for X conversion. The precision specifies the\r |
624 | minimum number of digits to appear; if the value being converted\r |
625 | can be represented in fewer digits, it is expanded with leading\r |
626 | zeros. The default precision is 1. The result of converting a zero\r |
627 | value with a precision of zero is no characters.\r |
628 | f,F A double argument representing a floating-point number is\r |
629 | converted to decimal notation in the style [-]ddd.ddd, where the\r |
630 | number of digits after the decimal-point character is equal to the\r |
631 | precision specification. If the precision is missing, it is taken\r |
632 | as 6; if the precision is zero and the # flag is not specified, no\r |
633 | decimal-point character appears. If a decimal-point character\r |
634 | appears, at least one digit appears before it. The value is rounded\r |
635 | to the appropriate number of digits.\r |
a430bdb1 |
636 | A double argument representing an infinity is converted in\r |
637 | the style [-]inf. A double argument representing a NaN is\r |
638 | converted in the style [-]nan. The F conversion specifier produces INF,\r |
2aa62f2b |
639 | INFINITY, or NAN instead of inf, infinity, or nan, respectively.\r |
640 | e,E A double argument representing a floating-point number is\r |
641 | converted in the style [-]d.ddd e[+-]dd, where there is one digit\r |
642 | (which is nonzero if the argument is nonzero) before the\r |
643 | decimal-point character and the number of digits after it is equal\r |
644 | to the precision; if the precision is missing, it is taken as 6; if\r |
645 | the precision is zero and the # flag is not specified, no\r |
646 | decimal-point character appears. The value is rounded to the\r |
647 | appropriate number of digits. The E conversion specifier produces a\r |
648 | number with E instead of e introducing the exponent. The exponent\r |
649 | always contains at least two digits, and only as many more digits\r |
650 | as necessary to represent the exponent. If the value is zero, the\r |
651 | exponent is zero.\r |
652 | A double argument representing an infinity or NaN is converted\r |
653 | in the style of an f or F conversion specifier.\r |
654 | g,G A double argument representing a floating-point number is\r |
655 | converted in style f or e (or in style F or E in the case of a G\r |
656 | conversion specifier), depending on the value converted and the\r |
657 | precision. Let P equal the precision if nonzero, 6 if the precision\r |
658 | is omitted, or 1 if the precision is zero. Then, if a conversion\r |
659 | with style E would have an exponent of X:\r |
660 | - if P > X = -4, the conversion is with style f (or F) and\r |
661 | precision P - (X + 1).\r |
662 | - otherwise, the conversion is with style e (or E) and\r |
663 | precision P - 1.\r |
664 | \r |
665 | Finally, unless the # flag is used, any trailing zeros are removed\r |
666 | from the fractional portion of the result and the decimal-point\r |
667 | character is removed if there is no fractional portion remaining.\r |
668 | A double argument representing an infinity or NaN is converted in\r |
669 | the style of an f or F conversion specifier.\r |
670 | c If no l length modifier is present, the int argument is\r |
671 | converted to an unsigned char, and the resulting character is\r |
672 | written. If an l length modifier is present, the wint_t argument is\r |
673 | converted as if by an ls conversion specification with no precision\r |
674 | and an argument that points to the initial element of a two-element\r |
675 | array of wchar_t, the first element containing the wint_t argument\r |
676 | to the lc conversion specification and the second a null wide\r |
677 | character.\r |
678 | s If no l length modifier is present, the argument is a pointer\r |
679 | to the initial element of an array of character type. Characters\r |
680 | from the array are written up to (but not including) the\r |
681 | terminating null character. If the precision is specified, no more\r |
682 | than that many bytes are written. If the precision is not specified\r |
683 | or is greater than the size of the array, the array shall contain a\r |
684 | null character.\r |
685 | If an l length modifier is present, the argument shall be a\r |
686 | pointer to the initial element of an array of wchar_t type. Wide\r |
687 | characters from the array are converted to multibyte characters\r |
688 | (each as if by a call to the wcrtomb function, with the conversion\r |
689 | state described by an mbstate_t object initialized to zero before\r |
690 | the first wide character is converted) up to and including a\r |
691 | terminating null wide character. The resulting multibyte characters\r |
692 | are written up to (but not including) the terminating null\r |
693 | character (byte). If no precision is specified, the array shall\r |
694 | contain a null wide character. If a precision is specified, no more\r |
695 | than that many bytes are written (including shift sequences, if\r |
696 | any), and the array shall contain a null wide character if, to\r |
697 | equal the multibyte character sequence length given by the\r |
698 | precision, the function would need to access a wide character one\r |
699 | past the end of the array. In no case is a partial multibyte\r |
700 | character written.\r |
701 | p The argument shall be a pointer to void. The value of the\r |
a430bdb1 |
702 | pointer is converted to a sequence of printing characters.\r |
2aa62f2b |
703 | n The argument shall be a pointer to signed integer into which is\r |
704 | written the number of characters written to the output stream so\r |
705 | far by this call to fprintf. No argument is converted, but one is\r |
706 | consumed. If the conversion specification includes any flags, a\r |
a430bdb1 |
707 | field width, or a precision, they will be ignored.\r |
2aa62f2b |
708 | % A % character is written. No argument is converted. The\r |
709 | complete conversion specification shall be %%.\r |
710 | \r |
711 | In no case does a nonexistent or small field width cause truncation of a\r |
712 | field; if the result of a conversion is wider than the field width, the\r |
713 | field is expanded to contain the conversion result.\r |
714 | \r |
715 | @param[in] stream An open File specifier to which the output is sent.\r |
716 | @param[in] format A multi-byte character sequence containing characters\r |
717 | to be copied unchanged, and conversion specifiers\r |
61403bd7 |
718 | which convert their associated arguments.\r |
2aa62f2b |
719 | @param ... Variable number of parameters as required by format.\r |
720 | \r |
721 | @return The fprintf function returns the number of characters\r |
722 | transmitted, or a negative value if an output or encoding\r |
723 | error occurred.\r |
2aa62f2b |
724 | **/\r |
725 | int fprintf (FILE * __restrict stream, const char * __restrict format, ...);\r |
726 | \r |
a430bdb1 |
727 | /** Reads characters from stream, under control of format, storing the converted values\r |
728 | in variables pointed to by the variable-length parameter list.\r |
729 | \r |
730 | The format is interpreted as a multibyte character sequence, beginning and ending\r |
731 | in its initial shift state. The format is composed of zero or more directives:\r |
732 | one or more white-space characters, an ordinary multibyte character\r |
733 | (neither % nor a white-space character), or a conversion specification.\r |
734 | \r |
735 | Each conversion specification is introduced by the character %. After\r |
736 | the %, the following appear in sequence:\r |
737 | - An optional assignment-suppressing character, *.\r |
738 | - An optional decimal integer, greater than zero, that specifies the\r |
739 | maximum field width (in characters).\r |
740 | - An optional length modifier that specifies the size of the receiving object.\r |
741 | - A conversion specifier character that specifies the type of conversion\r |
742 | to be applied.\r |
743 | \r |
744 | The fscanf function executes each directive of the format in turn. If a directive fails, as\r |
745 | detailed below, the function returns. Failures are described as input failures (due to the\r |
746 | occurrence of an encoding error or the unavailability of input characters), or matching\r |
747 | failures (due to inappropriate input).\r |
748 | \r |
749 | A directive composed of white-space character(s) is executed by reading input up to the\r |
750 | first non-white-space character (which remains unread), or until no more characters can\r |
751 | be read.\r |
752 | \r |
753 | A directive that is an ordinary multibyte character is executed by reading the next\r |
754 | characters of the stream. If any of those characters differ from the ones composing the\r |
755 | directive, the directive fails and the differing and subsequent characters remain unread.\r |
756 | Similarly, if end-of-file, an encoding error, or a read error prevents a character from being\r |
757 | read, the directive fails.\r |
758 | \r |
759 | The length modifiers and their meanings are:\r |
760 | - hh Specifies that a following d, i, o, u, x, X, or n conversion\r |
761 | specifier applies to an argument with type pointer to signed\r |
762 | char or unsigned char.\r |
763 | - h Specifies that a following d, i, o, u, x, X, or n conversion\r |
764 | specifier applies to an argument with type pointer to short\r |
765 | int or unsigned short int.\r |
766 | - l (ell) Specifies that a following d, i, o, u, x, X, or n conversion\r |
767 | specifier applies to an argument with type pointer to\r |
768 | long int or unsigned long int; that a following a, A, e,\r |
769 | E, f, F, g, or G conversion specifier applies to an\r |
770 | argument with type pointer to double; or that a following\r |
771 | c, s, or [ conversion specifier applies to an argument\r |
772 | with type pointer to wchar_t.\r |
773 | - ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion\r |
774 | specifier applies to an argument with type pointer to\r |
775 | long long int or unsigned long long int.\r |
776 | - j Specifies that a following d, i, o, u, x, X, or n conversion\r |
777 | specifier applies to an argument with type pointer to\r |
778 | intmax_t or uintmax_t.\r |
779 | - z Specifies that a following d, i, o, u, x, X, or n conversion\r |
780 | specifier applies to an argument with type pointer to\r |
781 | size_t or the corresponding signed integer type.\r |
782 | - t Specifies that a following d, i, o, u, x, X, or n conversion\r |
783 | specifier applies to an argument with type pointer to\r |
784 | ptrdiff_t or the corresponding unsigned integer type.\r |
785 | - L Specifies that a following e, E, f, F, g, or G\r |
786 | conversion specifier applies to an argument with type\r |
787 | pointer to long double.\r |
788 | \r |
789 | If a length modifier appears with any conversion specifier other than as specified above,\r |
790 | it will be ignored.\r |
791 | \r |
792 | The conversion specifiers and their meanings are:\r |
793 | - d Matches an optionally signed decimal integer, whose format is\r |
794 | the same as expected for the subject sequence of the strtol\r |
795 | function with the value 10 for the base argument. The\r |
796 | corresponding argument shall be a pointer to signed integer.\r |
797 | - i Matches an optionally signed integer, whose format is the same\r |
798 | as expected for the subject sequence of the strtol function\r |
799 | with the value 0 for the base argument. The corresponding\r |
800 | argument shall be a pointer to signed integer.\r |
801 | - o Matches an optionally signed octal integer, whose format is the\r |
802 | same as expected for the subject sequence of the strtoul\r |
803 | function with the value 8 for the base argument. The\r |
804 | corresponding argument shall be a pointer to unsigned integer.\r |
805 | - u Matches an optionally signed decimal integer, whose format is\r |
806 | the same as expected for the subject sequence of the strtoul\r |
807 | function with the value 10 for the base argument. The\r |
808 | corresponding argument shall be a pointer to unsigned integer.\r |
809 | - x Matches an optionally signed hexadecimal integer, whose format\r |
810 | is the same as expected for the subject sequence of the strtoul\r |
811 | function with the value 16 for the base argument. The\r |
812 | corresponding argument shall be a pointer to unsigned integer.\r |
813 | - e,f,g Matches an optionally signed floating-point number, infinity,\r |
814 | or NaN, whose format is the same as expected for the subject\r |
815 | sequence of the strtod function. The corresponding argument\r |
816 | shall be a pointer to floating.\r |
817 | - c Matches a sequence of characters of exactly the number\r |
818 | specified by the field width (1 if no field width is present\r |
819 | in the directive). If no l length modifier is present, the\r |
820 | corresponding argument shall be a pointer to the initial\r |
821 | element of a character array large enough to accept the\r |
822 | sequence. No null character is added.<BR><BR>\r |
823 | If an l length modifier is present, the input shall be a\r |
824 | sequence of multibyte characters that begins in the initial\r |
825 | shift state. Each multibyte character in the sequence is\r |
826 | converted to a wide character as if by a call to the mbrtowc\r |
827 | function, with the conversion state described by an mbstate_t\r |
828 | object initialized to zero before the first multibyte character\r |
829 | is converted. The corresponding argument shall be a pointer to\r |
830 | the initial element of an array of wchar_t large enough to\r |
831 | accept the resulting sequence of wide characters. No null wide\r |
832 | character is added.\r |
833 | - s Matches a sequence of non-white-space characters.\r |
834 | If no l length modifier is present, the corresponding argument\r |
835 | shall be a pointer to the initial element of a character array\r |
836 | large enough to accept the sequence and a terminating null\r |
837 | character, which will be added automatically. If an l length\r |
838 | modifier is present, the input shall be a sequence of multibyte\r |
839 | characters that begins in the initial shift state. Each\r |
840 | multibyte character is converted to a wide character as if by a\r |
841 | call to the mbrtowc function, with the conversion state\r |
842 | described by an mbstate_t object initialized to zero before the\r |
843 | first multibyte character is converted. The corresponding\r |
844 | argument shall be a pointer to the initial element of an array\r |
845 | of wchar_t large enough to accept the sequence and the\r |
846 | terminating null wide character, which will be added automatically.\r |
847 | - [ Matches a nonempty sequence of characters from a set of\r |
848 | expected characters (the scanset).<BR><BR>\r |
849 | If no l length modifier is present, the corresponding argument\r |
850 | shall be a pointer to the initial element of a character array\r |
851 | large enough to accept the sequence and a terminating null\r |
852 | character, which will be added automatically. If an l length\r |
853 | modifier is present, the input shall be a sequence of multibyte\r |
854 | characters that begins in the initial shift state. Each\r |
855 | multibyte character is converted to a wide character as if by a\r |
856 | call to the mbrtowc function, with the conversion state\r |
857 | described by an mbstate_t object initialized to zero before the\r |
858 | first multibyte character is converted. The corresponding\r |
859 | argument shall be a pointer to the initial element of an array\r |
860 | of wchar_t large enough to accept the sequence and the\r |
861 | terminating null wide character, which will be added\r |
862 | automatically.<BR><BR>\r |
863 | The conversion specifier includes all subsequent characters in\r |
864 | the format string, up to and including the matching right\r |
865 | bracket (]). The characters between the brackets (the scanlist)\r |
866 | compose the scanset, unless the character after the left\r |
867 | bracket is a circumflex (^), in which case the scanset contains\r |
868 | all characters that do not appear in the scanlist between the\r |
869 | circumflex and the right bracket. If the conversion specifier\r |
870 | begins with [] or [^], the right bracket character is in the\r |
871 | scanlist and the next following right bracket character is the\r |
872 | matching right bracket that ends the specification; otherwise\r |
873 | the first following right bracket character is the one that\r |
874 | ends the specification. If a - character is in the scanlist and\r |
875 | is not the first, nor the second where the first character is\r |
876 | a ^, nor the last character, it will be treated as a regular character.\r |
877 | - p Matches a set of sequences, which are the same as the set of\r |
878 | sequences that are produced by the %p conversion of the fprintf\r |
879 | function. The corresponding argument must be a pointer to a\r |
880 | pointer to void. The input item is converted to a pointer value.\r |
881 | If the input item is a value converted earlier during the same\r |
882 | program execution, the pointer that results will compare equal\r |
883 | to that value; otherwise the behavior of the %p conversion is\r |
884 | indeterminate.\r |
885 | - n No input is consumed. The corresponding argument shall be a\r |
886 | pointer to signed integer into which is to be written the\r |
887 | number of characters read from the input stream so far by this\r |
888 | call to the fscanf function. Execution of a %n directive does\r |
889 | not increment the assignment count returned at the completion\r |
890 | of execution of the fscanf function. No argument is converted,\r |
891 | but one is consumed. If the conversion specification includes\r |
892 | an assignment suppressing character the conversion specification\r |
893 | is ignored. If the conversion specification contains a\r |
894 | field width, the field width will be ignored.\r |
895 | - % Matches a single % character; no conversion or assignment occurs.\r |
896 | \r |
897 | @param[in] stream An open File specifier from which the input is read.\r |
898 | @param[in] format A multi-byte character sequence containing characters\r |
899 | to be matched against, and conversion specifiers\r |
900 | which convert their associated arguments. Converted\r |
901 | items are stored according to their associated arguments.\r |
902 | @param ... Variable number of parameters, as required by format,\r |
903 | specifying the objects to receive the converted input.\r |
904 | \r |
905 | @return The fscanf function returns EOF if an input failure occurs before\r |
906 | any conversion. Otherwise the number of input items assigned\r |
907 | is returned; which can be fewer than provided for, or even zero\r |
908 | in the event of an early matching failure.\r |
909 | **/\r |
910 | int fscanf (FILE * __restrict stream, const char * __restrict format, ...);\r |
911 | \r |
912 | /** Formatted print to stdout.\r |
913 | \r |
914 | The printf function is equivalent to fprintf with stdout used as the output stream.\r |
915 | \r |
916 | @param[in] format A multi-byte character sequence containing characters\r |
917 | to be copied unchanged, and conversion specifiers\r |
918 | which convert their associated arguments. Copied and\r |
919 | converted characters are sent to the output stream.\r |
920 | @param ... Variable number of parameters as required by format.\r |
921 | \r |
922 | @return The printf function returns the number of characters\r |
923 | transmitted, or a negative value if an output or encoding\r |
924 | error occurred.\r |
925 | **/\r |
926 | int printf (const char * __restrict format, ...);\r |
927 | \r |
928 | /** Formatted input from stdin.\r |
929 | \r |
930 | The scanf function is equivalent to fscanf with stdin used as the input stream.\r |
931 | \r |
932 | @param[in] format A multi-byte character sequence containing characters\r |
933 | to be matched against, and conversion specifiers\r |
934 | which convert their associated arguments. Converted\r |
935 | items are stored according to their associated arguments.\r |
936 | @param[out] ... Variable number of parameters, as required by format,\r |
937 | specifying the objects to receive the converted input.\r |
938 | \r |
939 | @return The scanf function returns EOF if an input failure occurs before\r |
940 | any conversion. Otherwise the number of input items assigned\r |
941 | is returned; which can be fewer than provided for, or even zero\r |
942 | in the event of an early matching failure.\r |
943 | **/\r |
944 | int scanf (const char * __restrict format, ...);\r |
945 | \r |
946 | /** Formatted output to a buffer.\r |
947 | \r |
948 | The sprintf function is equivalent to fprintf, except that the output is\r |
949 | written into array Buff instead of to a stream. A null character is written\r |
950 | at the end of the characters written; it is not counted as part of the\r |
951 | returned value.\r |
952 | \r |
953 | @param[out] Buff A pointer to the array to receive the formatted output.\r |
954 | @param[in] Format A multi-byte character sequence containing characters\r |
955 | to be copied unchanged, and conversion specifiers\r |
956 | which convert their associated arguments. Copied and\r |
957 | converted characters are written to the array pointed\r |
958 | to by Buff.\r |
959 | @param ... Variable number of parameters as required by format.\r |
960 | \r |
961 | @return The sprintf function returns the number of characters written in\r |
962 | the array, not counting the terminating null character, or a\r |
963 | negative value if an encoding error occurred.\r |
964 | **/\r |
965 | int sprintf (char * __restrict Buff, const char * __restrict Format, ...);\r |
966 | \r |
967 | /** Formatted input from a string.\r |
968 | \r |
969 | The sscanf function is equivalent to fscanf, except that input is obtained\r |
970 | from a string rather than from a stream. Reaching the end of the string\r |
971 | is equivalent to encountering end-of-file for the fscanf function.\r |
972 | \r |
973 | @param[in] Buff Pointer to the string from which to obtain input.\r |
974 | @param[in] Format A multi-byte character sequence containing characters\r |
975 | to be matched against, and conversion specifiers\r |
976 | which convert their associated arguments. Converted\r |
977 | items are stored according to their associated arguments.\r |
978 | @param[out] ... Variable number of parameters, as required by format,\r |
979 | specifying the objects to receive the converted input.\r |
980 | \r |
981 | @return The scanf function returns EOF if an input failure occurs before\r |
982 | any conversion. Otherwise the number of input items assigned\r |
983 | is returned; which can be fewer than provided for, or even zero\r |
984 | in the event of an early matching failure.\r |
985 | **/\r |
986 | int sscanf (const char * __restrict Buff, const char * __restrict Format, ...);\r |
987 | \r |
988 | /** Print formatted values from an argument list.\r |
989 | \r |
990 | The vfprintf function is equivalent to fprintf, with the variable argument\r |
991 | list replaced by Args, which must have been initialized by the va_start macro.\r |
992 | The vfprintf function does not invoke the va_end macro.\r |
993 | \r |
994 | @param[in] Stream The output stream to receive the formatted output.\r |
995 | @param[in] Format A multi-byte character sequence containing characters\r |
996 | to be matched against, and conversion specifiers\r |
997 | which convert their associated arguments. Converted\r |
998 | items are stored according to their associated arguments.\r |
999 | @param[in] Args A list of arguments, initialized by the va_start macro\r |
1000 | and accessed using the va_arg macro, used to satisfy\r |
1001 | the directives in the Format string.\r |
1002 | \r |
1003 | @return The vfprintf function returns the number of characters transmitted,\r |
1004 | or a negative value if an output or encoding error occurred.\r |
1005 | **/\r |
1006 | int vfprintf(FILE * __restrict Stream, const char * __restrict Format, va_list Args);\r |
1007 | \r |
1008 | /** Formatted print, to stdout, from an argument list.\r |
1009 | \r |
1010 | The vprintf function is equivalent to printf, with the variable argument\r |
1011 | list replaced by Args, which must have been initialized by the va_start\r |
1012 | macro (and possibly subsequent va_arg calls). The vprintf function does\r |
1013 | not invoke the va_end macro.\r |
1014 | \r |
1015 | @param[in] Format A multi-byte character sequence containing characters\r |
1016 | to be matched against, and conversion specifiers\r |
1017 | which convert their associated arguments. Converted\r |
1018 | items are stored according to their associated arguments.\r |
1019 | @param[in] Args A list of arguments, initialized by the va_start macro\r |
1020 | and accessed using the va_arg macro, used to satisfy\r |
1021 | the directives in the Format string.\r |
1022 | \r |
1023 | @return The vprintf function returns the number of characters transmitted,\r |
1024 | or a negative value if an output or encoding error occurred.\r |
1025 | **/\r |
1026 | int vprintf (const char * __restrict Format, va_list Args);\r |
1027 | \r |
1028 | /** Formatted print, to a buffer, from an argument list.\r |
1029 | \r |
1030 | The vsprintf function is equivalent to sprintf, with the variable argument\r |
1031 | list replaced by Args, which must have been initialized by the va_start\r |
1032 | macro. The vsprintf function does not invoke the va_end macro.\r |
1033 | \r |
1034 | @param[out] Buff A pointer to the array to receive the formatted output.\r |
1035 | @param[in] Format A multi-byte character sequence containing characters\r |
1036 | to be copied unchanged, and conversion specifiers\r |
1037 | which convert their associated arguments. Copied and\r |
1038 | converted characters are written to the array pointed\r |
1039 | to by Buff.\r |
1040 | @param[in] Args A list of arguments, initialized by the va_start macro\r |
1041 | and accessed using the va_arg macro, used to satisfy\r |
1042 | the directives in the Format string.\r |
1043 | \r |
1044 | @return The vsprintf function returns the number of characters written in\r |
1045 | the array, not counting the terminating null character, or a\r |
1046 | negative value if an encoding error occurred.\r |
1047 | **/\r |
1048 | int vsprintf(char * __restrict Buff, const char * __restrict Format, va_list Args);\r |
1049 | \r |
1050 | /* ################ Character Input/Output Functions. */\r |
1051 | \r |
1052 | /** Get a character from an input Stream.\r |
1053 | \r |
1054 | If the end-of-file indicator for the input stream pointed to by Stream is\r |
1055 | not set, and a next character is present, the fgetc function obtains that\r |
1056 | character as an unsigned char converted to an int and advances the\r |
1057 | associated file position indicator for the stream.\r |
1058 | \r |
1059 | @param[in] Stream An input stream from which to obtain a character.\r |
1060 | \r |
1061 | @return If the end-of-file indicator for the stream is set, or if the\r |
1062 | stream is at end-of-file, the end-of-file indicator for the\r |
1063 | stream is set and the fgetc function returns EOF. Otherwise,\r |
1064 | the fgetc function returns the next character from the input\r |
1065 | stream pointed to by Stream. If a read error occurs, the\r |
1066 | error indicator for the stream is set and the fgetc function\r |
1067 | returns EOF.\r |
1068 | **/\r |
1069 | int fgetc (FILE *Stream);\r |
1070 | \r |
1071 | /** Read a string from an input stream into a buffer.\r |
1072 | \r |
1073 | The fgets function reads at most one less than the number of characters\r |
1074 | specified by Limit from the stream pointed to by Stream into the array\r |
1075 | pointed to by Buff. No additional characters are read after a\r |
1076 | new-line character (which is retained) or after end-of-file. A null\r |
1077 | character is written immediately after the last character read into the array.\r |
1078 | \r |
1079 | @param[out] Buff A pointer to the array to receive the input string.\r |
1080 | @param[in] Limit The maximum number of characters to put into Buff,\r |
1081 | including the terminating null character.\r |
1082 | @param[in] Stream An input stream from which to obtain a character.\r |
1083 | \r |
1084 | @return The fgets function returns Buff if successful. If end-of-file is\r |
1085 | encountered and no characters have been read into the array, the\r |
1086 | contents of the array remain unchanged and a null pointer is\r |
1087 | returned. If a read error occurs during the operation, the array\r |
1088 | contents are indeterminate and a null pointer is returned.\r |
1089 | **/\r |
1090 | char *fgets (char * __restrict Buff, int Limit, FILE * __restrict Stream);\r |
1091 | \r |
1092 | /** Write a character to an output stream.\r |
1093 | \r |
1094 | The fputc function writes the character specified by C (converted to an\r |
1095 | unsigned char) to the output stream pointed to by Stream, at the position\r |
1096 | indicated by the associated file position indicator for the stream\r |
1097 | (if defined), and advances the indicator appropriately. If the file cannot\r |
1098 | support positioning requests, or if the stream was opened with append mode,\r |
1099 | the character is appended to the output stream.\r |
1100 | \r |
1101 | @param[in] C The character to be written to Stream.\r |
1102 | @param[in] Stream The output stream that C is to be written to.\r |
1103 | \r |
1104 | @return The fputc function returns the character written. If a write\r |
1105 | error occurs, the error indicator for the stream is set and\r |
1106 | fputc returns EOF.\r |
1107 | **/\r |
1108 | int fputc (int C, FILE *Stream);\r |
1109 | \r |
1110 | /** Write a string to an output stream.\r |
1111 | \r |
1112 | The fputs function writes String to the stream pointed to by Stream. The\r |
1113 | terminating null character is not written.\r |
1114 | \r |
1115 | @param[in] String The character string to be written to Stream.\r |
1116 | @param[in] Stream The output stream that String is to be written to.\r |
1117 | \r |
1118 | @return The fputs function returns EOF if a write error occurs; otherwise\r |
1119 | it returns a non-negative value.\r |
1120 | **/\r |
1121 | int fputs (const char * __restrict String, FILE * __restrict Stream);\r |
1122 | \r |
1123 | /** Get a character from an input stream.\r |
1124 | \r |
1125 | The getc function is equivalent to fgetc, except that if it is implemented\r |
1126 | as a macro, it may evaluate stream more than once, so the argument should\r |
1127 | never be an expression with side effects.\r |
1128 | \r |
1129 | @param[in] Stream An input stream from which to obtain a character.\r |
1130 | \r |
1131 | @return If the end-of-file indicator for the stream is set, or if the\r |
1132 | stream is at end-of-file, the end-of-file indicator for the\r |
1133 | stream is set and getc returns EOF. Otherwise, getc returns\r |
1134 | the next character from the input stream pointed to by Stream.\r |
1135 | If a read error occurs, the error indicator for the stream is set\r |
1136 | and getc returns EOF.\r |
1137 | **/\r |
2aa62f2b |
1138 | int getc (FILE *);\r |
a430bdb1 |
1139 | \r |
1140 | /** Get a character from stdin.\r |
1141 | \r |
1142 | The getchar function is equivalent to getc with the argument stdin.\r |
1143 | \r |
1144 | @return If the end-of-file indicator for stdin is set, or if stdin\r |
1145 | is at end-of-file, the end-of-file indicator is set and getchar\r |
1146 | returns EOF. Otherwise, getchar returns the next character from\r |
1147 | stdin. If a read error occurs, the error indicator for stdin is\r |
1148 | set and getchar returns EOF.\r |
1149 | **/\r |
2aa62f2b |
1150 | int getchar (void);\r |
2aa62f2b |
1151 | \r |
a430bdb1 |
1152 | /** Read a string from stdin into a buffer.\r |
1153 | \r |
1154 | The gets function reads characters from the input stream pointed to by\r |
1155 | stdin, into the array pointed to by Buff, until end-of-file is encountered\r |
1156 | or a new-line character is read. Any new-line character is discarded, and\r |
1157 | a null character is written immediately after the last character read into\r |
1158 | the array.\r |
1159 | \r |
1160 | @param[out] Buff A pointer to the array to receive the input string.\r |
1161 | \r |
1162 | @return The gets function returns Buff if successful. If end-of-file is\r |
1163 | encountered and no characters have been read into the array, the\r |
1164 | contents of the array remain unchanged and a null pointer is\r |
1165 | returned. If a read error occurs during the operation, the array\r |
1166 | contents are indeterminate and a null pointer is returned.\r |
1167 | **/\r |
1168 | char *gets (char *Buff);\r |
1169 | \r |
1170 | /** Write a character to an output stream.\r |
1171 | \r |
1172 | The putc function is equivalent to fputc, except that if it is implemented\r |
1173 | as a macro, it may evaluate Stream more than once, so that argument should\r |
1174 | never be an expression with side effects.\r |
1175 | \r |
1176 | @param[in] C The character to be written to Stream.\r |
1177 | @param[in] Stream The output stream that C is to be written to.\r |
1178 | \r |
1179 | @return The putc function returns the character written. If a write\r |
1180 | error occurs, the error indicator for the stream is set and\r |
1181 | putc returns EOF.\r |
1182 | **/\r |
1183 | int putc (int C, FILE *Stream);\r |
1184 | \r |
1185 | /** Write a character to stdout.\r |
1186 | \r |
1187 | The putchar function is equivalent to putc with stdout as the Stream argument.\r |
1188 | \r |
1189 | @param[in] C The character to be written to stdout.\r |
1190 | \r |
1191 | @return The putchar function returns the character written. If a write\r |
1192 | error occurs, the error indicator for stdout is set and putchar\r |
1193 | returns EOF.\r |
1194 | **/\r |
1195 | int putchar (int C);\r |
1196 | \r |
1197 | /** Write String to stdout.\r |
1198 | \r |
1199 | The puts function writes the string pointed to by String to the stream\r |
1200 | pointed to by stdout, and appends a new-line character to the output. The\r |
1201 | terminating null character is not written.\r |
1202 | \r |
1203 | @param[in] String A pointer to the character string to write to stdout.\r |
1204 | \r |
1205 | @return The puts function returns EOF if a write error occurs; otherwise\r |
1206 | it returns a non-negative value.\r |
1207 | **/\r |
1208 | int puts (const char *String);\r |
1209 | \r |
1210 | /** Return a character to the input Stream as if it had not been read.\r |
1211 | \r |
1212 | The ungetc function pushes the character specified by C (converted to an\r |
1213 | unsigned char) back onto the input stream pointed to by Stream. Pushed-back\r |
1214 | characters will be returned by subsequent reads on that stream in the\r |
1215 | reverse order of their being pushed. A successful intervening call\r |
1216 | (with the stream pointed to by Stream) to a file positioning function\r |
1217 | (fseek, fsetpos, or rewind) discards any pushed-back characters for the\r |
1218 | stream. The external storage corresponding to the stream is unchanged.\r |
1219 | \r |
1220 | One character of pushback is guaranteed. If the ungetc function is called\r |
1221 | too many times on the same stream without an intervening read or file\r |
1222 | positioning operation on that stream, the operation will fail.\r |
1223 | \r |
1224 | If the value of C equals that of the macro EOF, the operation fails and the\r |
1225 | input stream is unchanged.\r |
1226 | \r |
1227 | A successful call to the ungetc function clears the end-of-file indicator\r |
1228 | for the stream. The value of the file position indicator for the stream\r |
1229 | after reading or discarding all pushed-back characters is the same as it\r |
1230 | was before the characters were pushed back. For a binary stream, its\r |
1231 | file position indicator is decremented by each successful call to the\r |
1232 | ungetc function; if its value was zero before a call, it will remain zero\r |
1233 | after the call.\r |
1234 | \r |
1235 | @param[in] C The character to push back onto the Stream.\r |
1236 | @param[in] Stream The output stream that C is to be pushed back onto.\r |
1237 | \r |
1238 | @return The ungetc function returns the character pushed back,\r |
1239 | or EOF if the operation fails.\r |
1240 | **/\r |
1241 | int ungetc (int C, FILE *Stream);\r |
1242 | \r |
1243 | /* ################ Direct Input/Output Functions. */\r |
1244 | \r |
1245 | /** Read Num elements of size Size from a Stream into a Buffer.\r |
1246 | \r |
1247 | The fread function reads, into the array pointed to by Buffer, up to Num\r |
1248 | elements, whose size is specified by Size, from the stream pointed to by\r |
1249 | Stream. For each object, Size calls are made to the fgetc function and the\r |
1250 | results stored, in the order read, in an array of unsigned char exactly\r |
1251 | overlaying the Buffer object. The file position indicator for the stream\r |
1252 | (if defined) is advanced by the number of characters successfully read. If\r |
1253 | an error occurs, the resulting value of the file position indicator for the\r |
1254 | stream is indeterminate.\r |
1255 | \r |
1256 | @param[out] Buffer Pointer to an object to receive the read data.\r |
1257 | @param[in] Size Size of each element to be read.\r |
1258 | @param[in] Num Number of elements to read.\r |
1259 | @param[in] Stream Input stream to read the data from.\r |
1260 | \r |
1261 | @return The fread function returns the number of elements successfully\r |
1262 | read, which may be less than Num if a read error or end-of-file\r |
1263 | is encountered. If Size or Num is zero, fread returns zero and\r |
1264 | the contents of the array and the state of the stream remain\r |
1265 | unchanged.\r |
1266 | **/\r |
1267 | size_t fread (void * __restrict Buffer,\r |
1268 | size_t Size,\r |
1269 | size_t Num,\r |
1270 | FILE * __restrict Stream\r |
1271 | );\r |
1272 | \r |
1273 | /** Write Num elements of size Size from Buffer to Stream.\r |
1274 | \r |
1275 | The fwrite function writes, from the array pointed to by Buffer, up to Num\r |
1276 | elements whose size is specified by Size, to the stream pointed to by\r |
1277 | Stream. For each object, Size calls are made to the fputc function, taking\r |
1278 | the values (in order) from an array of unsigned char exactly overlaying the\r |
1279 | Buffer object. The file position indicator for the stream (if defined) is\r |
1280 | advanced by the number of characters successfully written. If an error\r |
1281 | occurs, the resulting value of the file position indicator for the stream is\r |
1282 | indeterminate.\r |
1283 | \r |
1284 | @param[out] Buffer Pointer to an object containing the data to be written.\r |
1285 | @param[in] Size Size of each element to be written.\r |
1286 | @param[in] Num Number of elements to write.\r |
1287 | @param[in] Stream Output stream to write the data to.\r |
1288 | \r |
1289 | @return The fwrite function returns the number of elements successfully\r |
1290 | written, which will be less than Num only if a write error is\r |
1291 | encountered. If Size or Num is zero, fwrite returns zero and\r |
1292 | the state of the stream remains unchanged.\r |
1293 | **/\r |
1e6e6f50 |
1294 | size_t fwrite (const void * __restrict Buffer,\r |
1295 | size_t Size,\r |
1296 | size_t Num,\r |
1297 | FILE * __restrict Stream\r |
a430bdb1 |
1298 | );\r |
1299 | \r |
1300 | /* ################ File Positioning Functions. */\r |
1301 | \r |
1302 | /** Get a stream's position and parse state.\r |
1303 | \r |
1304 | The fgetpos function stores the current values of the parse state (if any)\r |
1305 | and file position indicator for the stream pointed to by Stream in the\r |
1306 | object pointed to by Pos. The values stored contain unspecified\r |
1307 | information usable by the fsetpos function for repositioning the stream\r |
1308 | to its position at the time of the call to the fgetpos function.\r |
1309 | \r |
1310 | @param[in] Stream Stream to get current position of.\r |
1311 | @param[out] Pos Object to receive the stream's state and position information.\r |
1312 | \r |
1313 | @return If successful, the fgetpos function returns zero; if either\r |
1314 | parameter is NULL, the fgetpos function returns nonzero and\r |
1315 | stores EINVAL in errno.\r |
1316 | **/\r |
1317 | int fgetpos (FILE * __restrict Stream, fpos_t * __restrict Pos);\r |
1318 | \r |
1319 | /** Set the file position for a stream.\r |
1320 | \r |
1321 | The fseek function sets the file position indicator for the stream pointed\r |
1322 | to by Stream. If a read or write error occurs, the error indicator for the\r |
1323 | stream is set and fseek fails.\r |
1324 | \r |
1325 | For a binary stream, the new position, measured in characters from the\r |
1326 | beginning of the file, is obtained by adding Offset to the position\r |
1327 | specified by Whence. The specified position is the beginning of the file if\r |
1328 | Whence is SEEK_SET, the current value of the file position indicator if\r |
1329 | SEEK_CUR, or end-of-file if SEEK_END.\r |
1330 | \r |
1331 | For a text stream, Offset must either be zero or a value returned by an\r |
1332 | earlier successful call to the ftell function, on a stream associated with\r |
1333 | the same file, and Whence must be SEEK_SET.\r |
1334 | \r |
1335 | After determining the new position, a successful call to the fseek function\r |
1336 | undoes any effects of the ungetc function on the stream, clears the\r |
1337 | end-of-file indicator for the stream, and then establishes the new position.\r |
1338 | After a successful fseek call, the next operation on an update stream may\r |
1339 | be either input or output.\r |
1340 | \r |
1341 | @param[in] Stream The I/O stream to set the position of.\r |
1342 | @param[in] Offset The position, interpreted depending upon the value of\r |
1343 | Whence, that the stream is to be positioned to.\r |
1344 | @param[in] Whence A value indicating how Offset is to be interpreted:\r |
1345 | - SEEK_SET indicates Offset is an absolute position.\r |
1346 | - SEEK_END indicates Offset is relative to the end of the file.\r |
1347 | - SEEK_CUR indicates Offset is relative to the current position.\r |
1348 | \r |
1349 | @return The fseek function returns nonzero only for a request that cannot be satisfied.\r |
1350 | **/\r |
1351 | int fseek (FILE *Stream, long Offset, int Whence);\r |
1352 | \r |
1353 | /** Set a stream's position and parse state.\r |
1354 | \r |
1355 | The fsetpos function sets the mbstate_t object (if any) and file position\r |
1356 | indicator for the stream pointed to by Stream according to the value of the\r |
1357 | object pointed to by Pos, which is a value that was obtained from an\r |
1358 | earlier successful call to the fgetpos function on a stream associated with\r |
1359 | the same file. If a read or write error occurs, the error indicator for the\r |
1360 | stream is set and fsetpos fails.\r |
1361 | \r |
1362 | A successful call to the fsetpos function undoes any effects of the ungetc\r |
1363 | function on the stream, clears the end-of-file indicator for the stream,\r |
1364 | and then establishes the new parse state and position. After a successful\r |
1365 | fsetpos call, the next operation on an update stream may be either input or output.\r |
1366 | \r |
1367 | @param[in] Stream Stream to set current position of.\r |
1368 | @param[in] Pos Object containing the state and position information.\r |
1369 | \r |
1370 | @return If successful, the fsetpos function returns zero; on failure, the\r |
1371 | fsetpos function returns nonzero and stores EINVAL, or ESPIPE,\r |
1372 | in errno; depending upon whether the error was because of an invalid\r |
1373 | parameter, or because Stream is not seekable.\r |
1374 | **/\r |
1375 | int fsetpos (FILE *Stream, const fpos_t *Pos);\r |
1376 | \r |
1377 | /** Get Stream's current position.\r |
1378 | \r |
1379 | The ftell function obtains the current value of the file position indicator\r |
1380 | for the stream pointed to by Stream. For a binary stream, the value is the\r |
1381 | number of characters from the beginning of the file. For a text stream, its\r |
1382 | file position indicator contains unspecified information, usable by the\r |
1383 | fseek function for returning the file position indicator for the stream to\r |
1384 | its position at the time of the ftell call; the difference between two such\r |
1385 | return values is not necessarily a meaningful measure of the number of\r |
1386 | characters written or read.\r |
1387 | \r |
1388 | @param[in] Stream Pointer to the FILE object to get the current position of.\r |
1389 | \r |
1390 | @return If successful, the ftell function returns the current value of\r |
1391 | the file position indicator for the stream. On failure, the\r |
1392 | ftell function returns -1L and stores ESPIPE in errno indicating\r |
1393 | that the stream is not seekable.\r |
1394 | **/\r |
1395 | long ftell (FILE *Stream);\r |
1396 | \r |
1397 | /** Restore a Stream's file position to the beginning of the file.\r |
1398 | \r |
1399 | The rewind function sets the file position indicator for the stream pointed\r |
1400 | to by Stream to the beginning of the file and clears the stream's error indicator.\r |
1401 | \r |
1402 | @param[in] Stream Pointer to the stream to be positioned to its beginning.\r |
1403 | **/\r |
1404 | void rewind (FILE *Stream);\r |
1405 | \r |
1406 | /* ################ Error-handling Functions. */\r |
1407 | \r |
1408 | /** Clear a Stream's error and end-of-file indicators.\r |
1409 | \r |
1410 | @param[in] Stream Pointer to the stream to be cleared of errors.\r |
1411 | **/\r |
1412 | void clearerr(FILE *Stream);\r |
1413 | \r |
1414 | /** Test the end-of-file indicator for Stream.\r |
1415 | \r |
1416 | @param[in] Stream Pointer to the FILE object to be tested for EOF.\r |
1417 | \r |
1418 | @return The feof function returns non-zero if, and only if, the end-of-file\r |
1419 | indicator is set for Stream.\r |
1420 | **/\r |
1421 | int feof (FILE *Stream);\r |
1422 | \r |
1423 | /** Test the error indicator for Stream.\r |
1424 | \r |
1425 | @param[in] Stream Pointer to the stream to be tested for error.\r |
1426 | \r |
1427 | @return The ferror function returns non-zero if, and only if, the error\r |
1428 | indicator is set for Stream.\r |
1429 | **/\r |
1430 | int ferror (FILE *Stream);\r |
1431 | \r |
1432 | /** Print an error message to stderr based upon the value of errno and String.\r |
1433 | \r |
1434 | The perror function maps the error number in the integer expression errno\r |
1435 | to an error message. It writes a sequence of characters to the standard\r |
1436 | error stream thus: first (if String is not a null pointer and the character\r |
1437 | pointed to by String is not the null character), the string pointed to by\r |
1438 | String followed by a colon (:) and a space; then an appropriate error\r |
1439 | message string followed by a new-line character. The contents of the error\r |
1440 | message strings are the same as those returned by the strerror function\r |
1441 | with argument errno.\r |
1442 | \r |
1443 | @param[in] String A text string to prefix the output error message with.\r |
1444 | \r |
1445 | @sa strerror in <string.h>\r |
1446 | **/\r |
1447 | void perror (const char *String);\r |
1448 | \r |
2aa62f2b |
1449 | __END_DECLS\r |
1450 | \r |
1451 | /*\r |
1452 | * IEEE Std 1003.1-90\r |
1453 | */\r |
a430bdb1 |
1454 | __BEGIN_DECLS\r |
1455 | FILE *fdopen(int, const char *);\r |
1456 | __END_DECLS\r |
2aa62f2b |
1457 | \r |
1458 | /*\r |
1459 | * IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2\r |
1460 | */\r |
a430bdb1 |
1461 | __BEGIN_DECLS\r |
1462 | void flockfile (FILE *);\r |
1463 | int ftrylockfile (FILE *);\r |
1464 | void funlockfile (FILE *);\r |
1465 | int getc_unlocked (FILE *);\r |
1466 | int getchar_unlocked(void);\r |
1467 | int putc_unlocked (int, FILE *);\r |
1468 | int putchar_unlocked(int);\r |
1469 | __END_DECLS\r |
2aa62f2b |
1470 | \r |
1471 | /*\r |
1472 | * Functions defined in POSIX 1003.2 and XPG2 or later.\r |
1473 | */\r |
d7ce7006 |
1474 | __BEGIN_DECLS\r |
2aa62f2b |
1475 | int pclose (FILE *);\r |
1476 | FILE *popen (const char *, const char *);\r |
d7ce7006 |
1477 | __END_DECLS\r |
2aa62f2b |
1478 | \r |
1479 | /*\r |
1480 | * Functions defined in ISO XPG4.2, ISO C99, POSIX 1003.1-2001 or later.\r |
1481 | */\r |
d7ce7006 |
1482 | __BEGIN_DECLS\r |
2aa62f2b |
1483 | int snprintf (char * __restrict, size_t, const char * __restrict, ...)\r |
1484 | __attribute__((__format__(__printf__, 3, 4)));\r |
d7ce7006 |
1485 | int vsnprintf(char * __restrict, size_t, const char * __restrict, va_list)\r |
2aa62f2b |
1486 | __attribute__((__format__(__printf__, 3, 0)));\r |
d7ce7006 |
1487 | __END_DECLS\r |
2aa62f2b |
1488 | \r |
1489 | /*\r |
1490 | * Functions defined in XPG4.2.\r |
1491 | */\r |
d7ce7006 |
1492 | __BEGIN_DECLS\r |
a430bdb1 |
1493 | //int getw(FILE *);\r |
1494 | //int putw(int, FILE *);\r |
2aa62f2b |
1495 | char *mkdtemp(char *);\r |
1496 | int mkstemp(char *);\r |
1497 | char *mktemp(char *);\r |
1498 | \r |
d711a486 |
1499 | char *tempnam(const char *, const char *);\r |
d7ce7006 |
1500 | __END_DECLS\r |
2aa62f2b |
1501 | \r |
1502 | /*\r |
1503 | * X/Open CAE Specification Issue 5 Version 2\r |
1504 | */\r |
1505 | #ifndef off_t\r |
1506 | typedef __off_t off_t;\r |
1507 | #define off_t __off_t\r |
1508 | #endif /* off_t */\r |
1509 | \r |
1510 | __BEGIN_DECLS\r |
a430bdb1 |
1511 | int fseeko(FILE *, off_t, int);\r |
947a2d26 |
1512 | off_t ftello(FILE *);\r |
2aa62f2b |
1513 | __END_DECLS\r |
1514 | \r |
1515 | /*\r |
1516 | * Routines that are purely local.\r |
1517 | */\r |
a430bdb1 |
1518 | #define FPARSELN_UNESCESC 0x01\r |
d7ce7006 |
1519 | #define FPARSELN_UNESCCONT 0x02\r |
1520 | #define FPARSELN_UNESCCOMM 0x04\r |
1521 | #define FPARSELN_UNESCREST 0x08\r |
a430bdb1 |
1522 | #define FPARSELN_UNESCALL 0x0f\r |
2aa62f2b |
1523 | \r |
d7ce7006 |
1524 | __BEGIN_DECLS\r |
2aa62f2b |
1525 | //int asprintf(char ** __restrict, const char * __restrict, ...)\r |
1526 | // __attribute__((__format__(__printf__, 2, 3)));\r |
1527 | char *fgetln(FILE * __restrict, size_t * __restrict);\r |
1528 | char *fparseln(FILE *, size_t *, size_t *, const char[3], int);\r |
1529 | int fpurge(FILE *);\r |
1530 | void setbuffer(FILE *, char *, int);\r |
1531 | int setlinebuf(FILE *);\r |
1532 | int vasprintf(char ** __restrict, const char * __restrict,\r |
d7ce7006 |
1533 | va_list)\r |
2aa62f2b |
1534 | __attribute__((__format__(__printf__, 2, 0)));\r |
d7ce7006 |
1535 | int vscanf(const char * __restrict, va_list)\r |
2aa62f2b |
1536 | __attribute__((__format__(__scanf__, 1, 0)));\r |
a430bdb1 |
1537 | //int vfscanf(FILE * __restrict, const char * __restrict,\r |
1538 | // va_list)\r |
1539 | // __attribute__((__format__(__scanf__, 2, 0)));\r |
2aa62f2b |
1540 | int vsscanf(const char * __restrict, const char * __restrict,\r |
d7ce7006 |
1541 | va_list)\r |
2aa62f2b |
1542 | __attribute__((__format__(__scanf__, 2, 0)));\r |
a430bdb1 |
1543 | //const char *fmtcheck(const char *, const char *)\r |
1544 | // __attribute__((__format_arg__(2)));\r |
d7ce7006 |
1545 | __END_DECLS\r |
2aa62f2b |
1546 | \r |
1547 | /*\r |
1548 | * Stdio function-access interface.\r |
1549 | */\r |
d7ce7006 |
1550 | __BEGIN_DECLS\r |
2aa62f2b |
1551 | FILE *funopen(const void *,\r |
1552 | int (*)(void *, char *, int),\r |
1553 | int (*)(void *, const char *, int),\r |
1554 | fpos_t (*)(void *, fpos_t, int),\r |
1555 | int (*)(void *));\r |
d7ce7006 |
1556 | __END_DECLS\r |
2aa62f2b |
1557 | //#define fropen(cookie, fn) funopen(cookie, fn, 0, 0, 0)\r |
1558 | //#define fwopen(cookie, fn) funopen(cookie, 0, fn, 0, 0)\r |
2aa62f2b |
1559 | \r |
1560 | /*\r |
1561 | * Functions internal to the implementation.\r |
1562 | */\r |
1563 | __BEGIN_DECLS\r |
1564 | int __srget(FILE *);\r |
1565 | int __swbuf(int, FILE *);\r |
1566 | __END_DECLS\r |
1567 | \r |
1568 | /*\r |
1569 | * The __sfoo macros are here so that we can\r |
1570 | * define function versions in the C library.\r |
1571 | */\r |
1572 | #define __sgetc(p) (--(p)->_r < 0 ? __srget(p) : (int)(*(p)->_p++))\r |
d7ce7006 |
1573 | \r |
2aa62f2b |
1574 | #if defined(__GNUC__) && defined(__STDC__)\r |
1575 | static __inline int __sputc(int _c, FILE *_p) {\r |
1576 | if (--_p->_w >= 0 || (_p->_w >= _p->_lbfsize && (char)_c != '\n'))\r |
1577 | return (*_p->_p++ = _c);\r |
1578 | else\r |
1579 | return (__swbuf(_c, _p));\r |
1580 | }\r |
1581 | #else\r |
1582 | /*\r |
1583 | * This has been tuned to generate reasonable code on the vax using pcc.\r |
1584 | */\r |
1585 | #define __sputc(c, p) \\r |
1586 | (--(p)->_w < 0 ? \\r |
1587 | (p)->_w >= (p)->_lbfsize ? \\r |
1588 | (*(p)->_p = (unsigned char)(c)), *(p)->_p != '\n' ? \\r |
1589 | (int)*(p)->_p++ : \\r |
1590 | __swbuf('\n', p) : \\r |
1591 | __swbuf((int)(c), p) : \\r |
1592 | (*(p)->_p = (unsigned char)(c), (int)*(p)->_p++))\r |
1593 | #endif\r |
1594 | \r |
1595 | #define __sfeof(p) (((p)->_flags & __SEOF) != 0)\r |
1596 | #define __sferror(p) (((p)->_flags & __SERR) != 0)\r |
1597 | #define __sclearerr(p) ((void)((p)->_flags &= ~(__SERR|__SEOF)))\r |
1598 | #define __sfileno(p) ((p)->_file)\r |
1599 | \r |
1600 | #ifndef __lint__\r |
2aa62f2b |
1601 | #define feof(p) __sfeof(p)\r |
1602 | #define ferror(p) __sferror(p)\r |
1603 | #define clearerr(p) __sclearerr(p)\r |
1604 | \r |
1605 | #define getc(fp) __sgetc(fp)\r |
1606 | #define putc(x, fp) __sputc(x, fp)\r |
2aa62f2b |
1607 | #endif /* __lint__ */\r |
1608 | \r |
1609 | #define getchar() getc(stdin)\r |
1610 | #define putchar(x) putc(x, stdout)\r |
1611 | \r |
d7ce7006 |
1612 | #define fileno(p) __sfileno(p)\r |
2aa62f2b |
1613 | \r |
d7ce7006 |
1614 | #define getc_unlocked(fp) __sgetc(fp)\r |
1615 | #define putc_unlocked(x, fp) __sputc(x, fp)\r |
2aa62f2b |
1616 | \r |
d7ce7006 |
1617 | #define getchar_unlocked() getc_unlocked(stdin)\r |
1618 | #define putchar_unlocked(x) putc_unlocked(x, stdout)\r |
2aa62f2b |
1619 | \r |
1620 | #endif /* _STDIO_H_ */\r |