File: httpd.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (606 lines) | stat: -rw-r--r-- 19,774 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>httpd</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>httpd</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
httpd 

</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
An implementation of an HTTP 1.1 compliant Web server,
as defined in RFC 2616.


</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>Mainly specifies the Erlang Webserver callback API but also
provide some test and admin. functionality.
</DIV>

<H3> DATA TYPES </H3>
<DIV CLASS=REFBODY>

<PRE>
      ModData = #mod{}
    
</PRE>

<PRE>
      -record(mod, {
                data = [],
                socket_type = ip_comm,
                socket, 
                config_db,
                method,
                absolute_uri,
                request_uri,
                http_version,
                request_line,
                parsed_header = [],
                entity_body,
                connection
               }).
    
</PRE>

<P>The fields of the <CODE>mod</CODE> record has the following meaning:


<P>
<DL>

<DT>
<CODE>data</CODE>

</DT>

<DD>
Type <CODE>[{InteractionKey,InteractionValue}]</CODE> is used to
        propagate data between modules. Depicted
<CODE>interaction_data()</CODE> in function type declarations.
        

</DD>

<DT>
<CODE>socket_type</CODE>

</DT>

<DD>
<CODE>socket_type()</CODE>,
        Indicates whether it is a ip socket or a ssl socket.
        

</DD>

<DT>
<CODE>socket</CODE>

</DT>

<DD>
The actual socket in <CODE>ip_comm</CODE> or <CODE>ssl</CODE> format
        depending on the <CODE>socket_type</CODE>.
        

</DD>

<DT>
<CODE>config_db</CODE>

</DT>

<DD>
The config file directives stored as key-value tuples in
        an ETS-table. Depicted <CODE>config_db()</CODE> in function type
        declarations.
        

</DD>

<DT>
<CODE>method</CODE>

</DT>

<DD>
Type <CODE>&#34;GET&#34; | &#34;POST&#34; | &#34;HEAD&#34; | &#34;TRACE&#34;</CODE>, that is the
        HTTP metod.


</DD>

<DT>
<CODE>absolute_uri</CODE> 
</DT>

<DD>
If the request is a HTTP/1.1
request the URI might be in the absolute URI format. In that
case httpd will save the absolute URI in this field. An Example
of an absolute URI could
be<CODE>&#34;http://ServerName:Part/cgi-bin/find.pl?person=jocke&#34;</CODE>


</DD>

<DT>
<CODE>request_uri</CODE> 
</DT>

<DD>
The <CODE>Request-URI</CODE> as defined
in RFC 1945, for example <CODE>&#34;/cgi-bin/find.pl?person=jocke&#34;</CODE>



</DD>

<DT>
<CODE>http_version</CODE> 
</DT>

<DD>
The <CODE>HTTP</CODE> version of the
request, that is &#34;HTTP/0.9&#34;, &#34;HTTP/1.0&#34;, or &#34;HTTP/1.1&#34;.


</DD>

<DT>
<CODE>request_line</CODE> 
</DT>

<DD>
The <CODE>Request-Line</CODE> as
defined in RFC 1945, for example <CODE>&#34;GET
/cgi-bin/find.pl?person=jocke HTTP/1.0&#34;</CODE>.


</DD>

<DT>
<CODE>parsed_header</CODE> 
</DT>

<DD>
Type
<CODE>[{HeaderKey,HeaderValue}]</CODE>, <CODE>parsed_header</CODE> contains
all HTTP header fields from the HTTP-request stored in a list as
key-value tuples. See RFC 2616 for a listing of all header
fields. For example the date field would be stored as:
<CODE>{&#34;date&#34;,&#34;Wed, 15 Oct 1997 14:35:17 GMT&#34;}. RFC 2616 defines
that HTTP is a case insensitive protocol and the header fields
may be in lowercase or upper case. Httpd will ensure that all
header field names are in lowe case</CODE>.


</DD>

<DT>
<CODE>entity_body</CODE> 
</DT>

<DD>
The <CODE>Entity-Body</CODE> as defined
in RFC 2616, for example data sent from a CGI-script using the
POST method.


</DD>

<DT>
<CODE>connection</CODE>

</DT>

<DD>
 <CODE>true | false</CODE> If set to true the connection to the
        client is a persistent connections and will not be closed when
        the request is served.

</DD>

</DL>

</DIV>

<H3>Erlang Webserver API Callback Functions</H3>
<DIV CLASS=REFBODY>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="Module:do/1"><STRONG><CODE>Module:do(ModData)-&#62; {proceed, OldData} | {proceed, NewData} | {break, NewData} | done</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>OldData = list()</CODE></STRONG><BR>
<STRONG><CODE>NewData = [{response,{StatusCode,Body}}] | [{response,{response,Head,Body2}}] | 
         [{response,{already_sent,Statuscode,Size}] </CODE></STRONG><BR>
<STRONG><CODE>StausCode = integer()</CODE></STRONG><BR>
<STRONG><CODE>Body = io_list() | nobody | {Fun, Arg}</CODE></STRONG><BR>
<STRONG><CODE>Head = [HeaderOption]</CODE></STRONG><BR>
<STRONG><CODE>HeaderOption = {Key, Value} | {code, StatusCode}</CODE></STRONG><BR>
<STRONG><CODE>Key = allow | cache_control | content_MD5 | content_encoding
         | content_encoding | content_language | content_length
         | content_location | content_range | content_type | date | etag
         | expires | last_modified | location | pragma | retry_after |
         server | trailer | transfer_encoding</CODE></STRONG><BR>
<STRONG><CODE>Value = string()</CODE></STRONG><BR>
<STRONG><CODE>Fun = fun( Arg ) -&#62; sent| close | Body </CODE></STRONG><BR>
<STRONG><CODE>Arg = [term()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>      When a valid request reaches httpd it calls <CODE>do/1</CODE> in
         each module defined by the Modules configuration
         directive. The function may generate data for other modules
         or a response that can be sent back to the client.
        
<P>The field <CODE>data</CODE> in ModData is a list. This list will be
         the list returned from the from the last call to
         <CODE>do/1</CODE>.
        
<P>      
         <CODE>Body</CODE> is the body of the http-response that will be
         sent back to the client an appropriate header will be
         appended to the message. <CODE>StatusCode</CODE> will be the
         status code of the response see RFC2616 for the appropriate
         values.
        
<P>      <CODE>Head</CODE> is a key value list of HTTP header fields. the
         server will construct a HTTP header from this data. See RFC
         2616 for the appropriate value for each header field. If the
         client is a HTTP/1.0 client then the server will filter the
         list so that only HTTP/1.0 header fields will be sent back
         to the client.
        
<P>      If <CODE>Body2</CODE> is returned and equal to <CODE>{Fun,Arg}</CODE>
         The Web server will try <CODE>apply/2</CODE>. on <CODE>Fun</CODE> with
         <CODE>Arg</CODE> as argument and excpect that the fun either
         returns a list <CODE>(Body)</CODE> that is a HTTP-repsonse or the
         atom sent if the HTTP-response is sent back to the
         client. If close is returned from the fun something has gone
         wrong and the server will signal this to the client by
         closing the connection.
        
</DIV>

<P><A NAME="Module:load/2"><STRONG><CODE>Module:load(Line, Context)-&#62; eof | ok | {ok, NewContext} | 
        {ok, NewContext, Directive} | {ok, NewContext, DirectiveList} | {error, Reason} </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Line = string()</CODE></STRONG><BR>
<STRONG><CODE>Context = NewContext = DirectiveList = [Directive]</CODE></STRONG><BR>
<STRONG><CODE>Directive = {DirectiveKey , DirectiveValue} </CODE></STRONG><BR>
<STRONG><CODE>DirectiveKey = DirectiveValue = term() </CODE></STRONG><BR>
<STRONG><CODE>Reason = term()
</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>      <CODE>load/2</CODE> takes a row <CODE>Line</CODE> from the configuration
         file and tries to convert it to a key value tuple. If a
         directive is dependent on other directives, the directive
         may create a context. If the directive is not dependent on
         other directives return <CODE>{ok, [], Directive}</CODE>,
         otherwise return a new context, that is <CODE>{ok,
         NewContext}</CODE> or {ok, Context Directive}. If <CODE>{error,
         Reason}</CODE> is returned the configuration directive is
         assumed to be invalid.

</DIV>

<P><A NAME="Module:store/3"><STRONG><CODE>Module:store({DirectiveKey, DirectiveValue}, DirectiveList)-&#62; {ok, {DirectiveKey, NewDirectiveValue}} |
        {ok, [{ok, {DirectiveKey, NewDirectiveValue}} | {error, Reason} </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>DirectiveList = [{DirectiveKey, DirectiveValue}]</CODE></STRONG><BR>
<STRONG><CODE>DirectiveKey = DirecitveValue = term()</CODE></STRONG><BR>
<STRONG><CODE>Context = NewContext = DirectiveList = [Directive]</CODE></STRONG><BR>
<STRONG><CODE>Directive = {Key , Value} </CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>      When all rows in the configuration file is read the function
         <CODE>store/2</CODE> is called for each configuration
         directive. This makes it possible for a directive to alter
         other configuration directives. <CODE>DirectiveList</CODE> is a
         list of all configuration directives read in from load. If
         a directive may update other configuration directives then
         use this function.

</DIV>

<P><A NAME="Module:remove/1"><STRONG><CODE>Module:remove(ConfigDB)-&#62; ok | {error, Reason} </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ConfigDB = ets_table()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>      When httpd shutdown it will try to execute <CODE>remove/1</CODE>
         in each ewsapi module. The ewsapi programmer may use this to
         close ets tables, save data, or close down background
         processes.

</DIV>

<H3>Erlang Webserver API Help Functions</H3>
<DIV CLASS=REFBODY>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="parse_query/1"><STRONG><CODE>parse_query(QueryString) -&#62; ServerRet</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>QueryString = string()</CODE></STRONG><BR>
<STRONG><CODE>ServerRet = [{Key,Value}]</CODE></STRONG><BR>
<STRONG><CODE>Key = Value = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="parse_query"><!-- Empty --></A>
<P><CODE>parse_query/1</CODE> parses incoming data to <CODE>erl</CODE> and
         <CODE>eval</CODE> scripts (See <A HREF="mod_esi.html">mod_esi(3)</A>) as defined in the standard
         URL format, that is '+' becomes 'space' and decoding of
         hexadecimal characters (<CODE>%xx</CODE>).

</DIV>

<H3>Erlang Webserver Test and Admin Functions</H3>
<DIV CLASS=REFBODY>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start/0"><STRONG><CODE>start()</CODE></STRONG></A><BR>
<A NAME="start/1"><STRONG><CODE>start(Config) -&#62; ServerRet</CODE></STRONG></A><BR>
<A NAME="start_link/0"><STRONG><CODE>start_link()</CODE></STRONG></A><BR>
<A NAME="start_link/1"><STRONG><CODE>start_link(Config) -&#62; ServerRet</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Config = string() | HttpdOptions</CODE></STRONG><BR>
<STRONG><CODE>ServerRet = {ok,Pid} | ignore | {error,EReason} | {stop,SReason}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>EReason = {already_started, Pid} | term()</CODE></STRONG><BR>
<STRONG><CODE>SReason = string()</CODE></STRONG><BR>
<STRONG><CODE>HttpdOptions = {file,string()} , {debug,Debug}? , {accept_timeout,integer()}?</CODE></STRONG><BR>
<STRONG><CODE>Debug = disable | [DebugOptions]</CODE></STRONG><BR>
<STRONG><CODE>DebugOptions = {all_functions,Modules} | {exported_functions,Modules} | {disable,Modules}</CODE></STRONG><BR>
<STRONG><CODE>Modules = [atom()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="start"><!-- Empty --></A>
<P><CODE>start/1</CODE> and <CODE>start_link/1</CODE> starts a server 
         as specified in the given <CODE>ConfigFile</CODE>. The <CODE>ConfigFile</CODE> 
         supports a number of config directives specified below.
         
        
<P><CODE>start/0</CODE> and <CODE>start/0</CODE> starts a server as specified
         in a hard-wired config file, that is
         <CODE>start(&#34;/var/tmp/server_root/conf/8888.conf&#34;)</CODE>. Before
         utilizing <CODE>start/0</CODE> or <CODE>start_link/0</CODE>, copy the 
         example server
         root <FONT SIZE="-2">(<CODE>UNIX: $INETS_ROOT/examples/server_root/, Windows: %INETS_ROOT%\examples\server_root\</CODE>)</FONT> to a specific installation directory <FONT SIZE="-2">(<CODE>UNIX: /var/tmp/, Windows: X:\var\tmp\</CODE>)</FONT>
         and you have a server running in no time. 
         
        
<P>If you copy the example server root to the specific
         installation directory it is furthermore easy to start an
         SSL enabled server, that is
         <CODE>start(&#34;/var/tmp/server_root/conf/ssl.conf&#34;)</CODE>.

</DIV>

<P><A NAME="restart/0"><STRONG><CODE>restart()</CODE></STRONG></A><BR>
<A NAME="restart/1"><STRONG><CODE>restart(Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="restart/1"><STRONG><CODE>restart(ConfigFile) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="restart/2"><STRONG><CODE>restart(Address,Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Port = integer()</CODE></STRONG><BR>
<STRONG><CODE>Address = {A,B,C,D} | string() | undefined</CODE></STRONG><BR>
<STRONG><CODE>ConfigFile = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="restart"><!-- Empty --></A>
<P><CODE>restart</CODE> restarts the server and reloads its config file. 
        
<P>The follwing directives cannot be changed: BindAddress, Port and 
         SocketType. If these should be changed, then a new server should be
         started instead.
        
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>      Before the <CODE>restart</CODE> function can be called the
         server must be <A HREF="#block">blocked</A>. After <CODE>restart</CODE>
         has been called, the server must be <A HREF="#unblock"> unblocked</A>.    </TD>
  </TR>
</TABLE>

</DIV>

<P><A NAME="stop/0"><STRONG><CODE>stop()</CODE></STRONG></A><BR>
<A NAME="stop/1"><STRONG><CODE>stop(Port) -&#62; ServerRet</CODE></STRONG></A><BR>
<A NAME="stop/1"><STRONG><CODE>stop(ConfigFile) -&#62; ServerRet</CODE></STRONG></A><BR>
<A NAME="stop/2"><STRONG><CODE>stop(Address,Port) -&#62; ServerRet</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Port = integer()</CODE></STRONG><BR>
<STRONG><CODE>Address = {A,B,C,D} | string() | undefined</CODE></STRONG><BR>
<STRONG><CODE>ConfigFile = string()</CODE></STRONG><BR>
<STRONG><CODE>ServerRet = ok | not_started</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="stop"><!-- Empty --></A>
<P><CODE>stop/2</CODE> stops the server which listens to the specified 
         <CODE>Port</CODE> on <CODE>Address</CODE>.
         <CODE>stop(integer())</CODE> stops a server which listens to a specific
         <CODE>Port</CODE>. 
         <CODE>stop(string())</CODE> extracts <CODE>BindAddress</CODE> and <CODE>Port</CODE> 
         from the config file and stops the server which listens to the 
         specified <CODE>Port</CODE> on <CODE>Address</CODE>.
         <CODE>stop/0</CODE> stops a server which listens to port 8888, that is 
         <CODE>stop(8888)</CODE>. 

</DIV>

<P><A NAME="block/0"><STRONG><CODE>block() -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/1"><STRONG><CODE>block(Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/1"><STRONG><CODE>block(ConfigFile) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/2"><STRONG><CODE>block(Address,Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/2"><STRONG><CODE>block(Port,Mode) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/2"><STRONG><CODE>block(ConfigFile,Mode) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/3"><STRONG><CODE>block(Address,Port,Mode) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/3"><STRONG><CODE>block(ConfigFile,Mode,Timeout) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="block/4"><STRONG><CODE>block(Address,Port,Mode,Timeout) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Port = integer()</CODE></STRONG><BR>
<STRONG><CODE>Address = {A,B,C,D} | string() | undefined</CODE></STRONG><BR>
<STRONG><CODE>ConfigFile = string()</CODE></STRONG><BR>
<STRONG><CODE>Mode = disturbing | non_disturbing</CODE></STRONG><BR>
<STRONG><CODE>Timeout = integer()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="block"><!-- Empty --></A>
<P>This function is used to block a server. The blocking can be done 
         in two ways, disturbing or non-disturbing.
<P>By performing a <STRONG>disturbing</STRONG> block, the server is blocked 
         forcefully and all ongoing requests are terminated. No new 
         connections are accepted. If a timeout time is given then on-going 
         requests are given this much time to complete before the server is 
         forcefully blocked. In this case no new connections is accepted.
<P>A <STRONG>non-disturbing</STRONG> block is more gracefull. No new 
         connections are accepted, but the ongoing requests are allowed to 
         complete. If a timeout time is given, it waits this long before
         giving up (the block operation is aborted and the server state is 
         once more not-blocked)
<P>Default mode is disturbing.
<P>Default port is 8888
</DIV>

<P><A NAME="unblock/0"><STRONG><CODE>unblock() -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="unblock/1"><STRONG><CODE>unblock(Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="unblock/1"><STRONG><CODE>unblock(ConfigFile) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>
<A NAME="unblock/2"><STRONG><CODE>unblock(Address,Port) -&#62; ok | {error,Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Port = integer()</CODE></STRONG><BR>
<STRONG><CODE>Address = {A,B,C,D} | string() | undefined</CODE></STRONG><BR>
<STRONG><CODE>ConfigFile = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="unblock"><!-- Empty --></A>
<P>Unblocks a server. If the server is already unblocked this is a 
         no-op. If a block is ongoing, then it is aborted
         (this will have no effect on ongoing requests).
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Joakim Greben - support@erlang.ericsson.se<BR>
Torbjrn Trnkvist - support@erlang.ericsson.se<BR>
Joe Armstrong  - support@erlang.ericsson.se<BR>
Ingela Anderton Andin  - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>inets 4.7.6<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>