des_crypt.3: Minor wording fix in VERSIONS

[thirdparty/man-pages.git] / man3 / posix_fallocate.3

diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3
index d8f0c38d5f658ec6ac99ed0f3978e9da8d283139..58338d673f85ad4270340cd5f846390d5b9ad52b 100644 (file)
--- a/man3/posix_fallocate.3
+++ b/man3/posix_fallocate.3
@@ -1,5 +1,6 @@
-.\" (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -19,22 +20,34 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
-.TH POSIX_FALLOCATE 3  2006-03-01 "GNU" "Linux Programmer's Manual"
+.TH POSIX_FALLOCATE 3  2017-09-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
 posix_fallocate \- allocate file space
 .SH SYNOPSIS
 .nf
-.B #define _XOPEN_SOURCE 600
-.B #include <stdlib.h>
-.sp
+.B #include <fcntl.h>
+.PP
 .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len );
 .fi
+.PP
+.ad l
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.BR posix_fallocate ():
+.RS 4
+_POSIX_C_SOURCE\ >=\ 200112L
+.RE
+.ad
 .SH DESCRIPTION
 The function
 .BR posix_fallocate ()
 ensures that disk space is allocated for the file referred to by the
-descriptor
+file descriptor
 .I fd
 for the bytes in the range starting at
 .I offset
@@ -45,18 +58,18 @@ After a successful call to
 .BR posix_fallocate (),
 subsequent writes to bytes in the specified range are
 guaranteed not to fail because of lack of disk space.
-
+.PP
 If the size of the file is less than
 .IR offset + len ,
 then the file is increased to this size;
 otherwise the file size is left unchanged.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 .BR posix_fallocate ()
 returns zero on success, or an error number on failure.
 Note that
 .I errno
 is not set.
-.SH "ERRORS"
+.SH ERRORS
 .TP
 .B EBADF
 .I fd
@@ -66,11 +79,15 @@ is not a valid file descriptor, or is not opened for writing.
 .I offset+len
 exceeds the maximum file size.
 .TP
+.B EINTR
+A signal was caught during execution.
+.TP
 .B EINVAL
 .I offset
-or
+was less than 0, or
 .I len
-was less than 0.
+was less than or equal to 0, or the underlying filesystem does not
+support the operation.
 .TP
 .B ENODEV
 .I fd
@@ -83,13 +100,86 @@ referred to by
 .TP
 .B ESPIPE
 .I fd
-refers to a pipe of file descriptor.
+refers to a pipe.
 .SH VERSIONS
 .BR posix_fallocate ()
 is available since glibc 2.1.94.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR posix_fallocate ()
+T}     Thread safety   MT-Safe (but see NOTES)
+.TE
+.SH CONFORMING TO
 POSIX.1-2001.
-.SH "SEE ALSO"
+.PP
+POSIX.1-2008 says that an implementation
+.I shall
+give the
+.B EINVAL
+error if
+.I len
+was 0, or
+.I offset
+was less than 0.
+POSIX.1-2001 says that an implementation
+.I shall
+give the
+.B EINVAL
+error if
+.I len
+is less than 0, or
+.I offset
+was less than 0, and
+.I may
+give the error if
+.I len
+equals zero.
+.SH NOTES
+In the glibc implementation,
+.BR posix_fallocate ()
+is implemented using the
+.BR fallocate (2)
+system call, which is MT-safe.
+If the underlying filesystem does not support
+.BR fallocate (2),
+then the operation is emulated with the following caveats:
+.IP * 2
+The emulation is inefficient.
+.IP *
+There is a race condition where concurrent writes from another thread or
+process could be overwritten with null bytes.
+.IP *
+There is a race condition where concurrent file size increases by
+another thread or process could result in a file whose size is smaller
+than expected.
+.IP *
+If
+.I fd
+has been opened with the
+.B O_APPEND
+or
+.B O_WRONLY
+flags, the function fails with the error
+.BR EBADF .
+.PP
+In general, the emulation is not MT-safe.
+On Linux, applications may use
+.BR fallocate (2)
+if they cannot tolerate the emulation caveats.
+In general, this is
+only recommended if the application plans to terminate the operation if
+.B EOPNOTSUPP
+is returned, otherwise the application itself will need to implement a
+fallback with all the same problems as the emulation provided by glibc.
+.SH SEE ALSO
+.BR fallocate (1),
+.BR fallocate (2),
 .BR lseek (2),
-.BR posix_fadvise (2),
-.BR feature_test_macros (7)
+.BR posix_fadvise (2)