diff options
author | Joe Orton <joe@manyfish.uk> | 2021-03-06 17:46:59 +0000 |
---|---|---|
committer | Joe Orton <joe@manyfish.uk> | 2021-03-06 17:46:59 +0000 |
commit | 3bc3ff98d3f22543399ddd2f6b63ad834ffc2025 (patch) | |
tree | eb3400208a6364beae4e9129ec28e852aecc9b4d | |
parent | 12d9cfcfa50579c0853867aa3209616b8bc9bfa8 (diff) | |
download | neon-git-3bc3ff98d3f22543399ddd2f6b63ad834ffc2025.tar.gz |
* docs/: Add docs for ne_strhash, ne_vstrhash.
-rw-r--r-- | doc/manual.xml | 4 | ||||
-rw-r--r-- | doc/ref/hash.xml | 105 |
2 files changed, 108 insertions, 1 deletions
diff --git a/doc/manual.xml b/doc/manual.xml index 311cdac..9fdfee5 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -65,6 +65,7 @@ <!ENTITY refbufapp SYSTEM "ref/bufapp.xml"> <!ENTITY refbufdest SYSTEM "ref/bufdest.xml"> <!ENTITY refbufutil SYSTEM "ref/bufutil.xml"> +<!ENTITY refhash SYSTEM "ref/hash.xml"> <!ENTITY reftok SYSTEM "ref/tok.xml"> <!ENTITY refshave SYSTEM "ref/shave.xml"> <!ENTITY refvers SYSTEM "ref/vers.xml"> @@ -87,7 +88,7 @@ </personname> <email>neon@lists.manyfish.co.uk</email> </author> - <copyright><year>2001-2008</year><holder>Joe Orton</holder></copyright> + <copyright><year>2001-2021</year><holder>Joe Orton</holder></copyright> <legalnotice> @@ -170,6 +171,7 @@ ignoring the WebDAV support if desired.</para> &refbufutil; <!-- ne_buffer_clear --> &refbufcr; <!-- ne_buffer_create --> &refbufdest; <!-- ne_buffer_destroy --> + &refhash; <!-- ne_strhash --> &referr; <!-- ne_get_error --> &refgetst; <!-- ne_get_status --> &reffeat; <!-- ne_has_support --> diff --git a/doc/ref/hash.xml b/doc/ref/hash.xml new file mode 100644 index 0000000..7cfd00b --- /dev/null +++ b/doc/ref/hash.xml @@ -0,0 +1,105 @@ + <refentry id="refhash"> + + <refmeta> + <refentrytitle>ne_strhash</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname id="ne_strash">ne_strhash</refname> + <refpurpose>string hash interface</refpurpose> + </refnamediv> + + <refsynopsisdiv> + + <funcsynopsis> + <funcsynopsisinfo>#include <ne_string.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>char *<function>ne_strhash</function></funcdef> + <paramdef>unsigned int <parameter>flags</parameter></paramdef> + <paramdef><parameter>...</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>char *<function>ne_vstrhash</function></funcdef> + <paramdef>unsigned int <parameter>flags</parameter></paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>ne_strhash</function> and + <function>ne_vstrhash</function> functions can be used to + create hashes. The varargs argument list must be <type>const + char *</type> strings followed by a &null; terminator. The + <parameter>flags</parameter> argument must select exactly one + hash algorithm from the list below, which can be optionally + bitwise-ORed with one of the formatting option.</para> + + <refsect2> + <title>Hash algorithms</title> + + <para>The following hash algorithms are available: + <variablelist> + <varlistentry> + <term><constant>NE_HASH_MD5</constant></term> + <listitem><simpara>MD5</simpara></listitem> + </varlistentry> + <varlistentry> + <term><constant>NE_HASH_SHA256</constant></term> + <listitem><simpara>SHA-256 (SHA-2)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><constant>NE_HASH_SHA512</constant></term> + <listitem><simpara>SHA-512 (SHA-2)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><constant>NE_HASH_SHA256_256</constant></term> + <listitem><simpara>SHA-512/256 (SHA-2)</simpara></listitem> + </varlistentry> + </variablelist> + + </para></refsect2> + + <refsect2> + <title>Formatting options</title> + + <para>By default, the hash is returned as a hexadecimal + lower-case character string. The following formatting + options are available: + + <variablelist> + <varlistentry> + <term><constant>NE_HASH_COLON</constant></term> + <listitem><simpara>colon-separated hex pairs, e.g. <literal>"aa:11:22..."</literal> </simpara></listitem> + </varlistentry> + <varlistentry> + <term><constant>NE_HASH_SPACE</constant></term> + <listitem><simpara>space-separated hex pairs, e.g. <literal>"aa 11 22..."</literal></simpara></listitem> + </varlistentry> + </variablelist></para> + + </refsect2> + + </refsect1> + + <refsect1> + <title>Return value</title> + + <para>The return value is the ASCII hexadecimal representation + of the hash as a malloc-allocated, NUL-terminated string, or + &null; if the hash cannot be created. The string length is + determined by the hash algorithm (and formatting options + used). Support for hash algorithms is specific to the SSL + toolkit with which &neon; is compiled. Some systems will + further restrict hash availability at runtime, e.g. due to + FIPS mode.</para> + + </refsect1> + + </refentry> |