man2/truncate.2

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