lib/libcr/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 .\"
  28 .Dd November 5, 1998
  29 .Dt SENDFILE 2
  30 .Os
  31 .Sh NAME
  32 .Nm sendfile
  33 .Nd send a file to a socket
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/socket.h
  39 .In sys/uio.h
  40 .Ft int
  41 .Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
  42 .Sh DESCRIPTION
  43 .Fn Sendfile
  44 sends a regular file specified by descriptor
  45 .Fa fd
  46 out a stream socket specified by descriptor
  47 .Fa s .
  48 .Pp
  49 The
  50 .Fa offset
  51 argument specifies where to begin in the file.
  52 The
  53 .Fa nbytes
  54 argument specifies how many bytes of the file should be sent, with 0 having the special
  55 meaning of send until the end of file has been reached.
  56 .Pp
  57 An optional header and/or trailer can be sent before and after the file data by specifying
  58 a pointer to a struct sf_hdtr, which has the following structure:
  59 .Pp
  60 .Bd -literal -offset indent -compact
  61 struct sf_hdtr {
  62         struct iovec *headers;  /* pointer to header iovecs */
  63         int hdr_cnt;            /* number of header iovecs */
  64         struct iovec *trailers; /* pointer to trailer iovecs */
  65         int trl_cnt;            /* number of trailer iovecs */
  66 };
  67 .Ed
  68 .Pp
  69 The
  70 .Fa headers
  71 and
  72 .Fa trailers
  73 pointers, if non-NULL, point to arrays of struct iovec structures.
  74 See the
  75 .Fn writev
  76 system call for information on the iovec structure.
  77 The number of iovecs in these
  78 arrays is specified by
  79 .Fa hdr_cnt
  80 and
  81 .Fa trl_cnt .
  82 .Pp
  83 If non-NULL, the system will write the total number of bytes sent on the socket to the
  84 variable pointed to by
  85 .Fa sbytes .
  86 .Pp
  87 The
  88 .Fa flags
  89 argument is currently undefined and should be specified as 0.
  90 .Pp
  91 When using a socket marked for non-blocking I/O,
  92 .Fn sendfile
  93 may send fewer bytes than requested.
  94 In this case, the number of bytes successfully
  95 written is returned in
  96 .Fa *sbytes
  97 (if specified),
  98 and the error
  99 .Er EAGAIN
 100 is returned.
 101 .Sh IMPLEMENTATION NOTES
 102 The
 103 .Fx
 104 implementation of
 105 .Fn sendfile
 106 is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
 107 .Sh RETURN VALUES
 108 .Rv -std sendfile
 109 .Sh ERRORS
 110 .Bl -tag -width Er
 111 .It Bq Er EBADF
 112 .Fa fd
 113 is not a valid file descriptor.
 114 .It Bq Er EBADF
 115 .Fa s
 116 is not a valid socket descriptor.
 117 .It Bq Er ENOTSOCK
 118 .Fa s
 119 is not a socket.
 120 .It Bq Er EINVAL
 121 .Fa fd
 122 is not a regular file.
 123 .It Bq Er EINVAL
 124 .Fa s
 125 is not a SOCK_STREAM type socket.
 126 .It Bq Er EINVAL
 127 .Fa offset
 128 is negative or out of range.
 129 .It Bq Er ENOTCONN
 130 .Fa s
 131 points to an unconnected socket.
 132 .It Bq Er EPIPE
 133 The socket peer has closed the connection.
 134 .It Bq Er EIO
 135 An error occurred while reading from
 136 .Fa fd .
 137 .It Bq Er EFAULT
 138 An invalid address was specified for a parameter.
 139 .It Bq Er EAGAIN
 140 The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled.
 141 If specified, the number of bytes successfully sent will be returned in
 142 .Fa *sbytes .
 143 .El
 144 .Sh SEE ALSO
 145 .Xr open 2 ,
 146 .Xr send 2 ,
 147 .Xr socket 2 ,
 148 .Xr writev 2
 149 .Sh HISTORY
 150 .Fn sendfile
 151 first appeared in
 152 .Fx 3.0 .
 153 This manual page first appeared in
 154 .Fx 3.1 .
 155 .Sh AUTHORS
 156 .Fn sendfile
 157 and this manual page were written by
 158 .An David Greenman Aq dg@root.com .