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 -- 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);

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.

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.

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().

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

HISTORY
       The  functions  pidfile_open(),	pidfile_write(),  pidfile_close()  and
       pidfile_remove()	first appeared in FreeBSD 5.5.

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	14.3			 May 10, 2020			    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+14.3-RELEASE+and+Ports>

home | help