Linux STREAMS (LiS)

Contents

LiS Library Routines

Using the LiS Library
 

Introduction

During the installation process of Linux STREAMS (LiS) a subroutine library is built and installed on your system.  Three versions of the library are built and installed.  They are as follows.
 

These three libraries are copied to the directory /usr/lib when LiS is installed.

In addition, the utility program ldconfig is run during the LiS make install.  This causes this library to be linked, or searched, ahead of the standard C library.  This is necessary because the standard C library contains dummy routines for the STREAMS interface functions, or most of them in the best case.  If these dummy routines preempt the LiS versions then STREAMS applications will always perceive error returns from such routines as getmsg and putmsg.

Back to Contents

LiS Library Routines

The following routines are present in the libraries libLiS.a and libLiS.so.  The library libpLiS.so omits the "pipe" routine.

The routines in these libraries are standard STREAMS interface routines.  As such we do not offer detailed descriptions of the functions of these routines.  Instead we refer the reader to the AT&T SVR4 STREAMS documentation.

int     fattach(int fd, const char *path)          
int     fdetach(const char *path) 
int     getmsg(int fd, void *ctlptr, void *dataptr, int *flagsp) 
int     getpmsg(int fd, void *ctlptr, void *dataptr, int *bandp, int *flagsp) 
int     isastream(int fd) 
int     pipe(int *fd) 
int     poll(void *pollfds, long nfds, int timeout)          
int     putmsg(int fd, void *ctlptr, void *dataptr, int flags) 
int     putpmsg(int fd, void *ctlptr, void *dataptr, int *bandp, int *flagsp)        

These routines are all very small pieces of code.  Most of them simply pass their parameters to LiS via a system call.  The fattach and fdetach routines use ioctls to LiS if there is no system call available to call directly.

The poll routine simply executes the poll system call.  It is present for backward compatibility to 2.0 kernels, in which LiS provided the poll system call.

The pipe routine has the same semantics as the standard C library routine.  It uses STREAMS FIFOs to implement the pipe instead of the standard Linux pipes.

The libpLiS.so library, the one that preempts the standard C library, omits the STREAMS pipe routine so that standard Linux pipes are used unless the user explicitly links in libLiS.

Back to Contents

Using the LiS Library

In order to use one of the LiS libraries you should include the file <sys/stropts.h> in you program source code.  On you compiler command line you can add the option "-I/usr/src/LiS/include" to include the version of stropts.h that is distributed with LiS, or omit the option to include the system standard header file.  The two header files are believed to be compatible enough that it does not matter which one you include in your program.

When linking your program, or performing a final "cc" to build your executable, include one of the following options on your command line.
 

/usr/lib/libLiS.a	Use libLiS.a (static, includes "pipe")
-lLiS	Use libLiS.so (dynamic, includes "pipe")
-lpLiS	Use libpLiS.so (dynamic, omits "pipe")
Omit any options	As of libc-2.2.1 the LiS STREAMS interface routines will be used automatically via libpLiS.so.

Back to Contents