1 files changed, 121 insertions, 0 deletions
diff --git a/man3p/fsync.3p b/man3p/fsync.3p
new file mode 100644
index 000000000..f0890f12a
--- /dev/null
+++ b/man3p/fsync.3p
@@ -0,0 +1,121 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "FSYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" fsync 
+.SH NAME
+fsync \- synchronize changes to a file
+.SH SYNOPSIS
+.LP
+\fB#include <unistd.h>
+.br
+.sp
+int fsync(int\fP \fIfildes\fP\fB); \fP
+\fB
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIfsync\fP() function shall request that all data for the open
+file descriptor named by \fIfildes\fP is to be transferred
+to the storage device associated with the file described by \fIfildes\fP
+in an implementation-defined manner. The \fIfsync\fP()
+function shall not return until the system has completed that action
+or until an error is detected.
+.LP
+If _POSIX_SYNCHRONIZED_IO is defined, the \fIfsync\fP() function shall
+force all currently queued I/O operations associated with
+the file indicated by file descriptor \fIfildes\fP to the synchronized
+I/O completion state. All I/O operations shall be completed
+as defined for synchronized I/O file integrity completion. 
+.SH RETURN VALUE
+.LP
+Upon successful completion, \fIfsync\fP() shall return 0. Otherwise,
+-1 shall be returned and \fIerrno\fP set to indicate the
+error. If the \fIfsync\fP() function fails, outstanding I/O operations
+are not guaranteed to have been completed.
+.SH ERRORS
+.LP
+The \fIfsync\fP() function shall fail if:
+.TP 7
+.B EBADF
+The \fIfildes\fP argument is not a valid descriptor.
+.TP 7
+.B EINTR
+The \fIfsync\fP() function was interrupted by a signal.
+.TP 7
+.B EINVAL
+The \fIfildes\fP argument does not refer to a file on which this operation
+is possible.
+.TP 7
+.B EIO
+An I/O error occurred while reading from or writing to the file system.
+.sp
+.LP
+In the event that any of the queued I/O operations fail, \fIfsync\fP()
+shall return the error conditions defined for \fIread\fP() and \fIwrite\fP().
+.LP
+\fIThe following sections are informative.\fP
+.SH EXAMPLES
+.LP
+None.
+.SH APPLICATION USAGE
+.LP
+The \fIfsync\fP() function should be used by programs which require
+modifications to a file to be completed before continuing;
+for example, a program which contains a simple transaction facility
+might use it to ensure that all modifications to a file or
+files caused by a transaction are recorded.
+.SH RATIONALE
+.LP
+The \fIfsync\fP() function is intended to force a physical write of
+data from the buffer cache, and to assure that after a
+system crash or other failure that all data up to the time of the
+\fIfsync\fP() call is recorded on the disk. Since the concepts
+of "buffer cache", "system crash", "physical write", and "non-volatile
+storage" are not defined here, the wording has to be
+more abstract.
+.LP
+If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily
+on the conformance document to tell the user what can be
+expected from the system. It is explicitly intended that a null implementation
+is permitted. This could be valid in the case where
+the system cannot assure non-volatile storage under any circumstances
+or when the system is highly fault-tolerant and the
+functionality is not required. In the middle ground between these
+extremes, \fIfsync\fP() might or might not actually cause data
+to be written where it is safe from a power failure. The conformance
+document should identify at least that one configuration
+exists (and how to obtain that configuration) where this can be assured
+for at least some files that the user can select to use for
+critical data. It is not intended that an exhaustive list is required,
+but rather sufficient information is provided so that if
+critical data needs to be saved, the user can determine how the system
+is to be configured to allow the data to be written to
+non-volatile storage.
+.LP
+It is reasonable to assert that the key aspects of \fIfsync\fP() are
+unreasonable to test in a test suite. That does not make
+the function any less valuable, just more difficult to test. A formal
+conformance test should probably force a system crash (power
+shutdown) during the test for this condition, but it needs to be done
+in such a way that automated testing does not require this to
+be done except when a formal record of the results is being made.
+It would also not be unreasonable to omit testing for
+\fIfsync\fP(), allowing it to be treated as a quality-of-implementation
+issue.
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIsync\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
+\fI<unistd.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 .