libnetmar - The Netmar C Library

PURPOSE

WELCOME! The functions documented below and on the attached pages represent the bulk of the programming work that we've saved over our years of operation here at Netmar. We have saved the more flexible functions from all the software we've written so that future programs we write could be implemented more quickly and easily and without reinventing the wheel every time.

As these functions have helped us tremendously in writing new software over the years, we hope they will help you too. So, we've taken the unprecedented step of making these functions available to you, our customers, for use in your own programs, as a complete C library. And while we can't release the full source code of the library, we have created a standard C archive library to which you can link your C programs upon compilation to use any of these functions.

USAGE

To use libnetmar, you need to do only two things:

  1. Insert an include for the netmar.h header file in each of your C source files that references one of the libnetmar functions
    (e.g. "#include <netmar.h>"), and
  2. Link your program with -lnetmar upon compilation
    (e.g. gcc -o myprogram myprogram.c -lnetmar)

That's it! You can then use any of the functions in libnetmar in your C programs and CGI scripts.

TESTING & SUPPORT

All of the functions in libnetmar have been independently tested (outside of the program for which they were designed) and then used successfully in a program. So, while we can't guarantee the entire library is bug free, we do know that all of these functions work because they have all been tested and used in a real life environment.

If, however, you find something that you think is a bug, we would be appreciative if you would point it out to us, and tell us in as much detail as possible, how you came upon it. If ths situation caused your program to crash, we would appreciate you saving a core file for us. You can do this by typing "limit coredumpsize unlimited" at the command prompt before running the program. Please note that if your program is a CGI script, you can still run it from the command line to debug it by using the cgi_assign or getcgidata functions from the library.

As these function were written by us and are being made available to our customers as part of the webhosting service we offer, Netmar provides full technical support for users of the library. However, please note that Netmar technical support does not offer tutoring or support for the C programming language itself. If you don't understand how to write or compile your program, please consult your reference materials.

CGI Section
This section contains functions for use in writing CGI scripts. If you're writing a script, you want to use assign (with getcgidata) or cgi_assign as these fully automate the input task while also including a debugging interface. These function calls, together with fsend or tfsend, reduce the I/O portions of code in a CGI program to as little as two lines (one function call to read input, and one to send all output).

Other functions allow you to do some more advanced tasks, like sending your data to another CGI script via a POST request and encoding/decoding HTML and URL encoded strings.

If you're writing a CGI script, you'll also want to see the tfsend function in the next section.

  • assign- Assign CGI variable data directly to C variables from an existing data structure.
  • cgi- Get data from CGI or simulated input.
  • cgi_assign- Assign CGI variable data directly to C variables directly from the CGI input data.
  • checked- Retrieve checkbox information from a standard format CGI data output file.
  • getcgidata- Automatically get data from the appropriate type of CGI or simulated input.
  • getgetdata- Get data input via a HTTP GET request for a CGI script.
  • getmockdata- Get data input via keyboard and return it in the same form as CGI data.
  • getpostdata- Get data input via a HTTP POST request for a CGI script.
  • getval- Retrieve variable information from a standard format CGI data output file.
  • header- Determine if a line in a standard format CGI data output file contains a variable name and header.
  • htencode- HTML encode a string (by escaping <, >, &, and " characters)
  • htpost- Send a POST data body to an HTTP server via a POST request, returning the results to open file pointers.
  • htpost_s- Send a POST data body to an HTTP server via a POST request, returning the results to character array pointers.
  • makepost- Construct a POST data body.
  • repost- Send an existing CGI data structure to an HTTP server as a POST data body.
  • unescape_url- Unescape a string containing URL escaped characters.
  • urlencode- Encode a string by URL escaping certain characters.

Data Handling Section
The functions in this section provide various methods for reading, writing, and manipulating data. Mostly, these functions serve as shortcuts for what would otherwise be oft-typed repetitive code in a program. With the exception of the fsend, tfsend, and pgp_enc functions, these functions are mostly just shortcuts.

  • database- dbm, ndbm, and gdbm database interface routines
  • dbfget- retrieve an float from a dbm, ndbm, or gdbm database
  • dbfstore- store a float in a dbm, ndbm, or gdbm database
  • dbiget- retrieve an integer from a dbm, ndbm, or gdbm database
  • dbistore- store an integer in a dbm, ndbm, or gdbm database
  • dblget- retrieve an long integer from a dbm, ndbm, or gdbm database
  • dblstore- store a long integer in a dbm, ndbm, or gdbm database
  • dbsget- retrieve a string rom a dbm, ndbm, or gdbm database
  • dbsstore- store a string in a dbm, ndbm, or gdbm database
  • fsend- Parse and output a file using ordinal subcodes
  • grep- Search through lines of text
  • imakedatum- Convert an integer into data type datum suitable for storage in a database
  • makedatum- Convert data into data type datum suitable for storage in a database
  • makekey- Make a key for storing data in a dbm, ndbm, or gdbm database
  • pgp_enc- Encrypt a string using PGP
  • smakedatum- Convert a string into data type datum suitable for storage in a database
  • tfsend- Parse and output a file using nominal substitution codes (for CGI output mainly)

Miniature Tools Section
This section consists of functions that do various sundry tasks that could just be made easier and reusable by creating a separate function. So we did. Nothing here is earth-shattering. The things accomplished by these functions could be done by most programmers, regardless of level, but would just take time to code. So these functions are mainly just for convenience. You'll notice that some are for some very specific tasks. These are tasks that we needed to accomplish in writing certain program. The usefulness of some of these functions outside of the programs for which they were written is probably questionable. But the functions were already written, so we're including them in this secion.

  • cat- Output a file to stdout
  • dconvert- Convert the day number into a date for this year
  • fcat- Output a file to a file pointer
  • getname- Retrieve the full name of a user from the system password file
  • gettime- convert minutes and seconds portion of HTTP log format time string to integer
  • itoa- Convert integer to string without using sprintf()
  • itoh- Convert integer to string showing hexadecimal value without using sprintf()
  • minfo- Show mallinfo() (memory arena) information (Solaris only)
  • rnd- Generate random integers
  • rprintf- Pad output with spaces
  • seconds- Convert seconds to minutes and seconds
  • tail- Show trailing lines of a file (with no limit)
  • wdwrap- Wrap lines of a text file
  • whois_check- Check for domain name availability of InterNIC-delegated domains
  • xwdwrap- Wrap lines of a text file at any length and check for solid lines

Miscellaneous Tools Section
This section also contains functions that are mostly for convenience (providing simple functionality). But these functions are more likely to be of interest to programmers for use in more programs as the functionality provided is more commonly needed in CGI and Unix programming.

  • authenticate- Authenticate login/password against a Unix/htpasswd style password file
  • ccard_valid- Determine if a supplied credit card number could be a valid card number
  • cdate- Convert a date string from one format to another
  • crstrip- Strip trailing CR and LF characters from a string
  • domcheck- Determine if a string is a properly formatted domain name (no validity check)
  • emailcheck- Determine if a string is a properly formatted email address (no validity check)
  • envcpy- Copy current environment to a string for use with the env command
  • fphd2user- Determine user in whose home directory a filepath resides (read from fp)
  • hd2user- Determine user in whose home directory a filepath resides
  • ishost- Determine if a string is a properly formatted hostname (no validity check)
  • isweb- Determine if a string is a properly formatted WWW URL (no validity check)

Network Section
Network programming traditionally has required a platform specific level of understanding that is often beyond most novice programmers and even many intermediate and advanced programmers. It is almost always well beyond a programmers that is new to the platform. So, we have saved as separate functions, the code we have used in the past to communicate over TCP/IP sockets.

There are two sets of functions here. One is a medium level interface, which provides direct interaction with the TCP/IP socket with no buffering, while the other, a high level interfare, provides a buffered, error-controlled, and timed interface almost exactly identical to the file I/O interface provided by the stdio functions fgets and fputs.

  • call- Initiate a TCP/IP connection to the given host and port (high-level interface)
  • callsock- Initiate a TCP/IP connection to the given host and port (medium-level interface)
  • sgets- Get a string from the given TCP/IP session (medium-level interface)
  • sockclose- Close a TCP/IP connection (high-level interface)
  • socket- Medium level interface to TCP/IP sockets
  • sockgets- Get a string from the given TCP/IP session (high-level interface)
  • sockputs- Write a line to a TCP/IP connection (high-level interface)
  • sread- Read data from a TCP/IP connection (medium-level interface)
  • swrite- Write data to a TCP/IP connection (medium-level interface)
  • tcputil- High leve interface to TCP/IP sockets

String Tools Section
It has often been said that one of the main advantages of Perl over C is the ease of string manipulation built into the Perl language. The functions in this section provide a higher level of control over strings than that provided by the ANSI C string.h functions.

  • ccut- Cut text by column number (like /usr/bin/cut -c)
  • comma- Convert integer to string with commas for numbers over 1,000
  • fcount- Count number of fields in a string separated by a given separator character
  • fcut- Cut text by field (like /usr/bin/cut -d)
  • mfcut- Cut multiple fields of text (like /usr/bin/cut -d)
  • strcaseconv- Convert string case to all upper or all lower
  • strcasestr- Case insensitive string search (like strstr)
  • strip- Strip leading and/or trailing repeptitive characters
  • subst- Search and replace text in a string
  • xsubst- Search and replace text in a string globally or one per string