# 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:

> - `PR_SKIP_NONE`. Do not skip any files.
> - `PR_SKIP_DOT`. Skip the directory entry "." representing the
  >   current directory.
> - `PR_SKIP_DOT_DOT`. Skip the directory entry ".." representing
  >   the parent directory.
> - `PR_SKIP_BOTH`. Skip both "." and ".."
> - `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`