gcc/ada/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 --                            $Revision: 1.1 $
  10 --                                                                          --
  11 --          Copyright (C) 1995-2001 Free Software Foundation, Inc.          --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNAT was originally developed  by the GNAT team at  New York University. --
  32 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  33 --                                                                          --
  34 ------------------------------------------------------------------------------
  35
  36
  37
  38 --  This package is a thin binding to selected functions in the C
  39 --  library that provide a complete interface for handling C streams.
  40
  41 with Unchecked_Conversion;
  42 with System.Parameters;
  43
  44 package Interfaces.C_Streams is
  45 pragma Elaborate_Body (C_Streams);
  46
  47    --  Note: the reason we do not use the types that are in Interfaces.C is
  48    --  that we want to avoid dragging in the code in this unit if possible.
  49
  50    subtype chars is System.Address;
  51    --  Pointer to null-terminated array of characters
  52
  53    subtype FILEs is System.Address;
  54    --  Corresponds to the C type FILE*
  55
  56    subtype voids is System.Address;
  57    --  Corresponds to the C type void*
  58
  59    subtype int is Integer;
  60    --  Note: the above type is a subtype deliberately, and it is part of
  61    --  this spec that the above correspondence is guaranteed. This means
  62    --  that it is legitimate to, for example, use Integer instead of int.
  63    --  We provide this synonym for clarity, but in some cases it may be
  64    --  convenient to use the underlying types (for example to avoid an
  65    --  unnecessary dependency of a spec on the spec of this unit).
  66
  67    type long is range -(2 ** (System.Parameters.long_bits - 1))
  68       .. +(2 ** (System.Parameters.long_bits - 1)) - 1;
  69    --  Note: the above type also used to be a subtype, but the correspondence
  70    --  was unused so it was made into a parameterized type to avoid having
  71    --  multiple versions of this spec for systems where long /= Long_Integer.
  72
  73    type size_t is mod 2 ** Standard'Address_Size;
  74
  75    NULL_Stream : constant FILEs;
  76    --  Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
  77
  78    ----------------------------------
  79    -- Constants Defined in stdio.h --
  80    ----------------------------------
  81
  82    EOF : constant int;
  83    --  Used by a number of routines to indicate error or end of file
  84
  85    IOFBF : constant int;
  86    IOLBF : constant int;
  87    IONBF : constant int;
  88    --  Used to indicate buffering mode for setvbuf call
  89
  90    L_tmpnam : constant int;
  91    --  Maximum length of file name that can be returned by tmpnam
  92
  93    SEEK_CUR : constant int;
  94    SEEK_END : constant int;
  95    SEEK_SET : constant int;
  96    --  Used to indicate origin for fseek call
  97
  98    function stdin  return FILEs;
  99    function stdout return FILEs;
 100    function stderr return FILEs;
 101    --  Streams associated with standard files
 102
 103    --------------------------
 104    -- Standard C functions --
 105    --------------------------
 106
 107    --  The functions selected below are ones that are available in DOS,
 108    --  OS/2, UNIX and Xenix (but not necessarily in ANSI C). These are
 109    --  very thin interfaces which copy exactly the C headers. For more
 110    --  documentation on these functions, see the Microsoft C "Run-Time
 111    --  Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
 112    --  which includes useful information on system compatibility.
 113
 114    procedure clearerr (stream : FILEs);
 115
 116    function fclose (stream : FILEs) return int;
 117
 118    function fdopen (handle : int; mode : chars) return FILEs;
 119
 120    function feof (stream : FILEs) return int;
 121
 122    function ferror (stream : FILEs) return int;
 123
 124    function fflush (stream : FILEs) return int;
 125
 126    function fgetc (stream : FILEs) return int;
 127
 128    function fgets (strng : chars; n : int; stream : FILEs) return chars;
 129
 130    function fileno (stream : FILEs) return int;
 131
 132    function fopen (filename : chars; Mode : chars) return FILEs;
 133    --  Note: to maintain target independence, use text_translation_required,
 134    --  a boolean variable defined in a-sysdep.c to deal with the target
 135    --  dependent text translation requirement. If this variable is set,
 136    --  then b/t should be appended to the standard mode argument to set
 137    --  the text translation mode off or on as required.
 138
 139    function fputc (C : int; stream : FILEs) return int;
 140
 141    function fputs (Strng : chars; Stream : FILEs) return int;
 142
 143    function fread
 144      (buffer : voids;
 145       size   : size_t;
 146       count  : size_t;
 147       stream : FILEs)
 148       return   size_t;
 149
 150    function fread
 151      (buffer : voids;
 152       index  : size_t;
 153       size   : size_t;
 154       count  : size_t;
 155       stream : FILEs)
 156       return   size_t;
 157    --  Same as normal fread, but has a parameter 'index' that indicates
 158    --  the starting index for the read within 'buffer' (which must be the
 159    --  address of the beginning of a whole array object with an assumed
 160    --  zero base). This is needed for systems that do not support taking
 161    --  the address of an element within an array.
 162
 163    function freopen
 164      (filename : chars;
 165       mode     : chars;
 166       stream   : FILEs)
 167       return     FILEs;
 168
 169    function fseek
 170      (stream : FILEs;
 171       offset : long;
 172       origin : int)
 173       return   int;
 174
 175    function ftell (stream : FILEs) return long;
 176
 177    function fwrite
 178      (buffer : voids;
 179       size   : size_t;
 180       count  : size_t;
 181       stream : FILEs)
 182       return   size_t;
 183
 184    function isatty (handle : int) return int;
 185
 186    procedure mktemp (template : chars);
 187    --  The return value (which is just a pointer to template) is discarded
 188
 189    procedure rewind (stream : FILEs);
 190
 191    function setvbuf
 192      (stream : FILEs;
 193       buffer : chars;
 194       mode   : int;
 195       size   : size_t)
 196       return   int;
 197
 198    procedure tmpnam (string : chars);
 199    --  The parameter must be a pointer to a string buffer of at least L_tmpnam
 200    --  bytes (the call with a null parameter is not supported). The returned
 201    --  value, which is just a copy of the input argument, is discarded.
 202
 203    function tmpfile return FILEs;
 204
 205    function ungetc (c : int; stream : FILEs) return int;
 206
 207    function unlink (filename : chars) return int;
 208
 209    ---------------------
 210    -- Extra functions --
 211    ---------------------
 212
 213    --  These functions supply slightly thicker bindings than those above.
 214    --  They are derived from functions in the C Run-Time Library, but may
 215    --  do a bit more work than just directly calling one of the Library
 216    --  functions.
 217
 218    function file_exists (name : chars) return int;
 219    --  Tests if given name corresponds to an existing file.
 220
 221    function is_regular_file (handle : int) return int;
 222    --  Tests if given handle is for a regular file (result 1) or for
 223    --  a non-regular file (pipe or device, result 0).
 224
 225    ---------------------------------
 226    -- Control of Text/Binary Mode --
 227    ---------------------------------
 228
 229    --  If text_translation_required is true, then the following functions may
 230    --  be used to dynamically switch a file from binary to text mode or vice
 231    --  versa. These functions have no effect if text_translation_required is
 232    --  false (i.e. in normal unix mode). Use fileno to get a stream handle.
 233
 234    procedure set_binary_mode (handle : int);
 235    procedure set_text_mode   (handle : int);
 236
 237    ----------------------------
 238    -- Full Path Name support --
 239    ----------------------------
 240
 241    procedure full_name (nam : chars; buffer : chars);
 242    --  Given a NUL terminated string representing a file name, returns in
 243    --  buffer a NUL terminated string representing the full path name for
 244    --  the file name. On systems where it is relevant the drive is also part
 245    --  of the full path name. It is the responsibility of the caller to
 246    --  pass an actual parameter for buffer that is big enough for any full
 247    --  path name. Use max_path_len given below as the size of buffer.
 248
 249    max_path_len : Integer;
 250    --  Maximum length of an allowable full path name on the system,
 251    --  including a terminating NUL character.
 252
 253 private
 254    --  The following functions are specialized in the body depending on the
 255    --  operating system.
 256
 257    pragma Inline (fread);
 258    pragma Inline (fwrite);
 259    pragma Inline (setvbuf);
 260
 261    --  The following routines are always functions in C, and thus can be
 262    --  imported directly into Ada without any intermediate C needed
 263
 264    pragma Import (C, clearerr);
 265    pragma Import (C, fclose);
 266    pragma Import (C, fdopen);
 267    pragma Import (C, fflush);
 268    pragma Import (C, fgetc);
 269    pragma Import (C, fgets);
 270    pragma Import (C, fopen);
 271    pragma Import (C, fputc);
 272    pragma Import (C, fputs);
 273    pragma Import (C, freopen);
 274    pragma Import (C, fseek);
 275    pragma Import (C, ftell);
 276    pragma Import (C, isatty);
 277    pragma Import (C, mktemp);
 278    pragma Import (C, rewind);
 279    pragma Import (C, tmpnam);
 280    pragma Import (C, tmpfile);
 281    pragma Import (C, ungetc);
 282    pragma Import (C, unlink);
 283
 284    pragma Import (C, file_exists, "__gnat_file_exists");
 285    pragma Import (C, is_regular_file, "__gnat_is_regular_file_fd");
 286
 287    pragma Import (C, set_binary_mode, "__gnat_set_binary_mode");
 288    pragma Import (C, set_text_mode, "__gnat_set_text_mode");
 289
 290    pragma Import (C, max_path_len, "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-stdio.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    --  Constants in stdio are provided via imported variables that are
 301    --  defined in a-cstrea.c using the stdio.h header. It would be cleaner
 302    --  if we could import constant directly, but GNAT does not support
 303    --  pragma Import for constants ???
 304
 305    c_constant_EOF      : int;
 306
 307    c_constant_IOFBF    : int;
 308    c_constant_IOLBF    : int;
 309    c_constant_IONBF    : int;
 310
 311    c_constant_SEEK_CUR : int;
 312    c_constant_SEEK_END : int;
 313    c_constant_SEEK_SET : int;
 314
 315    c_constant_L_tmpnam : int;
 316
 317    pragma Import (C, c_constant_EOF, "__gnat_constant_eof");
 318    pragma Import (C, c_constant_IOFBF, "__gnat_constant_iofbf");
 319    pragma Import (C, c_constant_IOLBF, "__gnat_constant_iolbf");
 320    pragma Import (C, c_constant_IONBF, "__gnat_constant_ionbf");
 321    pragma Import (C, c_constant_SEEK_CUR, "__gnat_constant_seek_cur");
 322    pragma Import (C, c_constant_SEEK_END, "__gnat_constant_seek_end");
 323    pragma Import (C, c_constant_SEEK_SET, "__gnat_constant_seek_set");
 324    pragma Import (C, c_constant_L_tmpnam, "__gnat_constant_l_tmpnam");
 325
 326    pragma Import (C, stderr, "__gnat_constant_stderr");
 327    pragma Import (C, stdin,  "__gnat_constant_stdin");
 328    pragma Import (C, stdout, "__gnat_constant_stdout");
 329
 330    EOF      : constant int := c_constant_EOF;
 331    IOFBF    : constant int := c_constant_IOFBF;
 332    IOLBF    : constant int := c_constant_IOLBF;
 333    IONBF    : constant int := c_constant_IONBF;
 334    SEEK_CUR : constant int := c_constant_SEEK_CUR;
 335    SEEK_END : constant int := c_constant_SEEK_END;
 336    SEEK_SET : constant int := c_constant_SEEK_SET;
 337    L_tmpnam : constant int := c_constant_L_tmpnam;
 338
 339    type Dummy is access Integer;
 340    function To_Address is new Unchecked_Conversion (Dummy, System.Address);
 341    --  Used to concoct the null address below
 342
 343    NULL_Stream : constant FILEs := To_Address (Dummy'(null));
 344    --  Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
 345
 346 end Interfaces.C_Streams;