diff options
Diffstat (limited to 'docs/nspr/reference/pr_open.rst')
| -rw-r--r-- | docs/nspr/reference/pr_open.rst | 117 |
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. |