Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Daemon Launcher

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

KeyTypeDescription
redirect_stdio_to_nullBOOLIf TRUE, redirects standard input, output, and error to /dev/null.
programconst char *The program to run as a daemon, found in PATH as execvp() does.
...variadicAdditional 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

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 itself

clean_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

KeyTypeDescription
keep_fdintAn fd above stderr to keep open (a pipe that closes on the exec with O_CLOEXEC), or -1 for none.

Notes

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

KeyTypeDescription
firstunsigned intThe first fd to close.
lastunsigned intThe last fd to close, ~0U for all of them.

Notes

Example

close_fd_range(STDERR_FILENO + 1, ~0U);     // keep stdin, stdout and stderr

Linux 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

KeyTypeDescription
processfunction pointerEntry point invoked in the child. Receives the process name, work dir, domain dir and the cleanup callback.
process_nameconst char *Name of the process (used in /proc lookups and logs).
work_dirconst char *Working directory to chdir into before running.
domain_dirconst char *Domain-specific directory passed through to the child.
cleaning_fnfunction pointerCleanup callback invoked on shutdown. It can be NULL.

Returns

Returns 0 on normal shutdown, or a non-zero value on error.

Notes


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

KeyTypeDescription
process_nameconst 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 root

Notes

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

KeyTypeDescription
pathconst 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 pid

Notes

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

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

KeyTypeDescription
process_nameconst char *Target process name to match against /proc/*/comm (or /proc/*/cmdline).
cbfunction pointerCallback invoked for each matching process. Receives the opaque self, the resolved process name, and the PID.
selfvoid *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

KeyTypeDescription
setBOOLTRUE 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.