gcc/ada/libgnat/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-2023, 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
  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;