lib/libc/sys/sendfile.2

   1 .\" Copyright (c) 1998, David Greenman
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice unmodified, this list of conditions, and the following
   9 .\"    disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libc/sys/sendfile.2,v 1.6.2.6 2001/12/14 18:34:01 ru Exp $
  27 .\" $DragonFly: src/lib/libc/sys/sendfile.2,v 1.3 2004/03/11 12:28:51 hmp Exp $
  28 .\"
  29 .Dd November 5, 1998
  30 .Dt SENDFILE 2
  31 .Os
  32 .Sh NAME
  33 .Nm sendfile
  34 .Nd send a file to a socket
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/socket.h
  40 .In sys/uio.h
  41 .Ft int
  42 .Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
  43 .Sh DESCRIPTION
  44 .Fn Sendfile
  45 sends a regular file specified by descriptor
  46 .Fa fd
  47 out a stream socket specified by descriptor
  48 .Fa s .
  49 .Pp
  50 The
  51 .Fa offset
  52 argument specifies where to begin in the file.
  53 The
  54 .Fa nbytes
  55 argument specifies how many bytes of the file should be sent, with 0 having the special
  56 meaning of send until the end of file has been reached.
  57 .Pp
  58 An optional header and/or trailer can be sent before and after the file data by specifying
  59 a pointer to a struct sf_hdtr, which has the following structure:
  60 .Pp
  61 .Bd -literal -offset indent -compact
  62 struct sf_hdtr {
  63         struct iovec *headers;  /* pointer to header iovecs */
  64         int hdr_cnt;            /* number of header iovecs */
  65         struct iovec *trailers; /* pointer to trailer iovecs */
  66         int trl_cnt;            /* number of trailer iovecs */
  67 };
  68 .Ed
  69 .Pp
  70 The
  71 .Fa headers
  72 and
  73 .Fa trailers
  74 pointers, if non-NULL, point to arrays of struct iovec structures.
  75 See the
  76 .Fn writev
  77 system call for information on the iovec structure.
  78 The number of iovecs in these
  79 arrays is specified by
  80 .Fa hdr_cnt
  81 and
  82 .Fa trl_cnt .
  83 .Pp
  84 If non-NULL, the system will write the total number of bytes sent on the socket to the
  85 variable pointed to by
  86 .Fa sbytes .
  87 .Pp
  88 The
  89 .Fa flags
  90 argument is currently undefined and should be specified as 0.
  91 .Pp
  92 When using a socket marked for non-blocking I/O,
  93 .Fn sendfile
  94 may send fewer bytes than requested.
  95 In this case, the number of bytes successfully
  96 written is returned in
  97 .Fa *sbytes
  98 (if specified),
  99 and the error
 100 .Er EAGAIN
 101 is returned.
 102 .Sh IMPLEMENTATION NOTES
 103 The
 104 .Dx
 105 implementation of
 106 .Fn sendfile
 107 is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
 108 .Sh RETURN VALUES
 109 .Rv -std sendfile
 110 .Sh ERRORS
 111 .Bl -tag -width Er
 112 .It Bq Er EBADF
 113 .Fa fd
 114 is not a valid file descriptor.
 115 .It Bq Er EBADF
 116 .Fa s
 117 is not a valid socket descriptor.
 118 .It Bq Er ENOTSOCK
 119 .Fa s
 120 is not a socket.
 121 .It Bq Er EINVAL
 122 .Fa fd
 123 is not a regular file.
 124 .It Bq Er EINVAL
 125 .Fa s
 126 is not a SOCK_STREAM type socket.
 127 .It Bq Er EINVAL
 128 .Fa offset
 129 is negative or out of range.
 130 .It Bq Er ENOTCONN
 131 .Fa s
 132 points to an unconnected socket.
 133 .It Bq Er EPIPE
 134 The socket peer has closed the connection.
 135 .It Bq Er EIO
 136 An error occurred while reading from
 137 .Fa fd .
 138 .It Bq Er EFAULT
 139 An invalid address was specified for a parameter.
 140 .It Bq Er EAGAIN
 141 The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled.
 142 If specified, the number of bytes successfully sent will be returned in
 143 .Fa *sbytes .
 144 .El
 145 .Sh SEE ALSO
 146 .Xr open 2 ,
 147 .Xr send 2 ,
 148 .Xr socket 2 ,
 149 .Xr writev 2
 150 .Sh HISTORY
 151 .Fn sendfile
 152 first appeared in
 153 .Fx 3.0 .
 154 This manual page first appeared in
 155 .Fx 3.1 .
 156 .Sh AUTHORS
 157 .Fn sendfile
 158 and this manual page were written by
 159 .An David Greenman Aq dg@root.com .