TRUNCATE(3C)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 dis‐
carded. 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 mem‐
ory. 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, ftrun‐
cate() 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. Other‐
wise, −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 permis‐
sion, 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 direc‐
tory.
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 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 ordi‐
nary 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 ALSOchmod(2), fcntl(2), open(2), attributes(5), lf64(5), standards(5)
Apr 5, 2002 TRUNCATE(3C)
