The branch main has been updated by des:
URL:
https://cgit.FreeBSD.org/src/commit/?id=4e6a3e7e3240a95cda1d490831aa16ed3b9bd59b
commit 4e6a3e7e3240a95cda1d490831aa16ed3b9bd59b
Author: Dag-Erling Smørgrav <d...@freebsd.org>
AuthorDate: 2025-08-03 17:31:20 +0000
Commit: Dag-Erling Smørgrav <d...@freebsd.org>
CommitDate: 2025-08-03 17:31:20 +0000
libutil: Document pidfile_signal()
Fixes: 287451fd0192
MFC after: 1 week
Reviewed by: pauamma_gundo.com, emaste
Differential Revision: https://reviews.freebsd.org/D51705
---
lib/libutil/pidfile.3 | 68 ++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 64 insertions(+), 4 deletions(-)
diff --git a/lib/libutil/pidfile.3 b/lib/libutil/pidfile.3
index c4786736d28f..d28d5ed8eccb 100644
--- a/lib/libutil/pidfile.3
+++ b/lib/libutil/pidfile.3
@@ -22,14 +22,16 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd May 10, 2020
+.Dd August 2, 2025
.Dt PIDFILE 3
.Os
.Sh NAME
.Nm pidfile_open ,
.Nm pidfile_write ,
.Nm pidfile_close ,
-.Nm pidfile_remove
+.Nm pidfile_remove ,
+.Nm pidfile_fileno ,
+.Nm pidfile_signal
.Nd "library for PID files handling"
.Sh LIBRARY
.Lb libutil
@@ -45,6 +47,8 @@
.Fn pidfile_remove "struct pidfh *pfh"
.Ft int
.Fn pidfile_fileno "struct pidfh *pfh"
+.Ft int
+.Fn pidfile_signal "const char *path" "int sig" "pid_t *pidptr"
.Sh DESCRIPTION
The
.Nm pidfile
@@ -101,6 +105,26 @@ function closes and removes a pidfile.
The
.Fn pidfile_fileno
function returns the file descriptor for the open pidfile.
+.Pp
+The
+.Fn pidfile_signal
+function looks for the pidfile specified by
+.Va path ,
+and if it exists and is locked, sends the signal specified by
+.Va sig
+to the PID it contains.
+If
+.Va pidptr
+is not
+.Dv NULL ,
+the PID that was found in the pidfile is stored in the location it
+points to.
+Note that calling
+.Fn pidfile_signal
+with
+.Va sig
+set to zero is an effective way to verify the existence of a pidfile
+and of the process that owns it.
.Sh RETURN VALUES
The
.Fn pidfile_open
@@ -125,6 +149,13 @@ and sets
if a NULL
.Vt pidfh
is specified, or if the pidfile is no longer open.
+.Pp
+The
+.Fn pidfile_signal
+function returns 0 if it successfully signaled a process, and an
+appropriate
+.Va errno
+value otherwise.
.Sh EXAMPLES
The following example shows in which order these functions should be used.
Note that it is safe to pass
@@ -132,7 +163,7 @@ Note that it is safe to pass
to
.Fn pidfile_write ,
.Fn pidfile_remove ,
-.Fn pidfile_close
+.Fn pidfile_close ,
and
.Fn pidfile_fileno
functions.
@@ -280,7 +311,28 @@ Improper function use.
Probably called not from the process which used
.Fn pidfile_open .
.El
+.Pp
+The
+.Fn pidfile_signal
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er ENOENT
+The pidfile does not exist, or exists but is not locked.
+.It Bq Er EDOM
+The pidfile contains a negative number.
+.El
+.Pp
+The
+.Fn pidfile_signal
+function may also fail and return any of the
+.Va errno
+values specified for the
+.Fn pidfile_read
+function and the
+.Xr kill 2
+system call.
.Sh SEE ALSO
+.Xr kill 2 ,
.Xr open 2 ,
.Xr daemon 3 ,
.Xr flopen 3
@@ -288,11 +340,19 @@ Probably called not from the process which used
The functions
.Fn pidfile_open ,
.Fn pidfile_write ,
-.Fn pidfile_close
+.Fn pidfile_close ,
and
.Fn pidfile_remove
first appeared in
.Fx 5.5 .
+The
+.Fn pidfile_fileno
+function was added in
+.Fx 9.1 .
+The
+.Fn pidfile_signal
+function was added in
+.Fx 14.0 .
.Sh AUTHORS
.An -nosplit
The
