opensnoop(8)

🦋 opensnoop — like, the manual page but make it cute 🦋

okay bestie so this is opensnoop from the System Manager's Manual (section 8, we love a section 8 moment 💅). She traces open() syscalls with all the file details, and she runs on Linux ftrace. Periodt.

---

✨ NAME ✨

opensnoop — trace open() syscalls with file details. Uses Linux ftrace. no cap, that's literally her whole job 🫶

---

✨ SYNOPSIS ✨

opensnoop [-htx] [-d secs] [-p pid] [-L tid] [-n name] [filename]

---

✨ DESCRIPTION ✨

So what she does is trace open() syscalls, and she shows you the file name (the pathname, bestie) and the returned file descriptor number — or -1 if it errored out 😭.

This implementation is specifically built to work on older kernel versions, and to work without kernel debuginfo. Iconic of her honestly. The way she does it: dynamic tracing of the return value of getname() as a string, and then associating it with the following open() syscall return. 💫

⚠️ real talk: this approach is kernel version specific, and it may not work on your version. It's a workaround, and a proof of concept for ftrace, until more kernel tracing functionality is available. She's doing her best, okay?

And since this uses ftrace, only the root user can use this tool. root energy only 👑

---

✨ REQUIREMENTS ✨

• FTRACE and KPROBE CONFIG
• the syscalls:sys_exit_open tracepoint
• the getname() kernel function
• and awk (yes girl, awk is carrying this whole operation, we stan)

You may already have these enabled and available on recent Linux kernels. 💖

---

✨ OPTIONS ✨

• -d secs — set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. lowkey efficient of her ✨

The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size. 👀

• -h — print usage message. the little "help me help you" moment 🎀
• -n name — only show processes matching this process name. Partial strings and regular expressions are allowed. This is post-filtered using awk.
• -p PID — only trace this process ID. This is filtered in-kernel. 🔥
• -L TID — only trace this thread ID. This is filtered in-kernel. 🔥
• -t — include timestamps, in seconds. ⏰
• -x — only print failed open()s. the flop detector 💀
• filename — only show open()s which match this filename. Partial strings and regular expressions are allowed. This is post-filtered using awk.

---

✨ EXAMPLES ✨

Trace all open() syscalls with details:

# opensnoop

Only trace open()s for PID 81:

# opensnoop -p 81

Trace failed open() syscalls:

# opensnoop -x

Trace open() syscalls for filenames containing "conf":

# opensnoop conf

Trace open() syscalls for filenames ending in "log":

# opensnoop 'log$'

---

✨ FIELDS ✨

• TIMEs — time of open() completion, in units of seconds. ⏱️
• COMM — process name (if known).
• PID — process ID.
• FD — file descriptor. If this is a successful open, the file descriptor number is shown. If this is unsuccessful, -1 is shown. Numbers beginning with 0x are hexadecimal. 🧮
• FILE — filename (pathname) used by the open() syscall.

---

✨ OVERHEAD ✨

She reads open() syscalls and getname() kernel functions as they occur. For high rates of opens (> 500/s), the overhead may begin to be measurable. Test yourself, bestie, don't just take my word for it. You can use the -d mode to buffer output, reducing overheads. 🫶

---

✨ SOURCE ✨

This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool. 💖

---

✨ OS ✨

Linux 🐧

---

✨ STABILITY ✨

Unstable - in development. she's a work in progress and that's her journey 🌱

---

✨ AUTHOR ✨

Brendan Gregg 👑

---

✨ SEE ALSO ✨

execsnoop(8), strace(1)

---

and that's the whole vibe check, bestie 💅 this page came straight out of the USER COMMANDS section, dated 2014-07-20 — yes she's vintage, yes she still eats. go trace something, ily 🦋💖