The Atheros Open Powerline Toolkit includes many functions that have application outside the Open Powerline Toolkit. They are distributed with the toolkit but may also appear in other Atheros applications or third party packages. Consequently, we describe them separately and store them in separate folders.

The functions in this group have general application beyond the Open Powerline Toolkit. In some cases, these functions may appear in other Atheros or Open Source software packages. In a few cases, the Toolkit may include complementary or supplementary support functions but only use one or two of them. For example, functions memincr and memdecr are both included but memdecr is not used.

void alert const char *format ... This function is similar to function printf but messages are prefixed with the program name and appear on stderr instead of stdout. It is equivalent to calling function error with argument exitcode set to 0 and argument errno set to 0. A typical use is to print progress messages. The function is declared in error.h and defined in alert.c.

void error intexitcode errno_t number const char * format ... This function works like printf except that printed messages appear on stderr and are prefixed with the program name and error information. If argument errno is non-zero then messages are prefixed with the system error description. If argument exitcode is non-zero then function error exits the program with value exitcode after printing the message and does not return to the caller. The function is declared in error.h and defined in error.c.

bool checkfilename const char *filename Return logical true if the filename argument contains only letters, digits, slashes, periods, underscores and hyphens. This function can be used to detect cases where a user accidentally entered an Ethernet address in place of a filename on the command line. Ethernet address strings are, as it happens, also valid filenames. The function is declared in files.h and defined in checkfilename.c.

const char * filepart const char * pathname Return the address of the filename portion of a pathname string. The filename portion is everything after the rightmost path separator. If a path separator is not present then the address of the pathname string is returned. This function is similar to the POSIX basename function but it returns an empty string whenever the rightmost character is a path separator. The path separator can be either slash ('/') or backslash ('\\'). The function is declared in files.h and defined in filepart.c.

size_t strfbits char buffer [] size_t length const char *operands [] const char *operator unsigned flagword Encode a buffer with an enumerated list of the operands associated with the corresponding bits in flagword. separate enumerated operands with an operator string. For example, given const char *operands [] = { "loop", "wait", "busy" } and unsigned flagword = 0x05 then strfbits (buffer, length, operands, "|", flagword) would encode buffer with "loop|busy". Observe that each bit set in flagword appears in buffer as the corresponding string from operands. A typical application for this function is the enumeration of flagword states. The function is declared in tools.h and defined in strfbits.c.

int getoptv int argc const char * argv [] const char * optv [] A custom version of the POSIX function getopt. It supports standard global variables optind, opterr, optopt and optarg and the non-standard variable optmin. It extracts the program name from argv[0] and posts it for use by functions alert, error and other functions using the global string pointer program_name. Options -? and --help both display program information on stdout. Options -! and --version both display program version information on stdout. String vector optv includes both the standard argument optstring and usage text found in many programs. The function is declared in getoptv.h and defined in getoptv.c.

void bytespec const char * string byte memory [] size_t extent Encode a memory region with the binary equivalent of a fixed-length hexadecimal string. Print an error message on stderr and exit the program with status 1 if a syntax error occurs or the number of octets does not equal extent. Hexadecimal octets may be separated by colons for readability but colons are not required. Empty octets are illegal. This function is typically used to enter fixed-length data, like hardware addresses and encryption keys, on the command line. The function is declared in memory.h and defined in bytespec.c.

unint32_t checksum32 const uint32_t memory [] size_t length uint32_t checksum Return the 32 bit checksum of a memory region. The checksum is the one's complement of the XOR of all 32 bit words in the region. Argument length is the region extent in 32 bit words. Argument checksum is the reference checksum. When the checksum argument is 0, the function value will be the computed checksum. When the checksum argument is the computed checksum, the function value will be 0 such that any other value indicates a checksum error. A typical use is to validate PIB and NVM files or compute new checksums when these files are created or modified. The function is declared in memory.h and defined in checksum32.c.

unint32_t checksum_32 const void * memory size_t extent uint32_t checksum Return the 32 bit checksum of a memory region. The checksum is the one's complement of the XOR of all 32 bit words in the region. The region extent is specified in bytes but it will be rounded down to the nearest multiple of 4 bytes. Argument checksum is the reference checksum. The function will return the computed checksum when argument checksum is 0 and will return 0 if argument checksum equals the computed checksum. A typical use is to validate PIB and NVM files or compute new checksums when these files are created or modified. The function is declared in memory.h and defined in checksum_32.c. This function is similar to function checksum32 however there is no need to cast memory to uint32_t and there is no need to round extent down to a multiple of 4 bytes before calling the function because both operations are performed internally. Also, there is no unecessary endian manipulation of the checksum.

void decout const byte memory [] size_t length char c FILE *fp Print a memory region as a series of decimal octets separated by character c. Normally, character c will be DEC_EXTENDER, defined in file number.h, but it could be any character value. For example, specifying c as '.' and length as 4 would produce output looking something like "192.168.099.001" where each octet is expressed as a decimal integer. A typical use might be to print an IP or MAC address in readable format. The function is declared in memory.h and defined in decout.c.

void endian void * memory size_t extent Reverse the byte order of a memory region. It is a variable length version of functions like _bswap_16, _bswap_32 and _bswap_64. The function is declared in memory.h and defined in endian.c.

signed hexdecode byte memory [] size_t extent const char buffer [] size_t length Decode a memory region as a string of ASCII hexadecimal digits. Convert memory until the buffer or memory exhausts and return the string length. Allow three (3) string characters for each memory byte to be decoded. The number of bytes decoded will be the lesser of argument length divided by 3 or argument extent. The function is declared in memory.h and defined in hexdecode.c.

void hexdump const void * memory size_t offset size_t extent FILE * fp Print a full or partial memory region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argument memory contains some memory region. Argument extent is the region length. Argument offset is the starting display location. Locations memory [offset] up to memory [extent] are displayed, allowing a partial dump of the memory region. An offset of 0 will display the entire region. The function is declared in memory.h and defined in hexdump.c. This function is similar to but different from function hexview .

signed hexencode byte memory [] size_t extent const char * string Encode a memory region with the binary equivalent of an ASCII hexadecimal string. Return the number of bytes encoded or 0 on error. The value of errno is set to EINVAL if the number of bytes encoded is less than extent or the entire string cannot be converted due to illegal digits or excessive digits. Ignore optional HEX_EXTENDER characters separating octets in argument string. Constant HEX_EXTENDER is defined in file number.h. The function is declared in memory.h and defined in hexencode.c.

void hexin const byte memory [] size_t extent FILE *fp This function is similar to hexencode but it reads from file, instead of a string, and ignores any non-hexadecimal text and comments embedded within the input stream. Incoming text is binary encoded and written to the specified memory region. Reading terminates on the next occurance of a semicolon or end of file. The actual number of bytes encoded is returned. The function is declared in memory.h and defined in hexin.c.

void hexout const byte memory [] size_t length char c FILE *fp Print a memory region as a series of decimal octets separated by character c. Normally, character c will be HEX_EXTENDER, defined in file number.h, but it could be any character value. For example, specifying c as ':' and length as 6 would produce output looking something like "00:B0:52:DA:DA:01" where each octet is expressed as a hexadecimal integer. A typical use might be to print a MAC or Ethernet address in readable format. The function is declared in memory.h and defined in hexout.c.

char * hexstring char buffer [] size_t length const byte memory [] size_t extent Convert a memory region to a NUL terminated string and return the string address. This function is identical to function hexdecode but it return the string address instead of the number of characters decoded. The function is declared in memory.h and defined in hexstring.c.

void hexview const void * memory size_t offset size_t extent FILE * fp Print a partial memory region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argument memory contains part of a larger memory region, much like a file window. Argument extent is the window length. Argument offset is the relative offset of the window within the region. Locations memory [0] up to memory [extent] are displayed as a partial dump, providing a window into the region. The function is declared in memory.h and defined in hexview.c. This function is similar to but different from function hexdump.

size_t ipv4spec const char * string byte memory [] Encode a 4-byte memory region with an IPv4 dotted-decimal string and return the number of bytes encoded. Terminate the program with an error message and exitcode of 1 on conversion error. The value returned by this function is always 4 and memory is always encoded in network byte order. This function is typically used to convert IPv4 strings entered as command line arguments. The function is declared in memory.h and defined in ipv4spec.c. Dotted-decimal format consists of decimal values in the range 0 through 255. Each value represents one octet or 8-bit value. IPv4 addresses require 4 such values separated by one decimal point. This function permits empty octets and leading zeros within octets. For example, ... is equivalent to 0.0.0.0 and 127.0.000.001 is equivalent to 127.0.0.1. The second example will encode memory as follows { 0x7F, 0x00, 0x00, 0x01 } which is in network byte order, or big endian.

size_t ipv6spec const char * string byte memory [] Encode a 16-byte memory region with an IPv6 colon-separated hexadecimal quartet string and return the number of bytes encoded. Terminate the program with an error message and exitcode of 1 on conversion error. The value returned by this function is always 16 and memory is always encoded in network byte order. This function is typically used to convert IPv6 strings entered as command line arguments. The function is declared in memory.h and defined in ipv6spec.c. Colon-separated hexadecimal quartet notation consists of hexadecimal values in the range 0 through FFFF. Each value represents a quartet or a 32-bit value. IPv6 addresses require 8 quartets separated by one colon. By convention, an empty quartet expands with enough zeros to right-justify the remainder of the address. This function permits multiple empty quartets and leading zeros within quartets. When multiple empty quartets appear, only the right-most occurance expands to zeros. For example, AA12::BB34::CC56::DD78 is equivalent to AA12:0000:BB34:0000:CC56:0000:0000:DD78 because only the right-most empty field expands. This will encode memory as follows { 0xAA, 0x12, 0x00, 0x00, 0xBB, 0x34, 0x00, 0x00, 0xCC, 0x56, 0x00, 0x00, 0x00, 0x00, 0xDD, 0x78 } which is in network byte order, or big-endian.

signed memdecr byte memory [] size_t length Decrement a multi-byte memory region. Return 0 on success or -1 if all bytes have decremented to 0x00. For example, { 0xFF, 0xFF, 0xFF } decrements to { 0xFF, 0xFF, 0xFE } and { 0xFF, 0x00, 0x00 } decrements to { 0xFE, 0xFF, 0xFF }. A typical use is to iterate through a range if IP or MAC address values. The function is declared in memory.h and defined in memdecr.c.

signed memincr byte memory [] size_t length Increment a multi-byte memory region. Return 0 on success or -1 once all bytes have been incremented to 0xFF. For example { 0x00, 0x00, 0x00 } increments to { 0x00, 0x00, 0x01 } and { 0x00, 0xFF, 0xFF } increments to { 0x01, 0x00, 0x00 }. A typical use is to iterate through a range of IP or MAC address values. The function is declared in memory.h and defined in memincr.c.

void memswap void * buffer1 void * buffer2 size_t length Exchange the contents of one buffer with that of another. No provision is made for buffer overlap. No value is returned. A typical use might be to exchange source and destination addresses in an ethernet packet. The function is declared in memory.h and defined in memswap.c.

signed strdecr byte memory [] size_t length byte min byte max Decrement a multi-byte memory region using only ASCII character values in the range min through max. Return 0 on success or -1 once all characters have been decremented to the value of argument min. For example, if argument min is 'A' and argument max is 'Z' then { 'A', 'B', 'C' } decrements to { 'A', 'B', 'B' } and { 'B', 'Z', 'Z' } decrements to { 'A', 'A', 'A' }. A typical use is to generate a sequence of distinct character strings to seed encryption key functions. The function is declared in memory.h and defined in strdecr.c.

signed strincr byte memory [] size_t length byte min byte max Increment a multi-byte memory region using only ASCII character values in the range min through max. Return 0 on success or -1 once all characters have been incremented to the value of argument max. For example, if argument min is 'A' and argument max is 'Z' then { 'A', 'B', 'C' } increments to { 'A', 'B', 'D' } and { 'A', 'Z', 'Z' } increments to { 'B', 'A', 'A' }. A typical use is to generate a sequence of distinct character strings to seed encryption key functions. The function is declared in memory.h and defined in strincr.c.

unsigned todigit unsigned c Return the integer value of character c interpreted as digit in the base 36 number system. It is called by many encode functions to support number base conversion. If the value of c is '0' through '9' then integer 0 through 9 is returned. If the value of c is 'A' through 'Z' or 'a' through 'z' then integer 10 through 35 is returned. The function is declared in number.h and defined in todogit.c.

uint64_t basespec const char * string unsigned base unsigned size Return the unsigned integer equivalent of a numeric string. Print an error message on stderr and exit the program with status 1 if a syntax error occurs or the result exceeds the capacity of the requested integer size in bytes. If base is 0, numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with "0x" and binary values start with "0b". When base is non-zero, the notation in string must conform to the corresponding number base rules. Applications should cast the return value to the appropriate data type prevent loss-of-data compiler warnings. This function is typically used to convert and length-check integers entered as command line arguments. The function is declared in number.h and defined in basespec.c. Like function uintspec, this function both converts and range checks numeric string values, but the minimum and maximum value are implicit in the size of the integer. The minimum value is always 0 and the maximum value can be computed by ((1 << size << 3) - 1).

void dataspec const char * string byte memory [] size_t extent Encode a memory region with the binary equivalent of a variable-length hexadecimal string. Print an error message on stderr and exit the program with the status 1 if a syntax error occurs or the number of octets exceeds extent. The number of octets may, however, be less than extent. Unlike function bytespec, hexadecimal octets may not be separated by colons. This function is typically used to enter variable-length data from the command line. The function is declared in memory.h and defined in dataspec.c.

uint64_t uintspec const char * string uint64_t minimum uint64_t maximum Return the unsigned integer equivalent of a numeric string. Print an error message on stderr and exit the program with the value 1 when a syntax error occurs or the result exceeds the specified minimum or maximum value. Numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with "0x" and binary values start with "0b". Applications should cast the return value to the appropriate data type to avoid loss-of-data warnings on some compilers. This function is typically used to convert and range-check integer values entered as command-line arguments. The function is declared in number.h and defined in uintspec.c.

void assist const char * name const char * type const struct _code_ list [] size_t size FILE * fp Show why a symbolic name was rejected by function lookup or similar functions. Argument type contains a title for the class of names stored in list. This function prints an error message on file stream fp showing the program name, the type string, the symbolic name and all names stored in the list. The _code_ structure is declared in types.h. The function is declared in symbol.h and defined in assist.c. Function expect is used to print list names.

void expect const struct _code_ list [] size_t size FILE * fp Display all names in argument list on file stream fp. This function is called by runction assist to print the list of symbolic names but other function may have use for it. The _code_ structure is declared in types.h. The function is declared in symbol.h and defined in expect.c.

signed lookup const char * name const struct _code_ list [] size_t size Lookup a symbolic name in a list and return an associated integer or -1 if the name does not appear in the list. A typical use is the translation of symbolic command line arguments to integer codes. For example, some Toolkit programs assign symbolic names to field codes so that users can enter names instead of numbers. This approach becomes more useful as the number of permitted codes increases. The _code_ structure is declared in types.h. The function is declared in symbol.h and defined in lookup.c. This function offers two benefits: 1) multiple symbols can translate to one code and 2) names can be changed or new names added without affecting program logic. This function is similar to but different from function synonym which returns a character string instead of an integer.

const char * synonym const char * string const struct _term_ list [] size_t size Lookup a symbolic name in a list and return an associated string or the original string if the name does not appear in the list. A typical use is the translation of symbolic command line arguments to their equivalent numeric strings before encoding them. For example, many Toolkit programs convert the command line argument local to 00:B0:52:00:00:01 before encoding the device MAC address. The _term_ structure is declared in types.h. The function is declared in symbol.h and defined in synonym.c. This function is similar to but different from function lookup which returns an integer instead of a character string.

const char * typename const struct _type_ list [] size_t size type_t type const char * name Return the name associated with a message type by searching a list arranged in ascending order by message type. Return argument name as the function value if the message type is not present in the list. Data types struct _type_ and type_t are defined in file types.h. A typical use might be to return the name of message based on the message type. The function is declared in tools.h and defined in typename.c.

void putoptv const char * optv [] Print program information on stdout. Program information is stored in string vector optv. String indexes are defined in file putoptv.h. String optv[0] is the POSIX standard argument optstring. This function is called by function getoptv whenever option -? or --help is detected on the command line. There is virtually no need to call this function directly. The function is declared in putoptv.h and defined in putoptv.c.

void version Print package and program version information on stdout. This function is called by function getoptv whenever option -! or --version is detected on the command line. There is virtually no need to call this function directly. The function is declared in version.h and defined in version.c. Constants PACKAGE and VERSION define the information that is displayed. They are defined in file version.h and must be maintained by developers.

const char *MMECode uint16_t MMTYPE uint8_t MSTATUS Return text that explains the status code for a given Atheros vendor-specific management message. Argument MMTYPE is an unsigned integer in the range 0xA000 through 0xAFFF and must exactly match the MMTYPE of the message returning the status code. For example, the CNF variant of a message is currently the only variant that has an MSTATUS field and so other variants return a default string. The function is declared in mme.h and defined in MMECode.c. Inclusion of this function can increase application size by 3kb because the text associated with all Atheros vendor-specific management messages and errors are included whether needed or not. Conditional compilation statements are provided internally to suppress the full table with a terse substitute. Although the Bootloader and firmware share some common Vendor Specific Management Messages, the two programs may return different codes for a given message and error condition. Where there are conflicts, Bootloader codes take precedence over firmware codes because it is unlikely that users will .issue the same messages to a device running firmware.

const char *MMEMode uint16_t MMTYPE Return the mode of a given management message type as a string. The mode is determined by the two least significant bits of argument MMTYPE. The mode string will be one of REQ, CNF, IND or RSP. The function is declared in ihp.h and defined in MMEMode.c. Most management messages have a request and a confirmation variant while a few have an indication and a response variant. Requests originate from the host and are acknolwedged by a confirmation from the device. Indications originate from a device and are acknowledged by a response from the host.

const char *MMEName uint16_t MMTYPE Return the name associated with a given management message type. The name is the mnemonic used to distinguish one message type from another in the HomePlug AV Specification or Atheros Firwmare Technical Reference Manual. Argument MMTYPE is an unsigned integer in the range 0x0000 through 0xAFFF. The request, confirmation, indication and response variants of a management message will all return the same message name. The function is declared in mme.h and defined in MMEName.c.

void MMEPeek const byte memory [] size_t length size_t length, FILE *fp Prints an Atheros vendor-specific management message to stream fp in human readable format. Argument buffer is the message address and argument length is the message length in bytes. Output consists of a formatted header showing decoded header. The function is declared in mme.h and defined in MMEPeek.c.

void MACPasswords uint32_tvendor uint32_tdevice uint32_tnumber unsigned count unsigned bunch unsigned space flag_t flags Print a range of device addresses and user passwords on stdout. The calling application must split the starting device address into a three-byte OUI and three-byte device number and pass them as the unsigned 32-bit integers vendor and device, respectively. Argument device is the first device number in the range and number is the final device number. Argument count is the number of uppercase letters comprising a password. Passwords contain this many letters but the letters are grouped for easy reading. Letter groups are separated by hyphens. Argument bunch defines how many letters form each group. Argument space is the character used to separate groups of letters. Argument flags enables or disables function features such as insertion of a used flag for use by the Atheros Production Test System or the omission of the device address on output. The output of this function is similar to that produced by the DB Builder utility distributed with the PTS. This function is declared in keys.h and defined in MACPasswords.c.

void HPAVKeyDAK byte DAK [] const char string Encode buffer DAK with the Device Access Key (DAK) derived from the NUL terminated string. The string is salted, hashed and re-hashed using the SHA256 algorithm. The DAK is always HPAVKEY_DAK_LEN bytes, defined in HPAVKey.h, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in HPAVKey.h and defined in HPAVKeyDAK.c.

void HPAVKeyNMK byte digest [] const char string Encode buffer NMK with the Network Membership Key (NMK) derived from the NUL terminated string. The string is salted, hashed and re-hashed using the SHA256 algorithm. The DAK is always HPAVKEY_NMK_LEN bytes, as defined in HPAVKey.h, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in HPAVKey.h and defined in HPAVKeyNMK.c.

void HPAVKeyNID byte NID [] const byte NMK [] signed level Encode buffer NID with the Network Identification Key (NID) derived from the 16-byte Network Membership Key (NMK). The NMK is hashed and re-hashed using the SHA256 algorithm then encoded with the security level. The NID is always HPAVKEY_NID_LEN bytes, as defined in HPAVKey.h, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in HPAVKey.h and defined in HPAVKeyNID.c.

void HPAVKeyOut const byte digest [] size_t length const char * phrase flag_t flags Decode and print up to length bytes from buffer digest on stdout. Print NUL terminated phrase on the same line following the digest when bit HPAVKEY_VERBOSE, defined in HPAVKey.h, is set in flags. This procedure prints keys and phrases in a standard column-oriented format that other applications can easily read and use. This function is declared in HPAVKey.h and defined in HPAVKeyOut.c.

void SHA256Block struct sha256 *sha256 const byte buffer [] Merge one 64 byte block of information into the current SHA256 digest. This function performs the core computations required by the SHA256 algoithm. It is called by function SHA256Fetch and there is no reason to call this function directly. This function is declared in SHA256.h and defined in SHA256Block.c. The sha256 structure is defined in SHA256.h.

void SHA256Fetch struct sha256 *sha256 byte digest [] Conclude SHA256 computation and copy the result to the specified 32-byte digest buffer. The digest is always 32 bytes long regardless of the amount of information written using function SHA256Write. The sha256 structure is defined in SHA256.h. This function is declared in SHA256.h and defined in SHA256Fetch.c.

void SHA256Ident int fd byte digest [] Compute the SHA256 digest from the content of a file. The digest serves as the file fingerprint and can be used to identify identical content despite filename changes. File descriptor fd is the subject file which must be positioned to the start befor calling this function. Buffer digest will be written with the computed 256-digest and must be SHA256_DIGEST_SIZE bytes long, as defined in SHA256.h. This function is declared in SHA256.h and defined in SHA256Ident.c.

void SHA256Match int fd const byte digest [] Search a registry file for a known SHA256 digest. Return true on success or false on failure. File descriptor fd is the registry file which must be positioned to the start before calling this function. Buffer digest contains the known 256-bit digest and must be SHA256_DIGEST_SIZE bytes long, as defined in SHA256.h. A registry file consists of 64-digit hexadecimal strings that represent SHA256 digest values. Optional text may be appear between the digest and newline to document digest significance. This function ignores such text. This function is declared in SHA256.h and defined in SHA256Match.c.

void SHA256Print const byte digest [] const char * string Print an SHA256 digest and optional string on stdout. Buffer digest must be SHA256_DIGEST_SIZE bytes long, as defined in SHA256.h, which results in 64 hexadecimal digits on output. Variable length string is NUL terminated but may be NULL. If string is not NULL and is not empty then a space is inserted between the digest and the string on output. This function may be used to print SHA256 digests and optional strings in standard format, such as a registry file. This function is declared in SHA256.h and defined in SHA256Print.c.

void SHA256Reset struct sha256 *sha256 Initialize a sha256 structure before computing a new SHA256 digest. This function should be called once before calling SHA256Write for the first time for a given digest. The sha256 structure is defined in SHA256.h. This function is declared in SHA256.h and defined in SHA256Reset.c.

void SHA256Write struct sha256 *sha256 const byte buffer [] size_t length Writes a variable-length block of information to the current SHA256 digest contained in an sha256 structure. An application may call this function any number of times to concatinate multiple blocks of information before fetching the digest with function SHA256Fetch. The sha256 structure is defined in SHA256.h. This function is declared in SHA256.h and defined in SHA256Write.c.

signed xmledit struct node *node byte buffer [] size_t length Write data into buffer based on offset and length values defined in XML parse tree, node. This function will not apply modifications having malformed structure or having an invalid or an illegal offset, length or data value. Use function xmlschema to print the current schema. The function is declared in node.h and defined in xmledit.c. The node structure is defined in node.h.

void xmlfree struct node *node Release memory associated with an XML parse tree. The function is declared in node.h and defined in xmlfree.c. The node structure is defined in node.h. The text member if the parse tree root node points to memory allocated by xmlscan to store the original XML string. The application must either deallocate that memory before calling this function or store the text address and deallocate that memory after calling this function; otherwise, memory leaks will result.

struct node *xmlnode struct node *node Create an empty node blow the specified node and return a pointer to it. A typical application can be seen in function xmlscan.c. The function is declared in node.h and defined in xmlnode.c. The node structure is defined in node.h.

struct node *xmlopen const char *filename Open the named XML file, parse it and return the XML parse tree. The parse tree contains, among other things, all XML elements, attributes and values specified in the file. The function is declared in node.h and defined in xmlopen.c. The node structure is defined in node.h. The returned parse tree is ready to traverse using struct node members above, below, prior and after. Each node has a line, type and test member. This function calls function xmlscan to parse the file and generate the tree. The parse tree can be inspected by passing the root node to function xmltree.

signed xmlscan struct node *node Scan the XML string attached to the specified node and create a parse tree below it. Return 0 if parsing is successrul or -1 if not. The function is declared in node.h and defined in xmlscan.c. The node structure is defined in node.h. The application must point the text member to a copy of the XML string before calling this function because parsing is destructive and requires write access to the string. The application can search and manipulate the tree on return. The application should deallocate string memory before calling xmlfree. The following is sample input to function xmlscan. The element and attribute names shown are for illustration and were selected to that they can be easily identified in the output. The parse tree from this file can be seen in the example for function xmltree. 1234567890 The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. value2 ]]>

void xmlschema Print an XML schema that supports function xmledit on stdout. This function has no argument. The schema produced by this function is guaranteed to support the parse logic implemented by function xmledit. Scheme element names are defined as constants in node.h so that they can be referenced by applications that create their own XML edit instructions. The function is declared in node.h and defined in xmlschema.c. The text member in the parse tree root node points to memory allocated by xmlscan to store the original XML string. The application must either deallocate that memory before calling this function or store the text address and deallocate that memory after calling this function; otherwise, memory leaks will result. ]]> The schema shown above was produced by function xmlschema. It is should be used to validate XML edit instructions before submitting them to program pxe.

void xmltree struct node *node Print the XML parse tree on stdout. The function is declared in node.h and defined in xmltree.c. The following is sample output from function xmltree. The XML source is shown in the example for function xmlscan . The numbers appearing down the left margin indicate the input line number from the XML source file parsed by function xmlscan . The character codes indicate the node type and are defined in node.h. The node structure is defined in node.h. ] [1234567890] 006 [/] [attribute] 007 [<] [attribute] 007 [ ] [name] 007 [=] [Attribute2] 008 [>] [The quick brown fox jumped over the lazy dog.] 009 [/] [attribute] 010 [/] [element] 011 [<] [element] 011 [ ] [name] 011 [=] [Element2] 012 [<] [attribute] 012 [ ] [name] 012 [=] [Attribute1] 013 [/] [attribute] 014 [<] [attribute] 014 [ ] [name] 014 [=] [Attribute2] 015 [>] [The quick brown fox jumped over the lazy dog.azy] 018 [/] [attribute] 019 [/] [element] 020 [!] [-- comments can go anywhere --] 021 [<] [element] 021 [ ] [name] 021 [=] [Element2] 022 [<] [attribute] 022 [ ] [name] 022 [=] [Attribute1] 023 [<] [attribute] 023 [ ] [name] 023 [=] [Attribute2] 024 [>] [value2] 025 [/] [attribute] 026 [/] [element] 027 [/] [xmlfile] ]]>

void scaninput struct scan * content const char buffer [] signed length Initializes a SCAN structure for scanning by pointing the structure a buffer of given length, resetting intermmediate pointers and clearing the token class code.