tcsetpgrp (BPX1TSP, BPX4TSP) — Set the foreground process group ID
Function
The tcsetpgrp callable service moves the requested process group into the foreground, replacing the current foreground process group. The current foreground process group then becomes a background process group.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor or problem state, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1TSP): | 31-bit |
| AMODE (BPX4TSP): | 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
|
AMODE 64 callers use BPX4TSP 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 device.
- Process_group_ID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the process group ID that is to be associated with the controlling terminal.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the tcsetpgrp 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 tcsetpgrp service stores the return code. The tcsetpgrp 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 tcsetpgrp 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. EINTR A signal interrupted the function. EINVAL Process_group_ID is not a process group ID that is supported by this implementation. ENOTTY The calling process does not have a controlling terminal; File_descriptor is not associated with the controlling terminal; or the controlling terminal is no longer associated with the session of the calling process. EPERM Process_group_ID does not match the process group ID of any process in the same session as the calling process. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the tcsetpgrp service stores the reason code. The tcsetpgrp 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 tcsetpgrp service moves the requested process group into the foreground, replacing the current foreground process group. The current foreground process group then becomes a background group. This terminal must be the controlling terminal of the calling process, and it must be currently associated with the session of the calling process. Process_group_ID must represent a process group in the same session as the calling process.
- After the foreground process group is set, reads by the process group that was formerly in the foreground fail or cause the process group to stop from a SIGTTIN signal. Writes can also cause the process to stop (from a SIGTTOU signal), or they can succeed, depending upon the current setting of TOSTOP (from tcsetattr) and the signal options for SIGTTOU.
- The system issues a SIGTTOU signal when tcsetpgrp() is issued from a background process, unless SIGTTOU is being ignored or blocked. If the signal is set to default processing (SIG_DFL), the process group is stopped. If there is a handler, the handler gets control and errno=EINTR is returned.
- The File_descriptor parameter that is specified can be any of
the descriptors that represent the controlling terminal (such as standard
input [stdin], standard output [stdout], and standard error [stderr]).
The service affects future access from any file descriptor in use
for the terminal. Note: You must consider redirection when choosing the file descriptor to specify.
- The following table defines the processing of the SIGTTOU signal
when the tcsetpgrp service is called from a background process against
a controlling terminal:
SIGTTOU processing Expected behavior Default or signal handler The SIGTTOU signal is generated.
The function is not performed.
Return_value is set to -1,
and Return_code is set to EINTR.Ignored or blocked The SIGTTOU signal is not sent.
The function continues normally.
Related services
Characteristics and restrictions
There are no restrictions on the use of the tcsetpgrp service.
Examples
For an example using this callable service, see BPX1TSP (tcsetpgrp) example.