gnu/libexec/uucp/libuuconf/README

   1 This is the README file for the beta release of the uuconf library.
   2
   3 It was written by Ian Lance Taylor.  I can be reached at ian@airs.com,
   4 or, equivalently, uunet!cygint!airs!ian, or c/o Cygnus Support,
   5 48 Grove Street, Somerville, MA, 02144, USA.
   6
   7 This package is covered by the Gnu Library General Public License.
   8 See the file COPYING.LIB for details.  If you would like to do
   9 something with this package that you feel is reasonable but you feel
  10 is prohibited by the license, contact me to see if we can work it out.
  11
  12 WHAT IT IS
  13
  14 This is a beta release of the uuconf library.  The uuconf library
  15 provides a set of functions which can be used to read UUCP
  16 configuration files.  V2, HDB, and Taylor UUCP configuration files are
  17 supported.
  18
  19 Also included are two programs, uuchk and uuconv.  uuchk will read
  20 configuration files and display the information it finds in a verbose
  21 format.  This can be helpful to ensure that your configuration files
  22 are set up as you expect.  uuconv can be used to convert configuration
  23 files from one type to another.  This is particularly helpful for
  24 people installing Taylor UUCP on a existing system who want to take
  25 advantage of the additional functionality provided by the Taylor UUCP
  26 configuration files.
  27
  28 This is strictly a beta release.  The library provides all the
  29 information needed for uuchk and uuconv, but does not yet provide
  30 everything needed for uucp or cu.  I am releasing it now to get
  31 feedback and to provide the uuconv program to people using Taylor
  32 UUCP.
  33
  34 This may well be the only time this library is release independently.
  35 This library will be provided with Taylor UUCP, and future releases of
  36 the library will probably only occur as part of the complete Taylor
  37 UUCP package.
  38
  39 HOW TO USE IT
  40
  41 Configure and optionally install the package as described in INSTALL.
  42
  43 The functions provided by the library are described in uuconf.h.  At
  44 the moment there is no additional documentation.
  45
  46 Programs which use the library should include uuconf.h, and should not
  47 include any of the other header files.  The functions listed in
  48 uuconf.h all begin with the string "uuconf_".  The internal library
  49 functions all begin with the string "_uuconf_".  The internal library
  50 functions should not be called by a program which uses the library, as
  51 they may change in future releases.  The uuchk program is an example
  52 of program which uses the library; uuconv is not, as it relies upon
  53 internal data structures.
  54
  55 The uuchk program takes a single optional option, -I, which may be
  56 used to specify an alternate Taylor UUCP main configuration file.  The
  57 default configuration file is $(newconfigdir)/config ($(newconfigdir)
  58 is defined in Makefile).  For example:
  59     uuchk
  60     uuchk -I /usr/tmp/tstuu/Config1
  61
  62 The uuconv program requires two options: -i to specify the input type
  63 and -o to specify the output type.  Both options take a string
  64 argument, which must be one of "v2", "hdb", or "taylor".  uuconv also
  65 takes an optional -I option, which is the same as the -I option to
  66 uuchk.  The conversion is not intended to be perfect, and the results
  67 should be manually inspected.  In particular, the dialcode file is not
  68 converted (as the format is the same for all three configuration file
  69 types, it may simply be copied to the appropriate new name).  uuconv
  70 will create new files in the current working directory.  For example:
  71     uuconv -i hdb -o taylor
  72     uuconv -i taylor -I /usr/tmp/tstuu/Config1 -o v2
  73
  74 NOTES
  75
  76 The initial underscore on the internal library functions is required
  77 by the GNU standards.  As ANSI C reserves external identifiers with an
  78 initial underscore for the implementation, it is possible, though
  79 unlikely, that this will cause problems on other implementations; no
  80 workaround is currently provided for such problems.
  81
  82 The library functions rely upon the following functions:
  83
  84     fclose      fopen       free        fseek
  85     ftell       getc        isalpha     isdigit
  86     islower     isspace     isupper     malloc
  87     realloc     rewind      strchr      strcmp
  88     strcspn     strlen      strncmp     strspn
  89     tolower     toupper
  90
  91 and the following header files:
  92
  93     ctype.h     errno.h     stdio.h
  94
  95 If the following functions cannot be found by the configure script,
  96 replacements will be used (the replacement for strerror is Unix
  97 dependent):
  98
  99     getline     memcpy      strcasecmp  strdup
 100     strerror    strncasecmp strtol
 101
 102 If the following header files are found, they will be included:
 103
 104     libc.h      limits.h    memory.h    stddef.h
 105     stdlib.h    string.h    strings.h   sys/types.h
 106
 107 The following functions are required on Unix only:
 108
 109     fcntl       fileno
 110
 111 The following headers are used, if found, on Unix only:
 112
 113     fcntl.h     sys/file.h