csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/docbook2/omemory.xml

<chapter id='omemory'>
	<title>
		Class omemory
		</title>
	<section id="omemory-class" >
		<title>
			Introduction
			</title>
		<para>
			This class is a memory manipulation Easter basket. Class methods copy,  reorder, increment, decrement, encode and decode  variable-length memory regions on a byte level.    
			</para>
		<para>
			It is declared in <ulink url='omemory.hpp.html'>omemory.hpp</ulink> and implemented in <ulink url='omemory.cpp.html'>omemory.cpp</ulink>.
			</para>
		<section id="omemory-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="omemory-dependence">
			<title>
				Dependencies
				</title>
			<para>
				This class depends on static class <link linkend='oerror'>oerror</link> to report errors.
				</para>
			<para>
				This class needs header file <filename>stdint.h</filename> for the definition of <acronym>POSIX</acronym> data types <varname>uint8_t</varname>, <varname>uint16_t</varname> and <varname>uint32_t</varname>. An abridged version of this file is provided in <ulink url='stdint.h.html'>VisualStudioNET/include/stdint.h</ulink> for systems that do not have it.
				</para>
			</section>
	
		</section>
	<section id="omemory-methods">
		<title>
			Methods
			</title>
		<section id="omemory-bindecode">
			<title>
				omemory::bindecode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>bindecode</function></funcdef>
    					<paramdef>void  * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>char const <parameter>buffer</parameter> []</paramdef>
   					<paramdef>size_t <parameter>length</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Decode a <varname>memory</varname> region as a string of <acronym>ASCII</acronym> binary digits. Convert <varname>memory</varname> until the <varname>buffer</varname> or <varname>memory</varname> exhausts and return the string length. Allow <constant>9</constant> <varname>buffer</varname> characters for each <varname>memory</varname> byte to ensure that the entire region is decoded. If <varname>buffer</varname> is less than <constant>9</constant> characters nothing will be decoded. The number of bytes decoded will be the lesser of <varname>extent</varname> or <varname>length</varname> divided by <constant>9</constant>.  		
				</para>
			</section>
		<section id="omemory-binout">
			<title>
				omemory::binout
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>binout</function></funcdef>
    					<paramdef>void const * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef>char <parameter>c</parameter></paramdef>
    					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a <varname>memory</varname> region as a series of binary octets separated by character <varname>c</varname>. Normally, character <varname>c</varname> will be <constant>BIN_EXTENDER</constant>, as defined in file <ulink url="number.h.html">onumber.hpp</ulink>, but it could be any character value.  For example, specifying <varname>c</varname> as <constant>'-'</constant> and <varname>extent</varname> as <constant>4</constant> would produce output looking something like <computeroutput>"10101010-1111111-00000000-11001100"</computeroutput> where each octet is expressed as a binary integer. A typical use might be to print a <acronym>register</acronym> in readable format. 
				</para>
			</section>
		<section id="omemory-binstring">
			<title>
				omemory::binstring
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char * <function>binstring</function></funcdef>
    					<paramdef>char <parameter>buffer</parameter> []</paramdef>
					<paramdef>size_t <parameter>length</parameter></paramdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
					<paramdef>size_t <parameter>extent</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Convert a <varname>memory</varname> region to a <constant>NUL</constant> terminated string if <acronym>ASCII</acronym> binary digits and return the string address. This method is similar to method <link linkend='omemory-bindecode'>bindecode</link> but the argument order in different and it returns the string address instead of the number of characters decoded. 
				</para>
			</section>
		<section id="omemory-checksum16">
			<title>
				omemory::checksum16
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint16_t <function>checksum16</function></funcdef>
    					<paramdef>const void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>uint16_t <parameter>checksum</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
				<para>
					Return the 16-bit checksum of a <varname>memory</varname> region. The checksum is the one's complement of the XOR of all 16-bit words in the region. Argument <varname>extent</varname> is the region size in bytes and is rounded down to the neares multiple of two bytes. This method will return the computed checksum when argument <varname>checksum</varname> is <constant>0</constant> and return <constant>0</constant> when argument <varname>checksum</varname> matches the computed checksum. 								
				</para>
			</section>
		<section id="omemory-checksum32">
			<title>
				omemory::checksum32
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint32_t <function>checksum32</function></funcdef>
    					<paramdef>const void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>uint32_t <parameter>checksum</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
				<para>
					Return the 32-bit checksum of a <varname>memory</varname> region. The checksum is the one's complement of the XOR of all 32-bit words in the region. Argument <varname>length</varname> is the region size in bytes and is rounded down to the nearest multiple of four bytes. This method will return the computed checksum when argument <varname>checksum</varname> is <constant>0</constant> and return <constant>0</constant> when argument <varname>checksum</varname> matches the computed checksum. A typical use is <filename>.pib</filename> and <filename>.nvm</filename> file checksum computation or validation. 					
				</para>
			</section>
		<section id="omemory-decdecode">
			<title>
				omemory::decdecode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>decdecode</function></funcdef>
    					<paramdef>void  * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>char const <parameter>buffer</parameter> []</paramdef>
   					<paramdef>size_t <parameter>length</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Decode a <varname>memory</varname> region as a <constant>NUL</constant> terminated string of <acronym>ASCII</acronym> decimal digits. Convert <varname>memory</varname> until the <varname>buffer</varname> or <varname>memory</varname> exhausts then return the string length. Allow <constant>4</constant> <varname>buffer</varname> characters for each <varname>memory</varname> byte to ensure that the entire region is decoded. If <varname>buffer</varname> is less than <constant>4</constant> characters nothing will be decoded. The number of bytes decoded will be the lesser of <varname>extent</varname> or <varname>length</varname> divided by <constant>4</constant>.  		
 		
				</para>
			</section>
		<section id="omemory-decode">
			<title>
				omemory::decode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void const * <function>decode</function></funcdef>
    					<paramdef>void const * <parameter>memory</parameter></paramdef>
     					<paramdef>void * <parameter>target</parameter></paramdef>
   					<paramdef>size_t <parameter>extent</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Copy a <varname>memory</varname> region to some <varname>target</varname> location and return the address of the next uncopied memory byte. The <varname>memory</varname> address is incremented by the region <varname>extent</varname> and returned as the method value. This method is similar to the <link linkend='omemory-encode'>encode</link> method except for the direction of copy. This method may be used to sequentially unpack buffer fields into diverse memory locations.
				</para>
			</section>
		<section id="omemory-decstring">
			<title>
				omemory::decstring
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char * <function>decstring</function></funcdef>
    					<paramdef>char <parameter>buffer</parameter> []</paramdef>
					<paramdef>size_t <parameter>length</parameter></paramdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
					<paramdef>size_t <parameter>extent</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Convert a <varname>memory</varname> region to a <constant>NUL</constant> terminated string and return the string address. This method is similar to method <link linkend='omemory-decdecode'>decdecode</link> but the arguments are in different order and it returns the string address instead of the number of characters decoded. 
				</para>
			</section>
		<section id="omemory-decout">
			<title>
				omemory::decout
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>decout</function></funcdef>
    					<paramdef>void const * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef>char <parameter>c</parameter></paramdef>
    					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a <varname>memory</varname> region as a series of decimal octets separated by character <constant>c</constant>. Normally, character <constant>c</constant> will be <constant>DEC_EXTENDER</constant>, defined in file <ulink url="onumber.hpp.html">onumber.hpp</ulink>, but it could be any character value.  For example, specifying <varname>c</varname> as <constant>'.'</constant> and <varname>extent</varname> as <constant>4</constant> would produce output looking something like <computeroutput>"192.168.099.001"</computeroutput> where each octet is expressed as a decimal integer. A typical use might be to print an <acronym>IP</acronym> or <acronym>MAC</acronym> address in readable format. 
				</para>
			</section>
		<section id="omemory-encode">
			<title>
				omemory::encode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>encode</function></funcdef>
    					<paramdef>void * <parameter>memory</parameter></paramdef>
     					<paramdef>void const * <parameter>source</parameter></paramdef>
   					<paramdef>size_t <parameter>extent</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Copy a <varname>memory</varname> region from some <varname>source</varname> location and return the address of the next uncopied memory byte. The <varname>memory</varname> address is incremented by the region <varname>extent</varname> and returned as the method value. This method is similar to the <link linkend='omemory-decode'>decode</link> method except for the direction of copy. This method can be used to sequentially pack buffer fields with data from diverse memory locations.
				</para>
			</section>
		<section id="omemory-endian">
			<title>
				omemory::endian
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>endian</function></funcdef>
    					<paramdef>void  * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Reverse the byte order of a <varname>memory</varname> region. It is a variable-length version of methods like <function>__bswap_16</function>, <function>__bswap_32</function> and <function>__bswap_64</function>. 
				</para>
			</section>
		<section id="omemory-hexdecode">
			<title>
				omemory::hexdecode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>hexdecode</function></funcdef>
    					<paramdef>void  * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>char const <parameter>buffer</parameter> []</paramdef>
   					<paramdef>size_t <parameter>length</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Decode a <varname>memory</varname> region as a string of <acronym>ASCII</acronym> hexadecimal digits. Convert memory until the <varname>buffer</varname> or <varname>memory</varname> exhausts and return the string length. Allow <constant>3</constant> <varname>buffer</varname> characters for each <varname>memory</varname> byte to ensure that the entire region is decoded. If <varname>buffer</varname> is less than <constant>3</constant> characters nothing will be decoded. The number of bytes decoded will be the lesser of <varname>extent</varname> or <varname>length</varname> divided by <constant>3</constant>.  		
 		
				</para>
			</section>
		<section id="omemory-hexdump">
			<title>
				omemory::hexdump
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>void <function>hexdump</function></funcdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
					<paramdef>size_t <parameter>offset</parameter></paramdef>
					<paramdef>size_t <parameter>extent</parameter></paramdef>
					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a full or partial <varname>memory</varname> region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argumen <varname>extent</varname> is the region size in bytes. Argument <varname>offset</varname> is the starting display location. Locations <varname>memory</varname> [<varname>offset</varname>] up to <varname>memory</varname> [<varname>extent</varname>] are displayed, allowing a partial dump of the entire region. The entire region will be displayed when argument <varname>offset</varname> is <constant>0</constant>.		
				</para>
			<para>
				This method is similar to but different from method <link linkend='omemory-hexview'>hexview</link> .
				</para>
			</section>
		<section id="omemory-hexencode">
			<title>
				omemory::hexencode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>hexencode</function></funcdef>
    					<paramdef>void const * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
   					<paramdef>char const * <parameter>string</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Encode a <varname>memory</varname> region with the binary equivalent of an <acronym>ASCII</acronym> hexadecimal string. Return the number of bytes encoded or <constant>0</constant> on error. The value of <varname>errno</varname> is set to <constant>EINVAL</constant> if the number of bytes encoded is less than <varname>extent</varname> or the entire string cannot be converted due to illegal digits or excessive digits. Ignore optional <constant>HEX_EXTENDER</constant> characters separating octets in argument <varname>string</varname>. Constant <constant>HEX_EXTENDER</constant> is defined in file <ulink url='onumber.hpp.html'>onumber.hpp</ulink>. 
				</para>
			</section>
		<section id="omemory-hexin">
			<title>
				omemory::hexload
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>ssize_t <function>hexload</function></funcdef>
    					<paramdef>void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				This method is similar to <link linkend="omemory-hexencode">hexencode</link> but it reads from file, instead of a string and ignores non-hexadecimal text and comments within the input stream. Incoming text is binary encoded and written to the specified <varname>memory</varname> region. The actual number of bytes encoded is returned or <constant>-1</constant> on error. 
				</para>
			</section>
		<section id="omemory-hexout">
			<title>
				omemory::hexout
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>hexout</function></funcdef>
    					<paramdef>void const * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef>char <parameter>c</parameter></paramdef>
    					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a <varname>memory</varname> region as a series of decimal octets separated by character <constant>c</constant>. Normally, character <constant>c</constant> will be <constant>HEX_EXTENDER</constant>, defined in file <ulink url="onumber.hpp.html">onumber.hpp</ulink>, but it could be any character value.  For example, specifying <varname>c</varname> as <constant>':'</constant> and <varname>extent</varname> as <constant>6</constant> would produce output looking something like <computeroutput>"00:B0:52:DA:DA:01"</computeroutput> where each octet is expressed as a hexadecimal integer. A typical use might be to print a <acronym>MAC</acronym> or <acronym>Ethernet</acronym> address in readable format. 
				</para>
			</section>
		<section id="omemory-hexstring">
			<title>
				omemory::hexstring
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char * <function>hexstring</function></funcdef>
    					<paramdef>char <parameter>buffer</parameter> []</paramdef>
					<paramdef>size_t <parameter>length</parameter></paramdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
					<paramdef>size_t <parameter>extent</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Convert a <varname>memory</varname> region to a <constant>NUL</constant> terminated string of <acronym>ASCII</acronym> hexadecimal digits and return the string address. This method is similar to method <link linkend='omemory-hexdecode'>hexdecode</link> but the arguments are in different order and it returns the string address instead of the number of characters decoded. 
				</para>
			</section>
		<section id="omemory-hexview">
			<title>
				omemory::hexview
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>void <function>hexview</function></funcdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
					<paramdef>size_t <parameter>offset</parameter></paramdef>
					<paramdef>size_t <parameter>extent</parameter></paramdef>
					<paramdef>FILE * <parameter>fp</parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a partial <varname>memory</varname> region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argument <varname>memory</varname> contains part of a larger memory region, much like a file window. Argument <varname>extent</varname> is the window length. Argument <varname>offset</varname> is the relative offset of the window within the region. Locations <constant>memory [0]</constant> up to <constant>memory [extent]</constant> are displayed as a partial dump, providing a window into the region.		
				</para>
			<para>
				This method is similar to but different from method <link linkend='omemory-hexdump'>hexdump</link>.
				</para>
			</section>
		<section id="omemory-memdecr">
			<title>
				omemory::memdecr
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>memdecr</function></funcdef>
    					<paramdef>void  * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Decrement a multi-byte <varname>memory</varname> region. Return <constant>0</constant> on success or <constant>-1</constant> if all bytes have decremented to <constant>0x00</constant>. For example, <computeroutput>{ 0xFF, 0xFF, 0xFF }</computeroutput> decrements to <computeroutput>{ 0xFF, 0xFF, 0xFE }</computeroutput> and <computeroutput>{ 0xFF, 0x00, 0x00 }</computeroutput> decrements to <computeroutput>{ 0xFE, 0xFF, 0xFF }</computeroutput>. A typical use is to iterate through a range if <acronym>IP</acronym> or <acronym>MAC</acronym> address values. 
				</para>
			</section>
		<section id="omemory-memincr">
			<title>
				omemory::memincr
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>memincr</function></funcdef>
    					<paramdef>void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Increment a multi-byte <varname>memory</varname> region. Return <constant>0</constant> on success or <constant>-1</constant> once all bytes have been incremented to <constant>0xFF</constant>. For example <computeroutput>{ 0x00, 0x00, 0x00 }</computeroutput> increments to <computeroutput>{ 0x00, 0x00, 0x01 }</computeroutput> and <computeroutput>{ 0x00, 0xFF, 0xFF }</computeroutput> increments to <computeroutput>{ 0x01, 0x00, 0x00 }</computeroutput>. A typical use is to iterate through a range of <acronym>IP</acronym> or <acronym>MAC</acronym> address values. 
				</para>
			</section>
		<section id="omemory-memtext">
			<title>
				omemory::memtext
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>memtext</function></funcdef>
    					<paramdef>char const * <parameter>string</parameter></paramdef>
    					<paramdef>char <parameter>buffer</parameter> []</paramdef>
    					<paramdef>size_t <parameter>length</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Copy a variable-length <varname>string</varname> to a fixed-length <varname>buffer</varname> ensuring that the <varname>buffer</varname> is <constant>NUL</constant> terminated. The <varname>string</varname> is right truncated on overflow and the <varname>buffer</varname> is right padded with <constant>NUL</constant> characters on undeflow. For all non-zero lengths, <varname>buffer</varname>[<varname>length</varname>-<constant>1</constant>] will be <constant>NUL</constant>. This method is an alternative to standard library function <varname>strncpy</varname> which does not terminate the destination string on overflow or pad the buffer on underflow.
				</para>
			</section>
		<section id="omemory-serial">
			<title>
				omemory::serial
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>serial</function></funcdef>
    					<paramdef>void * <parameter>buffer</parameter></paramdef>
    					<paramdef>size_t <parameter>length</parameter></paramdef>
    					<paramdef>unsigned <parameter>value</parameter></paramdef>
   					<paramdef>unsigned <parameter>radix</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Convert unsigned integer <varname>value</varname> to a <constant>NUL</constant> terminated numeric string of specified <varname>length</varname> and <varname>radix</varname> and return the string address. The string is stored in a user allocated buffer <varname>buffer</varname> and is left truncated or left padded with <constant>'0'</constant> to match the <varname>length</varname>. This method is similar to <link linkend='omemory-binstring'>binstring</link>, <link linkend='omemory-decstring'>decstring</link> and <link linkend='omemory-hexstring'>hexstring</link> but the entire buffer is filled with digits plus the terminator and no seperators are used. 
				</para>
			</section>
		<section id="omemory-strdecr">
			<title>
				omemory::strdecr
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>strdecr</function></funcdef>
    					<paramdef>void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef> byte <parameter>min</parameter></paramdef>
    					<paramdef> byte <parameter>max</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Decrement a multi-byte <varname>memory</varname> region using only ASCII character values in the range <varname>min</varname> through <varname>max</varname>. Return <constant>0</constant> on success or <constant>-1</constant> once all characters have been decremented to the value of argument <varname>min</varname>. For example,  if argument <varname>min</varname> is <constant>'A'</constant> and argument <varname>max</varname> is <constant>'Z'</constant> then <computeroutput>{ 'A', 'B', 'C' }</computeroutput> decrements to <computeroutput>{ 'A', 'B', 'B' }</computeroutput> and <computeroutput>{ 'B', 'Z', 'Z' }</computeroutput> decrements to <computeroutput>{ 'A', 'A', 'A' }</computeroutput>. A typical use is to generate a sequence of distinct character strings to seed encryption key methods.					</para>
			</section>
		<section id="omemory-strincr">
			<title>
				omemory::strincr
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>signed <function>strincr</function></funcdef>
    					<paramdef>void * <parameter>memory</parameter></paramdef>
    					<paramdef>size_t <parameter>extent</parameter></paramdef>
    					<paramdef> byte <parameter>min</parameter></paramdef>
    					<paramdef> byte <parameter>max</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Increment a multi-byte <varname>memory</varname> region using only ASCII character values in the range <varname>min</varname> through <varname>max</varname>. Return <constant>0</constant> on success or <constant>-1</constant> once all characters have been incremented to the value of argument <varname>max</varname>.  For example,  if argument <varname>min</varname> is <constant>'A'</constant> and argument <varname>max</varname> is <constant>'Z'</constant> then <computeroutput>{ 'A', 'B', 'C' }</computeroutput> increments to <computeroutput>{ 'A', 'B', 'D' }</computeroutput> and <computeroutput>{ 'A', 'Z', 'Z' }</computeroutput> increments to <computeroutput>{ 'B', 'A', 'A' }</computeroutput>. A typical use is to generate a sequence of distinct character strings to seed encryption key methods. 					</para>
			</section>
		<section id="omemory-swap">
			<title>
				omemory::swap
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void <function>swap</function></funcdef>
    					<paramdef>void *</paramdef>
    					<paramdef>void *</paramdef>
    					<paramdef>size_t <parameter>length</parameter></paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Exchange the contents of two memory regions of equal <varname>length</varname> in bytes. No provision is made for memory overlap. This method may be used to sort a list of multi-byte entries or exchange the source and destination addresses in an Ethernet frame. 
				</para>
			</section>
		</section>
	</chapter>