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  al-
       ready  running  daemon  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() function 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
       pidfile.

       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 pidfile and of the process that owns it.

RETURN VALUES
       The pidfile_open() function returns a valid pointer to a	 pidfh	struc-
       ture 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
			  pidfile,  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
			  pidfile, 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
			  pidfile_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
       specified 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  er-
       rors specified for the close(2),	fstat(2), write(2), and	unlink(2) sys-
       tem 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
       pidfile_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	15.0			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.0-RELEASE+and+Ports>

home | help