From owner-svn-src-head@FreeBSD.ORG Mon Jun 4 22:59:07 2012 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 6FCD7106566B; Mon, 4 Jun 2012 22:59:07 +0000 (UTC) (envelope-from obrien@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 4FC388FC1B; Mon, 4 Jun 2012 22:59:07 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q54Mx75d073087; Mon, 4 Jun 2012 22:59:07 GMT (envelope-from obrien@svn.freebsd.org) Received: (from obrien@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q54Mx7Ok073084; Mon, 4 Jun 2012 22:59:07 GMT (envelope-from obrien@svn.freebsd.org) Message-Id: <201206042259.q54Mx7Ok073084@svn.freebsd.org> From: "David E. O'Brien" Date: Mon, 4 Jun 2012 22:59:07 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r236593 - head/share/man/man4 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 04 Jun 2012 22:59:07 -0000 Author: obrien Date: Mon Jun 4 22:59:06 2012 New Revision: 236593 URL: http://svn.freebsd.org/changeset/base/236593 Log: Add a man page for filemon(4) [r236592]. Added: head/share/man/man4/filemon.4 (contents, props changed) Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Mon Jun 4 22:54:19 2012 (r236592) +++ head/share/man/man4/Makefile Mon Jun 4 22:59:06 2012 (r236593) @@ -126,6 +126,7 @@ MAN= aac.4 \ fdt.4 \ fdtbus.4 \ ffclock.4 \ + filemon.4 \ firewire.4 \ fpa.4 \ fwe.4 \ Added: head/share/man/man4/filemon.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/filemon.4 Mon Jun 4 22:59:06 2012 (r236593) @@ -0,0 +1,166 @@ +.\" Copyright (c) 2012 +.\" David E. O'Brien . 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 acknowledgement: +.\" 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 MERCHANTABILITY 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: +.Bl -tag -width indent -compact +.It Dq Li C +.Xr chdir 2 +.It Dq Li D +.Xr unlink 2 +.It Dq Li E +.Xr exec 2 +.It Dq Li F +.Xr fork 2 , +.Xr vfork 2 +.It Dq Li L +.Xr link 2 , +.Xr linkat 2 , +.Xr symlink 2 , +.Xr symlinkat 2 +.It Dq Li M +.Xr rename 2 +.It Dq Li R +.Xr open 2 +for read +.It Dq Li S +.Xr stat 2 +.It Dq Li W +.Xr open 2 +for write +.It Dq Li X +.Xr _exit 2 +.El +.Pp +Note that +.Dq R +following +.Dq W +records can represent a single +.Xr open 2 +for R/W, +or two seperate +.Xr open 2 +calls, one for +R +and one for +W. +.Sh IOCTLS +User mode programs communicate with the filemon driver through a +number of ioctls which are described below. +Each takes a single argument. +.Bl -tag -width 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 +.Pp +.Sh RETURN VALUES +The ioctl returns zero on success and non-zero on failure. +.Sh EXAMPLES +.Bd -literal -offset indent +#include +#include +#include +#include +#include +#include +#include + +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(\"/dev/filemon\", 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) < 0) + 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) { + /* Do something here. */ + return 0; + } else { + if (ioctl(fm_fd, FILEMON_SET_PID, &child) < 0) + err(1, "Cannot set filemon PID"); + wait(&child); + close(fm_fd); + } + return 0; +} +.Ed +.Pp +Creates a file named +.Pa filemon.out +and configures the +.Nm +device to write the filemon buffer contents to it. +.Sh FILES +.Bl -tag -width /dev/zero +.It Pa /dev/filemon +.El +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr ktrace 1 , +.Xr truss 1 +.Sh HISTORY +A +.Nm +device appeared in +.Fx 9.1 .