man2/truncate.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)truncate.2  6.9 (Berkeley) 3/10/91
  35 .\"
  36 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  38 .\" Modified 1998-12-21 by Andries Brouwer <aeb@cwi.nl>
  39 .\" Modified 2002-01-07 by Michael Kerrisk <mtk.manpages@gmail.com>
  40 .\" Modified 2002-04-06 by Andries Brouwer <aeb@cwi.nl>
  41 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  42 .\"
  43 .TH TRUNCATE 2 2019-03-06 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 truncate, ftruncate \- truncate a file to a specified length
  46 .SH SYNOPSIS
  47 .B #include <unistd.h>
  48 .br
  49 .B #include <sys/types.h>
  50 .PP
  51 .BI "int truncate(const char *" path ", off_t " length );
  52 .br
  53 .BI "int ftruncate(int " fd ", off_t " length );
  54 .PP
  55 .in -4n
  56 Feature Test Macro Requirements for glibc (see
  57 .BR feature_test_macros (7)):
  58 .in
  59 .ad l
  60 .PP
  61 .BR truncate ():
  62 .RS 4
  63 _XOPEN_SOURCE\ >=\ 500
  64 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  65 .br
  66     || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  67     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  68 .RE
  69 .PP
  70 .BR ftruncate ():
  71 .RS 4
  72 _XOPEN_SOURCE\ >=\ 500
  73 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  74     || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE\ >=\ 200112L
  75     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  76 .RE
  77 .ad b
  78 .SH DESCRIPTION
  79 The
  80 .BR truncate ()
  81 and
  82 .BR ftruncate ()
  83 functions cause the regular file named by
  84 .I path
  85 or referenced by
  86 .I fd
  87 to be truncated to a size of precisely
  88 .I length
  89 bytes.
  90 .PP
  91 If the file previously was larger than this size, the extra data is lost.
  92 If the file previously was shorter, it is extended, and
  93 the extended part reads as null bytes (\(aq\e0\(aq).
  94 .PP
  95 The file offset is not changed.
  96 .PP
  97 If the size changed, then the st_ctime and st_mtime fields
  98 (respectively, time of last status change and
  99 time of last modification; see
 100 .BR inode (7))
 101 for the file are updated,
 102 and the set-user-ID and set-group-ID mode bits may be cleared.
 103 .PP
 104 With
 105 .BR ftruncate (),
 106 the file must be open for writing; with
 107 .BR truncate (),
 108 the file must be writable.
 109 .SH RETURN VALUE
 110 On success, zero is returned.
 111 On error, \-1 is returned, and
 112 .I errno
 113 is set appropriately.
 114 .SH ERRORS
 115 For
 116 .BR truncate ():
 117 .TP
 118 .B EACCES
 119 Search permission is denied for a component of the path prefix,
 120 or the named file is not writable by the user.
 121 (See also
 122 .BR path_resolution (7).)
 123 .TP
 124 .B EFAULT
 125 The argument
 126 .I path
 127 points outside the process's allocated address space.
 128 .TP
 129 .B EFBIG
 130 The argument
 131 .I length
 132 is larger than the maximum file size. (XSI)
 133 .TP
 134 .B EINTR
 135 While blocked waiting to complete,
 136 the call was interrupted by a signal handler; see
 137 .BR fcntl (2)
 138 and
 139 .BR signal (7).
 140 .TP
 141 .B EINVAL
 142 The argument
 143 .I length
 144 is negative or larger than the maximum file size.
 145 .TP
 146 .B EIO
 147 An I/O error occurred updating the inode.
 148 .TP
 149 .B EISDIR
 150 The named file is a directory.
 151 .TP
 152 .B ELOOP
 153 Too many symbolic links were encountered in translating the pathname.
 154 .TP
 155 .B ENAMETOOLONG
 156 A component of a pathname exceeded 255 characters,
 157 or an entire pathname exceeded 1023 characters.
 158 .TP
 159 .B ENOENT
 160 The named file does not exist.
 161 .TP
 162 .B ENOTDIR
 163 A component of the path prefix is not a directory.
 164 .TP
 165 .B EPERM
 166 .\" This happens for at least MSDOS and VFAT filesystems
 167 .\" on kernel 2.6.13
 168 The underlying filesystem does not support extending
 169 a file beyond its current size.
 170 .TP
 171 .B EPERM
 172 The operation was prevented by a file seal; see
 173 .BR fcntl (2).
 174 .TP
 175 .B EROFS
 176 The named file resides on a read-only filesystem.
 177 .TP
 178 .B ETXTBSY
 179 The file is an executable file that is being executed.
 180 .PP
 181 For
 182 .BR ftruncate ()
 183 the same errors apply, but instead of things that can be wrong with
 184 .IR path ,
 185 we now have things that can be wrong with the file descriptor,
 186 .IR fd :
 187 .TP
 188 .B EBADF
 189 .I fd
 190 is not a valid file descriptor.
 191 .TP
 192 .BR EBADF " or " EINVAL
 193 .I fd
 194 is not open for writing.
 195 .TP
 196 .B EINVAL
 197 .I fd
 198 does not reference a regular file or a POSIX shared memory object.
 199 .TP
 200 .BR EINVAL " or " EBADF
 201 The file descriptor
 202 .I fd
 203 is not open for writing.
 204 POSIX permits, and portable applications should handle,
 205 either error for this case.
 206 (Linux produces
 207 .BR EINVAL .)
 208 .SH CONFORMING TO
 209 POSIX.1-2001, POSIX.1-2008,
 210 4.4BSD, SVr4 (these calls first appeared in 4.2BSD).
 211 .\" POSIX.1-1996 has
 212 .\" .BR ftruncate ().
 213 .\" POSIX.1-2001 also has
 214 .\" .BR truncate (),
 215 .\" as an XSI extension.
 216 .\" .LP
 217 .\" SVr4 documents additional
 218 .\" .BR truncate ()
 219 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 220 .\" .BR ftruncate ()
 221 .\" an additional EAGAIN error condition.
 222 .SH NOTES
 223 .BR ftruncate ()
 224 can also be used to set the size of a POSIX shared memory object; see
 225 .BR shm_open (7).
 226 .PP
 227 The details in DESCRIPTION are for XSI-compliant systems.
 228 For non-XSI-compliant systems, the POSIX standard allows
 229 two behaviors for
 230 .BR ftruncate ()
 231 when
 232 .I length
 233 exceeds the file length
 234 (note that
 235 .BR truncate ()
 236 is not specified at all in such an environment):
 237 either returning an error, or extending the file.
 238 Like most UNIX implementations, Linux follows the XSI requirement
 239 when dealing with native filesystems.
 240 However, some nonnative filesystems do not permit
 241 .BR truncate ()
 242 and
 243 .BR ftruncate ()
 244 to be used to extend a file beyond its current length:
 245 a notable example on Linux is VFAT.
 246 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
 247 .PP
 248 The original Linux
 249 .BR truncate ()
 250 and
 251 .BR ftruncate ()
 252 system calls were not designed to handle large file offsets.
 253 Consequently, Linux 2.4 added
 254 .BR truncate64 ()
 255 and
 256 .BR ftruncate64 ()
 257 system calls that handle large files.
 258 However, these details can be ignored by applications using glibc, whose
 259 wrapper functions transparently employ the more recent system calls
 260 where they are available.
 261 .PP
 262 On some 32-bit architectures,
 263 the calling signature for these system calls differ,
 264 for the reasons described in
 265 .BR syscall (2).
 266 .SH BUGS
 267 A header file bug in glibc 2.12 meant that the minimum value of
 268 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
 269 .BR _POSIX_C_SOURCE
 270 required to expose the declaration of
 271 .BR ftruncate ()
 272 was 200809L instead of 200112L.
 273 This has been fixed in later glibc versions.
 274 .SH SEE ALSO
 275 .BR truncate (1),
 276 .BR open (2),
 277 .BR stat (2),
 278 .BR path_resolution (7)