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
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, state any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1TGA): | 31-bit |
AMODE (BPX4TGA): | 64-bit |
ASC mode: | Primary address space control (ASC) mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4TGA with the same parameters.
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
- 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
- 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.
Examples
For an example using this callable service, see BPX1TGA (tcgetattr) example.