Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume1/8708/20/README.PORT

Text File | 1990-07-13 | 12.3 KB | 302 lines

uupc Porting Information     August 3, 1987      uupc Development


This writeup is aimed at programmers intending to port uupc to
machines and operating systems which it don't currently run on.
If you only want to install uupc on a system where a uupc port
exists, this writeup might also provide some insights to the
internal working of uupc and make the installation of uupc on
your machine a more interesting task.

Since I did part of the IBM-PC/MS-DOS port for uupc, what I will
describe here is actually closely related to the structure of
this particular port.  (I also did part of the port of uupc's
mailer to AIX (SVR1) on the RT-PC.)  What is shown here is *by no
mean* the only way things could be done, it's just some tips and
hints that I can think of after doing one-and-a-half port of
uupc.

The purpose of this writeup is to try to make the life of
programmers doing uupc ports for other machines/operating systems
easier.  However, the best sources of information on how new
ports should be done is still by reading the system-dependent
code of the existing uupc ports.  (This is how I learnt how to do
my ports.)  It would also be useful to have a listing of the
system-dependent code of the IBM-PC/DOS port handy while reading
this writeup.


To compile uupc, the C compiler and linker on your system must be
able to differentiate between upper and lower cases in external
names.

The C run-time support on your system should use '\n' as line
separator for *text* files.  If your system uses other sequences
or methods to delimit text file lines, the C run-time support
must perform the appropriate translation functions for mapping in
both directions when a file is opened in text mode.

In order to port uupc to a new machine/operating system, you have
to come up with a new version of six system-dependent files in
the the "local" directory.  The names of these six files in the
local directory are host.h, host.c, mlib.c, ulib.c, ndir.h and
ndir.c.

Note that theses files could in turn #include other *.c and *.h
files if you wish to separate the system-dependent code into more
small files.  The important thing here is that they must
collectively provide the same set of routines, global variables,
and environment to the common code.

What should be contained in these six files are describe below:


host.h - Host dependent file virtual #included everywhere else.

   Almost every file in both the common and host-dependent code
   include this header file.  So it should contains all the
   #includes, #defines, and externs that everybody would need.

   Parts of the uupc common code assume Berkeley-style index()
   and rindex(), so if your system supports only SysV-style
   strchr() and strrchr(), they need to mapped using #define
   here.

   Declarations for "library" routines in host.c, mlib.c and
   ulib.c should also be make here to made them known to the rest
   of the world.  However, declaractions for the directory
   scanning routines should be put into ndir.h instead.

   If your system requires that text file and binary fiies be
   opened differently, you should map the name 'FILEMODE' into
   'filemode' with a #define here.  Otherwise, 'FILEMODE' should
   be mapped to the null string.


host.c - Generic main program and library routines for both parts.

   This file includes a generic main program that simply starts
   up and call the procedure MAIN.  More importantly, the
   definition of all the library routines that are needed by both
   uu and mail are also here.

   This generic main program is used to start up both uu and
   mail, by having the preprocessor symbol MAIN #defined to
   different procedure names in the files which include host.c.
   This generic main program should perform all the necessary
   start up and wrap up functions as required by the host
   operating system and call the routine MAIN while the host
   environment is established.

   If the preprocessor symbol CWDSPOOL is #defined by the file
   that #includes host.c, the main program should change the
   current working directory to the spooling directory before
   calling MAIN, and switch back to the orginal directory after
   MAIN had returned.

   The following are the other routines residing in host.c and
   used by the others parts of both uu and mail:

   importpath - A deterministic function which maps a canonical
      file name to a local file name.  This function must be
      deterministic (i.e. always return the same local name when
      given the same canonical name) because it is used on each
      canonical file name several times in various part of the
      code to obtain the corresponding local file name.

      A canonical file name has the same format as a UNIX
      pathname, and the format of a local file name is defined by
      your local file system.

      This function should at least preserve the first 6 and last
      2 characters of the canonical file name, since this parts
      of the canonical file name usually contain the site name
      and the sequence number, which is critical to the
      successful operation of uupc.

      Perferably the last 4 characters of the canonical file name
      should be perserved, since that is the number of digits in
      the sequence number, but if that is not possible, an
      attempt should be made to preverse the last 3 characters
      before resorting to only preserve the last 2 characters.
      (With only the last 2 characters preserved, the spool file
      sequence number cycle will become only 100 before it goes
      around again.)

   mkfilename - Build a local path name out of a given local
      directory path and local base name pair.  It usually just
      concatenates the two parts together with the local system's
      directory path separator between them.

   loadenv - Retrieve certain configuration parameters from the
      user's "environment" and make them available to the
      program.  This involves filling in the appropriate global
      (char *) variables to point to the appropriate strings
      which contains the character value of the desired
      configuration parameters.

   If your system requires the differentiation of text file and
   binary files, you should also supply the following routine.

   filemode() - If this routine is passed the character 't' as
      parameter, any subsequently opened file in the program
      should be opened in text mode.  Similarly, if the parameter
      is the character 'b', all subsequently opened file should
      be opened in binary mode.


mlib.c - Library of routines used only by the mail part.

   Currently there is only one routine in this library.

   get_one - Wait for a single character to be typed on the
      console keyboard and return to the caller with the
      character read as soon as it is pressed.  It short, this is
      a routine that detects and returns a keypress.

      This routine is used when you reach the bottom of a page
      while paging through your mail.

      The single character read by this routine should not be
      echoed to the console screen.


ulib.c - Library of routines used only by the uu part.

   login - The logger which verifies logins and passwords for
      incoming UUCP connections.  You only need to have this
      routine functional if you plan to ever run your node in
      slave mode.  i.e. Waiting on the phone line for other nodes
      to call you to make UUCP connections.

   shell - Perform an UNIX command sent from a remote site via
      uux.  To support incoming remote mail you need to emulate
      the UNIX 'rmail' command, which can be easily done using
      the pcmail package (compiled as rmail) which is part of
      this uupc distribution.  If you want to also support
      incoming USENET news-feeds, the UNIX 'rnews' command will
      need to be supported as well.

      If your system is capable of invoking another program
      within a program, you might want to dispatch rmail and
      rnews as a separate program here.  Otherwise, you might
      need to compile, or link, them into uu as routines.

   sleep - Wait a specified number of seconds in real-time.  You
      could either use a busy wait loop or a timer alarm here,
      depending on if your system has other (e.g. background)
      jobs competing for CPU time at the same time.  On mutli-
      tasking or multi-users systems, you would likely *not* want
      to busy wait even if that's easier to implement.

   The rest of this library consists of routines to deal with the
   communications line (serial port).

   openline - Open a communications line as the active line.  The
      name of the serial line device and the speed to open the
      line at are *both* specified as (char *) type parameters.
      These value are just the corresponding values in the
      systems file entry of the site being called.

   sread - Read a specified number of bytes from the active
      serial line and return with *no* input characters consumed
      *if* the specified number of bytes is not available after
      the specified timeout period.  This is basically a non-
      blocking read that waits up to an user-specified amount of
      time before returning.

   swrite - Write a specified number of bytes out to the active
      serial line.  No timeout mechanism needs to be provided by
      this routine.

   closeline - Close the active communications line.

   SIOSpeed - Change the line speed of the active communications
      line on-the-fly.  The new line speed is given as (char *)
      rather than (int).  Note the mixed-case nature of this
      routine name.


ndir.h - Header file for the directory scanning routines.

   At least the following needs to be defined in this file.

   -- The constant 'MAXNAMLEN' declared with "#define".  This is
      the maximum length of a file name in your system.  Note
      that a file name does not include a directory path prefix,
      it is only the maximum length of a file name within a
      directory.

   -- The structure 'direct' declared with "struct".  This
      structure is a public data structure and its fields are
      examined directly by uu, so your declaration needs to
      provide at least the following fields:

      struct direct {
         short d_reclen;
         short d_namlen;
         char  d_name[MAXNAMLEN + 1];
      };

      d_reclen is the length of the structure minus the size of
      the unused portion of d_name at the end of the structure.

      d_namelen is strlen(d_name).

      d_name is the name of the next file in the scan, with a
      terminating '\0'.

      It is important for the structure 'direct' to be defined
      using "struct" insted of "typedef".

   -- The type 'DIR' declared with "typedef".  This is a private
      structure used by the ndir routines and should contain all
      the static data related to a single invocation of the ndir
      routines.

      It is important for 'DIR' to be defined using "typedef"
      instead of "struct".  (Note this is the *reverse* of the
      structure 'direct' above.)

   -- The routines opendir(), readdir(), and closedir().  Which
      opens a specified directory, read the next file entry from
      an opened directory, and close an opened directory,
      respectively.


ndir.c - "Berkeley-style" directory scanning routines.

   This file contains a set of routines similar in functions to
   the Berkeley-style directory scanning routines.  These
   routines are used only by uu, not mail, and only the
   opendir(), readdir(), and closedir() routines are used, and
   therefore need to be implemented.

   Eventhough the ndir routines should be capable of mutliple
   concurrent invocations using separate (DIR *)'s, uu only uses
   one invocation of it at a time.

   If your system's file name is mono-case, then your readdir()
   routine should always return the file name field (d_name) in
   all lowercase.


Any questions about porting uupc to other machines/operating
systems, and comments and suggestions about this writeup should
be directed to one of the e-mail addresses listed at the end of
this file.

If you do decide to start porting uupc to a new machine/operating
system, please drop us a line as well.  We might even be able to
save each other some duplicated efforts!


UUCP: {seismo,ihnp4!alberta,uw-beaver,uunet}!ubc-vision!van-bc!uupc
Internet: [e-mail]
-------


--
{ihnp4!alberta!ubc-vision,uunet}!van-bc!Stuart.Lynne Vancouver,BC,604-937-7532