-- --
-- S p e c --
-- --
--- Copyright (C) 2000-2005 Ada Core Technologies, Inc. --
+-- Copyright (C) 2000-2009, AdaCore --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- Non_Blocking_Spawn
-- (Fd, "ftp",
-- (1 => new String' ("machine@domain")));
--- Timeout := 10000; -- 10 seconds
+-- Timeout := 10_000; -- 10 seconds
-- Expect (Fd, Result, Regexp_Array'(+"\(user\)", +"\(passwd\)"),
-- Timeout);
-- case Result is
-- Close (Fd);
-- You can also combine multiple regular expressions together, and get the
--- specific string matching a parenthesis pair by doing something like. If you
--- expect either "lang=optional ada" or "lang=ada" from the external process,
--- you can group the two together, which is more efficient, and simply get the
--- name of the language by doing:
+-- specific string matching a parenthesis pair by doing something like this:
+-- If you expect either "lang=optional ada" or "lang=ada" from the external
+-- process, you can group the two together, which is more efficient, and
+-- simply get the name of the language by doing:
-- declare
-- Matched : Match_Array (0 .. 2);
-- -- Task Safety --
-- -----------------
--- This package is not task-safe: there should be not concurrent calls to
--- the functions defined in this package. In other words, separate tasks
--- may not access the facilities of this package without synchronization
--- that serializes access.
+-- This package is not task-safe: there should not be concurrent calls to the
+-- functions defined in this package. In other words, separate tasks must not
+-- access the facilities of this package without synchronization that
+-- serializes access.
with System;
with GNAT.OS_Lib;
Null_Pid : constant Process_Id := 0;
type Filter_Type is (Output, Input, Died);
- -- The signals that are emitted by the Process_Descriptor upon state
- -- changed in the child. One can connect to any of this signal through
- -- the Add_Filter subprograms.
+ -- The signals that are emitted by the Process_Descriptor upon state change
+ -- in the child. One can connect to any of these signals through the
+ -- Add_Filter subprograms.
--
-- Output => Every time new characters are read from the process
-- associated with Descriptor, the filter is called with
- -- these new characters in argument.
+ -- these new characters in the argument.
--
- -- Note that output is only generated when the program is
+ -- Note that output is generated only when the program is
-- blocked in a call to Expect.
--
-- Input => Every time new characters are written to the process
-- associated with Descriptor, the filter is called with
- -- these new characters in argument.
- -- Note that input is only generated by calls to Send.
+ -- these new characters in the argument.
+ -- Note that input is generated only by calls to Send.
--
-- Died => The child process has died, or was explicitly killed
-- the process and/or automatic parsing of the output.
--
-- The expect buffer associated with that process can contain at most
- -- Buffer_Size characters. Older characters are simply discarded when
- -- this buffer is full. Beware that if the buffer is too big, this could
- -- slow down the Expect calls if not output is matched, since Expect has
- -- to match all the regexp against all the characters in the buffer.
- -- If Buffer_Size is 0, there is no limit (ie all the characters are kept
+ -- Buffer_Size characters. Older characters are simply discarded when this
+ -- buffer is full. Beware that if the buffer is too big, this could slow
+ -- down the Expect calls if the output not is matched, since Expect has to
+ -- match all the regexp against all the characters in the buffer. If
+ -- Buffer_Size is 0, there is no limit (i.e. all the characters are kept
-- till Expect matches), but this is slower.
--
-- If Err_To_Out is True, then the standard error of the spawned process is
-- connected to the standard output. This is the only way to get the
- -- Except subprograms also match on output on standard error.
+ -- Except subprograms to also match on output on standard error.
--
-- Invalid_Process is raised if the process could not be spawned.
procedure Close (Descriptor : in out Process_Descriptor);
-- Terminate the process and close the pipes to it. It implicitly
-- does the 'wait' command required to clean up the process table.
- -- This also frees the buffer associated with the process id.
+ -- This also frees the buffer associated with the process id. Raise
+ -- Invalid_Process if the process id is invalid.
procedure Close
(Descriptor : in out Process_Descriptor;
Status : out Integer);
- -- Same as above, but also returns the exit status of the process,
- -- as set for example by the procedure GNAT.OS_Lib.OS_Exit.
+ -- Same as above, but also returns the exit status of the process, as set
+ -- for example by the procedure GNAT.OS_Lib.OS_Exit.
procedure Send_Signal
(Descriptor : Process_Descriptor;
Signal : Integer);
- -- Send a given signal to the process
+ -- Send a given signal to the process. Raise Invalid_Process if the process
+ -- id is invalid.
procedure Interrupt (Descriptor : in out Process_Descriptor);
-- Interrupt the process (the equivalent of Ctrl-C on unix and windows)
-- and call close if the process dies.
function Get_Input_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
-- Return the input file descriptor associated with Descriptor
function Get_Output_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
-- Return the output file descriptor associated with Descriptor
function Get_Error_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
-- Return the error output file descriptor associated with Descriptor
function Get_Pid
- (Descriptor : Process_Descriptor)
- return Process_Id;
- -- Return the process id assocated with a given process descriptor
+ (Descriptor : Process_Descriptor) return Process_Id;
+ -- Return the process id associated with a given process descriptor
function Get_Command_Output
(Command : String;
Arguments : GNAT.OS_Lib.Argument_List;
Input : String;
- Status : access Integer;
+ Status : not null access Integer;
Err_To_Out : Boolean := False) return String;
-- Execute Command with the specified Arguments and Input, and return the
-- generated standard output data as a single string. If Err_To_Out is
--
-- Str is a string of all these characters.
--
- -- User_Data, if specified, is a user specific data that will be passed to
- -- the filter. Note that no checks are done on this parameter that should
- -- be used with cautiousness.
+ -- User_Data, if specified, is user specific data that will be passed to
+ -- the filter. Note that no checks are done on this parameter, so it should
+ -- be used with caution.
procedure Add_Filter
(Descriptor : in out Process_Descriptor;
Filter_On : Filter_Type := Output;
User_Data : System.Address := System.Null_Address;
After : Boolean := False);
- -- Add a new filter for one of the filter type. This filter will be
- -- run before all the existing filters, unless After is set True,
- -- in which case it will be run after existing filters. User_Data
- -- is passed as is to the filter procedure.
+ -- Add a new filter for one of the filter types. This filter will be run
+ -- before all the existing filters, unless After is set True, in which case
+ -- it will be run after existing filters. User_Data is passed as is to the
+ -- filter procedure.
procedure Remove_Filter
(Descriptor : in out Process_Descriptor;
(Descriptor : Process_Descriptor'Class;
Str : String;
User_Data : System.Address := System.Null_Address);
- -- Function that can be used a filter and that simply outputs Str on
+ -- Function that can be used as a filter and that simply outputs Str on
-- Standard_Output. This is mainly used for debugging purposes.
-- User_Data is ignored.
procedure Lock_Filters (Descriptor : in out Process_Descriptor);
-- Temporarily disables all output and input filters. They will be
-- reactivated only when Unlock_Filters has been called as many times as
- -- Lock_Filters;
+ -- Lock_Filters.
procedure Unlock_Filters (Descriptor : in out Process_Descriptor);
-- Unlocks the filters. They are reactivated only if Unlock_Filters
-- If the buffer was full and some characters were discarded
Expect_Timeout : constant Expect_Match := -2;
- -- If not output matching the regexps was found before the timeout
+ -- If no output matching the regexps was found before the timeout
function "+" (S : String) return GNAT.OS_Lib.String_Access;
-- Allocate some memory for the string. This is merely a convenience
(Descriptor : in out Process_Descriptor;
Result : out Expect_Match;
Regexp : String;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Wait till a string matching Fd can be read from Fd, and return 1
-- if a match was found.
(Descriptor : in out Process_Descriptor;
Result : out Expect_Match;
Regexp : GNAT.Regpat.Pattern_Matcher;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as the previous one, but with a precompiled regular expression.
-- This is more efficient however, especially if you are using this
Result : out Expect_Match;
Regexp : String;
Matched : out GNAT.Regpat.Match_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as above, but it is now possible to get the indexes of the
-- substrings for the parentheses in the regexp (see the example at the
Result : out Expect_Match;
Regexp : GNAT.Regpat.Pattern_Matcher;
Matched : out GNAT.Regpat.Match_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as above, but with a precompiled regular expression
type Regexp_Array is array (Positive range <>) of GNAT.OS_Lib.String_Access;
- type Pattern_Matcher_Access is access GNAT.Regpat.Pattern_Matcher;
+ type Pattern_Matcher_Access is access all GNAT.Regpat.Pattern_Matcher;
type Compiled_Regexp_Array is array (Positive range <>)
of Pattern_Matcher_Access;
return Pattern_Matcher_Access;
-- Allocate some memory for the pattern matcher.
-- This is only a convenience function to help create the array of
- -- compiled regular expressoins.
+ -- compiled regular expressions.
procedure Expect
(Descriptor : in out Process_Descriptor;
Result : out Expect_Match;
Regexps : Regexp_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Wait till a string matching one of the regular expressions in Regexps
-- is found. This function returns the index of the regexp that matched.
(Descriptor : in out Process_Descriptor;
Result : out Expect_Match;
Regexps : Compiled_Regexp_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as the previous one, but with precompiled regular expressions.
-- This can be much faster if you are using them multiple times.
Result : out Expect_Match;
Regexps : Regexp_Array;
Matched : out GNAT.Regpat.Match_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as above, except that you can also access the parenthesis
-- groups inside the matching regular expression.
Result : out Expect_Match;
Regexps : Compiled_Regexp_Array;
Matched : out GNAT.Regpat.Match_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as above, but with precompiled regular expressions.
-- The first index in Matched must be 0, or Constraint_Error will be
(Result : out Expect_Match;
Regexps : Multiprocess_Regexp_Array;
Matched : out GNAT.Regpat.Match_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as above, but for multi processes
procedure Expect
(Result : out Expect_Match;
Regexps : Multiprocess_Regexp_Array;
- Timeout : Integer := 10000;
+ Timeout : Integer := 10_000;
Full_Buffer : Boolean := False);
-- Same as the previous one, but for multiple processes.
-- This procedure finds the first regexp that match the associated process.
procedure Set_Up_Communications
(Pid : in out Process_Descriptor;
Err_To_Out : Boolean;
- Pipe1 : access Pipe_Type;
- Pipe2 : access Pipe_Type;
- Pipe3 : access Pipe_Type);
+ Pipe1 : not null access Pipe_Type;
+ Pipe2 : not null access Pipe_Type;
+ Pipe3 : not null access Pipe_Type);
-- Set up all the communication pipes and file descriptors prior to
-- spawning the child process.
-- possibly in future child units providing extensions to this package.
procedure Portable_Execvp
- (Pid : access Process_Id;
+ (Pid : not null access Process_Id;
Cmd : String;
Args : System.Address);
pragma Import (C, Portable_Execvp, "__gnat_expect_portable_execvp");
OSDN Git Service
