Turn a process into a well-behaved Unix daemon: detach, redirect stdio, write a pidfile, and optionally relaunch on crash.
Source code:
launch_daemon()¶
launch_daemon() runs a program as a detached daemon (a double fork, the
daemon in a session of its own) and returns the PID of the daemon once its
exec is done.
int launch_daemon(
BOOL redirect_stdio_to_null,
const char *program,
...
);Parameters
| Key | Type | Description |
|---|---|---|
redirect_stdio_to_null | BOOL | If TRUE, redirects standard input, output, and error to /dev/null. |
program | const char * | The program to run as a daemon, found in PATH as execvp() does. |
... | variadic | Additional arguments to pass to the program, terminated by NULL (at most 255 in all). |
Returns
The PID of the daemon, or -1, said on stderr, when the launch
failed: a fork(), setsid(), /dev/null or the execvp() failed, or
too many arguments.
Notes
It waits for the
execof the daemon, not for its end: the children tell it the daemon’s PID or their failure through a pipe that closes on the daemon’sexec(O_CLOEXEC), read to its end. The first child is reaped.The PID answered is the daemon’s:
kill(pid, SIGTERM)ends it.Up to 7.29.3 it answered the PID of the first child, which had already exited (a
kill()of it did nothing to the daemon) and was never reaped (a zombie per call). It read the pipe once without waiting, so anexecfailure was seen only when it came first. And the daemon kept the write end of the pipe open.The daemon starts with no signal blocked and every signal at its default but SIGHUP, which it ignores, and with no fd of the caller but stdin, stdout and stderr (
clean_child_before_exec()). Up to 7.29.3 it inherited the caller’s mask and ignores (a yuno’s: SIGTERM, SIGINT, SIGQUIT and the rest of itssignalfdset blocked) and every fd of the caller withoutO_CLOEXEC, and the first child left withexit(), which wrote out a second time what the caller had in its stdio buffers.A caller whose
SIGCHLDisSIG_IGN(or whose handler of it reaps) gets the PID too, and no error is said: the first child reaped by somebody else is not a failure.A caller with stdin or stdout closed is no different: the ends of the pipe are put above stderr. Before, they took fds 0 and 1, the daemon’s
/dev/nulltook the place of the write end, and anexecfailure went to/dev/null: the PID of a program never run was answered.
Example
pid_t pid = launch_daemon(TRUE, "telnet", "localhost", "3303", NULL);
if(pid < 0) {
return -1; // not launched, already said
}
// ... the telnet connects to a listener of the test ...
kill(pid, SIGKILL); // the daemon itselfclean_child_before_exec()¶
clean_child_before_exec() prepares a forked child for its exec: the
program starts with no signal blocked, every signal at its default, and no
fd open but stdin, stdout, stderr and keep_fd. It is what
launch_daemon(), pty_sync_spawn()
and the command of C_PTY do before their exec
(run_process2() and run_command() get
the same from posix_spawn()).
void clean_child_before_exec(int keep_fd);Parameters
| Key | Type | Description |
|---|---|---|
keep_fd | int | An fd above stderr to keep open (a pipe that closes on the exec with O_CLOEXEC), or -1 for none. |
Notes
A yuno keeps its signals blocked for its
signalfd, and a blocked or an ignored signal stays so acrossexec. An fd withoutO_CLOEXECstays open acrossexec. Without this, the program inherits both.A signal that cannot be set (SIGKILL, SIGSTOP, those the C library keeps for itself) is left. The fds are closed with
close_range(). On a kernel without it (before 5.9), the ones open, as/proc/self/fdlists them, and only without/procone by one up to the limit of open files. Before, that loop was the only way, and underLimitNOFILE=infinityit was millions ofclose()per program run.Call it only in the child, after
fork(): it changes the process it runs in. Nothing is logged: the child is about toexec.
Example
pid_t pid = fork();
if(pid == 0) {
clean_child_before_exec(-1);
execl("/bin/sh", "sh", "-c", command, (char *)NULL);
_exit(127);
}close_fd_range()¶
close_fd_range() closes every fd of [first, last] that is open: with
close_range(), or on a kernel without it (before 5.9) each one that
/proc/self/fd lists. It is what
clean_child_before_exec() uses, and what a
yuno started with --start uses to close everything it inherited.
void close_fd_range(unsigned int first, unsigned int last);Parameters
| Key | Type | Description |
|---|---|---|
first | unsigned int | The first fd to close. |
last | unsigned int | The last fd to close, ~0U for all of them. |
Notes
Only without
/procdoes it close one by one up to the limit of open files. Up to 7.29.3 that loop was the only way on a kernel withoutclose_range(): underLimitNOFILE=infinity(fs.nr_open, 4000000 with the package’s sysctl) it was four millionclose()for each program a yuno ran, and at each--start.Nothing is logged: a child about to
exec, or a daemon at its start, has nobody to tell.
Example
close_fd_range(STDERR_FILENO + 1, ~0U); // keep stdin, stdout and stderrLinux daemon supervisor¶
Declared in
ydaemon.h.
These entry points run a yuno under a parent “watcher” process that
relaunches the child on crash. They are only compiled on Linux
(#ifdef __linux__).
daemon_run()¶
daemon_run() starts the watcher / child supervision loop. The parent
process keeps running as a watcher that relaunches the child if it
dies. The child calls process(process_name, work_dir, domain_dir, cleaning_fn)
to do the actual work.
int daemon_run(
void (*process)(
const char *process_name,
const char *work_dir,
const char *domain_dir,
void (*cleaning_fn)(void)
),
const char *process_name,
const char *work_dir,
const char *domain_dir,
void (*cleaning_fn)(void)
);Parameters
| Key | Type | Description |
|---|---|---|
process | function pointer | Entry point invoked in the child. Receives the process name, work dir, domain dir and the cleanup callback. |
process_name | const char * | Name of the process (used in /proc lookups and logs). |
work_dir | const char * | Working directory to chdir into before running. |
domain_dir | const char * | Domain-specific directory passed through to the child. |
cleaning_fn | function pointer | Cleanup callback invoked on shutdown. It can be NULL. |
Returns
Returns 0 on normal shutdown, or a non-zero value on error.
Notes
The watcher process relaunches the child each time it exits abnormally: 2 s after its end the first time. When each new child ends within 60 s of its start, the wait doubles, up to 60 s, and a child that lived longer sets it back to 2 s (Entry point §4.3). See
get_relaunch_times()to inspect how many relaunches happened so far.Use
daemon_shutdown()from another process (or the child itself) to terminate both watcher and child cleanly.A SIGQUIT to the watcher is the stop: its child is not relaunched, and the watcher passes the SIGQUIT to the child it waits for. So a stop that comes while the watcher forks a child, which the sender did not know, stops that child too. Up to 7.29.3 only a stop that came before the watcher looked at it after the fork reached the child. A later one reached only the watcher, and
--stopkilled the child with SIGKILL 10 s later.yuneta_entry_point()blocks the yuno’s signals (get_yuno_signal_set()) before it reads the arguments. With--startthey stay blocked, so a SIGQUIT that comes beforedaemon_run()sets the watcher’s signals is the stop: nothing is launched. Up to 7.29.3 a yuno started by hand or by a systemd unit ended then with a core dump. Without--startthe signals are given back once the arguments are read.
daemon_shutdown()¶
daemon_shutdown() requests an orderly shutdown of a running daemon
by process name. Every process of that name started as it gets SIGQUIT, the
watchers first. The name is the base name
of argv[0] in /proc/<pid>/cmdline. A script of the same name has its
interpreter there and is not one. A daemon whose binary was renamed still
is one. Another user’s process is taken only when the caller is root. A zombie of the
name is dead and is not counted, nor is an EPERM on one a failure. The list has no fixed size, so look-alikes
of the name, which anybody can start, cannot push the real ones out of it.
A watcher notes the SIGQUIT and does not relaunch its child, whatever its end.
The child stops in order and exits 0, and its watcher exits with it.
They are given 10 s to be gone. Then the name is scanned again, and what is
left is killed with SIGKILL, said on stdout and in syslog (print_error()).
Each kill() is checked.
int daemon_shutdown(const char *process_name);Parameters
| Key | Type | Description |
|---|---|---|
process_name | const char * | Name of the running daemon process to stop. |
Returns
0 when every process of the name is gone or killed. -1 when the function
fails to signal one (EPERM), when it fails to read the cmdline of one for a
reason other than its end (so it is not known whether it is the daemon), when
the list fails to grow (no memory), or when nothing of the name is the
caller’s and the name can run as another user. That is, the processes of the name are
all another user’s (7.30.20+), or /proc is mounted hidepid=1 and the name
of other users’ processes cannot be read (7.30.21+. In 7.30.20, it returned
0, whether the daemon ran or not). Each one is said on stdout and in
syslog, and not waited for. For example, --stop as a user, with /proc
mounted hidepid=1, returns -1 and prints:
--stop: yuneta_agent: not known if it runs: the name of 250 process(es) of other users cannot be read (pid 1: /proc mounted with hidepid?): run --stop as rootNotes
No-op if no process with the given name is found. The calling process is
never signaled. It returns once every process is gone (a zombie counts as
gone), so a start that follows does not meet the old one. Up to 7.25.21 each
process was killed 1 s after its own SIGQUIT, one after the other: an agent
had one second for its orderly shutdown. Up to 7.25.22 it returned nothing:
an EPERM waited 10 s, said “killed (SIGKILL)” and the --stop exited 0.
And a child that crashed in its shutdown was relaunched by its watcher and
left alive once the watcher was killed.
Example
if(arguments.stop) {
return daemon_shutdown(APP_NAME) < 0? 1 : 0; // returns when the daemon is gone
}get_watcher_pid()¶
get_watcher_pid() returns the PID of the watcher (parent) process
that is supervising the current child, or 0 if the caller is not
running under a watcher.
int get_watcher_pid(void);Returns
The watcher process PID, or 0 if the current process has no watcher.
daemon_set_pid_file()¶
daemon_set_pid_file() names the file where, under --start, the pid of
the WATCHER is written -- by the process that was started, before it exits,
which is when a systemd unit of Type=forking reads its PIDFile=. The
entry point calls it with the value of --pid-file. A yuno has nothing else
to do for it.
void daemon_set_pid_file(const char *path);Parameters
| Key | Type | Description |
|---|---|---|
path | const char * | The file. It must live until daemon_run() (an argv string does). NULL or empty: no file. |
Example
/yuneta/agent/yuneta_agent --config-file=/yuneta/agent/yuneta_agent.json \
--start --pid-file=/run/yuneta_agent/yuneta_agent.pid
cat /run/yuneta_agent/yuneta_agent.pid # the watcher, the unit's main pidNotes
The file is written aside (<file>.tmp) and renamed, so systemd reads it
whole or not at all. A failure to write it is printed and sent to syslog. The
daemon goes on. The unit that uses it is described in
the entry point chapter.
get_relaunch_times()¶
get_relaunch_times() returns the number of times the watcher has
relaunched its child process since the daemon was started. Useful for
diagnostics and stats endpoints.
int get_relaunch_times(void);Returns
The relaunch counter (0 on the first run, incremented on each restart).
get_yuno_signal_set()¶
get_yuno_signal_set() fills set with the signals a yuno reads from its
signalfd (C_YUNO): SIGPIPE, SIGTERM, SIGALRM, SIGQUIT, SIGINT, SIGUSR1
and SIGUSR2. It is the one definition of that set: C_YUNO blocks it for
its signalfd, the watcher blocks it around each fork() of a child, and
yuneta_entry_point() blocks it from the start of a yuno.
void get_yuno_signal_set(sigset_t *set);Parameters
| Key | Type | Description |
|---|---|---|
set | sigset_t * | The set to fill. What it had is replaced. |
Example
sigset_t yuno_signals;
get_yuno_signal_set(&yuno_signals);
sigprocmask(SIG_BLOCK, &yuno_signals, NULL); // pending until the signalfd reads them
int sfd = signalfd(-1, &yuno_signals, SFD_NONBLOCK|SFD_CLOEXEC);search_process()¶
search_process() walks /proc looking for running processes whose
name matches process_name and invokes a callback for each match.
int search_process(
const char *process_name,
void (*cb)(void *self, const char *name, pid_t pid),
void *self
);Parameters
| Key | Type | Description |
|---|---|---|
process_name | const char * | Target process name to match against /proc/*/comm (or /proc/*/cmdline). |
cb | function pointer | Callback invoked for each matching process. Receives the opaque self, the resolved process name, and the PID. |
self | void * | Opaque pointer forwarded to the callback. |
Returns
Returns the number of matches found, or a negative value on error.
Notes
Used internally by daemon_shutdown() to locate
the watcher process to signal.
daemon_set_debug_mode()¶
daemon_set_debug_mode() enables or disables daemon debug mode for
the current process. When debug mode is on the supervisor emits extra
tracing and can skip behaviors that will make debugging harder (for
example, preventing auto-relaunch on crash).
int daemon_set_debug_mode(BOOL set);Parameters
| Key | Type | Description |
|---|---|---|
set | BOOL | TRUE to enable debug mode, FALSE to disable it. |
Returns
Returns 0 on success.
daemon_get_debug_mode()¶
daemon_get_debug_mode() returns whether the daemon is currently
running in debug mode.
BOOL daemon_get_debug_mode(void);Returns
TRUE if debug mode is enabled, FALSE otherwise.