urlutil - URL parsing utility

SYNOPSIS

<urlutil $action [$arg ...]>

DESCRIPTION
The urlutil function provides URL and other network-related utility functions. The $action argument determines what it does:

• abs $absurl $relurl or absurl $absurl $relurl Makes URLs absolute (fully specified). The $absurl values are one or more absolute page URLs. The $relurl values are corresponding links - relative or not - from those page(s). For each $relurl value, its absolute value is returned, as if it were a link on that page. If there are fewer $absurl values than $relurl values, the last $absurl value is re-used.

• charsetconv $buf $from [$to] Converts text buffer $buf from charset $from to charset $to. The default for $to if unspecified or empty is the current <urlcp charsettxt> setting. Some character sets may require the use of an external charset converter (the default is iconv, see <urlcp charsetconverter> to change it), which is automatically executed when needed. Added in version 5.00.1090598954 20040723.

• filepath $u Takes $u, which must be a file:// URL, and returns the local file path that would be used to read the file, as determined by the current <urlcp fileroot> etc. settings.

• split $u $parts Splits a URL into one or more parts. The $u value is the URL to split. The $parts values are a list of the parts to return, in the same order, as values in $ret. The parts can be protocol, user, pass, host, port, path, type, anchor, or query.

• sslcertificate $pem tostring   Parses an SSL certificate string buffer $pem (in PEM format). The tostring sub-action returns a human-readable string version of the certificate, with subject, issuer, expiration etc. printed. This can be used to view a server certificate returned from <urlinfo sslservercertificate>.

Several actions take inet type arguments, which are IP network and/or host address specification strings of the form: N[.N[.N[.N]]]{/B|:IP}] where N is a decimal, octal or hexadecimal integer from 0 to 255, B is a decimal, octal or hexadecimal netmask integer from 0 to 32, and IP is an IP address netmask of the form N[.N[.N[.N]]]. If only x Ns are specified, the last N may be 5-x bytes in size instead of 1 byte. E.g. "1.2.65535" is legal (last N is 2 bytes), whereas "1.2.3.65535" is not. If no netmask (/B|:IP) is specified, the netmask will be calculated from standard class A/B/C/D/E rules, but it will be at least large enough to include all specified bytes of the IP. (Thus, to get the class A/B/C/D/E netmask of an IP address via inetnetmask, just give the first/highest N byte of the IP, as this is the sole determiner of class.) If an IP netmask is specified, only the largest contiguous set of most-significant 1 bits are used. Examples: "1.2.3.4" (netmask is /32 because 4 bytes given), "10" (netmask is /8 because it is a Class A address), "1.2.3.4/10", "67305985" (e.g. 4.3.2.1).

The inet actions were added in version 5.01.1112986377 20050408, and include the following (see also the SQL equivalents):

• inetabbrev $inet Returns the shortest representation of $inet. This will include all contiguous most-significant bytes of the network, non-zero bytes of the host, and a netmask. Other trailing 0 bytes of the IP may be trimmed. Empty string is returned on error.

• inetcanon $inet Returns canonical representation of $inet. This is dotted-decimal with all 4 bytes, and a /N netmask. Empty string is returned on error.

• inetnetwork $inet Returns 4-decimal IP address with the network bits of $inet, and the host bits set to 0. Empty string is returned on error.

• inethost $inet Returns 4-decimal IP address with the host bits of $inet, and the network bits set to 0. Empty string is returned on error.

• inetbroadcast $inet Returns 4-decimal IP broadcast address for $inet, i.e. with the network bits, and host bits set to 1. Empty string is returned on error.

• inetnetmask $inet Returns 4-decimal IP netmask for $inet, i.e. with the network bits set to 1, and host bits set to 0. Empty string is returned on error.

• inetnetmasklen $inet Returns integer netmask length of $inet. -1 is returned on error.

• inetcontains $inetA $inetB Returns 1 if $inetA contains $inetB, i.e. every address in $inetB occurs within the $inetA network. 0 is returned if not, or -1 on error.

• inetclass $inet Returns class of $inet, e.g. A, B, C, D, E or classless if a different netmask is used. Empty string is returned on error.

• inet2int $inet Returns integer representation of IP network/host bits of $inet (i.e. without netmask). Useful for compact storage of IPv4 address as integers instead of strings. -1 is returned on error (note that -1 may also be legitimately returned for an all-ones IP address, e.g. "255.255.255.255").

• int2inet $i Returns inet string for integer $i taken as an IP address. Since no netmask can be stored in the integer form of an IP address, the returned IP string will not have a netmask. Empty string is returned on error.

EXAMPLE

<urlutil abs "http://mysite.com/dir/page.html" "other.html">

The return value in $ret would be "http://mysite.com/dir/other.html".

CAVEATS
The urlutil function was added in version 3.0.957600000 20000505.

SEE ALSO
fetch, urlinfo