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 The argument
 127 .I path
 128 points outside the process's allocated address space.
 129 .TP
 130 .B EFBIG
 131 The argument
 132 .I length
 133 is larger than the maximum file size. (XSI)
 134 .TP
 135 .B EINTR
 136 While blocked waiting to complete,
 137 the call was interrupted by a signal handler; see
 138 .BR fcntl (2)
 139 and
 140 .BR signal (7).
 141 .TP
 142 .B EINVAL
 143 The argument
 144 .I length
 145 is negative or larger than the maximum file size.
 146 .TP
 147 .B EIO
 148 An I/O error occurred updating the inode.
 149 .TP
 150 .B EISDIR
 151 The named file is a directory.
 152 .TP
 153 .B ELOOP
 154 Too many symbolic links were encountered in translating the pathname.
 155 .TP
 156 .B ENAMETOOLONG
 157 A component of a pathname exceeded 255 characters,
 158 or an entire pathname exceeded 1023 characters.
 159 .TP
 160 .B ENOENT
 161 The named file does not exist.
 162 .TP
 163 .B ENOTDIR
 164 A component of the path prefix is not a directory.
 165 .TP
 166 .B EPERM
 167 .\" This happens for at least MSDOS and VFAT filesystems
 168 .\" on kernel 2.6.13
 169 The underlying filesystem does not support extending
 170 a file beyond its current size.
 171 .TP
 172 .B EROFS
 173 The named file resides on a read-only filesystem.
 174 .TP
 175 .B ETXTBSY
 176 The file is a pure procedure (shared text) file that is being executed.
 177 .PP
 178 For
 179 .BR ftruncate ()
 180 the same errors apply, but instead of things that can be wrong with
 181 .IR path ,
 182 we now have things that can be wrong with the file descriptor,
 183 .IR fd :
 184 .TP
 185 .B EBADF
 186 .I fd
 187 is not a valid descriptor.
 188 .TP
 189 .BR EBADF " or " EINVAL
 190 .I fd
 191 is not open for writing.
 192 .TP
 193 .B EINVAL
 194 .I fd
 195 does not reference a regular file.
 196 .SH CONFORMING TO
 197 4.4BSD, SVr4, POSIX.1-2001 (these calls first appeared in 4.2BSD).
 198 .\" POSIX.1-1996 has
 199 .\" .BR ftruncate ().
 200 .\" POSIX.1-2001 also has
 201 .\" .BR truncate (),
 202 .\" as an XSI extension.
 203 .\" .LP
 204 .\" SVr4 documents additional
 205 .\" .BR truncate ()
 206 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 207 .\" .BR ftruncate ()
 208 .\" an additional EAGAIN error condition.
 209 .SH NOTES
 210 The details in DESCRIPTION are for XSI-compliant systems.
 211 For non-XSI-compliant systems, the POSIX standard allows
 212 two behaviors for
 213 .BR ftruncate ()
 214 when
 215 .I length
 216 exceeds the file length
 217 (note that
 218 .BR truncate ()
 219 is not specified at all in such an environment):
 220 either returning an error, or extending the file.
 221 Like most UNIX implementations, Linux follows the XSI requirement
 222 when dealing with native filesystems.
 223 However, some nonnative filesystems do not permit
 224 .BR truncate ()
 225 and
 226 .BR ftruncate ()
 227 to be used to extend a file beyond its current length:
 228 a notable example on Linux is VFAT.
 229 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
 230
 231 The original Linux
 232 .BR truncate ()
 233 and
 234 .BR ftruncate ()
 235 system calls were not designed to handle large file offsets.
 236 Consequently, Linux 2.4 added
 237 .BR truncate64 ()
 238 and
 239 .BR ftruncate64 ()
 240 system calls that handle large files.
 241 However, these details can be ignored by applications using glibc, whose
 242 wrapper functions transparently employ the more recent system calls
 243 where they are available.
 244
 245 On some 32-bit architectures,
 246 the calling signature for these system calls differ,
 247 for the reasons described in
 248 .BR syscall (2).
 249 .SH BUGS
 250 A header file bug in glibc 2.12 meant that the minimum value of
 251 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
 252 .BR _POSIX_C_SOURCE
 253 required to expose the declaration of
 254 .BR ftruncate ()
 255 was 200809L instead of 200112L.
 256 This has been fixed in later glibc versions.
 257 .SH SEE ALSO
 258 .BR open (2),
 259 .BR stat (2),
 260 .BR path_resolution (7)
 261 .SH COLOPHON
 262 This page is part of release 3.76 of the Linux
 263 .I man-pages
 264 project.
 265 A description of the project,
 266 information about reporting bugs,
 267 and the latest version of this page,
 268 can be found at
 269 \%http://www.kernel.org/doc/man\-pages/.