[PATCH] docs/system: Clarify local filename escaping in device URLs

[PATCH] docs/system: Clarify local filename escaping in device URLs

[nanliu]

The documentation currently lacks explicit information on how to escape
a local filename if it contains characters that cause it to be parsed
as a protocol (e.g., containing a ':').

Use two methods to avoid this:
1. use the explicit prefix ``file:`` (e.g. ``-cdrom file:foo:bar.iso``).
2. use a path with ``./`` in it (e.g. ``-cdrom ./foo:bar.iso``)

Fixes: https://gitlab.com/qemu-project/qemu/-/issues/3072

Signed-off-by: nanliu <nanliu@redhat.com>
---
 docs/system/device-url-syntax.rst.inc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/system/device-url-syntax.rst.inc b/docs/system/device-url-syntax.rst.inc
index 43b5c2596b..e7aa2be721 100644
--- a/docs/system/device-url-syntax.rst.inc
+++ b/docs/system/device-url-syntax.rst.inc
@@ -43,6 +43,14 @@ These are specified using a special URL syntax.
       LIBISCSI_CHAP_PASSWORD="password" \\
       |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
 
+   Note on path parsing: If a local filename used with a device
+   option (e.g., ``-cdrom``) contains a colon (``:``), QEMU may
+   interpret it as a URL protocol; use the explicit prefix ``file:``
+   (e.g. ``-cdrom file:foo:bar.iso``) or a path with ``./`` in it
+   (e.g. ``-cdrom ./foo:bar.iso``) to ensure correct local file
+   resolution, and avoid using ``file://`` which may lead to
+   incorrect path resolution.
+
 ``NBD``
    QEMU supports NBD (Network Block Devices) both using TCP protocol as
    well as Unix Domain Sockets. With TCP, the default port is 10809.
-- 
2.51.1