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 August 22, 2005
  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 flock 2
  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 with the
  62 .Xr flock 2
  63 system call.
  64 If a file can not be locked, a PID of an already running daemon is returned in
  65 the
  66 .Fa pidptr
  67 argument (if it is not
  68 .Dv NULL ) .
  69 The function does not write process' PID into the file here, so it can be
  70 used before
  71 .Fn fork Ns ing
  72 and exit with a proper error message when needed.
  73 If the
  74 .Fa path
  75 argument is
  76 .Dv NULL ,
  77 .Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
  78 file will be used.
  79 .Pp
  80 The
  81 .Fn pidfile_write
  82 function writes process' PID into a previously opened file.
  83 .Pp
  84 The
  85 .Fn pidfile_close
  86 function closes a pidfile.
  87 It should be used after daemon
  88 .Fn fork Ns s
  89 to start a child process.
  90 .Pp
  91 The
  92 .Fn pidfile_remove
  93 function closes and removes a pidfile.
  94 .Sh RETURN VALUES
  95 The
  96 .Fn pidfile_open
  97 function returns a valid pointer to a
  98 .Vt pidfh
  99 structure on success, or
 100 .Dv NULL
 101 if an error occurs.
 102 If an error occurs,
 103 .Va errno
 104 will be set.
 105 .Rv -std pidfile_write pidfile_close pidfile_remove
 106 .Sh EXAMPLES
 107 The following example shows in which order these functions should be used.
 108 Note that it is safe to pass
 109 .Dv NULL
 110 to
 111 .Fn pidfile_write ,
 112 .Fn pidfile_remove
 113 and
 114 .Fn pidfile_close
 115 functions.
 116 .Bd -literal
 117 struct pidfh *pfh;
 118 pid_t otherpid, childpid;
 119
 120 pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
 121 if (pfh == NULL) {
 122         if (errno == EEXIST) {
 123                 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
 124                     (intmax_t)otherpid);
 125         }
 126         /* If we cannot create pidfile from other reasons, only warn. */
 127         warn("Cannot open or create pidfile");
 128 }
 129
 130 if (daemon(0, 0) == -1) {
 131         warn("Cannot daemonize");
 132         pidfile_remove(pfh);
 133         exit(EXIT_FAILURE);
 134 }
 135
 136 pidfile_write(pfh);
 137
 138 for (;;) {
 139         /* Do work. */
 140         childpid = fork();
 141         switch (childpid) {
 142         case -1:
 143                 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
 144                 break;
 145         case 0:
 146                 pidfile_close(pfh);
 147                 /* Do child work. */
 148                 break;
 149         default:
 150                 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
 151                 break;
 152         }
 153 }
 154
 155 pidfile_remove(pfh);
 156 exit(EXIT_SUCCESS);
 157 .Ed
 158 .Sh ERRORS
 159 The
 160 .Fn pidfile_open
 161 function will fail if:
 162 .Bl -tag -width Er
 163 .It Bq Er EEXIST
 164 Some process already holds the lock on the given pidfile, meaning that a
 165 daemon is already running.
 166 .It Bq Er ENAMETOOLONG
 167 Specified pidfile's name is too long.
 168 .It Bq Er EINVAL
 169 Some process already holds the lock on the given pidfile, but PID read
 170 from there is invalid.
 171 .It Bq Er EAGAIN
 172 Some process already holds the lock on the given pidfile, but the file
 173 is truncated.
 174 Most likely, the existing daemon is writing new PID into
 175 the file.
 176 .El
 177 .Pp
 178 The
 179 .Fn pidfile_open
 180 function may also fail and set
 181 .Va errno
 182 for any errors specified for the
 183 .Xr fstat 2 ,
 184 .Xr open 2 ,
 185 and
 186 .Xr read 2
 187 calls.
 188 .Pp
 189 The
 190 .Fn pidfile_write
 191 function will fail if:
 192 .Bl -tag -width Er
 193 .It Bq Er EDOOFUS
 194 Improper function use.
 195 Probably called before
 196 .Fn pidfile_open .
 197 .El
 198 .Pp
 199 The
 200 .Fn pidfile_write
 201 function may also fail and set
 202 .Va errno
 203 for any errors specified for the
 204 .Xr fstat 2 ,
 205 .Xr ftruncate 2 ,
 206 and
 207 .Xr write 2
 208 calls.
 209 .Pp
 210 The
 211 .Fn pidfile_close
 212 function may fail and set
 213 .Va errno
 214 for any errors specified for the
 215 .Xr close 2
 216 and
 217 .Xr fstat 2
 218 calls.
 219 .Pp
 220 The
 221 .Fn pidfile_remove
 222 function will fail if:
 223 .Bl -tag -width Er
 224 .It Bq Er EDOOFUS
 225 Improper function use.
 226 Probably called not from the process which made
 227 .Fn pidfile_write .
 228 .El
 229 .Pp
 230 The
 231 .Fn pidfile_remove
 232 function may also fail and set
 233 .Va errno
 234 for any errors specified for the
 235 .Xr close 2 ,
 236 .Xr flock 2 ,
 237 .Xr fstat 2 ,
 238 .Xr write 2 ,
 239 and
 240 .Xr unlink 2
 241 calls.
 242 .Sh SEE ALSO
 243 .Xr flock 2 ,
 244 .Xr open 2 ,
 245 .Xr daemon 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 .