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