pr_open.rst (4850B)
1 PR_Open 2 ======= 3 4 Opens a file for reading, writing, or both. Also used to create a file. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prio.h> 13 14 PRFileDesc* PR_Open( 15 const char *name, 16 PRIntn flags, 17 PRIntn mode); 18 19 20 Parameters 21 ~~~~~~~~~~ 22 23 The function has the following parameters: 24 25 ``name`` 26 The pathname of the file to be opened. 27 ``flags`` 28 The file status flags define how the file is accessed. It is a 29 bitwise ``OR`` of the following bit flags. In most cases, only one of 30 the first three flags may be used. If the ``flags`` parameter does 31 not include any of the first three flags (``PR_RDONLY``, 32 ``PR_WRONLY``, or ``PR_RDWR``), the open file can't be read or 33 written, which is not useful. 34 35 .. note:: 36 37 The constants PR_RDWR and friends are not in any interface 38 (`bug 433295 <https://bugzilla.mozilla.org/show_bug.cgi?id=433295>`__). 39 Thus they cannot be used in JavaScript, you have to use the octal 40 constants (see `File I/O Snippets </en/Code_snippets:File_I/O>`__). 41 42 +--------------------+-------+---------------------------------------+ 43 | Name | Value | Description | 44 +====================+=======+=======================================+ 45 | ``PR_RDONLY`` | 0x01 | Open for reading only. | 46 +--------------------+-------+---------------------------------------+ 47 | ``PR_WRONLY`` | 0x02 | Open for writing only. | 48 +--------------------+-------+---------------------------------------+ 49 | ``PR_RDWR`` | 0x04 | Open for reading and writing. | 50 +--------------------+-------+---------------------------------------+ 51 | ``PR_CREATE_FILE`` | 0x08 | If the file does not exist, the file | 52 | | | is created. If the file exists, this | 53 | | | flag has no effect. | 54 +--------------------+-------+---------------------------------------+ 55 | ``PR_APPEND`` | 0x10 | The file pointer is set to the end of | 56 | | | the file prior to each write. | 57 +--------------------+-------+---------------------------------------+ 58 | ``PR_TRUNCATE`` | 0x20 | If the file exists, its length is | 59 | | | truncated to 0. | 60 +--------------------+-------+---------------------------------------+ 61 | ``PR_SYNC`` | 0x40 | If set, each write will wait for both | 62 | | | the file data and file status to be | 63 | | | physically updated. | 64 +--------------------+-------+---------------------------------------+ 65 | ``PR_EXCL`` | 0x80 | With ``PR_CREATE_FILE``, if the file | 66 | | | does not exist, the file is created. | 67 | | | If the file already exists, no action | 68 | | | and NULL is returned. | 69 +--------------------+-------+---------------------------------------+ 70 71 72 73 ``mode`` 74 When ``PR_CREATE_FILE`` flag is set and the file is created, these 75 flags define the access permission bits of the newly created file. 76 This feature is currently only applicable on Unix platforms. It is 77 ignored by any other platform but it may apply to other platforms in 78 the future. Possible values of the ``mode`` parameter are listed in 79 the table below. 80 81 ============ ===== ===================================== 82 Name Value Description 83 ============ ===== ===================================== 84 ``PR_IRWXU`` 0700 read, write, execute/search by owner. 85 ``PR_IRUSR`` 0400 read permission, owner. 86 ``PR_IWUSR`` 0200 write permission, owner. 87 ``PR_IXUSR`` 0100 execute/search permission, owner. 88 ``PR_IRWXG`` 0070 read, write, execute/search by group 89 ``PR_IRGRP`` 0040 read permission, group 90 ``PR_IWGRP`` 0020 write permission, group 91 ``PR_IXGRP`` 0010 execute/search permission, group 92 ``PR_IRWXO`` 0007 read, write, execute/search by others 93 ``PR_IROTH`` 0004 read permission, others 94 ``PR_IWOTH`` 0002 write permission, others 95 ``PR_IXOTH`` 0001 execute/search permission, others 96 ============ ===== ===================================== 97 98 99 Returns 100 ~~~~~~~ 101 102 The function returns one of the following values: 103 104 - If the file is successfully opened, a pointer to a dynamically 105 allocated :ref:`PRFileDesc` for the newly opened file. The 106 :ref:`PRFileDesc` should be freed by calling :ref:`PR_Close`. 107 - If the file was not opened successfully, a ``NULL`` pointer. 108 109 110 Description 111 ----------- 112 113 :ref:`PR_Open` creates a file descriptor (:ref:`PRFileDesc`) for the file with 114 the pathname ``name`` and sets the file status flags of the file 115 descriptor according to the value of ``flags``. If a new file is created 116 as a result of the :ref:`PR_Open` call, its file mode bits are set 117 according to the ``mode`` parameter.