interpio(3)

Section: Interp SDK (3)
Updated: 2011-02-22

NAME

interpio - encapsulates interp's formatted I/O functions

SYNOPSIS

#include itypes.h
#include interp.h
#include interpio.h

int send_string( ibyte *message, Interp_T cp, ibyte *opcode );
int memory_string( ibyte *message, Interp_T cp, ibyte *opcode, ibyte *dest );
int send_number( Interp_T cp, base_T base, int width, int notated, ibyte *opcode );
int mem_send_number( Interp_T cp, int mem_size, base_T base, int width, int notated, ibyte *opcode );
int emit_operator( Interp_T cp, ibyte c );
int handle_error( int error_code, ibyte *opcode, Interp_T cp );

DESCRIPTION

These functions are the glue between interp and the I/O portability layer. They provide interp with a stack-oriented I/O capability suitable for printing numbers in various formats and number bases, and processing strings containing output formatting directives and argument type information.

Even though emit_operator and handle_error do no I/O operations, they are in this API because they are I/O-helper functions that are called from other APIs.

LIST OF FUNCTIONS

Function
Description
send_string
Accepts a formatting string, message and the interp control block pointer cp. The content of the zero-terminated formatting string determines all actions taken and all output produced. The final argument is a pointer to the token or suboperator being executed now. It is used in the error message if there is a problem interpreting the formatting string. The returned status is 0 for success or an error code.

        Special, meta-characters, interpreted during printing:
        # - print the top-of-stack value in the current output base
              Optional modifiers (only one, follows '#'):
                 b - print value as a notated (0x) hexadecimal byte (4 characters)
                 B - print the value as a hex byte (2 characters)
                 c - print value as one ASCII character
                 C - print value as one ASCII character, prints '.' if the character is non-printable
                 d - print value as free-form decimal
                 Dn - display decimal value, right-justified in an n-digit field.
                         The range of n is 0-9 with 0 being a 10-digit field and all
                         other values representing their equivalent field width.
                 h - print value as a notated (0x) hexadecimal halfword (6 chars)
                 H - print value as a hex halfword (4 characters)
                 s - use value as the address of a null-terminated string
                       of ASCII characters, and print the entire string
                 T - treat the value as elapsed time in microseconds and print
                       it as hh:mm:ss.uuuuuu, where "hh" is hours, "mm" minutes,
                       "ss" seconds, and "uuuuuu" microseconds
                 w - print value as a notated (0x) hexadecimal word (10 chars)
                 W - print value as a hex word (8 characters)
        NOTE:These modifiers (bBhHwW) specify minimum field width.
                    If the value is larger, it still prints properly.

        !A - use the top of stack as the print iterator address, store it
                at PRINT_ITERATOR_ADDRESS (K38), reset PRINT_ITERATOR_MODE
                (K39) to auto-increment (1), and set PRINT_ITERATOR_FIRST_ONE
                (K40) to TRUE/~0 (only used by auto-decrement)
        !i - enable auto-increment of the print iterator address after
                printing the contents.
        !d - enable auto-decrement of the print iterator address after
                printing the contents.

        @ - print the value pointed to by PRINT_ITERATOR_ADDRESS (K38) in
                the current output base. An optional modifier follows the '@'.
                If no modifier is present, the value is read from memory as a
                32-bit word. If a modifier is present, the value is read from
                memory as indicated below; HALFWORD is 2-bytes, and WORD is 4:
        a - (WORD) print the print iterator address as a notated (0x)
              hexadecimal word (10 characters). Print iterator address is
              not changed by this modifier.
        A - (WORD) print the print iterator address as a hexadecimal
              word (8 characters). Print iterator address is not changed
              by this modifier.
        b - (BYTE) print value as a notated (0x) hexadecimal byte
              (4 chars)
        B - (BYTE) print value as a hex byte (2 characters)
        c - (BYTE) print value as one ASCII character
        C - (BYTE) print value as one ASCII character, prints '.' if
              the character is non-printable
        d - (WORD) print value as free-form decimal
        Dn - (BYTE/HALFWORD/WORD) display decimal value right-justified
                in an n-digit field. The range of n is 0-9 with 0 being a
                10-digit field and all other values representing their
                equivalent field width. The size of memory read is deter-
                mined by the specified field width:
                   BYTE - D1, D2, and D3
                   HALFWORD - D4 and D5
                   WORD - D6, D7, D8, D9, and D0
        h - (HALFWORD) print value as a notated (0x) hexadecimal half-
              word (6 chars)
        H - (HALFWORD) print value as a hex halfword (4 characters)
        s - (WORD) use value as the address of a null-terminated string
              of ASCII characters, and print the entire string or "NULL"
              if the value (treated as pointer) is NULL.
        S - (string length+1) use value as a zero-terminated string
              of ASCII characters, and print the entire string
        T - (WORD) treat the value as elapsed time in microseconds and
              print it as hh:mm:ss.uuuuuu, where "hh" is hours, "mm"
              minutes, "ss" seconds, and "uuuuuu" microseconds
        w - (WORD) print value as a notated (0x) hexadecimal word
              (10 chars)
        W - (WORD) print value as a hex word (8 characters)
        NOTE:These modifiers (bBhHwW) specify minimum field width. If the value is larger, it still prints properly.
        NOTE:Each modifier (except aA) increments the print iterator address after reading the value.
        NOTE:The 'S' modifier is illegal when outo-decrement mode is enabled ("!d") because of the uncertainty
                     associated with searching backwards for the beginning of a variable-length string.

       \ - display a special character, from this list:
       n - newline, 0x0A
       r - carriage return, 0x0D
       t - tab, 0x09
       other - literal character

memory_string
Performs the same job as send_string except it writes the resulting zero-terminated string to dest
send_number
Accepts the interp control block pointer cp, the minimum output field size, base, the minimum output field size, width, a hex notation flag, notated, and a pointer to the token or suboperator being executed now. It is used in the error message if there is a problem. When the number is popped off the stack and converted to a string, the conversion uses the output/error message buffer pointed to by the interp control block. The returned status is 0 for success or an error code.
mem_send_number
Accepts the interp control block pointer cp, the size of the item in bytes, mem_size, the output number base, base, the minimum output field size, width, a hex notation flag, notated, and a pointer to the token or suboperator being executed now. It is used in the error message if there is a problem. When the number is popped off the stack and converted to a string, the conversion uses the output/error message buffer pointed to by the interp control block. The returned status is 0 for success or an error code.
emit_operator
Accepts the interp control block pointer and the token or suboperator being executed. Either the literal character or its hexadecimal representation, if it is non-printable, is placed at the beginning of the output/error message buffer pointed to by the interp control block. The value returned is the offset from the beginning of the buffer to the next available location. This is always the next character after whatever was placed in the buffer.
handle_error
Formats error messages. It accepts an error code, a pointer to the token or sub operator being executed, and the interp control block pointer. It formats an error message into the output/error message buffer pointed to by the interp control block, and updates error state information (bop and err) in the control block. The returned status is the error code of the recognized error. If the passed in error code is erroneous, UNRECOGNIZED_ERROR_CODE is returned, otherwise the returned error code is the same as the passed in error code.

SEE ALSO

ilowlevelio(3), interp(3)