From 03b6b4dd5372560db1eccabd854ca527697a191f Mon Sep 17 00:00:00 2001
From: Raphael Campos <raphaelcampos.rp@gmail.com>
Date: Tue, 3 Dec 2024 14:55:55 -0600
Subject: [PATCH] docs(filters): add restrictions when kernel data filter is
 used

- Add the restrictions applicable when the kernel-space data filter is
available for an event field.
---
 docs/docs/flags/events.1.md | 15 +++++++++++++--
 docs/man/events.1           | 21 ++++++++++++++++++++-
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/docs/docs/flags/events.1.md b/docs/docs/flags/events.1.md
index 72c135f8bd22..8137452c788e 100644
--- a/docs/docs/flags/events.1.md
+++ b/docs/docs/flags/events.1.md
@@ -2,7 +2,7 @@
 title: TRACEE-EVENTS
 section: 1
 header: Tracee Events Flag Manual
-date: 2024/06
+date: 2024/12
 ...
 
 ## NAME
@@ -54,7 +54,12 @@ Available for:
 - return value
 - scope fields
 
-Strings can be compared as a prefix if ending with '\*', or as a suffix if starting with '\*'.
+Strings can be compared as a prefix if ending with '\*', or as a suffix if starting with '\*'.  If a string starts with '\*' and ends with '\*', it functions as a contains operator.
+
+For certain event fields filtered in kernel space, the user will receive a warning if:
+
+- String filters exceed 255 characters.
+- The contains operator is used. Only exact matches, prefix, and suffix comparisons are allowed.
 
 NOTE: Expressions containing '\*' token must be escaped!
 
@@ -116,6 +121,12 @@ Available only for:
   --events openat.data.pathname='*shadow'
   ```
 
+- To trace only 'openat' events that have 'pathname' contains the substring 'pass', use the following flag:
+
+  ```console
+  --events openat.data.pathname='*pass*'
+  ```
+
 - To exclude 'openat' events that have 'pathname' equal to '/tmp/1' or '/bin/ls', use the following flag:
 
   ```console
diff --git a/docs/man/events.1 b/docs/man/events.1
index 1a2d745c544b..284870c76875 100644
--- a/docs/man/events.1
+++ b/docs/man/events.1
@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "TRACEE\-EVENTS" "1" "2024/06" "" "Tracee Events Flag Manual"
+.TH "TRACEE\-EVENTS" "1" "2024/12" "" "Tracee Events Flag Manual"
 .SS NAME
 tracee \f[B]\-\-events\f[R] \- Select which events to trace
 .SS SYNOPSIS
@@ -68,6 +68,16 @@ scope fields
 .PP
 Strings can be compared as a prefix if ending with `*', or as a suffix
 if starting with `*'.
+If a string starts with `*' and ends with `*', it functions as a
+contains operator.
+.PP
+For certain event fields filtered in kernel space, the user will receive
+a warning if:
+.IP \[bu] 2
+String filters exceed 255 characters.
+.IP \[bu] 2
+The contains operator is used.
+Only exact matches, prefix, and suffix comparisons are allowed.
 .PP
 NOTE: Expressions containing `*' token must be escaped!
 .SS EXCLUSION OPERATOR (PREPENDED)
@@ -147,6 +157,15 @@ use the following flag:
 .EE
 .RE
 .IP \[bu] 2
+To trace only `openat' events that have `pathname' contains the
+substring `pass', use the following flag:
+.RS 2
+.IP
+.EX
+\-\-events openat.data.pathname=\[aq]*pass*\[aq]
+.EE
+.RE
+.IP \[bu] 2
 To exclude `openat' events that have `pathname' equal to `/tmp/1' or
 `/bin/ls', use the following flag:
 .RS 2