"Fossies" - the Fresh Open Source Software Archive

Member "sysvinit-2.99/doc/initctl" (21 Feb 2021, 4241 Bytes) of package /linux/misc/sysvinit-2.99.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "initctl": 2.98_vs_2.99.

    1 This document describes the communiction pipe set up by SysV init
    2 at /run/initctl. This named pipe allows programs with the proper
    3 permissions (typically programs run by root have read+write access to
    4 the pipe) to send signals to the init program (PID 1).
    5 
    6 The init manual page has, up until recently, simply stated
    7 that people wishing to understand how to send messages to init
    8 should read the init program's source code, but that is not usually practical.
    9 
   10 Messages sent to the pipe to talk to init must have a special format.
   11 This format is defined as a C structure and the technical break-down
   12 is presented here:
   13 
   14 /*
   15  *      Because of legacy interfaces, "runlevel" and "sleeptime"
   16  *      aren't in a separate struct in the union.
   17  *
   18  *      The weird sizes are because init expects the whole
   19  *      struct to be 384 bytes.
   20  */
   21 struct init_request {
   22         int     magic;                  /* Magic number                 */
   23         int     cmd;                    /* What kind of request         */
   24         int     runlevel;               /* Runlevel to change to        */
   25         int     sleeptime;              /* Time between TERM and KILL   */
   26         union {
   27                 struct init_request_bsd bsd;
   28                 char                    data[368];
   29         } i;
   30 };
   31 
   32 
   33 Let's go through the init_request structure one line at a time. The
   34 first variable, the "magic" number must be of the value 0x03091969.
   35 The init program then knows that only programs with root access which send
   36 this magic number are authorized to communicate with init.
   37 
   38 The cmd variable is a value in the range of 0-8 (currently). This cmd
   39 variable tells init what we want it to do. Here are the possible options:
   40 
   41 1 - Set the current runlevel, specified by the runlevel variable.
   42 2 - The power will fail soon (probably low battery) prepare to shutdown.
   43 3 - The power is failing, do shutdown immediately.
   44 4 - The power is okay, cancel shutdown.
   45 6 - Set an environment variable to a value to be specified in 
   46     the data variable of this structure.
   47 
   48 Other cmd options may be added to init later. For example, command values
   49 0, 5 and 7 are defined but currently not implemented.
   50 
   51 The runlevel variable will specify the runlevel to switch to (0-6).
   52 
   53 The sleeptime variable is to be used when we want to tell init to change
   54 the time spent waiting between sending SIGTERM and SIGKILL during the
   55 shutdown process. Changing this at run time is not yet implemented.
   56 
   57 The data variable (in the union) can be used to pass misc data which init
   58 might need to process our request. For example, when setting environment
   59 variables.
   60 
   61 When setting an environment variable through init's /run/initctl pipe,
   62 the data variable should have the format VARIABLE=VALUE. The string
   63 should be terminated with a NULL '\0' character.
   64 
   65 
   66 The following C code example shows how to send a set environment variable
   67 request to the init process using the /run/initctl pipe. This example
   68 is simplified and skips the error checking. A more comlpete example can be
   69 found in the shutdown.c program's init_setnv() function.
   70 
   71 
   72 struct init_request     request;           /* this is the structure defined above */
   73 int                     fd;                /* file descriptor for the pipe */
   74 
   75 memset(&request, 0, sizeof(request));      /* initialize structure */
   76 request.magic = 0x03091969;                /* this magic number must be included */
   77 request.cmd = 6;                           /* 6 is the command to set a variable */
   78 sprintf(request.data, "VARIABLE=VALUE");   /* set VARIABLE to VALUE  in init */
   79 if ((fd = open(INIT_FIFO, O_WRONLY)) >= 0) /* open pipe for writing */
   80 { 
   81     size_t s  = sizeof(request);           /* size of the structure to write */
   82     void *ptr = &request;                  /* temporary pointer */
   83     write(fd, ptr, s);                     /* send the structure to the pipe */
   84     close(fd);                             /* close the pipe when done */
   85 }
   86 
   87 
   88 
   89 Usually the /run/initctl pipe would only be used by low-level programs to
   90 request a power-related shutdown or change the runlevel, like telinit
   91 would do. Most of the time there is no need to talk to init directly, but
   92 this gives us an extenable approach so init can be taught how to learn
   93 more commands.
   94