SyncDir Notes
-------------
This was an attempt at making a platform independant program, and
it seems I succeeded in as much as it works under DOS, Windows 95,
and Unix, though all are very similar. It would be more interesting
to see a VMS port.

The directory structure is as follows:

syncdir
   + dos
   |   DOS functional code
   + gnu
   |   gnu functional code
   + nt
   |   WIN32 functional code
   + shared
       code that is shared by all. this is the actual ``syncdir''
       code without any platform specific or UI code.

The file ``shared\syncdir.h'' contains the comments pertinent to
porting the code. The ported code is defined by two sections: functional
contains the code needed to to perform functions, and UI contains code
to interact with the user.

Functional
==========
Note: see os_h.txt for a description of required OS definitions

int sysError(void)
  Entry: none
  Exit:  last system error value
  Description:
    This is ``errno'' on most systems. Unfortunatly, multi-threaded
    Win32 apps define ``errno'' as a function which confuses everything.

FILETABLE *fileTableInit(const char *name, BOOL create);
  Entry: {name}   points to the full path of directory to create
         {create} contains FALSE if this path must exist, or
                    TRUE if it may be created
  Exit:  a valid FILETABLE * on success
         0 on error
  Description:
    This function does the necessary validation, and returns
    with a call to fileTableAlloc(...) on success.

BOOL directoryScan(FILETABLE *tbl);
  Entry: {tbl} points to a FILETABLE returned by fileTableInit(...)
  Exit:  TRUE if the directory was scanned successfully
         FALSE on error
  Description:
    Scan the directory, adding all entries that match the include mask, but
    not the exclude mask to the file table.

BOOL directoryDelete(const char *name);
  Entry: {name} points to the full path of the directory to delete
  Exit:  TRUE if directory was deleted, FALSE on failure
  Description:
    Remove the specified directory. This should remove all files and 
    subdirectories.

BOOL directoryCreate(const char *name);
  Entry: {name} points to the full path of the directory to create
  Exit:  TRUE if directory was successfully created, FALSE if not
  Description:
    Create the specified directory. 

BOOL fileDelete(const char *name);
  Entry: {name} points to the full path of the file to delete
  Exit:  TRUE if the file was deleted, FALSE if not
  Description:
    Remove the specified file.

FILEHANDLE fileOpen(const char *name);
  Entry: {name} points to the full path of the file to open
  Exit:  an implementation defined  FILEHANDLE
  Description:
    Open the specified file for reading.

FILEHANDLE fileCreate(const char *name, UINT32 sz);
  Entry: {name} points to the full path of the file to create
         {sz}   contains the size of the file which will be written
  Exit:  an implementation defined FILEHANDLE
  Description:
    Create the file specified. On some systems (notably DOS and Windows 95), 
    it is more efficient to preallocate the file length before actually
    writing. On others (unix) this preallocation has no effect or 
    (in Windows NT) is detrimental to performance.

BOOL fileHandleIsValid(FILEHANDLE f);
  Entry: {f} contains the FILEHANDLE returned by fileOpen(...) or 
             fileCreate(...)
  Exit:  TRUE if this is a valid file handle, else FALSE
  Description:
    This is used to determine the success or failure of fileOpen(...)
    and fileCreate(...)

UINT32 fileLength(FILEHANDLE f);
  Entry: {f} contains a valid FILEHANDLE returned by fileOpen(...)
  Exit:  the length of the file
  Description:
    Get the length of the file represented by {f}.

UINT32 fileRead(FILEHANDLE f, void *dst, UINT32 len);
  Entry: {f}   contains a valid FILEHANDLE returned by fileOpen(...)
         {dst} points to the destination buffer
         {len} contains number of bytes to read
  Exit:  number of bytes read
  Description:
    Read {len} bytes from {f} into {dst}.

UINT32 fileWrite(FILEHANDLE f, const void *src, UINT32 len);
  Entry: {f}   contains a valid FILEHANDLE returned by fileCreate(...)
         {src} points to the source buffer
         {len} contains the number of bytes to write
  Exit:  number of bytes written
  Description:
    Write {len} bytes from {src} to {f}

BOOL fileClose(FILEHANDLE f);
  Entry: {f}  contains a valid FILEHANDLE returned by fileOpen(...) or 
              fileCreate(...)
  Exit:  TRUE if close was successful, else FALSE
  Description:
    Close the specified file.

int fileInfoDateCompare(const FILEINFO *a, const FILEINFO *b);
  Entry: {a} points to a FILEINFO structure
         {b} points to a FILEINFO structure
  Exit:  -1 if a < b, 0 if a = b, 1 if a > b
  Description:
    Compare the date component FILEINFO structures. The date should be held
    in the OS_FILEINFO structure that is filled in during the 
    directoryScan(...) operation.

int fileInfoNameCompare(const FILEINFO *a, const FILEINFO *b, BOOL partial);
  Entry: {a}       points to a FILEINFO structure
         {b}       points to a FILEINFO structure
         {partial} contains TRUE if the compare length will not exceed the 
                   length of the name in {a}
  Exit:  -1 if a < b, 0 if a = b, 1 if a > b
  Description:
    Compare the name component of FILEINFO structures.
    If {partial} is TRUE, only the bytes up to length of the name in {a} are
      compared.

BOOL fileAttrGet(const char *name, FILEATTR *sts);
  Entry: {name} points to a source file or directory
         {sts}  points to an implementation defined attribute structure
  Exit:  {sts} is filled with the file attributes of {name} and TRUE returned
         on success, FALSE returned on fail.
  Description:
    Called at the beginning of a file copy, before the file is opened. Used
    to transfer file attributes to the destination file, and to reset the
    source attributes to those in place before the copy begins. On systems
    that maintain a modifiable ``last accessed'' time, this prevents the
    modification of this field.

BOOL fileAttrSet(const char *name, const FILEATTR *sts);
  Entry: {name} points to a destination file or directory
         {sts}  points to the file attributes retrieved from fileAttrGet(...)
  Exit:  TRUE if the file attributes were set, FALSE if not.
  Description:
    Called after a successful file copy to set the destination attributes,
    and after closing the source file to reset its attribues.

Note: The following function are only used by ``sfiletbl.c''

FILE *fileTempCreate(void);
  Entry: none
  Exit:  a FILE * opened for reading and writing binary data, or 0 on failure
  Description:
    Many systems provide a default implementation for opening temporary
    files which are automatically deleted on close. ANSI defines
    ``tmpfile()'' to do just that. Unfortunatly, the Microsoft C library
    puts the temporary file in the root directory of the current drive.
    Since this is not guarenteed to be writable, I had to overload this
    function.

BOOL fileTempDestroy(FILE *f);
  Entry: the FILE * returned by fileTempCreate(...)
  Exit:  TRUE if this file was successfully destroyed, else FALSE
  Description:
    Close the file and delete it.

UI
==
void showHelp(const char *str);
  Entry: {str} points to one of the HELP_* strings, or 0
  Exit:  none
  Description:
    Display the help screen for this version. Called by the parser on error.

BOOL queryAction(const char *src, const char *dst, ACTION act)
  Entry: {src} points to the source of the action
         {dst} points to the destination of the action (0 if ACTION_DELETE)
         {act} contains the action to be performed
  Exit:  TRUE  if action may be completed,
         FALSE if not
  Description:
    Query the user for an action.

Note:  the following functions are not called if OPT_QUIET is specified

void showBegin(void)
  Entry: none
  Exit:  none
  Description:
    Called after the log file has been successfully opened.

void showComplete(void)
  Entry: none
  Exit:  none
  Description:
    Called after all actions have been completed. 
    Note: this call could appear without a call to showBegin(...) if a 
    serious error occurs while parsing the command line or opening the 
    log file.

void showProcessBegin(UINT32 amt)
  Entry: {amt} contains the number of files to be processed
  Exit:  none
  Description:
    Called at the beginning of the process phase.

void showProcessUpdate(UINT32 amt, UINT32 complete)
  Entry: {amt} contains the total number of files being processed
         {complete} contains the number of files that have been processed
  Exit:  none
  Description:
    Called at the end of each process pass. 
    Note: {complete} may increment by one or two after each call.

void   showProcessComplete(UINT32 amt)
  Entry: {amt} conatins the number of files processed
  Exit:  none
  Description:
    Called at the end of the process phase.

void showPostProcessBegin(FILETABLE *tbl)
  Entry: {tbl} points to the table being processed
  Exit:  none
  Description:
    Called at the beginning of the postProcess phase.

void showPostProcessUpdate(FILETABLE *tbl, UINT32 complete)
  Entry: {tbl} points to the table being processed
         {complete} contains the number of files processed
  Exit:  none
  Description:
    Called at the end of each postProcess pass

void   showPostProcessComplete(FILETABLE *tbl)
  Entry: {tbl} points to the table that has been processed
  Exit:  none
  Description:
    Called at the end of the postProces phase

void   showExecuteBegin(void)
  Entry: none
  Exit:  none
  Description:
    Called at the beginning of the execute phase.

void   showExecuteComplete(void)
  Entry: none
  Exit:  none
  Description:
    Called at the end of the execute phase.

void   showExecuteError(const char *file, const char *fn, const char *str, 
                        const char *logStr)
  Entry: {file}   points to the file being processed
         {fn}     points to the one of the (LOG_FN_*) strings
         {str}    points to the system error string (strerror(...))
         {logStr} points to the string that was written to the log file
  Exit:  none
  Description:
    Called when an error occurs processing file.

void   showExecuteAction(const char *src, const char *dst, ACTION act,
                         BOOL exec, const char *logStr)
  Entry: {file}   points to the file being processed
         {fn}     points to the function being performed (LOG_FN_*)
         {act}    contains the action being performed
         {exec}   is TRUE if the action will be performed, FALSE if not
         {logStr} points to the string that was written to the log file
  Exit:  none
  Description:
    Called when before an action is performed.

void   showCompleteAction(const char *src, const char *dst, ACTION act)
  Entry: {src}   points to the source 
         {dst}   points to the destination (0 if ACTION_DELETE)
         {act}   contains the action performed
  Exit: none
  Description:
    Called after an action is performed.

void   showCopyBegin(const char *src, const char *dst, UINT32 amt)
  Entry: {src}   points to the source file name
         {dst}   points to the destination file name
         {amt}   contains the number of bytes to be copied
  Exit:  none
  Description:
    Called after the source and destination have both successfully been opened.

void   showCopyUpdate(const char *src, const char *dst, UINT32 amt, UINT32 complete)
  Entry: {src}      points to the source file name
         {dst}      points to the destination file name
         {amt}      contains the number of bytes to be copied
         {complete} contains the number of bytes copied
  Exit:  none
  Description:
    Called after each block has been successfully read and written.

void   showCopyComplete(const char *src, const char *dst, UINT32 amt)
  Entry: {src}      points to the source file name
         {dst}      points to the destination file name
         {amt}      contains the number of bytes copied
  Exit:  none
  Description:
    Called when the copy completes.
