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: src/lib/libutil/pidfile.3,v 1.5 2006/03/04 15:20:28 keramida Exp $
  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 .El
 172 .Pp
 173 The
 174 .Fn pidfile_open
 175 function may also fail and set
 176 .Va errno
 177 for any errors specified for the
 178 .Xr fstat 2 ,
 179 .Xr open 2 ,
 180 and
 181 .Xr read 2
 182 calls.
 183 .Pp
 184 The
 185 .Fn pidfile_write
 186 function will fail if:
 187 .Bl -tag -width Er
 188 .It Bq Er EDOOFUS
 189 Improper function use.
 190 Probably called before
 191 .Fn pidfile_open .
 192 .El
 193 .Pp
 194 The
 195 .Fn pidfile_write
 196 function may also fail and set
 197 .Va errno
 198 for any errors specified for the
 199 .Xr fstat 2 ,
 200 .Xr ftruncate 2 ,
 201 and
 202 .Xr write 2
 203 calls.
 204 .Pp
 205 The
 206 .Fn pidfile_close
 207 function may fail and set
 208 .Va errno
 209 for any errors specified for the
 210 .Xr close 2
 211 and
 212 .Xr fstat 2
 213 calls.
 214 .Pp
 215 The
 216 .Fn pidfile_remove
 217 function will fail if:
 218 .Bl -tag -width Er
 219 .It Bq Er EDOOFUS
 220 Improper function use.
 221 Probably called not from the process which made
 222 .Fn pidfile_write .
 223 .El
 224 .Pp
 225 The
 226 .Fn pidfile_remove
 227 function may also fail and set
 228 .Va errno
 229 for any errors specified for the
 230 .Xr close 2 ,
 231 .Xr flock 2 ,
 232 .Xr fstat 2 ,
 233 .Xr write 2 ,
 234 and
 235 .Xr unlink 2
 236 calls.
 237 .Sh SEE ALSO
 238 .Xr flock 2 ,
 239 .Xr open 2 ,
 240 .Xr daemon 3
 241 .Sh AUTHORS
 242 .An -nosplit
 243 The
 244 .Nm pidfile
 245 functionality is based on ideas from
 246 .An John-Mark Gurney Aq jmg@FreeBSD.org .
 247 .Pp
 248 The code and manual page was written by
 249 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .