This is an automated email from the ASF dual-hosted git repository.
acassis 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 8bddb558ccf Documentation: Document hostname command.
8bddb558ccf is described below
commit 8bddb558ccf8b4a9491063efdf1b4544934e1308
Author: hanzhijian <[email protected]>
AuthorDate: Wed May 27 13:09:15 2026 +0800
Documentation: Document hostname command.
Add documentation for the hostname command, which displays or
sets the system hostname.
Refs #11081
Signed-off-by: hanzj <[email protected]>
---
.../applications/system/hostname/index.rst | 96 ++++++++++++++++++++++
1 file changed, 96 insertions(+)
diff --git a/Documentation/applications/system/hostname/index.rst
b/Documentation/applications/system/hostname/index.rst
index 7b9d335be85..5d3f7fd86e0 100644
--- a/Documentation/applications/system/hostname/index.rst
+++ b/Documentation/applications/system/hostname/index.rst
@@ -1,3 +1,99 @@
===============================
``hostname`` "hostname" command
===============================
+
+Overview
+========
+
+The ``hostname`` command displays or sets the system hostname. When called
+without arguments, it prints the current hostname. When called with a
+hostname argument, it sets the system hostname to the specified value.
+
+The hostname is stored in the kernel and can be retrieved by applications
+using the ``gethostname()`` system call. It is typically used to identify
+the system on a network and in shell prompts.
+
+Configuration
+=============
+
+Enable the command with ``CONFIG_SYSTEM_HOSTNAME``. This option has no
+additional dependencies.
+
+Usage
+=====
+
+.. code-block:: console
+
+ hostname
+
+Display the current system hostname.
+
+.. code-block:: console
+
+ hostname <hostname>
+
+Set the system hostname to ``<hostname>``.
+
+.. code-block:: console
+
+ hostname -F <file>
+
+Read the hostname from the specified file and set it as the system hostname.
+
+Options
+=======
+
+``-F <file>``
+ Read the hostname from the specified file. The first line of the file
+ is used as the hostname. Trailing newlines are stripped.
+
+``-h``
+ Display usage information and exit.
+
+Examples
+========
+
+Display the current hostname:
+
+.. code-block:: console
+
+ nsh> hostname
+ nuttx
+
+Set a new hostname:
+
+.. code-block:: console
+
+ nsh> hostname mydevice
+ nsh> hostname
+ mydevice
+
+Read hostname from a file:
+
+.. code-block:: console
+
+ nsh> cat /etc/hostname
+ embedded-device
+ nsh> hostname -F /etc/hostname
+ nsh> hostname
+ embedded-device
+
+Display usage information:
+
+.. code-block:: console
+
+ nsh> hostname -h
+ Usage: hostname [<hostname>|-F <file>]
+
+Notes
+=====
+
+- The hostname must be between 1 and ``HOST_NAME_MAX`` characters long.
+- Setting an empty hostname or a hostname longer than ``HOST_NAME_MAX``
+ will result in an error.
+- The hostname is stored in the kernel and persists until the system is
+ rebooted or the hostname is changed again.
+- The ``-F`` option reads only the first line of the specified file and
+ strips any trailing newline characters.
+- If both a hostname argument and the ``-F`` option are provided, the
+ ``-F`` option takes precedence.
