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