]>
Commit | Line | Data |
---|---|---|
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 | |
108 | Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>\r | |
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 | |
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 | |
148 | NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp\r | |
149 | */\r | |
150 | #ifndef _STDIO_H_\r | |
151 | #define _STDIO_H_\r | |
152 | \r | |
153 | #include <stdarg.h>\r | |
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 | |
159 | /** size_t is the unsigned integer type of the result of the sizeof operator. **/\r | |
160 | typedef _EFI_SIZE_T_ size_t;\r | |
161 | #undef _EFI_SIZE_T_\r | |
162 | #undef _BSD_SIZE_T_\r | |
163 | #endif\r | |
164 | \r | |
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 | |
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 | |
187 | /*@}*/\r | |
188 | \r | |
189 | /* stdio buffers */\r | |
190 | struct __sbuf {\r | |
191 | unsigned char *_base;\r | |
192 | int _size;\r | |
193 | };\r | |
194 | \r | |
195 | /** Structure which holds all the information needed to control a stream or file.\r | |
196 | *\r | |
197 | * The following always hold:<BR>\r | |
198 | *\r | |
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 | |
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 | |
218 | */\r | |
219 | typedef struct __sFILE {\r | |
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 | |
227 | \r | |
228 | /* operations */\r | |
229 | void *_cookie; /**< cookie passed to io functions */\r | |
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 | |
235 | /** file extension */\r | |
236 | struct __sbuf _ext;\r | |
237 | \r | |
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 | |
244 | \r | |
245 | /* tricks to meet minimum requirements even when malloc() fails */\r | |
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 | |
248 | \r | |
249 | /** separate buffer for fgetln() when line crosses buffer boundary */\r | |
250 | struct __sbuf _lb; /* buffer for fgetln() */\r | |
251 | \r | |
252 | /* Unix stdio files get aligned to block boundaries on fseek() */\r | |
253 | int _blksize; /**< stat.st_blksize (may be != _bf._size) */\r | |
254 | fpos_t _offset; /**< current lseek offset */\r | |
255 | } FILE;\r | |
256 | \r | |
257 | __BEGIN_DECLS\r | |
258 | extern FILE __sF[];\r | |
259 | __END_DECLS\r | |
260 | \r | |
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 | |
265 | /* RD and WR are never simultaneously asserted */\r | |
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 | |
277 | \r | |
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 | |
285 | */\r | |
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 | |
289 | \r | |
290 | #define BUFSIZ 1024 /**< size of buffer used by setbuf */\r | |
291 | #define EOF (-1) /**< A constant integer expression indicating end-of-file. */\r | |
292 | \r | |
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 | |
296 | */\r | |
297 | #define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */\r | |
298 | \r | |
299 | /** Size needed for an array of char large enough to hold the longest file name string. */\r | |
300 | #define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */\r | |
301 | \r | |
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 | |
305 | #define L_tmpnam PATH_MAX /* must be == PATH_MAX */\r | |
306 | \r | |
307 | #ifndef TMP_MAX\r | |
308 | #define TMP_MAX 308915776 /**< The maximum number of unique file names\r | |
309 | that can be generated by tmpnam(). **/\r | |
310 | #endif\r | |
311 | \r | |
312 | /* Always ensure that these are consistent with <fcntl.h>! */\r | |
313 | #ifndef SEEK_SET\r | |
314 | #define SEEK_SET 0 /**< set file offset to offset */\r | |
315 | #endif\r | |
316 | #ifndef SEEK_CUR\r | |
317 | #define SEEK_CUR 1 /**< set file offset to current plus offset */\r | |
318 | #endif\r | |
319 | #ifndef SEEK_END\r | |
320 | #define SEEK_END 2 /**< set file offset to EOF plus offset */\r | |
321 | #endif\r | |
322 | \r | |
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 | |
326 | \r | |
327 | __BEGIN_DECLS\r | |
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 | |
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 | |
500 | arguments for the format, the behavior is indeterminate. If the format is\r | |
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 | |
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 | |
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 | |
530 | zero. If a precision appears with any other conversion specifier, it\r | |
531 | is ignored.\r | |
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 | |
541 | A negative precision argument is interpreted as if the precision were omitted.\r | |
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 | |
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 | |
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 | |
570 | precision is specified, the 0 flag is ignored.\r | |
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 | |
611 | specified above, it is ignored.\r | |
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 | |
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 | |
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 | |
702 | pointer is converted to a sequence of printing characters.\r | |
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 | |
707 | field width, or a precision, they will be ignored.\r | |
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 | |
718 | which convert their associated arguments.\r | |
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 | |
724 | **/\r | |
725 | int fprintf (FILE * __restrict stream, const char * __restrict format, ...);\r | |
726 | \r | |
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 | |
1138 | int getc (FILE *);\r | |
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 | |
1150 | int getchar (void);\r | |
1151 | \r | |
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 | |
1294 | size_t fwrite (const void * __restrict Buffer,\r | |
1295 | size_t Size,\r | |
1296 | size_t Num,\r | |
1297 | FILE * __restrict Stream\r | |
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 | |
1449 | __END_DECLS\r | |
1450 | \r | |
1451 | /*\r | |
1452 | * IEEE Std 1003.1-90\r | |
1453 | */\r | |
1454 | __BEGIN_DECLS\r | |
1455 | FILE *fdopen(int, const char *);\r | |
1456 | __END_DECLS\r | |
1457 | \r | |
1458 | /*\r | |
1459 | * IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2\r | |
1460 | */\r | |
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 | |
1470 | \r | |
1471 | /*\r | |
1472 | * Functions defined in POSIX 1003.2 and XPG2 or later.\r | |
1473 | */\r | |
1474 | __BEGIN_DECLS\r | |
1475 | int pclose (FILE *);\r | |
1476 | FILE *popen (const char *, const char *);\r | |
1477 | __END_DECLS\r | |
1478 | \r | |
1479 | /*\r | |
1480 | * Functions defined in ISO XPG4.2, ISO C99, POSIX 1003.1-2001 or later.\r | |
1481 | */\r | |
1482 | __BEGIN_DECLS\r | |
1483 | int snprintf (char * __restrict, size_t, const char * __restrict, ...)\r | |
1484 | __attribute__((__format__(__printf__, 3, 4)));\r | |
1485 | int vsnprintf(char * __restrict, size_t, const char * __restrict, va_list)\r | |
1486 | __attribute__((__format__(__printf__, 3, 0)));\r | |
1487 | __END_DECLS\r | |
1488 | \r | |
1489 | /*\r | |
1490 | * Functions defined in XPG4.2.\r | |
1491 | */\r | |
1492 | __BEGIN_DECLS\r | |
1493 | //int getw(FILE *);\r | |
1494 | //int putw(int, FILE *);\r | |
1495 | char *mkdtemp(char *);\r | |
1496 | int mkstemp(char *);\r | |
1497 | char *mktemp(char *);\r | |
1498 | \r | |
1499 | char *tempnam(const char *, const char *);\r | |
1500 | __END_DECLS\r | |
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 | |
1511 | int fseeko(FILE *, off_t, int);\r | |
1512 | off_t ftello(FILE *);\r | |
1513 | __END_DECLS\r | |
1514 | \r | |
1515 | /*\r | |
1516 | * Routines that are purely local.\r | |
1517 | */\r | |
1518 | #define FPARSELN_UNESCESC 0x01\r | |
1519 | #define FPARSELN_UNESCCONT 0x02\r | |
1520 | #define FPARSELN_UNESCCOMM 0x04\r | |
1521 | #define FPARSELN_UNESCREST 0x08\r | |
1522 | #define FPARSELN_UNESCALL 0x0f\r | |
1523 | \r | |
1524 | __BEGIN_DECLS\r | |
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 | |
1533 | va_list)\r | |
1534 | __attribute__((__format__(__printf__, 2, 0)));\r | |
1535 | int vscanf(const char * __restrict, va_list)\r | |
1536 | __attribute__((__format__(__scanf__, 1, 0)));\r | |
1537 | //int vfscanf(FILE * __restrict, const char * __restrict,\r | |
1538 | // va_list)\r | |
1539 | // __attribute__((__format__(__scanf__, 2, 0)));\r | |
1540 | int vsscanf(const char * __restrict, const char * __restrict,\r | |
1541 | va_list)\r | |
1542 | __attribute__((__format__(__scanf__, 2, 0)));\r | |
1543 | //const char *fmtcheck(const char *, const char *)\r | |
1544 | // __attribute__((__format_arg__(2)));\r | |
1545 | __END_DECLS\r | |
1546 | \r | |
1547 | /*\r | |
1548 | * Stdio function-access interface.\r | |
1549 | */\r | |
1550 | __BEGIN_DECLS\r | |
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 | |
1556 | __END_DECLS\r | |
1557 | //#define fropen(cookie, fn) funopen(cookie, fn, 0, 0, 0)\r | |
1558 | //#define fwopen(cookie, fn) funopen(cookie, 0, fn, 0, 0)\r | |
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 | |
1573 | \r | |
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 | |
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 | |
1607 | #endif /* __lint__ */\r | |
1608 | \r | |
1609 | #define getchar() getc(stdin)\r | |
1610 | #define putchar(x) putc(x, stdout)\r | |
1611 | \r | |
1612 | #define fileno(p) __sfileno(p)\r | |
1613 | \r | |
1614 | #define getc_unlocked(fp) __sgetc(fp)\r | |
1615 | #define putc_unlocked(x, fp) __sputc(x, fp)\r | |
1616 | \r | |
1617 | #define getchar_unlocked() getc_unlocked(stdin)\r | |
1618 | #define putchar_unlocked(x) putc_unlocked(x, stdout)\r | |
1619 | \r | |
1620 | #endif /* _STDIO_H_ */\r |