pidfile(3bsd)

1PIDFILE(3)               BSD Library Functions Manual               PIDFILE(3)
2

NAME

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

LIBRARY

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

SYNOPSIS

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

DESCRIPTION

26     The pidfile family of functions allows daemons to handle PID files.  It
27     uses flopen(3) to lock a pidfile and detect already running daemons.
28
29     The pidfile_open() function opens (or creates) a file specified by the
30     path argument and locks it.  If a file can not be locked, a PID of an
31     already running daemon is returned in the pidptr argument (if it is not
32     NULL).  The function does not write process' PID into the file here, so
33     it can be used before fork()ing and exit with a proper error message when
34     needed.  If the path argument is NULL, /var/run/⟨progname⟩.pid file will
35     be used.
36
37     The pidfile_write() function writes process' PID into a previously opened
38     file.
39
40     The pidfile_close() function closes a pidfile.  It should be used after
41     daemon fork()s to start a child process.
42
43     The pidfile_remove() function closes and removes a pidfile.
44

RETURN VALUES

46     The pidfile_open() function returns a valid pointer to a pidfh structure
47     on success, or NULL if an error occurs.  If an error occurs, errno will
48     be set.
49
50     The pidfile_write(), pidfile_close(), and pidfile_remove() functions
51     return the value 0 if successful; otherwise the value -1 is returned and
52     the global variable errno is set to indicate the error.
53

EXAMPLES

55     The following example shows in which order these functions should be
56     used.  Note that it is safe to pass NULL to pidfile_write(),
57     pidfile_remove() and pidfile_close() functions.
58
59     struct pidfh *pfh;
60     pid_t otherpid, childpid;
61
62     pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
63     if (pfh == NULL) {
64             if (errno == EEXIST) {
65                     errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
66                         (intmax_t)otherpid);
67             }
68             /* If we cannot create pidfile from other reasons, only warn. */
69             warn("Cannot open or create pidfile");
70     }
71
72     if (daemon(0, 0) == -1) {
73             warn("Cannot daemonize");
74             pidfile_remove(pfh);
75             exit(EXIT_FAILURE);
76     }
77
78     pidfile_write(pfh);
79
80     for (;;) {
81             /* Do work. */
82             childpid = fork();
83             switch (childpid) {
84             case -1:
85                     syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
86                     break;
87             case 0:
88                     pidfile_close(pfh);
89                     /* Do child work. */
90                     break;
91             default:
92                     syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
93                     break;
94             }
95     }
96
97     pidfile_remove(pfh);
98     exit(EXIT_SUCCESS);
99

ERRORS

101     The pidfile_open() function will fail if:
102
103     [EEXIST]           Some process already holds the lock on the given pid‐
104                        file, meaning that a daemon is already running.
105
106     [ENAMETOOLONG]     Specified pidfile's name is too long.
107
108     [EINVAL]           Some process already holds the lock on the given pid‐
109                        file, but PID read from there is invalid.
110
111     [EAGAIN]           Some process already holds the lock on the given pid‐
112                        file, but the file is truncated.  Most likely, the
113                        existing daemon is writing new PID into the file.
114
115     The pidfile_open() function may also fail and set errno for any errors
116     specified for the fstat(2), open(2), and read(2) calls.
117
118     The pidfile_write() function will fail if:
119
120     [EINVAL]           Improper function use.  Probably called before
121                        pidfile_open().
122
123     The pidfile_write() function may also fail and set errno for any errors
124     specified for the fstat(2), ftruncate(2), and write(2) calls.
125
126     The pidfile_close() function may fail and set errno for any errors speci‐
127     fied for the close(2) and fstat(2) calls.
128
129     The pidfile_remove() function will fail if:
130
131     [EINVAL]           Improper function use.  Probably called not from the
132                        process which made pidfile_write().
133
134     The pidfile_remove() function may also fail and set errno for any errors
135     specified for the close(2), fstat(2), write(2), and unlink(2) system
136     calls and the flopen(3) library function.
137

AUTHORS

142     The pidfile functionality is based on ideas from John-Mark Gurney
143     <jmg@FreeBSD.org>.
144
145     The code and manual page was written by Pawel Jakub Dawidek
146     <pjd@FreeBSD.org>.
147
148BSD                            October 20, 2008                            BSD