PIDFILE(3) | Library Functions Manual | PIDFILE(3) |
pidfile
, pidfile_lock
,
pidfile_read
, pidfile_clean
—
#include <util.h>
int
pidfile
(const
char *path);
pid_t
pidfile_lock
(const
char *path);
pid_t
pidfile_read
(const
char *path);
int
pidfile_clean
(void);
pidfile
() and pidfile_lock
()
create and lock a file containing the process ID of the calling program. The
pid file can be used as a quick reference if the process needs to be sent a
signal. The pid file is truncated and removed automatically when the program
exits, unless the program receives a fatal signal.
If path is NULL
or a
plain basename (a name containing no directory components), the pid file is
created in the /var/run directory. The file name has
the form /var/run/basename.pid. The basename part is
either the value of path if it was not
NULL
, or the program name as returned by
getprogname(3)
otherwise.
If path is an absolute or relative path (i.e. it contains the ‘/’ character), the pid file is created in the provided location.
If called with a new path,
pidfile
() and pidfile_lock
()
will remove the old pid file.
The pid file is truncated, so these functions can be called multiple times and allow a child process to take over the lock.
pidfile_read
() will read the last pid file
created, or specified by path, and return the process
ID it contains.
pidfile_clean
() will
ftruncate(2),
close(2), and
unlink(2) the last opening pid
file if, and only if, the current process wrote it. This function should be
called if the program needs to call
_exit(2) (such as from a signal
handler) and needs to clean up the pid file.
pidfile
() and pidfile_clean
()
returns 0 on success and -1 on failure.
pidfile_lock
() returns 0 on success.
Otherwise, the process ID who owns the lock is returned and if that cannot
be derived then -1 is returned.
pidfile_read
() returns the process ID if
known, otherwise -1.
pidfile
() and pidfile_lock
()
functions will fail if:
EEXIST
]ENAMETOOLONG
]pidfile
() function call appeared in
NetBSD 1.5. Support for creating pid files in any
arbitrary path was added in NetBSD 6.0.
The pidfile_lock
(),
pidfile_read
(), and
pidfile_clean
() function calls appeared in
NetBSD 8.
pidfile
() and pidfile_lock
() use
atexit(3) to ensure the pid file
is cleaned at program exit. However, programs that use the
_exit(2) function (for example,
in signal handlers) will not trigger this behaviour and should call
pidfile_clean
(). Like-wise, if the program creates a
pid file before fork(2)ing a child
to take over, it should use the
_exit(2) function instead of
returning or using the exit(3)
function to ensure the pid file is not cleaned.
April 10, 2016 | NetBSD 9.0 |