Function            parsefilename - parses a filename, supports paths

  Syntax              struct filespec *parsefilename(char *fspec);

  Prototype in        filehk.h

  Remarks             parsefilename parses a string pointed to by fspec
                      for a file name. The file name is placed in a
                      struct filespec as a drive, path, and filename.ext.
                      Wildcards are supported. The struct filespec is
                      returned as follows:

                           drive          NULL (\0) if not given, else
                                          drive letter
                           path           NULL string ("") if not given,
                                          else the path with a \ added to
                                          the end of the path string
                           filename.ext   NULL string ("") if no file
                                          name given, else a filename.ext
                                          as per standard DOS file names.

                      The filename.ext is not expanded (i.e. c:tchk.lib
                      has a filename.ext of tchk.lib, but c:tchk. has a
                      filename.ext of tchk., and c:tchk has a
                      filename.ext of tchk.).

                      parsefilename is intelligent enough to know that
                      c:. expands out to C:.\*.*, where . is a path.

                      parsefilename is very similar to Borland's
                      parsefnm(), except Borland's function does NOT
                      handle paths, whereas parsefilename will (since
                      parsefnm() is just a DOS call, and we all know who
                      writes that wonderful operating system MS-DOS,
                      don't we?)

                      Limited error checking is performed, so beware. The
                      string will be parsed properly, but errors due to
                      long strings (i.e. strlen(fspec) > 100) and other
                      miscellania can cause extensive damage due to
                      pointer manipulations.

                      Furthermore, an invalid string (i.e. C:\TC\;HK\Z.C)
                      will not be treated as an error. The string is
                      parsed from the beginning to look for a drive
                      letter, and scanned from the right to the left,
                      stopping at the first \. If a \ is found,
                      everything to the right of it is considered the
                      file name, everything to the left is the path
                      (excluding the drive). You are responsible for
                      making sure fspec is a valid DOS drive, path and
                      file name.

  Return value        parsefilename returns the DOS file name fspec
                      broken down into drive, path and filename.ext.

                      parsefilename returns a pointer to the storage
                      location containing the struct filespec, or NULL if
                      space could not be allocated.

  See also            getfilespec(), parsefnameext(), resolvepath()

  Example             see demopars.c