TABLE OF CONTENTS

dslib.lib/j_Close
dslib.lib/j_close_dosserv
dslib.lib/j_CreateDir
dslib.lib/j_CurrentDir
dslib.lib/j_DeleteFile
dslib.lib/j_DupLock
dslib.lib/j_Examine
dslib.lib/j_ExNext
dslib.lib/j_IoErr
dslib.lib/j_Lock
dslib.lib/j_MatchPattern
dslib.lib/j_Open
dslib.lib/j_open_dosserv
dslib.lib/j_ParentDir
dslib.lib/j_ParsePattern
dslib.lib/j_Read
dslib.lib/j_Rename
dslib.lib/j_Seek
dslib.lib/j_SetFileDate
dslib.lib/j_SetProtection
dslib.lib/j_tickle_janus
dslib.lib/j_UnLock
dslib.lib/j_Write
dslib.lib/j_Close                                           dslib.lib/j_Close

   NAME   
      j_Close - close a file.

   SYNOPSIS
      j_Close(struct dslib_struct *ds, ULONG afile)

   FUNCTION
      Close a file.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG afile
         File handle of file to be closed, obtained via
         j_Open().

   RESULT

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_close_dosserv                           dslib.lib/j_close_dosserv

   NAME   
      j_close_dosserv -- closes DOSServ service

   SYNOPSIS
      UBYTE Error = j_close_dosserv(struct dslib_struct *ds)

   FUNCTION
      Closes the DOSServ service (opposite of j_open_dosserv()).
      If j_open_dosserv() succeeded, you should call this function
      when you are finished with j_fxxx() calls.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         allocated and filled in by j_open_dosserv().

   RESULT
      Error
         FALSE (zero)
            Indicates that DOSServ has been closed.
         TRUE (nonzero)
            Indicates failure to close DOSServ.  This
            should never happen.

   EXAMPLE

   NOTES

   BUGS
      Ideally, all the functions in this library that open files
      or create locks should register these things in a list
      attached to the dslib_struct, so that j_close_dosserv()
      can get rid of them in case of programmer error.

   SEE ALSO
      j_open_dosserv()

dslib.lib/j_CreateDir                                   dslib.lib/j_CreateDir

   NAME   
      j_CreateDir - create a directory on the amiga

   SYNOPSIS
      ULONG Lock = j_CreateDir(struct dslib_struct *ds, char *name)

   FUNCTION
      Creates a directory on the amiga using the name supplied.
      Returns 0 if failed, or a lock value if succeeded.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *name
         Name of directory to create.

   RESULT
      Lock
         zero
            j_CreateDir failed for some reason
         nonzero
            The lock for the new directory.  The lock must
            be freed using j_UnLock() eventually.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_CurrentDir                                 dslib.lib/j_CurrentDir

   NAME   
      j_CurrentDir - change the current directory

   SYNOPSIS
      ULONG Lock = j_CurrentDir(struct dslib_struct *ds,
                 ULONG newlock)

   FUNCTION
      Change the current directory to that attached to the given
      lock.  returns the lock for the "old" current directory.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG newlock
         lock obtained via j_Lock() or j_CreateDir.

   RESULT
      ULONG Lock
         lock for previous current directory

   EXAMPLE

   NOTES
      The lock you pass in *must* be a directory (not a file) lock.

   BUGS

   SEE ALSO

dslib.lib/j_DeleteFile                                 dslib.lib/j_DeleteFile

   NAME   
      j_DeleteFile - delete a file

   SYNOPSIS
      ULONG success = j_DeleteFile(struct dslib_struct *ds,
                    char *name)

   FUNCTION
      Delete an amiga file

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *name
         The name of the file to delete.

   RESULT
      ULONG success
         nonzero if file was deleted.
         zero if file was not deleted.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_DupLock                                       dslib.lib/j_DupLock

   NAME   
      j_DupLock - duplicate a lock

   SYNOPSIS
      ULONG newlock = j_DupLock(struct dslib_struct *ds,
                 ULONG oldlock)

   FUNCTION
      Duplicate a lock on a file or directory.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG oldlock
         The lock to be duplicated

   RESULT
      ULONG newlock
         A lock on the same object as oldlock

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_Examine                                       dslib.lib/j_Examine

   NAME   
      j_Examine - get information about a lock

   SYNOPSIS
      ULONG success = j_Examine(struct dslib_struct *ds, ULONG lock,
                 struct FileInfoBlock *infoblock)

   FUNCTION
      Get information about a lock.  Call this before calling
      j_ExNext() when scanning a directory.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG lock
         Lock on an object to be examined.

      struct FileInfoBlock *infoblock
         Pointer to structure to be filled in by j_Examine().

   RESULT
      ULONG success
         nonzero if succeeded.
         zero if failed.

      struct FileInfoBlock *infoblock
         if success is nonzero, structure has been filled in.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_ExNext                                         dslib.lib/j_ExNext

   NAME   
      j_ExNext - get information about a lock

   SYNOPSIS
      ULONG success = j_ExNext(struct dslib_struct *ds, ULONG lock,
                struct FileInfoBlock *infoblock)

   FUNCTION
      Get information about a lock.  Call this after j_Examine()
      repeatedly to scan a directory.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG lock
         Lock on an object to be examined.

      struct FileInfoBlock *infoblock
         Pointer to structure to be filled in by j_ExNext().
         Must have already been filled in by j_Examine().

   RESULT
      ULONG success
         nonzero if succeeded.
         zero if failed.

      struct FileInfoBlock *infoblock
         if success is nonzero, structure has been filled in.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_IoErr                                           dslib.lib/j_IoErr

   NAME   
      j_IoErr - get the last AmigaDOS error code

   SYNOPSIS
      ULONG err = j_IoErr(struct dslib_struct *ds)

   FUNCTION
      Determine the error code for the last DOS function.

   INPUTS
      struct j_dosserv *d_s
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

   RESULT
      ULONG err
         The last AmigaDOS error code.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_Lock                                             dslib.lib/j_Lock

   NAME   
      j_Lock - obtain a lock on a file or directory

   SYNOPSIS
      ULONG lock = j_Lock(struct dslib_struct *ds, char *name,
                LONG accessmode)

   FUNCTION
      Obtain a lock on an object.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *name
         Name of object to lock.

      LONG accessmode
         Type of lock.  Can be one of:
            ACCESS_READ
               shared read lock
            ACCESS_WRITE
               exclusive read/write lock

   RESULT
      ULONG lock
         nonzero - Lock on object (lock succeeded).
         zero - lock failed.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_MatchPattern                             dslib.lib/j_MatchPattern

   NAME   
      j_MatchPattern - compare a string with a preparsed regular
             expression.

   SYNOPSIS
      ULONG match = j_MatchPattern(struct dslib_struct *ds,
                    char *pat, char *str)

   FUNCTION
      Determine if a string (typically a filename) matches a
      preparsed amigados regular expression.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *pat
         Preparsed amigados regular expression.

      char *name
         Name to check against regular expression.

   RESULT
      ULONG match
         nonzero - name matches pattern
         zero - name does not match pattern

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
      j_ParsePattern()

dslib.lib/j_Open                                             dslib.lib/j_Open

   NAME   
      j_Open - open a file.

   SYNOPSIS
      ULONG handle = j_Open(struct dslib_struct *ds,
                  char *fname, LONG mode)

   FUNCTION
      Open an amiga file.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *fname
         Name of file to open.

      LONG mode
         How to open the file.  One of the following:
            MODE_OLDFILE
               The file must exist, and will be
               opened in shared read mode.
            MODE_NEWFILE
               If the file exists, it is cleared.
               If it doesn't exist, it is created.
               The file is opened in exclusive write
               mode.
            MODE_READWRITE
               If the file exists, it is opened.
               If it doesn't exist, it is created.
               The file is opened in shared read mode.

   RESULT
      LONG handle
         The file handle needed to read/write/seek/close this
         file.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_open_dosserv                             dslib.lib/j_open_dosserv

   NAME   
      j_open_dosserv -- open DOSServ service

   SYNOPSIS
      struct dslib_struct *ds = j_open_dosserv()

   FUNCTION
      Opens the DOSServ service provided by the Amiga, paving the
      way for j_fxxx() functions.

   INPUTS
      None.

   RESULT
      struct j_dosserv *ds
         0 = The DOSServ service failed to open.
         Otherwise, a pointer to a dslib_struct which should be
         passed to other j_xxx() functions.

   EXAMPLE

   NOTES
      Before calling, you should insure that the janus handler is
      present by calling j_tickle_janus().

      This function may take up to 30 seconds to complete (assuming
      that a GetService() with GETS_WAIT and GETS_ALOAD times out
      in 30 seconds if the service won't or can't start).

      If this function fails, you should not call j_close_dosserv().

   BUGS
      Currently the synchronization of autoloaded services with
      GetService() isn't working right, so this call can sometimes
      appear to work when it really failed.

   SEE ALSO
      j_tickle_janus(), j_close_dosserv(), j_fopen(), f_fclose(),
      j_fread(), j_fwrite(), j_fseek()

dslib.lib/j_ParentDir                                   dslib.lib/j_ParentDir

   NAME   
      j_ParentDir - get the parent of a directory

   SYNOPSIS
      ULONG plock = j_ParentDir(struct dslib_struct *ds,
                 ULONG lock)

   FUNCTION
      Get a lock on the directory above the given one.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG lock
         lock obtained via j_Lock() or j_CreateDir.

   RESULT
      ULONG plock
         lock for parent of the lock attached to lock.

   EXAMPLE

   NOTES
      The lock you pass in *must* be a directory (not a file) lock.

   BUGS

   SEE ALSO

dslib.lib/j_ParsePattern                             dslib.lib/j_ParsePattern

   NAME   
      j_ParsePattern - convert an amigados regular expression to
             a parsed regular expression for use by
             j_MatchPattern().

   SYNOPSIS
      LONG wild = j_ParsePattern(struct dslib_struct *ds,
                  char *sourcepat, char *destpat,
                  LONG destlen)

   FUNCTION
      Create a parsed regular expression for j_MatchPattern().

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *sourcepat
         Amigados regular expression string.

      char *destpat
         Place to store result.

   RESULT
      LONG wild
          1 = pattern contains wildcards (success)
          0 = pattern does not contain wildcards (success)
         -1 = conversion error (syntax or destpat to small)

      char *destpat
         If wild indicates success, contains parsed regexp.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
      j_MatchPattern()

dslib.lib/j_Read                                             dslib.lib/j_Read

   NAME   
      j_Read - read data from a file.

   SYNOPSIS
      LONG bytesread = j_Read(struct dslib_struct *ds,
               ULONG afile, void *bufin, LONG n_bytes)

   FUNCTION
      Read from a file.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG afile
         File handle of file to read from.

      void *bufin
         Pointer to where to store data.

      LONG n_bytes
         Number of bytes to read.

   RESULT
      LONG bytesread
         -1 = error occurred, no data read
          0 = EOF (no data read)
          otherwise number of bytes read.  Note that ds->errno
            should be checked in this case, since multiple
            reads can be performed for each call, and if
            some succeed but a later read fails, you can
            get a positive value but still have had an
            error.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_Rename                                         dslib.lib/j_Rename

   NAME   
      j_Rename - rename a file or directory

   SYNOPSIS
      ULONG success = j_Rename(struct dslib_struct *ds,
                char *oldname, char *newname)

   FUNCTION
      Rename an amiga file or directory.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *oldname
         The name of the file to rename.

      char *newname
         The new name of the file.

   RESULT
      ULONG success
         nonzero if file was renamed.
         zero if file was not renamed.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_Seek                                             dslib.lib/j_Seek

   NAME   
      j_Seek - change file position pointer.

   SYNOPSIS
      LONG oldpos = j_Seek(struct dslib_struct *ds, ULONG afile,
                 LONG offset, LONG mode)

   FUNCTION
      Seek within a file

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG afile
         File handle of file to seek.

      LONG offset
         Offset in bytes within file.  Actual position depends
         on mode.

      LONG mode
         How to interpret offset.  One of the following:
            OFFSET_BEGINNING
               offset = number of bytes from start
               of file.
            OFFSET_CURRENT
               offset = number of bytes from current
               position (may be negative).  a zero
               value doesn't move the file pointer,
               but has the effect of returning the
               current file position.
            OFFSET_END
               offset = number of bytes from end
               of file.  this value should be negative
               to seek backwards from the end, or
               zero to seek to the end.

   RESULT
      LONG oldpos
         the file pointer value before this call completes.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_SetFileDate                               dslib.lib/j_SetFileDate

   NAME   
      j_SetFileDate - change the time/date stamp of a file

   SYNOPSIS
      ULONG success = j_SetFileDate(struct dslib_struct *ds,
                  char *fname, struct DateStamp *d_s)

   FUNCTION
      Alter a file's timestamp

   INPUTS
      struct j_dosserv *d_s
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *fname
         Name of file whose bits to change.

      stuct DateStamp *ds
         Pointer to a DateStamp struct containing the new timestamp
         value.

   RESULT
      ULONG success
         TRUE if the timestamp was modified.
         FALSE if the timestamp was not modified.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_SetProtection                           dslib.lib/j_SetProtection

   NAME   
      j_SetProtection - change a file's protection bits

   SYNOPSIS
      ULONG success = j_SetProtection(struct dslib_struct *ds,
                  char *fname, LONG bits)

   FUNCTION
      Alter a file's protection bits.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      char *fname
         Name of file whose bits to change.

      LONG bits
         New bits to install in the file's fib.fib_Protection
         field.  Possible values are listed in dslib.h.

   RESULT
      ULONG success
         TRUE if the bits were modified.
         FALSE if the bits were not modified.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_tickle_janus                             dslib.lib/j_tickle_janus

   NAME   
      j_tickle_janus -- determine if janus handler is installed

   SYNOPSIS
      UBYTE success = j_tickle_janus()

   FUNCTION
      Determines if the janus handler is present in the system.

   INPUTS

   RESULT
      UBYTE success
         FALSE (0) value indicates failure to locate the
            janus handler.
         TRUE (nonzero) value indicates that DOSServ has been
            opened and the structure filled in correctly.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_UnLock                                         dslib.lib/j_UnLock

   NAME   
      j_UnLock - free a lock obtained via j_Lock(), j_CreateDir,
            j_ParentDir, or j_DupLock().

   SYNOPSIS
      j_UnLock(struct dslib_struct *ds, ULONG lock)

   FUNCTION
      Get rid of a lock.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG lock
         The lock to be freed.

   RESULT

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

dslib.lib/j_Write                                           dslib.lib/j_Write

   NAME   
      j_Write - write data to a file.

   SYNOPSIS
      LONG byteswritten = j_Write(struct dslib_struct *ds,
                   ULONG afile, void *bufin,
                   LONG n_bytes)

   FUNCTION
      Write to a file.

   INPUTS
      struct j_dosserv *ds
         Pointer to a j_dosserv struct.  This structure was
         filled in by j_open_dosserv().

      ULONG afile
         File handle of file to write to.

      void *bufin
         Pointer to where to fetch data.

      LONG n_bytes
         Number of bytes to write.

   RESULT
      LONG byteswritten
         -1 = error occurred, no data written
          otherwise number of bytes written.  Note that
             ds->errno should be checked in this case, since
             multiple writes can be performed for each call,
            and if some succeed but a later write fails,
            you can get a positive value but still have
            had an error.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

