FILEMON(4)              NetBSD 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
     being 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).

NetBSD 9.0                      January 6, 2016                     NetBSD 9.0

You can also request any man page by name and (optionally) by section:


Use the DEFAULT collection to view manual pages for third-party software.

©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2019 Modified for NetBSD by Kimmo Suominen