trusty (3) ftruncate.3posix.gz

NAME

       ftruncate - truncate a file to a specified length

SYNOPSIS

       #include <unistd.h>

       int ftruncate(int fildes, off_t length);

DESCRIPTION

       If fildes is not a valid file descriptor open for writing, the ftruncate() function shall fail.

       If  fildes  refers  to  a  regular  file, the ftruncate() function shall cause the size of the file to be
       truncated to length. If the size of the file previously exceeded length, the extra data shall  no  longer
       be  available  to reads on the file. If the file previously was smaller than this size, ftruncate() shall
       either increase the size of the file or fail.   XSI-conformant systems shall increase  the  size  of  the
       file.  If the file size is increased, the extended area shall appear as if it were zero-filled. The value
       of the seek pointer shall not be modified by a call to ftruncate().

       Upon successful completion, if fildes refers to a regular file, the ftruncate() function shall  mark  for
       update the st_ctime and st_mtime fields of the file and the S_ISUID and S_ISGID bits of the file mode may
       be cleared. If the ftruncate() function is unsuccessful, the file is unaffected.

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

       If fildes refers to a directory, ftruncate() shall fail.

       If fildes refers to any other file type, except a shared memory object, the result is unspecified.

       If fildes refers to a shared memory object, ftruncate() shall set the size of the shared memory object to
       length.

       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 Memory Protection option  is  supported,  references  to  discarded  pages  shall  result  in  the
       generation of a SIGBUS signal; otherwise, the result of such references is undefined.

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

RETURN VALUE

       Upon  successful completion, ftruncate() shall return 0; otherwise, -1 shall be returned and errno set to
       indicate the error.

ERRORS

       The ftruncate() function shall 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.

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

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

       EBADF or EINVAL

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

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

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

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       The  ftruncate()  function  is  part  of  IEEE Std 1003.1-2001  as  it  was deemed to be more useful than
       truncate(). The truncate() function is provided as an XSI extension.

FUTURE DIRECTIONS

       None.

SEE ALSO

       open() , truncate() , the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .