1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- I N T E R F A C E S . C _ S T R E A M S --
9 -- Copyright (C) 1995-2002 Free Software Foundation, Inc. --
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 2, 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. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- This package is a thin binding to selected functions in the C
35 -- library that provide a complete interface for handling C streams.
37 with System
.Parameters
;
39 package Interfaces
.C_Streams
is
42 -- Note: the reason we do not use the types that are in Interfaces.C is
43 -- that we want to avoid dragging in the code in this unit if possible.
45 subtype chars
is System
.Address
;
46 -- Pointer to null-terminated array of characters
48 subtype FILEs
is System
.Address
;
49 -- Corresponds to the C type FILE*
51 subtype voids
is System
.Address
;
52 -- Corresponds to the C type void*
54 subtype int
is Integer;
55 -- Note: the above type is a subtype deliberately, and it is part of
56 -- this spec that the above correspondence is guaranteed. This means
57 -- that it is legitimate to, for example, use Integer instead of int.
58 -- We provide this synonym for clarity, but in some cases it may be
59 -- convenient to use the underlying types (for example to avoid an
60 -- unnecessary dependency of a spec on the spec of this unit).
62 type long
is range -(2 ** (System
.Parameters
.long_bits
- 1))
63 .. +(2 ** (System
.Parameters
.long_bits
- 1)) - 1;
64 -- Note: the above type also used to be a subtype, but the correspondence
65 -- was unused so it was made into a parameterized type to avoid having
66 -- multiple versions of this spec for systems where long /= Long_Integer.
68 type size_t
is mod 2 ** Standard
'Address_Size;
70 NULL_Stream
: constant FILEs
;
71 -- Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
73 ----------------------------------
74 -- Constants Defined in stdio.h --
75 ----------------------------------
78 -- Used by a number of routines to indicate error or end of file
83 -- Used to indicate buffering mode for setvbuf call
85 L_tmpnam
: constant int
;
86 -- Maximum length of file name that can be returned by tmpnam
88 SEEK_CUR
: constant int
;
89 SEEK_END
: constant int
;
90 SEEK_SET
: constant int
;
91 -- Used to indicate origin for fseek call
93 function stdin
return FILEs
;
94 function stdout
return FILEs
;
95 function stderr
return FILEs
;
96 -- Streams associated with standard files
98 --------------------------
99 -- Standard C functions --
100 --------------------------
102 -- The functions selected below are ones that are available in DOS,
103 -- OS/2, UNIX and Xenix (but not necessarily in ANSI C). These are
104 -- very thin interfaces which copy exactly the C headers. For more
105 -- documentation on these functions, see the Microsoft C "Run-Time
106 -- Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
107 -- which includes useful information on system compatibility.
109 procedure clearerr
(stream
: FILEs
);
111 function fclose
(stream
: FILEs
) return int
;
113 function fdopen
(handle
: int
; mode
: chars
) return FILEs
;
115 function feof
(stream
: FILEs
) return int
;
117 function ferror
(stream
: FILEs
) return int
;
119 function fflush
(stream
: FILEs
) return int
;
121 function fgetc
(stream
: FILEs
) return int
;
123 function fgets
(strng
: chars
; n
: int
; stream
: FILEs
) return chars
;
125 function fileno
(stream
: FILEs
) return int
;
127 function fopen
(filename
: chars
; Mode
: chars
) return FILEs
;
128 -- Note: to maintain target independence, use text_translation_required,
129 -- a boolean variable defined in a-sysdep.c to deal with the target
130 -- dependent text translation requirement. If this variable is set,
131 -- then b/t should be appended to the standard mode argument to set
132 -- the text translation mode off or on as required.
134 function fputc
(C
: int
; stream
: FILEs
) return int
;
136 function fputs
(Strng
: chars
; Stream
: FILEs
) return int
;
152 -- Same as normal fread, but has a parameter 'index' that indicates
153 -- the starting index for the read within 'buffer' (which must be the
154 -- address of the beginning of a whole array object with an assumed
155 -- zero base). This is needed for systems that do not support taking
156 -- the address of an element within an array.
170 function ftell
(stream
: FILEs
) return long
;
179 function isatty
(handle
: int
) return int
;
181 procedure mktemp
(template
: chars
);
182 -- The return value (which is just a pointer to template) is discarded
184 procedure rewind
(stream
: FILEs
);
193 procedure tmpnam
(string : chars
);
194 -- The parameter must be a pointer to a string buffer of at least L_tmpnam
195 -- bytes (the call with a null parameter is not supported). The returned
196 -- value, which is just a copy of the input argument, is discarded.
198 function tmpfile
return FILEs
;
200 function ungetc
(c
: int
; stream
: FILEs
) return int
;
202 function unlink
(filename
: chars
) return int
;
204 ---------------------
205 -- Extra functions --
206 ---------------------
208 -- These functions supply slightly thicker bindings than those above.
209 -- They are derived from functions in the C Run-Time Library, but may
210 -- do a bit more work than just directly calling one of the Library
213 function file_exists
(name
: chars
) return int
;
214 -- Tests if given name corresponds to an existing file.
216 function is_regular_file
(handle
: int
) return int
;
217 -- Tests if given handle is for a regular file (result 1) or for
218 -- a non-regular file (pipe or device, result 0).
220 ---------------------------------
221 -- Control of Text/Binary Mode --
222 ---------------------------------
224 -- If text_translation_required is true, then the following functions may
225 -- be used to dynamically switch a file from binary to text mode or vice
226 -- versa. These functions have no effect if text_translation_required is
227 -- false (i.e. in normal unix mode). Use fileno to get a stream handle.
229 procedure set_binary_mode
(handle
: int
);
230 procedure set_text_mode
(handle
: int
);
232 ----------------------------
233 -- Full Path Name support --
234 ----------------------------
236 procedure full_name
(nam
: chars
; buffer
: chars
);
237 -- Given a NUL terminated string representing a file name, returns in
238 -- buffer a NUL terminated string representing the full path name for
239 -- the file name. On systems where it is relevant the drive is also part
240 -- of the full path name. It is the responsibility of the caller to
241 -- pass an actual parameter for buffer that is big enough for any full
242 -- path name. Use max_path_len given below as the size of buffer.
244 max_path_len
: Integer;
245 -- Maximum length of an allowable full path name on the system,
246 -- including a terminating NUL character.
249 -- The following functions are specialized in the body depending on the
252 pragma Inline
(fread
);
253 pragma Inline
(fwrite
);
254 pragma Inline
(setvbuf
);
256 -- The following routines are always functions in C, and thus can be
257 -- imported directly into Ada without any intermediate C needed
259 pragma Import
(C
, clearerr
);
260 pragma Import
(C
, fclose
);
261 pragma Import
(C
, fdopen
);
262 pragma Import
(C
, fflush
);
263 pragma Import
(C
, fgetc
);
264 pragma Import
(C
, fgets
);
265 pragma Import
(C
, fopen
);
266 pragma Import
(C
, fputc
);
267 pragma Import
(C
, fputs
);
268 pragma Import
(C
, freopen
);
269 pragma Import
(C
, fseek
);
270 pragma Import
(C
, ftell
);
271 pragma Import
(C
, isatty
);
272 pragma Import
(C
, mktemp
);
273 pragma Import
(C
, rewind
);
274 pragma Import
(C
, tmpnam
);
275 pragma Import
(C
, tmpfile
);
276 pragma Import
(C
, ungetc
);
277 pragma Import
(C
, unlink
);
279 pragma Import
(C
, file_exists
, "__gnat_file_exists");
280 pragma Import
(C
, is_regular_file
, "__gnat_is_regular_file_fd");
282 pragma Import
(C
, set_binary_mode
, "__gnat_set_binary_mode");
283 pragma Import
(C
, set_text_mode
, "__gnat_set_text_mode");
285 pragma Import
(C
, max_path_len
, "__gnat_max_path_len");
286 pragma Import
(C
, full_name
, "__gnat_full_name");
288 -- The following may be implemented as macros, and so are supported
289 -- via an interface function in the a-cstrea.c file.
291 pragma Import
(C
, feof
, "__gnat_feof");
292 pragma Import
(C
, ferror
, "__gnat_ferror");
293 pragma Import
(C
, fileno
, "__gnat_fileno");
295 pragma Import
(C
, EOF
, "__gnat_constant_eof");
296 pragma Import
(C
, IOFBF
, "__gnat_constant_iofbf");
297 pragma Import
(C
, IOLBF
, "__gnat_constant_iolbf");
298 pragma Import
(C
, IONBF
, "__gnat_constant_ionbf");
299 pragma Import
(C
, SEEK_CUR
, "__gnat_constant_seek_cur");
300 pragma Import
(C
, SEEK_END
, "__gnat_constant_seek_end");
301 pragma Import
(C
, SEEK_SET
, "__gnat_constant_seek_set");
302 pragma Import
(C
, L_tmpnam
, "__gnat_constant_l_tmpnam");
304 pragma Import
(C
, stderr
, "__gnat_constant_stderr");
305 pragma Import
(C
, stdin
, "__gnat_constant_stdin");
306 pragma Import
(C
, stdout
, "__gnat_constant_stdout");
308 NULL_Stream
: constant FILEs
:= System
.Null_Address
;
310 end Interfaces
.C_Streams
;