truncate.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)truncate.2  6.9 (Berkeley) 3/10/91
  33 .\"
  34 .\" Modified Sat Jul 24 12:46:33 1993 by Rik Faith <faith@cs.unc.edu>
  35 .\" Modified Tue Oct 22 22:36:33 1996 by Eric S. Raymond <esr@thyrsus.com>
  36 .\" Modified Mon Dec 21 13:37:05 1998 by Andries Brouwer <aeb@cwi.nl>
  37 .\" Modified 7 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
  38 .\"
  39 .TH TRUNCATE 2 1998-12-21 "" "Linux Programmer's Manual"
  40 .SH NAME
  41 truncate, ftruncate \- truncate a file to a specified length
  42 .SH SYNOPSIS
  43 .B #include <unistd.h>
  44 .sp
  45 .BI "int truncate(const char *" path ", off_t " length );
  46 .br
  47 .BI "int ftruncate(int " fd ", off_t " length );
  48 .SH DESCRIPTION
  49 The
  50 .B truncate
  51 and
  52 .B ftruncate
  53 functions cause the regular file named by
  54 .I path
  55 or referenced by
  56 .I fd
  57 to be truncated to a size of precisely
  58 .I length
  59 bytes.
  60 .LP
  61 If the file previously was larger than this size, the extra data is lost.
  62 If the file previously was shorter, it is extended, and
  63 the extended part reads as zero bytes.
  64 .LP
  65 The file pointer is not changed.
  66 .LP
  67 With
  68 .BR ftruncate ,
  69 the file must be open for writing; with
  70 .BR truncate ,
  71 the file must be writable.
  72 .SH "RETURN VALUE"
  73 On success, zero is returned.  On error, \-1 is returned, and
  74 .I errno
  75 is set appropriately.
  76 .SH ERRORS
  77 For
  78 .BR truncate :
  79 .TP
  80 .B EACCES
  81 Search permission is denied for a component of the path prefix,
  82 or the named file is not writable by the user.
  83 .TP
  84 .B EFAULT
  85 .I Path
  86 points outside the process's allocated address space.
  87 .TP
  88 .B EFBIG
  89 The argument
  90 .I length
  91 is larger than the maximum file size. (XSI)
  92 .TP
  93 .B EINTR
  94 A signal was caught during execution.
  95 .TP
  96 .B EINVAL
  97 The argument
  98 .I length
  99 is negative or larger than the maximum file size.
 100 .TP
 101 .B EIO
 102 An I/O error occurred updating the inode.
 103 .TP
 104 .B EISDIR
 105 The named file is a directory.
 106 .TP
 107 .B ELOOP
 108 Too many symbolic links were encountered in translating the pathname.
 109 .TP
 110 .B ENAMETOOLONG
 111 A component of a pathname exceeded 255 characters,
 112 or an entire path name exceeded 1023 characters.
 113 .TP
 114 .B ENOENT
 115 The named file does not exist.
 116 .TP
 117 .B ENOTDIR
 118 A component of the path prefix is not a directory.
 119 .TP
 120 .B EROFS
 121 The named file resides on a read-only file system.
 122 .TP
 123 .B ETXTBSY
 124 The file is a pure procedure (shared text) file that is being executed.
 125 .PP
 126 For
 127 .B ftruncate
 128 the same errors apply, but instead of things that can be wrong with
 129 .IR path ,
 130 we now have things that can be wrong with
 131 .IR fd :
 132 .TP
 133 .B EBADF
 134 The
 135 .I fd
 136 is not a valid descriptor.
 137 .TP
 138 .BR EBADF " or " EINVAL
 139 The
 140 .I fd
 141 is not open for writing.
 142 .TP
 143 .B EINVAL
 144 The
 145 .I fd
 146 does not reference a regular file.
 147 .SH "CONFORMING TO"
 148 4.4BSD, SVr4 (these function calls first appeared in BSD 4.2).
 149 POSIX 1003.1-1996 has
 150 .BR ftruncate .
 151 POSIX 1003.1-2001 also has
 152 .IR truncate ,
 153 as an XSI extension.
 154 .LP
 155 SVr4 documents additional
 156 .B truncate
 157 error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
 158 .B ftruncate
 159 an additional EAGAIN error condition.
 160 .SH NOTES
 161 The above description is for XSI-compliant systems.
 162 For non-XSI-compliant systems, the POSIX standard allows
 163 two behaviours for
 164 .B ftruncate
 165 when
 166 .I length
 167 exceeds the file length
 168 (note that
 169 .B truncate
 170 is not specified at all in such an environment):
 171 either returning an error, or extending the file.
 172 (Most Unices follow the XSI requirement.)
 173 .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
 174 .SH "SEE ALSO"
 175 .BR open (2)