| 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 |
|