                              LREAD  2.3
Programm to read LINUX Extended2-Filesystems on PCs from within DOS

			Original version 1.0 written by
  Jason Hunter and David Lutz at Willamette University, Salem, Oregon, USA

			Version 2.x modified by
		  Werner Zimmermann, FHTE Esslingen, Germany


	Revision 2.x is released to public under the GNU GPL license,
	see file COPYING. You are using the program on your own risk.


Contents:
	1. Usage
	2. Configuring and Compiling lread and ldir
	3. Known Problems and To Do List, Help Wanted
	4. History
	5. Acknowledgements
	Appendix: lread10's original README.TXT
		 

1. Usage

ldir [-h | -v] [-s/dev/hd..] [Linux_Directory]

	* lists a ext2-directory like DOS' dir or Linux's ls.
	* -h  print help info
	* -v  print version info
	* -s  specify the harddisk partition on which the ext2-directory is
	      eg. /dev/hda5. The default value is set in ldir.h (see 2.)
	      Floppy disk drives /dev/fd0 and /dev/fd1 are also supported.
	      If you only specify /dev/hda or /dev/hdb, ie. no partition number,
	      ldir will search for the first Linux partition on that drive.
	      Please note, that without parameter -s/dev/... ldir will only
	      search the harddisk which was preconfigured when it was compiled
	      (usually /dev/hda, i.e. your first (primary) IDE harddisk).
              You may also specify SCSI harddisks, e.g. /dev/sda, or partitions
              on these disks as /dev/sda3.
              If you're using a mix of IDE and SCSI harddisks, see 3.

	* Linux_Directory is the directory you want to list, if you omit it,
	  the root directory '/' is listed. You can also specify a Linux_File
	  instead of a directory. The name must be a valid Linux name, i.e
	  path delimiter is '/' (not '\'!), all names are case sensitive. For
	  using wildcards see below. If Linux_Directory ends with '/', the
	  contents of the directory is listed.

lread [-h | v] [-s/dev/hd..] Linux_File [DOS_File]
	
	* lists a Linux file or copies it to DOS
	* -h  print help info
	* -v  print version info
	* -s  see ldir
	* Linux_File is the name of the Linux file including the path, if
	  necessary. Pathnames are specified in UNIX style, i.e. with '/'
	  instead of DOS's '\', eg. /usr/src/linux/Documentation.
	  See below how to use wildcards.
	* DOS_File is the name of the file after it is copied, it must be a
          valid DOS filename. Long filenames (more than 8+3 characters) are
          only supported, when you operate under Windows95 (and newer) and
          when your binary is compiled by Turbo/Borland C. If you do not
          specify DOS_File, the Linux_File is listed to stdout (normally the
          screen) instead of copied. If you specify '.' as DOS_File, the
          copy will have the same name as the Linux_File (if not operating
          under Windows95 the filename will be cut to 8+3 characters!)

	  When specifying filenames, remember, that Linux path- and file-
	  names are case sensitive, whereas DOS names are not.

Using wildcards:
	  You may use wildcards '?' and '*'. Wildcards are supported in
	  DOS style, not UNIX style, i.e. '*' stands for 'rest of the name
	  - until the next '.' does not matter'. Unfortunately there are some 
	  restrictions:
	    - If you use wildcards in a pathname rather than in a filename,
	      only the first matching directory is shown.
	    - When you want to copy multiple files by using wildcards, you
	      must specify '.' as destination (or leave blank to copy to 
	      stdout). Files, for which the Linux_File-name is not a valid 
	      DOS_File-name cannot be copied using the '.' option, for those 
	      you must explicitely specify a DOS_File-name.


2. Configuring and Compiling ldir and lread

Before you compile them, edit ldir.h to configure the default name of your
ext2 Linux partition and the timezone value (see the comments in ldir.h).
The Linux partition name is any valid Linux harddisk device, e.g. /dev/hda2 
(second partition of your first harddisk) or /dev/hdb6 (second logical par-
tion on an extended partition on your second harddisk). If you have SCSI
harddisks, you may also specify partitions on SCSI disks, e.g. /dev/sda3.
If you use a mixture of IDE and SCSI drives, please see 3.
If you only specify /dev/hda or /dev/hdb, i.e. without the partition number,
ldir/lread will search for the first Linux partition on this harddisk.
Floppy disk drives /dev/fd0 and /dev/fd1 are also supported. 

If you want to recompile ldir/lread 3 makefiles are provided. Do a
		make -f makefile.dos
to recompile with Borland C (tested with BC 3.1 and 4.5).

If you do have D.J.Delories port of Gnu's GCC you may compile it with
		make -f makefile.gnu
This gives you a 32bit binary, which should not have any memory problems 
(but runs somewhat slower than the Borland C compiled binary).

If for some reason you want to run the program under Linux, e.g. to inspect 
an unmounted filesystem, yes, this is possible, too. Compile (under Linux) 
with    
		make -f makefile.unx

In all three cases maybe, you have to slightly modify the makefile before to
adapt for different pathnames on your system. 


3. Known Problems and To Do List, Help Wanted

Harddisk Detection with IDE harddisks
To detect a ext2 harddisk partition ldir/lread read the harddisk partition 
table and relys on the standard table structure. Some boot managers and 
especially harddisk managers like e.g. the Online Track Manager, which are 
used to support harddisks >504MB with an old ROM BIOS, may modify the par-
tition table in a non-standard way. If ldir/lread has problems detecting your 
disk, please enable #ifdef DEBUG_READDISK in ldir.h and recompile it. Now ldir
will print out the partition table's contents. Mail me the results, describe
your harddisk setup and I'll try to modify the code accordingly.

Harddisk Detection with SCSI harddisks
For reading the disk's partition table, ldir/lread rely on BIOS commands. If 
your SCSI drive can be read under DOS, it should have an extension BIOS, which
should be compatible with ldir/lread. If you only have SCSI harddisks (no IDE
disks), that should work fine by simple specifing  '-s/dev/sdXY' or compiling
ldir/lread with the appropriate setting in ldir.h (X is a letter, specifying the
disk (a=first, b=second harddisk), y is a number, specifing the partition num-
ber with the ext2-filesystem).
If you have a mix of IDE and SCSI harddisks, things are a little difficult,
because Linux handels partition and disk numbering different than DOS. Rudi
Hoekema (rudi@cardio.azn.kun.nl) has done some testing for me. Here is, what
he found out:
      for your first  harddisk use '-s/dev/hdaY' or '-s/dev/sdaY'
      for your second harddisk use '-s/dev/hdbY' or '-s/dev/sdbY'
independent, what the disk's name under Linux is! Only 'Y' still is the
original Linux partition number.
There is still not so much experience with such configurations, so please mail 
me the results. If you run into problems, please enable #ifdef DEBUG_READDISK 
in ldir.h and recompile it. Now ldir will print out some diagnostics info. 
Mail me the results, describe your harddisk setup, maybe it is possible to 
modify the code accordingly.

Floppy Disk Support
Was included as a quick hack, to support the future development of also wri-
ting to ext2-filesystems (it is not so much pleasure, to crash harddisks :-))
Floppy support was not thoroughly tested.

Bugs
Well no bugs, only a bundle of 'features' :-) . ldir/lread has not been tested
extensively, so I assume, that there are quite a lot of bugs. Please feel free
to help correct them. Mail me the problem and preferrably a bug fix.

To Do List
* better support for wildcards in path- and filenames 
* more intelligent name mangling to deal with long Linux filenames when co-
  pied to the pre-DOS7/Windows95  8+3 character filesystem
* implement writing, not only reading ext2-files 
  a higher priority, but I am afraid of all those backup/reformat/restore 
  cycles, which are most likely if you develop low level harddisk write
  routines). To support this development, extended 2 filesystems on floppy 
  disks, which can easyly been reformatted, are now also supported.
* ldir and lread try to read directories and files incrementally. Neverthe-
  less the block group list needs a permanently allocated buffer on the heap
  and read_inode needs a buffer allocated on the heap, which's size is depen-
  dent on the size of the inode. With directories, which hold an extremely 
  big number of files, theoretically this can be a problem with small real 
  mode memory models like TINY or SMALL. Therefore ldir comes precompiled in
  memory model COMPACT. Nevertheless the author has sucessfully tested ldir/
  lread with directories containing up to 1400 files in memory model TINY
  without having problems. So the rewrite of the memory allocation stuff
  and carefully freeing all buffers as soon as possible, seems to be quite
  sucessful.

My long term goal is, to rewrite ldir/lread as a DOS device driver in order 
to 'mount' an ext2-partition like a network drive under DOS. This would allow
Linux partitions to be browsed with Window's filemanager (Bill calls it Ex-
plorer now, does he?) etc.. A horrible scenario for the tough Linux guys, isn't 
it? Well I admit, I like Linux very much (I have developped one of the CDROM
drivers in the Linux standard kernel), but I still write my letters under 
W*Word.

You are invited to help me. If you want to contact me or simply sent bug re-
ports, or even better bug fixes, you can reach me by Email:

               Werner.Zimmermann@fht-esslingen.de

4. History

The first version lread10 was written by Jason Hunter and David Lutz at 
Willamette University, Salem, Oregon, USA as a project in an Operating
Class. I've included their original README.TXT file in the appendix. 
Good work, guys!

I found lread10.zip on Sunsite's server together with another program with
a similar functionality (exttools). When I tried them, the programs in
package exttools did work quite well, but they need gcc for compilation,  
resulting in 32bit programs running with a DOS extender. They are definitely 
not suited for being modified into a DOS device driver (which basically must 
be an assembler program, in best case calling 16bit C subroutines).
When I tried ldir/lread, it did not work at all, because my Linux is located
on DOS extended partitions, but version 1.0 did only detect primary parti-
tions. So I started to rewrite the harddisk detection code. When it finally
worked, I found out, that it could not handle big directories, so I rewrote
the buffering scheme and memory allocation code, when reading inodes, buil-
ding and listing directories. Finally I rewrote the user interface, added 
some command line options, much of the error handling code and 'styled' the
code to compile under Borland C, D.J.Delories gcc port and Linux gcc with-
out warnings...

Maybe it is of some use for you. If not, you can at least take my part of
the code as an example of bad programming practice or simply do a 
'mv lread/* /dev/null'  :-)) !


5. Acknowledgments
Thanks to Jason Hunter and Dave Lutz, who not only developped version 1.0 of
lread/ldir but also had a look into my modifications and suggested further
improvements.
Thanks also to Rudi Hoekema, who provided information and tests for SCSI
support.

Enjoy

Werner Zimmermann
FHTE, FB IT
Fachhochschule fuer Technik Esslingen, Germany
May 10, 1997


############################################################################
Appendix: The original README.TXT of lread10:

Welcome to lread/ldir!

This program was written for an Operating Systems class at Willamette
University in Salem, Oregon, USA.  It is a DOS program (though it has
been shown to work under Linux) which reads the Linux ext2 filesystem.


USAGE

The usage is as follows:

ldir /any/Linux/path
	  and
lread /any/Linux/path[/filename] [savefile]

where bracketed items are optional.

Ldir will printout something akin to a "ls -l" for the given directory.  It
always outputs to stdout.  Lread will print actual files.  It will print to
stdout unless a savefile is given in which case it will save that file on
the DOS filesystem.  If lread is given a directory name instead of a file
name, it will display or save a dump of the directory.  We consider the
capability to both "dir" and "read" a directory a feature.


LDIR/LREAD DIFFERENCES

As you can tell by viewing the code, the only difference between ldir and
lread is the filename.  The program does a quick check of argv[0] and reacts
based on the name of the called program.  Under Linux you can simply link
ldir to lread, but under DOS you must make a full copy of the file.  So 
compile the code to be either lread or ldir and copy the other.


COMPILING TIPS

When you compile the code under DOS be sure to use the Compact memory model
or larger.  64K of data space is not enough for parsing large directories. 
Super-large directories still cause problems under DOS.


PROGRAM OPERATION

The program works by first reading the data about the hard drive in the
partition table.  It finds the first Linux partition on the first hard drive
(if you have more than one, change the code... we're graduating and done
with this at least for a while!).  It uses the drive specifications it finds
in the table to enable DOS to use BIOS calls to read outside the DOS
partition.

Using this capability, the program finds the inode of the first parameter
(kind of like performing a mini "stat" under DOS).  It chases down the path
piece by piece to find the inode of the last part.  It begins at the rood
directory (inode 2), loads that directory, and then scans it for the inode
corresponding to the next piece of the path.  It stops when it has resolved
the full path or hits a softlink or filename in the middle of the path.  (If
you care to allow it to follow softlinks, be my guest.  Please see my email
address below as a contact point.)

With this inode the program can follow the file block by block--through the
single indirect, double indirect, and triple indirect pointers.  After
reading each block it either displays it or writes it to a file.

When everything has finished the program reports any errors encountered or
the fact that no errors were found.  On ldir it only reports problems.

There is a list of problems and things to work on in main.c.  If you have
skills and interest, feel free to tackle some code modifications.  For at
least the near future work is keeping me too busy to continue working on
this.  Please report bugs and comments to the addresses below.


THE GOOD-BYE

Keep in touch on email!

jhunter@willamette.edu
jhunter@engr.sgi.com
dlutz@willamette.edu

Jason and Dave
