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 truncate ( Path,  Length)
const   char *Path;
off_t Length;

int ftruncate ( FileDescriptor, Length)
int FileDescriptor;
off_t Length;

Note: The truncate64 and ftruncate64 subroutines apply to AIX® 4.2 and later releases.

int truncate64 ( Path,  Length)
const   char *Path;
off64_t Length;

int ftruncate64 ( FileDescriptor, Length)
int FileDescriptor;
off64_t Length;

Description

Note: The truncate64 and ftruncate64 subroutines apply to AIX 4.2 and later releases.

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 desired 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 will be traversed and path-name resolution will continue.

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:

These subroutines also clear the SetGroupID bit (S_ISGID) if:

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 resides on a read-only file system.
Note: In addition, the truncate subroutine can return the same errors as the open subroutine if there is a problem opening the file.

The truncate and ftruncate subroutines fail if one of the following is true:

Item Description
EAGAIN The truncation operation fails due to an enforced write lock on a portion of the file 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 has been 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 has set the environment variable XPG_SUS_ENV=ON prior to execution of the process, then the SIGXFSZ signal is posted to the process when exceeding 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 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 containing the file.
ETXTBSY The file is part of a process that is running.
EROFS The named file resides on a read-only file system.
Note:
  1. The truncate subroutine can also be unsuccessful for other reasons. For a list of additional errors, see Base Operating System error codes for services that require path-name resolution .
  2. The truncate subroutine can return the same errors as the open subroutine if there is a problem opening the file.

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 will fail if:

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 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.
ENTDIR 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:

Item Description
ENAMETOOLONG Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.