1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\" @(#)truncate.2 6.9 (Berkeley) 3/10/91
8 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
10 .\" Modified 1998-12-21 by Andries Brouwer <aeb@cwi.nl>
11 .\" Modified 2002-01-07 by Michael Kerrisk <mtk.manpages@gmail.com>
12 .\" Modified 2002-04-06 by Andries Brouwer <aeb@cwi.nl>
13 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
15 .TH truncate 2 (date) "Linux man-pages (unreleased)"
17 truncate, ftruncate \- truncate a file to a specified length
20 .RI ( libc ", " \-lc )
23 .B #include <unistd.h>
25 .BI "int truncate(const char *" path ", off_t " length );
26 .BI "int ftruncate(int " fd ", off_t " length );
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
37 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
38 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
39 || /* glibc <= 2.19: */ _BSD_SOURCE
45 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
46 || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
47 || /* glibc <= 2.19: */ _BSD_SOURCE
54 functions cause the regular file named by
58 to be truncated to a size of precisely
62 If the file previously was larger than this size, the extra data is lost.
63 If the file previously was shorter, it is extended, and
64 the extended part reads as null bytes (\[aq]\e0\[aq]).
66 The file offset is not changed.
68 If the size changed, then the st_ctime and st_mtime fields
69 (respectively, time of last status change and
70 time of last modification; see
72 for the file are updated,
73 and the set-user-ID and set-group-ID mode bits may be cleared.
77 the file must be open for writing; with
79 the file must be writable.
81 On success, zero is returned.
82 On error, \-1 is returned, and
84 is set to indicate the error.
90 Search permission is denied for a component of the path prefix,
91 or the named file is not writable by the user.
93 .BR path_resolution (7).)
98 points outside the process's allocated address space.
103 is larger than the maximum file size. (XSI)
106 While blocked waiting to complete,
107 the call was interrupted by a signal handler; see
115 is negative or larger than the maximum file size.
118 An I/O error occurred updating the inode.
121 The named file is a directory.
124 Too many symbolic links were encountered in translating the pathname.
127 A component of a pathname exceeded 255 characters,
128 or an entire pathname exceeded 1023 characters.
131 The named file does not exist.
134 A component of the path prefix is not a directory.
137 .\" This happens for at least MSDOS and VFAT filesystems
139 The underlying filesystem does not support extending
140 a file beyond its current size.
143 The operation was prevented by a file seal; see
147 The named file resides on a read-only filesystem.
150 The file is an executable file that is being executed.
154 the same errors apply, but instead of things that can be wrong with
156 we now have things that can be wrong with the file descriptor,
161 is not a valid file descriptor.
163 .BR EBADF " or " EINVAL
165 is not open for writing.
169 does not reference a regular file or a POSIX shared memory object.
171 .BR EINVAL " or " EBADF
174 is not open for writing.
175 POSIX permits, and portable applications should handle,
176 either error for this case.
180 The details in DESCRIPTION are for XSI-compliant systems.
181 For non-XSI-compliant systems, the POSIX standard allows
186 exceeds the file length
189 is not specified at all in such an environment):
190 either returning an error, or extending the file.
191 Like most UNIX implementations, Linux follows the XSI requirement
192 when dealing with native filesystems.
193 However, some nonnative filesystems do not permit
197 to be used to extend a file beyond its current length:
198 a notable example on Linux is VFAT.
199 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
201 On some 32-bit architectures,
202 the calling signature for these system calls differ,
203 for the reasons described in
209 4.4BSD, SVr4 (first appeared in 4.2BSD).
211 .\" .BR ftruncate ().
212 .\" POSIX.1-2001 also has
214 .\" as an XSI extension.
216 .\" SVr4 documents additional
218 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for
220 .\" an additional EAGAIN error condition.
226 system calls were not designed to handle large file offsets.
227 Consequently, Linux 2.4 added
231 system calls that handle large files.
232 However, these details can be ignored by applications using glibc, whose
233 wrapper functions transparently employ the more recent system calls
234 where they are available.
237 can also be used to set the size of a POSIX shared memory object; see
240 A header file bug in glibc 2.12 meant that the minimum value of
241 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
243 required to expose the declaration of
245 was 200809L instead of 200112L.
246 This has been fixed in later glibc versions.
251 .BR path_resolution (7)