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 of length bytes.

     The ftruncate() function causes the regular file  referenced
     by fildes to have a size of length bytes.

     The effect of ftruncate() and truncate() on other  types  of
     files  is  unspecified.   If  the file previously was larger
     than length, the extra data is lost.  If it  was  previously
     shorter  than  length, bytes between the old and new lengths
     are read as zeroes. With ftruncate(), the file must be  open
     for  writing;  for  truncate(),  the process must have write
     permission for the file.

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

     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 may be cleared.

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.

     The truncate() function will fail if:

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

     EFAULT
           The path argument points outside  the  process'  allo-
           cated 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 direc-
           tory.

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

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

     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 associated 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

USAGE

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

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     mount_ufs(1M), chmod(2), fcntl(2),  open(2),  attributes(5),
     lf64(5)