Technical Reference: Base Operating System and Extensions , Volume 2

truncate, truncate64, ftruncate, or ftruncate64 Subroutine

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.

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:

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

Path	Specifies the name of a file that is opened, truncated, and then closed.
FileDescriptor	Specifies the descriptor of a file 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:

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:

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.

Notes:

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

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:

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:

ENAMETOOLONG

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

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The fclear subroutine, openx, open, or creat subroutine.

Appendix A, Base Operating System Error Codes for Services That Require Path-Name Resolution.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.