freebsd-src/gnu/libexec/uucp/libuuconf

This is the README file for the beta release of the uuconf library.

It was written by Ian Lance Taylor.  I can be reached at ian@airs.com,
or, equivalently, uunet!cygint!airs!ian, or c/o Cygnus Support, 
48 Grove Street, Somerville, MA, 02144, USA.

This package is covered by the Gnu Library General Public License.
See the file COPYING.LIB for details.  If you would like to do
something with this package that you feel is reasonable but you feel
is prohibited by the license, contact me to see if we can work it out.

WHAT IT IS

This is a beta release of the uuconf library.  The uuconf library
provides a set of functions which can be used to read UUCP
configuration files.  V2, HDB, and Taylor UUCP configuration files are
supported.

Also included are two programs, uuchk and uuconv.  uuchk will read
configuration files and display the information it finds in a verbose
format.  This can be helpful to ensure that your configuration files
are set up as you expect.  uuconv can be used to convert configuration
files from one type to another.  This is particularly helpful for
people installing Taylor UUCP on a existing system who want to take
advantage of the additional functionality provided by the Taylor UUCP
configuration files.

This is strictly a beta release.  The library provides all the
information needed for uuchk and uuconv, but does not yet provide
everything needed for uucp or cu.  I am releasing it now to get
feedback and to provide the uuconv program to people using Taylor
UUCP.

This may well be the only time this library is release independently.
This library will be provided with Taylor UUCP, and future releases of
the library will probably only occur as part of the complete Taylor
UUCP package.

HOW TO USE IT

Configure and optionally install the package as described in INSTALL.

The functions provided by the library are described in uuconf.h.  At
the moment there is no additional documentation.

Programs which use the library should include uuconf.h, and should not
include any of the other header files.  The functions listed in
uuconf.h all begin with the string "uuconf_".  The internal library
functions all begin with the string "_uuconf_".  The internal library
functions should not be called by a program which uses the library, as
they may change in future releases.  The uuchk program is an example
of program which uses the library; uuconv is not, as it relies upon
internal data structures.

The uuchk program takes a single optional option, -I, which may be
used to specify an alternate Taylor UUCP main configuration file.  The
default configuration file is $(newconfigdir)/config ($(newconfigdir)
is defined in Makefile).  For example:
    uuchk
    uuchk -I /usr/tmp/tstuu/Config1

The uuconv program requires two options: -i to specify the input type
and -o to specify the output type.  Both options take a string
argument, which must be one of "v2", "hdb", or "taylor".  uuconv also
takes an optional -I option, which is the same as the -I option to
uuchk.  The conversion is not intended to be perfect, and the results
should be manually inspected.  In particular, the dialcode file is not
converted (as the format is the same for all three configuration file
types, it may simply be copied to the appropriate new name).  uuconv
will create new files in the current working directory.  For example:
    uuconv -i hdb -o taylor
    uuconv -i taylor -I /usr/tmp/tstuu/Config1 -o v2

NOTES

The initial underscore on the internal library functions is required
by the GNU standards.  As ANSI C reserves external identifiers with an
initial underscore for the implementation, it is possible, though
unlikely, that this will cause problems on other implementations; no
workaround is currently provided for such problems.

The library functions rely upon the following functions:

    fclose      fopen       free        fseek
    ftell       getc        isalpha     isdigit
    islower     isspace     isupper     malloc
    realloc     rewind      strchr      strcmp
    strcspn     strlen      strncmp     strspn
    tolower     toupper

and the following header files:

    ctype.h     errno.h     stdio.h

If the following functions cannot be found by the configure script,
replacements will be used (the replacement for strerror is Unix
dependent):

    getline     memcpy      strcasecmp  strdup
    strerror    strncasecmp strtol

If the following header files are found, they will be included:

    libc.h      limits.h    memory.h    stddef.h
    stdlib.h    string.h    strings.h	sys/types.h

The following functions are required on Unix only:

    fcntl       fileno

The following headers are used, if found, on Unix only:

    fcntl.h     sys/file.h