lib/libutil/pidfile.3

   1 .\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd October 20, 2008
  28 .Dt PIDFILE 3
  29 .Os
  30 .Sh NAME
  31 .Nm pidfile_open ,
  32 .Nm pidfile_write ,
  33 .Nm pidfile_close ,
  34 .Nm pidfile_remove
  35 .Nd "library for PID files handling"
  36 .Sh LIBRARY
  37 .Lb libutil
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In libutil.h
  41 .Ft "struct pidfh *"
  42 .Fn pidfile_open "const char *path" "mode_t mode" "pid_t *pidptr"
  43 .Ft int
  44 .Fn pidfile_write "struct pidfh *pfh"
  45 .Ft int
  46 .Fn pidfile_close "struct pidfh *pfh"
  47 .Ft int
  48 .Fn pidfile_remove "struct pidfh *pfh"
  49 .Sh DESCRIPTION
  50 The
  51 .Nm pidfile
  52 family of functions allows daemons to handle PID files.
  53 It uses
  54 .Xr flopen 3
  55 to lock a pidfile and detect already running daemons.
  56 .Pp
  57 The
  58 .Fn pidfile_open
  59 function opens (or creates) a file specified by the
  60 .Fa path
  61 argument and locks it.
  62 If a file can not be locked, a PID of an already running daemon is returned in
  63 the
  64 .Fa pidptr
  65 argument (if it is not
  66 .Dv NULL ) .
  67 The function does not write process' PID into the file here, so it can be
  68 used before
  69 .Fn fork Ns ing
  70 and exit with a proper error message when needed.
  71 If the
  72 .Fa path
  73 argument is
  74 .Dv NULL ,
  75 .Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
  76 file will be used.
  77 .Pp
  78 The
  79 .Fn pidfile_write
  80 function writes process' PID into a previously opened file.
  81 .Pp
  82 The
  83 .Fn pidfile_close
  84 function closes a pidfile.
  85 It should be used after daemon
  86 .Fn fork Ns s
  87 to start a child process.
  88 .Pp
  89 The
  90 .Fn pidfile_remove
  91 function closes and removes a pidfile.
  92 .Sh RETURN VALUES
  93 The
  94 .Fn pidfile_open
  95 function returns a valid pointer to a
  96 .Vt pidfh
  97 structure on success, or
  98 .Dv NULL
  99 if an error occurs.
 100 If an error occurs,
 101 .Va errno
 102 will be set.
 103 .Pp
 104 .Rv -std pidfile_write pidfile_close pidfile_remove
 105 .Sh EXAMPLES
 106 The following example shows in which order these functions should be used.
 107 Note that it is safe to pass
 108 .Dv NULL
 109 to
 110 .Fn pidfile_write ,
 111 .Fn pidfile_remove
 112 and
 113 .Fn pidfile_close
 114 functions.
 115 .Bd -literal
 116 struct pidfh *pfh;
 117 pid_t otherpid, childpid;
 118
 119 pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
 120 if (pfh == NULL) {
 121         if (errno == EEXIST) {
 122                 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
 123                     (intmax_t)otherpid);
 124         }
 125         /* If we cannot create pidfile from other reasons, only warn. */
 126         warn("Cannot open or create pidfile");
 127 }
 128
 129 if (daemon(0, 0) == -1) {
 130         warn("Cannot daemonize");
 131         pidfile_remove(pfh);
 132         exit(EXIT_FAILURE);
 133 }
 134
 135 pidfile_write(pfh);
 136
 137 for (;;) {
 138         /* Do work. */
 139         childpid = fork();
 140         switch (childpid) {
 141         case -1:
 142                 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
 143                 break;
 144         case 0:
 145                 pidfile_close(pfh);
 146                 /* Do child work. */
 147                 break;
 148         default:
 149                 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
 150                 break;
 151         }
 152 }
 153
 154 pidfile_remove(pfh);
 155 exit(EXIT_SUCCESS);
 156 .Ed
 157 .Sh ERRORS
 158 The
 159 .Fn pidfile_open
 160 function will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er EEXIST
 163 Some process already holds the lock on the given pidfile, meaning that a
 164 daemon is already running.
 165 .It Bq Er ENAMETOOLONG
 166 Specified pidfile's name is too long.
 167 .It Bq Er EINVAL
 168 Some process already holds the lock on the given pidfile, but PID read
 169 from there is invalid.
 170 .It Bq Er EAGAIN
 171 Some process already holds the lock on the given pidfile, but the file
 172 is truncated.
 173 Most likely, the existing daemon is writing new PID into
 174 the file.
 175 .El
 176 .Pp
 177 The
 178 .Fn pidfile_open
 179 function may also fail and set
 180 .Va errno
 181 for any errors specified for the
 182 .Xr fstat 2 ,
 183 .Xr open 2 ,
 184 and
 185 .Xr read 2
 186 calls.
 187 .Pp
 188 The
 189 .Fn pidfile_write
 190 function will fail if:
 191 .Bl -tag -width Er
 192 .It Bq Er EDOOFUS
 193 Improper function use.
 194 Probably called before
 195 .Fn pidfile_open .
 196 .El
 197 .Pp
 198 The
 199 .Fn pidfile_write
 200 function may also fail and set
 201 .Va errno
 202 for any errors specified for the
 203 .Xr fstat 2 ,
 204 .Xr ftruncate 2 ,
 205 and
 206 .Xr write 2
 207 calls.
 208 .Pp
 209 The
 210 .Fn pidfile_close
 211 function may fail and set
 212 .Va errno
 213 for any errors specified for the
 214 .Xr close 2
 215 and
 216 .Xr fstat 2
 217 calls.
 218 .Pp
 219 The
 220 .Fn pidfile_remove
 221 function will fail if:
 222 .Bl -tag -width Er
 223 .It Bq Er EDOOFUS
 224 Improper function use.
 225 Probably called not from the process which made
 226 .Fn pidfile_write .
 227 .El
 228 .Pp
 229 The
 230 .Fn pidfile_remove
 231 function may also fail and set
 232 .Va errno
 233 for any errors specified for the
 234 .Xr close 2 ,
 235 .Xr fstat 2 ,
 236 .Xr write 2 ,
 237 and
 238 .Xr unlink 2
 239 system calls and the
 240 .Xr flopen 3
 241 library function.
 242 .Sh SEE ALSO
 243 .Xr open 2 ,
 244 .Xr daemon 3 ,
 245 .Xr flopen 3
 246 .Sh AUTHORS
 247 .An -nosplit
 248 The
 249 .Nm pidfile
 250 functionality is based on ideas from
 251 .An John-Mark Gurney Aq jmg@FreeBSD.org .
 252 .Pp
 253 The code and manual page was written by
 254 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .