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-2012, 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-- As a special exception under Section 7 of GPL version 3, you are granted --
19-- additional permissions described in the GCC Runtime Library Exception,   --
20-- version 3.1, as published by the Free Software Foundation.               --
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
35with System.CRTL;
36
37package 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 voids is System.Address;
47
48   NULL_Stream : constant FILEs;
49   --  Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
50
51   ----------------------------------
52   -- Constants Defined in stdio.h --
53   ----------------------------------
54
55   EOF : constant int;
56   --  Used by a number of routines to indicate error or end of file
57
58   IOFBF : constant int;
59   IOLBF : constant int;
60   IONBF : constant int;
61   --  Used to indicate buffering mode for setvbuf call
62
63   L_tmpnam : constant int;
64   --  Maximum length of file name that can be returned by tmpnam
65
66   SEEK_CUR : constant int;
67   SEEK_END : constant int;
68   SEEK_SET : constant int;
69   --  Used to indicate origin for fseek call
70
71   function stdin  return FILEs;
72   function stdout return FILEs;
73   function stderr return FILEs;
74   --  Streams associated with standard files
75
76   --------------------------
77   -- Standard C functions --
78   --------------------------
79
80   --  The functions selected below are ones that are available in
81   --  UNIX (but not necessarily in ANSI C). These are very thin
82   --  interfaces which copy exactly the C headers. For more
83   --  documentation on these functions, see the Microsoft C "Run-Time
84   --  Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
85   --  which includes useful information on system compatibility.
86
87   procedure clearerr (stream : FILEs) renames System.CRTL.clearerr;
88
89   function fclose (stream : FILEs) return int renames System.CRTL.fclose;
90
91   function fdopen (handle : int; mode : chars) return FILEs
92     renames System.CRTL.fdopen;
93
94   function feof (stream : FILEs) return int;
95
96   function ferror (stream : FILEs) return int;
97
98   function fflush (stream : FILEs) return int renames System.CRTL.fflush;
99
100   function fgetc (stream : FILEs) return int renames System.CRTL.fgetc;
101
102   function fgets (strng : chars; n : int; stream : FILEs) return chars
103     renames System.CRTL.fgets;
104
105   function fileno (stream : FILEs) return int;
106
107   function fopen
108     (filename : chars;
109      mode     : chars;
110      encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
111      return FILEs
112     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 fputs (Strng : chars; Stream : FILEs) return int
123     renames System.CRTL.fputs;
124
125   function fread
126     (buffer : voids;
127      size   : size_t;
128      count  : size_t;
129      stream : FILEs) return size_t;
130
131   function fread
132     (buffer : voids;
133      index  : size_t;
134      size   : size_t;
135      count  : size_t;
136      stream : FILEs) return size_t;
137   --  Same as normal fread, but has a parameter 'index' that indicates
138   --  the starting index for the read within 'buffer' (which must be the
139   --  address of the beginning of a whole array object with an assumed
140   --  zero base). This is needed for systems that do not support taking
141   --  the address of an element within an array.
142
143   function freopen
144     (filename : chars;
145      mode     : chars;
146      stream   : FILEs;
147      encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
148      return FILEs
149     renames System.CRTL.freopen;
150
151   function fseek
152     (stream : FILEs;
153      offset : long;
154      origin : int) return int
155     renames System.CRTL.fseek;
156
157   function fseek64
158     (stream : FILEs;
159      offset : ssize_t;
160      origin : int) return int
161     renames System.CRTL.fseek64;
162
163   function ftell (stream : FILEs) return long
164     renames System.CRTL.ftell;
165
166   function ftell64 (stream : FILEs) return ssize_t
167     renames System.CRTL.ftell64;
168
169   function fwrite
170     (buffer : voids;
171      size   : size_t;
172      count  : size_t;
173      stream : FILEs) return size_t;
174
175   function isatty (handle : int) return int renames System.CRTL.isatty;
176
177   procedure mktemp (template : chars) renames System.CRTL.mktemp;
178   --  The return value (which is just a pointer to template) is discarded
179
180   procedure rewind (stream : FILEs) renames System.CRTL.rewind;
181
182   function setvbuf
183     (stream : FILEs;
184      buffer : chars;
185      mode   : int;
186      size   : size_t) return int;
187
188   procedure tmpnam (str : chars) renames System.CRTL.tmpnam;
189   --  The parameter must be a pointer to a string buffer of at least L_tmpnam
190   --  bytes (the call with a null parameter is not supported). The returned
191   --  value, which is just a copy of the input argument, is discarded.
192
193   function tmpfile return FILEs renames System.CRTL.tmpfile;
194
195   function ungetc (c : int; stream : FILEs) return int
196     renames System.CRTL.ungetc;
197
198   function unlink (filename : chars) return int
199     renames System.CRTL.unlink;
200
201   ---------------------
202   -- Extra functions --
203   ---------------------
204
205   --  These functions supply slightly thicker bindings than those above.
206   --  They are derived from functions in the C Run-Time Library, but may
207   --  do a bit more work than just directly calling one of the Library
208   --  functions.
209
210   function file_exists (name : chars) return int;
211   --  Tests if given name corresponds to an existing file
212
213   function is_regular_file (handle : int) return int;
214   --  Tests if given handle is for a regular file (result 1) or for a
215   --  non-regular file (pipe or device, result 0).
216
217   ---------------------------------
218   -- Control of Text/Binary Mode --
219   ---------------------------------
220
221   --  If text_translation_required is true, then the following functions may
222   --  be used to dynamically switch a file from binary to text mode or vice
223   --  versa. These functions have no effect if text_translation_required is
224   --  false (i.e. in normal unix mode). Use fileno to get a stream handle.
225
226   procedure set_binary_mode (handle : int);
227   procedure set_text_mode   (handle : int);
228
229   ----------------------------
230   -- Full Path Name support --
231   ----------------------------
232
233   procedure full_name (nam : chars; buffer : chars);
234   --  Given a NUL terminated string representing a file name, returns in
235   --  buffer a NUL terminated string representing the full path name for
236   --  the file name. On systems where it is relevant the drive is also part
237   --  of the full path name. It is the responsibility of the caller to
238   --  pass an actual parameter for buffer that is big enough for any full
239   --  path name. Use max_path_len given below as the size of buffer.
240
241   max_path_len : constant Integer;
242   --  Maximum length of an allowable full path name on the system,including a
243   --  terminating NUL character. Declared as a constant to allow references
244   --  from other preelaborated GNAT library packages.
245
246private
247   --  The following functions are specialized in the body depending on the
248   --  operating system.
249
250   pragma Inline (fread);
251   pragma Inline (fwrite);
252   pragma Inline (setvbuf);
253
254   pragma Import (C, file_exists, "__gnat_file_exists");
255   pragma Import (C, is_regular_file, "__gnat_is_regular_file_fd");
256
257   pragma Import (C, set_binary_mode, "__gnat_set_binary_mode");
258   pragma Import (C, set_text_mode, "__gnat_set_text_mode");
259
260   pragma Import (C, max_path_len, "__gnat_max_path_len");
261   pragma Import (C, full_name, "__gnat_full_name");
262
263   --  The following may be implemented as macros, and so are supported
264   --  via an interface function in the a-cstrea.c file.
265
266   pragma Import (C, feof,   "__gnat_feof");
267   pragma Import (C, ferror, "__gnat_ferror");
268   pragma Import (C, fileno, "__gnat_fileno");
269
270   pragma Import (C, EOF, "__gnat_constant_eof");
271   pragma Import (C, IOFBF, "__gnat_constant_iofbf");
272   pragma Import (C, IOLBF, "__gnat_constant_iolbf");
273   pragma Import (C, IONBF, "__gnat_constant_ionbf");
274   pragma Import (C, SEEK_CUR, "__gnat_constant_seek_cur");
275   pragma Import (C, SEEK_END, "__gnat_constant_seek_end");
276   pragma Import (C, SEEK_SET, "__gnat_constant_seek_set");
277   pragma Import (C, L_tmpnam, "__gnat_constant_l_tmpnam");
278
279   pragma Import (C, stderr, "__gnat_constant_stderr");
280   pragma Import (C, stdin,  "__gnat_constant_stdin");
281   pragma Import (C, stdout, "__gnat_constant_stdout");
282
283   NULL_Stream : constant FILEs := System.Null_Address;
284
285end Interfaces.C_Streams;
286