Return to libdmsdos.doc CVS log

Up to [GPL Stacker compression] / dmsdos / doc

Annotation of dmsdos/doc/libdmsdos.doc, revision 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 :(

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