.\" $NetBSD: opensnoop.1m,v 1.5 2020/06/26 15:45:18 wiz Exp $
.Dd June 25, 2020
.Dt OPENSNOOP 1
.Os
.Sh NAME
.Nm opensnoop
.Nd snoop file opens as they occur. Uses DTrace
.Sh SYNOPSIS
.Nm
.Op Fl a | Fl A | Fl ceghsvxZ
.Op Fl f Ar pathname
.Op Fl n Ar name
.Op Fl p Ar PID
.Sh DESCRIPTION
.Nm
tracks file opens.
As a process issues a file open, details such as UID, PID and pathname are
printed out.
The returned file descriptor is printed, a value of \-1 indicates an error.
This can be useful for troubleshooting to determine if appliacions are
attempting to open files that do not exist.
Since this uses DTrace, only the root user or users with the
dtrace_kernel privilege can run this command.
.Bl -tag -width Fl
.It Fl A
dump all data, space delimited
.It Fl a
print all data
.It Fl c
print current working directory of process
.It Fl e
print errno value
.It Fl f Ar pathname
file pathname to snoop
.It Fl g
print full command arguments
.It Fl n Ar name
process name to snoop
.It Fl p Ar PID
process ID to snoop
.It Fl s
print start time, us
.It Fl v
print start time, string
.It Fl x
only print failed opens
.It Fl Z
print zonename
.El
.Bl -column "STRTIME"
.It Sy Fields Ta Sy Description
.It ZONE      Ta Zone name
.It UID       Ta User ID
.It PID       Ta Process ID
.It PPID      Ta Parent Process ID
.It FD        Ta File Descriptor
.Pq \-1 is error
.It ERR       Ta Va errno
value
.Pq see Pa /usr/include/sys/errno.h
.It CWD       Ta current working directory of process
.It PATH      Ta pathname for file open
.It COMM      Ta command name for the process
.It ARGS      Ta argument listing for the process
.It TIME      Ta timestamp for the open event, us
.It STRTIME   Ta timestamp for the open event, string
.El
.Sh EXAMPLES
Default output, print file opens by process as they occur,
.Pp
.Dl Ic opensnoop
.Pp
Print human readable timestamps,
.Pp
.Dl Ic opensnoop -v
.Pp
See error codes,
.Pp
.Dl Ic opensnoop -e
.Pp
Snoop this file only,
.Pp
.Dl Ic opensnoop -f /etc/passwd
.Ss STABILITY
stable \(em needs the syscall provider.
.Ss DOCUMENTATION
See the DTraceToolkit for further documentation under the Docs directory.
The DTraceToolkit docs may include full worked examples with verbose
descriptions explaining the output.
.Sh EXIT
.Nm
will run forever until Ctrl\-C is hit.
.Sh SEE ALSO
.Xr dtrace 1
.Sh AUTHORS
.An Brendan Gregg
[Sydney, Australia]
.Sh BUGS
Occasionally the pathname for the file open cannot be read and the following
error will be seen,
.Pp
.Dl dtrace: error on enabled probe ID 6 (...): invalid address
.Pp
this is normal behaviour.