unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



lseek(2)							     lseek(2)



NAME
  lseek	-  Moves read-write file offset

SYNOPSIS

  #include <&lt;sys/types.h>&gt;
  #include <&lt;unistd.h>&gt;

  off_t	lseek (
	  int filedes,
	  off_t	offset,
	  int whence );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  lseek():  XSH5.0, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  filedes   Specifies a	file descriptor	obtained from a	successful open() or
	    fcntl() function.

  offset    Specifies a	value, in bytes, that is used in conjunction with the
	    whence parameter to	set the	file pointer. A	negative value causes
	    seeking in the reverse direction. The resulting file position may
	    also be negative.

  whence    Specifies how to interpret the offset parameter in setting the
	    file pointer associated with the filedes parameter.	 Values	for
	    the	whence parameter are:

	    SEEK_SET  Sets the file pointer to the value of the	offset param-
		      eter.

	    SEEK_CUR  Sets the file pointer to its current location plus the
		      value of the offset parameter.

	    SEEK_END  Sets the file pointer to the size	of the file plus the
		      value of the offset parameter.

DESCRIPTION

  The lseek() function sets the	file offset for	the open file specified	by
  the filedes parameter.  The whence parameter determines how the offset is
  to be	interpreted.


  The lseek() function allows the file offset to be set	beyond the end of
  existing data	in the file.  If data is later written at this point, subse-
  quently reading data in the gap returns bytes	with the value 0 (zero)	until
  data is actually written into	the gap.


  By itself, the lseek() function does not extend the size of the file.

RETURN VALUES

  Upon successful completion, the resulting pointer location (the file
  offset), measured in bytes from the beginning	of the file, is	returned. If
  the lseek() function fails, the file offset remains unchanged, a value of
  (off_t) - 1 is returned, and errno is	set to indicate	the error.

ERRORS

  If the lseek() function fails, the file offset remains unchanged and errno
  may be set to	one of the following values:

  [EBADF]   The	filedes	parameter is not an open file descriptor.

  [EINVAL]  The	whence parameter is an invalid value or	the resulting file
	    offset would be invalid.

  [ESPIPE]  The	filedes	parameter is associated	with a pipe (FIFO), a socket,
	    or a multiplexed special file.

	    The	filedes	parameter underlying the stream	is associated with a
	    socket.

RELATED	INFORMATION

  Functions: fcntl(2), fseek(3), open(2), read(2), write(2)

  Standards: standards(5)