original/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 2013-04-01 "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 .sp
  51 .BI "int truncate(const char *" path ", off_t " length );
  52 .br
  53 .BI "int ftruncate(int " fd ", off_t " length );
  54 .sp
  55 .in -4n
  56 Feature Test Macro Requirements for glibc (see
  57 .BR feature_test_macros (7)):
  58 .in
  59 .ad l
  60 .PD 0
  61 .sp
  62 .BR truncate ():
  63 .RS 4
  64 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  65 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  66 .br
  67 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  68 .RE
  69 .sp
  70 .BR ftruncate ():
  71 .RS 4
  72 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  73 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  74 .br
  75 || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE\ >=\ 200112L
  76 .RE
  77 .PD
  78 .ad b
  79 .SH DESCRIPTION
  80 The
  81 .BR truncate ()
  82 and
  83 .BR ftruncate ()
  84 functions cause the regular file named by
  85 .I path
  86 or referenced by
  87 .I fd
  88 to be truncated to a size of precisely
  89 .I length
  90 bytes.
  91 .LP
  92 If the file previously was larger than this size, the extra data is lost.
  93 If the file previously was shorter, it is extended, and
  94 the extended part reads as null bytes (\(aq\\0\(aq).
  95 .LP
  96 The file offset is not changed.
  97 .LP
  98 If the size changed, then the st_ctime and st_mtime fields
  99 (respectively, time of last status change and
 100 time of last modification; see
 101 .BR stat (2))
 102 for the file are updated,
 103 and the set-user-ID and set-group-ID permission bits may be cleared.
 104 .LP
 105 With
 106 .BR ftruncate (),
 107 the file must be open for writing; with
 108 .BR truncate (),
 109 the file must be writable.
 110 .SH RETURN VALUE
 111 On success, zero is returned.
 112 On error, \-1 is returned, and
 113 .I errno
 114 is set appropriately.
 115 .SH ERRORS
 116 For
 117 .BR truncate ():
 118 .TP
 119 .B EACCES
 120 Search permission is denied for a component of the path prefix,
 121 or the named file is not writable by the user.
 122 (See also
 123 .BR path_resolution (7).)
 124 .TP
 125 .B EFAULT
 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 EROFS
 172 The named file resides on a read-only filesystem.
 173 .TP
 174 .B ETXTBSY
 175 The file is a pure procedure (shared text) file that is being executed.
 176 .PP
 177 For
 178 .BR ftruncate ()
 179 the same errors apply, but instead of things that can be wrong with
 180 .IR path ,
 181 we now have things that can be wrong with the file descriptor,
 182 .IR fd :
 183 .TP
 184 .B EBADF
 185 .I fd
 186 is not a valid descriptor.
 187 .TP
 188 .BR EBADF " or " EINVAL
 189 .I fd
 190 is not open for writing.
 191 .TP
 192 .B EINVAL
 193 .I fd
 194 does not reference a regular file.
 195 .SH CONFORMING TO
 196 4.4BSD, SVr4, POSIX.1-2001 (these calls first appeared in 4.2BSD).
 197 .\" POSIX.1-1996 has
 198 .\" .BR ftruncate ().
 199 .\" POSIX.1-2001 also has
 200 .\" .BR truncate (),
 201 .\" as an XSI extension.
 202 .\" .LP
 203 .\" SVr4 documents additional
 204 .\" .BR truncate ()
 205 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 206 .\" .BR ftruncate ()
 207 .\" an additional EAGAIN error condition.
 208 .SH NOTES
 209 The details in DESCRIPTION are for XSI-compliant systems.
 210 For non-XSI-compliant systems, the POSIX standard allows
 211 two behaviors for
 212 .BR ftruncate ()
 213 when
 214 .I length
 215 exceeds the file length
 216 (note that
 217 .BR truncate ()
 218 is not specified at all in such an environment):
 219 either returning an error, or extending the file.
 220 Like most UNIX implementations, Linux follows the XSI requirement
 221 when dealing with native filesystems.
 222 However, some nonnative filesystems do not permit
 223 .BR truncate ()
 224 and
 225 .BR ftruncate ()
 226 to be used to extend a file beyond its current length:
 227 a notable example on Linux is VFAT.
 228 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
 229
 230 The original Linux
 231 .BR truncate ()
 232 and
 233 .BR ftruncate ()
 234 system calls were not designed to handle large file offsets.
 235 Consequently, Linux 2.4 added
 236 .BR truncate64 ()
 237 and
 238 .BR ftruncate64 ()
 239 system calls that handle large files.
 240 However, these details can be ignored by applications using glibc, whose
 241 wrapper functions transparently employ the more recent system calls
 242 where they are available.
 243
 244 On some 32-bit architectures,
 245 the calling signature for these system calls differ,
 246 for the reasons described in
 247 .BR syscall (2).
 248 .SH BUGS
 249 A header file bug in glibc 2.12 meant that the minimum value of
 250 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
 251 .BR _POSIX_C_SOURCE
 252 required to expose the declaration of
 253 .BR ftruncate ()
 254 was 200809L instead of 200112L.
 255 This has been fixed in later glibc versions.
 256 .SH SEE ALSO
 257 .BR open (2),
 258 .BR stat (2),
 259 .BR path_resolution (7)
 260 .SH COLOPHON
 261 This page is part of release 3.68 of the Linux
 262 .I man-pages
 263 project.
 264 A description of the project,
 265 information about reporting bugs,
 266 and the latest version of this page,
 267 can be found at
 268 \%http://www.kernel.org/doc/man\-pages/.