original/man3/posix_fallocate.3

   1 .\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH POSIX_FALLOCATE 3  2013-02-12 "GNU" "Linux Programmer's Manual"
  26 .SH NAME
  27 posix_fallocate \- allocate file space
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <fcntl.h>
  31 .sp
  32 .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len );
  33 .fi
  34 .sp
  35 .ad l
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .sp
  41 .BR posix_fallocate ():
  42 .RS 4
  43 _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
  44 .RE
  45 .ad
  46 .SH DESCRIPTION
  47 The function
  48 .BR posix_fallocate ()
  49 ensures that disk space is allocated for the file referred to by the
  50 descriptor
  51 .I fd
  52 for the bytes in the range starting at
  53 .I offset
  54 and continuing for
  55 .I len
  56 bytes.
  57 After a successful call to
  58 .BR posix_fallocate (),
  59 subsequent writes to bytes in the specified range are
  60 guaranteed not to fail because of lack of disk space.
  61
  62 If the size of the file is less than
  63 .IR offset + len ,
  64 then the file is increased to this size;
  65 otherwise the file size is left unchanged.
  66 .SH RETURN VALUE
  67 .BR posix_fallocate ()
  68 returns zero on success, or an error number on failure.
  69 Note that
  70 .I errno
  71 is not set.
  72 .SH ERRORS
  73 .TP
  74 .B EBADF
  75 .I fd
  76 is not a valid file descriptor, or is not opened for writing.
  77 .TP
  78 .B EFBIG
  79 .I offset+len
  80 exceeds the maximum file size.
  81 .TP
  82 .B EINVAL
  83 .I offset
  84 was less than 0, or
  85 .I len
  86 was less than or equal to 0.
  87 .TP
  88 .B ENODEV
  89 .I fd
  90 does not refer to a regular file.
  91 .TP
  92 .B ENOSPC
  93 There is not enough space left on the device containing the file
  94 referred to by
  95 .IR fd .
  96 .TP
  97 .B ESPIPE
  98 .I fd
  99 refers to a pipe.
 100 .SH VERSIONS
 101 .BR posix_fallocate ()
 102 is available since glibc 2.1.94.
 103 .SH CONFORMING TO
 104 POSIX.1-2001.
 105
 106 POSIX.1-2008 says that an implementation
 107 .I shall
 108 give the
 109 .B EINVAL
 110 error if
 111 .I len
 112 was 0, or
 113 .I offset
 114 was less than 0.
 115 POSIX.1-2001 says that an implementation
 116 .I shall
 117 give the
 118 .B EINVAL
 119 error if
 120 .I len
 121 is less than 0, or
 122 .I offset
 123 was less than 0, and
 124 .I may
 125 give the error if
 126 .I len
 127 equals zero.
 128 .SH SEE ALSO
 129 .BR fallocate (1),
 130 .BR fallocate (2),
 131 .BR lseek (2),
 132 .BR posix_fadvise (2)
 133 .SH COLOPHON
 134 This page is part of release 3.68 of the Linux
 135 .I man-pages
 136 project.
 137 A description of the project,
 138 information about reporting bugs,
 139 and the latest version of this page,
 140 can be found at
 141 \%http://www.kernel.org/doc/man\-pages/.