From db75c8b17549fdfa23cc8622770d257fa0d7420f Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Tue, 10 Mar 2026 23:07:27 +0200 Subject: file: document File interface semantics (task 399) --- internal/file/file.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'internal') diff --git a/internal/file/file.go b/internal/file/file.go index 8510b61..ab67fe2 100644 --- a/internal/file/file.go +++ b/internal/file/file.go @@ -12,6 +12,19 @@ import ( ) // File is the common interface for file-like syscall payload representations. +// +// Implementations may represent either a live file descriptor-backed handle +// (FdFile) or partial path metadata for syscalls that do not resolve to a +// stable descriptor (for example rename-like or pathname-only events). +// +// Semantics: +// - Name returns the best single-path identifier for the event. For +// rename-like events this is the "new" path; for pathname-only events it is +// the observed pathname. +// - Flags returns open flags when known, otherwise unknownFlag. +// - FD returns the tracked file descriptor when one exists, otherwise -1. +// - String returns a human-readable representation suitable for TUI/CSV use +// and should remain informative even when Name or FD are unavailable. type File interface { String() string Name() string -- cgit v1.2.3