Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 93 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_readdir.rst b/docs/nspr/reference/pr_readdir.rst
new file mode 100644
index 0000000000..1379b694c9
--- /dev/null
+++ b/docs/nspr/reference/pr_readdir.rst
@@ -0,0 +1,93 @@
+PR_ReadDir
+==========
+
+Gets a pointer to the next entry in the directory.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prio.h>
+
+   PRDirEntry* PR_ReadDir(
+     PRDir *dir,
+     PRDirFlags flags);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameters:
+
+``dir``
+   A pointer to a :ref:`PRDir` object that designates an open directory.
+``flags``
+   Specifies which directory entries, if any, to skip. Values can
+   include the following:
+
+    - :ref:`PR_SKIP_NONE`. Do not skip any files.
+    - :ref:`PR_SKIP_DOT`. Skip the directory entry "." representing the
+      current directory.
+    - :ref:`PR_SKIP_DOT_DOT`. Skip the directory entry ".." representing
+      the parent directory.
+    - :ref:`PR_SKIP_BOTH`. Skip both "." and ".."
+    - :ref:`PR_SKIP_HIDDEN`. Skip hidden files. On Windows platforms and
+      the Mac OS, this value identifies files with the "hidden"
+      attribute set. On Unix platform, this value identifies files whose
+      names begin with a period (".").
+
+
+Returns
+~~~~~~~
+
+-  A pointer to the next entry in the directory.
+-  If the end of the directory is reached or an error occurs, ``NULL``.
+   The reason can be retrieved via :ref:`PR_GetError`.
+
+
+Description
+-----------
+
+:ref:`PR_ReadDir` returns a pointer to a directory entry structure:
+
+.. code::
+
+   struct PRDirEntry {
+     const char *name;
+   };
+
+   typedef struct PRDirEntry PRDirEntry;
+
+The structure has the following field:
+
+``name``
+   Name of entry, relative to directory name.
+
+The ``flags`` parameter is an enum of type ``PRDirFlags``:
+
+.. code::
+
+   typedef enum PRDirFlags {
+     PR_SKIP_NONE    = 0x0,
+     PR_SKIP_DOT     = 0x1,
+     PR_SKIP_DOT_DOT = 0x2,
+     PR_SKIP_BOTH    = 0x3,
+     PR_SKIP_HIDDEN  = 0x4
+   } PRDirFlags;
+
+The memory associated with the returned PRDirEntry structure is managed
+by NSPR. The caller must not free the ``PRDirEntry`` structure.
+Moreover, the ``PRDirEntry`` structure returned by each :ref:`PR_ReadDir`
+call is valid only until the next :ref:`PR_ReadDir` or :ref:`PR_CloseDir` call
+on the same :ref:`PRDir` object.
+
+If the end of the directory is reached, :ref:`PR_ReadDir` returns ``NULL``,
+and :ref:`PR_GetError` returns ``PR_NO_MORE_FILES_ERROR``.
+
+
+See Also
+--------
+
+:ref:`PR_OpenDir`