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