shutdown_system(), shutdown_system_with_reason()

#include <sys/shutdown.h>

void shutdown_system( int type,
                      int flags );

void shutdown_system_with_reason( int type,
                                  int flags,
                                  char *reason );

Arguments:

type

The type of shutdown; one of the following:

• SHUTDOWN_REBOOT — do a cold reboot.
• SHUTDOWN_SYSTEM — power off the system in such a way as to maintain the realtime clock.
• SHUTDOWN_KILLSWITCH — usually the same as SHUTDOWN_SYSTEM, but is used in cases where SHUTDOWN_SYSTEM doesn't actually power off the system. The realtime clock isn't maintained.
• SHUTDOWN_WARMREBOOT — do a warm reboot, if possible.
• SHUTDOWN_SHELFMODE — used for specific hardware that leaks power for a normal SHUTDOWN_SYSTEM.

flags

Zero or more of the following bits:

• FLAG_FAST — do a “fast” shutdown.
• FLAG_DEBUG — debug mode; don't actually shut down.
• FLAG_REVERSE_ORDER — kill processes in the reverse of the order in which they were created (i.e., kill the newest one first).
• FLAG_VERBOSE — be verbose.
• FLAG_VERY_VERBOSE — be very verbose.
• FLAG_NONROOT — ignore root privileges (not used in the default library).
• FLAG_UNATTENDED — don't ask for options (not used in the default library).
• FLAG_NO_DAEMON — don't daemonize the process.

reason

(shutdown_system_with_reason() only) A string that describes why the system is being shut down.

Library:

libshutdown.a

Use the -l shutdown option to qcc to link against this library.

Description:

The shutdown_system() function reboots or shuts down the system. In order to use this function, your process needs to have these abilities enabled:

• PROCMGR_AID_PRIORITY
• PROCMGR_AID_REBOOT
• PROCMGR_AID_SIGNAL

For more information, see procmgr_ability().

Depending on the type argument, shutdown_system() does the following:

1. (QNX Neutrino 7.0 or later) It tries to call a preshutdown function from a board-specific DLL that you can provide. You can use the BOARD_SHUTDOWN_DLL environment variable to specify the name of this DLL; if you don't specify the full path, the DLL must be in one of the directories that dlopen() searches. For example, you could do the following on the command line:

   export BOARD_SHUTDOWN_DLL=/some/path/my_shutdown_dll.so

   If you don't set the environment variable, shutdown_system() tries to open shutdown-hardware.so, where hardware is the value of the machine member of the utsname structure obtained from uname(). If you provide this DLL, it must be in one of the directories that dlopen() searches.

   The synopsis of the preshutdown function is as follows:

   void board_pre_shutdown( int type );

   The argument is the type argument passed to shutdown_system().

2. The shutdown_system() function shuts down any processes, in a reasonable order. In general terms, it determines the class of each process listed under /proc (either based on the process's name or the class returned by the shutdown_classify() callout—see below), sorts the processes by class, and then does the following for each process:
   1. It sends a SIGTERM signal to the process.
   2. (QNX Neutrino 6.6 or later) It sends a SIGCONT signal, in case the process was stopped.
   3. It waits for a period of time. If the SIGKILL_TIMEOUT environment variable is defined, its value is used as the number of milliseconds to wait. Otherwise, the time depends on the class of the application (reduced if you specify the FLAG_FAST flag).
   4. It sends a SIGKILL signal to the process if it still exists and is in the CLASS_UNKNOWN, CLASS_GRAPHICAL_APP, or CLASS_APP class.

   The interval between the SIGTERM and SIGKILL signals allows processes that have elected to catch the SIGTERM signal to perform any cleanup they need to do before the system is rebooted. The SIGCONT allows a stopped process to be terminated by the queued SIGTERM or the subsequent SIGKILL.

3. (QNX Neutrino 7.0 or later) The shutdown_system() function tries to call a board-specific shutdown function from the same DLL as board_pre_shutdown(). The synopsis of the function is as follows:

   void board_shutdown( int type );

   The argument is the type argument passed to shutdown_system(). You can use this function to shut down or reboot the board, depending on the type argument.

(QNX Neutrino 7.0 or later) The shutdown_system_with_reason() function is similar to shutdown_system(), but it first saves the given reason by loading a user-provided, board-specific DLL called shutdown_nvram.so, and then calling a function in the DLL:

void save_reset_info_to_nv( int type, char *reason );

This function should store the information in stable storage for later retrieval.

You can customize shutdown_system() by providing your own callouts to override those in the library (which is what the shutdown utility does):

• shutdown_classify()
• shutdown_display()
• shutdown_done()
• shutdown_error()
• shutdown_process()
• shutdown_progress()
• shutdown_prompt()

You can define your callouts in the same file as your call to shutdown_system() or put them in a library that you link against before libshutdown.a.

shutdown_classify() callout

ProcessClass_t shutdown_classify( ProcessInfo_t const *pip );

This callout determines the class of an application, based on the information provided in the structure that pip points to. The shutdown_system() function recognizes some applications by their name or other information, and calls shutdown_classify() to determine the type of applications that it doesn't recognize.

The ProcessInfo_t structure includes various fields, but only the following are set when this callout is invoked:

pid_t pid

The process ID.

char *name

The name of the process.

The shutdown_classify() callout should return one of the defined class types:

• CLASS_UNKNOWN
• CLASS_GRAPHICAL_APP — a graphical application.
• CLASS_APP — a non-graphical application.
• CLASS_DAEMON — a server, resource manager, or driver.
• CLASS_FSYS — a filesystem.
• CLASS_DISPLAY — a display driver.
• CLASS_NR — no reset. The shutdown library doesn't send a SIGTERM to processes in this class.

The default stub unconditionally returns CLASS_UNKNOWN.

shutdown_display() callout

void shutdown_display( int type,
                       DisplayData_t const *display);

This callout can display the name of a process or class of processes being shut down, depending on the type argument:

• DISPLAY_CLASS — a new class of processes was encountered.
• DISPLAY_PROC — a new process was encountered.

The default stub does nothing.

The DisplayData_t structure provides information about what's currently being shut down. It's defined as follows:

typedef union
{
    int proc_class;         /* use for DISPLAY_CLASS */
    char const *proc_name;  /* use for DISPLAY_PROC */
} DisplayData_t;

The proc_class member is one of the class types that shutdown_classify() returns.

shutdown_done() callout

void shutdown_done( int type );

This callout is called before shutting down the display processes, but after shutting down the rest. The type argument is the typed passed to shutdown_system().

The default stub does nothing.

shutdown_error() callout

void shutdown_error( char const *msg );

The library invokes this callout if an error has occurred; the library exits, indicating a failure, after issuing this callout. The default stub does nothing.

shutdown_process() callout

void shutdown_process(void);

This callout is called to process intermediate events during the shutdown. The default stub does nothing.

shutdown_progress() callout

void shutdown_progress( int done,
                        int total );

This callout is called to display the progress being made at shutting down. The done argument indicates the number of processes already shut down, out of the given total.

The default stub does nothing.

shutdown_prompt() callout

int shutdown_prompt(char const *name,pid_t pid);

This callout is called to deal with a process that isn't responding. It should return one of the following to indicate to the library how to deal with the errant process:

• PROMPT_KILL — immediately raise a SIGKILL signal for the process.
• PROMPT_WAIT — continue to wait for the pending SIGTERM.
• PROMPT_SKIP — ignore this process, and shut down other processes.
• PROMPT_CANCEL — abort the shutdown in progress.

The default stub returns PROMPT_SKIP.

Classification:

QNX Neutrino