docs/nspr/reference/pr_seek.rst

   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.