truncate(3C)						   Standard C Library Functions 					      truncate(3C)

NAME

       truncate, ftruncate - set a file to a specified length

SYNOPSIS

       #include <unistd.h>

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

       int ftruncate(int fildes, off_t length);

DESCRIPTION

       The truncate() function causes the regular file named by path to have a size equal to length bytes.

       If  the	file  previously  was larger than length, the extra data is discarded. If the file was previously shorter than length, its size is
       increased, and the extended area appears as if it were zero-filled.

       The application must ensure that the process has write permission for the file.

       This function does not modify the file offset for any open file descriptions associated with the file.

       The ftruncate() function causes the regular file referenced by fildes to be truncated to  length.  If  the  size  of  the  file	previously
       exceeded length, the extra data is no longer available to reads on the file. If the file previously was smaller than this size, ftruncate()
       increases the size of the file with the extended area appearing as if it were zero-filled. The value of the seek pointer is not modified by
       a call to ftruncate().

       The  ftruncate() function works only with regular files and shared memory. If fildes refers to a shared memory object, ftruncate() sets the
       size of the shared memory object to length. If fildes refers to a directory or is not a valid file descriptor open for writing, ftruncate()
       fails.

       If  the	effect	of  ftruncate() is to decrease the size of a shared memory object or memory mapped file and whole pages beyond the new end
       were previously mapped, then the whole pages beyond the new end shall be discarded.

       If the effect of ftruncate() is to increase the size of a shared memory object, it is unspecified if  the  contents  of	any  mapped  pages
       between the old end-of-file and the new are flushed to the underlying object.

       These  functions  do  not modify the file offset for any open file descriptions associated with the file.  On successful completion, if the
       file size is changed, these functions will mark for update the st_ctime and st_mtime fields of the file, and if the file is a regular file,
       the S_ISUID and S_ISGID bits of the file mode are left unchanged.

       If  the	request  would	cause the file size to exceed the soft file size limit for the process, the request will fail and a SIGXFSZ signal
       will be generated for the process.

RETURN VALUES

       Upon successful completion, ftruncate() and truncate() return 0. Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

       The ftruncate() and truncate() functions will fail if:

       EINTR	       A signal was caught during execution.

       EINVAL	       The length argument was less than 0.

       EFBIG or EINVAL The length argument was greater than the maximum file size.

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

       EROFS	       The named file resides on a read-only file system.

       The truncate() function will fail if:

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

       EFAULT	       The path argument points outside the process' allocated address space.

       EINVAL	       The path argument is not an ordinary file.

       EISDIR	       The named file is a directory.

       ELOOP	       Too many symbolic links were encountered in resolving path.

       EMFILE	       The maximum number of file descriptors available to the process has been reached.

       ENAMETOOLONG    The length of the specified pathname exceeds {PATH_MAX} bytes, or the  length  of  a  component	of  the  pathname  exceeds
		       {NAME_MAX} bytes.

       ENOENT	       A component of path does not name an existing file or path is an empty string.

       ENFILE	       Additional space could not be allocated for the system file table.

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

       ENOLINK	       The path argument points to a remote machine and the link to that machine is no longer active.

       The ftruncate() function will fail if:

       EAGAIN	       The file exists, mandatory file/record locking is set, and there are outstanding record locks on the file (see chmod(2)).

       EBADF or EINVAL The fildes argument is not a file descriptor open for writing.

       EFBIG	       The  file  is a regular file and length is greater than the offset maximum established in the open file description associ-
		       ated with fildes.

       EINVAL	       The fildes argument references a file that was opened without write permission.

       EINVAL	       The fildes argument does not correspond to an ordinary file.

       ENOLINK	       The fildes argument points to a remote machine and the link to that machine is no longer active.

       The truncate() function may fail if:

       ENAMETOOLONG    Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

USAGE

       The truncate() and ftruncate() functions have transitional interfaces for 64-bit file offsets.  See lf64(5).

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       chmod(2), fcntl(2), open(2), attributes(5), lf64(5), standards(5)

SunOS 5.10							    5 Apr 2002							      truncate(3C)