Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 117 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_open.rst b/docs/nspr/reference/pr_open.rst
new file mode 100644
index 0000000000..1dba4d6a56
--- /dev/null
+++ b/docs/nspr/reference/pr_open.rst
@@ -0,0 +1,117 @@
+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::
+
+   **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.