nulib.c.stdio source code

1 /**
2     Bindings to C standard library I/O functions.
3 
4     Copyright:
5         Copyright © 2023-2025, Kitsunebi Games
6         Copyright © 2023-2025, Inochi2D Project
7     
8     License:   $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
9     Authors:   Luna Nielsen
10 */
11 module nulib.c.stdio;
12 import numem.compiler;
13 
14 extern(C) nothrow @nogc:
15 
16 /**
17     Opaque File Handle
18 */
19 struct FILE;
20 
21 enum {
22     /**
23         Offset is relative to the beginning.
24     */
25     SEEK_SET,
26 
27     /**
28         Offset is relative to the current position.
29     */
30     SEEK_CUR,
31     
32     /**
33         Offset is relative to the end.
34     */
35     SEEK_END
36 }
37 
38 enum {
39 
40     /**
41         End-of-file
42     */
43     EOF = -1
44 }
45 
46 /**
47     Prints a formatted string.
48 
49     Params:
50         format = The format string.
51         ...    = Arguments following `format`.
52 
53     Returns:
54         On success, the total number of characters written is returned.
55 */
56 pragma(printf)
57 extern int printf(const(char)* format, ...) @trusted pure;
58 
59 /**
60     Prints a formatted string to a sized buffer.
61 
62     Params:
63         buffer =    The buffer to write to.
64         size   =    The size of the buffer.
65         format =    The format string.
66         ...    =    Arguments following `format`.
67 
68     Returns:
69         On success, the total number of characters written is returned.
70         A terminating $(D '\0') is automatically written to the buffer after
71         the content.
72 */
73 pragma(printf)
74 extern int snprintf(char* buffer, size_t size, const(char)* format, ...) @trusted pure;
75 
76 /**
77     Prints a formatted string to a buffer.
78 
79     Params:
80         buffer =    The buffer to write to.
81         format =    The format string.
82         ...    =    Arguments following `format`.
83 
84     Returns:
85         On success, the total number of characters written is returned.
86         A terminating $(D '\0') is automatically written to the buffer after
87         the content.
88 */
89 pragma(printf)
90 extern int sprintf(char* buffer, const(char)* format, ...) @system pure;
91 
92 /**
93     Reads a data from stdin with a given format.
94 
95     Params:
96         format = The format string.
97         ...    = Arguments following `format`.
98 
99     Returns:
100         The amount of items successfully filled.
101 */
102 pragma(scanf)
103 extern int scanf(const(char)* format, ...) @trusted pure;
104 
105 /**
106     Reads a data from a string with a given format.
107 
108     Params:
109         s       = The input string.
110         format  = The format string.
111         ...     = Arguments following `format`.
112 
113     Returns:
114         The amount of items successfully filled.
115 */
116 pragma(scanf)
117 extern int sscanf(const(char)* s, const(char)* format, ...) @trusted pure;
118 
119 /**
120     Writes the last reported error to stderr.
121 
122     Params:
123         str = Optional string to preprend to the error.
124 */
125 extern void perror(const(char)* str = null) @trusted pure;
126 
127 /**
128     Opens the file with the given file name and mode.
129 
130     Params:
131         filename =  The name and path of the file to open, in system encoding.
132         mode =      The mode to open the file in.
133 
134     Returns:
135         A file handle on success, $(D null) on failure.
136 */
137 extern FILE* fopen(const(char)* filename, const(char)* mode);
138 
139 /**
140     Opens the file with the given file name and mode.
141 
142     Params:
143         filename =  The name and path of the file to open, in UTF-16.
144         mode =      The mode to open the file in.
145 
146     Returns:
147         A file handle on success, $(D null) on failure.
148 */
149 version (CRuntime_Microsoft)
150 extern FILE* _wfopen(const(wchar)* filename, const(wchar)* mode);
151 
152 /**
153     Flushes the stream.
154 
155     If the stream provided is $(D null), all streams are flushed.
156     The stream remains open after this call.
157 
158     Params:
159         stream =    Pointer to a $(D FILE)
160 
161     Returns:
162         0 on success, $(D EOF) on failure.
163 */
164 extern int fflush(FILE* stream) @trusted;
165 
166 /**
167     Closes the stream. 
168 
169     Params:
170         stream =    Pointer to a $(D FILE)
171 
172     Returns:
173         0 on success, $(D EOF) on failure.
174 */
175 extern int fclose(FILE* stream);
176 
177 /**
178     Gets the current position in the stream.
179 
180     Params:
181         stream =    Pointer to a $(D FILE)
182 
183     Returns:
184         0 on success.
185 */
186 extern ptrdiff_t ftell(FILE* stream);
187 
188 /**
189     Sets the position of the stream.
190 
191     Params:
192         stream =    Pointer to a $(D FILE)
193         offset =    Offset into the stream.
194         origin =    The origin to seek from.
195 
196     Returns:
197         0 on success.
198 */
199 extern int fseek(FILE* stream, ptrdiff_t offset, int origin);
200 
201 /**
202     Sets the position of the stream to its beginning.
203 
204     Params:
205         stream =    Pointer to a $(D FILE)
206 */
207 extern void rewind(FILE* stream);
208 
209 /**
210     Reads data from the stream.
211 
212     Params:
213         ptr =       Buffer to write to.
214         size =      Size of a single unit of data in bytes
215         count =     The amount of units to write to the buffer.
216         stream =    The stream to read from.
217     
218     Returns:
219         The amount of elements read.
220 */
221 extern size_t fread(void* ptr, size_t size, size_t count, FILE* stream);
222 
223 /**
224     Writes data to the stream.
225 
226     Params:
227         ptr =       The buffer to write to.
228         size =      Size of a single unit of data in bytes
229         count =     The amount of units to write to the file.
230         stream =    The stream to write to.
231     
232     Returns:
233         The amount of elements written.
234 */
235 extern size_t fwrite(const(void)* ptr, size_t size, size_t count, FILE* stream);
236 
237 /**
238     Creates a temporary file handle.
239 
240     This handle is not backed by a real file.
241 
242     Returns:
243         A file handle on success, $(D null) on failure.
244 */
245 extern FILE* tmpfile();
246 
247 /**
248     Generates a temporary file name.
249 
250     Params:
251         str = The buffer that should store the name, or $(D null).
252 
253     Returns:
254         The buffer containing the name.
255 */
256 extern char* tmpnam(char* str);
257 
258 /**
259     Removes the given file.
260 
261     Params:
262         path = Path to the file to remove, in system encoding.
263     
264     Returns:
265         0 on success.
266 */
267 extern int remove(const(char)* path);
268 
269 /**
270     Removes the given file.
271 
272     Params:
273         path = Path to the file to remove, in UTF-16 encoding.
274     
275     Returns:
276         0 on success.
277 */
278 version (CRuntime_Microsoft)
279 extern int _wremove(const(wchar)* path);
280 
281 /**
282     Renames the given file.
283 
284     Params:
285         oldName =   Path to the file to rename, in system encoding.
286         newName =   The new path of the file, in system encoding.
287     
288     Returns:
289         0 on success.
290 */
291 extern int rename(const(char)* oldName, const(char)* newName);
292 
293 /**
294     Renames the given file.
295 
296     Params:
297         oldName =   Path to the file to rename, in UTF-16 encoding.
298         newName =   The new path of the file, in UTF-16 encoding.
299     
300     Returns:
301         0 on success.
302 */
303 version (CRuntime_Microsoft)
304 extern int _wrename(const(wchar)* oldName, const(wchar)* newName);