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-2010, 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 voids is System.Address;
  46
  47    NULL_Stream : constant FILEs;
  48    --  Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error
  49
  50    ----------------------------------
  51    -- Constants Defined in stdio.h --
  52    ----------------------------------
  53
  54    EOF : constant int;
  55    --  Used by a number of routines to indicate error or end of file
  56
  57    IOFBF : constant int;
  58    IOLBF : constant int;
  59    IONBF : constant int;
  60    --  Used to indicate buffering mode for setvbuf call
  61
  62    L_tmpnam : constant int;
  63    --  Maximum length of file name that can be returned by tmpnam
  64
  65    SEEK_CUR : constant int;
  66    SEEK_END : constant int;
  67    SEEK_SET : constant int;
  68    --  Used to indicate origin for fseek call
  69
  70    function stdin  return FILEs;
  71    function stdout return FILEs;
  72    function stderr return FILEs;
  73    --  Streams associated with standard files
  74
  75    --------------------------
  76    -- Standard C functions --
  77    --------------------------
  78
  79    --  The functions selected below are ones that are available in
  80    --  UNIX (but not necessarily in ANSI C). These are very thin
  81    --  interfaces which copy exactly the C headers. For more
  82    --  documentation on these functions, see the Microsoft C "Run-Time
  83    --  Library Reference" (Microsoft Press, 1990, ISBN 1-55615-225-6),
  84    --  which includes useful information on system compatibility.
  85
  86    procedure clearerr (stream : FILEs) renames System.CRTL.clearerr;
  87
  88    function fclose (stream : FILEs) return int renames System.CRTL.fclose;
  89
  90    function fdopen (handle : int; mode : chars) return FILEs
  91      renames System.CRTL.fdopen;
  92
  93    function feof (stream : FILEs) return int;
  94
  95    function ferror (stream : FILEs) return int;
  96
  97    function fflush (stream : FILEs) return int renames System.CRTL.fflush;
  98
  99    function fgetc (stream : FILEs) return int renames System.CRTL.fgetc;
 100
 101    function fgets (strng : chars; n : int; stream : FILEs) return chars
 102      renames System.CRTL.fgets;
 103
 104    function fileno (stream : FILEs) return int;
 105
 106    function fopen
 107      (filename : chars;
 108       mode     : chars;
 109       encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
 110       return FILEs
 111      renames System.CRTL.fopen;
 112    --  Note: to maintain target independence, use text_translation_required,
 113    --  a boolean variable defined in sysdep.c to deal with the target
 114    --  dependent text translation requirement. If this variable is set,
 115    --  then b/t should be appended to the standard mode argument to set
 116    --  the text translation mode off or on as required.
 117
 118    function fputc (C : int; stream : FILEs) return int
 119      renames System.CRTL.fputc;
 120
 121    function fputs (Strng : chars; Stream : FILEs) return int
 122      renames System.CRTL.fputs;
 123
 124    function fread
 125      (buffer : voids;
 126       size   : size_t;
 127       count  : size_t;
 128       stream : FILEs) return size_t;
 129
 130    function fread
 131      (buffer : voids;
 132       index  : size_t;
 133       size   : size_t;
 134       count  : size_t;
 135       stream : FILEs) return size_t;
 136    --  Same as normal fread, but has a parameter 'index' that indicates
 137    --  the starting index for the read within 'buffer' (which must be the
 138    --  address of the beginning of a whole array object with an assumed
 139    --  zero base). This is needed for systems that do not support taking
 140    --  the address of an element within an array.
 141
 142    function freopen
 143      (filename : chars;
 144       mode     : chars;
 145       stream   : FILEs;
 146       encoding : System.CRTL.Filename_Encoding := System.CRTL.UTF8)
 147       return FILEs
 148      renames System.CRTL.freopen;
 149
 150    function fseek
 151      (stream : FILEs;
 152       offset : long;
 153       origin : int) return int
 154      renames System.CRTL.fseek;
 155
 156    function ftell (stream : FILEs) return long
 157      renames System.CRTL.ftell;
 158
 159    function fwrite
 160      (buffer : voids;
 161       size   : size_t;
 162       count  : size_t;
 163       stream : FILEs) return size_t;
 164
 165    function isatty (handle : int) return int renames System.CRTL.isatty;
 166
 167    procedure mktemp (template : chars) renames System.CRTL.mktemp;
 168    --  The return value (which is just a pointer to template) is discarded
 169
 170    procedure rewind (stream : FILEs) renames System.CRTL.rewind;
 171
 172    function setvbuf
 173      (stream : FILEs;
 174       buffer : chars;
 175       mode   : int;
 176       size   : size_t) return int;
 177
 178    procedure tmpnam (string : chars) renames System.CRTL.tmpnam;
 179    --  The parameter must be a pointer to a string buffer of at least L_tmpnam
 180    --  bytes (the call with a null parameter is not supported). The returned
 181    --  value, which is just a copy of the input argument, is discarded.
 182
 183    function tmpfile return FILEs renames System.CRTL.tmpfile;
 184
 185    function ungetc (c : int; stream : FILEs) return int
 186      renames System.CRTL.ungetc;
 187
 188    function unlink (filename : chars) return int
 189      renames System.CRTL.unlink;
 190
 191    ---------------------
 192    -- Extra functions --
 193    ---------------------
 194
 195    --  These functions supply slightly thicker bindings than those above.
 196    --  They are derived from functions in the C Run-Time Library, but may
 197    --  do a bit more work than just directly calling one of the Library
 198    --  functions.
 199
 200    function file_exists (name : chars) return int;
 201    --  Tests if given name corresponds to an existing file
 202
 203    function is_regular_file (handle : int) return int;
 204    --  Tests if given handle is for a regular file (result 1) or for a
 205    --  non-regular file (pipe or device, result 0).
 206
 207    ---------------------------------
 208    -- Control of Text/Binary Mode --
 209    ---------------------------------
 210
 211    --  If text_translation_required is true, then the following functions may
 212    --  be used to dynamically switch a file from binary to text mode or vice
 213    --  versa. These functions have no effect if text_translation_required is
 214    --  false (i.e. in normal unix mode). Use fileno to get a stream handle.
 215
 216    procedure set_binary_mode (handle : int);
 217    procedure set_text_mode   (handle : int);
 218
 219    ----------------------------
 220    -- Full Path Name support --
 221    ----------------------------
 222
 223    procedure full_name (nam : chars; buffer : chars);
 224    --  Given a NUL terminated string representing a file name, returns in
 225    --  buffer a NUL terminated string representing the full path name for
 226    --  the file name. On systems where it is relevant the drive is also part
 227    --  of the full path name. It is the responsibility of the caller to
 228    --  pass an actual parameter for buffer that is big enough for any full
 229    --  path name. Use max_path_len given below as the size of buffer.
 230
 231    max_path_len : Integer;
 232    --  Maximum length of an allowable full path name on the system,
 233    --  including a terminating NUL character.
 234
 235 private
 236    --  The following functions are specialized in the body depending on the
 237    --  operating system.
 238
 239    pragma Inline (fread);
 240    pragma Inline (fwrite);
 241    pragma Inline (setvbuf);
 242
 243    pragma Import (C, file_exists, "__gnat_file_exists");
 244    pragma Import (C, is_regular_file, "__gnat_is_regular_file_fd");
 245
 246    pragma Import (C, set_binary_mode, "__gnat_set_binary_mode");
 247    pragma Import (C, set_text_mode, "__gnat_set_text_mode");
 248
 249    pragma Import (C, max_path_len, "__gnat_max_path_len");
 250    pragma Import (C, full_name, "__gnat_full_name");
 251
 252    --  The following may be implemented as macros, and so are supported
 253    --  via an interface function in the a-cstrea.c file.
 254
 255    pragma Import (C, feof,   "__gnat_feof");
 256    pragma Import (C, ferror, "__gnat_ferror");
 257    pragma Import (C, fileno, "__gnat_fileno");
 258
 259    pragma Import (C, EOF, "__gnat_constant_eof");
 260    pragma Import (C, IOFBF, "__gnat_constant_iofbf");
 261    pragma Import (C, IOLBF, "__gnat_constant_iolbf");
 262    pragma Import (C, IONBF, "__gnat_constant_ionbf");
 263    pragma Import (C, SEEK_CUR, "__gnat_constant_seek_cur");
 264    pragma Import (C, SEEK_END, "__gnat_constant_seek_end");
 265    pragma Import (C, SEEK_SET, "__gnat_constant_seek_set");
 266    pragma Import (C, L_tmpnam, "__gnat_constant_l_tmpnam");
 267
 268    pragma Import (C, stderr, "__gnat_constant_stderr");
 269    pragma Import (C, stdin,  "__gnat_constant_stdin");
 270    pragma Import (C, stdout, "__gnat_constant_stdout");
 271
 272    NULL_Stream : constant FILEs := System.Null_Address;
 273
 274 end Interfaces.C_Streams;