Vectors, Variables, and Values

Design/Implementation/Documentation Conventions

My library software follows certain conventions that you might find useful to know when using or examining the software:

• In general, each source file ("obj_util.c") is a package of functions that operate on a particular type of object; e.g., a network connection, a hash table, etc. Associated with each package is a header file ("obj_util.h") which defines an opaque handle for objects of the given type, any global variables, and function prototypes for public functions in the package.
  
  
• Naming conventions for the functions that operate on objects are as follows:
  
  
  • objCreate() creates a particular type of object and returns a handle that is passed to other functions in the package.
  • objDestroy() destroys an object.
  • objAdd() and objDelete() are used to add and delete items in a container object; e.g., elements of a list, entries in a hash table, etc.
  
  I/O packages typically include the following functions:
  
  
  • objOpen() and objClose() create and destroy, respectively, objects of the given type.
  • objFd() returns the underlying UNIX file descriptor for an I/O object.
  • objIsReadable(), objIsWriteable(), and objIsUp() poll an I/O object.
  • objName() returns the name of an I/O object.
  • objRead() and objWrite() perform actual I/O on an object.
  
  
• Most of the library functions return an errno(3) status code as their value: zero indicates no error, EINVAL indicates an invalid argument, etc.
  
  
• vperror() is a perror(3)-like function that formats and prints a user error message on stderr, followed by the system error message corresponding to the current value of errno. vperror() output is enabled by setting a global variable, vperror_print, to a non-zero value.
  
  My library functions use vperror() to report errors (in addition to returning an error code). A rather primitive mechanism for reporting errors? You betcha - but at least it's there!
  
  Since vperror_print is initialized to zero, you normally won't see any error messages. My programs usually enable vperror() output during initialization (when configuration errors and such like may occur) and disable it thereafter. A command line option, "-vperror", is usually available to override this behavior.
  
  
• Most of the packages have a global obj_util_debug variable that can be set to a non-zero value to enable debug output to stdout.

More to follow when I think of it ...

Porting and Supported Platforms

In writing my software, I try make it as portable as possible. I make use of ANSI C libraries and header files as much as I can. Function declarations are made in both ANSI C and non-ANSI C form, so the code will compile whether your compiler is ANSI C-compliant or not.

The operating systems I'm using on my current project are: Solaris (SunOS 5.5 on Sun-4 and x86 platforms) and Lynx OS 2.4 (on a PowerPC), a real-time UNIX. For the previous 3 years, I used: SunOS 4.1.3 (on Sun-4 platforms), HP/UX, and VxWorks, a real-time, Unix-like OS running on 68040-based systems. Prior to that, I was on a project for which we ported earlier versions of much of this software from UNIX to VMS (VAX C and UCX TCP/IP).

The software distributions generally include the following Makefiles:

• Makefile.hpux - for building under HP/UX using their ANSI C compiler.
• Makefile.lynx - for building under Lynx 2.4 (Power PC) using gcc.
• Makefile.sun4 - for building under SunOS 4.1.3 using cc.
• Makefile.sun4os5 - for building under Solaris (Sun-4 platform) using gcc.
• Makefile.x86os5 - for building under Solaris (PC platform) using gcc.
• Makefile.vx68k - for building under VxWorks using cc68k.

(At one time, I tried setting up the networking library to use configure, but I got lost in the documentation and the process. configure is a great idea that's too darned complicated - I'm sure we should all be grateful for UNIX and open systems!)

I suspect that most of the non-OS-specific software would build without error on a PC. If someone will loan (or give) me a PC with Windows, I will be happy to test out my theory.

Acknowledgements

Thanks to the following people for bug and porting reports:

• Tom Dahm - ported LIBGPL to Linux. (NetMechanic, featured in Inter@ctive Week)
• Mathieu Frenette - ported the regular expression utilities to Windows 95. He also reported a bug in rex_wild(); if I was Donald Knuth, I'd pay him for it! (File Name Juggler)
• Örjan Leringe - ported the regular expression utilities to MS-DOS (Borland C version 3.1) and Windows (95? Visual C version 5). (A co-author of SAFT?)
• The XCORPUS Toolkit includes my hash table package.
• Thierry Le Blond has modified the hash table package to support fixed-length, binary keys.
• Nicolas Boghossian, the man of 1000 E-mail addresses, reported a memory allocation bug in rex_replace().
• $cott Dybiec - ported LIBGPL to Linux and AIX. (Human Factor)
• Laura Tweedy appears to be using some of my software in a COBOL-to-C translator.
• Kevin Esteb - corrected the regular expression utilities to handle full 8-bit characters. He also ported LIBGPL to Linux and parts of it to Alpha VMS 7.1.

I don't have the changes required for the various ports, but at least I know it's possible to port the code to the various platforms with relatively little trouble. My apologies to anyone I've left out, including those who reported bugs (e.g., in the quadword utilities and in the IPC utilities) before I started keeping a list here.

General Purpose Library (libgpl.tar.Z,)

Command Line Processing

opt_util - full-word option scanning package for UNIX-style command lines or strings.

Data Structures

gsc_util - generic depth-first and breadth-first graph search package.

hash_util - hash table creation/search package.

list_util - generic list handling package.

tpl_util - N-tuple creation and element retrieval.

Error Reporting

vperror - perror(3)-like error reporting function.

Files

drs_util - directory scanning package.

fnm_util - file name parsing package.

Interprocess Communication

The IPC packages provide named message queues, semaphores, and shared memory segments under UNIX and VxWorks. Earlier versions of the semaphore and shared memory packages were ported to VMS by Fred Shaklan and myself; message queues were not needed, but they could have been easily emulated using mailboxes. If I ever work on VMS again, I'll port the new packages; the package APIs are operating system-independent.

msq_util - high-level interface to named message queues (UNIX and VxWorks).

nob_util - named objects database package.

sem_util - high-level interface to named semaphores (UNIX and VxWorks).

shm_util - high-level interface to named shared memory (UNIX and VxWorks).

Memory Management

meo_util - memory operations.

String Manipulation

get_util - miscellaneous string scanning functions.

rex_util - full-featured regular expression matching and substitution package.

str_util - miscellaneous string handling functions.

Time

bmw_util - benchmarking package.

ts_util - POSIX timespec manipulation package.

tv_util - UNIX timeval manipulation package.

Miscellaneous

bit_util - bit manipulation functions.

xqt_util - shell execution package (high-level interface to UNIX shell or VMS CLI).

 

Networking (libnet.tar.Z,)

(This library distribution is a subset of the libgpl library, plus some test clients and servers.)

The following packages provide high-level, but powerful, interfaces to TCP/IP and UDP/IP networking:

tcp_util - high-level interface for TCP/IP network socket I/O.

udp_util - high-level interface for UDP/IP network socket I/O.

And the following packages implement higher-level protocols layered on top of the TCP_UTIL package:

lfn_util - high-level interface for LF-terminated network I/O.

nft_util - FTP server framework (UNIX, VMS, and VxWorks).

xnet_util - high-level interface to xdr(3)-based network I/O.

The NIX package simplifies the writing of I/O-event-driven applications (e.g., network servers):

nix_util - non-X-based, X Toolkit-style I/O and timer event dispatcher.

port_util - simple listening ports for NIX dispatcher-based network servers.

The remaining packages are an assortment of networking support functions:

net_util - miscellaneous network functions.

skt_util - socket support functions.

Version-Independent Messages

These three packages implement version-independent messages as described in Appendix B of Robert Martin's Designing Object-Oriented C++ Applications Using the Booch Method. (What he calls attributed data trees, I call name/value lists.) VIM network streams are layered on top of the TCP_UTIL package.

nvp_util - name/value pairs.

nvl_util - lists of name/value pairs.

vim_util - version-independent message streams.

C++ Library (libgplp)

Endpoint - generic network endpoint.

TcpEndpoint - TCP/IP endpoint.

BufferedTCP - buffered TCP/IP stream.

Dispatcher - I/O event dispatcher.

HashTable - hash table creation and search.

OptionsScan - full-word option scanning package for UNIX-style command lines or strings.

EPOCH Version 3 Library (libepl)

edb_util - EPOCH events database utilities.

epc_util - EPOCH network communications.

gv_util - EPOCH global variables.

ins_util - IN-SNEC CORTEX utilities.

nvf_util - named variable set files.

nvr_util - named variable utilities.

nvs_util - named variable sets.

EPOCH Version 3 Remote Access Library (liberal)

Endpoint - network endpoint.

TcpEndpoint - TCP/IP endpoint.

BufferedTCP - buffered TCP/IP stream.

EpochStream - EPOCH network stream.

EpochMessage - EPOCH network message.

NVar - named variables.

NVarSet - sets of named variables.

NVarFile - files of named variable sets.

GSegment - EPOCH global variable segments.

GVar - EPOCH global variables.

Dispatcher - I/O events dispatcher.

HashTable - hash table creation and search.

OptionsScan - command-line options scanning.

Applications

gentle

A network server that provides each client with its own Tcl interpreter, extended with networking and hardware debugging commands. (Derived from earlier programs, nicl and picl!)

npath

Collects function-by-function metrics for C source code. The metrics include lines-of-code, Halstead's Software Science volume, McCabe's cyclomatic complexity, and NPATH.

pose

A pocket FTP/WWW server, included in the libnet distribution.

Generic Tools

dump - formatted dump program.

ffc - format file in columns.

talknet - network talk utility.

Project-Specific Tools

cornet - CORTEX network tool.

direct - EPOCH directive submitter.

eire - EPOCH events reader.

epcot - EPOCH-CORTEX telemetry server.

glop - EPOCH global variable print.