__shutdown_registration() — Register OMVS shutdown options
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX | both | z/OS V1R3 |
Format
#define _OPEN_SYS
#include <signal.h>
int __shutdown_registration(int regtype, int regscope, int regoptions);
General description
- a shutdown blocking process
- a permanent process
- a shutdown notification process
Registration can be done for the invoking process only, or for all of the tasks in the job. The process can also modify the behavior of OMVS requests issued by permanent processes while OMVS shutdown and restart is in progress.
- process user and group identity
- process, session and process group identities
- process file mode creation mask
- zombie child processes
- signal registration, signal actions, signal mask data and pending signals
- current working directory
- open file and socket descriptors
Zombie child process ending status is checkpointed so that the permanent process can retrieve it after the restart.
If the current working directory path name cannot be resolved after restart, then the current working directory is set to a dummy root which will cause relative path name lookup to fail.
All of the checkpointed file descriptors will be marked invalid after restart, and any I/O requests other than close() will cause EIO errors.
Timer events are not checkpointed. Timer events which expire before the restart completes are lost. Timer events which have not expired after restart is complete will still be in effect.
- semaphores
- shared library programs
- __map() shared memory blocks
- message queues
- memory mapped files
- all other UNIX System Services resources
Registration is at the process level, not the thread level. For multithreaded applications, the SIGDANGER signal is sent to the process and not to any particular thread.
If a process is registered as a blocking process or a permanent process, the process must de-register before attempting to register with a different registration type. For example, a blocking process must de-register as a blocking process before attempting to register as a permanent process.
Registration remains in effect for the life of the process, or until the process de-registers. Registration remains in place across an exec() syscall because the new program image runs in the same process. Registration does not propagate to child processes as a result of fork() and spawn() syscalls.
- regtype
- Description
- _SDR_BLOCKING
- The process will prevent OMVS Shutdown from proceeding for as long as it the process remains registered as a blocking process. If the process exits or de-registers as a blocking process then OMVS Shutdown can proceed.
- _SDR_PERMANENT
- The process will not be terminated during OMVS Shutdown and Restart processing.
- _SDR_NOBLOCKING
- The process will no longer block an OMVS Shutdown.
- _SDR_NOPERMANENT
- The process will no longer be a permanent process.
- _SDR_NOTIFY
- The process will be notified by SIGDANGER signal delivery once OMVS Shutdown is initiated.
- _SDR_NONOTIFY
- The process will no longer be notified by SIGDANGER signal delivery if OMVS Shutdown is initiated.
- The calling address space is a system started task address space.
- The caller is running authorized (APF Authorized, System Key (0-7) or Supervisor State).
- The caller is a privileged UNIX process. It must either have a superuser identity or have read permission to BPX.SHUTDOWN.
- regscope
- Definition
- _SDR_REGJOB
- All the processes in the Job are registered.
- _SDR_REGPROCESS
- Only the calling process is registered.
- regoptions
- Definition
- _SDR_NOOPTIONS
- No options are requested. This request code is not valid for _SDR_NOTIFY registration.
- _SDR_BLOCKSYSCALLS
- Kernel calls issued from permanent processes while OMVS is not up will hang, and return to the caller once z/OS UNIX System Services is back up. This request is mutually exclusive with _SDR_ABENDSYSCALLS, and is valid only for permanent process registration.
- _SDR_ABENDSYSCALLS
- Kernel calls issued from permanent processes while OMVS is not up will ABEND. This request is mutually exclusive with _SDR_BLOCKSYSCALLS, and is valid only for permanent process registration.
- _SDR_SENDSIGDANGER
- Kernel sends SIGDANGER signal to the process when OMVS Shutdown is initiated. This option MUST be specified on _SDR_NOTIFY registration. This option may be specified for _SDR_BLOCKING and _SDR_PERMANENT registration. It may be combined with either _SDR_BLOCK_SYSCALLS or _SDR_ABENDSYSCALLS on _SDR_PERMANENT registration.
Returned value
If successful, __shutdown_registration() returns zero. the service completes without error, otherwise it returns
There are no documented errnos for this function.
If unsuccessful, __shutdown_registration() returns -1 and sets errno and __errno2() to indicate the cause of the failure. The _errno2() values are documented as reason codes in z/OS UNIX System Services Messages and Codes.
The values of errno are:
- Error Code
- Description
- EINVAL
- Failed for one of the following reasons:
- The callable service is rejected because the job step process must be registered before registering a lower process of the job step process.
- The request to register a blocking process or job, or a request to register a permanent process or job cannot be performed as a shutdown is currently in progress.
- The request to register a blocking process or job, or a request to register a permanent process or job cannot be performed as the job can not be de-registered while a lowerprocess is still registered.
- The request to deregister a blocking process or job, or a request to deregister a permanent process or job cannot be performed because the job or the current process is not registered.
- One of the parameters was invalid.
- EPERM
- Failed for one of the following reasons:
- Invoker does not have superuser or equivalent authority.
- Caller must be given read permission to BPX.SHUTDOWN facility class profile in order to use __shutdown_registration() successfully.
- EMVSSAF2ERR
- Internal Security product error. Hexadecimal Reason code value contains the two byte security product return code xx and reason code yy.
Example
/*
Register the process as a blocking process and request notification
of shutdown initiation by way of SIGDANGER signal.
*/
#define _OPEN_SYS
#include <signal.h>
...
if (-1 == (rc = __shutdown_registration(_SDR_ BLOCKING, _SDR_REGPROCESS,
_SDR_SENDSIGDANGER)))
printf("Error during __shutdown_registration errno=%d,
errno2=0x%08x\n", errno, __errno2())
/*
Register the process as a permanent process and don't ask for
SIGDANGER signals.
*/
#define _OPEN_SYS
#include <sys>
if (-1 == (rc = __shutdown_registration(_SDR_PERMANENT, _SDR_REGPROCESS,
_SDR_NOOPTIONS)))
printf("Error during __shutdown_registration errno=%d,
errno2=0x%08x\n", errno, __errno2())