logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

posix_fallocate.3p (4005B)

    

  1. '\" et
  2. .TH POSIX_FALLOCATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. posix_fallocate
  12. \(em file space control
  13. (\fBADVANCED REALTIME\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <fcntl.h>
  18. .P
  19. int posix_fallocate(int \fIfd\fP, off_t \fIoffset\fP, off_t \fIlen\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIposix_fallocate\fR()
  24. function shall ensure that any required storage for regular file data
  25. starting at
  26. .IR offset
  27. and continuing for
  28. .IR len
  29. bytes is allocated on the file system storage media. If
  30. \fIposix_fallocate\fR()
  31. returns successfully, subsequent writes to the specified file data
  32. shall not fail due to the lack of free space on the file system storage
  33. media.
  34. .P
  35. If the
  36. .IR offset +\c
  37. .IR len
  38. is beyond the current file size, then
  39. \fIposix_fallocate\fR()
  40. shall adjust the file size to
  41. .IR offset +\c
  42. .IR len .
  43. Otherwise, the file size shall not be changed.
  44. .P
  45. It is implementation-defined whether a previous
  46. \fIposix_fadvise\fR()
  47. call influences allocation strategy.
  48. .P
  49. Space allocated via
  50. \fIposix_fallocate\fR()
  51. shall be freed by a successful call to
  52. \fIcreat\fR()
  53. or
  54. \fIopen\fR()
  55. that truncates the size of the file. Space allocated via
  56. \fIposix_fallocate\fR()
  57. may be freed by a successful call to
  58. \fIftruncate\fR()
  59. that reduces the file size to a size smaller than
  60. .IR offset +\c
  61. .IR len .
  62. .SH "RETURN VALUE"
  63. Upon successful completion,
  64. \fIposix_fallocate\fR()
  65. shall return zero; otherwise, an error number shall be returned to
  66. indicate the error.
  67. .SH ERRORS
  68. The
  69. \fIposix_fallocate\fR()
  70. function shall fail if:
  71. .TP
  72. .BR EBADF
  73. The
  74. .IR fd
  75. argument is not a valid file descriptor.
  76. .TP
  77. .BR EBADF
  78. The
  79. .IR fd
  80. argument references a file that was opened without write permission.
  81. .TP
  82. .BR EFBIG
  83. The value of
  84. .IR offset +\c
  85. .IR len
  86. is greater than the maximum file size.
  87. .TP
  88. .BR EINTR
  89. A signal was caught during execution.
  90. .TP
  91. .BR EINVAL
  92. The
  93. .IR len
  94. argument is less than zero, or the
  95. .IR offset
  96. argument is less than zero, or the underlying file system does not
  97. support this operation.
  98. .TP
  99. .BR EIO
  100. An I/O error occurred while reading from or writing to a file system.
  101. .TP
  102. .BR ENODEV
  103. The
  104. .IR fd
  105. argument does not refer to a regular file.
  106. .TP
  107. .BR ENOSPC
  108. There is insufficient free space remaining on the file system storage
  109. media.
  110. .TP
  111. .BR ESPIPE
  112. The
  113. .IR fd
  114. argument is associated with a pipe or FIFO.
  115. .P
  116. The
  117. \fIposix_fallocate\fR()
  118. function may fail if:
  119. .TP
  120. .BR EINVAL
  121. The
  122. .IR len
  123. argument is zero.
  124. .LP
  125. .IR "The following sections are informative."
  126. .SH EXAMPLES
  127. None.
  128. .SH "APPLICATION USAGE"
  129. The
  130. \fIposix_fallocate\fR()
  131. function is part of the Advisory Information option and need not be
  132. provided on all implementations.
  133. .SH RATIONALE
  134. None.
  135. .SH "FUTURE DIRECTIONS"
  136. None.
  137. .SH "SEE ALSO"
  138. .IR "\fIcreat\fR\^(\|)",
  139. .IR "\fIftruncate\fR\^(\|)",
  140. .IR "\fIopen\fR\^(\|)",
  141. .IR "\fIunlink\fR\^(\|)"
  142. .P
  143. The Base Definitions volume of POSIX.1\(hy2017,
  144. .IR "\fB<fcntl.h>\fP"
  145. .\"
  146. .SH COPYRIGHT
  147. Portions of this text are reprinted and reproduced in electronic form
  148. from IEEE Std 1003.1-2017, Standard for Information Technology
  149. -- Portable Operating System Interface (POSIX), The Open Group Base
  150. Specifications Issue 7, 2018 Edition,
  151. Copyright (C) 2018 by the Institute of
  152. Electrical and Electronics Engineers, Inc and The Open Group.
  153. In the event of any discrepancy between this version and the original IEEE and
  154. The Open Group Standard, the original IEEE and The Open Group Standard
  155. is the referee document. The original Standard can be obtained online at
  156. http://www.opengroup.org/unix/online.html .
  157. .PP
  158. Any typographical or formatting errors that appear
  159. in this page are most likely
  160. to have been introduced during the conversion of the source files to
  161. man page format. To report such errors, see
  162. https://www.kernel.org/doc/man-pages/reporting_bugs.html .