Annotation of embedaddon/libpdel/http/servlet/http_servlet_file.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: http_servlet_file.3,v 1.11 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_SERVLET_FILE 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_servlet_file
! 45: .Nd HTTP file servlet
! 46: .Sh LIBRARY
! 47: PDEL Library (libpdel, \-lpdel)
! 48: .Sh SYNOPSIS
! 49: .In sys/types.h
! 50: .In stdio.h
! 51: .In netinet/in.h
! 52: .In openssl/ssl.h
! 53: .In pdel/tmpl/tmpl.h
! 54: .In pdel/http/http_defs.h
! 55: .In pdel/http/http_server.h
! 56: .In pdel/http/servlet/tmpl.h
! 57: .In pdel/http/servlet/file.h
! 58: .Ft "struct http_servlet *"
! 59: .Fn http_servlet_file_create "const struct http_servlet_file_info *info"
! 60: .Ft void
! 61: .Fn http_servlet_file_serve "const char *path" "http_logger_t *logger" "struct http_request *req" "struct http_response *resp"
! 62: .Sh DESCRIPTION
! 63: .Fn http_servlet_file_create
! 64: creates a new servlet that serves HTTP requests from a file
! 65: or a tree of files in a directory hierarchy, with support for serving
! 66: .Xr tmpl 3
! 67: template files.
! 68: .Pp
! 69: .Fa info
! 70: is a pointer to a
! 71: .Li "struct http_servlet_file_info" :
! 72: .Pp
! 73: .Bd -literal -compact -offset 3n
! 74: typedef int http_servlet_file_hide_t(
! 75: const struct http_servlet_file_info *info,
! 76: struct http_request *req, struct http_response *resp,
! 77: const char *path);
! 78:
! 79: struct http_servlet_file_info {
! 80: const char *docroot; /* document root, or NULL for cwd */
! 81: u_char allow_escape; /* allow url to escape docroot */
! 82: const char *filename; /* filename, or NULL to use url */
! 83: const char *prefix; /* url prefix to strip, or NULL */
! 84: const char *mime_type; /* mime type, or NULL to guess */
! 85: const char *mime_encoding; /* mime encoding (or NULL) */
! 86: http_logger_t *logger; /* http error logger */
! 87:
! 88: http_servlet_file_hide_t *hide; /* optional file hider */
! 89: struct http_servlet_tmpl_tinfo tinfo; /* for *.tmpl files */
! 90: };
! 91: .Ed
! 92: .Pp
! 93: When a request is received, the above
! 94: .Fa info
! 95: is used together with the requested URL to identify a file in the
! 96: filesystem from which to generate the response.
! 97: .Pp
! 98: .Fa docroot
! 99: specifies the root directory starting from which relative pathnames
! 100: are resolved.
! 101: If
! 102: .Fa docroot
! 103: is
! 104: .Dv NULL ,
! 105: then the current working directory is assumed.
! 106: .Pp
! 107: .Fa allow_escape
! 108: is a boolean value that determines whether the file ultimately served
! 109: may lie outside of the directory hierarchy rooted at
! 110: .Fa docroot
! 111: (or the current directory if
! 112: .Fa docroot
! 113: is equal to
! 114: .Dv NULL) .
! 115: This can happen when symbolic links are encountered.
! 116: .Pp
! 117: If not
! 118: .Dv NULL ,
! 119: .Fa filename
! 120: is the pathname of a specific file from which to serve all requests.
! 121: It may be a relative or absolute pathname; in the relative case,
! 122: it is relative to
! 123: .Fa docroot .
! 124: .Pp
! 125: Otherwise, if
! 126: .Fa filename
! 127: is
! 128: .Dv NULL ,
! 129: a pathname is generated dynamically as follows.
! 130: First, if
! 131: .Fa prefix
! 132: is not
! 133: .Dv NULL
! 134: and it exactly matches the first part of the requested URL path, then that
! 135: prefix is removed from the URL path.
! 136: Note that the first character of
! 137: .Fa prefix
! 138: must be '/' for it to match.
! 139: Then a pathname is generated by by treating the requested URL path
! 140: as a relative pathname relative to
! 141: .Fa docroot .
! 142: .Pp
! 143: In all cases, the strings
! 144: .Dq \&. ,
! 145: .Dq \&.\&. ,
! 146: and the empty string are disallowed as pathname components in the
! 147: requested URL path and will generate a
! 148: .Dq "404 Not Found"
! 149: response.
! 150: .Pp
! 151: .Fa mime_type
! 152: may be used to specify the MIME type for the served file, and
! 153: .Fa mime_encoding
! 154: the content encoding.
! 155: Either or both may be
! 156: .Dv NULL
! 157: to let the file servlet try to guess the MIME information.
! 158: .Pp
! 159: The
! 160: .Fa logger
! 161: is a logging function whose type is defined in
! 162: .Xr http_server 3 .
! 163: .Pp
! 164: The
! 165: .Fa hide
! 166: function pointer, if not
! 167: .Dv NULL ,
! 168: allows selectively hiding certain files in the directory tree.
! 169: .Fn hide
! 170: should return non-zero to hide the file with pathname
! 171: .Fa path ,
! 172: which will always be an absolute pathname in normalized form (see
! 173: .Xr realpath 3) .
! 174: .Fa info
! 175: points to a read-only copy of the information passed to
! 176: .Fn http_servlet_file_create .
! 177: .\"
! 178: .Ss "Template support"
! 179: .\"
! 180: This servlet is capable of serving
! 181: .Xr tmpl
! 182: template files by automatically creating
! 183: .Xr http_servlet_tmpl 3
! 184: servlets on a demand basis.
! 185: To enable this feature, the
! 186: .Fa tinfo
! 187: structure should be filled in with a non-
! 188: .Dv NULL
! 189: .Fa handler
! 190: field.
! 191: Then if for any requested file pathname "/foo/bar" there is a file named
! 192: "/foo/bar.tmpl", then this file will be treated as a
! 193: .Xr tmpl 3
! 194: template and passed to the
! 195: .Xr http_servlet_tmpl 3
! 196: servlet.
! 197: .Pp
! 198: See
! 199: .Xr http_servlet_tmpl 3
! 200: for a description of the
! 201: .Fa tinfo
! 202: structure.
! 203: Although the same
! 204: .Fa tinfo
! 205: structure is used to create multiple template servlets, the
! 206: .Fn tinfo.freer
! 207: destructor function will only be invoked once, when the enclosing
! 208: .Nm http_servlet_file
! 209: servlet is destroyed.
! 210: .Pp
! 211: The
! 212: .Fn hide
! 213: function (if specified) does not block template execution; however,
! 214: it may still be used to block access to the actual template files
! 215: themselves.
! 216: .\"
! 217: .Ss "Directory support"
! 218: .\"
! 219: If the file being served is a directory, the file servlet will
! 220: respond with a corresponding HTTP redirect if any of the following
! 221: files exist in that directory:
! 222: .Li index.tmpl ,
! 223: .Li index.html ,
! 224: or
! 225: .Li index.htm.
! 226: .Pp
! 227: .Fn http_servlet_file_serve
! 228: is a general function sometimes useful when implementing other servlets.
! 229: It simply serves the file at pathname
! 230: .Fa path
! 231: using the MIME guessing and directory redirection algorithms.
! 232: .Sh RETURN VALUES
! 233: On failure,
! 234: .Fn http_servlet_file_create
! 235: returns
! 236: .Dv NULL
! 237: and sets
! 238: .Va errno
! 239: to an appropriate value.
! 240: .Sh SEE ALSO
! 241: .Xr http_request 3 ,
! 242: .Xr http_response 3 ,
! 243: .Xr http_server 3 ,
! 244: .Xr http_servlet 3 ,
! 245: .Xr http_servlet_tmpl 3 ,
! 246: .Xr libpdel 3 ,
! 247: .Xr realpath 3
! 248: .Sh HISTORY
! 249: The PDEL library was developed at Packet Design, LLC.
! 250: .Dv "http://www.packetdesign.com/"
! 251: .Sh AUTHORS
! 252: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet_file.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http / servlet