Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
PIDFILE(3)		     Library Functions Manual		      PIDFILE(3)

NAME
     pidfile_open, pidfile_write, pidfile_close, pidfile_remove, pidfile_fileno,
     pidfile_signal -- library for PID files handling

LIBRARY
     System Utilities Library (libutil, -lutil)

SYNOPSIS
     #include <libutil.h>

     struct pidfh *
     pidfile_open(const char *path, mode_t mode, pid_t *pidptr);

     int
     pidfile_write(struct pidfh *pfh);

     int
     pidfile_close(struct pidfh *pfh);

     int
     pidfile_remove(struct pidfh *pfh);

     int
     pidfile_fileno(struct pidfh *pfh);

     int
     pidfile_signal(const char *path, int sig, pid_t *pidptr);

DESCRIPTION
     The  pidfile  family  of  functions allows daemons to handle PID files.  It
     uses flopen(3) to lock a pidfile and detect already running daemons.

     The pidfile_open() function opens (or creates) a file specified by the path
     argument and locks it.  If pidptr argument is not NULL and file can not  be
     locked,  the function will use it to store a PID of an already running dae-
     mon or -1 in case daemon did not write its PID yet.  The function does  not
     write  process'  PID into the file here, so it can be used before fork()ing
     and exit with a proper error message when needed.	If the path argument  is
     NULL,  /var/run/<progname>.pid file will be used.	The pidfile_open() func-
     tion sets the O_CLOEXEC close-on-exec flag when opening the pidfile.

     The pidfile_write() function writes process' PID into a  previously  opened
     file.   The  file is truncated before write, so calling the pidfile_write()
     function multiple times is supported.

     The pidfile_close() function closes a pidfile.  It  should  be  used  after
     daemon fork()s to start a child process.

     The pidfile_remove() function closes and removes a pidfile.

     The pidfile_fileno() function returns the file descriptor for the open pid-
     file.

     The  pidfile_signal() function looks for the pidfile specified by path, and
     if it exists and is locked, sends the signal specified by sig to the PID it
     contains.	If pidptr is not NULL, the PID that was found in the pidfile  is
     stored  in  the  location it points to.  Note that calling pidfile_signal()
     with sig set to zero is an effective way to verify the existence of a  pid-
     file and of the process that owns it.

RETURN VALUES
     The pidfile_open() function returns a valid pointer to a pidfh structure on
     success,  or  NULL  if  an error occurs.  If an error occurs, errno will be
     set.

     The pidfile_write(), pidfile_close(), and pidfile_remove() functions return
     the value 0 if successful; otherwise the  value  -1  is  returned	and  the
     global variable errno is set to indicate the error.

     The  pidfile_fileno()  function  returns the low-level file descriptor.  It
     returns -1 and sets errno if a NULL pidfh is specified, or if  the  pidfile
     is no longer open.

     The  pidfile_signal()  function  returns  0  if  it successfully signaled a
     process, and an appropriate errno value otherwise.

EXAMPLES
     The following example shows in which order these functions should be  used.
     Note  that  it  is  safe to pass NULL to pidfile_write(), pidfile_remove(),
     pidfile_close(), and pidfile_fileno() functions.

     struct pidfh *pfh;
     pid_t otherpid, childpid;

     pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
     if (pfh == NULL) {
	     if (errno == EEXIST) {
		     errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
			 (intmax_t)otherpid);
	     }
	     /* If we cannot create pidfile from other reasons, only warn. */
	     warn("Cannot open or create pidfile");
	     /*
	      * Even though pfh is NULL we can continue, as the other pidfile_*
	      * function can handle such situation by doing nothing except setting
	      * errno to EDOOFUS.
	      */
     }

     if (daemon(0, 0) == -1) {
	     warn("Cannot daemonize");
	     pidfile_remove(pfh);
	     exit(EXIT_FAILURE);
     }

     pidfile_write(pfh);

     for (;;) {
	     /* Do work. */
	     childpid = fork();
	     switch (childpid) {
	     case -1:
		     syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
		     break;
	     case 0:
		     pidfile_close(pfh);
		     /* Do child work. */
		     break;
	     default:
		     syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
		     break;
	     }
     }

     pidfile_remove(pfh);
     exit(EXIT_SUCCESS);

ERRORS
     The pidfile_open() function will fail if:

     [EEXIST]		Some process already holds the lock on	the  given  pid-
			file,  meaning	that  a  daemon  is already running.  If
			pidptr argument is not NULL the function will use it  to
			store  a  PID of an already running daemon or -1 in case
			daemon did not write its PID yet.

     [ENAMETOOLONG]	Specified pidfile's name is too long.

     [EINVAL]		Some process already holds the lock on	the  given  pid-
			file, but PID read from there is invalid.

     The  pidfile_open()  function  may  also  fail and set errno for any errors
     specified for the fstat(2), open(2), and read(2) calls.

     The pidfile_write() function will fail if:

     [EDOOFUS]		Improper function  use.   Probably  called  before  pid-
			file_open().

     The  pidfile_write()  function  may  also fail and set errno for any errors
     specified for the fstat(2), ftruncate(2), and write(2) calls.

     The pidfile_close() function may fail and set errno for any  errors  speci-
     fied for the close(2) and fstat(2) calls.

     The pidfile_remove() function will fail if:

     [EDOOFUS]		Improper  function  use.   Probably  called not from the
			process which made pidfile_write().

     The pidfile_remove() function may also fail and set errno	for  any  errors
     specified	for the close(2), fstat(2), write(2), and unlink(2) system calls
     and the flopen(3) library function.

     The pidfile_fileno() function will fail if:

     [EDOOFUS]		Improper function use.	Probably  called  not  from  the
			process which used pidfile_open().

     The pidfile_signal() function will fail if:

     [ENOENT]		The pidfile does not exist, or exists but is not locked.

     [EDOM]		The pidfile contains a negative number.

     The  pidfile_signal()  function  may  also fail and return any of the errno
     values specified for the pidfile_read() function  and  the  kill(2)  system
     call.

SEE ALSO
     kill(2), open(2), daemon(3), flopen(3)

HISTORY
     The  functions  pidfile_open(),  pidfile_write(), pidfile_close(), and pid-
     file_remove() first appeared in FreeBSD 5.5.  The pidfile_fileno() function
     was added in FreeBSD 9.1.	 The  pidfile_signal()	function  was  added  in
     FreeBSD 14.0.

AUTHORS
     The   pidfile  functionality  is  based  on  ideas  from  John-Mark  Gurney
     <jmg@FreeBSD.org>.

     The  code	and  manual  page   was   written   by	 Pawel	 Jakub	 Dawidek
     <pjd@FreeBSD.org>.

FreeBSD ports 15.quarterly	 August 2, 2025 		      PIDFILE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pidfile&sektion=3&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help