forked from mirrors/gecko-dev
117 lines
4.7 KiB
ReStructuredText
117 lines
4.7 KiB
ReStructuredText
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.
|