grantpt (BPX1GPT, BPX4GPT) — Grant access to the slave pseudoterminal

Function

The grantpt callable service changes the mode and ownership of the slave pseudoterminal device that is identified by the file descriptor. The file descriptor must be the file descriptor of the corresponding master pseudoterminal. The user ID of the slave is set to the real UID of the calling process. The group ID is set to the group ID that is associated with the group name that was specified by the installation in the TTYGROUP initialization parameter. The permission mode of the slave pseudoterminal is set to be readable and writable by the owner, and writable by the group.

You can provide secure connections either by using grantpt and unlockpt, or by issuing the first open against the slave pseudoterminal from the user ID or process that opened the master terminal.

Requirements

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

The syntax format is as follows:

CALL BPX1GPT,(File_descriptor,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4GPT with the same parameter.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the file descriptor for the terminal.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the grantpt 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 grantpt service stores the return code. The grantpt 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 grantpt service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The slave pseudoterminal was opened before grantpt, or a grantpt has already been issued. In either case, slave pseudoterminal permissions and ownership have already been updated. If you use grantpt to change slave pseudoterminal permissions, you must issue grantpt between the master open and the first pseudoterminal open. The grantpt service can only be requested once.
EBADF	The File_descriptor parameter does not specify a valid open file descriptor.
EINVAL	The file descriptor is not associated with a master pseudoterminal device.
ENOENT	During lookup, the slave pseudoterminal device was not found.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Related services

unlockpt (BPX1UPT, BPX4UPT) — Unlock a pseudoterminal master/slave pair

Characteristics and restrictions

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