pr_seek.rst (2480B)
1 PR_Seek 2 ======= 3 4 Moves the current read-write file pointer by an offset expressed as a 5 32-bit integer. 6 7 .. container:: blockIndicator deprecated deprecatedHeader 8 9 | **Deprecated** 10 | This feature is no longer recommended. Though some browsers might 11 still support it, it may have already been removed from the 12 relevant web standards, may be in the process of being dropped, or 13 may only be kept for compatibility purposes. Avoid using it, and 14 update existing code if possible; see the `compatibility 15 table <#Browser_compatibility>`__ at the bottom of this page to 16 guide your decision. Be aware that this feature may cease to work 17 at any time. 18 19 Deprecated in favor of :ref:`PR_Seek64`. 20 21 22 Syntax 23 ~~~~~~ 24 25 .. code:: 26 27 #include <prio.h> 28 29 PRInt32 PR_Seek( 30 PRFileDesc *fd, 31 PRInt32 offset, 32 PRSeekWhence whence); 33 34 35 Parameters 36 ~~~~~~~~~~ 37 38 The function has the following parameters: 39 40 ``fd`` 41 A pointer to a :ref:`PRFileDesc` object. 42 ``offset`` 43 A value, in bytes, used with the whence parameter to set the file 44 pointer. A negative value causes seeking in the reverse direction. 45 ``whence`` 46 A value of type :ref:`PRSeekWhence` that specifies how to interpret the 47 ``offset`` parameter in setting the file pointer associated with the 48 fd parameter. The value for the ``whence`` parameter can be one of 49 the following: 50 51 - :ref:`PR_SEEK_SET`. Sets the file pointer to the value of the 52 ``offset`` parameter. 53 - :ref:`PR_SEEK_CUR`. Sets the file pointer to its current location 54 plus the value of the ``offset`` parameter. 55 - :ref:`PR_SEEK_END`. Sets the file pointer to the size of the file 56 plus the value of the ``offset`` parameter. 57 58 59 Returns 60 ~~~~~~~ 61 62 The function returns one of the following values: 63 64 - If the function completes successfully, it returns the resulting file 65 pointer location, measured in bytes from the beginning of the file. 66 - If the function fails, the file pointer remains unchanged and the 67 function returns -1. The error code can then be retrieved with 68 :ref:`PR_GetError`. 69 70 71 Description 72 ----------- 73 74 Here's an idiom for obtaining the current location of the file pointer 75 for the file descriptor ``fd``: 76 77 ``PR_Seek(fd, 0, PR_SEEK_CUR)`` 78 79 80 See Also 81 -------- 82 83 If you need to move the file pointer by a large offset that's out of the 84 range of a 32-bit integer, use :ref:`PR_Seek64`. New code should use 85 :ref:`PR_Seek64` so that it can handle files larger than 2 GB.