gcc/ada/i-vxwoio.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                 GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS                 --
   4 --                                                                          --
   5 --                 I N T E R F A C E S . V X W O R K S . I O                --
   6 --                                                                          --
   7 --                                  S p e c                                 --
   8 --                                                                          --
   9 --           Copyright (C) 2002-2009, Free Software Foundation, Inc.        --
  10 --                                                                          --
  11 -- GNARL 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 -- GNARL was developed by the GNARL team at Florida State University.       --
  28 -- Extensive contributions were provided by Ada Core Technologies, Inc.     --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package provides a binding to the functions fileno and ioctl
  33 --  in VxWorks, providing a set of definitions of ioctl function codes
  34 --  and options for the use of these functions.
  35
  36 --  A particular use of this interface is to enable use of Get_Immediate
  37 --  in Ada.Text_IO. There is no way in VxWorks to provide the desired
  38 --  functionality of Get_Immediate (no buffering and no waiting for a
  39 --  line return) without flushing the buffer, which violates the Ada
  40 --  semantic requirements for Ada.Text_IO.
  41
  42 with Interfaces.C_Streams;
  43
  44 package Interfaces.VxWorks.IO is
  45
  46    -------------------------
  47    -- The ioctl Interface --
  48    --------------------------
  49
  50    type FUNCODE is new int;
  51    --  Type of the function codes in ioctl
  52
  53    type IOOPT is mod 2 ** int'Size;
  54    --  Type of the option codes in ioctl
  55
  56    --  ioctl function codes (for more information see ioLib.h)
  57    --  These values could be generated automatically in System.OS_Constants???
  58
  59    FIONREAD       : constant FUNCODE := 1;
  60    FIOFLUSH       : constant FUNCODE := 2;
  61    FIOOPTIONS     : constant FUNCODE := 3;
  62    FIOBAUDRATE    : constant FUNCODE := 4;
  63    FIODISKFORMAT  : constant FUNCODE := 5;
  64    FIODISKINIT    : constant FUNCODE := 6;
  65    FIOSEEK        : constant FUNCODE := 7;
  66    FIOWHERE       : constant FUNCODE := 8;
  67    FIODIRENTRY    : constant FUNCODE := 9;
  68    FIORENAME      : constant FUNCODE := 10;
  69    FIOREADYCHANGE : constant FUNCODE := 11;
  70    FIONWRITE      : constant FUNCODE := 12;
  71    FIODISKCHANGE  : constant FUNCODE := 13;
  72    FIOCANCEL      : constant FUNCODE := 14;
  73    FIOSQUEEZE     : constant FUNCODE := 15;
  74    FIONBIO        : constant FUNCODE := 16;
  75    FIONMSGS       : constant FUNCODE := 17;
  76    FIOGETNAME     : constant FUNCODE := 18;
  77    FIOGETOPTIONS  : constant FUNCODE := 19;
  78    FIOSETOPTIONS  : constant FUNCODE := FIOOPTIONS;
  79    FIOISATTY      : constant FUNCODE := 20;
  80    FIOSYNC        : constant FUNCODE := 21;
  81    FIOPROTOHOOK   : constant FUNCODE := 22;
  82    FIOPROTOARG    : constant FUNCODE := 23;
  83    FIORBUFSET     : constant FUNCODE := 24;
  84    FIOWBUFSET     : constant FUNCODE := 25;
  85    FIORFLUSH      : constant FUNCODE := 26;
  86    FIOWFLUSH      : constant FUNCODE := 27;
  87    FIOSELECT      : constant FUNCODE := 28;
  88    FIOUNSELECT    : constant FUNCODE := 29;
  89    FIONFREE       : constant FUNCODE := 30;
  90    FIOMKDIR       : constant FUNCODE := 31;
  91    FIORMDIR       : constant FUNCODE := 32;
  92    FIOLABELGET    : constant FUNCODE := 33;
  93    FIOLABELSET    : constant FUNCODE := 34;
  94    FIOATTRIBSE    : constant FUNCODE := 35;
  95    FIOCONTIG      : constant FUNCODE := 36;
  96    FIOREADDIR     : constant FUNCODE := 37;
  97    FIOFSTATGET    : constant FUNCODE := 38;
  98    FIOUNMOUNT     : constant FUNCODE := 39;
  99    FIOSCSICOMMAND : constant FUNCODE := 40;
 100    FIONCONTIG     : constant FUNCODE := 41;
 101    FIOTRUNC       : constant FUNCODE := 42;
 102    FIOGETFL       : constant FUNCODE := 43;
 103    FIOTIMESET     : constant FUNCODE := 44;
 104    FIOINODETONAM  : constant FUNCODE := 45;
 105    FIOFSTATFSGE   : constant FUNCODE := 46;
 106
 107    --  ioctl option values
 108
 109    OPT_ECHO     : constant IOOPT := 16#0001#;
 110    OPT_CRMOD    : constant IOOPT := 16#0002#;
 111    OPT_TANDEM   : constant IOOPT := 16#0004#;
 112    OPT_7_BIT    : constant IOOPT := 16#0008#;
 113    OPT_MON_TRAP : constant IOOPT := 16#0010#;
 114    OPT_ABORT    : constant IOOPT := 16#0020#;
 115    OPT_LINE     : constant IOOPT := 16#0040#;
 116    OPT_RAW      : constant IOOPT := 16#0000#;
 117    OPT_TERMINAL : constant IOOPT := OPT_ECHO     or
 118                                     OPT_CRMOD    or
 119                                     OPT_TANDEM   or
 120                                     OPT_MON_TRAP or
 121                                     OPT_7_BIT    or
 122                                     OPT_ABORT    or
 123                                     OPT_LINE;
 124
 125    function fileno (Fp : Interfaces.C_Streams.FILEs) return int;
 126    pragma Import (C, fileno, "fileno");
 127    --  Binding to the C routine fileno
 128
 129    function ioctl (Fd : int; Function_Code : FUNCODE; Arg : IOOPT) return int;
 130    pragma Import (C, ioctl, "ioctl");
 131    --  Binding to the C routine ioctl
 132    --
 133    --  Note: we are taking advantage of the fact that on currently supported
 134    --  VxWorks targets, it is fine to directly bind to a variadic C function.
 135
 136    ------------------------------
 137    -- Control of Get_Immediate --
 138    ------------------------------
 139
 140    --  The procedures in this section make use of the interface to ioctl
 141    --  and fileno to provide a mechanism for enabling unbuffered behavior
 142    --  for Get_Immediate in VxWorks.
 143
 144    --  The situation is that the RM requires that the use of Get_Immediate
 145    --  be identical to Get except that it is desirable (not required) that
 146    --  there be no buffering or line editing.
 147
 148    --  Unfortunately, in VxWorks, the only way to enable this desired
 149    --  unbuffered behavior involves changing into raw mode. But this
 150    --  transition into raw mode flushes the input buffer, a behavior
 151    --  not permitted by the RM semantics for Get_Immediate.
 152
 153    --  Given that Get_Immediate cannot be accurately implemented in
 154    --  raw mode, it seems best not to enable it by default, and instead
 155    --  to require specific programmer action, with the programmer being
 156    --  aware that input may be lost.
 157
 158    --  The following is an example of the use of the two procedures
 159    --  in this section (Enable_Get_Immediate and Disable_Get_Immediate)
 160
 161    --  with Ada.Text_IO; use Ada.Text_IO;
 162    --  with Ada.Text_IO.C_Streams; use Ada.Text_IO.C_Streams;
 163    --  with Interfaces.VxWorks.IO; use Interfaces.VxWorks.IO;
 164
 165    --  procedure Example_IO is
 166    --     Input     : Character;
 167    --     Available : Boolean;
 168    --     Success   : Boolean;
 169
 170    --  begin
 171    --     Enable_Get_Immediate (C_Stream (Current_Input), Success);
 172
 173    --     if Success = False then
 174    --        raise Device_Error;
 175    --     end if;
 176
 177    --     --  Example with the first type of Get_Immediate
 178    --     --  Waits for an entry on the input. Immediately returns
 179    --     --  after having received an character on the input
 180
 181    --     Put ("Input -> ");
 182    --     Get_Immediate (Input);
 183    --     New_Line;
 184    --     Put_Line ("Character read: " & Input);
 185
 186    --     --  Example with the second type of Get_Immediate
 187    --     --  This is equivalent to a non blocking read
 188
 189    --     for J in 1 .. 10 loop
 190    --        Put ("Input -> ");
 191    --        Get_Immediate (Input, Available);
 192    --        New_Line;
 193
 194    --        if Available = True then
 195    --           Put_Line ("Character read: " & Input);
 196    --        end if;
 197
 198    --        delay 1.0;
 199    --     end loop;
 200
 201    --     Disable_Get_Immediate (C_Stream (Current_Input), Success);
 202
 203    --     if Success = False then
 204    --        raise Device_Error;
 205    --     end if;
 206
 207    --  exception
 208    --     when Device_Error =>
 209    --        Put_Line ("Device Error. Check your configuration");
 210    --  end Example_IO;
 211
 212    procedure Enable_Get_Immediate
 213      (File    : Interfaces.C_Streams.FILEs;
 214       Success : out Boolean);
 215    --  On VxWorks, a call to this procedure is required before subsequent calls
 216    --  to Get_Immediate have the desired effect of not waiting for a line
 217    --  return. The reason that this call is not automatic on this target is
 218    --  that the call flushes the input buffer, discarding any previous input.
 219    --  Note: Following a call to Enable_Get_Immediate, the only permitted
 220    --  operations on the relevant file are Get_Immediate operations. Any
 221    --  other operations have undefined behavior.
 222
 223    procedure Disable_Get_Immediate
 224      (File    : Interfaces.C_Streams.FILEs;
 225       Success : out Boolean);
 226    --  This procedure resets File to standard mode, and permits subsequent
 227    --  use of the full range of Ada.Text_IO functions
 228
 229 end Interfaces.VxWorks.IO;