lib/libc/sys/truncate.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)truncate.2  8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 30, 2020
  32 .Dt TRUNCATE 2
  33 .Os
  34 .Sh NAME
  35 .Nm truncate ,
  36 .Nm ftruncate
  37 .Nd truncate or extend a file to a specified length
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn truncate "const char *path" "off_t length"
  44 .Ft int
  45 .Fn ftruncate "int fd" "off_t length"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn truncate
  49 system call
  50 causes the file named by
  51 .Fa path
  52 or referenced by
  53 .Fa fd
  54 to be truncated or extended to
  55 .Fa length
  56 bytes in size.
  57 If the file
  58 was larger than this size, the extra data
  59 is lost.
  60 If the file was smaller than this size,
  61 it will be extended as if by writing bytes
  62 with the value zero.
  63 .Pp
  64 The
  65 .Fn ftruncate
  66 system call causes the file or shared memory object backing the file descriptor
  67 .Fa fd
  68 to be truncated or extended to
  69 .Fa length
  70 bytes in size.
  71 The file descriptor must be a valid file descriptor open for writing.
  72 The file position pointer associated with the file descriptor
  73 .Fa fd
  74 will not be modified.
  75 .Sh RETURN VALUES
  76 .Rv -std
  77 If the file to be modified is not a directory or
  78 a regular file, the
  79 .Fn truncate
  80 call has no effect and returns the value 0.
  81 .Sh ERRORS
  82 The
  83 .Fn truncate
  84 system call
  85 succeeds unless:
  86 .Bl -tag -width Er
  87 .It Bq Er ENOTDIR
  88 A component of the path prefix is not a directory.
  89 .It Bq Er ENAMETOOLONG
  90 A component of a pathname exceeded 255 characters,
  91 or an entire path name exceeded 1023 characters.
  92 .It Bq Er ENOENT
  93 The named file does not exist.
  94 .It Bq Er EACCES
  95 Search permission is denied for a component of the path prefix.
  96 .It Bq Er EACCES
  97 The named file is not writable by the user.
  98 .It Bq Er ELOOP
  99 Too many symbolic links were encountered in translating the pathname.
 100 .It Bq Er EPERM
 101 The named file has its immutable or append-only flag set, see the
 102 .Xr chflags 2
 103 manual page for more information.
 104 .It Bq Er EISDIR
 105 The named file is a directory.
 106 .It Bq Er EROFS
 107 The named file resides on a read-only file system.
 108 .It Bq Er ETXTBSY
 109 The file is a pure procedure (shared text) file that is being executed.
 110 .It Bq Er EFBIG
 111 The
 112 .Fa length
 113 argument was greater than the maximum file size.
 114 .It Bq Er EINVAL
 115 The
 116 .Fa length
 117 argument was less than 0.
 118 .It Bq Er EIO
 119 An I/O error occurred updating the inode.
 120 .It Bq Er EINTEGRITY
 121 Corrupted data was detected while reading from the file system.
 122 .It Bq Er EFAULT
 123 The
 124 .Fa path
 125 argument
 126 points outside the process's allocated address space.
 127 .El
 128 .Pp
 129 The
 130 .Fn ftruncate
 131 system call
 132 succeeds unless:
 133 .Bl -tag -width Er
 134 .It Bq Er EBADF
 135 The
 136 .Fa fd
 137 argument
 138 is not a valid descriptor.
 139 .It Bq Er EINVAL
 140 The
 141 .Fa fd
 142 argument
 143 references a file descriptor that is not a regular file or shared memory object.
 144 .It Bq Er EINVAL
 145 The
 146 .Fa fd
 147 descriptor
 148 is not open for writing.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr chflags 2 ,
 152 .Xr open 2 ,
 153 .Xr shm_open 2
 154 .Sh HISTORY
 155 The
 156 .Fn truncate
 157 and
 158 .Fn ftruncate
 159 system calls appeared in
 160 .Bx 4.2 .
 161 .Sh BUGS
 162 These calls should be generalized to allow ranges
 163 of bytes in a file to be discarded.
 164 .Pp
 165 Historically, the use of
 166 .Fn truncate
 167 or
 168 .Fn ftruncate
 169 to extend a file was not portable, but this behavior became required in
 170 .St -p1003.1-2008 .