Linux STREAMS (LiS)


LiS User Commands

Contents

Introduction

Global Commands

fattach
fdetach
ldlconfig
ldltest
polltst
streams
strmakenodes
strtst
timetst


Introduction

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

Back to Contents


Global Commands

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

Back to Contents



 

fattach

/usr/sbin/fattach [-v] [-m|-u|-M mode] [-p|STREAMS-path] path ...
/usr/sbin/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

-p

Create a STREAMS-based pipe, to which to attach the subsequently  specified path names.  The first path will be attached to the first pipe end, the  second to the second pipe end, the third to the first pipe end,  etc.,  until the list of path  names is exhausted.

By  default,  the  umask  (see  umask(2))  is  also applied to each end of the  pipe  after  attaching. (See fattach(3)).

-c

Like -p (both  may  be  given),  but additionally pushes the connld module onto the first end of the pipe.   This  conveniently  creates a free-standing pipe-serving pipe (see connld(9), and below).

-m

Apply the mode of the last-specified path(s) to the attached STREAMS-based  file(s) after  attaching.  (See fattach(3).

-u

Apply the umask (see  umask(2)) of the  STREAMS-based file  after  attaching.  (See fattach(3)).  This is done by default when a pipe is created via -p.

-M mode

Apply the given mode to the STREAMS-based  file(s) after attaching.  (See fattach(3)).

-v

Operate in a "verbose" manner.  This causes fattach to report its progress via message output to stdout or stderr.

-?

Provide a usage summary.

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>

Back to Contents


fdetach

/usr/sbin/fdetach [-v] path ...
/usr/sbin/fdetach -a
/usr/sbin/fattach -?

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

-a

Undo all attachments currently in effect.

-v

Operate in a "verbose" manner.  This causes fdetach to report its progress via message output to stdout or stderr.

-?

Provide a usage summary.

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>

Back to Contents


ldlconfig

/usr/sbin/ldlconfig Options
/usr/sbin/ldlconfig -h

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

-aname

The name of the network driver interface to attach.  For example, "-aeth0" attaches to the eth0 network driver.

-bsap

The SAP to bind.  The interpretation of the SAP depends upon the mode (-p) and framing (-F) being used.

-dfiled

Instead of opening /dev/ldl, use the given file descriptor number.  This allows an external program to open /dev/ldl, use ldlconfig to configure the STREAM, and then continue to use the open file descriptor for further operations.

-fflag

Flag to set with ioctl.  Mnemonic values for flag are PEDANTIC_STANDARD and RAW.

-Fframing

The type of framing to use in interactions with the network driver.  Mnemonic values for framing are EII, 802.2, SNAP, 802.3 and RAWLLC.

-h

Print a command usage synopsis.

-pmode

Set promiscuous mode.  Mnemonic values for mode are PHYS, SAP or MULTI.

-vmask

Set verbose mask.

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>
 

Back to Contents


ldltest

/usr/sbin/ldltest Options Driver Local-IP

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

-a

Respond to received ARP queries.

-s

Respond to received pings. Also enables LLC TEST/XID echo mode.

-S dsap:ssap

Set the DSAP and SSAP to use when sending an LLC TEST or XID.

-r remote-IP

The remote IP address to which the ping is to be directed.

-R remote-MAC

The remote MAC address for sending LLC TEST/XID frames.

-c packet-cnt

The number of ping packets to send. Default is 1.

-v number

Set verbosity level.

-f framing

Set framing style to EII (default), RAW or SNAP.

-d mask

Set debug mask for the ldl driver to mask.

-H

Print out the values for the debug mask bits.

-g

Print out global statistics obtained from the ldl driver.

-T

Send LLC TEST command.

-X

Send LLC XID command

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

ldltest -r 192.168.1.1 eth0 192.168.1.117

Sends a ping to 192.168.1.1. The local host address is 192.168.1.117 (obtainable from the ifconfig command).

ldltest -S 0x00:0x0C -T -R 00:00:C0:D7:54:F8 eth0

Sends an LLC TEST command to the remote system with Ethernet address 00:00:C0:D7:54:F8, DSAP 0x00 and SSAP 0x0C. Await the response.

ldltest -s -f RAW eth0 192.168.1.47

Listens for RAW LLC frames addressed to the local machine whose IP address is 192.168.1.47. Send responses to TEST and XID commands.

ldltest -d 0x0f

Sets the debug mask in the ldl driver.

ldltest -H

Prints the values assigned to the debug mask bits as follows:

0x00000001 dump raw frame from net driver
0x00000002 dump UNITDATA_IND upstream
0x00000004 dump UNITDATA_REQ downstream
0x00000008 dump Tx to net driver
0x00000010 dump full buffer, not just header
0x00000020 debug info for DL_ATTACH
0x00000040 debug info for DL_BIND

Author

Ole Husgaard <sparre@login.dknet.dk>

Back to Contents


polltst

/usr/bin/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>
 

Back to Contents


streams

/usr/sbin/streams Options

Description


The streams program is used to perform several different management functions for the LiS package, including starting and stopping the LiS subsystem.
 

Options

start

Start the LiS subsystem.  This amounts to performing the command "modprobe streams".

stop

Stop the LiS subsystem.  This amounts to performing the command "modprobe -r streams".

status

Reports on the status of the LiS subsystem.

-cKbytes

Print or set the maximum message memory usage for LiS.  The value 0 (default) means unlimited.

-CKbytes

Print or set the maximum total memory usage for LiS.  The value 0 (default) means unlimited.

-dmask

Set the debug mask for LiS.  See below for details.

-Dmask

Set an additional debug mask for LiS.  See below for details.

-s

Print STREAMS memory usage statistics.

-L

Print out lock contention statistics. Use debug bit DEBUG_LOCK_CONTENTION to enable the lock contention statistics gathering.

-m

Print STREAMS memory allocation to the system messages file (from kernel).  This option should be used only for debugging and only when LiS is in a quiescent state.  Unpredictable results can occur if this option is used while LiS memory allocations are changing dynamically.

-p

Print the LiS lock trace buffer to the system messages file (from kernel).  Used in conjunction with the DEBUG_SPL_TRACE debug option.

-q

Print all STREAMS queues to the system messages file (from kernel).  This option should be used only for debugging and only when LiS is in a quiescent state.  Unpredictable results can occur if this option is used while LiS queue allocations are changing dynamically.

-S

Print out STREAMS queue-runner thread statistics.

-t

Print STREAMS timing statistics.  Used inconjunction with the DEBUG_MEAS_TIME debug option.

-T

Print the LiS semaphore latency histogram. Use debug bit DEBUG_SEMTIME to enable the statistics collection.

-h

Print a command synopsis.

-H

Print a command synopsis including the debug mask mnemonics.

Debug Options

The value that is used with the -d option consists of the logical "or" of the following single bit options.
 

-d Options

 
DEBUG_OPEN 0x00000001
DEBUG_CLOSE 0x00000002
DEBUG_READ 0x00000004
DEBUG_WRITE 0x00000008
DEBUG_IOCTL 0x00000010
DEBUG_PUTNEXT 0x00000020
DEBUG_STRRPUT 0x00000040
DEBUG_SIG 0x00000080
DEBUG_PUTMSG 0x00000100
DEBUG_GETMSG 0x00000200
DEBUG_POLL 0x00000400
DEBUG_LINK 0x00000800
DEBUG_MEAS_TIME 0x00001000
DEBUG_MEM_LEAK 0x00002000
DEBUG_FLUSH 0x00004000
DEBUG_FATTACH 0x00008000
DEBUG_SAFE 0x00010000
DEBUG_TRCE_MSG 0x00020000
DEBUG_CLEAN_MSG 0x00040000
DEBUG_SPL_TRACE 0x00080000
DEBUG_MP_ALLOC 0x00100000
DEBUG_MP_FREEMSG 0x00200000
DEBUG_MALLOC 0x00400000
DEBUG_MONITOR_MEM 0x00800000
DEBUG_DMP_QUEUE 0x01000000
DEBUG_DMP_MBLK 0x02000000
DEBUG_DMP_DBLK 0x04000000
DEBUG_DMP_STRHD 0x08000000
DEBUG_ADDRS 0x80000000

-D Options

 
DEBUG_SNDFD 0x00000001
DEBUG_CP 0x00000002
DEBUG_CACHE 0x00000004
DEBUG_LOCK_CONTENTION 0x00000008
DEBUG_REFCNTS 0x00000010
DEBUG_SEMTIME 0x00000020

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>

Back to Contents


strmakenodes

/usr/sbin/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.
 

Back to Contents


strtst

/usr/bin/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>
 

Back to Contents


timetst

/usr/bin/timetst [Iterations]

Description


timetst peforms a timing test using the LiS loopback driver.  It writes short messages downstream under several different LiS options and measures the round trip time for the messages.  The Iterations parameter specified the number of iterations that timetst uses in its timing loop, the default being 100,000.
 

Author

David Grothe <dave@gcom.com>
 

Back to Contents