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