91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# PR_Open
|
|
|
|
Opens a file for reading, writing, or both. Also used to create a file.
|
|
|
|
## Syntax
|
|
|
|
```{code}
|
|
#include <prio.h>
|
|
|
|
PRFileDesc* PR_Open(
|
|
const char *name,
|
|
PRIntn flags,
|
|
PRIntn mode);
|
|
```
|
|
|
|
### Parameters
|
|
|
|
The function has the following parameters:
|
|
|
|
`name`
|
|
|
|
: The pathname of the file to be opened.
|
|
|
|
`flags`
|
|
|
|
: The file status flags define how the file is accessed. It is a
|
|
bitwise `OR` of the following bit flags. In most cases, only one of
|
|
the first three flags may be used. If the `flags` parameter does
|
|
not include any of the first three flags (`PR_RDONLY`,
|
|
`PR_WRONLY`, or `PR_RDWR`), the open file can't be read or
|
|
written, which is not useful.
|
|
|
|
:::{note}
|
|
The constants PR_RDWR and friends are not in any interface
|
|
([bug 433295](https://bugzilla.mozilla.org/show_bug.cgi?id=433295)).
|
|
Thus they cannot be used in JavaScript, you have to use the octal
|
|
constants (see [File I/O Snippets](/en/Code_snippets:File_I/O)).
|
|
:::
|
|
|
|
| Name | Value | Description |
|
|
| ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `PR_RDONLY` | 0x01 | Open for reading only. |
|
|
| `PR_WRONLY` | 0x02 | Open for writing only. |
|
|
| `PR_RDWR` | 0x04 | Open for reading and writing. |
|
|
| `PR_CREATE_FILE` | 0x08 | If the file does not exist, the file is created. If the file exists, this flag has no effect. |
|
|
| `PR_APPEND` | 0x10 | The file pointer is set to the end of the file prior to each write. |
|
|
| `PR_TRUNCATE` | 0x20 | If the file exists, its length is truncated to 0. |
|
|
| `PR_SYNC` | 0x40 | If set, each write will wait for both the file data and file status to be physically updated. |
|
|
| `PR_EXCL` | 0x80 | With `PR_CREATE_FILE`, if the file does not exist, the file is created. If the file already exists, no action and NULL is returned. |
|
|
|
|
`mode`
|
|
|
|
: When `PR_CREATE_FILE` flag is set and the file is created, these
|
|
flags define the access permission bits of the newly created file.
|
|
This feature is currently only applicable on Unix platforms. It is
|
|
ignored by any other platform but it may apply to other platforms in
|
|
the future. Possible values of the `mode` parameter are listed in
|
|
the table below.
|
|
|
|
| Name | Value | Description |
|
|
| ---------- | ----- | ------------------------------------- |
|
|
| `PR_IRWXU` | 0700 | read, write, execute/search by owner. |
|
|
| `PR_IRUSR` | 0400 | read permission, owner. |
|
|
| `PR_IWUSR` | 0200 | write permission, owner. |
|
|
| `PR_IXUSR` | 0100 | execute/search permission, owner. |
|
|
| `PR_IRWXG` | 0070 | read, write, execute/search by group |
|
|
| `PR_IRGRP` | 0040 | read permission, group |
|
|
| `PR_IWGRP` | 0020 | write permission, group |
|
|
| `PR_IXGRP` | 0010 | execute/search permission, group |
|
|
| `PR_IRWXO` | 0007 | read, write, execute/search by others |
|
|
| `PR_IROTH` | 0004 | read permission, others |
|
|
| `PR_IWOTH` | 0002 | write permission, others |
|
|
| `PR_IXOTH` | 0001 | execute/search permission, others |
|
|
|
|
### Returns
|
|
|
|
The function returns one of the following values:
|
|
|
|
- If the file is successfully opened, a pointer to a dynamically
|
|
allocated {ref}`PRFileDesc` for the newly opened file. The
|
|
{ref}`PRFileDesc` should be freed by calling {ref}`PR_Close`.
|
|
- If the file was not opened successfully, a `NULL` pointer.
|
|
|
|
## Description
|
|
|
|
{ref}`PR_Open` creates a file descriptor ({ref}`PRFileDesc`) for the file with
|
|
the pathname `name` and sets the file status flags of the file
|
|
descriptor according to the value of `flags`. If a new file is created
|
|
as a result of the {ref}`PR_Open` call, its file mode bits are set
|
|
according to the `mode` parameter.
|