tcgetattr (BPX1TGA, BPX4TGA) — Get the attributes for a terminal

Function

The tcgetattr callable service gets control information for a terminal and stores it in the specified Termios_structure.

Requirements

Parameters

File_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the file descriptor of the terminal for which you want attributes.

Termios_structure

Returned parameter

Type:

Structure

Length:

Specified by BPXYTIOS#LENGTH in the BPXYTIOS macro

The name of an area into which the function is to return the terminal information. Termios_structure is mapped by the BPXYTIOS macro. This structure contains the control modes, input modes, output modes, local modes, and special control characters as defined by the POSIX standard (see BPXYTIOS — Map the termios structure).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the tcgetattr service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the tcgetattr service stores the return code. The tcgetattr service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The tcgetattr service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	File_descriptor is not a valid open file descriptor.
ENOTTY	The file that is associated with the file descriptor is not a terminal; the process does not have a controlling terminal; or the file is not the controlling terminal for the process.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the tcgetattr service stores the reason code. The tcgetattr service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The BPXYTIOS macro should be used to map the termios structure and define the equates for bits and values. Note the following about BPXYTIOS:
   • BPXYTIOS generates standard POSIX-defined names, except that all names are uppercase. In addition, all names can have a user-specified prefix.
   • When testing or setting bits in flag fields, you should use an offset name to define which byte in the flag field contains the bit. For instance: TM C_CFLAG+HUPCL_O,HUPCL.
   • CS5 through CS8 values can be contained in CSIZE. CSIZE is essentially a 2-bit integer that can contain decimal values 0 through 3, as defined by CS5 through CS8.
   • BPXYTIOS can be used to define either a DSECT or an inline structure. This is determined by the DSECT= keyword.
   • The C_CC field is an array of 1-byte fields, indexed by the various special character equates. These equates can be used as offsets into C_CC, or can be put into a register to be used with indexing instructions. For instance:

     MVC   C_CC+VSUSP,NEWVAL    To set a new value
     LA    R10,VSUSP            To set an register to use as an index
                                   in a later IC or STC instructions

2. You can run the tcgetattr service in either a foreground or a background process. However, if the process is in the background, a foreground process can later change the attributes that you obtained.

Related services

tcsetattr (BPX1TSA, BPX4TSA) — Set the attributes for a terminal

Characteristics and restrictions

There are no restrictions on the use of the tcgetattr service.