shutdown_system()

Shut down the system

Synopsis:

#include <sys/shutdown.h>

void shutdown_system( int type,
                      int flags );

Arguments:

type

The type of shutdown; one of the following:

• SHUTDOWN_PHOTON — exit from Photon
• SHUTDOWN_PHOTON_USER — exit from Photon (same as SHUTDOWN_PHOTON).
• SHUTDOWN_REBOOT — reboot the system.
• SHUTDOWN_SYSTEM — shut down the 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_VERBOSE — be verbose.
• FLAG_VERY_VERBOSE — be very verbose.
• FLAG_PHLOGIN — spawned from phlogin (not used in the default library).
• FLAG_PHOTON_REMOTE — remote Photon session.
• 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.

Library:

libshutdown.a

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

Description:

The shutdown_system() function exits from Photon, or reboots or shuts down the system, depending on the type argument. It tries to shut down Photon applications first, then Photon itself, followed by non-Photon processes.

You can customize this function by providing your own callouts to override those in the library:

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

The phshutdown and shutdown utilities use this library, providing their own callouts.

shutdown_classify() callout

ProcessClass_t shutdown_classify( ProcessInfo_t const *pip );

This callout determines whether an application is Photon- or console-based, based on the information provided in the structure that pip points to. The ProcessInfo_t structure is defined as follows:

typedef struct
{
    uint64_t start_time;
    pid_t pid;
    int8_t class;
    uint8_t padding[3];
    char *name;
} ProcessInfo_t;

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 shutdown_classify() callout should return one of the defined class types:

• CLASS_UNKNOWN
• CLASS_PHOTON_APP — a Photon application.
• CLASS_APP — a non-Photon application.
• CLASS_DAEMON — a server, resource manager, or driver.
• CLASS_FSYS — a filesystem.
• CLASS_DISPLAY — a display driver.

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.

Examples:

See the source code on our Foundry27 website, http://community.qnx.com/:

• Look for the source for the library and the shutdown utility in the project for the QNX Neutrino OS.
• Look for the source for phshutdown in the Graphics project.

Classification:

QNX Neutrino

See also:

phlogin, phlogin2, phshutdown, shutdown in the Utilities Reference