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 (date) "Linux man-pages (unreleased)"
  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 .P
  25 .BI "int truncate(const char *" path ", off_t " length );
  26 .BI "int ftruncate(int " fd ", off_t " length );
  27 .fi
  28 .P
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .P
  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 .P
  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 .P
  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 .P
  66 The file offset is not changed.
  67 .P
  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 .P
  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 .P
 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 VERSIONS
 180 The details in DESCRIPTION are for XSI-compliant systems.
 181 For non-XSI-compliant systems, the POSIX standard allows
 182 two behaviors for
 183 .BR ftruncate ()
 184 when
 185 .I length
 186 exceeds the file length
 187 (note that
 188 .BR truncate ()
 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
 194 .BR truncate ()
 195 and
 196 .BR ftruncate ()
 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
 200 .P
 201 On some 32-bit architectures,
 202 the calling signature for these system calls differ,
 203 for the reasons described in
 204 .BR syscall (2).
 205 .SH STANDARDS
 206 POSIX.1-2008.
 207 .SH HISTORY
 208 POSIX.1-2001,
 209 4.4BSD, SVr4 (first appeared in 4.2BSD).
 210 .\" POSIX.1-1996 has
 211 .\" .BR ftruncate ().
 212 .\" POSIX.1-2001 also has
 213 .\" .BR truncate (),
 214 .\" as an XSI extension.
 215 .\" .P
 216 .\" SVr4 documents additional
 217 .\" .BR truncate ()
 218 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 219 .\" .BR ftruncate ()
 220 .\" an additional EAGAIN error condition.
 221 .P
 222 The original Linux
 223 .BR truncate ()
 224 and
 225 .BR ftruncate ()
 226 system calls were not designed to handle large file offsets.
 227 Consequently, Linux 2.4 added
 228 .BR truncate64 ()
 229 and
 230 .BR ftruncate64 ()
 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.
 235 .SH NOTES
 236 .BR ftruncate ()
 237 can also be used to set the size of a POSIX shared memory object; 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)