gcc/ada/libgnat/g-exptty.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT LIBRARY COMPONENTS                          --
   4 --                                                                          --
   5 --                      G N A T . E X P E C T . T T Y                       --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                    Copyright (C) 2000-2023, AdaCore                      --
  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 with GNAT.TTY;
  33
  34 with System;
  35 with System.OS_Constants;
  36
  37 package GNAT.Expect.TTY is
  38
  39    pragma Linker_Options (System.OS_Constants.PTY_Library);
  40
  41    ------------------
  42    --  TTY_Process --
  43    ------------------
  44
  45    type TTY_Process_Descriptor is new Process_Descriptor with private;
  46    --  Similar to Process_Descriptor, with the parent set up as a full terminal
  47    --  (Unix sense, see tty(4)).
  48
  49    procedure Pseudo_Descriptor
  50      (Descriptor  : out TTY_Process_Descriptor'Class;
  51       TTY         : GNAT.TTY.TTY_Handle;
  52       Buffer_Size : Natural := 4096);
  53    --  Given a terminal descriptor (TTY), create a pseudo process descriptor
  54    --  to be used with GNAT.Expect.
  55    --
  56    --  Note that it is invalid to call Close, Interrupt, Send_Signal on the
  57    --  resulting descriptor. To deallocate memory associated with Process,
  58    --  call Close_Pseudo_Descriptor instead.
  59
  60    procedure Close_Pseudo_Descriptor
  61      (Descriptor : in out TTY_Process_Descriptor);
  62    --  Free memory and ressources associated with Descriptor. Will *not*
  63    --  close the associated TTY, it is the caller's responsibility to call
  64    --  GNAT.TTY.Close_TTY.
  65
  66    procedure Interrupt (Pid : Integer);
  67    --  Interrupt a process given its pid.
  68    --  This is equivalent to sending a ctrl-c event, or kill -SIGINT.
  69
  70    procedure Terminate_Process (Pid : Integer);
  71    --  Terminate abruptly a process given its pid.
  72    --  This is equivalent to kill -SIGKILL under unix, or TerminateProcess
  73    --  under Windows.
  74
  75    overriding procedure Send
  76      (Descriptor   : in out TTY_Process_Descriptor;
  77       Str          : String;
  78       Add_LF       : Boolean := True;
  79       Empty_Buffer : Boolean := False);
  80    --  See parent
  81    --  What does that comment mean??? what is "parent" here
  82
  83    procedure Set_Use_Pipes
  84      (Descriptor : in out TTY_Process_Descriptor;
  85       Use_Pipes  : Boolean);
  86    --  Tell Expect.TTY whether to use Pipes or Console (on windows). Needs to
  87    --  be set before spawning the process. Default is to use Pipes.
  88
  89    procedure Set_Size
  90      (Descriptor : in out TTY_Process_Descriptor'Class;
  91       Rows       : Natural;
  92       Columns    : Natural);
  93    --  Sets up the size of the terminal as reported to the spawned process
  94
  95    function Is_Process_Running
  96       (Descriptor : in out TTY_Process_Descriptor)
  97       return Boolean;
  98    --  Returns True if the process is still alive
  99
 100 private
 101
 102    --  All declarations in the private part must be fully commented ???
 103
 104    overriding procedure Close
 105      (Descriptor : in out TTY_Process_Descriptor;
 106       Status     : out Integer);
 107
 108    overriding procedure Close
 109      (Descriptor : in out TTY_Process_Descriptor);
 110
 111    overriding procedure Interrupt (Descriptor : in out TTY_Process_Descriptor);
 112    --  When we use pseudo-terminals, we do not need to use signals to
 113    --  interrupt the debugger, we can simply send the appropriate character.
 114    --  This provides a better support for remote debugging for instance.
 115
 116    procedure Set_Up_Communications
 117      (Pid        : in out TTY_Process_Descriptor;
 118       Err_To_Out : Boolean;
 119       Pipe1      : not null access Pipe_Type;
 120       Pipe2      : not null access Pipe_Type;
 121       Pipe3      : not null access Pipe_Type);
 122
 123    procedure Set_Up_Parent_Communications
 124      (Pid   : in out TTY_Process_Descriptor;
 125       Pipe1 : in out Pipe_Type;
 126       Pipe2 : in out Pipe_Type;
 127       Pipe3 : in out Pipe_Type);
 128
 129    procedure Set_Up_Child_Communications
 130      (Pid   : in out TTY_Process_Descriptor;
 131       Pipe1 : in out Pipe_Type;
 132       Pipe2 : in out Pipe_Type;
 133       Pipe3 : in out Pipe_Type;
 134       Cmd   : String;
 135       Args  : System.Address);
 136
 137    procedure Close_Input (Descriptor : in out TTY_Process_Descriptor);
 138
 139    Still_Active : constant Integer := -1;
 140
 141    type TTY_Process_Descriptor is new Process_Descriptor with record
 142       Process     : System.Address := System.Null_Address;
 143       --  Underlying structure used in C
 144       Exit_Status : Integer := Still_Active;
 145       --  Holds the exit status of the process
 146       Use_Pipes   : Boolean := True;
 147    end record;
 148
 149 end GNAT.Expect.TTY;