aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc
diff options
context:
space:
mode:
authorLukas Larsson <[email protected]>2011-11-27 17:30:06 +0100
committerLukas Larsson <[email protected]>2011-12-02 10:39:38 +0100
commit758fab8895755b22ce02f0a6026d4d286c8a9c5a (patch)
tree74063068b58c3f1f83f5d9436d636167894e7522 /lib/kernel/doc
parent4d198cb07025a8fc341a1e7fd7f9906b5fb714d6 (diff)
downloadotp-758fab8895755b22ce02f0a6026d4d286c8a9c5a.tar.gz
otp-758fab8895755b22ce02f0a6026d4d286c8a9c5a.tar.bz2
otp-758fab8895755b22ce02f0a6026d4d286c8a9c5a.zip
Expand sendfile documentation
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r--lib/kernel/doc/src/file.xml66
1 files changed, 57 insertions, 9 deletions
diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index 78bf0aff45..7fcc354176 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -149,6 +149,9 @@
<datatype>
<name name="mode"/>
</datatype>
+ <datatype>
+ <name name="sendfile_option"/>
+ </datatype>
</datatypes>
<funcs>
@@ -1574,25 +1577,70 @@
</desc>
</func>
<func>
- <name name="sendfile" arity="4"/>
+ <name name="sendfile" arity="2"/>
<fsummary>send a file to a socket</fsummary>
<desc>
- <p>Sends <c>Bytes</c> in from the file
- referenced by <c>IoDevice</c> beginning at <c>Offset</c> to
- <c>Socket</c>.
+ <p>Sends the file <c>Filename</c> to <c>Socket</c>.
Returns <c>{ok, BytesSent}</c> if successful,
otherwise <c>{error, Reason}</c>.</p>
- <p>Available on Linux, FreeBSD, DragonflyBSD, Solaris, Darwin and Windows</p>
</desc>
</func>
<func>
- <name name="sendfile" arity="2"/>
+ <name name="sendfile" arity="5"/>
<fsummary>send a file to a socket</fsummary>
<desc>
- <p>Sends the file <c>Filename</c> to <c>Socket</c>.
+ <p>Sends <c>Bytes</c> from the file
+ referenced by <c>RawFile</c> beginning at <c>Offset</c> to
+ <c>Socket</c>.
Returns <c>{ok, BytesSent}</c> if successful,
- otherwise <c>{error, Reason}</c>.</p>
- <p>Available on Linux, FreeBSD, DragonflyBSD, Solaris, Darwin and Windows</p>
+ otherwise <c>{error, Reason}</c>. If <c>Bytes</c> is set to
+ 0 all data after the given <c>Offset</c> is sent.</p>
+ <p>The file used must be opened using the raw flag, and the process
+ calling sendfile must be the controlling process of the socket.
+ See <seealso marker="gen_tcp#controlling_process-2">gen_tcp:controlling_process/2</seealso></p>
+ <p>If the OS used does not support sendfile, an Erlang fallback
+ using file:read and gen_tcp:send is used.</p>
+ <p>The option list can contain the following options:
+ <taglist>
+ <tag><c>headers</c></tag>
+ <item>A list containing data which is to be sent before
+ the file is sent. If <c>headers</c> is used, <c>Bytes</c> specifies
+ the total bytes in the header and/or file to be sent. If
+ <c>Bytes</c> is set to 0, the all headers, the file and
+ possible trailers will be sent. </item>
+ <tag><c>trailers</c></tag>
+ <item>A list containing data which is to be after before
+ the file is sent. All the <c>trailers</c> will be sent after the
+ file is sent, no matter what <c>Bytes</c> is set to. </item>
+ <tag><c>chunk_size</c></tag>
+ <item>The chunk size used by the erlang fallback to send
+ data. If using the fallback, this should be set to a value
+ which comfortably fits in the systems memory. Default is 20 MB.</item>
+ <tag><c>sf_nodiskio</c></tag>
+ <item>This flag causes any sendfile() call which would
+ block on disk I/O to instead return EBUSY. Busy servers may bene-
+ fit by transferring requests that would block to a separate I/O
+ worker thread.</item>
+ <tag><c>sf_mnowait</c></tag>
+ <item>Do not wait for some kernel resource to become avail-
+ able, in particular, mbuf and sf_buf. The flag does not make the
+ sendfile() syscall truly non-blocking, since other resources are
+ still allocated in a blocking fashion.</item>
+ <tag><c>sf_sync</c></tag>
+ <item>sendfile sleeps until the network stack no longer refer-
+ ences the VM pages of the file, making subsequent modifications to
+ it safe. Please note that this is not a guarantee that the data
+ has actually been sent.</item>
+ </taglist>
+ </p>
+ <p>On operating systems with thread support, it is recommended to use
+ async threads. See the command line flag
+ <c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>. If it is not
+ possible to use async threads for sendfile, it is recommended to use
+ a relatively small value for the send buffer on the socket. Otherwise
+ the Erlang VM might loose some of its soft realtime guarantees.
+ Which size to use depends on the OS/hardware and the requirements
+ of the application.</p>
</desc>
</func>
<func>