diff options
Diffstat (limited to 'lib/inets/doc/src/httpd_util.xml')
| -rw-r--r-- | lib/inets/doc/src/httpd_util.xml | 260 |
1 files changed, 95 insertions, 165 deletions
diff --git a/lib/inets/doc/src/httpd_util.xml b/lib/inets/doc/src/httpd_util.xml index a48e141368..0f498ba2fc 100644 --- a/lib/inets/doc/src/httpd_util.xml +++ b/lib/inets/doc/src/httpd_util.xml @@ -30,9 +30,10 @@ <file>httpd_util.sgml</file> </header> <module>httpd_util</module> - <modulesummary>Miscellaneous utility functions to be used when implementing Erlang Web server API modules.</modulesummary> + <modulesummary>Miscellaneous utility functions to be used when implementing + Erlang web server API modules.</modulesummary> <description> - <p>This module provides the Erlang Web Server API module + <p>This module provides the Erlang web server API module programmer with miscellaneous utility functions.</p> <marker id="convert_request_date"></marker> @@ -41,7 +42,7 @@ <funcs> <func> <name>convert_request_date(DateString) -> ErlDate|bad_date</name> - <fsummary>Convert The the date to the Erlang date format.</fsummary> + <fsummary>Converts the date to the Erlang date format.</fsummary> <type> <v>DateString = string()</v> <v>ErlDate = {{Year,Month,Date},{Hour,Min,Sec}}</v> @@ -49,10 +50,9 @@ </type> <desc> <p><c>convert_request_date/1</c> converts <c>DateString</c> to - the Erlang date format. DateString must be in one of the three - date formats that is defined in the RFC 2616.</p> - - <marker id="create_etag"></marker> + the Erlang date format. <c>DateString</c> must be in one of the + three date formats defined in + <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>.</p> </desc> </func> @@ -64,128 +64,84 @@ <v>Etag = string()</v> </type> <desc> - <p><c>create_etag/1</c> calculates the Etag for a file, from its - size and time for last modification. fileinfo is a record defined - in <c>kernel/include/file.hrl</c></p> - - <marker id="decode_hex"></marker> + <p><c>create_etag/1</c> calculates the Etag for a file from its + size and time for last modification. <c>FileInfo</c> is a record defined + in <c>kernel/include/file.hrl</c>.</p> </desc> </func> - - <func> - <name>decode_hex(HexValue) -> DecValue</name> - <fsummary>Convert a hex value into its decimal equivalent.</fsummary> - <type> - <v>HexValue = DecValue = string()</v> - </type> - <desc> - <p>Converts the hexadecimal value <c>HexValue</c> into its - decimal equivalent (<c>DecValue</c>).</p> - - <marker id="day"></marker> - </desc> - </func> - + <func> <name>day(NthDayOfWeek) -> DayOfWeek</name> - <fsummary>Convert the day of the week (integer [1-7]) to an abbreviated string.</fsummary> + <fsummary>Converts the day of the week + (integer [1-7]) to an abbreviated string.</fsummary> <type> <v>NthDayOfWeek = 1-7</v> <v>DayOfWeek = string()</v> </type> <desc> - <marker id="day"></marker> <p><c>day/1</c> converts the day of the week - (<c>NthDayOfWeek</c>) as an integer (1-7) to an abbreviated - string, that is: </p> + (<c>NthDayOfWeek</c>) from an integer (1-7) to an abbreviated + string, that is:</p> <p>1 = "Mon", 2 = "Tue", ..., 7 = "Sat".</p> - - <marker id="flatlength"></marker> </desc> </func> <func> - <name>flatlength(NestedList) -> Size</name> - <fsummary>Compute the size of a possibly nested list.</fsummary> + <name>decode_hex(HexValue) -> DecValue</name> + <fsummary>Converts a hexadecimal value into its decimal equivalent.</fsummary> <type> - <v>NestedList = list()</v> - <v>Size = integer()</v> + <v>HexValue = DecValue = string()</v> </type> <desc> - <marker id="flatlength"></marker> - <p><c>flatlength/1</c> computes the size of the possibly nested - list <c>NestedList</c>. Which may contain binaries.</p> - - <marker id="hexlist_to_integer"></marker> + <p>Converts the hexadecimal value <c>HexValue</c> into its + decimal equivalent (<c>DecValue</c>).</p> </desc> </func> - -<!-- + <func> - <name>header(StatusCode,PersistentConn)</name> - <name>header(StatusCode,Date)</name> - <name>header(StatusCode,MimeType,Date)</name> - <name>header(StatusCode,MimeType,PersistentConn,Date) -> HTTPHeader</name> - <fsummary>Generate a HTTP 1.1 header.</fsummary> + <name>flatlength(NestedList) -> Size</name> + <fsummary>Computes the size of a possibly nested list.</fsummary> <type> - <v>StatusCode = integer()</v> - <v>Date = rfc1123_date()</v> - <v>MimeType = string()</v> - <v>PersistentConn = true | false</v> + <v>NestedList = list()</v> + <v>Size = integer()</v> </type> <desc> - <marker id="header"></marker> - <p><c>header</c> returns a HTTP 1.1 header string. The - <c>StatusCode</c> is one of the status codes defined in RFC - 2616 and the <c>Date</c> string is RFC 1123 - compliant. (See <seealso marker="#rfc1123_date">rfc1123_date/0</seealso>). - </p> - <p>Note that the two version of <c>header/n</c> that does not - has a <c>PersistentConn</c> argument is there only for - backward compatibility, and must not be used in new Erlang - Webserver API modules. that will support persistent - connections.</p> - - <marker id="hexlist_to_integer"></marker> + <p><c>flatlength/1</c> computes the size of the possibly nested + list <c>NestedList</c>, which can contain binaries.</p> </desc> </func> ---> <func> <name>hexlist_to_integer(HexString) -> Number</name> - <fsummary>Convert a hexadecimal string to an integer.</fsummary> + <fsummary>Converts a hexadecimal string to an integer.</fsummary> <type> <v>Number = integer()</v> <v>HexString = string()</v> </type> <desc> - <p><c>hexlist_to_integer</c> Convert the Hexadecimal value of - HexString to an integer.</p> - - <marker id="integer_to_hexlist"></marker> + <p><c>hexlist_to_integer</c> converts the hexadecimal value of + <c>HexString</c> to an integer.</p> </desc> </func> <func> <name>integer_to_hexlist(Number) -> HexString</name> - <fsummary>Convert an integer to a hexadecimal string.</fsummary> + <fsummary>Converts an integer to a hexadecimal string.</fsummary> <type> <v>Number = integer()</v> <v>HexString = string()</v> </type> <desc> - <marker id="integer_to_hexlist"></marker> - <p><c>integer_to_hexlist/1</c> Returns a string that represents - the Number in a Hexadecimal form.</p> - - <marker id="lookup"></marker> + <p><c>integer_to_hexlist/1</c> returns a string representing + <c>Number</c> in a hexadecimal form.</p> </desc> </func> <func> <name>lookup(ETSTable,Key) -> Result</name> <name>lookup(ETSTable,Key,Undefined) -> Result</name> - <fsummary>Extract the first value associated with a key in an ETS table.</fsummary> + <fsummary>Extracts the first value associated with a <c>Key</c> + in an ETS table.</fsummary> <type> <v>ETSTable = ets_table()</v> <v>Key = term()</v> @@ -195,20 +151,18 @@ <desc> <p><c>lookup</c> extracts <c>{Key,Value}</c> tuples from <c>ETSTable</c> and returns the <c>Value</c> associated - with <c>Key</c>. If <c>ETSTable</c> is of type <c>bag</c> + with <c>Key</c>. If <c>ETSTable</c> is of type <c>bag</c>, only the first <c>Value</c> associated with <c>Key</c> is returned. <c>lookup/2</c> returns <c>undefined</c> and <c>lookup/3</c> returns <c>Undefined</c> if no <c>Value</c> is found.</p> - - <marker id="lookup_mime"></marker> </desc> </func> <func> <name>lookup_mime(ConfigDB,Suffix)</name> <name>lookup_mime(ConfigDB,Suffix,Undefined) -> MimeType</name> - <fsummary>Return the mime type associated with a specific file suffix. </fsummary> + <fsummary>Returns the MIME type associated with a specific file suffix.</fsummary> <type> <v>ConfigDB = ets_table()</v> <v>Suffix = string()</v> @@ -216,20 +170,19 @@ <v>Undefined = term()</v> </type> <desc> - <marker id="lookup_mime"></marker> - <p><c>lookup_mime</c> returns the mime type associated with a - specific file suffix as specified in the <c>mime.types</c> - file (located in the - <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types">config directory</path>).</p> - - <marker id="lookup_mime_default"></marker> + <p><c>lookup_mime</c> returns the MIME type associated with a + specific file suffix as specified in the file <c>mime.types</c> + (located in the + <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types"> + config directory</path>).</p> </desc> </func> <func> <name>lookup_mime_default(ConfigDB,Suffix)</name> <name>lookup_mime_default(ConfigDB,Suffix,Undefined) -> MimeType</name> - <fsummary>Return the mime type associated with a specific file suffix or the value of the DefaultType.</fsummary> + <fsummary>Returns the MIME type associated with a specific file suffix + or the value of the DefaultType.</fsummary> <type> <v>ConfigDB = ets_table()</v> <v>Suffix = string()</v> @@ -237,22 +190,19 @@ <v>Undefined = term()</v> </type> <desc> - <marker id="lookup_mime_default"></marker> - <p><c>lookup_mime_default</c> returns the mime type associated + <p><c>lookup_mime_default</c> returns the MIME type associated with a specific file suffix as specified in the <c>mime.types</c> file (located in the - <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types">config directory</path>). - If no appropriate association can be found - the value of DefaultType is + <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types"> + config directory</path>). + If no appropriate association is found, the value of <c>DefaultType</c> is returned.</p> - - <marker id="message"></marker> </desc> </func> <func> <name>message(StatusCode,PhraseArgs,ConfigDB) -> Message</name> - <fsummary>Return an informative HTTP 1.1 status string in HTML.</fsummary> + <fsummary>Returns an informative HTTP 1.1 status string in HTML.</fsummary> <type> <v>StatusCode = 301 | 400 | 403 | 404 | 500 | 501 | 504</v> <v>PhraseArgs = term()</v> @@ -260,53 +210,48 @@ <v>Message = string()</v> </type> <desc> - <marker id="message"></marker> <p><c>message/3</c> returns an informative HTTP 1.1 status string in HTML. Each <c>StatusCode</c> requires a specific <c>PhraseArgs</c>: </p> <taglist> <tag><c>301</c></tag> - <item><c>string()</c>: A URL pointing at the new document - position.</item> + <item><p><c>string()</c>: A URL pointing at the new document + position.</p></item> <tag><c>400 | 401 | 500</c></tag> - <item><c>none</c> (No <c>PhraseArgs</c>)</item> + <item><p><c>none</c> (no <c>PhraseArgs</c>).</p></item> <tag><c>403 | 404</c></tag> - <item><c>string()</c>: A <c>Request-URI</c> as described in - RFC 2616.</item> + <item><p><c>string()</c>: A <c>Request-URI</c> as described in + <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>.</p> + </item> <tag><c>501</c></tag> - <item><c>{Method,RequestURI,HTTPVersion}</c>: The HTTP - <c>Method</c>, <c>Request-URI</c> and <c>HTTP-Version</c> - as defined in RFC 2616.</item> + <item><p><c>{Method,RequestURI,HTTPVersion}</c>: The HTTP + <c>Method</c>, <c>Request-URI</c>, and <c>HTTP-Version</c> + as defined in RFC 2616.</p></item> <tag><c>504</c></tag> - <item><c>string()</c>: A string describing why the service - was unavailable.</item> + <item><p><c>string()</c>: A string describing why the service + was unavailable.</p></item> </taglist> - - <marker id="month"></marker> </desc> </func> <func> <name>month(NthMonth) -> Month</name> - <fsummary>Convert the month as an integer (1-12) to an abbreviated string.</fsummary> + <fsummary>Converts the month as an integer (1-12) to an abbreviated string.</fsummary> <type> <v>NthMonth = 1-12</v> <v>Month = string()</v> </type> <desc> - <marker id="month"></marker> <p><c>month/1</c> converts the month <c>NthMonth</c> as an integer (1-12) to an abbreviated string, that is: </p> <p>1 = "Jan", 2 = "Feb", ..., 12 = "Dec".</p> - - <marker id="multi_lookup"></marker> </desc> </func> <func> <name>multi_lookup(ETSTable,Key) -> Result</name> - <fsummary>Extract the values associated with a key in a ETS table.</fsummary> + <fsummary>Extracts the values associated with a key in an ETS table.</fsummary> <type> <v>ETSTable = ets_table()</v> <v>Key = term()</v> @@ -314,49 +259,44 @@ </type> <desc> <p><c>multi_lookup</c> extracts all <c>{Key,Value}</c> tuples - from an <c>ETSTable</c> and returns <em>all</em><c>Values</c> associated with the <c>Key</c> in a list.</p> - - <marker id="reason phrase"></marker> + from an <c>ETSTable</c> and returns <em>all</em> <c>Values</c> + associated with <c>Key</c> in a list.</p> </desc> </func> <func> <name>reason_phrase(StatusCode) -> Description</name> - <fsummary>Return the description of an HTTP 1.1 status code.</fsummary> + <fsummary>Returns the description of an HTTP 1.1 status code.</fsummary> <type> - <v>StatusCode = 100| 200 | 201 | 202 | 204 | 205 | 206 | 300 | 301 | 302 | 303 | 304 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 410 411 | 412 | 413 | 414 415 | 416 | 417 | 500 | 501 | 502 | 503 | 504 | 505</v> + <v>StatusCode = 100| 200 | 201 | 202 | 204 | 205 | 206 | 300 | 301 | 302 | 303 | 304 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 410 411 | 412 | 413 | 414 415 | 416 | 417 | 500 | 501 | 502 | 503 | 504 | 505</v> <v>Description = string()</v> </type> <desc> - <p><c>reason_phrase</c> returns the <c>Description</c> of an - HTTP 1.1 <c>StatusCode</c>, for example 200 is "OK" and 201 - is "Created". Read RFC 2616 for further information.</p> - - <marker id="rfc1123_date"></marker> + <p><c>reason_phrase</c> returns <c>Description</c> of an + HTTP 1.1 <c>StatusCode</c>, for example, 200 is "OK" and 201 + is "Created". For more information, see + <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>.</p> </desc> </func> <func> <name>rfc1123_date() -> RFC1123Date</name> <name>rfc1123_date({{YYYY,MM,DD},{Hour,Min,Sec}}) -> RFC1123Date</name> - <fsummary>Return the current date in RFC 1123 format.</fsummary> + <fsummary>Returns the current date in RFC 1123 format.</fsummary> <type> <v>YYYY = MM = DD = Hour = Min = Sec = integer()</v> <v>RFC1123Date = string()</v> </type> <desc> - <marker id="rfc1123_date"></marker> <p><c>rfc1123_date/0</c> returns the current date in RFC 1123 format. <c>rfc_date/1</c> converts the date in the Erlang format to the RFC 1123 date format.</p> - - <marker id="split"></marker> </desc> </func> <func> <name>split(String,RegExp,N) -> SplitRes</name> - <fsummary>Split a string in N chunks using a regular expression.</fsummary> + <fsummary>Splits a string in N chunks using a regular expression.</fsummary> <type> <v>String = RegExp = string()</v> <v>SplitRes = {ok, FieldList} | {error, errordesc()}</v> @@ -364,96 +304,86 @@ <v>N = integer</v> </type> <desc> - <marker id="split"></marker> - <p><c>split/3</c> splits the <c>String</c> in <c>N</c> chunks - using the <c>RegExp</c>. <c>split/3</c> is is equivalent to - <c>regexp:split/2</c> with one exception, that is <c>N</c> - defines the number of maximum number of fields in the + <p><c>split/3</c> splits <c>String</c> in <c>N</c> chunks + using <c>RegExp</c>. <c>split/3</c> is equivalent to + <c>regexp:split/2</c> with the exception that <c>N</c> + defines the maximum number of fields in <c>FieldList</c>.</p> - - <marker id="split_script_path"></marker> </desc> </func> <func> <name>split_script_path(RequestLine) -> Splitted</name> - <fsummary>Split a <c>RequestLine</c>in a file reference to an executable and a<c>QueryString</c>or a <c>PathInfo</c>string.</fsummary> + <fsummary>Splits a <c>RequestLine</c> in a file reference to an executable, + and a <c>QueryString</c> or a <c>PathInfo</c>string.</fsummary> <type> <v>RequestLine = string()</v> <v>Splitted = not_a_script | {Path, PathInfo, QueryString}</v> <v>Path = QueryString = PathInfo = string()</v> </type> <desc> - <marker id="split_script_path"></marker> <p><c>split_script_path/1</c> is equivalent to <c>split_path/1</c> with one exception. If the longest - possible path is not a regular, accessible and executable - file <c>not_a_script</c> is returned.</p> - - <marker id="split_path"></marker> + possible path is not a regular, accessible, and executable + file, then <c>not_a_script</c> is returned.</p> </desc> </func> <func> <name>split_path(RequestLine) -> {Path,QueryStringOrPathInfo}</name> - <fsummary>Split a <c>RequestLine</c>in a file reference and a <c>QueryString</c>or a<c>PathInfo</c>string.</fsummary> + <fsummary>Splits a <c>RequestLine</c> in a file reference, and a + <c>QueryString</c> or a <c>PathInfo</c> string.</fsummary> <type> <v>RequestLine = Path = QueryStringOrPathInfo = string()</v> </type> <desc> - <marker id="split_path"></marker> - <p><c>split_path/1</c> splits the <c>RequestLine</c> in a file - reference (<c>Path</c>) and a <c>QueryString</c> or a - <c>PathInfo</c> string as specified in RFC 2616. A - <c>QueryString</c> is isolated from the <c>Path</c> with a + <p><c>split_path/1</c> splits <c>RequestLine</c> in a file + reference (<c>Path</c>), and a <c>QueryString</c> or a + <c>PathInfo</c> string as specified in + <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>. + A <c>QueryString</c> is isolated from <c>Path</c> with a question mark (<c>?</c>) and <c>PathInfo</c> with a slash (/). In the case of a <c>QueryString</c>, everything before - the <c>?</c> is a <c>Path</c> and everything after a - <c>QueryString</c>. In the case of a <c>PathInfo</c> the + <c>?</c> is a <c>Path</c> and everything after <c>?</c> is a + <c>QueryString</c>. In the case of a <c>PathInfo</c>, <c>RequestLine</c> is scanned from left-to-right on the hunt for longest possible <c>Path</c> being a file or a directory. Everything after the longest possible <c>Path</c>, isolated with a <c>/</c>, is regarded as <c>PathInfo</c>. The resulting <c>Path</c> is decoded using <c>decode_hex/1</c> before delivery.</p> - - <marker id="strip"></marker> </desc> </func> <func> <name>strip(String) -> Stripped</name> - <fsummary>Returns String where the leading and trailing space and tabs has been removed.</fsummary> + <fsummary>Returns <c>String</c> where the leading and trailing space + tabs are removed.</fsummary> <type> <v>String = Stripped = string()</v> </type> <desc> - <marker id="strip"></marker> <p><c>strip/1</c> removes any leading or trailing linear white - space from the string. Linear white space should be read as + space from the string. Linear white space is to be read as horizontal tab or space.</p> - - <marker id="suffix"></marker> </desc> </func> <func> <name>suffix(FileName) -> Suffix</name> - <fsummary>Extract the file suffix from a given filename.</fsummary> + <fsummary>Extracts the file suffix from a given filename.</fsummary> <type> <v>FileName = Suffix = string()</v> </type> <desc> - <marker id="suffix"></marker> <p><c>suffix/1</c> is equivalent to - <c>filename:extension/1</c> with one exception, that is - <c>Suffix</c> is returned without a leading dot (<c>.</c>). </p> + <c>filename:extension/1</c> with the exception that + <c>Suffix</c> is returned without a leading dot (<c>.</c>).</p> </desc> </func> </funcs> <section> - <marker id="see_also"></marker> <title>SEE ALSO</title> <p><seealso marker="httpd">httpd(3)</seealso></p> </section> |