Merge branch 'fdm/file-allocate/OTP-10680'

* fdm/file-allocate/OTP-10680:
  Update preloaded prim_file.beam
  erts: Fix xcomp configure for fallocate
  Add file:allocate/3 operation

14 files changed, 365 insertions, 7 deletions

diff --git a/erts/configure.in b/erts/configure.in
index 3256b0cb59..a73bb358a0 100644
--- a/erts/configure.in
+++ b/erts/configure.in
@@ -1075,8 +1075,45 @@ fi
 
 AC_SUBST(ERTS_BUILD_SMP_EMU)
 
-AC_CHECK_FUNCS([posix_fadvise])
+AC_CHECK_FUNCS([posix_fadvise, fallocate])
+AC_CHECK_HEADERS([linux/falloc.h])
 
+dnl * Old glibcs have broken posix_fallocate(). Make sure not to use it.
+dnl * It may also be broken in AIX.
+AC_CACHE_CHECK([whether posix_fallocate() works],i_cv_posix_fallocate_works,[
+    AC_TRY_RUN([
+        #if !defined(__sun) && !defined(__sun__)
+        #define _XOPEN_SOURCE 600
+        #endif
+        #include <stdio.h>
+        #include <stdlib.h>
+        #include <fcntl.h>
+        #include <unistd.h>
+        #if defined(__GLIBC__) && (__GLIBC__ < 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ < 7))
+            possibly broken posix_fallocate
+        #endif
+        int main() {
+            int fd = creat("conftest.temp", 0600);
+            int ret;
+            if (-1 == fd) {
+               perror("creat()");
+               return 2;
+            }
+            ret = posix_fallocate(fd, 1024, 1024) < 0 ? 1 : 0;
+            unlink("conftest.temp");
+            return ret;
+        }
+    ], [
+        i_cv_posix_fallocate_works=yes
+    ], [
+        i_cv_posix_fallocate_works=no
+    ], [
+        i_cv_posix_fallocate_works=no
+    ])
+])
+if test $i_cv_posix_fallocate_works = yes; then
+   AC_DEFINE(HAVE_POSIX_FALLOCATE,, Define if you have a working posix_fallocate())
+fi
 
 #
 # Figure out if the emulator should use threads. The default is set above
diff --git a/erts/emulator/drivers/common/efile_drv.c b/erts/emulator/drivers/common/efile_drv.c
index 2ac7f169af..25b02db2c9 100644
--- a/erts/emulator/drivers/common/efile_drv.c
+++ b/erts/emulator/drivers/common/efile_drv.c
@@ -56,6 +56,7 @@
 #define FILE_FDATASYNC          30
 #define FILE_FADVISE            31
 #define FILE_SENDFILE           32
+#define FILE_FALLOCATE          33
 
 /* Return codes */
 
@@ -504,6 +505,10 @@ struct t_data
 	    Uint64 written;
 	} sendfile;
 #endif /* HAVE_SENDFILE */
+	struct {
+	    Sint64 offset;
+	    Sint64 length;
+	} fallocate;
     } c;
     char b[1];
 };
@@ -1963,6 +1968,17 @@ static int flush_sendfile(file_descriptor *desc,void *_) {
 #endif /* HAVE_SENDFILE */
 
 
+static void invoke_fallocate(void *data)
+{
+    struct t_data *d = (struct t_data *) data;
+    int fd = (int) d->fd;
+    Sint64 offset = d->c.fallocate.offset;
+    Sint64 length = d->c.fallocate.length;
+
+    d->again = 0;
+    d->result_ok = efile_fallocate(&d->errInfo, fd, offset, length);
+}
+
 static void free_readdir(void *data)
 {
     struct t_data *d = (struct t_data *) data;
@@ -2358,6 +2374,7 @@ file_async_ready(ErlDrvData e, ErlDrvThreadData data)
       case FILE_RENAME:
       case FILE_WRITE_INFO:
       case FILE_FADVISE:
+      case FILE_FALLOCATE:
 	reply(desc, d->result_ok, &d->errInfo);
 	free_data(data);
 	break;
@@ -2971,6 +2988,20 @@ file_output(ErlDrvData e, char* buf, ErlDrvSizeT count)
         goto done;
     }
 
+    case FILE_FALLOCATE:
+    {
+        d = EF_SAFE_ALLOC(sizeof(struct t_data));
+
+        d->fd = fd;
+        d->command = command;
+        d->invoke = invoke_fallocate;
+        d->free = free_data;
+        d->level = 2;
+        d->c.fallocate.offset = get_int64((uchar*) buf);
+        d->c.fallocate.length = get_int64(((uchar*) buf) + sizeof(Sint64));
+        goto done;
+    }
+
     }
 
     /*
diff --git a/erts/emulator/drivers/common/erl_efile.h b/erts/emulator/drivers/common/erl_efile.h
index 69ad02633c..b29b4f971c 100644
--- a/erts/emulator/drivers/common/erl_efile.h
+++ b/erts/emulator/drivers/common/erl_efile.h
@@ -185,3 +185,4 @@ int efile_fadvise(Efile_error* errInfo, int fd, Sint64 offset, Sint64 length,
 int efile_sendfile(Efile_error* errInfo, int in_fd, int out_fd,
 		      off_t *offset, Uint64 *nbytes, struct t_sendfile_hdtl *hdtl);
 #endif /* HAVE_SENDFILE */
+int efile_fallocate(Efile_error* errInfo, int fd, Sint64 offset, Sint64 length);
diff --git a/erts/emulator/drivers/common/ram_file_drv.c b/erts/emulator/drivers/common/ram_file_drv.c
index a109e40333..7f7cd7cd91 100644
--- a/erts/emulator/drivers/common/ram_file_drv.c
+++ b/erts/emulator/drivers/common/ram_file_drv.c
@@ -48,6 +48,7 @@
 #define RAM_FILE_SIZE          37  /* get file size */
 #define RAM_FILE_ADVISE        38  /* predeclare the access
                                     * pattern for file data */
+#define RAM_FILE_ALLOCATE      39  /* allocate space for a file */
 /* possible new operations include:
    DES_ENCRYPT
    DES_DECRYPT
@@ -720,6 +721,13 @@ static void rfile_command(ErlDrvData e, char* buf, ErlDrvSizeT count)
 	else
 	    reply(f, 1, 0);
 	break;
+
+    case RAM_FILE_ALLOCATE:
+	if (f->flags == 0)
+	    error_reply(f, EBADF);
+	else
+	    reply(f, 1, 0);
+	break;
     }
     /*
      * Ignore anything else -- let the caller hang.
diff --git a/erts/emulator/drivers/unix/unix_efile.c b/erts/emulator/drivers/unix/unix_efile.c
index cf7af71b92..558651fff9 100644
--- a/erts/emulator/drivers/unix/unix_efile.c
+++ b/erts/emulator/drivers/unix/unix_efile.c
@@ -22,6 +22,12 @@
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
+#if defined(HAVE_POSIX_FALLOCATE) && !defined(__sun) && !defined(__sun__)
+#define _XOPEN_SOURCE 600
+#endif
+#if !defined(_GNU_SOURCE) && defined(HAVE_LINUX_FALLOC_H)
+#define _GNU_SOURCE
+#endif
 #include "sys.h"
 #include "erl_driver.h"
 #include "erl_efile.h"
@@ -41,9 +47,13 @@
 #define DARWIN 1
 #endif
 
-#ifdef DARWIN
+#if defined(DARWIN) || defined(HAVE_LINUX_FALLOC_H) || defined(HAVE_POSIX_FALLOCATE)
 #include <fcntl.h>
-#endif /* DARWIN */
+#endif
+
+#ifdef HAVE_LINUX_FALLOC_H
+#include <linux/falloc.h>
+#endif
 
 #ifdef SUNOS4
 #  define getcwd(buf, size) getwd(buf)
@@ -967,3 +977,81 @@ efile_sendfile(Efile_error* errInfo, int in_fd, int out_fd,
     return check_error(retval, errInfo);
 }
 #endif /* HAVE_SENDFILE */
+
+#ifdef HAVE_POSIX_FALLOCATE
+static int
+call_posix_fallocate(int fd, Sint64 offset, Sint64 length)
+{
+    int ret;
+
+    /*
+     * On Linux and Solaris for example, posix_fallocate() returns
+     * a positive error number on error and it does not set errno.
+     * On FreeBSD however (9.0 at least), it returns -1 on error
+     * and it sets errno.
+     */
+    do {
+        ret = posix_fallocate(fd, (off_t) offset, (off_t) length);
+        if (ret > 0) {
+            errno = ret;
+            ret = -1;
+        }
+    } while (ret != 0 && errno == EINTR);
+
+    return ret;
+}
+#endif /* HAVE_POSIX_FALLOCATE */
+
+int
+efile_fallocate(Efile_error* errInfo, int fd, Sint64 offset, Sint64 length)
+{
+#if defined HAVE_FALLOCATE
+    /* Linux specific, more efficient than posix_fallocate. */
+    int ret;
+
+    do {
+        ret = fallocate(fd, FALLOC_FL_KEEP_SIZE, (off_t) offset, (off_t) length);
+    } while (ret != 0 && errno == EINTR);
+
+#if defined HAVE_POSIX_FALLOCATE
+    /* Fallback to posix_fallocate if available. */
+    if (ret != 0) {
+        ret = call_posix_fallocate(fd, offset, length);
+    }
+#endif
+
+    return check_error(ret, errInfo);
+#elif defined F_PREALLOCATE
+    /* Mac OS X specific, equivalent to posix_fallocate. */
+    int ret;
+    fstore_t fs;
+
+    memset(&fs, 0, sizeof(fs));
+    fs.fst_flags = F_ALLOCATECONTIG;
+    fs.fst_posmode = F_VOLPOSMODE;
+    fs.fst_offset = (off_t) offset;
+    fs.fst_length = (off_t) length;
+
+    ret = fcntl(fd, F_PREALLOCATE, &fs);
+
+    if (-1 == ret) {
+        fs.fst_flags = F_ALLOCATEALL;
+        ret = fcntl(fd, F_PREALLOCATE, &fs);
+
+#if defined HAVE_POSIX_FALLOCATE
+        /* Fallback to posix_fallocate if available. */
+        if (-1 == ret) {
+            ret = call_posix_fallocate(fd, offset, length);
+        }
+#endif
+    }
+
+    return check_error(ret, errInfo);
+#elif defined HAVE_POSIX_FALLOCATE
+    /* Other Unixes, use posix_fallocate if available. */
+    return check_error(call_posix_fallocate(fd, offset, length), errInfo);
+#else
+    errno = ENOTSUP;
+    return check_error(-1, errInfo);
+#endif
+}
diff --git a/erts/emulator/drivers/win32/win_efile.c b/erts/emulator/drivers/win32/win_efile.c
index dc7add01f7..f5011d11a5 100644
--- a/erts/emulator/drivers/win32/win_efile.c
+++ b/erts/emulator/drivers/win32/win_efile.c
@@ -1558,3 +1558,13 @@ efile_fadvise(Efile_error* errInfo, int fd, Sint64 offset,
     errno = ERROR_SUCCESS;
     return check_error(0, errInfo);
 }
+
+int
+efile_fallocate(Efile_error* errInfo, int fd, Sint64 offset, Sint64 length)
+{
+    /* No file preallocation method available in Windows. */
+    errno = errno_map(ERROR_NOT_SUPPORTED);
+    SetLastError(ERROR_NOT_SUPPORTED);
+
+    return check_error(-1, errInfo);
+}
diff --git a/erts/preloaded/ebin/prim_file.beam b/erts/preloaded/ebin/prim_file.beam
index ff44d38fa9..b8f71b0c1e 100644
--- a/erts/preloaded/ebin/prim_file.beam
+++ b/erts/preloaded/ebin/prim_file.beam
diff --git a/erts/preloaded/src/prim_file.erl b/erts/preloaded/src/prim_file.erl
index eafab1bae4..c412b7faf2 100644
--- a/erts/preloaded/src/prim_file.erl
+++ b/erts/preloaded/src/prim_file.erl
@@ -27,7 +27,7 @@
 %% Generic file contents operations
 -export([open/2, close/1, datasync/1, sync/1, advise/4, position/2, truncate/1,
 	 write/2, pwrite/2, pwrite/3, read/2, read_line/1, pread/2, pread/3,
-	 copy/3, sendfile/10]).
+	 copy/3, sendfile/10, allocate/3]).
 
 %% Specialized file operations
 -export([open/1, open/3]).
@@ -100,6 +100,7 @@
 -define(FILE_FDATASYNC,        30).
 -define(FILE_ADVISE,           31).
 -define(FILE_SENDFILE,         32).
+-define(FILE_ALLOCATE,         33).
 
 %% Driver responses
 -define(FILE_RESP_OK,          0).
@@ -293,6 +294,11 @@ advise(#file_descriptor{module = ?MODULE, data = {Port, _}},
     end.
 
 %% Returns {error, Reason} | ok.
+allocate(#file_descriptor{module = ?MODULE, data = {Port, _}}, Offset, Length) ->
+    Cmd = <<?FILE_ALLOCATE, Offset:64/signed, Length:64/signed>>,
+    drv_command(Port, Cmd).
+
+%% Returns {error, Reason} | ok.
 write(#file_descriptor{module = ?MODULE, data = {Port, _}}, Bytes) ->
     case drv_command_nt(Port, [?FILE_WRITE,erlang:dt_prepend_vm_tag_data(Bytes)],undefined) of
 	{ok, _Size} ->
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
@@ -170,6 +170,18 @@
       </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>
       <desc>
diff --git a/lib/kernel/src/file.erl b/lib/kernel/src/file.erl
index de3eaad5a1..16f2dde464 100644
--- a/lib/kernel/src/file.erl
+++ b/lib/kernel/src/file.erl
@@ -38,7 +38,7 @@
 %% Specialized
 -export([ipread_s32bu_p32bu/3]).
 %% Generic file contents.
--export([open/2, close/1, advise/4,
+-export([open/2, close/1, advise/4, allocate/3,
 	 read/2, write/2, 
 	 pread/2, pread/3, pwrite/2, pwrite/3,
 	 read_line/1,
@@ -490,6 +490,18 @@ advise(#file_descriptor{module = Module} = Handle, Offset, Length, Advise) ->
 advise(_, _, _, _) ->
     {error, badarg}.
 
+-spec allocate(File, Offset, Length) ->
+	'ok' | {'error', posix()} when
+      File :: io_device(),
+      Offset :: non_neg_integer(),
+      Length :: non_neg_integer().
+
+allocate(File, Offset, Length) when is_pid(File) ->
+    R = file_request(File, {allocate, Offset, Length}),
+    wait_file_reply(File, R);
+allocate(#file_descriptor{module = Module} = Handle, Offset, Length) ->
+    Module:allocate(Handle, Offset, Length).
+
 -spec read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason} when
       IoDevice :: io_device() | atom(),
       Number :: non_neg_integer(),
diff --git a/lib/kernel/src/file_io_server.erl b/lib/kernel/src/file_io_server.erl
index acaffe1e41..fad2ed7fb3 100644
--- a/lib/kernel/src/file_io_server.erl
+++ b/lib/kernel/src/file_io_server.erl
@@ -211,6 +211,10 @@ file_request({advise,Offset,Length,Advise},
     Reply ->
         {reply,Reply,State}
     end;
+file_request({allocate, Offset, Length},
+         #state{handle = Handle} = State) ->
+    Reply = ?PRIM_FILE:allocate(Handle, Offset, Length),
+    {reply, Reply, State};
 file_request({pread,At,Sz}, 
 	     #state{handle=Handle,buf=Buf,read_mode=ReadMode}=State) ->
     case position(Handle, At, Buf) of
diff --git a/lib/kernel/src/ram_file.erl b/lib/kernel/src/ram_file.erl
index 48ea871433..ca881ff8a4 100644
--- a/lib/kernel/src/ram_file.erl
+++ b/lib/kernel/src/ram_file.erl
@@ -29,6 +29,7 @@
 %% Specialized file operations
 -export([get_size/1, get_file/1, set_file/2, get_file_close/1]).
 -export([compress/1, uncompress/1, uuencode/1, uudecode/1, advise/4]).
+-export([allocate/3]).
 
 -export([open_mode/1]).  %% used by ftp-file
 
@@ -72,6 +73,7 @@
 -define(RAM_FILE_UUDECODE,       36).
 -define(RAM_FILE_SIZE,           37).
 -define(RAM_FILE_ADVISE,         38).
+-define(RAM_FILE_ALLOCATE,       39).
 
 %% Open modes for RAM_FILE_OPEN
 -define(RAM_FILE_MODE_READ,       1).
@@ -383,6 +385,11 @@ advise(#file_descriptor{module = ?MODULE, data = Port}, Offset,
 advise(#file_descriptor{}, _Offset, _Length, _Advise) ->
     {error, enotsup}.
 
+allocate(#file_descriptor{module = ?MODULE, data = Port}, Offset, Length) ->
+    call_port(Port, <<?RAM_FILE_ALLOCATE, Offset:64/signed, Length:64/signed>>);
+allocate(#file_descriptor{}, _Offset, _Length) ->
+    {error, enotsup}.
+
 
 
 %%%-----------------------------------------------------------------
diff --git a/lib/kernel/test/file_SUITE.erl b/lib/kernel/test/file_SUITE.erl
index 9c507fd437..914f0d6127 100644
--- a/lib/kernel/test/file_SUITE.erl
+++ b/lib/kernel/test/file_SUITE.erl
@@ -84,6 +84,8 @@
 
 -export([advise/1]).
 
+-export([allocate/1]).
+
 -export([standard_io/1,mini_server/1]).
 
 %% Debug exports
@@ -116,7 +118,7 @@ groups() ->
      {files, [],
       [{group, open}, {group, pos}, {group, file_info},
        {group, consult}, {group, eval}, {group, script},
-       truncate, sync, datasync, advise]},
+       truncate, sync, datasync, advise, allocate]},
      {open, [],
       [open1, old_modes, new_modes, path_open, close, access,
        read_write, pread_write, append, open_errors,
@@ -1617,6 +1619,74 @@ advise(Config) when is_list(Config) ->
     ?line test_server:timetrap_cancel(Dog),
     ok.
 
+allocate(suite) -> [];
+allocate(doc) -> "Tests that ?FILE_MODULE:allocate/3 at least doesn't crash.";
+allocate(Config) when is_list(Config) ->
+    ?line Dog = test_server:timetrap(test_server:seconds(5)),
+    ?line PrivDir = ?config(priv_dir, Config),
+    ?line Allocate = filename:join(PrivDir,
+			       atom_to_list(?MODULE)
+			       ++"_allocate.fil"),
+
+    Line1 = "Hello\n",
+    Line2 = "World!\n",
+
+    ?line {ok, Fd} = ?FILE_MODULE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd, 1, iolist_size([Line1, Line2])),
+    ?line ok = io:format(Fd, "~s", [Line1]),
+    ?line ok = io:format(Fd, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd),
+
+    ?line {ok, Fd2} = ?FILE_MODULE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd2, 1, iolist_size(Line1)),
+    ?line ok = io:format(Fd2, "~s", [Line1]),
+    ?line ok = io:format(Fd2, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd2),
+
+    ?line {ok, Fd3} = ?FILE_MODULE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd3, 1, iolist_size(Line1) + 1),
+    ?line ok = io:format(Fd3, "~s", [Line1]),
+    ?line ok = io:format(Fd3, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd3),
+
+    ?line {ok, Fd4} = ?FILE_MODULE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd4, 1, 4 * iolist_size([Line1, Line2])),
+    ?line ok = io:format(Fd4, "~s", [Line1]),
+    ?line ok = io:format(Fd4, "~s", [Line2]),
+    ?line ok = ?FILE_MODULE:close(Fd4),
+
+    ?line [] = flush(),
+    ?line test_server:timetrap_cancel(Dog),
+    ok.
+
+allocate_and_assert(Fd, Offset, Length) ->
+    % Just verify that calls to ?PRIM_FILE:allocate/3 don't crash or have
+    % any other negative side effect. We can't really asssert against a
+    % specific return value, because support for file space pre-allocation
+    % depends on the OS, OS version and underlying filesystem.
+    %
+    % The Linux kernel added support for fallocate() in version 2.6.23,
+    % which currently works only for the ext4, ocfs2, xfs and btrfs file
+    % systems. posix_fallocate() is available in glibc as of version
+    % 2.1.94, but it was buggy until glibc version 2.7.
+    %
+    % Mac OS X, as of version 10.3, supports the fcntl operation F_PREALLOCATE.
+    %
+    % Solaris supports posix_fallocate() but only for the UFS file system
+    % apparently (not supported for ZFS).
+    %
+    % FreeBSD 9.0 is the first FreeBSD release supporting posix_fallocate().
+    %
+    % For Windows there's apparently no way to pre-allocate file space, at
+    % least with same semantics as posix_fallocate(), fallocate() and
+    % fcntl F_PREALLOCATE.
+    Result = ?FILE_MODULE:allocate(Fd, Offset, Length),
+    case os:type() of
+        {win32, _} ->
+            ?line {error, enotsup} = Result;
+        _ ->
+            ?line _ = Result
+    end.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
diff --git a/lib/kernel/test/prim_file_SUITE.erl b/lib/kernel/test/prim_file_SUITE.erl
index a56746bbc4..4e93a593b3 100644
--- a/lib/kernel/test/prim_file_SUITE.erl
+++ b/lib/kernel/test/prim_file_SUITE.erl
@@ -57,6 +57,8 @@
 %% System probe functions that might be handy to check from the shell
 -export([unix_free/1]).
 
+-export([allocate/1]).
+
 -include_lib("test_server/include/test_server.hrl").
 -include_lib("kernel/include/file.hrl").
 
@@ -87,7 +89,7 @@ groups() ->
        cur_dir_1a, cur_dir_1b]},
      {files, [],
       [{group, open}, {group, pos}, {group, file_info},
-       truncate, sync, datasync, advise, large_write]},
+       truncate, sync, datasync, advise, large_write, allocate]},
      {open, [],
       [open1, modes, close, access, read_write, pread_write,
        append, exclusive]},
@@ -1359,6 +1361,76 @@ check_large_write(Dog, Fd, _, _, []) ->
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+allocate(suite) -> [];
+allocate(doc) -> "Tests that ?PRIM_FILE:allocate/3 at least doesn't crash.";
+allocate(Config) when is_list(Config) ->
+    ?line Dog = test_server:timetrap(test_server:seconds(5)),
+    ?line PrivDir = ?config(priv_dir, Config),
+    ?line Allocate = filename:join(PrivDir,
+			       atom_to_list(?MODULE)
+			       ++"_allocate.fil"),
+
+    Line1 = "Hello\n",
+    Line2 = "World!\n",
+
+    ?line {ok, Fd} = ?PRIM_FILE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd, 1, iolist_size([Line1, Line2])),
+    ?line ok = ?PRIM_FILE:write(Fd, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd),
+
+    ?line {ok, Fd2} = ?PRIM_FILE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd2, 1, iolist_size(Line1)),
+    ?line ok = ?PRIM_FILE:write(Fd2, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd2, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd2),
+
+    ?line {ok, Fd3} = ?PRIM_FILE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd3, 1, iolist_size(Line1) + 1),
+    ?line ok = ?PRIM_FILE:write(Fd3, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd3, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd3),
+
+    ?line {ok, Fd4} = ?PRIM_FILE:open(Allocate, [write, binary]),
+    allocate_and_assert(Fd4, 1, 4 * iolist_size([Line1, Line2])),
+    ?line ok = ?PRIM_FILE:write(Fd4, Line1),
+    ?line ok = ?PRIM_FILE:write(Fd4, Line2),
+    ?line ok = ?PRIM_FILE:close(Fd4),
+
+    ?line test_server:timetrap_cancel(Dog),
+    ok.
+
+allocate_and_assert(Fd, Offset, Length) ->
+    % Just verify that calls to ?PRIM_FILE:allocate/3 don't crash or have
+    % any other negative side effect. We can't really asssert against a
+    % specific return value, because support for file space pre-allocation
+    % depends on the OS, OS version and underlying filesystem.
+    %
+    % The Linux kernel added support for fallocate() in version 2.6.23,
+    % which currently works only for the ext4, ocfs2, xfs and btrfs file
+    % systems. posix_fallocate() is available in glibc as of version
+    % 2.1.94, but it was buggy until glibc version 2.7.
+    %
+    % Mac OS X, as of version 10.3, supports the fcntl operation F_PREALLOCATE.
+    %
+    % Solaris supports posix_fallocate() but only for the UFS file system
+    % apparently (not supported for ZFS).
+    %
+    % FreeBSD 9.0 is the first FreeBSD release supporting posix_fallocate().
+    %
+    % For Windows there's apparently no way to pre-allocate file space, at
+    % least with similar API/semantics as posix_fallocate(), fallocate() or
+    % fcntl F_PREALLOCATE.
+    Result = ?PRIM_FILE:allocate(Fd, Offset, Length),
+    case os:type() of
+        {win32, _} ->
+            ?line {error, enotsup} = Result;
+        _ ->
+            ?line _ = Result
+    end.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 delete_a(suite) -> [];
 delete_a(doc) -> [];
 delete_a(Config) when is_list(Config) ->