Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FILEMON(4)	       FreeBSD Kernel Interfaces Manual		    FILEMON(4)

     filemon --	track interesting system calls

     pseudo-device filemon

     In	normal situations, filemon is not built-in to the kernel, and a	call
     to	open /dev/filemon will auto-load the filemon module (see module(7) for
     more details).

     (Although not recommended,	the filemon facility can be included in	a ker-
     nel build by adding

	   pseudo-device filemon

     to	the kernel configuration file.)

     filemon provides a	means for tracking the successful system calls per-
     formed by a process and its descendants.  It is used by make(1) to	track
     the activities of build scripts, for the purpose of automatically learn-
     ing dependencies.

     The data captured by filemon for the script

	   n=`wc -l /etc/motd`;	echo "int motd_lines = $n;" >
	   cmp -s foo.h 2> /dev/null || mv foo.h

     looks like:

	   # filemon version 4
	   # Target pid	24291
	   V 4
	   E 29676 /bin/sh
	   R 29676 /etc/
	   R 29676 /lib/
	   R 29676 /lib/
	   R 29676 /lib/
	   F 29676 4899
	   E 4899 /usr/bin/wc
	   R 4899 /etc/
	   R 4899 /usr/lib/
	   R 4899 /etc/motd
	   X 4899 0
	   W 29676
	   X 29676 0
	   # Bye bye
	   E 3250 /bin/sh
	   R 3250 /etc/
	   R 3250 /lib/
	   R 3250 /lib/
	   R 3250 /lib/
	   W 26673 /dev/null
	   E 26673 /usr/bin/cmp
	   R 26673 /etc/
	   R 26673 /usr/lib/
	   X 26673 2
	   E 576 /bin/mv
	   R 576 /etc/
	   R 576 /lib/
	   M 576 '' 'foo.h'
	   X 576 0
	   X 3250 0
	   # Bye bye

     Most records follow the format:

	   type	pid data

     where type	is one of the list below, and unless otherwise specified, data
     is	a pathname.

	   C	   chdir(2).

	   D	   unlink(2).

	   E	   exec(3).

	   F	   fork(2), vfork(2); data is the process id of	the child.

	   L	   link(2), symlink(2);	data is	two pathnames.

	   M	   rename(2); data is two pathnames.

	   R	   open(2) for read or read-write.

	   W	   open(2) for writing or read-write.

	   X	   exit(3); data is the	exit status.

	   V	   indicates the version of filemon.

     A filemon instance	is created by opening /dev/filemon.  Then use
     ioctl(filemon_fd, FILEMON_SET_PID,	_pid) to identify the target process
     to	monitor, and ioctl(filemon_fd, FILEMON_SET_FD, _output_fd) to direct
     the event log to an already-opened	output file.


     The following example demonstrates	the basic usage	of filemon:

	   #include <filemon.h>

	   pid_t pid;
	   int filemon_fd, temp_fd;
	   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, FD_CLOEXEC);
	   fcntl(temp_fd, F_SETFD, FD_CLOEXEC);

	   pid = fork();
	   switch(pid) {
	    case -1:
		err(1, "cannot fork");
	    case 0:
		pid = getpid();
		/* tell	filemon	to monitor this	process	*/
		ioctl(filemon_fd, FILEMON_SET_PID, &pid);
		status = wait();
		lseek(temp_fd, SEEK_SET, 0);
		/* read	the captured syscalls from temp_fd */

     The output	of filemon is intended to be simple to parse.  It is possible
     to	achieve	almost equivalent results with dtrace(1) though	on many	sys-
     tems this requires	elevated privileges.  Also, ktrace(1) can capture sim-
     ilar data,	but records failed system calls	as well	as successful, and is
     thus more complex to post-process.

     filemon was contributed by	Juniper	Networks.

     If	the monitored process exits, and its pid gets reused, filemon will
     continue to report	events for the new process (and	its descendants) with-
     out any authorization checks.

     Monitoring	of a process enables the target	process	to write to the	track-
     ing process's file	descriptor.

     The filemon facility can only be used to track processes running in the
     system's native emulation.	 Neither processes using any of	the COMPAT_xxx
     compatibility layers nor any descendants of such processes	can be

     If	two processes are monitored, and one is	a descendant of	the other,
     events related to the descendant process and its further descendants are
     delivered only to the descendant process's	monitor.  If a process is be-
     ing monitored by two instances of filemon,	events will be delivered only
     to	the first instance created (when /dev/filemon was opened), regardless
     of	the order in which the monitoring processes called ioctl(fd,
     FILEMON_SET_PID, pid).

FreeBSD	13.0			January	6, 2016			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help