PowerAda 69

From OC Systems Wiki!
Jump to: navigation, search

(69) Any implementation-defined characteristics of the input-output packages.

See A.7(14).

Packages SEQUENTIAL_IO, DIRECT_IO, and TEXT_IO are supported.

Package LOW_LEVEL_IO is not supported.

Unconstrained array types and unconstrained types with discriminants may be instantiated for I/O.

File names follow the conventions and restrictions of the target operating system, except that ASCII.Nul characters are disallowed.

In TEXT_IO, the type FIELD is defined as follows:

subtype Field is integer range 0..1000; In TEXT_IO, the type COUNT is defined as follows:

type Count is range 0..2_147_483_646; Annex A of the LRM describes the Ada functions for manipulating files. The operations CREATE and OPEN for files allow the caller to specify a FORM string. PowerAda supports the syntax and semantics for the FORM string as specified for POSIX/Ada in Section 8 of IEEE Std 1003.5-1992.

The syntax for the FORM string, written in the notation used within the LRM:

form_image ::=
 [field_name_identifier => field_value
 {,field_name_identifier => field_value}]
field_value ::=  field_value_identifier | integer

The required values of field_name_identifier and field_value are described in the paragraphs that follow. All field names and field values are insensitive to case.

The exception IO_EXCEPTIONS.USE_ERROR is raised if the FORM parameter includes a field name or a field value that is not defined by POSIX/Ada or PowerAda. The USE_ERROR exception is also raised if a particular field name appears more than once within a FORM parameter.

File permissions

The field names are OWNER, GROUP, and OTHER. The allowed field values are NONE, READ, WRITE, EXECUTE, READ_WRITE, READ_EXECUTE, WRITE_EXECUTE, or READ_WRITE_EXECUTE. These fields may be used only with the CREATE operation; use with the OPEN operation will raise USE_ERROR. The fields set the access permissions for a newly created file (if the file does not already exist at the time of the CREATE operation). If a field is specified, the resulting set of permissions is the logical intersection of those specified in the parameter and those allowed by the permission mask for the process. If a field is not specified, the default value is READ_WRITE_EXECUTE, which results in the set of permissions specified by the current process file creation mask.

Appending to the file

The field name is APPEND. The field value is either TRUE or FALSE. If not specified, the default value is FALSE. This field may be used only with the OPEN operation. Use with the CREATE operation will raise USE_ERROR. Use of "APPEND => TRUE" means that any output shall be written to the end of the named external file.

Blocking or nonblocking I/O

The field name is BLOCKING. The only supported field value is PROGRAM which is also the default value. In PowerAda, I/O will block the task executing the I/O statement..

How characters are read from the keyboard

The field name is TERMINAL_INPUT. The field value is either LINES or CHARACTERS. If not specified, the default value is LINES. If the value LINES is selected, the input terminal is processed in canonical mode. If the value CHARACTERS is selected, noncanonical terminal input will be performed.

In canonical mode input processing, the terminal input is processed in units of lines. A line is delimited by a newline character, an end-of-file character, or an end-of-line character. This means that a read request will not return until an entire line has been typed or a signal has been received. Also, no matter how many characters are requested in the read call, at most one line will be returned.

In noncanonical mode input processing, input characters are not assembled into lines, and erase and kill processing does not occur. If the value CHARACTERS is selected, the Ada I/O input operations will return as soon as there is enough input to satisfy the request.

Specifying TERMINAL_INPUT has no effect if the file is not opened for input or if the file is opened on a terminal.

Creation of FIFO files

The field name is FILE_STRUCTURE. The field value is either REGULAR or FIFO. If not specified, the default value is REGULAR. Use of this field is permitted only with the CREATE operation. Use with the OPEN operation, causes the exception USE_ERROR to be raised. Use of "FILE_STRUCTURE=>FIFO" means that the file to be created shall be a named FIFO file. If the file already exists, the CREATE operation will raise USE_ERROR.

Note that the CREATE of a FIFO will block until some other process opens the FIFO for either output (if the CREATE is for input) or input (if the CREATE is for output).

Access to open POSIX files

The field name is FILE_DESCRIPTOR. The field value is a sequence of characters that would denote a valid file descriptor value if used as the parameter for Integer'Value. Use of this option means that the opened Ada file object becomes associated with the external file denoted by the given file descriptor. The association continues until the Ada file object is closed. If the integer number does not correspond to an open file descriptor, or if the modes are incompatible, then USE_ERROR is raised. During the period that the Ada file is open, the execution of any AIX I/O or file operations, except for file locking, on the file descriptor will have unspecified results on the contents of the external file. Subsequent use of the TEXT_IO.NAME function on this file will raise USE_ERROR. This field may be used only with OPEN; use with CREATE will raise USE_ERROR. Note that this mechanism permits access to the standard error file by using "FILE_DESCRIPTOR=>2".

Treatment of terminators

The field name is PAGE_TERMINATORS. The field value is either TRUE or FALSE. The default value is TRUE. Use of "PAGE_TERMINATORS => TRUE" means that the external representation of a page terminator is ASCII.FF. Use of "PAGE_TERMINATORS => FALSE" means that the external file will contain no page terminators. Upon input of a file with "PAGE_TERMINATORS => FALSE," any occurrence of the character ASCII.FF will not be interpreted as a page terminator but will instead result in the input of the ASCII.FF character. Upon output of a file with "PAGE_TERMINATORS => FALSE," an explicit call to TEXT_IO.NEW_PAGE will raise USE_ERROR, and an explicit call to TEXT_IO.SET_LINE when the current line number exceeds the value specified by the TO parameter will raise USE_ERROR.

The file objects returned by TEXT_IO.STANDARD_INPUT and TEXT_IO.STANDARD_OUTPUT operate as if they were opened with "PAGE_TERMINATORS => FALSE."

Buffering of output

PowerAda supports the implementation specific field name DISABLE_BUFFERING. Note that this is not a field name defined by POSIX/Ada. The field value is either TRUE or FALSE. The default value is FALSE. For output to some files, PowerAda will buffer the output in memory before writing the output to the file. Buffering greatly improves the performance of output to a file. Specifying "DISABLE_BUFFERING => TRUE" will disable any buffering that PowerAda performs.

Advisory locking of files

PowerAda supports the implementation specific field name LOCK_FILE. Note that this is not a field name defined by POSIX/Ada. The field value is either TRUE or FALSE. The default value is FALSE. Specifying "LOCK_FILE => TRUE" will result in PowerAda obtaining an advisory lock on the file upon OPEN or CREATE. If the file is opened for input, the lock will be a read lock on the entire file. If the file is opened for output, the lock will be a write lock on the entire file. The OPEN or CREATE operation will raise USE_ERROR if some other process has the file locked for reading or writing if "LOCK_FILE => TRUE" is specified.

I/O For Unconstrained Types

USE_ERROR may be raised by CREATE if the maximum range for the unconstrained discriminants of a record is large (e.g., POSITIVE).

Conditions under which an exception is raised

USE_ERROR will be raised in the following situations:

  • illegal syntax for a FORM string (see above),
  • exceeding the maximum record size of 16#4000000#,
  • specifying a FILE_DESCRIPTOR in the FORM string on an OPEN call that is not already open,
  • specifying a FILE_DESCRIPTOR in the FORM string on an OPEN call that is not open with the correct mode,
  • an attempt is made to open the same external file for writing that is already open for reading or writing in the same program,
  • an attempt is made to open the same external file for reading that is already open for writing in the same program,
  • an attempt to create a FIFO, via the FORM string, without specifying a name,
  • an attempt to get the NAME of a file opened using FILE_DESCRIPTOR ina FORM string,
  • an attempt to get the NAME of STANDARD_INPUT, STANDARD_OUTPUT, or STANDARD_ERROR when they are not associated with a terminal (e.g., when redirected to a pipe or file),
  • when the fully-qualified NAME of a file cannot be determined (e.g., because of directory permissions),
  • an attempt to perform on operation that would require a new page terminator to be written to a file opened with PAGE_TERMINATORS => FALSE in the FORM string (this includes STANDARD_INPUT, STANDARD_OUTPUT, and STANDARD_ERROR),
  • failure of a low-level I/O operation due to:
    • insufficient space left in the file system,
    • insufficient user or group quotas for the operation,
    • an attempt to create a file that already exists,
    • the system limit for open files per process has been reached,
    • the system file table is full,
    • too many symbolic links were encountered in the path name,
    • a file in the specified path is not a directory,
    • the device associated with a special file does not exist.

NAME_ERROR is raised in the following situations:

  • the fully-qualified filename exceeds 1023 characters,
  • the filename contains ASCII.NUL,
  • an attempt to open a named file that does not exist,
  • an attempt to open or create a named file without sufficient permission.