Linux STREAMS (LiS)
|
Linux STREAMS (LiS) |
|
|
LiS User Commands |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IntroductionThe Linux STREAMS (LiS) package contains some user level commands that are used to manage the package and assist the user with STREAMS functions. These commands are installed in /usr/bin or /usr/sbin. They are referred to a "global commands." A second group is built in the LiS installation directory and left there.
This second group is oriented more towards testing of LiS than towards
its operation. These commands remain undocumented since they are
primarily intended for the use of the authors of the modules that they
test.
Global CommandsThese are the commands that are installed in /usr/bin or /usr/sbin, and are thus globally accessible to any user with those directories in his/her path.
fattach
Description The fattach program provides a command-line interface to the underlying fattach(3) function. If the -p and/or the -c option is specified, a STREAMS-based pipe is created and its two ends are alternately attached to the path names given. In this mode of usage, at least two path names are required, but there need not be an even number of path names (i.e., the pipe ends need not be attached to the same number of paths). If the -p and -c options are not specified, the first path name given must identify a STREAMS-based file. That file will be opened, and it will be attached to each of the path names subsequently specified (of which there must be at least one). Options
Return Value Upon successful completion, i.e., if all given path names are attached to, fattach returns 0. Upon failure, fattach returns 1. However, the failure of one more attachments does not otherwise affect those that succeed, and the user is responsible for detaching any that may have succeeded if that is the desired behavior in the event of any failures. Application Usage The -p and -c options provide a convenient means for creating free-standing mounted pipes. The openers of the paths attached via -p will share a single pipe, while the openers of the paths attached via -c will have access to a pipe-serving pipe. I.e., each open of the first end (e.g., the client end) will generate a new pipe, one end of which will be given to the opener, and the other end of which will be passed as if by the I_SENDFD ioctl to the path attached to the other end (e.g., the server end). Each opener of the server path could poll(2) for input, receive a new pipe end using the I_RECVFD ioctl, and then close the server path, therefter using the new pipe end to communicate with the corresponding opener of the client path (note that the sense of client and server will in fact depend on the application - users of the two paths need only be aware of whether or not an I_RECVFD ioctl must be performed). See Also connld(9), fattach(3), fdetach(3), fdetach(8), STREAMS(4), umask(2) History An fattach function has been provided for various STREAMS implementations based on SVR4 STREAMS. Not all of these have provided a corresponding utility program of this sort. Author John Boyd, protologos LLC <jaboydjr@netwalk.com>
fdetach
Description The fdetach program provides a command-line interface to the underlying fdetach(3) function. It is thus intended to provide a convenient means to dismantle so-called mounted STREAMS. If the -a option is specified, all currently attached STREAMS-based files are detached. If the -a option is not specified, the path names given are taken to identify paths to which STREAMS-based files are currently attached. Those files will be detached from these paths. Options
Return Value Upon successful completion, i.e., if all given path names identify mounted STREAMS and these are all successfully detached, fdetach returns 0. Upon failure, fdetach returns 1. Note, however, that a failure indication does not mean that no action is taken; i.e., those detachments that succeed are not affected by those that fail. Warnings It should be noted that although the fdetach program implements the -a option, by passing "*" to the fdetach function, this is not at all equivalent to specifying "*" on the command line when executing the program. Normally, "*" specified on the command line will be converted by a shell into a list of all files in the current working directory. By contrast, the -a option causes the fdetach operation to operate not with respect to path names at all, but with respect to STREAMS devices currently active within the STREAMS subsystem. I.e., each active stream head is examined for attachments, and any attachments found are dismantled. The intended use for the -a option is thus to undo all attachments, e.g., in preparation for unloading the STREAMS subsystem. See Also fdetach(3), fattach(8), STREAMS(4) History An fdetach function has been provided for various STREAMS implementations based on SVR4 STREAMS. Not all of these have provided a corresponding utility program of this sort. Author John Boyd, protologos LLC <jaboydjr@netwalk.com>
ldlconfig
Description ldlconfig is used to configure the ldl STREAMS driver as a client of a standard Linux network driver. Once configured other STREAMS drivers can be pushed or I_LINKed on top of the ldl driver, thus giving STREAMS drivers access to Linux network drivers. Options
Operation ldlconfig opens the clone device /dev/ldl, or accepts a file descriptor to a file already opened to that device. It performs a DLPI Attach Request based upon the -a parameter. This attaches the file to a Linux network device. It then sets operational options based upon the -f and -p options, if any were specified. If the -b option is specified it also performs a DLPI Bind Request on the stream. The resulting stream connects to the ldl driver which acts as a DLPI Provider and translates between the DLPI STREAMS protocol from above to the Linux network driver interface below. The effect is to present a DLPI interface to a Linux network driver. The type of network driver (Ethernet, Token Ring, FDDI, HDLC) is compared with the requested framing type (is option) and RAW flag (is option). If the given driver does not support the requested framing type then the ldlconfig command will fail. All drivers support the RAW frame interface. Depending upon the driver type and framing type, the ldl driver will set up to decode incoming "frames" according to the framing type. This has an effect on where the driver looks in the incoming "frame" to find the SAP to match against the requested SAP in the DLPI Bind Request to ldl (-b option). The framing type of RAWLLC generally means that the entire frame is passed upstream. This allows the upstream client driver to interpret the LLC information within the frame. Frame types other than RAWLLC generally mean that the LLC header will be stripped from received frames passing just the payload portion to the upstream client. The received frame is passed upstream in a DL_UNITDATA_IND M_PROTO message and the address carried by this frame will be set to the source MAC address from the frame header. In the transmit direction, a frame type of RAWLLC means that the formatting of the frame to be sent to the medium is under the control of the upstream client. For other types of framing, the ldl driver will build the LLC header according to the framing type. The address in the DL_UNITDATA_REQ is used to develop the destination MAC address. For any given frame type and driver type, it is often necessary to consult
the driver source code in order to understand the fine details of the
frame processing involved. Return Value ldlconfig returns 0 upon success and 1 if any indicated operation failed.
Author Ole Husgaard <sparre@login.dknet.dk>
ldltest
Description ldltest is used to test the ldl STREAMS driver by using one of the existing standard Linux network drivers to send a "ping" to another host on the network. The command line parameters specify the local-IP and remote-IP addresses and the name of the Driver to use when sending the ping. ldltest is also used to obtain statistics from the ldl STREAMS driver and to set debugging masks. Options
Operation In test mode, ldltest constructs a ping packet from the parameters given and sends it to the remote host. It awaits the response and prints out the round trip time when it receives the response. If the -c option is used it sends the ping repeatedly and prints out the round-trip time every 1,000 packets. With the -s (lower case) option, ldltest listens for received frames from the indicated interface driver. If the framing is specified as RAW then it will receive LLC frames from the driver. Other types of framing result in non-LLC Ethernet types of frames such as IP packets and ARP messages. Thus, the setting of the -f option conditions the type of messages that can be received from the interface. When an ICMP ping is received, it is responded to. When an LLC TEST or XID command is received it is responded to with the corresponding response frame. With the -g option, ldltest obtains statistics maintained by the ldl driver and prints them out. This is useful for troubleshooting protocol stack configuration since you can see whether packets entering ldl from either above or below was forwarded to the neighboring module. By setting debug bits via the -d option, you can cause the ldl driver to print the contents of packets flowing into it and out of it. Examples
Author Ole Husgaard <sparre@login.dknet.dk> polltst
Description polltst is a simple test program for the poll system call. Using poll, it reads keystrokes from stdin, writes them to one end of the LiS loopback driver, reads them from the other end and then writes them back to stdout. While performing this operation it configures stdin
for "no echo" mode, so the appearance of "echoed" characters is evidence
of the operation of poll involving both a STREAMS and a non-STREAMS file.
Author David Grothe <dave@gcom.com>
streams
Description
Options
Debug Options The value that is used with the -d option consists of the logical "or"
of the following single bit options.
Most of these options are intuitive as to their operation from the mnemonics. The DEBUG_MEAS_TIME option causes LiS to use a high precision timer to calculate the execution time of several operations within itself. These timings include the time spent in STREAMS drivers. Thus, under controlled circumstances this option can be used to time STREAMS driver code. It is used in conjunction with the -t option to print out the timing statistics. The DEBUG_SAFE option causes LiS to carefully check for NULL pointers when performing message passing and queueing operations such as putq and putnext. The DEBUG_CLEAN_MSG option causes LiS to clear message data buffers to zero when they are allocated. It is useful for tracking down driver problems relating to using uninitialized areas of messages. The DEBUG_SPL_TRACE option causes LiS to maintain a trace table of all LiS locking operations. It is used in conjunction with the -p option to print out the lock trace table. The locking operations that are traced include calls on the LiS locking primitives from STREAMS drivers. The options DEBUG_DMP_QUEUE, DEBUG_DMP_MBLK and DEBUG_DMP_DBLK control the verbosity of the printing out of LiS memory areas via the -m option. With these debug mask bits set, LiS will print out the contents of these structures as well as the headers indicating that such a structure was allocated. The DEBUG_ADDRS option causes the -m option to print out the addresses of structures as well as their memory tags and/or contents. The DEBUG_MONITOR_MEM
option causes LiS to monitor the guard words surrounding allocated memory
areas in an attempt to catch overwriting of these words in a timely fashion.
This option comes at a fairly substantial CPU time penalty. Author David Grothe <dave@gcom.com>
strmakenodes
Description strmakenodes makes all of the /dev entries that are associated with LiS as a result of the LiS build process. All of the Config files that contributed to the LiS build are scanned for their "node" declarations. strmakenodes performs a mknod system call for each specified "node". This command must be run before LiS can operate correctly after it is installed. This command is run automatically as a result of the "make install" operation of LiS. This command accepts the option "-r" to mean remove nodes instead of making them. The command is run with this option as a result of the "make uninstall" operation. The source code for this command is generated automatically as a side-effect
of running the strconf utility.
strtst
Description strtst is a test program which tests the core functionality of LiS. It is a user level program which uses the built-in drivers that are installed by default with LiS. It performs numerous STREAMS operations and checks the results for correctness. It prints out a voluminous log file whose output is routed to the "messages" file (kernel informational messages). The output of strtst can
be compared to earlier "reference" outputs to see if the behavior of LiS
has changed as a result of modifications to the code. Author David Grothe <dave@gcom.com>
timetst
Description
Author David Grothe <dave@gcom.com>
|
