NAME

       filemon — the filemon device

SYNOPSIS

       #include <dev/filemon/filemon.h>

DESCRIPTION

       The  filemon  device  allows  a  process  to  collect  file  operations data of its children.  The device
       /dev/filemon responds to two ioctl(2) calls.

       System calls are denoted using the following single letters:

       ‘C’     chdir(2)
       ‘D’     unlink(2)
       ‘E’     exec(2)
       ‘F’     fork(2), vfork(2)
       ‘L’     link(2), linkat(2), symlink(2), symlinkat(2)
       ‘M’     rename(2)
       ‘R’     open(2) for read
       ‘S’     stat(2)
       ‘W’     open(2) for write
       ‘X’     _exit(2)

       Note that ‘R’ following ‘W’ records can represent a single open(2)  for  R/W,  or  two  seperate  open(2)
       calls, one for ‘R’ and one for ‘W’.

IOCTLS

       User  mode  programs  communicate  with the filemon driver through a number of ioctls which are described
       below.  Each takes a single argument.

       FILEMON_SET_FD   Write the internal tracing buffer to the supplied open file descriptor.

       FILEMON_SET_PID  Child process ID to trace.

RETURN VALUES

       The ioctl() function returns the value 0 if successful; otherwise the value -1 is returned and the global
       variable errno is set to indicate the error.

FILES

       /dev/filemon

EXAMPLES

       #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(\"/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) == -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;
       }

       Creates a file named filemon.out and configures the filemon device to write the filemon  buffer  contents
       to it.

SEE ALSO

       dtrace(1), ktrace(1), truss(1)

HISTORY

       A filemon device appeared in FreeBSD 9.1.

Debian                                            May 30, 2012                                        FILEMON(4)