util: Add documentation for PID file handling

Signed-off-by: Martin Schwenke <martin@meltin.net>
Reviewed-by: Amitay Isaacs <amitay@gmail.com>
Autobuild-User(master): Amitay Isaacs <amitay@samba.org>
Autobuild-Date(master): Thu Aug 17 19:45:32 CEST 2017 on sn-devel-144

diff --git a/lib/util/pidfile.c b/lib/util/pidfile.c
index fdf9afb5ec9b268c60abe75a7cef69b35a334dce..5cd09cee75ce5d73f4dab7bba0a5f460a5eb1c86 100644 (file)
--- a/lib/util/pidfile.c
+++ b/lib/util/pidfile.c
@@ -27,11 +27,6 @@
 
 #include "lib/util/pidfile.h"
 
-/**
- * @file
- * @brief Pid file handling
- */
-
 int pidfile_path_create(const char *path, int *outfd)
 {
        struct flock lck;

diff --git a/lib/util/pidfile.h b/lib/util/pidfile.h
index d51161afc391136b5de3a3a3db36ed86d5ff5461..b1b9f54933927a3656fdd7576d2ef914d1906a5d 100644 (file)
--- a/lib/util/pidfile.h
+++ b/lib/util/pidfile.h
@@ -20,11 +20,64 @@
 #ifndef _SAMBA_PIDFILE_H_
 #define _SAMBA_PIDFILE_H_
 
+/**
+ * @file pidfile.h
+ *
+ * @brief PID file handling
+ */
+
+/**
+ * @brief Create a PID file
+ *
+ * Opens file, locks it, and writes PID.  Returns EACCES or EAGAIN if
+ * another process has the PID file locked.  Use unlink(2) and
+ * pidfile_fd_close() to remove the PID file.
+ *
+ * @param[in] path PID file name
+ * @param[out] outfd File descriptor of open/locked PID file
+ * @return 0 on success, errno on failure
+ */
 int pidfile_path_create(const char *path, int *outfd);
+
+/**
+ * @brief Unlock and close a PID file
+ *
+ * @param[in] fd File descriptor of open/locked PID file
+ */
 void pidfile_fd_close(int fd);
 
+/**
+ * @brief Check a PID file
+ *
+ * PID file name is <piddir>/<name>.pid
+ *
+ * @param[in] piddir Directory for PID file
+ * @param[in] name PID file process name
+ * @return PID of active process, 0 if PID file missing/stale/error
+ */
 pid_t pidfile_pid(const char *piddir, const char *name);
-void pidfile_create(const char *piddir, const char *program_name);
-void pidfile_unlink(const char *piddir, const char *program_name);
+
+/**
+ * @brief Create a PID file
+ *
+ * Leave PID file open/locked on success, exit on failure.  On
+ * success, use pidfile_unlink() to remove PID file before exiting.
+ *
+ * PID file name is <piddir>/<name>.pid
+ *
+ * @param[in] piddir Directory for PID file
+ * @param[in] name PID file process name
+ */
+void pidfile_create(const char *piddir, const char *name);
+
+/**
+ * @brief Remove a PID file
+ *
+ * PID file name is <piddir>/<name>.pid
+ *
+ * @param[in] piddir Directory for PID file
+ * @param[in] name PID file process name
+ */
+void pidfile_unlink(const char *piddir, const char *name);
 
 #endif