truncate, truncate64, ftruncate, or ftruncate64 Subroutine

Purpose

Changes the length of regular files.

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

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:

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:

Notes:

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:

The truncate function will fail if:

The truncate function may fail if:

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 Version 4.3 General Programming Concepts: Writing and Debugging Programs.