trap command (specifies the action when signals and forced termination requests are received)
The functionality of the trap command for the Windows edition differs from its functionality for the UNIX edition. For details about the functionality for the UNIX edition, see (1) trap command (UNIX edition). For details about the functionality for the Windows edition, see (2) trap command (Windows edition).
(1) trap command (UNIX edition)
- Organization of this page
Format
trap [action] [signal ...]
Description
This command specifies the action to be taken when one or more specified signals are received. When the shell receives a specified signal, it executes the specified action.
When this command is executed with no arguments, it outputs to the standard output a list of the actions associated with all signals in the following format:
Category of signal |
Output format |
---|---|
Signal whose name is defined |
trap -- action signal-name-without-SIG-prefix |
Signal whose name is not defined |
trap -- action UNKNOWN SIGNAL |
Actions can be set for signals for which multiple names are defined under a single signal number, as shown in the tables below.
- Linux
-
Signal name
Alternate name
Whether an action can be set by the trap command
SIGSYS
SIGUNUSED
SIGSYS
Can be set.
SIGUNUSED
Can be set.
- AIX
-
Signal name
Alternate name 1
Alternate name 2
Whether an action can be set by the trap command
SIGABRT
SIGLOST
SIGIOT
SIGABRT
Can be set.
SIGLOST
Can be set.
SIGIOT
Can be set.
SIGIO
SIGPOLL
None
SIGIO
Can be set.
SIGPOLL
Can be set.
- HP-UX or Solaris
-
Signal name
Alternate name
Whether an action can be set by the trap command
SIGABRT
SIGIOT
SIGABRT
Can be set.
SIGIOT
Can be set.
SIGIO
SIGPOLL
SIGIO
Can be set.
SIGPOLL
Can be set.
When an action is specified for a signal for which multiple names are defined under a single signal number, one of the specified signal names is output.
The trap command does not display an action that is set for a signal when that action is registered in an extended function.
Arguments
- action
-
Specifies the action to be taken when the specified signals are received. If this argument is omitted or a hyphen (-) is specified, the previously-specified traps for the specified signals are reverted to their default settings. If action is omitted and a signal number is specified for signal, the previously specified traps for the specified signals are also reverted to their default settings.
- signal
-
Specifies a signal that is to be trapped. You can specify a signal number or a signal name. When you specify a signal name, you must specify it without the leading SIG (for example, specify INT for SIGINT). For the specifications for each signal, see the documentation for the OS being used.
The operation that is performed when SIGTERM is specified depends on the specification of the TRAP_ACTION_SIGTERM environment setting parameter. For details, see TRAP_ACTION_SIGTERM parameter (defines the job controller's action when a forced termination request is received) in 7. Parameters Specified in the Environment Files.
You can specify multiple signals delimited by the space. You can also specify 0, EXIT, or ERR for this argument.
- When you execute the trap command with 0 or EXIT specified for signal
-
Executes the command specified in action when the shell terminates.
- When you execute the trap command with ERR specified for signal
-
Executes the action specified in action when the any of the following commands executed after the trap command terminates with a non-zero return code:
-
Regular built-in command
-
typeset command
-
return command that results in an error in a function or external script because of an invalid format
-
In AIX, the SIGWAITING signal cannot be specified. If you execute this command in AIX with SIGWAITING specified, the command terminates with an error.
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination |
1 |
Error termination |
Notes
-
If you specify a value that is smaller than 0 for the signal argument, the trap command treats it as an invalid signal. When you specify a numeric value for the signal argument, specify a value that is within the permissible range of 0 to signal.
-
If the adshread extended shell command is specified in the operation defined by the trap command and a forced termination request is received, the job waits for an entry and will not be terminated. If you specify TERM, or AUTO(and the job starts from JP1/AJS) in the TRAP_ACTION_SIGTERM parameter, do not specify the adshread extended shell command in the operation that is defined by the trap command.
-
If the command syntax of this special built-in command is invalid, it exits the shell that is executing the command.
-
If the action argument is omitted and only a signal number is specified in the signal argument, the trap command resets the action specified for signal to the default setting. However, if only a signal name is specified without SIG, the trap command terminates itself without resetting the action specified for signal.
- Example: trap 15
-
The command resets the action for signal number 15 to the default setting.
- Example: trap TERM
-
The command does not reset the action.
Usage examples
-
Output the message "trapped." by the echo command when the INT signal is received.
trap 'echo trapped.' INT
-
Display the actions that are associated with signals.
Contents of the job definition script
trap -- 'echo Hangup.' HUP trap -- 'echo trapped.' INT trap
Contents of the STDOUT file of the execution job
******** JOB SCOPE STDOUT ******** trap -- 'echo Hangup.' HUP trap -- 'echo trapped.' INT
(2) trap command (Windows edition)
Format
trap [action][method]
Description
This command specifies the action to be taken when a forced termination request is received.
- When TERM is specified in the TRAP_ACTION_SIGTERM parameter
-
The action to be taken upon receiving a forced termination request can be specified. When the forced termination request specified in the method is received, the job controller performs the operation specified for action.
If the forced termination request specified in method is neither TERM nor 15, the command issues the KNAX6718-I message and terminates with return code 0 without performing the specified action.
If the command is executed with no argument specified, it outputs the action set for forced termination requests to the standard output in the following format:
Output format
trap -- action "character-string-indicating-the-forced-termination-method"
- When DISABLE is specified in the TRAP_ACTION_SIGTERM parameter
-
The command issues the KNAX6710-I message and always terminates normally with return code 0. The command does not perform processing for forced termination requests.
Arguments
- action
-
Specifies the action to be taken when a forced termination request is received.
If a hyphen (-) is specified for action,the command resets the previously specified action setting for the specified method so that the method is not associated with any action setting. If action is omitted and 15 is specified in the method argument, the command also resets the previously specified action setting for the specified method so that the method is not associated with any action setting.
If you specify "" for the action, the trap command terminates normally without changing the current setting for action.
- method
-
Specifies the forced termination method that is to be subject to the trap.
You must specify either TERM or 15 for method.
- TERM or 15
-
Specifies that immediate process termination is to be performed by a function such as TerminateProcess (such as forced termination from JP1/AJS or the taskkill command).
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination |
1 |
Error termination |
Notes
-
When kill -KILL process-ID is executed to terminate adshexec.exe for a job, the action defined in the terminated job's trap action TERM is executed.
-
If TERM is specified in the TRAP_ACTION_SIGTERM parameter, the trap command with an option specified results in an error. If a value other than TERM is specified in the TRAP_ACTION_SIGTERM parameter, the trap command with an option specified will not result in an error.
-
If the adshread extended shell command is specified in the operation defined by the trap command and a forced termination request is received, the job waits for an entry and will not be terminated. If you specify TERM in the TRAP_ACTION_SIGTERM parameter, do not specify the adshread extended shell command in the operation that is defined by the trap command.
-
If this special built-in command terminates with an error due to a syntax error, the shell running the command will also terminate.
-
If the action argument is omitted and 15 is specified in the method argument, the trap command resets the action specified for immediate process termination by a function such as TerminateProcess so that the method is not associated with any action setting. However, if only TERM is specified, the trap command terminates itself without resetting the action specified for immediate process termination.
- Example: trap 15
-
The command resets the action specified for immediate process termination by a function such as TerminateProcess so that the method is not associated with any action setting.
- Example: trap TERM
-
The command does not reset the action.
-
If multiple values are specified for method and at least one of those values is TERM or 15, the command sets action for TERM or 15 without issuing the KNAX6718-I message. For any other method, the command does not set action.
Example: If trap date 28 15 is executed, the trap command sets the date command as the action for 15 without issuing the KNAX6718-I message.
Usage Examples
-
"trapped." is output by the echo command when a forced termination request performed by a function such as TerminateProcess is received.
trap 'echo trapped.' TERM
-
Display the action that is set for forced termination requests. TERM is displayed as the forced termination method even when 15 is set for method in the trap command that sets action.
Contents of the job definition script:
trap 'echo trapped.' 15 trap
Contents of the STDOUT file of the execution job:
******** JOB SCOPE STDOUT ******** trap -- 'echo trapped.' TERM