From 0d080223a8567a5ef673deb6ac49152fd67dd1b7 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sat, 16 Dec 2023 18:03:13 +0000
Subject: [PATCH] file: Further rework documentation of dir= parameter

Move the documentation to a new section, allowing us to expand on this
topic.  This also makes the HTML documentation linkable.

Updates: commit 7cbd49ced6414e49fcf4ff1a967929a2b83ab44e
(cherry picked from commit 74621ec608d0edd76c2d8de140e7d1d5626c8251)
---
 plugins/file/nbdkit-file-plugin.pod | 66 +++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 17 deletions(-)

diff --git a/plugins/file/nbdkit-file-plugin.pod b/plugins/file/nbdkit-file-plugin.pod
index 5feb8ea9..de8fbeba 100644
--- a/plugins/file/nbdkit-file-plugin.pod
+++ b/plugins/file/nbdkit-file-plugin.pod
@@ -63,23 +63,7 @@ directory named C<DIRECTORY>, including those found by following
 symbolic links.  Other special files in the directory (such as
 subdirectories, pipes, or Unix sockets) are ignored.
 
-When this mode is used, the file to be served is chosen by the export
-name passed by the client.  For security, when using directory mode,
-this plugin will not accept export names containing slash (C</>).
-
-To list exports, use L<nbdinfo(1)> I<--list> option, for example:
-
- nbdinfo --list nbd://localhost
-
-An NBD client can request a list of available exports using
-C<NBD_OPT_LIST>.
-
-A client that requests the default export (C<"">) will be rejected.
-However, you can use L<nbdkit-exportname-filter(1)> to adjust what
-export names the client sees, and which one the client uses as a
-default.  For example to make F</dir/file> be the default export:
-
- nbdkit file dir=/dir --filter=exportname default-export=file
+See L</Serving multiple files and block devices> below.
 
 =item B<dirfd=>FILE_DESCRIPTOR
 
@@ -89,6 +73,8 @@ This is like the C<dir=> option, but instead of specifying the
 directory by name, the parent process should open the directory and
 pass this file descriptor by inheritance to nbdkit.
 
+See L</Serving multiple files and block devices> below.
+
 =item B<fadvise=normal>
 
 =item B<fadvise=random>
@@ -140,6 +126,52 @@ L<https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-devi
 
 =head1 NOTES
 
+=head2 Serving multiple files and block devices
+
+Using C<dir=DIRECTORY> (or C<dirfd=DIRFD>) you can serve all regular
+files and block devices located directly inside the directory named
+C<DIRECTORY>, including those found by following symbolic links.
+Other special files in the directory (such as subdirectories, pipes,
+or Unix sockets) are ignored.
+
+When this mode is used, the file to be served is chosen by the export
+name passed by the client.  For security, when using directory mode,
+this plugin will not accept export names containing slash (C</>).
+
+For example:
+
+ $ ls -l /var/tmp/exports
+ total 0
+ -rw-r--r--. 1 rjones rjones 1048576 Dec 14 15:34 disk1
+ -rw-r--r--. 1 rjones rjones 2097152 Dec 14 15:34 disk2
+ lrwxrwxrwx. 1 rjones rjones       9 Dec 14 15:35 sda1 -> /dev/sda1
+ $ nbdkit file dir=/var/tmp/exports
+
+will serve three exports called C<"disk1">, C<"disk2"> and C<"sda1">.
+The first two are regular files and the last is a block device.  You
+can add or remove files or symbolic links from the directory while
+nbdkit is running.
+
+To list exports, use L<nbdinfo(1)> I<--list> option, for example:
+
+ $ nbdinfo --list nbd://localhost
+ protocol: newstyle-fixed without TLS, using structured packets
+ export="disk1":
+     export-size: 1048576 (1M)
+     uri: nbd://localhost:10809/disk1
+ [etc]
+
+An NBD client can request a list of available exports using
+C<NBD_OPT_LIST>.  For libnbd clients see nbd_opt_list(3).
+
+A client that requests the default export (C<"">) will be rejected.
+However, you can use L<nbdkit-exportname-filter(1)> to adjust the
+default export as well as other transformations of export names.  For
+example to make F</var/tmp/exports/disk1> be the default export:
+
+ nbdkit file dir=/var/tmp/exports \
+        --filter=exportname default-export=disk1
+
 =head2 Optimizing for random or sequential access
 
 If you know in advance that the NBD client will access the file
-- 
2.39.3