diff options
Diffstat (limited to 'share/man/man4/filemon.4')
| -rw-r--r-- | share/man/man4/filemon.4 | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/share/man/man4/filemon.4 b/share/man/man4/filemon.4 new file mode 100644 index 0000000..0726e5a --- /dev/null +++ b/share/man/man4/filemon.4 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2012 +.\" David E. O'Brien <obrien@FreeBSD.org>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgment: +.\" This product includes software developed by David E. O'Brien and +.\" contributors. +.\" 4. Neither the name of the author nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 30, 2012 +.Dt FILEMON 4 +.Os +.Sh NAME +.Nm filemon +.Nd the filemon device +.Sh SYNOPSIS +.In dev/filemon/filemon.h +.Sh DESCRIPTION +The +.Nm +device allows a process to collect file operations data of its children. +The device +.Pa /dev/filemon +responds to two +.Xr ioctl 2 +calls. +.Pp +System calls are denoted using the following single letters: +.Pp +.Bl -tag -width indent -compact +.It Ql C +.Xr chdir 2 +.It Ql D +.Xr unlink 2 +.It Ql E +.Xr exec 2 +.It Ql F +.Xr fork 2 , +.Xr vfork 2 +.It Ql L +.Xr link 2 , +.Xr linkat 2 , +.Xr symlink 2 , +.Xr symlinkat 2 +.It Ql M +.Xr rename 2 +.It Ql R +.Xr open 2 +for read +.It Ql S +.Xr stat 2 +.It Ql W +.Xr open 2 +for write +.It Ql X +.Xr _exit 2 +.El +.Pp +Note that +.Ql R +following +.Ql W +records can represent a single +.Xr open 2 +for R/W, +or two separate +.Xr open 2 +calls, one for +.Ql R +and one for +.Ql W . +Note that only successful system calls are captured. +.Sh IOCTLS +User mode programs communicate with the +.Nm +driver through a number of ioctls which are described below. +Each takes a single argument. +.Bl -tag -width ".Dv FILEMON_SET_PID" +.It Dv FILEMON_SET_FD +Write the internal tracing buffer to the supplied open file descriptor. +.It Dv FILEMON_SET_PID +Child process ID to trace. +.El +.Sh RETURN VALUES +.\" .Rv -std ioctl +The +.Fn ioctl +function returns the value 0 if successful; +otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh FILES +.Bl -tag -width ".Pa /dev/filemon" +.It Pa /dev/filemon +.El +.Sh EXAMPLES +.Bd -literal +#include <sys/types.h> +#include <sys/stat.h> +#include <sys/wait.h> +#include <sys/ioctl.h> +#include <dev/filemon/filemon.h> +#include <fcntl.h> +#include <err.h> + +static void +open_filemon(void) +{ + pid_t child; + int fm_fd, fm_log; + + if ((fm_fd = open("/dev/filemon", O_RDWR)) == -1) + err(1, "open(\e"/dev/filemon\e", O_RDWR)"); + if ((fm_log = open("filemon.out", + O_CREAT | O_WRONLY | O_TRUNC, DEFFILEMODE)) == -1) + err(1, "open(filemon.out)"); + + if (ioctl(fm_fd, FILEMON_SET_FD, &fm_log) == -1) + err(1, "Cannot set filemon log file descriptor"); + /* Set up these two fd's to close on exec. */ + (void)fcntl(fm_fd, F_SETFD, FD_CLOEXEC); + (void)fcntl(fm_log, F_SETFD, FD_CLOEXEC); + + if ((child = fork()) == 0) { + child = getpid(); + if (ioctl(fm_fd, FILEMON_SET_PID, &child) == -1) + err(1, "Cannot set filemon PID"); + /* Do something here. */ + return 0; + } else { + wait(&child); + close(fm_fd); + } + return 0; +} +.Ed +.Pp +Creates a file named +.Pa filemon.out +and configures the +.Nm +device to write the +.Nm +buffer contents to it. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr ktrace 1 , +.Xr truss 1 , +.Xr ioctl 2 +.Sh HISTORY +A +.Nm +device appeared in +.Fx 9.1 . |
