.\" Copyright (c) 2001-2002 Packet Design, LLC.
.\" All rights reserved.
.\" 
.\" Subject to the following obligations and disclaimer of warranty,
.\" use and redistribution of this software, in source or object code
.\" forms, with or without modifications are expressly permitted by
.\" Packet Design; provided, however, that:
.\" 
.\"    (i)  Any and all reproductions of the source or object code
.\"         must include the copyright notice above and the following
.\"         disclaimer of warranties; and
.\"    (ii) No rights are granted, in any manner or form, to use
.\"         Packet Design trademarks, including the mark "PACKET DESIGN"
.\"         on advertising, endorsements, or otherwise except as such
.\"         appears in the above copyright notice or in the software.
.\" 
.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
.\" OR NON-INFRINGEMENT.  PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
.\" RELIABILITY OR OTHERWISE.  IN NO EVENT SHALL PACKET DESIGN BE
.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
.\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
.\" THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Author: Archie Cobbs <archie@freebsd.org>
.\"
.\" $Id: http_servlet_file.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $
.\"
.Dd April 22, 2002
.Dt HTTP_SERVLET_FILE 3
.Os
.Sh NAME
.Nm http_servlet_file
.Nd HTTP file servlet
.Sh LIBRARY
PDEL Library (libpdel, \-lpdel)
.Sh SYNOPSIS
.In sys/types.h
.In stdio.h
.In netinet/in.h
.In openssl/ssl.h
.In pdel/tmpl/tmpl.h
.In pdel/http/http_defs.h
.In pdel/http/http_server.h
.In pdel/http/servlet/tmpl.h
.In pdel/http/servlet/file.h
.Ft "struct http_servlet *"
.Fn http_servlet_file_create "const struct http_servlet_file_info *info"
.Ft void
.Fn http_servlet_file_serve "const char *path" "http_logger_t *logger" "struct http_request *req" "struct http_response *resp"
.Sh DESCRIPTION
.Fn http_servlet_file_create
creates a new servlet that serves HTTP requests from a file
or a tree of files in a directory hierarchy, with support for serving
.Xr tmpl 3
template files.
.Pp
.Fa info
is a pointer to a
.Li "struct http_servlet_file_info" :
.Pp
.Bd -literal -compact -offset 3n
typedef int http_servlet_file_hide_t(
              const struct http_servlet_file_info *info,
              struct http_request *req, struct http_response *resp,
              const char *path);

struct http_servlet_file_info {
    const char    *docroot;       /* document root, or NULL for cwd */
    u_char        allow_escape;   /* allow url to escape docroot */
    const char    *filename;      /* filename, or NULL to use url */
    const char    *prefix;        /* url prefix to strip, or NULL */
    const char    *mime_type;     /* mime type, or NULL to guess */
    const char    *mime_encoding; /* mime encoding (or NULL) */
    http_logger_t *logger;        /* http error logger */

    http_servlet_file_hide_t       *hide;     /* optional file hider */
    struct http_servlet_tmpl_tinfo tinfo;     /* for *.tmpl files */
};
.Ed
.Pp
When a request is received, the above
.Fa info
is used together with the requested URL to identify a file in the
filesystem from which to generate the response.
.Pp
.Fa docroot
specifies the root directory starting from which relative pathnames
are resolved.
If
.Fa docroot
is
.Dv NULL ,
then the current working directory is assumed.
.Pp
.Fa allow_escape
is a boolean value that determines whether the file ultimately served
may lie outside of the directory hierarchy rooted at
.Fa docroot
(or the current directory if
.Fa docroot
is equal to
.Dv NULL) .
This can happen when symbolic links are encountered.
.Pp
If not
.Dv NULL ,
.Fa filename
is the pathname of a specific file from which to serve all requests.
It may be a relative or absolute pathname; in the relative case,
it is relative to
.Fa docroot .
.Pp
Otherwise, if
.Fa filename
is
.Dv NULL ,
a pathname is generated dynamically as follows.
First, if
.Fa prefix
is not
.Dv NULL
and it exactly matches the first part of the requested URL path, then that
prefix is removed from the URL path.
Note that the first character of
.Fa prefix
must be '/' for it to match.
Then a pathname is generated by by treating the requested URL path
as a relative pathname relative to
.Fa docroot .
.Pp
In all cases, the strings
.Dq \&. ,
.Dq \&.\&. ,
and the empty string are disallowed as pathname components in the
requested URL path and will generate a
.Dq "404 Not Found"
response.
.Pp
.Fa mime_type
may be used to specify the MIME type for the served file, and
.Fa mime_encoding
the content encoding.
Either or both may be
.Dv NULL
to let the file servlet try to guess the MIME information.
.Pp
The
.Fa logger
is a logging function whose type is defined in
.Xr http_server 3 .
.Pp
The
.Fa hide
function pointer, if not
.Dv NULL ,
allows selectively hiding certain files in the directory tree.
.Fn hide
should return non-zero to hide the file with pathname
.Fa path ,
which will always be an absolute pathname in normalized form (see
.Xr realpath 3) .
.Fa info
points to a read-only copy of the information passed to
.Fn http_servlet_file_create .
.\"
.Ss "Template support"
.\"
This servlet is capable of serving
.Xr tmpl
template files by automatically creating
.Xr http_servlet_tmpl 3
servlets on a demand basis.
To enable this feature, the
.Fa tinfo
structure should be filled in with a non-
.Dv NULL
.Fa handler
field.
Then if for any requested file pathname "/foo/bar" there is a file named
"/foo/bar.tmpl", then this file will be treated as a
.Xr tmpl 3
template and passed to the
.Xr http_servlet_tmpl 3
servlet.
.Pp
See
.Xr http_servlet_tmpl 3
for a description of the
.Fa tinfo
structure.
Although the same
.Fa tinfo
structure is used to create multiple template servlets, the
.Fn tinfo.freer
destructor function will only be invoked once, when the enclosing
.Nm http_servlet_file
servlet is destroyed.
.Pp
The
.Fn hide
function (if specified) does not block template execution; however,
it may still be used to block access to the actual template files
themselves.
.\"
.Ss "Directory support"
.\"
If the file being served is a directory, the file servlet will
respond with a corresponding HTTP redirect if any of the following
files exist in that directory:
.Li index.tmpl ,
.Li index.html ,
or
.Li index.htm.
.Pp
.Fn http_servlet_file_serve
is a general function sometimes useful when implementing other servlets.
It simply serves the file at pathname
.Fa path
using the MIME guessing and directory redirection algorithms.
.Sh RETURN VALUES
On failure,
.Fn http_servlet_file_create
returns
.Dv NULL
and sets
.Va errno
to an appropriate value.
.Sh SEE ALSO
.Xr http_request 3 ,
.Xr http_response 3 ,
.Xr http_server 3 ,
.Xr http_servlet 3 ,
.Xr http_servlet_tmpl 3 ,
.Xr libpdel 3 ,
.Xr realpath 3
.Sh HISTORY
The PDEL library was developed at Packet Design, LLC.
.Dv "http://www.packetdesign.com/"
.Sh AUTHORS
.An Archie Cobbs Aq archie@freebsd.org