General description
The __shutdown_registration() function is used to register OMVS
Shutdown characteristics for the process. The process can be registered
as one of the following:
- a shutdown blocking process
- a permanent process
- a shutdown notification process
These types are mutually exclusive. A shutdown blocking process
will prevent OMVS shutdown from proceeding until it either de-registers
as a blocking process or ends. A permanent process will survive across
an OMVS shutdown. Most OMVS process attributes will be checkpointed
during the shutdown and restored during the Restart. A shutdown notification
process will be informed when an OMVS shutdown is initiated. It neither
blocks Shutdown nor survives shutdown. Blocking and permanent processes
can also register to be informed when OMVS shutdown is initiated.
For more information on OMVS shutdown see
z/OS UNIX System Services Planning.
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.
Checkpointed permanent process attributes include the following:
- 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.
Non-checkpointable permanent process attributes include the following:
- semaphores
- shared library programs
- __map() shared memory blocks
- message queues
- memory mapped files
- all other UNIX System Services
resources
If any non-checkpointable resources are being used by a permanent
process, the shutdown request will fail.
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 defines the type of registration. The possible
values are listed below. These values are all mutually exclusive.
- 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 _SDR_BLOCKING and _SDR_PERMANENT registrations are restricted.
The invoker must meet one of the following criteria in order for
these two registration types to succeed:
- 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 defines the registration scope. The possible
values are listed below. The two values are mutually exclusive.
- regscope
- Definition
- _SDR_REGJOB
- All the processes in the Job are registered.
- _SDR_REGPROCESS
- Only the calling process is registered.
regoptions defines various options for the registered
process. The possible values are listed below. Multiple options
may be specified by or'ing the values together. The default behavior
for kernel calls issued by permanent processes while z/OS UNIX is
not up is to fail the request with errno set to EMVSERR and the reason
code (__errno2() value) set to JrKernelReady. Those kernel calls
which which do not return a return code will end with an EC6 abend
and reason code xxxx8039.
- 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())