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 February 8, 2012
  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 libutil.h
  40 .Ft "struct pidfh *"
  41 .Fn pidfile_open "const char *path" "mode_t mode" "pid_t *pidptr"
  42 .Ft int
  43 .Fn pidfile_write "struct pidfh *pfh"
  44 .Ft int
  45 .Fn pidfile_close "struct pidfh *pfh"
  46 .Ft int
  47 .Fn pidfile_remove "struct pidfh *pfh"
  48 .Ft int
  49 .Fn pidfile_fileno "struct pidfh *pfh"
  50 .Sh DESCRIPTION
  51 The
  52 .Nm pidfile
  53 family of functions allows daemons to handle PID files.
  54 It uses
  55 .Xr flopen 3
  56 to lock a pidfile and detect already running daemons.
  57 .Pp
  58 The
  59 .Fn pidfile_open
  60 function opens (or creates) a file specified by the
  61 .Fa path
  62 argument and locks it.
  63 If
  64 .Fa pidptr
  65 argument is not
  66 .Dv NULL
  67 and file can not be locked, the function will use it to store a PID of an
  68 already running daemon or
  69 .Li -1
  70 in case daemon did not write its PID yet.
  71 The function does not write process' PID into the file here, so it can be
  72 used before
  73 .Fn fork Ns ing
  74 and exit with a proper error message when needed.
  75 If the
  76 .Fa path
  77 argument is
  78 .Dv NULL ,
  79 .Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
  80 file will be used.
  81 The
  82 .Fn pidfile_open
  83 function sets the O_CLOEXEC close-on-exec flag when opening the pidfile.
  84 .Pp
  85 The
  86 .Fn pidfile_write
  87 function writes process' PID into a previously opened file.
  88 The file is truncated before write, so calling the
  89 .Fn pidfile_write
  90 function multiple times is supported.
  91 .Pp
  92 The
  93 .Fn pidfile_close
  94 function closes a pidfile.
  95 It should be used after daemon
  96 .Fn fork Ns s
  97 to start a child process.
  98 .Pp
  99 The
 100 .Fn pidfile_remove
 101 function closes and removes a pidfile.
 102 .Pp
 103 The
 104 .Fn pidfile_fileno
 105 function returns the file descriptor for the open pidfile.
 106 .Sh RETURN VALUES
 107 The
 108 .Fn pidfile_open
 109 function returns a valid pointer to a
 110 .Vt pidfh
 111 structure on success, or
 112 .Dv NULL
 113 if an error occurs.
 114 If an error occurs,
 115 .Va errno
 116 will be set.
 117 .Pp
 118 .Rv -std pidfile_write pidfile_close pidfile_remove
 119 .Pp
 120 The
 121 .Fn pidfile_fileno
 122 function returns the low-level file descriptor.
 123 It returns
 124 .Li -1
 125 and sets
 126 .Va errno
 127 if a NULL
 128 .Vt pidfh
 129 is specified, or if the pidfile is no longer open.
 130 .Sh EXAMPLES
 131 The following example shows in which order these functions should be used.
 132 Note that it is safe to pass
 133 .Dv NULL
 134 to
 135 .Fn pidfile_write ,
 136 .Fn pidfile_remove ,
 137 .Fn pidfile_close
 138 and
 139 .Fn pidfile_fileno
 140 functions.
 141 .Bd -literal
 142 struct pidfh *pfh;
 143 pid_t otherpid, childpid;
 144
 145 pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
 146 if (pfh == NULL) {
 147         if (errno == EEXIST) {
 148                 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
 149                     (intmax_t)otherpid);
 150         }
 151         /* If we cannot create pidfile from other reasons, only warn. */
 152         warn("Cannot open or create pidfile");
 153         /*
 154          * Eventhough pfh is NULL we can continue, as the other pidfile_*
 155          * function can handle such situation by doing nothing except setting
 156          * errno to EDOOFUS.
 157          */
 158 }
 159
 160 if (daemon(0, 0) == -1) {
 161         warn("Cannot daemonize");
 162         pidfile_remove(pfh);
 163         exit(EXIT_FAILURE);
 164 }
 165
 166 pidfile_write(pfh);
 167
 168 for (;;) {
 169         /* Do work. */
 170         childpid = fork();
 171         switch (childpid) {
 172         case -1:
 173                 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
 174                 break;
 175         case 0:
 176                 pidfile_close(pfh);
 177                 /* Do child work. */
 178                 break;
 179         default:
 180                 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
 181                 break;
 182         }
 183 }
 184
 185 pidfile_remove(pfh);
 186 exit(EXIT_SUCCESS);
 187 .Ed
 188 .Sh ERRORS
 189 The
 190 .Fn pidfile_open
 191 function will fail if:
 192 .Bl -tag -width Er
 193 .It Bq Er EEXIST
 194 Some process already holds the lock on the given pidfile, meaning that a
 195 daemon is already running.
 196 If
 197 .Fa pidptr
 198 argument is not
 199 .Dv NULL
 200 the function will use it to store a PID of an already running daemon or
 201 .Li -1
 202 in case daemon did not write its PID yet.
 203 .It Bq Er ENAMETOOLONG
 204 Specified pidfile's name is too long.
 205 .It Bq Er EINVAL
 206 Some process already holds the lock on the given pidfile, but PID read
 207 from there is invalid.
 208 .El
 209 .Pp
 210 The
 211 .Fn pidfile_open
 212 function may also fail and set
 213 .Va errno
 214 for any errors specified for the
 215 .Xr fstat 2 ,
 216 .Xr open 2 ,
 217 and
 218 .Xr read 2
 219 calls.
 220 .Pp
 221 The
 222 .Fn pidfile_write
 223 function will fail if:
 224 .Bl -tag -width Er
 225 .It Bq Er EDOOFUS
 226 Improper function use.
 227 Probably called before
 228 .Fn pidfile_open .
 229 .El
 230 .Pp
 231 The
 232 .Fn pidfile_write
 233 function may also fail and set
 234 .Va errno
 235 for any errors specified for the
 236 .Xr fstat 2 ,
 237 .Xr ftruncate 2 ,
 238 and
 239 .Xr write 2
 240 calls.
 241 .Pp
 242 The
 243 .Fn pidfile_close
 244 function may fail and set
 245 .Va errno
 246 for any errors specified for the
 247 .Xr close 2
 248 and
 249 .Xr fstat 2
 250 calls.
 251 .Pp
 252 The
 253 .Fn pidfile_remove
 254 function will fail if:
 255 .Bl -tag -width Er
 256 .It Bq Er EDOOFUS
 257 Improper function use.
 258 Probably called not from the process which made
 259 .Fn pidfile_write .
 260 .El
 261 .Pp
 262 The
 263 .Fn pidfile_remove
 264 function may also fail and set
 265 .Va errno
 266 for any errors specified for the
 267 .Xr close 2 ,
 268 .Xr fstat 2 ,
 269 .Xr write 2 ,
 270 and
 271 .Xr unlink 2
 272 system calls and the
 273 .Xr flopen 3
 274 library function.
 275 .Pp
 276 The
 277 .Fn pidfile_fileno
 278 function will fail if:
 279 .Bl -tag -width Er
 280 .It Bq Er EDOOFUS
 281 Improper function use.
 282 Probably called not from the process which used
 283 .Fn pidfile_open .
 284 .El
 285 .Sh SEE ALSO
 286 .Xr open 2 ,
 287 .Xr daemon 3 ,
 288 .Xr flopen 3
 289 .Sh AUTHORS
 290 .An -nosplit
 291 The
 292 .Nm pidfile
 293 functionality is based on ideas from
 294 .An John-Mark Gurney Aq jmg@FreeBSD.org .
 295 .Pp
 296 The code and manual page was written by
 297 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .