This is an automated email from the ASF dual-hosted git repository.
xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 6a71c893805 Documentation/grep: Add grep command documentation
6a71c893805 is described below
commit 6a71c893805d3210f6e6442d148b65ca325720b2
Author: Junbo Zheng <[email protected]>
AuthorDate: Fri Aug 28 23:13:45 2026 +0800
Documentation/grep: Add grep command documentation
Add a user documentation page for the grep system command covering
overview, configuration options, usage, options, exit status and
examples. The command lives in apps/system/grep and is enabled with
CONFIG_SYSTEM_GREP (depends on CONFIG_LIBC_REGEX).
This documents the command added in
https://github.com/apache/nuttx-apps/pull/3741.
Signed-off-by: Junbo Zheng <[email protected]>
---
Documentation/applications/system/grep/index.rst | 128 +++++++++++++++++++++++
1 file changed, 128 insertions(+)
diff --git a/Documentation/applications/system/grep/index.rst
b/Documentation/applications/system/grep/index.rst
new file mode 100644
index 00000000000..e8723005fd7
--- /dev/null
+++ b/Documentation/applications/system/grep/index.rst
@@ -0,0 +1,128 @@
+==============================
+``grep`` system 'grep' command
+==============================
+
+Overview
+========
+
+The ``grep`` command searches for lines matching a regular expression in
+text files (or standard input). It uses the NuttX libc regular expression
+library (``regcomp`` / ``regexec``), so it supports real regular
+expressions including anchors (``^``, ``$``) and character classes
+(``[...]``), not just fixed substring matching.
+
+By default ``grep`` reads from ``stdin`` when no file is given, which
+makes it useful in NSH pipelines. When more than one file is searched (or
+when recursing into directories), the matching file name is prefixed to
+each result line.
+
+Configuration
+=============
+
+Enable the command with ``CONFIG_SYSTEM_GREP``. This option depends on
+``CONFIG_LIBC_REGEX`` and is disabled by default.
+
+The following configuration options are available:
+
+``CONFIG_SYSTEM_GREP_PROGNAME``
+ Program name for the ``grep`` command. Default: ``grep``.
+
+``CONFIG_SYSTEM_GREP_PRIORITY``
+ Task priority for the ``grep`` command. Default: 100.
+
+``CONFIG_SYSTEM_GREP_STACKSIZE``
+ Stack size for the ``grep`` command. Default:
+ ``DEFAULT_TASK_STACKSIZE``.
+
+Usage
+=====
+
+.. code-block:: console
+
+ grep [-invrHh] <pattern> [<file>...]
+
+When no ``<file>`` is given, ``grep`` reads from ``stdin``.
+
+Options
+=======
+
+``-i``
+ Case-insensitive match.
+
+``-n``
+ Prefix each matching line with its 1-based line number.
+
+``-v``
+ Invert the match: select lines that do **not** match.
+
+``-r``
+ Recurse into subdirectories. When set, the file name is always prefixed
+ to each result.
+
+``-H``
+ Always print the file name prefix, even with a single input file.
+
+``-h``
+ Never print the file name prefix.
+
+Exit status
+===========
+
+``0``
+ At least one line matched.
+
+``1``
+ No line matched.
+
+``2``
+ An error occurred (invalid option, unreadable file, bad regex, ...).
+
+Examples
+========
+
+Search ``stdin`` for lines containing ``error``:
+
+.. code-block:: console
+
+ nsh> dmesg | grep error
+
+Case-insensitive search with line numbers:
+
+.. code-block:: console
+
+ nsh> grep -in error /tmp/log.txt
+
+Invert the match (print non-matching lines):
+
+.. code-block:: console
+
+ nsh> grep -v error /tmp/log.txt
+
+Regular expression anchor -- match lines starting with ``ERR``:
+
+.. code-block:: console
+
+ nsh> grep "^ERR" /tmp/log.txt
+
+Recurse a directory, always printing the file name:
+
+.. code-block:: console
+
+ nsh> grep -r -H TODO /data/src
+
+Pipe usage -- filter the output of another NSH command:
+
+.. code-block:: console
+
+ nsh> ps | grep work
+
+Notes
+=====
+
+- ``grep`` is built on the libc regex library; ``CONFIG_SYSTEM_GREP``
+ depends on ``CONFIG_LIBC_REGEX``, so both must be enabled to satisfy the
+ ``regcomp`` / ``regexec`` dependency.
+- The ``-r`` option implies multi-file mode, so the file name is always
+ prefixed regardless of ``-H`` / ``-h``.
+- Long lines are truncated at ``GREP_LINE_MAX`` (512 bytes); matching is
+ performed on the (newline-stripped) content of each line.
