Debian Codegraph @

upstream/debian-unstable/man2/truncate.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH truncate 2 2026-04-12 "Linux man-pages 6.18"
7 .SH NAME
8 truncate, ftruncate \- truncate a file to a specified length
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <unistd.h>
15 .P
16 .BI "int truncate(const char *" path ", off_t " length );
17 .BI "int ftruncate(int " fd ", off_t " length );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR truncate ():
26 .nf
27 _XOPEN_SOURCE >= 500
28 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
29 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
30 || /* glibc <= 2.19: */ _BSD_SOURCE
31 .fi
32 .P
33 .BR ftruncate ():
34 .nf
35 _XOPEN_SOURCE >= 500
36 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
37 || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
38 || /* glibc <= 2.19: */ _BSD_SOURCE
39 .fi
40 .SH DESCRIPTION
41 The
42 .BR truncate ()
43 and
44 .BR ftruncate ()
45 functions cause the regular file named by
46 .I path
47 or referenced by
48 .I fd
49 to be truncated to a size of precisely
50 .I length
51 bytes.
52 .P
53 If the file previously was larger than this size, the extra data is lost.
54 If the file previously was shorter, it is extended, and
55 the extended part reads as null bytes (\[aq]\[rs]0\[aq]).
56 .P
57 The file offset is not changed.
58 .P
59 If the size changed,
60 then the st_ctime and st_mtime fields
61 (respectively,
62 time of last status change and
63 time of last modification;
64 see
65 .BR inode (7))
66 for the file are updated,
67 and the set-user-ID and set-group-ID mode bits may be cleared.
68 .P
69 With
70 .BR ftruncate (),
71 the file must be open for writing;
72 with
73 .BR truncate (),
74 the file must be writable.
75 .SH RETURN VALUE
76 On success, zero is returned.
77 On error, \-1 is returned, and
78 .I errno
79 is set to indicate the error.
80 .SH ERRORS
81 For
82 .BR truncate ():
83 .TP
84 .B EACCES
85 Search permission is denied for a component of the path prefix,
86 or the named file is not writable by the user.
87 (See also
88 .BR path_resolution (7).)
89 .TP
90 .B EFAULT
91 The argument
92 .I path
93 points outside the process's allocated address space.
94 .TP
95 .B EFBIG
96 The argument
97 .I length
98 is larger than the maximum file size.
99 (XSI)
100 .TP
101 .B ENOSPC
102 There is not enough space left on the device for extending the
103 file size to the given
104 .IR length .
105 .TP
106 .B EINTR
107 While blocked waiting to complete,
108 the call was interrupted by a signal handler;
109 see
110 .BR fcntl (2)
111 and
112 .BR signal (7).
113 .TP
114 .B EINVAL
115 The argument
116 .I length
117 is negative or larger than the maximum file size.
118 .TP
119 .B EIO
120 An I/O error occurred updating the inode.
121 .TP
122 .B EISDIR
123 The named file is a directory.
124 .TP
125 .B ELOOP
126 Too many symbolic links were encountered in translating the pathname.
127 .TP
128 .B ENAMETOOLONG
129 A component of a pathname exceeded 255 characters,
130 or an entire pathname exceeded 1023 characters.
131 .TP
132 .B ENOENT
133 The named file does not exist.
134 .TP
135 .B ENOTDIR
136 A component of the path prefix is not a directory.
137 .TP
138 .B EPERM
139 .\" This happens for at least MSDOS and VFAT filesystems
140 .\" on kernel 2.6.13
141 The underlying filesystem does not support extending
142 a file beyond its current size.
143 .TP
144 .B EPERM
145 The operation was prevented by a file seal;
146 see
147 .BR fcntl (2).
148 .TP
149 .B EROFS
150 The named file resides on a read-only filesystem.
151 .TP
152 .B ETXTBSY
153 The file is an executable file that is being executed.
154 .P
155 For
156 .BR ftruncate ()
157 the same errors apply, but instead of things that can be wrong with
158 .IR path ,
159 we now have things that can be wrong with the file descriptor,
160 .IR fd :
161 .TP
162 .B EBADF
163 .I fd
164 is not a valid file descriptor.
165 .TP
166 .BR EBADF " or " EINVAL
167 .I fd
168 is not open for writing.
169 .TP
170 .B EINVAL
171 .I fd
172 does not reference a regular file or a POSIX shared memory object.
173 .TP
174 .BR EINVAL " or " EBADF
175 The file descriptor
176 .I fd
177 is not open for writing.
178 POSIX permits, and portable applications should handle,
179 either error for this case.
180 (Linux produces
181 .BR EINVAL .)
182 .SH VERSIONS
183 The details in DESCRIPTION are for XSI-compliant systems.
184 For non-XSI-compliant systems, the POSIX standard allows
185 two behaviors for
186 .BR ftruncate ()
187 when
188 .I length
189 exceeds the file length
190 (note that
191 .BR truncate ()
192 is not specified at all in such an environment):
193 either returning an error, or extending the file.
194 Like most UNIX implementations, Linux follows the XSI requirement
195 when dealing with native filesystems.
196 However, some nonnative filesystems do not permit
197 .BR truncate ()
198 and
199 .BR ftruncate ()
200 to be used to extend a file beyond its current length:
201 a notable example on Linux is VFAT.
202 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
203 .P
204 On some 32-bit architectures,
205 the calling signature for these system calls differ,
206 for the reasons described in
207 .BR syscall (2).
208 .SH STANDARDS
209 POSIX.1-2024.
210 .SH HISTORY
211 POSIX.1-2001,
212 SVr4, 4.2BSD.
213 .\" POSIX.1-1996 has
214 .\" .BR ftruncate ().
215 .\" POSIX.1-2001 also has
216 .\" .BR truncate (),
217 .\" as an XSI extension.
218 .\" .P
219 .\" SVr4 documents additional
220 .\" .BR truncate ()
221 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for
222 .\" .BR ftruncate ()
223 .\" an additional EAGAIN error condition.
224 .P
225 The original Linux
226 .BR truncate ()
227 and
228 .BR ftruncate ()
229 system calls were not designed to handle large file offsets.
230 Consequently, Linux 2.4 added
231 .BR truncate64 ()
232 and
233 .BR ftruncate64 ()
234 system calls that handle large files.
235 However,
236 these details can be ignored by applications using glibc,
237 whose wrapper functions transparently employ the more recent system calls
238 where they are available.
239 .SH NOTES
240 .BR ftruncate ()
241 can also be used to set the size of a POSIX shared memory object;
242 see
243 .BR shm_open (3).
244 .SH BUGS
245 A header file bug in glibc 2.12 meant that the minimum value of
246 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
247 .B _POSIX_C_SOURCE
248 required to expose the declaration of
249 .BR ftruncate ()
250 was 200809L instead of 200112L.
251 This has been fixed in later glibc versions.
252 .SH SEE ALSO
253 .BR truncate (1),
254 .BR open (2),
255 .BR stat (2),
256 .BR path_resolution (7)