diff --git a/lib/libutil/pidfile.3 b/lib/libutil/pidfile.3 --- 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 @@ 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,20 @@ 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. +Note that +.Fn pidfile_signal +will return +.Dv ENOENT , +if the pidfile exists but is not locked, and that it may also return +.Dv ESRCH +if called just as the process is shutting down. .Sh EXAMPLES The following example shows in which order these functions should be used. Note that it is safe to pass @@ -282,6 +320,7 @@ .El .Sh SEE ALSO .Xr open 2 , +.Xr kill 2 , .Xr daemon 3 , .Xr flopen 3 .Sh HISTORY