ttyname (BPX2TYN, BPX4TYN) (X/Open version) — Get the name of a terminal

Function

The ttyname callable service obtains the pathname of the terminal that is associated with the file descriptor.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX2TYN):	31-bit
AMODE (BPX4TYN):	64-bit
ASC mode:	Primary 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

CALL BPX2TYN,(File_descriptor,
              Terminal_name_length,
              Terminal_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TYN with the same parameters.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the file descriptor.

Terminal_name_length

Parameter supplied and returned

Type:: Integer
Length:: Fullword

The name of a fullword that contains the size, in bytes, of the buffer that is referred to by Terminal_name. The size of this field should be less than 4096 bytes (4KB) in length. The size of the buffer that is specified should be the maximum length that the terminal_name could be on output.

Terminal_name

Returned parameter

Type:: Character string
Character set:: No restriction
Length:: Specified by the Terminal_name_length parameter

The name of an area to which ttyname returns either the pathname of the terminal, terminated by a X'00', or a single byte of X'00' (null string), if the file descriptor is not valid or does not represent a terminal.

The length of Terminal_name should be 1024 bytes long (PATH_MAX+1), unless the pathname is known to be shorter.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the ttyname 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 ttyname service stores the return code. The ttyname service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The ttyname service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	The File_descriptor argument is not a valid open file descriptor.
ENOTTY	The File_descriptor argument is not associated with a terminal.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the ttyname service stores the reason code. The ttyname 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

This version of ttyname is XPG4 compliant.
If Terminal_name is an area smaller than the actual pathname of the terminal, the name is truncated.

Related services

isatty (BPX1ITY) (POSIX Version) — Determine whether a file descriptor represents a terminal

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX2TYN (ttyname) example.