BSD 4_4 development

[unix-history] / usr / share / man / cat2 / seek.0

LSEEK(2)                    BSD Programmer's Manual                   LSEEK(2)

N\bNA\bAM\bME\bE
    l\bls\bse\bee\bek\bk - reposition read/write file offset

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
    #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b>

    _\bo_\bf_\bf_\b__\bt
    l\bls\bse\bee\bek\bk(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bi_\bn_\bt _\bw_\bh_\be_\bn_\bc_\be);

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
    The l\bls\bse\bee\bek\bk() function repositions the offset of the file descriptor _\bf_\bi_\bl_\bd_\be_\bs
    to the argument _\bo_\bf_\bf_\bs_\be_\bt according to the directive _\bw_\bh_\be_\bn_\bc_\be_\b. The argument
    _\bf_\bi_\bl_\bd_\be_\bs must be an open file descriptor.  L\bLs\bse\bee\bek\bk() repositions the file
    pointer _\bf_\bi_\bl_\bd_\be_\bs as follows:

          If _\bw_\bh_\be_\bn_\bc_\be is SEEK_SET, the offset is set to _\bo_\bf_\bf_\bs_\be_\bt bytes.

          If _\bw_\bh_\be_\bn_\bc_\be is SEEK_CUR, the offset is set to its current location
          plus _\bo_\bf_\bf_\bs_\be_\bt bytes.

          If _\bw_\bh_\be_\bn_\bc_\be is SEEK_END, the offset is set to the size of the file
          plus _\bo_\bf_\bf_\bs_\be_\bt bytes.

    The l\bls\bse\bee\bek\bk() function allows the file offset to be set beyond the end of
    the existing end-of-file of the file. If data is later written at this
    point, subsequent reads of the data in the gap return bytes of zeros (un-
    til data is actualy written into the gap).

    Some devices are incapable of seeking.  The value of the pointer associ-
    ated with such a device is undefined.

R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
    Upon successful completion, l\bls\bse\bee\bek\bk() returns the resulting offset location
    as measured in bytes from the begining of the file.  Otherwise, a value
    of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error.

E\bER\bRR\bRO\bOR\bRS\bS
    L\bLs\bse\bee\bek\bk() will fail and the file pointer will remain unchanged if:

    [EBADF]   _\bF_\bi_\bl_\bd_\be_\bs is not an open file descriptor.

    [ESPIPE]  _\bF_\bi_\bl_\bd_\be_\bs is associated with a pipe, socket, or FIFO.

    [EINVAL]  _\bW_\bh_\be_\bn_\bc_\be is not a proper value.

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
    dup(2),  open(2)

B\bBU\bUG\bGS\bS
    This document's use of _\bw_\bh_\be_\bn_\bc_\be is incorrect English, but maintained for
    historical reasons.

S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS
    The l\bls\bse\bee\bek\bk() function conforms to IEEE Std 1003.1-1988 (``POSIX'').

4th Berkeley Distribution        June 4, 1993                                1