truncate, truncate64, ftruncate, or ftruncate64 Subroutine
Purpose
Changes the length of regular files or shared memory object.
Library
Standard C Library (libc.a)
Syntax
#include <unistd.h>
int ftruncate ( FileDescriptor, Length)
int FileDescriptor;
off_t Length;
int ftruncate64 ( FileDescriptor, Length)
int FileDescriptor;
off64_t Length;
Description
The truncate and ftruncate subroutines change the length of regular files or shared memory object.
The Path parameter must point to a regular file for which the calling process has write permission. The Length parameter specifies the wanted length of the new file in bytes.
The Length parameter measures the specified file in bytes from the beginning of the file. If the new length is less than the previous length, all data between the new length and the previous end of file is removed. If the new length in the specified file is greater than the previous length, data between the old and new lengths is read as zeros. 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 parameter.
If the file designated in the Path parameter names a symbolic link, the link is traversed and path name resolution continues.
These subroutines do not modify the seek pointer of the file.
These subroutines cannot be applied to a file that a process has open with the O_DEFER flag.
Successful completion of the truncate or ftruncate subroutine
updates the st_ctime
and st_mtime
fields
of the file. Successful completion also clears the SetUserID bit (S_ISUID)
of the file if any of the following are true:
- The calling process does not have root user authority.
- The effective user ID of the calling process does not match the user ID of the file.
- The file is executable by the group (S_IXGRP) or others (S_IXOTH).
These subroutines also clear the SetGroupID bit (S_ISGID) if the following conditions are true:
- The file does not match the effective group ID or one of the supplementary group IDs of the process
- OR
- The file is executable by the owner (S_IXUSR)
or others (S_IXOTH). Note: Clearing of the SetUserID and SetGroupID bits can occur even if the subroutine fails because the data in the file was modified before the error was detected.
truncate and ftruncate can be used to specify any size up to OFF_MAX. truncate64 and ftruncate64 can be used to specify any length up to the maximum file size for the file.
In the large file enabled programming environment, truncate is redefined to be truncate64 and ftruncate is redefined to be ftruncate64.
Parameters
Item | Description |
---|---|
Path | Specifies the name of a file that is opened, truncated, and then closed. |
FileDescriptor | Specifies the descriptor of a file or shared memory object that must be open for writing. |
Length | Specifies the new length of the truncated file in bytes. |
Return Values
Upon successful completion, a value of 0 is returned. If the truncate or ftruncate subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the nature of the error.
Error Codes
The truncate and ftruncate subroutines fail if the following is true:
Item | Description |
---|---|
EROFS | An attempt was made to truncate a file that occupies a read-only file system. |
The truncate and ftruncate subroutines fail if one of the following is true:
Item | Description |
---|---|
EAGAIN | The truncation operation fails when an enforced write lock on a portion of the file that is being truncated. Because the target file was opened with the O_NONBLOCK or O_NDELAY flags set, the subroutine fails immediately rather than wait for a release. |
EDQUOT | New disk blocks cannot be allocated for the truncated file. The quota of the user's or group's allotted disk blocks was exhausted on the target file system. |
EFBIG | An attempt was made to write a file that exceeds the process' file size limit or the maximum file size. If the user environment variable XPG_SUS_ENV=ON is set before execution of the process, then the SIGXFSZ signal is posted to the process when it exceeds the process' file size limit. |
EFBIG | The file is a regular file and length is greater than the offset maximum established in the open file description that is associated with fildes. |
EINVAL | The file is not a regular file. |
EINVAL | The Length parameter was less than zero. |
EISDIR | The named file is a directory. |
EINTR | A signal was caught during execution. |
EIO | An I/O error occurred while reading from or writing to the file system. |
EMFILE | The file is open with O_DEFER by one or more processes. |
ENOSPC | New disk blocks cannot be allocated for the truncated file. There is no free space on the file system that contains the file. |
ETXTBSY | The file is part of a process that is running. |
EROFS | The named file occupies a read-only file system. |
- The truncate subroutine can also be unsuccessful for other reasons. For a list of more errors, see Base Operating System error codes for services that require path-name resolution.
- The truncate subroutine can return the same errors as the open subroutine if a problem occurs while the file is being opened.
The ftruncate subroutine fails if the following is true:
Item | Description |
---|---|
EBADF | The FileDescriptor parameter is not a valid file descriptor open for writing. |
EINVAL | The FileDescriptor argument references a file that was opened without write permission. |
The truncate function fails if the following conditions are true:
Item | Description |
---|---|
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 path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes. |
ENOENT | A component of path does not name an existing file or path is an empty string. |
ENTDIR | A component of the path prefix of path is not a directory. |
EROFS | The named file occupies a read-only file system. |
The truncate function fails if the following is true:
Item | Description |
---|---|
ENAMETOOLONG | Path name resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX. |