Source code
Revision control
Copy as Markdown
Other Tools
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
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.