NAME

ftruncate, truncate - truncate a file to a specified length

 SYNOPSIS

#include <unistd.h>

int ftruncate(int fildes, off_t length);
int truncate(const char *path, off_t length);

 DESCRIPTION

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

The truncate() function causes the regular file named by path to have a size of length bytes.

If the file previously was larger than length, the extra data is discarded. If it was previously shorter than length, it is unspecified whether the file is changed or its size increased. If the file is extended, the extended area appears as if it were zero-filled. If fildes references a shared memory object, ftruncate() sets the size of the shared memory object to length. If the file is not a regular file or a shared memory object, the result is unspecified.

With ftruncate(), the file must be open for writing; for truncate(), the process must have write permission for the file.

If the effect of truncation is to decrease the size of a file or shared memory object and whole pages beyond the new end were previously mapped, then the whole pages beyond the new end will be discarded. References to the discarded pages result in generation of a SIGBUS signal.

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 VALUE

Upon successful completion, ftruncate() and truncate() return 0. Otherwise a -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 ftruncate() function will fail if:

[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.

[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.

[EISDIR]

The named file is a directory.

[ELOOP]

Too many symbolic links were encountered in resolving path.

[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.

[ENOTDIR]

A component of the path prefix of path is not a directory.

[EROFS]

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

The truncate() function may fail if:

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

open(), <unistd.h>.