dmsdos/doc/libdmsdos.doc - annotate

Return to libdmsdos.doc CVS log

Up to [GPL Stacker compression] / dmsdos / doc

Annotation of dmsdos/doc/libdmsdos.doc, revision 1.1.1.1

1.1 root 1: This is documentation for the dmsdos library. 22Apr1998
2:
3:
4: The dmsdos library, libdmsdos.a, provides the dmsdos interface that is known
5: from the kernel to a user-level process. This is acchieved by compiling the
6: dmsdos code simply in a different way (well, with some rather dirty tricks).
7:
8: The library is intended to export the following functions:
9:
10: open_cvf
11: close_cvf
12:
13: Well, these two ones above are new, but the rest should be well known to
14: you:
15:
16: dbl_bitfat_value
17: dbl_fat_nextcluster
18: dbl_mdfat_value
19: dmsdos_read_cluster
20: dmsdos_write_cluster
21: raw_bread
22: raw_brelse
23: raw_getblk
24: raw_mark_buffer_dirty
25: raw_set_uptodate
26: simple_check
27: stac_bitfat_state
28:
29: In fact, it exports much more, but only these listed here are guaranteed
30: to be kept in future versions. Well, one thing should be important to know:
31: The library does NOT export virtual sector management. It will never do.
32:
33: The functions are just used like in the kernel. For prototypes, see file
34: dmsdos.h. How to use them see the sources. :) Seriously, if you aren't
35: a dmsdos hacker forget about the library.
36:
37: The first two, open_cvf and close_cvf, are special. They are called instead
38: of mounting and unmounting the CVF.
39:
40: How to "mount" a CVF (example code):
41:
42: struct super_block*sb;
43: sb=open_cvf("CVF_Filename",rwflag /*0=RDONLY or 1=RDWR*/);
44: if(sb==NULL)
45: { fprintf(stderr,"open CVF failed\n");
46: exit(1);
47: }
48:
49: Keep the sb pointer. It must be passed to a lot of functions. It can be used
50: in the same way as in the kernel. The sb pointer is used to distinguish
51: between several open CVFs (in fact, in sb->s_dev the file descriptor is
52: stored).
53:
54: After use, the CVF must be "unmounted" again:
55:
56: close_cvf(sb);
57:
58: If you want to see more example code, look at the dcread utility source
59: (file dcread.c in the src directory).
60:
61: Notes:
62: * The user-level functions are single-threaded. You cannot run several
63: processes on the same CVF unless all are only reading. The library
64: uses flock in order to detect such situations and just denies access
65: in that case. You can however use different CVFs in parallel, even
66: read-write, even in one program.
67: * You should use this library only to access a CVF that is currently not
68: mounted. You *cannot* use it on a CVF that is mounted read-write. If
69: the CVF is currently mounted read-only, the library allows read-only
70: access to the CVF. The library scans /etc/mtab in order to check this.
71: This check is not perfect, though. It also does not prevent mount
72: from mounting a CVF that is used by the library. So just be careful.
73: * You must not touch CVFs that are currently used by dosemu with
74: wholedisk or partition access. I don't know how to test for that
75: situation, so the library doesn't check for this. Well, as dosemu
76: refuses to run if the underlying dos partition is mounted, that
77: situation should never occur :)
78: * If you do not intend to write to the CVF, open it in read-only mode.
79: Then the CVF is not locked exclusively and other processes are allowed
80: to read the CVF at the same time.
81: * The library prints the "kernel" messages to stderr. It obeys the
82: loglevel variable.
83: * The first call of open_cvf initializes the library and prints some
84: version information to stderr.
85: * open_cvf does not do a filesystem check. If you do want the same
86: simple filesystem check that dmsdos usually does when mounting, call
87: simple_check afterwards.
88: * open_cvf may open the filesystem read-only though you request
89: read-write access. This happens if write access is denied or if the
90: dmsdos subsystem detects unexpected problems with the CVF. You may
91: not like this behaviour, but it's best for long life of your CVFs :)
92: Programmers please check sb->s_flags for the MS_RDONLY flag after
93: calling open_cvf to be sure.
94: * To compile your application using the dmsdos library you should under
95: no cirumstances define the macro __KERNEL__ for the whole program.
96: It causes problems with libc6. Just define __KERNEL__ for those
97: include files that don't work without and undefine it afterwards.
98:
99: As an idea what the dmsdos library might be good for:
100:
101: * A mtools clone for CVFs, for example called dtools.
102: * A fsck.dmsdos.
103: * A defragmentation program.
104: * For debugging dmsdos at user level (it's the same source code).
105: * An external fs for midnight commander.
106: * ... add your favourite idea here :)
107:
108: Support for a shared dmsdos library
109: -----------------------------------
110:
111: libdmsdos can now be compiled as a shared library. Just enter a
112: 'make libdmsdos.so' in the src directory. Note that the default installation
113: does not compile the shared library. This is intended. If you are not
114: an experienced shared library hacker please be careful. It's easy to screw
115: up some binaries with shared libraries :)
116:
117: You should not use the dmsdos shared library for now as there's currently no
118: standard that ensures that future versions will be backwards compatible.
119: Link statically with libdmsdos.a unless disk space or memory is very critical.
120:
121: WARNING: If there's a shared dmsdos library lying around, gcc defaults to
122: link *dynamically* all programs that need this library. For example, if
123: libdmsdos.so is present and you recompile dmsdosfsck, the binary will be
124: dynamically linked with that library. This can be very confusing :(

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.