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 EPERM
 173 The operation was prevented by a file seal; see
 174 .BR fcntl (2).
 175 .TP
 176 .B EROFS
 177 The named file resides on a read-only filesystem.
 178 .TP
 179 .B ETXTBSY
 180 The file is a pure procedure (shared text) file that is being executed.
 181 .PP
 182 For
 183 .BR ftruncate ()
 184 the same errors apply, but instead of things that can be wrong with
 185 .IR path ,
 186 we now have things that can be wrong with the file descriptor,
 187 .IR fd :
 188 .TP
 189 .B EBADF
 190 .I fd
 191 is not a valid descriptor.
 192 .TP
 193 .BR EBADF " or " EINVAL
 194 .I fd
 195 is not open for writing.
 196 .TP
 197 .B EINVAL
 198 .I fd
 199 does not reference a regular file.
 200 .SH CONFORMING TO
 201 4.4BSD, SVr4, POSIX.1-2001 (these calls first appeared in 4.2BSD).
 202 .\" POSIX.1-1996 has
 203 .\" .BR ftruncate ().
 204 .\" POSIX.1-2001 also has
 205 .\" .BR truncate (),
 206 .\" as an XSI extension.
 207 .\" .LP
 208 .\" SVr4 documents additional
 209 .\" .BR truncate ()
 210 .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 211 .\" .BR ftruncate ()
 212 .\" an additional EAGAIN error condition.
 213 .SH NOTES
 214 The details in DESCRIPTION are for XSI-compliant systems.
 215 For non-XSI-compliant systems, the POSIX standard allows
 216 two behaviors for
 217 .BR ftruncate ()
 218 when
 219 .I length
 220 exceeds the file length
 221 (note that
 222 .BR truncate ()
 223 is not specified at all in such an environment):
 224 either returning an error, or extending the file.
 225 Like most UNIX implementations, Linux follows the XSI requirement
 226 when dealing with native filesystems.
 227 However, some nonnative filesystems do not permit
 228 .BR truncate ()
 229 and
 230 .BR ftruncate ()
 231 to be used to extend a file beyond its current length:
 232 a notable example on Linux is VFAT.
 233 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
 234
 235 The original Linux
 236 .BR truncate ()
 237 and
 238 .BR ftruncate ()
 239 system calls were not designed to handle large file offsets.
 240 Consequently, Linux 2.4 added
 241 .BR truncate64 ()
 242 and
 243 .BR ftruncate64 ()
 244 system calls that handle large files.
 245 However, these details can be ignored by applications using glibc, whose
 246 wrapper functions transparently employ the more recent system calls
 247 where they are available.
 248
 249 On some 32-bit architectures,
 250 the calling signature for these system calls differ,
 251 for the reasons described in
 252 .BR syscall (2).
 253 .SH BUGS
 254 A header file bug in glibc 2.12 meant that the minimum value of
 255 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
 256 .BR _POSIX_C_SOURCE
 257 required to expose the declaration of
 258 .BR ftruncate ()
 259 was 200809L instead of 200112L.
 260 This has been fixed in later glibc versions.
 261 .SH SEE ALSO
 262 .BR open (2),
 263 .BR stat (2),
 264 .BR path_resolution (7)