File : i-cstrea.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- I N T E R F A C E S . C _ S T R E A M S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1995-2014, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This package is a thin binding to selected functions in the C
33 -- library that provide a complete interface for handling C streams.
34
35 with System.CRTL;
36
37 package Interfaces.C_Streams is
38 pragma Preelaborate;
39
40 subtype chars is System.CRTL.chars;
41 subtype FILEs is System.CRTL.FILEs;
42 subtype int is System.CRTL.int;
43 subtype long is System.CRTL.long;
44 subtype size_t is System.CRTL.size_t;
45 subtype ssize_t is System.CRTL.ssize_t;
46 subtype int64 is System.CRTL.int64;
47 subtype voids is System.Address;
48
49 NULL_Stream : constant FILEs;
50 -- Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
51
52 ----------------------------------
53 -- Constants Defined in stdio.h --
54 ----------------------------------
55
56 EOF : constant int;
57 -- Used by a number of routines to indicate error or end of file
58
59 IOFBF : constant int;
60 IOLBF : constant int;
61 IONBF : constant int;
62 -- Used to indicate buffering mode for setvbuf call
63
64 L_tmpnam : constant int;
65 -- Maximum length of file name that can be returned by tmpnam
66
67 SEEK_CUR : constant int;
68 SEEK_END : constant int;
69 SEEK_SET : constant int;
70 -- Used to indicate origin for fseek call
71
72 function stdin return FILEs;
73 function stdout return FILEs;
74 function stderr return FILEs;
75 -- Streams associated with standard files
76
77 --------------------------
78 -- Standard C functions --
79 --------------------------
80
81 -- The functions selected below are ones that are available in
82 -- UNIX (but not necessarily in ANSI C). These are very thin
83 -- interfaces which copy exactly the C headers. For more
84 -- documentation on these functions, see the Microsoft C "Run-Time
85 -- Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
86 -- which includes useful information on system compatibility.
87
88 procedure clearerr (stream : FILEs) renames System.CRTL.clearerr;
89
90 function fclose (stream : FILEs) return int renames System.CRTL.fclose;
91
92 function fdopen (handle : int; mode : chars) return FILEs
93 renames System.CRTL.fdopen;
94
95 function feof (stream : FILEs) return int;
96
97 function ferror (stream : FILEs) return int;
98
99 function fflush (stream : FILEs) return int renames System.CRTL.fflush;
100
101 function fgetc (stream : FILEs) return int renames System.CRTL.fgetc;
102
103 function fgets (strng : chars; n : int; stream : FILEs) return chars
104 renames System.CRTL.fgets;
105
106 function fileno (stream : FILEs) return int;
107
108 function fopen
109 (filename : chars;
110 mode : chars;
111 encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
112 return FILEs renames System.CRTL.fopen;
113 -- Note: to maintain target independence, use text_translation_required,
114 -- a boolean variable defined in sysdep.c to deal with the target
115 -- dependent text translation requirement. If this variable is set,
116 -- then b/t should be appended to the standard mode argument to set
117 -- the text translation mode off or on as required.
118
119 function fputc (C : int; stream : FILEs) return int
120 renames System.CRTL.fputc;
121
122 function fputwc (C : int; stream : FILEs) return int
123 renames System.CRTL.fputwc;
124
125 function fputs (Strng : chars; Stream : FILEs) return int
126 renames System.CRTL.fputs;
127
128 function fread
129 (buffer : voids;
130 size : size_t;
131 count : size_t;
132 stream : FILEs) return size_t;
133
134 function fread
135 (buffer : voids;
136 index : size_t;
137 size : size_t;
138 count : size_t;
139 stream : FILEs) return size_t;
140 -- Same as normal fread, but has a parameter 'index' that indicates
141 -- the starting index for the read within 'buffer' (which must be the
142 -- address of the beginning of a whole array object with an assumed
143 -- zero base). This is needed for systems that do not support taking
144 -- the address of an element within an array.
145
146 function freopen
147 (filename : chars;
148 mode : chars;
149 stream : FILEs;
150 encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
151 return FILEs renames System.CRTL.freopen;
152
153 function fseek
154 (stream : FILEs;
155 offset : long;
156 origin : int) return int
157 renames System.CRTL.fseek;
158
159 function fseek64
160 (stream : FILEs;
161 offset : int64;
162 origin : int) return int
163 renames System.CRTL.fseek64;
164
165 function ftell (stream : FILEs) return long
166 renames System.CRTL.ftell;
167
168 function ftell64 (stream : FILEs) return int64
169 renames System.CRTL.ftell64;
170
171 function fwrite
172 (buffer : voids;
173 size : size_t;
174 count : size_t;
175 stream : FILEs) return size_t;
176
177 function isatty (handle : int) return int renames System.CRTL.isatty;
178
179 procedure mktemp (template : chars) renames System.CRTL.mktemp;
180 -- The return value (which is just a pointer to template) is discarded
181
182 procedure rewind (stream : FILEs) renames System.CRTL.rewind;
183
184 function setvbuf
185 (stream : FILEs;
186 buffer : chars;
187 mode : int;
188 size : size_t) return int;
189
190 procedure tmpnam (str : chars) renames System.CRTL.tmpnam;
191 -- The parameter must be a pointer to a string buffer of at least L_tmpnam
192 -- bytes (the call with a null parameter is not supported). The returned
193 -- value, which is just a copy of the input argument, is discarded.
194
195 function tmpfile return FILEs renames System.CRTL.tmpfile;
196
197 function ungetc (c : int; stream : FILEs) return int
198 renames System.CRTL.ungetc;
199
200 function unlink (filename : chars) return int
201 renames System.CRTL.unlink;
202
203 ---------------------
204 -- Extra functions --
205 ---------------------
206
207 -- These functions supply slightly thicker bindings than those above.
208 -- They are derived from functions in the C Run-Time Library, but may
209 -- do a bit more work than just directly calling one of the Library
210 -- functions.
211
212 function file_exists (name : chars) return int;
213 -- Tests if given name corresponds to an existing file
214
215 function is_regular_file (handle : int) return int;
216 -- Tests if given handle is for a regular file (result 1) or for a
217 -- non-regular file (pipe or device, result 0).
218
219 ---------------------------------
220 -- Control of Text/Binary Mode --
221 ---------------------------------
222
223 procedure set_binary_mode (handle : int);
224 procedure set_text_mode (handle : int);
225 -- If text_translation_required is true, then these two functions may
226 -- be used to dynamically switch a file from binary to text mode or vice
227 -- versa. These functions have no effect if text_translation_required is
228 -- false (e.g. in normal unix mode). Use fileno to get a stream handle.
229
230 type Content_Encoding is (None, Default_Text, Text, U8text, Wtext, U16text);
231 for Content_Encoding use (0, 1, 2, 3, 4, 5);
232 pragma Convention (C, Content_Encoding);
233 -- Content_Encoding describes the text encoding for file content:
234 -- None : No text encoding, this file is treated as a binary file
235 -- Default_Text : A text file but not from Text_Translation form string
236 -- In this mode we are eventually using the system-wide
237 -- translation if activated.
238 -- Text : Text encoding activated
239 -- Wtext : Unicode mode
240 -- U16text : Unicode UTF-16 encoding
241 -- U8text : Unicode UTF-8 encoding
242 --
243 -- This encoding is system dependent and only used on Windows systems.
244 --
245 -- Note that modifications to Content_Encoding must be synchronized with
246 -- sysdep.c:__gnat_set_mode.
247
248 subtype Text_Content_Encoding
249 is Content_Encoding range Default_Text .. U16text;
250
251 subtype Non_Default_Text_Content_Encoding
252 is Content_Encoding range Text .. U16text;
253
254 procedure set_mode (handle : int; Mode : Content_Encoding);
255 -- As above but can set the handle to any mode. On Windows this can be used
256 -- to have proper 16-bit wide-string output on the console for example.
257
258 ----------------------------
259 -- Full Path Name support --
260 ----------------------------
261
262 procedure full_name (nam : chars; buffer : chars);
263 -- Given a NUL terminated string representing a file name, returns in
264 -- buffer a NUL terminated string representing the full path name for
265 -- the file name. On systems where it is relevant the drive is also part
266 -- of the full path name. It is the responsibility of the caller to
267 -- pass an actual parameter for buffer that is big enough for any full
268 -- path name. Use max_path_len given below as the size of buffer.
269
270 max_path_len : constant Integer;
271 -- Maximum length of an allowable full path name on the system,including a
272 -- terminating NUL character. Declared as a constant to allow references
273 -- from other preelaborated GNAT library packages.
274
275 private
276 -- The following functions are specialized in the body depending on the
277 -- operating system.
278
279 pragma Inline (fread);
280 pragma Inline (fwrite);
281 pragma Inline (setvbuf);
282
283 pragma Import (C, file_exists, "__gnat_file_exists");
284 pragma Import (C, is_regular_file, "__gnat_is_regular_file_fd");
285
286 pragma Import (C, set_binary_mode, "__gnat_set_binary_mode");
287 pragma Import (C, set_text_mode, "__gnat_set_text_mode");
288 pragma Import (C, set_mode, "__gnat_set_mode");
289
290 pragma Import (C, max_path_len, "__gnat_max_path_len");
291 pragma Import (C, full_name, "__gnat_full_name");
292
293 -- The following may be implemented as macros, and so are supported
294 -- via an interface function in the a-cstrea.c file.
295
296 pragma Import (C, feof, "__gnat_feof");
297 pragma Import (C, ferror, "__gnat_ferror");
298 pragma Import (C, fileno, "__gnat_fileno");
299
300 pragma Import (C, EOF, "__gnat_constant_eof");
301 pragma Import (C, IOFBF, "__gnat_constant_iofbf");
302 pragma Import (C, IOLBF, "__gnat_constant_iolbf");
303 pragma Import (C, IONBF, "__gnat_constant_ionbf");
304 pragma Import (C, SEEK_CUR, "__gnat_constant_seek_cur");
305 pragma Import (C, SEEK_END, "__gnat_constant_seek_end");
306 pragma Import (C, SEEK_SET, "__gnat_constant_seek_set");
307 pragma Import (C, L_tmpnam, "__gnat_constant_l_tmpnam");
308
309 pragma Import (C, stderr, "__gnat_constant_stderr");
310 pragma Import (C, stdin, "__gnat_constant_stdin");
311 pragma Import (C, stdout, "__gnat_constant_stdout");
312
313 NULL_Stream : constant FILEs := System.Null_Address;
314
315 end Interfaces.C_Streams;