diff options
Diffstat (limited to '')
-rw-r--r-- | docs/nspr/reference/pr_readdir.rst | 93 |
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` |