source: trunk/libs/mini-libc/stdio.h @ 687

Last change on this file since 687 was 677, checked in by alain, 4 years ago

Introduce the fgetc() and fputc() functions.
File size: 11.2 KB
Line 
1/*
2 * stdio.h - User level <stdio> library definition.
3 *
4 * Author     Alain Greiner (2016,2017,2018,2019)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _STDIO_H_
25#define _STDIO_H_
26
27/*********************************************************************************************
28 * This file defines the user level, TXT related <stdio> library.
29 *
30 * These functions call the read() and write() functions defined in the <unistd> library
31 * to access the TXT terminal.
32 ********************************************************************************************/
33
34#define  MAX_OPEN_FILE_PER_PROCESS  256
35#define  VALID_OPEN_FILE            0x12345678
36#define  EOF                        -1
37#define  NULL                       (void *)0
38
39/*********************************************************************************************
40 * This defines the user level FILE structure.
41 * The open_file_array[] of files is a global variable allocated in the <stdio.c> file
42 ********************************************************************************************/
43
44typedef struct stream_s
45{
46    int fd;          // index in both kernel fd_array[], and user open_file_array[]
47    int key;         // entry valid in open_file_array[] when (key == VALID_OPEN_FILE)
48}
49FILE;
50
51/*********************************************************************************************
52 * This function causes the file/directory named <old> to be renamed as <new>.
53 * If <new> exists, it is previously removed.
54 *********************************************************************************************
55 * @ returns 0 if success / returns -1 if failure.
56 ********************************************************************************************/
57int rename( const char * old,
58            const char * new );
59
60/*********************************************************************************************
61 * This function writes a formated string to the standard "stdout" stream.
62 *********************************************************************************************
63 * @ returns number of characters written if success / returns -1 if failure.
64 ********************************************************************************************/
65int printf( const char * format, ... );
66
67/*********************************************************************************************
68 * This function writes the <c> character to the standard "stdout" stream.
69 *********************************************************************************************
70 * @ returns written character code if success / returns 0 (EOF) if failure.
71 ********************************************************************************************/
72int putchar( int c );
73
74/*********************************************************************************************
75 * This function returns one single character from the standard "stdin" stream.
76 *********************************************************************************************
77 * @ returns read character code if success / returns 0 (EOF) if failure.
78 ********************************************************************************************/
79int getchar( void );
80
81/*********************************************************************************************
82 * This function copies a formated string to a fixed size buffer.
83 * it includes the NUL terminating character.
84 * it cheks that the formated string fit in the buffer length.
85 *********************************************************************************************
86 * @ string    : pointer on target buffer.
87 * @ length    : max bumber of characters in target buffer.
88 * @ format    : formated string.
89 * @ returns string length (not including NUL) if success / returns -1 if failure.
90 ********************************************************************************************/
91int snprintf( char         * string,
92              unsigned int   length,
93              const char   * format, ... );
94
95
96
97
98
99
100/*********************************************************************************************
101 * This function opens the file identified by the <pathname> argument and associates
102 * the stream pointed by <FILE> with it.
103 * The <mode> argument is a string that can have the following values:
104 * - "r"   Open text file for reading.
105 *         The stream is positioned at the beginning of the file.
106 * - "r+"  Open for reading and writing.
107 *         The stream is positioned at the beginning of the file.
108 * - "w"   Truncate the file to zero length or create text file for writing.
109 *         The stream is positioned at the beginning of the file.
110 * - "w+"  Open for reading and writing.
111 *         The file is created if it does not exist, otherwise it is truncated.
112 *         The stream is positioned at the beginning of the file.
113 * - "a"   Open for writing.  The file is created if it does not exist.
114 *         The stream is positioned at the end of the file. 
115 *         Subsequent writes to the file will always end up at the current end of file,
116 *         irrespective of any intervening fseek() or similar.
117 * - "a+"  Open for reading and writing. 
118 *         The file is created if it does not exist. 
119 *         The stream is positioned at the end of the file.
120 *         Subsequent writes to the file will always end up at the current end of file,
121 *         irrespective of any intervening fseek() or similar.
122 *********************************************************************************************
123 * @ pathname  : file pathname.
124 * @ mode      : must be NULL <=> only "w+" mode is supported.
125 * @ returns a stream pointer if success / returns NULL if file not found.
126 ********************************************************************************************/
127FILE * fopen( const char * pathname,
128              const char * mode );
129
130/*********************************************************************************************
131 * This function dissociates the stream from its underlying file and close this file.
132 * If the stream was being used for output, any buffered data is written first.
133 *********************************************************************************************
134 * @ stream    : pointer on a stream.
135 * @ returns 0 if success / returns EOF if failure.
136 ********************************************************************************************/
137int fclose( FILE * stream );
138
139/*********************************************************************************************
140 * This function returns one single character from the FILE identified by <stream>.
141 *********************************************************************************************
142 * @ returns read character code if success / returns 0 (EOF) if failure.
143 ********************************************************************************************/
144int fgetc( FILE * stream );
145
146/*********************************************************************************************
147 * This function writes the <c> character to the FILE identified by <stream>.
148 *********************************************************************************************
149 * @ returns written character code if success / returns 0 (EOF) if failure.
150 ********************************************************************************************/
151int fputc( int c, 
152           FILE * stream);
153
154/*********************************************************************************************
155 * This function copies a formated string to an output stream identified by the <stream>
156 * argument. It can be a  regular file or a character oriented output device.
157 *********************************************************************************************
158 * @ stream    : pointer on a stream.
159 * @ format    : formated string.
160 * @ returns number of characters written if success / returns -1 if failure.
161 ********************************************************************************************/
162int fprintf( FILE       * stream,
163             const char * format, ... );
164
165/*********************************************************************************************
166 * This function moves <nitems> oblects, each <size> bytes long, from an input stream
167 * identified by <stream>, to the user buffer identified by the <buffer> argument.
168 * It can be a regular file or a character oriented input device.
169 *********************************************************************************************
170 * @ buffer    : pointer on user buffer.
171 * @ size      : item size in bytes.
172 * @ nitems    : number of items.
173 * @ stream    : pointer on a stream.
174 * @ returns actual number of items read if success / returns 0 if failure.
175 ********************************************************************************************/
176unsigned int fread( void         * buffer,
177                    unsigned int   size,
178                    unsigned int   nitems,
179                    FILE         * stream ); 
180
181/*********************************************************************************************
182 * This function moves <nitems> oblects, each <size> bytes long, from an user buffer
183 * identified by the <buffer> argument, to an output stream identified by <stream>.
184 * It can be a  regular file or a character oriented input device.
185 *********************************************************************************************
186 * @ buffer    : pointer on user buffer.
187 * @ size      : item size in bytes.
188 * @ nitems    : number of items.
189 * @ stream    : pointer on a stream.
190 * @ returns actual number of written items if success / returns 0 if failure.
191 ********************************************************************************************/
192unsigned int fwrite( void         * buffer,
193                     unsigned int   size,
194                     unsigned int   nitems,
195                     FILE         * stream ); 
196
197/*********************************************************************************************
198 * This function moves <nitems> oblects, each <size> bytes long, from an input stream
199 * identified by <stream>, to the user buffer identified by the <buffer> argument.
200 * It can be a regular file or a character oriented input device.
201 *********************************************************************************************
202 * @ stream    : pointer on a stream.
203 * @ offset    : used to compute new offset value.
204 * @ whence    : operation type (SEEK_SET / SEEK_CUR / SEEK_END)
205 * @ return 0 if success / returns -1 if failure.
206 ********************************************************************************************/
207unsigned int fseek( FILE        * stream,
208                    unsigned int  offset,
209                    int           whence );
210
211
212#endif  // _STDIO_H_
Note: See TracBrowser for help on using the repository browser.