unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



truncate(2)							  truncate(2)



NAME

  truncate, ftruncate -	Changes	file length

SYNOPSIS

  #include <&lt;unistd.h>&gt;

  int truncate(
	  const	char *path,
	  off_t	length);

  int ftruncate(
	  int filedes,
	  off_t	length);

STANDARDS

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

  ftruncate(), truncate():  XSH4.2

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

PARAMETERS

  path	    Specifies the name of a file that is opened, truncated, and	then
	    closed.  The path parameter	must point to a	pathname which names
	    a regular file for which the calling process has write permis-
	    sion.  If the path parameter refers	to a symbolic link, the
	    length of the file pointed to by the symbolic link is truncated.

  filedes   Specifies the descriptor of	a file that must be open for writing.

  length    Specifies the new length of	the file in bytes.

DESCRIPTION

  The truncate() and ftruncate() functions change the length of	a file to the
  size in bytes	specified by the length	parameter.  If the new length is less
  than the previous length, the	truncate() and ftruncate() functions remove
  all data beyond length bytes from the	specified file.	 All file data
  between the new end-of-file and the previous end-of-file is discarded.  If
  the new length is greater than the previous length, one byte of zero (0x00)
  is written at	the offset of the new length.  The space in between the	pre-
  vious	end-of-file and	the new	end-of-file is left as a hole; that is,	no
  blocks are allocated to the space in between the previous last block and
  the new last block.

  Full blocks are returned to the file system so that they can be used again,
  and the file size is changed to the value of the length parameter.

  The truncate() and ftruncate() functions have	no effect on FIFO special
  files	or directories.	 These functions do not	modify the seek	pointer	of
  the file.


  Upon successful completion, the truncate() and ftruncate() functions mark
  the st_ctime and st_mtime fields of the file for update.  If the file	is a
  regular file,	the  ftruncate() and truncate()	functions clear	the S_ISUID
  and S_ISGID attributes of the	file.

  If the file has enforced file	locking	enabled	and there are file locks on
  the file, the	truncate() or ftruncate() function fails.

RETURN VALUES

  Upon successful completion, a	value of 0 (zero) is returned. If the trun-
  cate() or ftruncate()	function fails,	it returns a value of -1, and errno
  is set to indicate the error.

ERRORS

  The ftruncate() and truncate() functions set errno to	the specified values
  for the following conditions:

  [EAGAIN]  [Tru64 UNIX]  The write operation failed due to an enforced	write
	    lock on the	file.

	    [Tru64 UNIX]  The file has enforced	mode file locking enabled and
	    there are file locks on the	file.

  [EFBIG]   The	length parameter was greater than the maximum file size.

  [EINTR]   A signal was caught	during execution.

  [EINVAL]  The	length parameter was less than 0 (zero).

	    [Tru64 UNIX]  The file is not a regular file.

  [EIO]	    An I/O error occurred while	reading	from or	writing	to a file
	    system.

  [ESTALE]  [Tru64 UNIX]  The process' root or current directory is located
	    in a virtual file system that has been unmounted.

  In addition, the ftruncate() function	sets errno to the specified values
  for the following conditions:

  [EACCES]  [Tru64 UNIX]  Write	access permission to the file was denied.

  [EBADF]   The	filedes	parameter is not a valid file descriptor open for
	    writing.

  [EINVAL]  The	fildes parameter references a file that	was opened without
	    write permission.

  [EROFS]   [Tru64 UNIX]  The file resides on a	read-only file system.

  In addition, the truncate() function fails if	errors occur that apply	to
  any service requiring	pathname resolution, or	if one of the following	are
  true:

  [EACCES]  A component	of the path prefix denies search permission, or	write
	    permission is denied on the	file.

  [EISDIR]  The	named file is a	directory.

  [ELOOP]   Too	many symbolic links were encountered in	resolving path.

  [ENAMETOOLONG]
	    The	size of	the pathname exceeds PATH_MAX or a pathname component
	    is longer than NAME_MAX.

  [ENOENT]  A component	of the specified pathname does not exist, or the path
	    parameter points to	an empty string.

  [ENOTDIR] A component	of the path prefix is not a directory.

  [EROFS]   The	file resides on	a read-only file system.

RELATED	INFORMATION

  Functions: chmod(2), fcntl(2), open(2)

  Standards: standards(5)