pr_readdir.rst (2239B)
1 PR_ReadDir 2 ========== 3 4 Gets a pointer to the next entry in the directory. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prio.h> 13 14 PRDirEntry* PR_ReadDir( 15 PRDir *dir, 16 PRDirFlags flags); 17 18 19 Parameters 20 ~~~~~~~~~~ 21 22 The function has the following parameters: 23 24 ``dir`` 25 A pointer to a :ref:`PRDir` object that designates an open directory. 26 ``flags`` 27 Specifies which directory entries, if any, to skip. Values can 28 include the following: 29 30 - :ref:`PR_SKIP_NONE`. Do not skip any files. 31 - :ref:`PR_SKIP_DOT`. Skip the directory entry "." representing the 32 current directory. 33 - :ref:`PR_SKIP_DOT_DOT`. Skip the directory entry ".." representing 34 the parent directory. 35 - :ref:`PR_SKIP_BOTH`. Skip both "." and ".." 36 - :ref:`PR_SKIP_HIDDEN`. Skip hidden files. On Windows platforms and 37 the Mac OS, this value identifies files with the "hidden" 38 attribute set. On Unix platform, this value identifies files whose 39 names begin with a period ("."). 40 41 42 Returns 43 ~~~~~~~ 44 45 - A pointer to the next entry in the directory. 46 - If the end of the directory is reached or an error occurs, ``NULL``. 47 The reason can be retrieved via :ref:`PR_GetError`. 48 49 50 Description 51 ----------- 52 53 :ref:`PR_ReadDir` returns a pointer to a directory entry structure: 54 55 .. code:: 56 57 struct PRDirEntry { 58 const char *name; 59 }; 60 61 typedef struct PRDirEntry PRDirEntry; 62 63 The structure has the following field: 64 65 ``name`` 66 Name of entry, relative to directory name. 67 68 The ``flags`` parameter is an enum of type ``PRDirFlags``: 69 70 .. code:: 71 72 typedef enum PRDirFlags { 73 PR_SKIP_NONE = 0x0, 74 PR_SKIP_DOT = 0x1, 75 PR_SKIP_DOT_DOT = 0x2, 76 PR_SKIP_BOTH = 0x3, 77 PR_SKIP_HIDDEN = 0x4 78 } PRDirFlags; 79 80 The memory associated with the returned PRDirEntry structure is managed 81 by NSPR. The caller must not free the ``PRDirEntry`` structure. 82 Moreover, the ``PRDirEntry`` structure returned by each :ref:`PR_ReadDir` 83 call is valid only until the next :ref:`PR_ReadDir` or :ref:`PR_CloseDir` call 84 on the same :ref:`PRDir` object. 85 86 If the end of the directory is reached, :ref:`PR_ReadDir` returns ``NULL``, 87 and :ref:`PR_GetError` returns ``PR_NO_MORE_FILES_ERROR``. 88 89 90 See Also 91 -------- 92 93 :ref:`PR_OpenDir`