1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- I N T E R F A C E S . C _ S T R E A M S --
10 -- Copyright (C) 1995-2002 Free Software Foundation, Inc. --
12 -- GNAT is free software; you can redistribute it and/or modify it under --
13 -- terms of the GNU General Public License as published by the Free Soft- --
14 -- ware Foundation; either version 2, or (at your option) any later ver- --
15 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
16 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
17 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
18 -- for more details. You should have received a copy of the GNU General --
19 -- Public License distributed with GNAT; see file COPYING. If not, write --
20 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
21 -- MA 02111-1307, USA. --
23 -- As a special exception, if other files instantiate generics from this --
24 -- unit, or you link this unit with other files to produce an executable, --
25 -- this unit does not by itself cause the resulting executable to be --
26 -- covered by the GNU General Public License. This exception does not --
27 -- however invalidate any other reasons why the executable file might be --
28 -- covered by the GNU Public License. --
30 -- GNAT was originally developed by the GNAT team at New York University. --
31 -- Extensive contributions were provided by Ada Core Technologies Inc. --
33 ------------------------------------------------------------------------------
35 -- This package is a thin binding to selected functions in the C
36 -- library that provide a complete interface for handling C streams.
38 with System
.Parameters
;
40 package Interfaces
.C_Streams
is
43 -- Note: the reason we do not use the types that are in Interfaces.C is
44 -- that we want to avoid dragging in the code in this unit if possible.
46 subtype chars
is System
.Address
;
47 -- Pointer to null-terminated array of characters
49 subtype FILEs
is System
.Address
;
50 -- Corresponds to the C type FILE*
52 subtype voids
is System
.Address
;
53 -- Corresponds to the C type void*
55 subtype int
is Integer;
56 -- Note: the above type is a subtype deliberately, and it is part of
57 -- this spec that the above correspondence is guaranteed. This means
58 -- that it is legitimate to, for example, use Integer instead of int.
59 -- We provide this synonym for clarity, but in some cases it may be
60 -- convenient to use the underlying types (for example to avoid an
61 -- unnecessary dependency of a spec on the spec of this unit).
63 type long
is range -(2 ** (System
.Parameters
.long_bits
- 1))
64 .. +(2 ** (System
.Parameters
.long_bits
- 1)) - 1;
65 -- Note: the above type also used to be a subtype, but the correspondence
66 -- was unused so it was made into a parameterized type to avoid having
67 -- multiple versions of this spec for systems where long /= Long_Integer.
69 type size_t
is mod 2 ** Standard
'Address_Size;
71 NULL_Stream
: constant FILEs
;
72 -- Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
74 ----------------------------------
75 -- Constants Defined in stdio.h --
76 ----------------------------------
79 -- Used by a number of routines to indicate error or end of file
84 -- Used to indicate buffering mode for setvbuf call
86 L_tmpnam
: constant int
;
87 -- Maximum length of file name that can be returned by tmpnam
89 SEEK_CUR
: constant int
;
90 SEEK_END
: constant int
;
91 SEEK_SET
: constant int
;
92 -- Used to indicate origin for fseek call
94 function stdin
return FILEs
;
95 function stdout
return FILEs
;
96 function stderr
return FILEs
;
97 -- Streams associated with standard files
99 --------------------------
100 -- Standard C functions --
101 --------------------------
103 -- The functions selected below are ones that are available in DOS,
104 -- OS/2, UNIX and Xenix (but not necessarily in ANSI C). These are
105 -- very thin interfaces which copy exactly the C headers. For more
106 -- documentation on these functions, see the Microsoft C "Run-Time
107 -- Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
108 -- which includes useful information on system compatibility.
110 procedure clearerr
(stream
: FILEs
);
112 function fclose
(stream
: FILEs
) return int
;
114 function fdopen
(handle
: int
; mode
: chars
) return FILEs
;
116 function feof
(stream
: FILEs
) return int
;
118 function ferror
(stream
: FILEs
) return int
;
120 function fflush
(stream
: FILEs
) return int
;
122 function fgetc
(stream
: FILEs
) return int
;
124 function fgets
(strng
: chars
; n
: int
; stream
: FILEs
) return chars
;
126 function fileno
(stream
: FILEs
) return int
;
128 function fopen
(filename
: chars
; Mode
: chars
) return FILEs
;
129 -- Note: to maintain target independence, use text_translation_required,
130 -- a boolean variable defined in a-sysdep.c to deal with the target
131 -- dependent text translation requirement. If this variable is set,
132 -- then b/t should be appended to the standard mode argument to set
133 -- the text translation mode off or on as required.
135 function fputc
(C
: int
; stream
: FILEs
) return int
;
137 function fputs
(Strng
: chars
; Stream
: FILEs
) return int
;
153 -- Same as normal fread, but has a parameter 'index' that indicates
154 -- the starting index for the read within 'buffer' (which must be the
155 -- address of the beginning of a whole array object with an assumed
156 -- zero base). This is needed for systems that do not support taking
157 -- the address of an element within an array.
171 function ftell
(stream
: FILEs
) return long
;
180 function isatty
(handle
: int
) return int
;
182 procedure mktemp
(template
: chars
);
183 -- The return value (which is just a pointer to template) is discarded
185 procedure rewind
(stream
: FILEs
);
194 procedure tmpnam
(string : chars
);
195 -- The parameter must be a pointer to a string buffer of at least L_tmpnam
196 -- bytes (the call with a null parameter is not supported). The returned
197 -- value, which is just a copy of the input argument, is discarded.
199 function tmpfile
return FILEs
;
201 function ungetc
(c
: int
; stream
: FILEs
) return int
;
203 function unlink
(filename
: chars
) return int
;
205 ---------------------
206 -- Extra functions --
207 ---------------------
209 -- These functions supply slightly thicker bindings than those above.
210 -- They are derived from functions in the C Run-Time Library, but may
211 -- do a bit more work than just directly calling one of the Library
214 function file_exists
(name
: chars
) return int
;
215 -- Tests if given name corresponds to an existing file.
217 function is_regular_file
(handle
: int
) return int
;
218 -- Tests if given handle is for a regular file (result 1) or for
219 -- a non-regular file (pipe or device, result 0).
221 ---------------------------------
222 -- Control of Text/Binary Mode --
223 ---------------------------------
225 -- If text_translation_required is true, then the following 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 (i.e. in normal unix mode). Use fileno to get a stream handle.
230 procedure set_binary_mode
(handle
: int
);
231 procedure set_text_mode
(handle
: int
);
233 ----------------------------
234 -- Full Path Name support --
235 ----------------------------
237 procedure full_name
(nam
: chars
; buffer
: chars
);
238 -- Given a NUL terminated string representing a file name, returns in
239 -- buffer a NUL terminated string representing the full path name for
240 -- the file name. On systems where it is relevant the drive is also part
241 -- of the full path name. It is the responsibility of the caller to
242 -- pass an actual parameter for buffer that is big enough for any full
243 -- path name. Use max_path_len given below as the size of buffer.
245 max_path_len
: Integer;
246 -- Maximum length of an allowable full path name on the system,
247 -- including a terminating NUL character.
250 -- The following functions are specialized in the body depending on the
253 pragma Inline
(fread
);
254 pragma Inline
(fwrite
);
255 pragma Inline
(setvbuf
);
257 -- The following routines are always functions in C, and thus can be
258 -- imported directly into Ada without any intermediate C needed
260 pragma Import
(C
, clearerr
);
261 pragma Import
(C
, fclose
);
262 pragma Import
(C
, fdopen
);
263 pragma Import
(C
, fflush
);
264 pragma Import
(C
, fgetc
);
265 pragma Import
(C
, fgets
);
266 pragma Import
(C
, fopen
);
267 pragma Import
(C
, fputc
);
268 pragma Import
(C
, fputs
);
269 pragma Import
(C
, freopen
);
270 pragma Import
(C
, fseek
);
271 pragma Import
(C
, ftell
);
272 pragma Import
(C
, isatty
);
273 pragma Import
(C
, mktemp
);
274 pragma Import
(C
, rewind
);
275 pragma Import
(C
, tmpnam
);
276 pragma Import
(C
, tmpfile
);
277 pragma Import
(C
, ungetc
);
278 pragma Import
(C
, unlink
);
280 pragma Import
(C
, file_exists
, "__gnat_file_exists");
281 pragma Import
(C
, is_regular_file
, "__gnat_is_regular_file_fd");
283 pragma Import
(C
, set_binary_mode
, "__gnat_set_binary_mode");
284 pragma Import
(C
, set_text_mode
, "__gnat_set_text_mode");
286 pragma Import
(C
, max_path_len
, "__gnat_max_path_len");
287 pragma Import
(C
, full_name
, "__gnat_full_name");
289 -- The following may be implemented as macros, and so are supported
290 -- via an interface function in the a-cstrea.c file.
292 pragma Import
(C
, feof
, "__gnat_feof");
293 pragma Import
(C
, ferror
, "__gnat_ferror");
294 pragma Import
(C
, fileno
, "__gnat_fileno");
296 pragma Import
(C
, EOF
, "__gnat_constant_eof");
297 pragma Import
(C
, IOFBF
, "__gnat_constant_iofbf");
298 pragma Import
(C
, IOLBF
, "__gnat_constant_iolbf");
299 pragma Import
(C
, IONBF
, "__gnat_constant_ionbf");
300 pragma Import
(C
, SEEK_CUR
, "__gnat_constant_seek_cur");
301 pragma Import
(C
, SEEK_END
, "__gnat_constant_seek_end");
302 pragma Import
(C
, SEEK_SET
, "__gnat_constant_seek_set");
303 pragma Import
(C
, L_tmpnam
, "__gnat_constant_l_tmpnam");
305 pragma Import
(C
, stderr
, "__gnat_constant_stderr");
306 pragma Import
(C
, stdin
, "__gnat_constant_stdin");
307 pragma Import
(C
, stdout
, "__gnat_constant_stdout");
309 NULL_Stream
: constant FILEs
:= System
.Null_Address
;
311 end Interfaces
.C_Streams
;