A.15 The Package Command_Line

danger

This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue

1

The package Command_Line allows a program to obtain the values of its arguments and to set the exit status code to be returned on normal termination.

1.a/2

implementation defined

The meaning of Argument_Count, Argument, and Command_Name for package Command_Line. The bounds of type Command_Line.Exit_Status.

Static Semantics

2

The library package Ada.Command_Line has the following declaration:

3/5

package Ada.Command_Line 
  with  Preelaborate, Nonblocking, Global => in out synchronized is 
function Argument_Count return Natural;
function Argument (Number : in Positive) return String;
function Command_Name return String;
type Exit_Status is implementation-defined integer type;
Success : constant Exit_Status;
  Failure : constant Exit_Status;
procedure Set_Exit_Status (Code : in Exit_Status);
private
  ... -- not specified by the language
end Ada.Command_Line;

function Argument_Count return Natural;

12/3

If the external execution environment supports passing arguments to a program, then Argument_Count returns the number of arguments passed to the program invoking the function. Otherwise, it returns 0. The meaning of “number of arguments” is implementation defined.

13

function Argument (Number : in Positive) return String;

14/5

If the external execution environment supports passing arguments to a program, then Argument returns an implementation-defined value with lower bound 1 corresponding to the argument at relative position Number. If Number is outside the range 1..Argument_Count, then Constraint_Error is propagated.

14.a

ramification

If the external execution environment does not support passing arguments to a program, then Argument(N) for any N will raise Constraint_Error, since Argument_Count is 0.

15

function Command_Name return String;

16/5

If the external execution environment supports passing arguments to a program, then Command_Name returns an implementation-defined value with lower bound 1 corresponding to the name of the command invoking the program; otherwise, Command_Name returns the null string.

16.1/1

type Exit_Status is implementation-defined integer type;

17

The type Exit_Status represents the range of exit status values supported by the external execution environment. The constants Success and Failure correspond to success and failure, respectively.

18

procedure Set_Exit_Status (Code : in Exit_Status);

19

If the external execution environment supports returning an exit status from a program, then Set_Exit_Status sets Code as the status. Normal termination of a program returns as the exit status the value most recently set by Set_Exit_Status, or, if no such value has been set, then the value Success. If a program terminates abnormally, the status set by Set_Exit_Status is ignored, and an implementation-defined exit status value is set.

20

If the external execution environment does not support returning an exit value from a program, then Set_Exit_Status does nothing.

Implementation Permissions

21

An alternative declaration is allowed for package Command_Line if different functionality is appropriate for the external execution environment.

22

note

NOTE Argument_Count, Argument, and Command_Name correspond to the C language's argc, argv[n] (for n>0) and argv[0], respectively.

22.a

note

To be honest: The correspondence of Argument_Count to argc is not direct — argc would be one more than Argument_Count, since the argc count includes the command name, whereas Argument_Count does not.

Extensions to Ada 83

22.b/3

note

This subclause is new in Ada 95.

Wording Changes from Ada 2012

22.c/5

correction

Defined the lower bound of functions Argument and Command_Name. This could be inconsistent if someone depended on the lower bound of these routines (and it wasn't 1), but such code was never portable (even to later versions of the same implementation). Thus we don't document it as an inconsistency.

A.15.1 The Packages Wide_Command_Line and Wide_Wide_Command_Line

1/5

The packages Wide_Command_Line and Wide_Wide_Command_Line allow a program to obtain the values of its arguments and to set the exit status code to be returned on normal termination.

Static Semantics

2/5

The specification of package Wide_Command_Line is the same as for Command_Line, except that each occurrence of String is replaced by Wide_String.

3/5

The specification of package Wide_Wide_Command_Line is the same as for Command_Line, except that each occurrence of String is replaced by Wide_Wide_String.

Extensions to Ada 2012

3.a/5

note

These packages are new.