Sun Microsystems, Inc. gratefully acknowledges The Open Group for
permission to reproduce portions of its copyrighted documentation.
Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.
The Institute of Electrical and Electronics Engineers and The Open
Group, have given us permission to reprint portions of their
documentation.
In the following statement, the phrase ``this text'' refers to portions
of the system documentation.
Portions of this text are reprinted and reproduced in electronic form
in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6,
Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy
between these versions and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html.
This notice shall appear on any product containing this material.
The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
Copyright 1989 AT&T
Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
#include <unistd.h> int truncate(const char *path, off_t length);
int ftruncate(int fildes, off_t length);
The truncate() function causes the regular file named by path to have a size equal to length bytes.
If the file previously was larger than length, the extra data is discarded. If the file was previously shorter than length, its size is increased, and the extended area appears as if it were zero-filled.
The application must ensure that the process has write permission for the file.
This function does not modify the file offset for any open file descriptions associated with the file.
The ftruncate() function causes the regular file referenced by fildes to be truncated to length. If the size of the file previously exceeded length, the extra data is no longer available to reads on the file. If the file previously was smaller than this size, ftruncate() increases the size of the file with the extended area appearing as if it were zero-filled. The value of the seek pointer is not modified by a call to ftruncate().
The ftruncate() function works only with regular files and shared memory. If fildes refers to a shared memory object, ftruncate() sets the size of the shared memory object to length. If fildes refers to a directory or is not a valid file descriptor open for writing, ftruncate() fails.
If the effect of ftruncate() is to decrease the size of a shared memory object or memory mapped file and whole pages beyond the new end were previously mapped, then the whole pages beyond the new end shall be discarded.
If the effect of ftruncate() is to increase the size of a shared memory object, it is unspecified if the contents of any mapped pages between the old end-of-file and the new are flushed to the underlying object.
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 are left unchanged.
If the request would cause the file size to exceed the soft file size limit for the process, the request will fail and a SIGXFSZ signal will be generated for the process.
Upon successful completion, ftruncate() and truncate() return 0. Otherwise, -1 is returned and errno is set to indicate the error.
The ftruncate() and truncate() functions will fail if: EINTR
A signal was caught during execution.
The length argument was less than 0.
The length argument was greater than the maximum file size.
An I/O error occurred while reading from or writing to a file system.
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.
The path argument points outside the process' allocated address space.
The path argument is not an ordinary file.
The named file is a directory.
Too many symbolic links were encountered in resolving path.
The maximum number of file descriptors available to the process has been reached.
The length of the specified pathname exceeds {PATH_MAX} bytes, or the length of a component of the pathname exceeds {NAME_MAX} bytes.
A component of path does not name an existing file or path is an empty string.
Additional space could not be allocated for the system file table.
A component of the path prefix of path is not a directory.
The path argument points to a remote machine and the link to that machine is no longer active.
The ftruncate() function will fail if: EAGAIN
The file exists, mandatory file/record locking is set, and there are outstanding record locks on the file (see chmod(2)).
The fildes argument is not a file descriptor open for writing.
The file is a regular file and length is greater than the offset maximum established in the open file description associated with fildes.
The fildes argument references a file that was opened without write permission.
The fildes argument does not correspond to an ordinary file.
The fildes argument points to a remote machine and the link to that machine is no longer active.
The truncate() function may fail if: ENAMETOOLONG
Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.
The truncate() and ftruncate() functions have transitional interfaces for 64-bit file offsets. See lf64(5).
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Standard |
| MT-Level MT-Safe |
chmod(2), fcntl(2), open(2), attributes(5), lf64(5), standards(5)