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