psh(1)

SYNOPSIS
psh [ file ]

DESCRIPTION
Psh is a packet shell. Commands allow you to create, modify, send, and receive packets on networks. The operations available for each protocol are supplied by a dynamically linked library called a protocol library . These libraries are silently linked in from a special directory when the packet shell is begins execution. The packet shell is based on TCL.

Packets are stored in a special variable type. They consist of a data part, a protocol table, and a length. The data part consists simply of the bytes of the packet in network order. The protocol table contains a list of (protocol name, byte offset) entries which describe each portion of the packet the packet shell is able to identify. This data can be accessed to help identify or process the packet.

The packet shell commands are either generic or protocol specific. Generic commands are either extensible or basic. Extensible commands call into the protocol library to implement part of the functionality, while basic generic commands operates on packets in a protocol independent fashion.

Nomenclature

In the command description, packet is the name of a packet variable. Protocol is the name of a specific protocol. Wherever prlayer is indicated it means that it may be a protocol name, or a number, or a protocol name, followed by a colon and a number. If just a protocol name is supplied, it means the first instance in the packet of that protocol name. If the form is a number, it means the n-th protocol layer in the packet. It is zero indexed, so 0 indicates the first layer of the packet, one indicates the second layer, etc. If the protocol:number form is used, it means the numbered instance of the indicated protocol in the packet. This can be use in situations such as tunneling encapsulation where you might find an IP header inside an IP header to specify which IP header you wish.

Generic Commands

Besides the general TCL commands, the packet shell supplies a series of general commands.

packets
    Return the names of all packet variables currently existant.

ptbl packet
    Returns a list of each element of the named packet's protocol table.

plen packet [prlayer [length]]
    Get the length of the indicated packet layer. If length is supplied, set the length to the indicated value. If prlayer is omitted, report the total length of this packet.

poffset packet prlayer
    Get the offset of the indicated prlayer .

pproto packet prlayer
    Return the name of the indicated prlayer .

psleep timeval
    Sleep for the specified time interval (in seconds).

pcast packet prlayer protocol
    Cast the specified prlayer to be interpreted as the indicated protocol. this allows, for example, an incorrectly classified prlayer to be reclassified to its correct protocol.

pread packet {b|w|l} offset [count]
    This function allows a packet's data to be accessed directly. The character 'b', 'w', or 'l' indicates whether to read bytes, 16-bit words, or 32-bit long words. The offset indicates where, relative to the beginning of the packet to find the first data bytes. The units of the offset are specified in the size of the value being fetched. If count is supplied, that many items are returned. The default for count is one.

pwrite packet {b|w|l} offset value...
    Similar to pread , values are written into the packet buffer.

pcopy packet1/prlayer1 packet2/prlayer2...
    Copy into packet1 replacing the protocol layer prlayer1 from each indicated layer of packets indicated. Note that only the one layer in the destination packet is replaced, regardless of how many source packet layers are indicated. If the source layer(s) are larger in size than the destination layer, the layers following the indicated one in the destination packet are moved down and the over-all size of the packet buffer is increased accordingly. Note that this operation may invalidate fields in protocols which track the length of a packet. If so, they will have to be reset manually by pset operations after pcopy.

passert expression text
    Assert that the given expression evaluations to true. When this statement is executed, if the expression evaluates to false, the packet shell will abort returning the string text as an explanation of why a script failed.

Extensible Commands

Extensible commands represent a set of commands common to most protocols, yet which desire particular features which are specific to a protocol. A protocol might also choose not to provide some of the extensible functions.

pinit protocol packet [protocol-specific-options]
    Initialize a new packet named packet of the protocol specified. Any additional options are passed on to the protocol itself, and may be used to initialize the packet in a suitable way for that protocol. By convention, the first protocol-specific argument is usually the size in bytes of the buffer space to be allocated.

pfree packet
    Free and destroy the packet variable indicated.

plist packet protocol
    Provide a "convenient" listing of the contents of the indicated packet, of the protocol layer named protocol.

pget packet protocol element
    Return a string representation of the item named element of the indicated protocol. This command is useful to extract parts of packets into TCL variables, and to provide more detail on a packet than plist provides.

pset packet protocol element [value...]
    Set the indicated element in the indicated packet and protocol. Normally a value is not optional, however some options have a boolean sense.

popen protocol desc [protocol-specific-arguments]
    Open an end-point to send and receive packets of the given protocol. Desc is the name of a descriptor which names the end-point. By convention all operations on this end-point will be TCL commands of the form desc.operation. Note that the operation names are determined by the protocol library.

pclose protocol desc [protocol-specific-arguments]
    Close a previously popen 'ed end-point.

Protocol Commands

These commands are supplied by each protocol library. To prevent name-space collisions, it is recommended that commands be prefixed by the protocol name, but this is not enforced.

FILES

/opt/psh/lib
    Directory of automatically dynamically linked protocols.

SEE ALSO
xpsh(1), protolib(3).