Module Name: src Committed By: sjg Date: Fri Apr 1 00:07:35 UTC 2011
Added Files: src/share/man/man4: filemon.4 Log Message: A man page for filemon(4) To generate a diff of this commit: cvs rdiff -u -r0 -r1.1 src/share/man/man4/filemon.4 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Added files: Index: src/share/man/man4/filemon.4 diff -u /dev/null src/share/man/man4/filemon.4:1.1 --- /dev/null Fri Apr 1 00:07:35 2011 +++ src/share/man/man4/filemon.4 Fri Apr 1 00:07:34 2011 @@ -0,0 +1,154 @@ +.\" $NetBSD: filemon.4,v 1.1 2011/04/01 00:07:34 sjg Exp $ +.\" +.\" Copyright (c) 2011, Juniper Networks, Inc. +.\" +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" OWNER 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. +.\" +.Dd March 14, 2011 +.Dt FILEMON 4 +.Os +.Sh NAME +.Nm filemon +.Nd track interesting system calls +.Sh SYNOPSIS +.In filemon.h +.Pa /dev/filemon +.Sh DESCRIPTION +.Nm +provides a means for tracking the successful system calls performed by a process. +It is used by +.Xr make 1 +to track the activities of build scripts, for the purpose of automatically +learning dependencies. + +Example: +.Bd -literal +#include <filemon.h> + +pid_d pid; +int fd, tfd; +int status; + +filemon_fd = open("/dev/filemon", O_RDWR); +temp_fd = mkstemp("/tmp/filemon.XXXXXXX"); +/* give filemon the temp file to use */ +ioctl(filemon_fd, FILEMON_SET_FD, &temp_fd); +/* children do not need these once they exec */ +fcntl(filemon_fd, F_SETFD, 1); +fcntl(temp_fd, F_SETFD, 1); + +pid = fork(); +switch(pid) { + case -1: + err(1, "cannot fork"); + break; + case 0: + pid = getpid(); + /* tell filemon to monitor this process */ + ioctl(filemon_fd, FILEMON_SET_PID, &pid); + execvp(...); + _exit(1); + break; + default: + status = wait(); + close(filemon_fd); + lseek(temp_fd, SEEK_SET, 0); + /* read the captured syscalls from temp_fd */ + close(temp_fd); + break; +} + +.Ed + +It is possible to achieve almost equivalent results with +.Xr dtrace 1M +though on many systems this requires elevated privileges. + +The data captured by +.Nm +for the command +.Bd -literal +cat /etc/motd + +.Ed +looks like: +.Bd -literal +# filemon version 2 +# Target pid 7437 +V 2 +E 21848 /bin/cat +R 21848 /lib/libc.so.12 +R 21848 /etc/motd +X 21848 0 +# Bye bye + +.Ed + +Most records follow the format: + +.Pa type +.Pa pid +.Pa data + +Where +.Pa type +is one of the list below, and unless otherwise specified, +.Pa data +is a pathname. +.Bl -tag -width Ds +.It C +.Xr chdir 2 . +.It D +.Xr unlink 2 . +.It E +.Xr exec 2 . +.It F +.Xr fork 2 , +.Xr vfork 2 ; +.Pa data +is the process id of the child. +.It L +.Xr link 2 , +.Xr symlink 2 ; +.Pa data +is two pathnames. +.It M +.Xr rename 2 ; +.Pa data +is two pathnames. +.It R +.Xr open 2 +read-only. +.It W +.Xr open 2 +for writing or read-write. +.It X +.Xr exit 2 ; +.Pa data +is the exit status. +.It V +indicates the version of +.Nm . +.El +.Sh HISTORY +.Nm +was contributed by Juniper Networks.