truncate(2)truncate(2)NAME
truncate, ftruncate - Change file length
SYNOPSIS
#include <unistd.h>
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 stan‐
dards as follows:
ftruncate(), truncate(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the name of a file that is opened, truncated, and then
closed. The path parameter must point to a pathname which names a reg‐
ular file for which the calling process has write permission. If the
path parameter refers to a symbolic link, the length of the file
pointed to by the symbolic link is truncated. Specifies the descriptor
of a file that must be open for writing. 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() func‐
tions 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 previous 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 parame‐
ter.
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.
[Tru64 UNIX] 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
truncate() 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: [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. The length parameter was
greater than the maximum file size. A signal was caught during
execution. The length parameter was less than 0 (zero).
[Tru64 UNIX] The file is not a regular file. An I/O error
occurred while reading from or writing to a file system. [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 val‐
ues for the following conditions: [Tru64 UNIX] Write access permission
to the file was denied. The filedes parameter is not a valid file
descriptor open for writing. The fildes parameter references a file
that was opened without write permission. [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 follow‐
ing are true: A component of the path prefix denies search permission,
or write permission is denied on the file. The named file is a direc‐
tory. Too many symbolic links were encountered in resolving path. The
size of the pathname exceeds PATH_MAX or a pathname component is longer
than NAME_MAX.
Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds PATH_MAX. A component of the speci‐
fied pathname does not exist, or the path parameter points to an
empty string. A component of the path prefix is not a direc‐
tory. The file resides on a read-only file system.
SEE ALSO
Functions: chmod(2), fcntl(2), open(2)
Standards: standards(5)truncate(2)
