Generic Functions
Prev | Chapter 7. Support Function Reference | Next

## Generic Functions

The functions in this chapter are generic and may have application beyond the Open Powerline Toolkit. In some cases, these functions 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.

### binout

`void binout(` | memory, |
| extent, |
| c, |
| e, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`char c`;
`char e`;
`FILE * fp`;

Print a `memory` region as a series of binary octets separated by character `c` and terminated by character `e`. Normally, character `c` will be `BIN_EXTENDER`, defined in file number.h, but it could be any character value. Normally, character `e` will be a space or newline, but it could be any character value. A typical use might be to print a register in readable format. For example, specifying `c` as `'-'`, `e` as `';'` and `extent` as `4` would produce output looking something like `"10101010-1111111-00000000-11001100;"` where each octet is expressed as a binary integer. The function is declared in memory.h and defined in binout.c.

### checksum32

`unint32_t checksum32(` | memory, |
| extent, |
| checksum`)`; |

`const uint32_t 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. Argument `extent` is the region extent in 32 bit words. Argument `checksum` is the reference checksum. The function will return the computed checksum when reference`checksum` is `0` and will return `0` if reference `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 checksum32.c.

This function is similar to checksum_32 but is used exclusively by API functions. It may be deprecated at some point in the future.

### checksum_32

`unint32_t checksum_32(` | memory, |
| extent, |
| checksum`)`; |

`void const * 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 reference`checksum` is `0` and will return `0` if reference `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. It is the prefered method of computing a checksum.

### chrout

`void chrout(` | memory, |
| extent, |
| c, |
| e, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`char c`;
`char e`;
`FILE * fp`;

Print a `memory` region as a string of printable ASCII characters terminated by character `e`. Character `c` is printed in place of non-printable characters. The string is terminated by character `e`. Normally, character `c` is `'.'` but it could be any character value. Normally, character `e` is space or newline but it could be any charcter value. A typical use might be to print a memory region that may (or may not) contain an HFID or other printable text. The function is declared in memory.h and defined in chrout.c.

### decout

`void decout(` | memory, |
| extent, |
| c, |
| e, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`char c`;
`char e`;
`FILE * fp`;

Print a `memory` region as a series of decimal octets separated by character `c` and terminated by character `e`. Normally, character `c` will be `DEC_EXTENDER`, defined in file number.h, but it could be any character value. Normally, character `e` will be a space or newline but it could be any character value. A typical use might be to print an IP address in readable format. For example, specifying `c` as `'.'`, character `e` as `'/'` and `extent` as `4` would produce output looking something like `"192.168.099.001/"` where each octet is expressed as a decimal integer. The function is declared in memory.h and defined in decout.c.

### endian

`void endian(` | memory, |
| extent`)`; |

`void * memory`;
`size_t extent`;

Reverse the byte order of a `memory` region. It is a variable extent version of functions like `__bswap_16`, `__bswap_32` and `__bswap_64`. The function is declared in memory.h and defined in endian.c.

### fdchecksum32

`unit32_t fdchecksum32(` | fd, |
| extent, |
| checksum`)`; |

`int fd`;
`size_t extent`;
`unit32_t checksum`;

Return the 32 bit checksum of a file region starting from the current file position. The checksum is the one's complement of the XOR or of all 32 bit words in the region. Argument `extent` must be specified in 32 bit words, not bytes. Argument `checksum` is the reference checksum. The function will return the computed checksum when reference`checksum` is `0` and will return `0` if reference `checksum` equals the computed checksum. A typical use is to validate NVM files header by header or section by section. The function is declared in memory.h and defined in fdchecksum32.c.

### fdchecksum_32

`unit32_t fdchecksum_32(` | fd, |
| extent, |
| checksum`)`; |

`int fd`;
`size_t extent`;
`unit32_t checksum`;

Return the 32 bit checksum of a file region starting from the current file position. The checksum is the one's complement of the XOR or of all 32 bit words in the region. Argument `extent` is specified in bytes but is rounded down to the nearest multiple of 4 bytes. Argument `checksum` is the reference checksum. The function will return the computed checksum when reference`checksum` is `0` and will return `0` if reference `checksum` equals the computed checksum. A typical use is to validate NVM files header by header or section by section. The function is declared in memory.h and defined in fdchecksum_32.c.

This function is similar to function fdchecksum32 but there is no need to round `extent` down to the nearest multiple of 4 bytes before calling the function because that is done internally. Also, there is no unecessary endian manuipulation of the checksum.

### filepart

`char const * filepart(` | pathname`)`; |

`char const * 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.

### hexdecode

`signed hexdecode(` | memory, |
| extent, |
| buffer, |
| extent`)`; |

`void * memory`;
`size_t extent`;
`char const buffer []`;
`size_t extent`;

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

### hexdump

`void hexdump(` | memory, |
| offset, |
| extent, |
| fp`)`; |

`void const * 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 extent. 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 .

### hexencode

`signed hexencode(` | memory, |
| extent, |
| string`)`; |

`void * memory`;
`size_t extent`;
`char const * 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.

### hexin

`ssize_t hexin(` | memory, |
| extent, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`FILE * fp`;

This function is similar to hexencode 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 `memory` region. The actual number of bytes encoded is returned or `-1` on error. See the efsu man page for a thorough explanation of function behavior. The function is declared in memory.h and defined in hexin.c.

### hexout

`void hexout(` | memory, |
| extent, |
| c, |
| e, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`char c`;
`char e`;
`FILE * fp`;

Print a `memory` region as a series of hexdecimal octets separated by character `c` and termianted by character `e`. Normally, character `c` will be `HEX_EXTENDER`, defined in file number.h, but it could be any character value. Normally, character `e` will be a space or newline but it could be any character value. A typical use might be to print a MAC or Ethernet address in readable format. For example, specifying `c` as `':'`, character `e` as `','` and `extent` as `6` would produce output looking something like `"00:B0:52:DA:DA:01,"` where each octet is expressed as a hexadecimal integer. The function is declared in memory.h and defined in hexout.c.

### hexstring

`char * hexstring(` | buffer, |
| length, |
| memory, |
| extent`)`; |

`char buffer []`;
`size_t length`;
`void const * 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.

### hexview

`void hexview(` | memory, |
| offset, |
| extent, |
| fp`)`; |

`void const * 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 but excluding `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.

### memdecr

`signed memdecr(` | memory, |
| extent`)`; |

`void * memory`;
`size_t extent`;

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.

### memincr

`signed memincr(` | memory, |
| extent`)`; |

`void * memory`;
`size_t extent`;

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.

### memout

`void memout(` | memory, |
| extent, |
| format, |
| group, |
| c, |
| fp`)`; |

`void const * memory`;
`size_t extent`;
`char const * format`;
`unsigned group`;
`signed c`;
`FILE * fp`;

Print a `memory` region as a series of octet groups wach separated by character `c`. The `group` argument specifies the number of octets per group. The `format` argument determines how each octet is displayed. Normally, character `c` will be one of `BIN_EXTENDER`, `DEC_EXTENDER` or `HEX_EXTENDER` as defined in file number.h, but it could be any character value. The function is declared in memory.h and defined in memout.c.

### memswap

`void memswap(` | buffer1, |
| buffer2, |
| length`)`; |

`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.

### strdecr

`signed strdecr(` | memory, |
| extent, |
| min, |
| max`)`; |

`void * memory`;
`size_t extent`;
`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.

### strfbits

`size_t strfbits(` | buffer, |
| length, |
| operands, |
| operator, |
| flagword`)`; |

`char const buffer []`;
`size_t length`;
`char const * operands []`;
`char const * 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 `char const *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 format.h and defined in strfbits.c.

### strincr

`signed strincr(` | memory, |
| extent, |
| min, |
| max`)`; |

`void * memory`;
`size_t extent`;
`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.

### todigit

`unsigned todigit(` | c`)`; |

`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 todigit.c.

### typename

`char const * typename(` | list, |
| size, |
| type, |
| name`)`; |

`const struct _type_ list []`;
`size_t size`;
`type_t type`;
`char const * 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 symbol.h and defined in typename.c.

Prev | Up | Next
Network Functions | Home | Message Debug Functions