1PIDFILE(3bsd)                        LOCAL                       PIDFILE(3bsd)
2

NAME

4     pidfile_open, pidfile_write, pidfile_close, pidfile_remove,
5     pidfile_fileno — library for PID files handling
6

LIBRARY

8     Utility functions from BSD systems (libbsd, -lbsd)
9

SYNOPSIS

11     #include <libutil.h>
12     (See libbsd(7) for include usage.)
13
14     struct pidfh *
15     pidfile_open(const char *path, mode_t mode, pid_t *pidptr);
16
17     int
18     pidfile_write(struct pidfh *pfh);
19
20     int
21     pidfile_close(struct pidfh *pfh);
22
23     int
24     pidfile_remove(struct pidfh *pfh);
25
26     int
27     pidfile_fileno(struct pidfh *pfh);
28

DESCRIPTION

30     The pidfile family of functions allows daemons to handle PID files.  It
31     uses flopen(3bsd) to lock a pidfile and detect already running daemons.
32
33     The pidfile_open() function opens (or creates) a file specified by the
34     path argument and locks it.  If pidptr argument is not NULL and file can
35     not be locked, the function will use it to store a PID of an already run‐
36     ning daemon or -1 in case daemon did not write its PID yet.  The function
37     does not write process' PID into the file here, so it can be used before
38     fork()ing and exit with a proper error message when needed.  If the path
39     argument is NULL, /var/run/progname.pid file will be used.  The
40     pidfile_open() function sets the O_CLOEXEC close-on-exec flag when open‐
41     ing the pidfile.
42
43     The pidfile_write() function writes process' PID into a previously opened
44     file.  The file is truncated before write, so calling the pidfile_write()
45     function multiple times is supported.
46
47     The pidfile_close() function closes a pidfile.  It should be used after
48     daemon fork()s to start a child process.
49
50     The pidfile_remove() function closes and removes a pidfile.
51
52     The pidfile_fileno() function returns the file descriptor for the open
53     pidfile.
54

RETURN VALUES

56     The pidfile_open() function returns a valid pointer to a pidfh structure
57     on success, or NULL if an error occurs.  If an error occurs, errno will
58     be set.
59
60     The pidfile_write(), pidfile_close(), and pidfile_remove() functions
61     return the value 0 if successful; otherwise the value -1 is returned and
62     the global variable errno is set to indicate the error.
63
64     The pidfile_fileno() function returns the low-level file descriptor.  It
65     returns -1 and sets errno if a NULL pidfh is specified, or if the pidfile
66     is no longer open.
67

EXAMPLES

69     The following example shows in which order these functions should be
70     used.  Note that it is safe to pass NULL to pidfile_write(),
71     pidfile_remove(), pidfile_close() and pidfile_fileno() functions.
72
73     struct pidfh *pfh;
74     pid_t otherpid, childpid;
75
76     pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
77     if (pfh == NULL) {
78             if (errno == EEXIST) {
79                     errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
80                         (intmax_t)otherpid);
81             }
82             /* If we cannot create pidfile from other reasons, only warn. */
83             warn("Cannot open or create pidfile");
84             /*
85              * Even though pfh is NULL we can continue, as the other pidfile_*
86              * function can handle such situation by doing nothing except setting
87              * errno to EINVAL.
88              */
89     }
90
91     if (daemon(0, 0) == -1) {
92             warn("Cannot daemonize");
93             pidfile_remove(pfh);
94             exit(EXIT_FAILURE);
95     }
96
97     pidfile_write(pfh);
98
99     for (;;) {
100             /* Do work. */
101             childpid = fork();
102             switch (childpid) {
103             case -1:
104                     syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
105                     break;
106             case 0:
107                     pidfile_close(pfh);
108                     /* Do child work. */
109                     break;
110             default:
111                     syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
112                     break;
113             }
114     }
115
116     pidfile_remove(pfh);
117     exit(EXIT_SUCCESS);
118

ERRORS

120     The pidfile_open() function will fail if:
121
122     [EEXIST]           Some process already holds the lock on the given pid‐
123                        file, meaning that a daemon is already running.  If
124                        pidptr argument is not NULL the function will use it
125                        to store a PID of an already running daemon or -1 in
126                        case daemon did not write its PID yet.
127
128     [ENAMETOOLONG]     Specified pidfile's name is too long.
129
130     [EINVAL]           Some process already holds the lock on the given pid‐
131                        file, but PID read from there is invalid.
132
133     The pidfile_open() function may also fail and set errno for any errors
134     specified for the fstat(2), open(2), and read(2) calls.
135
136     The pidfile_write() function will fail if:
137
138     [EINVAL]           Improper function use.  Probably called before
139                        pidfile_open().
140
141     The pidfile_write() function may also fail and set errno for any errors
142     specified for the fstat(2), ftruncate(2), and write(2) calls.
143
144     The pidfile_close() function may fail and set errno for any errors speci‐
145     fied for the close(2) and fstat(2) calls.
146
147     The pidfile_remove() function will fail if:
148
149     [EINVAL]           Improper function use.  Probably called not from the
150                        process which made pidfile_write().
151
152     The pidfile_remove() function may also fail and set errno for any errors
153     specified for the close(2), fstat(2), write(2), and unlink(2) system
154     calls and the flopen(3bsd) library function.
155
156     The pidfile_fileno() function will fail if:
157
158     [EINVAL]           Improper function use.  Probably called not from the
159                        process which used pidfile_open().
160

SEE ALSO

162     open(2), daemon(3), flopen(3bsd)
163

AUTHORS

165     The pidfile functionality is based on ideas from John-Mark Gurney
166     <jmg@FreeBSD.org>.
167
168     The code and manual page was written by Pawel Jakub Dawidek
169     <pjd@FreeBSD.org>.
170
171BSD                            February 8, 2012                            BSD
Impressum