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