From c48348233c467f7dc96728a31710abbb12cbe1f1 Mon Sep 17 00:00:00 2001
From: Filipe David Manana <fdmanana@apache.org>
Date: Tue, 28 Dec 2010 10:57:04 +0000
Subject: Add file:allocate/3 operation

This operation allows pre-allocation of space for files.
It succeeds only on systems that support such operation.

The POSIX standard defines the optional system call
posix_fallocate() to implement this feature. However,
some systems implement more specific functions to
accomplish the same operation.

On Linux, if the more specific function fallocate() is
implemented, it is used instead of posix_fallocate(),
falling back to posix_fallocate() if the fallocate()
call failed (it's only supported for the ext4, ocfs2,
xfs and btrfs file systems at the moment).

On Mac OS X it uses the specific fcntl() operation
F_PREALLOCATE, falling back to posix_fallocate() if
it's available (at the moment Mac OS X doesn't provide
posix_fallocate()).

On any other UNIX system, it uses posix_fallocate() if it's
available. Any other system not providing this system call
or any function to pre-allocate space for files, this operation
always fails with the ENOTSUP POSIX error.
---
 lib/kernel/doc/src/file.xml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'lib/kernel/doc')

diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index 536b98b5f5..e30ade1bd2 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -169,6 +169,18 @@
         <p>On some platforms, this function might have no effect.</p>
       </desc>
     </func>
+    <func>
+      <name name="allocate" arity="3"/>
+      <fsummary>Allocate file space</fsummary>
+      <desc>
+        <p><c>allocate/3</c> can be used to preallocate space for a file.</p>
+        <p>This function only succeeds in platforms that implement this
+          feature. When it succeeds, space is preallocated for the file but
+          the file size might not be updated. This behaviour depends on the
+          preallocation implementation. To guarantee the file size is updated
+          one must truncate the file to the new size.</p>
+      </desc>
+    </func>
     <func>
       <name name="change_group" arity="2"/>
       <fsummary>Change group of a file</fsummary>
-- 
cgit v1.2.3