# PR_CreateFileMap

Creates a file mapping object.

## Syntax

```{code}
#include <prio.h>

PRFileMap* PR_CreateFileMap(
  PRFileDesc *fd,
  PRInt64 size,
  PRFileMapProtect prot);
```

### Parameters

The function has the following parameters:

`fd`

: A pointer to a {ref}`PRFileDesc` object representing the file that is to
  be mapped to memory.

`size`

: Size of the file specified by `fd`.

`prot`

: Protection option for read and write accesses of a file mapping. This
  parameter consists of one of the following options:

> - `PR_PROT_READONLY`. Read-only access.
> - `PR_PROT_READWRITE`. Readable, and write is shared.
> - `PR_PROT_WRITECOPY`. Readable, and write is private
  >   (copy-on-write).

### Returns

- If successful, a file mapping of type {ref}`PRFileMap`.
- If unsuccessful, `NULL`.

## Description

The `PRFileMapProtect` enumeration used in the `prot` parameter is
defined as follows:

```{code}
typedef enum PRFileMapProtect {
  PR_PROT_READONLY,
  PR_PROT_READWRITE,
  PR_PROT_WRITECOPY
} PRFileMapProtect;
```

{ref}`PR_CreateFileMap` only prepares for the mapping a file to memory. The
returned file-mapping object must be passed to {ref}`PR_MemMap` to actually
map a section of the file to memory.

The file-mapping object should be closed with a {ref}`PR_CloseFileMap` call
when it is no longer needed.