Annotation of embedaddon/libpdel/http/servlet/http_servlet_file.3, revision 1.1.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