Debian Codegraph @

upstream/mageia-cauldron/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 2025-10-29 "Linux man-pages 6.17"
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 EINTR
102 While blocked waiting to complete,
103 the call was interrupted by a signal handler;
104 see
105 .BR fcntl (2)
106 and
107 .BR signal (7).
108 .TP
109 .B EINVAL
110 The argument
111 .I length
112 is negative or larger than the maximum file size.
113 .TP
114 .B EIO
115 An I/O error occurred updating the inode.
116 .TP
117 .B EISDIR
118 The named file is a directory.
119 .TP
120 .B ELOOP
121 Too many symbolic links were encountered in translating the pathname.
122 .TP
123 .B ENAMETOOLONG
124 A component of a pathname exceeded 255 characters,
125 or an entire pathname exceeded 1023 characters.
126 .TP
127 .B ENOENT
128 The named file does not exist.
129 .TP
130 .B ENOTDIR
131 A component of the path prefix is not a directory.
132 .TP
133 .B EPERM
134 .\" This happens for at least MSDOS and VFAT filesystems
135 .\" on kernel 2.6.13
136 The underlying filesystem does not support extending
137 a file beyond its current size.
138 .TP
139 .B EPERM
140 The operation was prevented by a file seal;
141 see
142 .BR fcntl (2).
143 .TP
144 .B EROFS
145 The named file resides on a read-only filesystem.
146 .TP
147 .B ETXTBSY
148 The file is an executable file that is being executed.
149 .P
150 For
151 .BR ftruncate ()
152 the same errors apply, but instead of things that can be wrong with
153 .IR path ,
154 we now have things that can be wrong with the file descriptor,
155 .IR fd :
156 .TP
157 .B EBADF
158 .I fd
159 is not a valid file descriptor.
160 .TP
161 .BR EBADF " or " EINVAL
162 .I fd
163 is not open for writing.
164 .TP
165 .B EINVAL
166 .I fd
167 does not reference a regular file or a POSIX shared memory object.
168 .TP
169 .BR EINVAL " or " EBADF
170 The file descriptor
171 .I fd
172 is not open for writing.
173 POSIX permits, and portable applications should handle,
174 either error for this case.
175 (Linux produces
176 .BR EINVAL .)
177 .SH VERSIONS
178 The details in DESCRIPTION are for XSI-compliant systems.
179 For non-XSI-compliant systems, the POSIX standard allows
180 two behaviors for
181 .BR ftruncate ()
182 when
183 .I length
184 exceeds the file length
185 (note that
186 .BR truncate ()
187 is not specified at all in such an environment):
188 either returning an error, or extending the file.
189 Like most UNIX implementations, Linux follows the XSI requirement
190 when dealing with native filesystems.
191 However, some nonnative filesystems do not permit
192 .BR truncate ()
193 and
194 .BR ftruncate ()
195 to be used to extend a file beyond its current length:
196 a notable example on Linux is VFAT.
197 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
198 .P
199 On some 32-bit architectures,
200 the calling signature for these system calls differ,
201 for the reasons described in
202 .BR syscall (2).
203 .SH STANDARDS
204 POSIX.1-2024.
205 .SH HISTORY
206 POSIX.1-2001,
207 SVr4, 4.2BSD.
208 .\" POSIX.1-1996 has
209 .\" .BR ftruncate ().
210 .\" POSIX.1-2001 also has
211 .\" .BR truncate (),
212 .\" as an XSI extension.
213 .\" .P
214 .\" SVr4 documents additional
215 .\" .BR truncate ()
216 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for
217 .\" .BR ftruncate ()
218 .\" an additional EAGAIN error condition.
219 .P
220 The original Linux
221 .BR truncate ()
222 and
223 .BR ftruncate ()
224 system calls were not designed to handle large file offsets.
225 Consequently, Linux 2.4 added
226 .BR truncate64 ()
227 and
228 .BR ftruncate64 ()
229 system calls that handle large files.
230 However,
231 these details can be ignored by applications using glibc,
232 whose wrapper functions transparently employ the more recent system calls
233 where they are available.
234 .SH NOTES
235 .BR ftruncate ()
236 can also be used to set the size of a POSIX shared memory object;
237 see
238 .BR shm_open (3).
239 .SH BUGS
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
242 .B _POSIX_C_SOURCE
243 required to expose the declaration of
244 .BR ftruncate ()
245 was 200809L instead of 200112L.
246 This has been fixed in later glibc versions.
247 .SH SEE ALSO
248 .BR truncate (1),
249 .BR open (2),
250 .BR stat (2),
251 .BR path_resolution (7)