1.\" Copyright (c) 2012 2.\" David E. O'Brien <obrien@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgment: 14.\" This product includes software developed by David E. O'Brien and 15.\" contributors. 16.\" 4. Neither the name of the author nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd January 28, 2016 35.Dt FILEMON 4 36.Os 37.Sh NAME 38.Nm filemon 39.Nd the filemon device 40.Sh SYNOPSIS 41.In dev/filemon/filemon.h 42.Sh DESCRIPTION 43The 44.Nm 45device allows a process to collect file operations data of its children. 46The device 47.Pa /dev/filemon 48responds to two 49.Xr ioctl 2 50calls. 51.Pp 52.Nm 53is not intended to be a security auditing tool. 54Many syscalls are not tracked and binaries of foreign ABI will not be fully 55audited. 56It is intended for auditing of processes for the purpose of determining its 57dependencies in an efficient and easily parsable format. 58An example of this is 59.Xr make 1 60which uses this module with 61.Sy .MAKE.MODE=meta 62to handle incremental builds more smartly. 63.Pp 64System calls are denoted using the following single letters: 65.Pp 66.Bl -tag -width indent -compact 67.It Ql C 68.Xr chdir 2 69.It Ql D 70.Xr unlink 2 71.It Ql E 72.Xr exec 2 73.It Ql F 74.Xr fork 2 , 75.Xr vfork 2 76.It Ql L 77.Xr link 2 , 78.Xr linkat 2 , 79.Xr symlink 2 , 80.Xr symlinkat 2 81.It Ql M 82.Xr rename 2 83.It Ql R 84.Xr open 2 85for read 86.It Ql S 87.Xr stat 2 88.It Ql W 89.Xr open 2 90for write 91.It Ql X 92.Xr _exit 2 93.El 94.Pp 95Note that 96.Ql R 97following 98.Ql W 99records can represent a single 100.Xr open 2 101for R/W, 102or two separate 103.Xr open 2 104calls, one for 105.Ql R 106and one for 107.Ql W . 108Note that only successful system calls are captured. 109.Sh IOCTLS 110User mode programs communicate with the 111.Nm 112driver through a number of ioctls which are described below. 113Each takes a single argument. 114.Bl -tag -width ".Dv FILEMON_SET_PID" 115.It Dv FILEMON_SET_FD 116Write the internal tracing buffer to the supplied open file descriptor. 117.It Dv FILEMON_SET_PID 118Child process ID to trace. 119.El 120.Sh RETURN VALUES 121.\" .Rv -std ioctl 122The 123.Fn ioctl 124function returns the value 0 if successful; 125otherwise the value \-1 is returned and the global variable 126.Va errno 127is set to indicate the error. 128.Sh FILES 129.Bl -tag -width ".Pa /dev/filemon" 130.It Pa /dev/filemon 131.El 132.Sh EXAMPLES 133.Bd -literal 134#include <sys/types.h> 135#include <sys/stat.h> 136#include <sys/wait.h> 137#include <sys/ioctl.h> 138#include <dev/filemon/filemon.h> 139#include <fcntl.h> 140#include <err.h> 141#include <unistd.h> 142 143static void 144open_filemon(void) 145{ 146 pid_t child; 147 int fm_fd, fm_log; 148 149 if ((fm_fd = open("/dev/filemon", O_RDWR | O_CLOEXEC)) == -1) 150 err(1, "open(\e"/dev/filemon\e", O_RDWR)"); 151 if ((fm_log = open("filemon.out", 152 O_CREAT | O_WRONLY | O_TRUNC | O_CLOEXEC, DEFFILEMODE)) == -1) 153 err(1, "open(filemon.out)"); 154 155 if (ioctl(fm_fd, FILEMON_SET_FD, &fm_log) == -1) 156 err(1, "Cannot set filemon log file descriptor"); 157 158 if ((child = fork()) == 0) { 159 child = getpid(); 160 if (ioctl(fm_fd, FILEMON_SET_PID, &child) == -1) 161 err(1, "Cannot set filemon PID"); 162 /* Do something here. */ 163 } else { 164 wait(&child); 165 close(fm_fd); 166 } 167} 168.Ed 169.Pp 170Creates a file named 171.Pa filemon.out 172and configures the 173.Nm 174device to write the 175.Nm 176buffer contents to it. 177.Sh SEE ALSO 178.Xr dtrace 1 , 179.Xr ktrace 1 , 180.Xr script 1 , 181.Xr truss 1 , 182.Xr ioctl 2 183.Sh HISTORY 184A 185.Nm 186device appeared in 187.Fx 9.1 . 188.Sh BUGS 189Loading 190.Nm 191may reduce system performance for the noted syscalls. 192.Pp 193Only children of the set process are logged. 194Processes can escape being traced by double forking. 195This is not seen as a problem as the intended use is build monitoring, which 196does not make sense to have daemons for. 197