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 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 length exceeds {
PATH_MAX}.
USAGE
The
truncate() and
ftruncate() functions have transitional interfaces
for 64-bit file offsets. See
lf64(7).
ATTRIBUTES
See
attributes(7) 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(7),
lf64(7),
standards(7) April 5, 2002 TRUNCATE(3C)
