mirror of https://github.com/mkerrisk/man-pages
110 lines
3.4 KiB
Plaintext
110 lines
3.4 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "POSIX_FALLOCATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" posix_fallocate
|
||
|
.SH NAME
|
||
|
posix_fallocate \- file space control (\fBADVANCED REALTIME\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <fcntl.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int posix_fallocate(int\fP \fIfd\fP\fB, off_t\fP \fIoffset\fP\fB,
|
||
|
size_t\fP \fIlen\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIposix_fallocate\fP() function shall ensure that any required
|
||
|
storage for regular file data starting at \fIoffset\fP and
|
||
|
continuing for \fIlen\fP bytes is allocated on the file system storage
|
||
|
media. If \fIposix_fallocate\fP() returns successfully,
|
||
|
subsequent writes to the specified file data shall not fail due to
|
||
|
the lack of free space on the file system storage media.
|
||
|
.LP
|
||
|
If the \fIoffset\fP+ \fIlen\fP is beyond the current file size, then
|
||
|
\fIposix_fallocate\fP() shall adjust the file size to
|
||
|
\fIoffset\fP+ \fIlen\fP. Otherwise, the file size shall not be changed.
|
||
|
.LP
|
||
|
It is implementation-defined whether a previous \fIposix_fadvise\fP()
|
||
|
call
|
||
|
influences allocation strategy.
|
||
|
.LP
|
||
|
Space allocated via \fIposix_fallocate\fP() shall be freed by a successful
|
||
|
call to \fIcreat\fP() or \fIopen\fP() that truncates the size of the
|
||
|
file. Space allocated via \fIposix_fallocate\fP() may be freed by
|
||
|
a successful call to \fIftruncate\fP() that reduces the file size
|
||
|
to a size smaller than \fIoffset\fP+
|
||
|
\fIlen\fP.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, \fIposix_fallocate\fP() shall return zero;
|
||
|
otherwise, an error number shall be returned to indicate
|
||
|
the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIposix_fallocate\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIfd\fP argument is not a valid file descriptor.
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIfd\fP argument references a file that was opened without write
|
||
|
permission.
|
||
|
.TP 7
|
||
|
.B EFBIG
|
||
|
The value of \fIoffset\fP+ \fIlen\fP is greater than the maximum file
|
||
|
size.
|
||
|
.TP 7
|
||
|
.B EINTR
|
||
|
A signal was caught during execution.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The \fIlen\fP argument was zero or the \fIoffset\fP argument was less
|
||
|
than zero.
|
||
|
.TP 7
|
||
|
.B EIO
|
||
|
An I/O error occurred while reading from or writing to a file system.
|
||
|
.TP 7
|
||
|
.B ENODEV
|
||
|
The \fIfd\fP argument does not refer to a regular file.
|
||
|
.TP 7
|
||
|
.B ENOSPC
|
||
|
There is insufficient free space remaining on the file system storage
|
||
|
media.
|
||
|
.TP 7
|
||
|
.B ESPIPE
|
||
|
The \fIfd\fP argument is associated with a pipe or FIFO.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
The \fIposix_fallocate\fP() function is part of the Advisory Information
|
||
|
option and need not be provided on all
|
||
|
implementations.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIcreat\fP() , \fIftruncate\fP() , \fIopen\fP() , \fIunlink\fP()
|
||
|
, the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<fcntl.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|