summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/pr_open.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
commit6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch)
treea68f146d7fa01f0134297619fbe7e33db084e0aa /docs/nspr/reference/pr_open.rst
parentInitial commit. (diff)
downloadthunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.tar.xz
thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.zip
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference/pr_open.rst')
-rw-r--r--docs/nspr/reference/pr_open.rst117
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.