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 .Ft int
  50 .Fn pidfile_fileno "struct pidfh *pfh"
  51 .Sh DESCRIPTION
  52 The
  53 .Nm pidfile
  54 family of functions allows daemons to handle PID files.
  55 It uses
  56 .Xr flopen 3
  57 to lock a pidfile and detect already running daemons.
  58 .Pp
  59 The
  60 .Fn pidfile_open
  61 function opens (or creates) a file specified by the
  62 .Fa path
  63 argument and locks it.
  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 .Pp
  95 The
  96 .Fn pidfile_fileno
  97 function returns the file descriptor for the open pid file.
  98 .Sh RETURN VALUES
  99 The
 100 .Fn pidfile_open
 101 function returns a valid pointer to a
 102 .Vt pidfh
 103 structure on success, or
 104 .Dv NULL
 105 if an error occurs.
 106 If an error occurs,
 107 .Va errno
 108 will be set.
 109 .Pp
 110 .Rv -std pidfile_write pidfile_close pidfile_remove
 111 .Pp
 112 The
 113 .Fn pidfile_fileno
 114 function returns the low-level file descriptor.
 115 It returns -1 and sets
 116 .Va errno
 117 if a NULL
 118 .Vt pidfh
 119 is specified, or if the pidfile is no longer open.
 120 .Sh EXAMPLES
 121 The following example shows in which order these functions should be used.
 122 Note that it is safe to pass
 123 .Dv NULL
 124 to
 125 .Fn pidfile_write ,
 126 .Fn pidfile_remove ,
 127 .Fn pidfile_close
 128 and
 129 .Fn pidfile_fileno
 130 functions.
 131 .Bd -literal
 132 struct pidfh *pfh;
 133 pid_t otherpid, childpid;
 134
 135 pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
 136 if (pfh == NULL) {
 137         if (errno == EEXIST) {
 138                 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
 139                     (intmax_t)otherpid);
 140         }
 141         /* If we cannot create pidfile from other reasons, only warn. */
 142         warn("Cannot open or create pidfile");
 143 }
 144
 145 if (daemon(0, 0) == -1) {
 146         warn("Cannot daemonize");
 147         pidfile_remove(pfh);
 148         exit(EXIT_FAILURE);
 149 }
 150
 151 pidfile_write(pfh);
 152
 153 for (;;) {
 154         /* Do work. */
 155         childpid = fork();
 156         switch (childpid) {
 157         case -1:
 158                 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
 159                 break;
 160         case 0:
 161                 pidfile_close(pfh);
 162                 /* Do child work. */
 163                 break;
 164         default:
 165                 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
 166                 break;
 167         }
 168 }
 169
 170 pidfile_remove(pfh);
 171 exit(EXIT_SUCCESS);
 172 .Ed
 173 .Sh ERRORS
 174 The
 175 .Fn pidfile_open
 176 function will fail if:
 177 .Bl -tag -width Er
 178 .It Bq Er EEXIST
 179 Some process already holds the lock on the given pidfile, meaning that a
 180 daemon is already running.
 181 .It Bq Er ENAMETOOLONG
 182 Specified pidfile's name is too long.
 183 .It Bq Er EINVAL
 184 Some process already holds the lock on the given pidfile, but PID read
 185 from there is invalid.
 186 .It Bq Er EAGAIN
 187 Some process already holds the lock on the given pidfile, but the file
 188 is truncated.
 189 Most likely, the existing daemon is writing new PID into
 190 the file.
 191 .El
 192 .Pp
 193 The
 194 .Fn pidfile_open
 195 function may also fail and set
 196 .Va errno
 197 for any errors specified for the
 198 .Xr fstat 2 ,
 199 .Xr open 2 ,
 200 and
 201 .Xr read 2
 202 calls.
 203 .Pp
 204 The
 205 .Fn pidfile_write
 206 function will fail if:
 207 .Bl -tag -width Er
 208 .It Bq Er EDOOFUS
 209 Improper function use.
 210 Probably called before
 211 .Fn pidfile_open .
 212 .El
 213 .Pp
 214 The
 215 .Fn pidfile_write
 216 function may also fail and set
 217 .Va errno
 218 for any errors specified for the
 219 .Xr fstat 2 ,
 220 .Xr ftruncate 2 ,
 221 and
 222 .Xr write 2
 223 calls.
 224 .Pp
 225 The
 226 .Fn pidfile_close
 227 function may fail and set
 228 .Va errno
 229 for any errors specified for the
 230 .Xr close 2
 231 and
 232 .Xr fstat 2
 233 calls.
 234 .Pp
 235 The
 236 .Fn pidfile_remove
 237 function will fail if:
 238 .Bl -tag -width Er
 239 .It Bq Er EDOOFUS
 240 Improper function use.
 241 Probably called not from the process which made
 242 .Fn pidfile_write .
 243 .El
 244 .Pp
 245 The
 246 .Fn pidfile_remove
 247 function may also fail and set
 248 .Va errno
 249 for any errors specified for the
 250 .Xr close 2 ,
 251 .Xr fstat 2 ,
 252 .Xr write 2 ,
 253 and
 254 .Xr unlink 2
 255 system calls and the
 256 .Xr flopen 3
 257 library function.
 258 .Pp
 259 The
 260 .Fn pidfile_fileno
 261 function will fail if:
 262 .Bl -tag -width Er
 263 .It Bq Er EDOOFUS
 264 Improper function use.
 265 Probably called not from the process which used
 266 .Fn pidfile_open .
 267 .El
 268 .Sh SEE ALSO
 269 .Xr open 2 ,
 270 .Xr daemon 3 ,
 271 .Xr flopen 3
 272 .Sh AUTHORS
 273 .An -nosplit
 274 The
 275 .Nm pidfile
 276 functionality is based on ideas from
 277 .An John-Mark Gurney Aq jmg@FreeBSD.org .
 278 .Pp
 279 The code and manual page was written by
 280 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .