Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 844 lines (644 sloc) 24.25 kB
108bbc9 @klacke ""
authored
1 .TH YAWS_API "5" "" "" "User API"
abc3a43 @klacke documented yaws_api
authored
2 .SH NAME
3 yaws_api \- api available to yaws web server programmers
4 .SH SYNOPSIS
5 .B yaws_api:Function(...)
6
7 .SH DESCRIPTION
e2f272a @klacke explicit support for content_length
authored
8
abc3a43 @klacke documented yaws_api
authored
9 .PP
e263363 @klacke speling
authored
10 This is the api available to yaws web server programmers. The Erlang
abc3a43 @klacke documented yaws_api
authored
11 module yaws_api contains a wide variety of functions that can
12 be used inside yaws pages.
13
14 .PP
15 Each chunk of yaws code is executed while the yaws page is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
16 being delivered from the server. We give a very simple example here
e263363 @klacke speling
authored
17 to show the basic idea. Imagine the following HTML code:
abc3a43 @klacke documented yaws_api
authored
18
19 \fI
20 .nf
21 <html>
22 <body>
23
24 <h1> Header 1</h1>
25
26 <erl>
27 out(Arg) ->
28 {html, "<p> Insert this text into the document"}.
29 </erl>
30
31 </body>
32 </html>
33
34 .fi
35 \fR
36
37
38 .PP
39 The \fBout(Arg)\fR function is supplied one argument, an #arg{} structure.
40 We have the following relevant record definitions:
41
42 \fI
43 .nf
44
45 -record(arg, {
0be3c7e @klacke untabified all of yaws
authored
46 clisock, %% the socket leading to the peer client
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
47 client_ip_port, %% {ClientIp, ClientPort} tuple
0be3c7e @klacke untabified all of yaws
authored
48 headers, %% headers
49 req, %% request
50 clidata, %% The client data (as a binary in POST requests)
51 server_path, %% The normalized server path
52 querydata, %% Was the URL on the form of ...?query (GET reqs)
53 appmoddata, %% the remainder of the path up to the query
54 docroot, %% where's the data
55 fullpath, %% full path to yaws file
56 cont, %% Continuation for chunked multipart uploads
57 state, %% State for use by users of the out/1 callback
58 pid, %% pid of the yaws worker process
59 opaque, %% useful to pass static data
60 appmod_prepath, %% path in front of: <appmod><appmoddata>
61 pathinfo %% Set to 'd/e' when calling c.yaws for the request
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
62 %% http://some.host/a/b/c.yaws/d/e
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
63 }).
abc3a43 @klacke documented yaws_api
authored
64 .fi
65 \fR
66
67 The headers argument is also a record:
68 \fI
69 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
70
abc3a43 @klacke documented yaws_api
authored
71 -record(headers, {
8d5aa60 @klacke ""
authored
72 connection,
73 accept,
74 host,
75 if_modified_since,
76 if_match,
77 if_none_match,
78 if_range,
79 if_unmodified_since,
80 range,
81 referer,
82 user_agent,
83 accept_ranges,
84 cookie = [],
85 keep_alive,
86 content_length,
87 authorization,
88 other = [] %% misc other headers
89 }).
abc3a43 @klacke documented yaws_api
authored
90
91 .fi
92 \fR
93
94 .PP The \fBout/1\fR function can use the Arg to generate any content
95 it likes. We have the following functions to aid that generation.
96
97
98 .SH API
99
100 .TP
101 \fBssi(DocRoot, ListOfFiles)\fR
102 Server side include. Just include the files as is in the document. The files
103 will \fBnot\fR be parsed and searched for <erl> tags.
104
105
106 .TP
107 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
108 Server side include of pre indented code. The data in Files
109 will be included but contained in a <pre> tag. The data will be
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
110 htmlized.
abc3a43 @klacke documented yaws_api
authored
111
112 .TP
113 \fBpre_ssi_string(String)\fR
114 Include htmlized content from String.
115
116
117 .TP
118 \fBf(Fmt, Args)\fR
119 The equivalent of io_lib:format/2. This function is automatically
120 -included in all erlang code which is a part of a yaws page.
121
122 .TP
c5ebd38 @klacke added pam support + prepare for 1.58
authored
123 \fBhtmlize(Binary | List | Char)\fR
124 Htmlize an IO list object.
abc3a43 @klacke documented yaws_api
authored
125
126 .TP
127 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
128 Sets a cookie to the browser.
129
130 .TP
131 \fBfind_cookie_val(Cookie, Header)\fR
132 This function can be used to search for a cookie that was previously
133 set by \fBsetcookie/2-6\fR. For example if we set a cookie
134 as \fByaws_api:setcookie("sid",SomeRandomSid) \fR, then on subsequent requests
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
135 from the browser we can call:
abc3a43 @klacke documented yaws_api
authored
136 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
137
138 The function returns [] if no cookie was found, otherwise the actual cookie
139 is returned as a string.
140
141
142 .TP
143 \fBredirect(Url\fR
144 This function generates a redirect to the browser.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
145 It will clear any previously set headers. So to generate
146 a redirect \fBand\fR set a cookie, we need to set the cookie after
abc3a43 @klacke documented yaws_api
authored
147 the redirect as in:
148 \fI
149 .nf
150 out(Arg) ->
151 ... do some stuff
152
153 Ret = [{redirect, "http://www.somewhere.com"},
154 setcookie("sid", Random)
155 ].
156
157 .fi
158 \fR
159
160
161 .TP
883fa5a @klacke added redirect_self to yaws_api
authored
162 \fBredirect_self(Arg)\fR
163 If we want to issue a redirect to ourselves, this function
164 is useful. It returns a record \fI#redir_self{}\fR defined in
165 \fIyaws_api.hrl\fR. The record contains fields to construct
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
166 a URL to ourselves.
883fa5a @klacke added redirect_self to yaws_api
authored
167 \fI
168 .nf
169
170 -record(redir_self, {
171 host, %% string() - our own host
172 scheme, %% http | https
173 scheme_str, %% "https://" | "http://"
174 port, %% integer() - our own port
175 port_str %% "" | ":<int>" - the optional port part
176 %% to append to the url
177 }).
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored
178 .fi
883fa5a @klacke added redirect_self to yaws_api
authored
179
180
181 .TP
abc3a43 @klacke documented yaws_api
authored
182 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored
183 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored
184 from a stream of data. It returns:
185
186 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
187
188 The function handles multilines as defined in e.g. SMTP or HTTP
189
190 .TP
191 \fBmime_type(FileName)\fR
192 Returns the mime type as defined by the extension of FileName
193
194 .TP
195 \fBstream_chunk_deliver(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
196 When a yaws function needs to deliver chunks of data which it gets
abc3a43 @klacke documented yaws_api
authored
197 from a process. The other process can call this function to deliver
198 these chunks. It requires the \fBout/1\fR function to return the
199 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
404aec1 @sgolovan fix syntax and spelling errors in man pages
sgolovan authored
200 YawsPid is the process identifier of the yaws process delivering the
201 original .yaws file. That is self() in the yaws code.
ebb94d8 @klacke 1.54
authored
202 The Pid must typically be passed (somehow) to the producer of the stream.
abc3a43 @klacke documented yaws_api
authored
203
a39fab8 @klacke added example docs on how to stream data
authored
204 .TP
205 \fBstream_chunk_deliver_blocking(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
206 A synchronous version of the above function. This synchronous version
207 must always be used when the producer of the stream is faster than the
208 consumer. This is usually the case since the client is the WWW browser.
abc3a43 @klacke documented yaws_api
authored
209
210 .TP
211 \fBstream_chunk_end(YawsPid)\fR
212 When the process discussed above is done delivering data, it must call
213 this function to let the yaws content delivering process finish up
214 the HTTP transaction.
215
216 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
217 \fBstream_process_deliver(Socket, IoList)\fR
218 Yaws allows application processes to deliver data directly to the
219 client. The application tells yaws about such a process by returning
220 \fB{streamcontent_from_pid, MimeType, Pid}\fR from its \fBout/1\fR
221 function. In this case, \fIPid\fR uses the
222 \fBstream_process_deliver/2\fR function to deliver data to the
223 client. The application gets \fISocket\fR from \fIArg#arg.clisock\fR,
224 and \fIIoList\fR is the data to be sent to the client.
225
226 .TP
227 \fBstream_process_deliver_chunk(Socket, IoList)\fR
228 Same as above but delivers \fIIoList\fR using HTTP chunked transfer
229 format. \fIIoList\fR must have a size greater than zero. The
230 application process delivering the data will have had to have make
231 sure that the HTTP headers of the response indicate chunked transfer
232 mode, either by ensuring no Content-Length header is set or by
233 specifically setting the Transfer-Encoding header to chunked.
234
235 .TP
236 \fBstream_process_deliver_final_chunk(Socket, IoList)\fR
237 If the application process delivering data to the client uses chunked
238 transfer mode, it must call this to deliver the final chunk of the
239 transfer. This tells yaws to create a special final chunk in the
240 format required by the HTTP specification (RFC 2616). \fIIoList\fR may
241 be empty, but if its size is greater than zero, that data will be
242 sent as a separate chunk before the final chunk.
243
244 .TP
245 \fBstream_process_end(Socket, YawsPid)\fR
246 Application processes delivering data directly to clients must call
247 this function to inform yaws that they've finished using
248 \fISocket\fR. The \fIYawsPid\fR argument will have been passed to the
249 process earlier when yaws sent it a message telling it to proceed with
5da72a3 @vinoski Allow "stream processes" to close the client socket
vinoski authored
250 data delivery. Yaws expects \fISocket\fR to be open.
251
252 .TP
253 \fBstream_process_end(closed, YawsPid)\fR
254 Same as the previous function but the application calls this if it
255 closes the client socket as part of its data delivery process. This
256 allows yaws to continue without assuming the socket is still open and
257 encountering errors due to that assumption. The \fIYawsPid\fR argument
258 will have been passed to the application process earlier when yaws
259 sent it a message telling it to proceed with data delivery.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
260
261 .TP
abc3a43 @klacke documented yaws_api
authored
262 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
263 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored
264 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
265 part of the URL.
266
267 .TP
268 \fBqueryvar(Arg, VarName)\fR
269 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
270 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
271 querypart of the url. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored
272 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
273 return \fI{Val1, ....}\fR.
abc3a43 @klacke documented yaws_api
authored
274
275
276 .TP
c4523b3 @klacke ""
authored
277 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
278 This function will parse the POST data as supplied from the browser.
279 It will return a {Key, Value} list of the items set by the browser.
280
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
281 .TP
282 \fBpostvar(Arg, VarName)\fR
283 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
284 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
285 POSTed data from the client. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored
286 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
287 return \fI{Val1, ....}\fR.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
288
c9778e0 @klacke added support for 2 additional configure
authored
289 .TP
290 \fBgetvar(Arg, VarName)\fR
291 This function looks at the HTTP request method from the
292 client and invokes postvar/2 if it is a POST from the client
293 and queryvar/2 if it is a GET request from the client.
294
c4523b3 @klacke ""
authored
295
296 .TP
297 \fBparse_multipart_post(Arg)\fR
298
abc3a43 @klacke documented yaws_api
authored
299 If the browser has set the Content-Type header to the value
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
300 "multipart/form-data", which is the case when the browser
abc3a43 @klacke documented yaws_api
authored
301 wants to upload a file to the server the following happens:
302
303
304 If the function returns \fB{result, Res}\fR no more data
305 will come from the browser.
306
307 If the function returns \fB{cont, Cont, Res}\fR the browser
308 will supply more data. (The file was to big to come in one read)
309
310 This indicates that there is more data to come and the out/1 function
311 should return {get_more, Cont, User_state} where User_state might
312 usefully be a File Descriptor.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
313 The Res value is a list of either:
af3e2ca @capflam Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
capflam authored
314 \fB{head, {Name, Headers}}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
315
316 The function returns \fB{error, Reason}\fR when an error occurred during the
317 parsing.
abc3a43 @klacke documented yaws_api
authored
318
319
320 Example usage could be:
321 \fI
322 .nf
323 <erl>
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
324
abc3a43 @klacke documented yaws_api
authored
325 out(A) ->
c4523b3 @klacke ""
authored
326 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
327 {cont, Cont, Res} ->
328 St = handle_res(A, Res),
329 {get_more, Cont, St};
330 {result, Res} ->
331 handle_res(A, Res),
af3e2ca @capflam Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
capflam authored
332 {html, f("<pre>Done </pre>",[])};
333 {error, Reason} ->
334 {html, f("An error occured: ~p", [Reason])}
abc3a43 @klacke documented yaws_api
authored
335 end.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
336
af3e2ca @capflam Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
capflam authored
337 handle_res(A, [{head, {Name, _Hdrs}}|T]) ->
abc3a43 @klacke documented yaws_api
authored
338 io:format("head:~p~n",[Name]),
339 handle_res(A, T);
340 handle_res(A, [{part_body, Data}|T]) ->
341 io:format("part_body:~p~n",[Data]),
342 handle_res(A, T);
343 handle_res(A, [{body, Data}|T]) ->
344 io:format("body:~p~n",[Data]),
345 handle_res(A, T);
346 handle_res(A, []) ->
347 io:format("End_res~n").
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
348
abc3a43 @klacke documented yaws_api
authored
349 </erl>
350 .fi
351 \fR
352
353
354
355 .TP
87b1456 @klacke wrote the shopppingcart example
authored
356 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
357 Create a new cookie based session, the yaws system will set the
e263363 @klacke speling
authored
358 cookie. The new random generated cookie is returned from this
87b1456 @klacke wrote the shopppingcart example
authored
359 function. The Opaque argument will typically contain user data
e263363 @klacke speling
authored
360 such as user name and password
abc3a43 @klacke documented yaws_api
authored
361
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
362 .TP
363 \fBnew_cookie_session(Opaque, TTL)\fR
364 As above, but allows to set a session specific time-out value,
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored
365 overriding the system specified time-out value.
366
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
367 .TP
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored
368 \fBnew_cookie_session(Opaque, TTL, CleanupPid)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
369 As above, but also sends a message
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored
370 \fI{yaws_session_end, Reason, Cookie, Opaque}\fR to the provided CleanuPid where
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
371 Reason can be either of \fItimeout\fR or \fInormal\fR. The \fICookie\fR
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored
372 is the HTTP cookie as returned by \fInew_session()\fR and the Opaque
373 is the user provided Opaque parameter to \fInew_session()\fR.
374 The purpose of the feature is to cleanup resources assigned to the session.
375
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
376
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
377 .TP
87b1456 @klacke wrote the shopppingcart example
authored
378 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
379
380 .TP
381 \fBprint_cookie_sessions() \fR
382
87b1456 @klacke wrote the shopppingcart example
authored
383
384 .TP
385 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
386
abc3a43 @klacke documented yaws_api
authored
387 .TP
87b1456 @klacke wrote the shopppingcart example
authored
388 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
389
390
50a7ab2 @klacke added support/docs for embedded mode
authored
391 .TP
392 \fBsetconf(Gconf, Groups)\fR
393 This function is intended for embedded mode in yaws. It makes it possible
394 to load a yaws configuration from another data source than /etc/yaws.conf, such
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
395 as a database.
50a7ab2 @klacke added support/docs for embedded mode
authored
396 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
397 start with an empty default configuration, and wait for some other
398 program to execute a \fIsetconf/2\fR
399 The Gconf is a \fI#gconf{}\fR record and the Group variable is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
400 a list of lists of \fI#sconf{}\fR records. Each sublist must
50a7ab2 @klacke added support/docs for embedded mode
authored
401 contain \fI#sconf{}\fR records with the same IP/Port listen address.
e263363 @klacke speling
authored
402 To create a suitable initial #gconf{} record see the code in
403 yaws_config:make_default_gconf/2. Especially the \fIyaws_dir\fR parameter
404 is important to get right.
abc3a43 @klacke documented yaws_api
authored
405
2b9f008 @klacke ""
authored
406
407 .TP
408 \fBurl_decode(Str)\fR
e263363 @klacke speling
authored
409 Decode url-encoded string. A URL encoded string is a string where
2b9f008 @klacke ""
authored
410 all alfa numeric characters and the the character _ are preserved
411 and all other characters are encode as "%XY" where X and Y are the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
412 hex values of the least respective most significant 4 bits in the 8 bit
2b9f008 @klacke ""
authored
413 character.
414
415 .TP
416 \fBurl_encode(Str)\fR
417 Url-encodes a string. All URLs in HTML documents must be URL encoded.
418
419
814eb04 @klacke ""
authored
420 .TP
8d5aa60 @klacke ""
authored
421 \fBreformat_header(H)\fR
e263363 @klacke speling
authored
422 Returns a list of reformatted header values from a #header{}
814eb04 @klacke ""
authored
423 record. The return list is suitable for retransmit.
424
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
425 .TP
426 \fBrequest_url(ARG)\fR
427 Return the url as requested by the client. Return value
428 is a #url{} record as defined in yaws_api.hrl
429
2b9f008 @klacke ""
authored
430
8da2b3a @klacke parse_url
authored
431 .TP
432 \fBparse_url(Str)\fR
433 Parse URL in a string, returns a #url record
434
435 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
436 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored
437 Takes a #url record a formats the Url as a string
438
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
439 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
440 \fBcall_cgi(Arg, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
441 Calls an executable CGI script,
442 given by its full path. Used to make `.yaws' wrappers for CGI
443 programs. This function usually returns \fIstreamcontent\fR.
444
445 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
446 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
447 Like before, but
448 calls \fIExefilename\fR to handle the script. The file name of the
449 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored
450
f3deff2 @klacke added a dir_listing function in yaws_api
authored
451 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
452 \fBcall_fcgi_responder(Arg)\fR
2fa66b0 @klacke cgi support
authored
453 Calls a FastCGI responder.
454 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
455 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
456 Used to make `.yaws' wrappers for FastCGI responders.
457 Returns the same return values as out/1 (see below).
458
459 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
460 \fBcall_fcgi_responder(Arg, Options)\fR
2fa66b0 @klacke cgi support
authored
461 Same as above, but Options overrides the defaults from the server
462 configuration:
463
464 \fI
465 .nf
466 Options = [Option]
467 Option -- one of the following:
468 .fi
469 \fR
470
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
471 \fB{app_server_host, string() | ip_address()}\fR
2fa66b0 @klacke cgi support
authored
472 The hostname or the IP address of the FastCGI application server.
473
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
474 \fB{app_server_port, 0..65535}\fR
2fa66b0 @klacke cgi support
authored
475 The TCP port number of the FastCGI application server.
476
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
477 \fB{path_info, string()}\fR
2fa66b0 @klacke cgi support
authored
478 Override default pathinfo in Arg#arg.pathinfo.
479
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
480 \fB{extra_env, ExtraEnv}\fR
2fa66b0 @klacke cgi support
authored
481 Override default pathinfo in Arg#arg.pathinfo.
482
483 \fI
484 .nf
485 ExtraEnv = [Var]
486 Var = {Name, Value}
487 Name = string()
488 Value = string()
489 .fi
490 \fR
491
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
492 \fB{trace_protocol, boolean()}\fR
2fa66b0 @klacke cgi support
authored
493 Enable or disable tracing of FastCGI protocol messages as info
494 log messages.
495
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
496 \fB{log_app_error, boolean()}\fR
2fa66b0 @klacke cgi support
authored
497 Enable or disable logging of application error messages: output
498 to stderr and non-zero exit value.
499
500 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored
501 \fBcall_fcgi_authorizer(Arg) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored
502 Calls a FastCGI authorizer.
503 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
504 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
505 Used to make `.yaws' wrappers for FastCGI authorizers.
506 Variables contains the values of the variables returned by the FastCGI
507 application server in the "Variable-XXX: YYY" headers.
508
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored
509 If access is denied, Out contains the complete response returned by
510 the FastCGI application server. This response is typically returned
511 as-is to the HTTP client.
512
513 If access is allowed, Out contains the response returned by the
514 FastCGI application server minus the body (i.e. minus the content)
515 which should be ignored per the FastCGI specification. This response
516 is typically not returned to the HTTP client. The calling application
517 module may wish to inspect the response, for example by extracting
518 variables (see fcgi_extract_variables below) or by inspecting the
519 headers returned by the FastCGI application server.
520
2fa66b0 @klacke cgi support
authored
521 \fI
522 .nf
523 Out -- See return values for out/1 below
524 .fi
525 \fR
526
527 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored
528 \fBcall_fcgi_authorizer(Arg, Options) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored
529 Same as above, but Options overrides the defaults from the server
530 configuration. See call_fcgi_responder/2 above for a description
531 of Options.
532
533 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored
534 \fBfcgi_extract_variables(Out) -> [{Name, Value}]\fR
535 Extracts the environment variables from a FastCGI authorizer response
536 by looking for headers of the form "Variable-Name: Value".
537
538 \fI
539 .nf
540 Name = string() -- The name of the variable (the "Variable-" prefix
541 has already been removed).
542 Value = string() -- The value of the variable.
543 .fi
544 \fR
545
546 .TP
f3deff2 @klacke added a dir_listing function in yaws_api
authored
547 \fBdir_listing(Arg)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
548 Perform a directory listing. Can be used in special directories
f3deff2 @klacke added a dir_listing function in yaws_api
authored
549 when we don't want to turn on dir listings for the entire server.
550 Always returns ok.
8da2b3a @klacke parse_url
authored
551
abc3a43 @klacke documented yaws_api
authored
552 .SH RETURN VALUES from out/1
553 .PP
554 The out/1 function can return different values to control the behavior
555 of the server.
556
557 .TP
558 \fB{html, DeepList}\fB
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
559 This assumes that DeepList is formatted HTML code.
abc3a43 @klacke documented yaws_api
authored
560 The code will be inserted in the page.
561
562 .TP
04970fa exhtml cleanup
Claes Wikstrom authored
563 \fB{ehtml|exhtml, Term}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
564 This will transform the erlang term Term into a
04970fa exhtml cleanup
Claes Wikstrom authored
565 stream of HTML content. The exhtml variant transforms into
566 strict XHTML code. The basic syntax of Term
abc3a43 @klacke documented yaws_api
authored
567 is
568
569 \fI
570 .nf
571 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
572 binary() | character()
8d5aa60 @klacke ""
authored
573 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
574 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
575 Key = atom()
abc3a43 @klacke documented yaws_api
authored
576 Value = string()
577 Body = EHTML
578 .fi
579 \fR
580
581
ebb94d8 @klacke 1.54
authored
582 For example, \fI{p, [], "Howdy"}\fR expands into
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored
583 "<p>Howdy</p>" and
abc3a43 @klacke documented yaws_api
authored
584
585 \fI
586 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
587 {form, [{action, "a.yaws"}],
abc3a43 @klacke documented yaws_api
authored
588 {input, [{type,text}]}}
589
590 .fi
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
591 \fR
abc3a43 @klacke documented yaws_api
authored
592
593 expands into
594
595 \fI
596 .nf
597 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
598 <input type="text">
599 </form>
abc3a43 @klacke documented yaws_api
authored
600 .fi
601 \fR
602
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
603 It may be more convenient to generate erlang tuples
abc3a43 @klacke documented yaws_api
authored
604 than plain html code.
605
606 .TP
607 \fB{content, MimeType, Content}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
608 This function will make the web server generate
abc3a43 @klacke documented yaws_api
authored
609 different content than HTML. This return value is only allowed
610 in a yaws file which has only one <erl> </erl> part and no
611 html parts at all.
612
613
614 .TP
615 \fB{streamcontent, MimeType, FirstChunk}\fR
616 This return value plays the same role as the \fIcontent\fR return
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
617 value above.
e2f272a @klacke explicit support for content_length
authored
618
abc3a43 @klacke documented yaws_api
authored
619 However it makes it possible to stream data to the client
620 if the yaws code doesn't have access to all the data in one go. (Typically
621 if a file is very large or if data arrives from back end servers on the network.
622
623 .TP
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
624 \fB{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}\fR
404aec1 @sgolovan fix syntax and spelling errors in man pages
sgolovan authored
625 Similar to above, but with an explicit timeout. The default timeout
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
626 is 30 secs. I.e if the application fails to deliver data to the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
627 Yaws process, the streaming will stop. This is often not the
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
628 desired behaviour in Comet/Ajax applications. It's possible to
629 provide 'infinity' as timeout.
630
631 .TP
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored
632 \fB{streamcontent_from_pid, MimeType, Pid}\fR
633 This return value is similar to the \fIstreamcontent\fR return value above.
634
635 However it makes it possible to stream data to the client directly from an
636 application process to the socket. This approach can be useful for applications
637 that employ long-polling (Comet) techniques, for example, and for applications
638 wanting to avoid buffering data or avoid HTTP chunked mode transfer for streamed
639 data.
640
641 .TP
642 \fB{streamcontent_with_size, Sz, MimeType, FirstChunk}\fR
643 This return value is similar to the \fIstreamcontent\fR return value above.
644
645 However it makes it possible to stream data to the client by setting the content
646 length of the response. As the opposite of other ways to stream data, in this
647 case, the response is not chunked encoded.
648
649
650 .TP
abc3a43 @klacke documented yaws_api
authored
651 \fB{header, H}\fR
e2f272a @klacke explicit support for content_length
authored
652 Accumulates a HTTP header. The trailing CRNL which is supposed
ebb94d8 @klacke 1.54
authored
653 to end all HTTP headers must NOT be added. It is added by the server.
e2f272a @klacke explicit support for content_length
authored
654 The following list of headers are given special treatment.
655
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
656 \fI{connection, What}\fR
e2f272a @klacke explicit support for content_length
authored
657
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
658 This sets the Connection: header. If \fIWhat\fR is the special value
e2f272a @klacke explicit support for content_length
authored
659 \fI"close"\fR, the connection will be closed once the yaws page is delivered
660 to the client.
661
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
662 \fI{server, What}\fR
663
664 Sets the Server: header. By setting this header, the server's signature will be
665 dynamically overloaded.
666
e2f272a @klacke explicit support for content_length
authored
667 \fI{location, Url}\fR
668
669 Sets the Location: header. This header is typically combined with
670 the \fI{status, 302}\fR return value.
671
672 \fI{cache_control, What}\fR
673
674 Sets the Cache-Control: header.
675
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
676 \fI{expires, What}\fR
677
678 Sets the Expires: header.
679
680 \fI{date, What}\fR
681
682 Sets the Date: header.
683
684 \fI{allow, What}\fR
685
686 Sets the Allow: header.
687
688 \fI{last_modified, What}\fR
689
690 Sets the Last-Modified: header.
691
692 \fI{etag, What}\fR
693
694 Sets the Etag: header.
695
e2f272a @klacke explicit support for content_length
authored
696 \fI{set_cookie, Cookie}\fR
697
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
698 Prepends a Set-Cookie: header to the list of previously
e2f272a @klacke explicit support for content_length
authored
699 set Set-Cookie: headers.
700
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
701 \fI{content_range, What}\fR
702
703 Sets the Content-Range: header.
704
e2f272a @klacke explicit support for content_length
authored
705 \fI{content_type, MimeType}\fR
706
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
707 Sets the Content-Type: header.
708
709 \fI{content_encoding, What}\fR
710
711 Sets the Content-Encoding: header. If this header is defined, no deflate is
712 performed by Yaws. So you can compress data by yourself.
e2f272a @klacke explicit support for content_length
authored
713
714 \fI{content_length, Len}\fR
715
716 Normally yaws will ship Yaws pages using Transfer-Encoding: chunked. This
717 is because we generally can't know how long a yaws page will be. If we for
718 some reason want to force a Content-Length: header (and we actually do
719 know the length of the content, we can force yaws to not ship the
720 page chunked.
721
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
722 \fI{transfer_encoding, What}\fR
e2f272a @klacke explicit support for content_length
authored
723
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
724 Sets the Transfer-Encoding: header.
725
726 \fI{www_authenticate, What}\fR
727
728 Sets the WWW-Authenticate: header.
e2f272a @klacke explicit support for content_length
authored
729
730
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
731 All other headers must be added using the normal HTTP syntax.
732 Example:
e2f272a @klacke explicit support for content_length
authored
733
e61b0e3 @capflam Manage all 'special' headers of #headers{} and #outh{} records
capflam authored
734 \fI{header, {"My-X-Header", "gadong"}}\fR of \fI{header, "My-X-Header: gadong"}\fR
e2f272a @klacke explicit support for content_length
authored
735
abc3a43 @klacke documented yaws_api
authored
736
737 .TP
738 \fB{allheaders, HeaderList}\fB
739 Will clear all previously accumulated headers and replace them.
740
741
742 .TP
743 \fB{status, Code}\fR
744 Will set another HTTP status code than 200.
745
746
747 .TP
748 \fBbreak\fR
749 Will stop processing of any consecutive chunks of erl or html code
750 in the yaws file.
751
752 .TP
753 \fBok\fR
754 Do nothing.
755
f163227 @capflam Fix issue #88
capflam authored
756 .TP
757 \fBflush\fR
758 Flush remaining data sent by the client.
759
abc3a43 @klacke documented yaws_api
authored
760
761 .TP
762 \fB{redirect, Url}\fR
763 Erase all previous headers and accumulate a single
764 Location header. Set the status code.
765
766 .TP
767 \fB{redirect_local, Path}\fR
768 Does a redirect to the same Scheme://Host:Port/Path as we
769 currently are executing in.
770
771 .TP
772 \fB{get_more, Cont, State}\fR
773 When we are receiving large POSTs we can return this value
774 and be invoked again when more Data arrives.
775
776
777 .TP
c837288 @klacke page retval
authored
778 \fB{page, Page}\fR
779 Make Yaws return a different page than the one being
780 requested.
781
782
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
783 .TP
784 \fB{page, {Options, Page}}\fR
785 Like the above, but supplying an additional deep list of options. For
786 now, the only type of option is \fI{header, H}\fR with the effect of
787 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
788
c837288 @klacke page retval
authored
789
790 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
791 \fB{ssi, File, Delimiter, Bindings}\fR
792 Server side include File and macro expansion in File.
e263363 @klacke speling
authored
793 Each occurrence of a string, say "xyz", inside File which
794 is inside Delimiters is replaced with the corresponding
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
795 value in Bindings.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
796
797 Example:
798 Delimiter = %%
799
800 File contains the string .... %%xyz%% .....
801
802 Bindings contain the tuple {"xyz", "Dingbat"}
803
e263363 @klacke speling
authored
804 The occurrence of %%xyz%% in File will be replaced with "Dingbat"
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
805 in the Server side included output.
806
807 The {ssi, File, Delimiter, Bindings} statement can also
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
808 occur inside a deep ehtml structure.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
809
810
811 .TP
379666b @klacke documented jockes new bindings feature
authored
812 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
813 Establish variable bindings that can be used in the page.
814
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
815 All bindings can then be used in the rest of yaws code
816 (in HTML source and within erl tags).
817 In HTML source %%Key%% is expanded to Value and within erl
ab5edc6 @klacke *** empty log message ***
authored
818 tags \fIyaws_api:binding(Key)\fR can be used to extract Value
819 and \fIyaws_api:binding_exists(Key)\fR can be used to check for
e263363 @klacke speling
authored
820 the existence of a binding.
df96b15 @klacke New feature yssi, yaws include
authored
821
822 .TP
823 \fB{yssi, YawsFile}\fR
824 Include a yaws file. Compile it and expand as if it had
825 occured inline.
826
379666b @klacke documented jockes new bindings feature
authored
827 .TP
abc3a43 @klacke documented yaws_api
authored
828 \fB[ListOfValues]\fR
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored
829 It is possible to return a deep list of the above defined return values. Any
830 occurrence of \fIstreamcontent\fR, \fIstreamcontent_with_timeout\fR,
831 \fIstreamcontent_with_size\fR, \fIstreamcontent_from_pid\fR, \fIget_more\fR,
832 \fIpage\fR or \fIbreak\fR in this list is legal only if it is the last position
833 of the list. If not, remaining values in the list are ignored.
abc3a43 @klacke documented yaws_api
authored
834
835
836
837
838 .SH AUTHOR
839 Written by Claes Wikstrom
840 .SH "SEE ALSO"
841 .BR yaws.conf (5)
842 .BR erl (1)
843
Something went wrong with that request. Please try again.