1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Chelsio Communications, Inc. 5.\" Written by: John Baldwin <jhb@FreeBSD.org> 6.\" 7.Dd July 31, 2025 8.Dt FREEBSD::STRINGF 3 9.Os 10.Sh NAME 11.Nm freebsd::pidfile 12.Nd own a PID file handle 13.Sh LIBRARY 14.Lb libutil++ 15.Sh SYNOPSIS 16.In libutil++.hh 17.Pp 18.Vt class freebsd::pidfile 19{ 20.Bd -ragged -offset indent 21.Fn pidfile 22.Fn pidfile "struct pidfh *pfh" 23.Fn pidfile "pidfile &&other" 24.Fn ~pidfile 25.Ft struct pidfh * 26.Fn release 27.Ft void 28.Fn reset "struct pidfh *newpfh = nullptr" 29.Ft int 30.Fn write 31.Ft int 32.Fn close 33.Ft int 34.Fn fileno 35.Ft "pidfile &" 36.Fn operator= "pidfile &&other" 37.Ft "pidfile &" 38.Fn operator= "struct pidfh *pfh" 39.Fn "explicit operator bool" 40.Ed 41}; 42.Sh DESCRIPTION 43Each instance of this class owns a PID file handle created by 44.Xr pidfile_open 3 . 45This class is patterned on std::unique_ptr; 46however, 47rather than exporting the raw pointer via a 48.Fn get 49method, 50this class provides wrapper methods for each of the other 51.Xr pidfile 3 52functions. 53The currently-owned PID file is removed by invoking 54.Xr pidfile_remove 3 55when an instance of this class is destroyed. 56The currently-owned PID file is also removed if it is replaced by the 57.Fn reset 58method or assignment operators. 59.Pp 60The 61.Fn release 62method relinquishes ownership of the current PID file handle and returns the 63value of the previously-owned PID file handle. 64.Pp 65The 66.Fn write 67method writes out the PID of the current process to the PID file via 68.Xr pidfile_write 3 . 69.Pp 70The 71.Fn close 72method closes the current PID file without removing it via 73.Xr pidfile_close 3 . 74If the close succeeds, the PID file handle is no longer valid. 75.Pp 76The 77.Fn fileno 78method returns the underlying file descriptor for the current PID file via 79.Xr pidfile_fileno 3 . 80.Pp 81The explicit 82.Vt bool 83conversion operator permits testing the validity of an object. 84The operator returns true if the instance owns a valid PID file handle. 85.Sh EXAMPLES 86.Bd -literal -offset indent 87int 88main() 89{ 90 freebsd::pidfile pf(pidfile_open("/var/run/daemon.pid", 91 0600, NULL)); 92 if (!pf) 93 err(1, "pidfile_open"); 94 95 if (daemon(0, 0) == -1) { 96 warn("daemon"); 97 return 1; 98 } 99 100 pf->write(); 101 102 for (;;) { 103 /* Do Work */ 104 } 105 106 return 0; 107} 108.Ed 109.Sh SEE ALSO 110.Xr pidfile 3 111