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-2018, 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 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
275private
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
315end Interfaces.C_Streams;
316