Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!mailrus!ames!amdahl!uunet!mcvax!botter!star.cs.vu.nl!ast@cs.vu.nl From: ast@cs.vu.nl (Andy Tanenbaum) Newsgroups: comp.os.minix Subject: V1.3 posting #1 - USER_GUIDE Message-ID: <762@ast.cs.vu.nl> Date: 29 May 88 19:28:43 GMT Sender: ast@cs.vu.nl Reply-To: ast@cs.vu.nl (Andy Tanenbaum) Organization: VU Informatica, Amsterdam Lines: 387 This is the first posting of V1.3. It contains doc/USER_GUIDE, which replaces the READ_ME file. I will also make the following postings today: P1 - USER_GUIDE (this file) P2 - /usr/include P3 - lib: intro P4 - lib: [a-l]*.c diffs P5 - lib: [m-z]*.c diffs P6 - lib: new files P7 - commands: intro P8 - commands: diffs [a-m] P9 - commands: diffs [n-z] P10 - commands: selected new files (smaller ones) Please install and test this stuff, and post messages about problems, etc. Sometime in June I hope to post the kernel diffs and networking stuff. If you have reported a bug and it is not fixed, please report it again, preferably by posting, rather than by email, so that (1) everyone will be aware of it, and (2) maybe somebody will try to fix it. Please note that I have been very stingy about adding improved FEATURES to programs. The fact that 'ls' did not work in V7 like it does in 4.3 is not a bug and I didn't fix it. The fact that division by zero gives an infinite stream of error messages in 1.2 is a bug and I did fix it. Small, useful utilities are generally welcome. Huge ones are less so. This being said, I am still open to new changes and additions to 1.3, however, the larger the change, the harder it is to test, and the less like V7 it is, the less likely I will adopt it. No concessions are being made to MS-DOS or any of its compilers. A number of people have said that the MINIX C compiler is slow. Since I don't have (or want) any MS-DOS compiler, I can't make a comparison, but I did run the following timing test. I removed all the .s files from fs and typed: time make. The 20 compilations plus the link took 5:57 real time on my Z-248, which has 1.5 MB RAM and an ST-225 hard disk (70 msec access time). It seems to me that this isn't so awful. Obviously a PC will be slower, but that should hold proportionally for all compilers. Andy Tanenbaum (ast@cs.vu.nl) ------------------------------------ doc/USER_GUIDE ---------------------- The software has undergone some changes since the book was published. Among other things, the software has been more oriented toward hard disk users, it has been ported to the IBM PC-AT (and clones), and also to the Atari ST. The most significant changes are listed here. 1. GENERAL There were a number of minor changes made to the code after the book was printed, as mentioned above. As a result, line X of file Y in the book may actually appear at X+3, or X-5, etc. on the disk version. In the event of conflict, believe the disk version over the book version. 2. PC-AT The distribution for the PC-AT differs from that for the PC in minor ways. For example, there is no /user diskette. All the files that would normally be on /user fit on /usr. Furthermore, the number and organization of the source diskettes is different, but the same programs are available. Two additional special files are present in /dev: /dev/at0 and /dev/at1. These should be used to access 1.2M diskettes. To access 360K diskettes on the PC-AT, use /dev/fd0 and /dev/fd1. Special files are used by commands such as mount, mkfs, and df, among others. For example, to copy part of a 1.2M diskette, type dd if=/dev/at0 of=file count=100. The difference between /dev/at0 and /dev/fd0 is that in MINIX, special files have sizes to prevent access beyond the end. For /dev/fd0 the size is 360K. For /dev/at0 it is 1.2M. Finally, the executable binary for the PC-AT contains at_wini.c instead of xt_wini.c (see below). 3. HARD DISK DRIVERS MINIX supports the use of the standard IBM hard disks. Unfortunately, IBM chose to use different (and incompatible) disks and controllers on the XT and AT. To find out if MINIX works with your disk, give the command: dd if=/dev/hd0 of=/dev/null count=1000 If this runs to the end without errors, the driver embedded in your MINIX binary is appropriate for your controller and drive. If it gives errors, copy kernel/xt_wini.c to wini.c and recompile the operating system. If this fails, then try kernel/at_wini.c and recompile it once more. Usually, one of these will work. If neither works, your disk is not compatible with either the XT or AT. You will have to modify the driver. You MUST have a kernel/wini.c to recompile the system, even if you do not have a hard disk (in which case, either one will do). 4. INSTALLING MINIX ON A HARD DISK After you have made sure that you have a working hard disk driver, as described above, proceed as follows. To use MINIX on a hard disk, you need a MINIX partition. You may also have MS-DOS, PC-IX, OS/2, XENIX, or other partitions as well if you like. If you understand about making partitions, make one any way you are used to. Otherwise use the MINIX fdisk program. Once you have a partition available for MINIX (the type does not matter as MINIX does not check), make a file system by booting MINIX from floppy the usual way and run mkfs. If, for example, you have chosen partition 2, which has, say, 40 cylinders (i.e., 40 x 68 = 2720 sectors or 1360 1K blocks), type: mkfs /dev/hd2 1360 to make an empty file system. However, for partition 1 use 1 block less because block 0 is not available (it contains the MS-DOS partition table). In other words, a 40 cylinder partition 1 has 1359 blocks but a 40 cylinder partition 2 or higher has 1360 blocks. Then mount the file system by typing /etc/mount /dev/hd2 /user Next, make whatever directories you like, typically bin, lib, and others, and copy files to the hard disk. With the /usr floppy in drive 0, the command cp /usr/bin/* /user/bin will copy all the binaries from /usr/bin to the hard disk, for example. Alternatively, the cpdir program can be used to copy entire trees, e.g. cpdir /usr/bin /user/bin will create a new directory /user/bin, and put /usr/bin with all its files and subdirectories in it. A few of the files in /usr/bin must be owned by the root (instead of bin) and have mode 4755. Check to make sure. These files are: badblocks chgrp df fsck mkdir mv passwd readall rmdir su Finally, edit /etc/rc to have the hard disk mounted when the system is booted. A line such as /etc/mount /dev/hd2 /usr can be used as a replacement for the mount command initially in /etc/rc. After editing /etc/rc, mount the root file system diskette and copy it to the diskette; otherwise the changes will be lost when the system is rebooted. (There is nothing special about the root file system except its size; it can be mounted and written on like any other file system.) After these steps have been taken, the system can be booted from floppy in the usual way, and the root file system also read in from floppy. The hard disk will automatically be mounted by the /etc/rc. The root device remains on the RAM disk, and the boot process still goes via floppy (for compatibility and to prevent disaster in the event that something goes wrong with the hard disk file system). Hard disk file systems can be checked using fsck, the same as floppies. The special file /dev/hd0 refers to the whole disk, without regard to partitions, whereas /dev/hd1 ... /dev/hd4 refer to partitions 1 to 4. If you have a second hard disk, you can make /dev/hd5 ... /dev/hd9 with mknod (major device 3, minor device 5 ... 9) for the second drive, with hd5 for the whole drive, hd6 for partition 1, etc. Fsck also uses this convention. 5. CONFIGURING MINIX ON A HARD DISK When setting up MINIX on a hard disk, the following set of directories is recommended, although the MINIX source tree can go elsewhere if desired. Be sure to edit the cc.c program to make sure it knows where to find the various compiler passes and libraries, which may be in /bin, lib, /usr/bin, or /usr/bin. When a large RAM disk is available, put /bin and /lib on the RAM disk, and include the compiler parts in them. When extracting files from the distribution, note carefully that there is a lib directory on the /usr diskette (for /lib and /usr/lib) and another one among the sources (for /usr/src/minix/lib). Many of the directories listed below have sub- directories. /bin - most common binaries /dev - special files /etc - system administration /lib - most important libraries /tmp - scratch files go here /usr - mount usr file system here /usr/bin - rest of the binaries /usr/include - system include files /usr/lib - rest of the libraries /usr/src - sources go here /usr/src/minix - minix sources go here /usr/src/minix/amoeba - all networking code is here /usr/src/minix/commands - utility program sources /usr/src/minix/fs - file system sources /usr/src/minix/h - operating system header files /usr/src/minix/kernel - kernel and device driver sources /usr/src/minix/lib - libc.a sources /usr/src/minix/mm - memory manager sources /usr/src/minix/test - test programs /usr/src/minix/tools - tools for building new operating systems /usr/tmp - (optional) alternative place for temporaries 6. PUTTING THE ROOT FILE SYSTEM ON A HARD DISK To speed up the boot procedure, you may copy the root file system to /dev/hd3 with the commands cp /dev/fd0 /dev/hd3 or cp /dev/at0 /dev/hd3 The former is for the PC, the latter is for the AT. /dev/hd3 must not be mounted. When booting, leave the boot diskette in the drive when typing the = sign. MINIX will see that the diskette is not a valid file system, and take the root file system from the default device, /dev/hd3. You can change the choice of default by modifying RAM_IMAGE in fs/main.c 7. USING MS-DOS AS A DEVELOPMENT SYSTEM MINIX is now completely self supporting, so the C86 and PC-IX directories have been deleted. The only time you might need MS-DOS is for formatting blank diskettes. MINIX does not have a format program. 8. EDITING LARGE PROGRAMS WITH MINED Mined has a limit on the size of programs it can edit. To edit larger ones, they must be broken up with split, edited separately and recombined later. Better yet, use elle, which is a much better editor, is emacs compatible, and can handle files as large as the disk. 9. MKNOD MINIX differs from UNIX in that block special files (and even some character special files, such as /dev/kmem) can have sizes. A 360K floppy disk special file, such as /dev/fd0 can have size 360K. Unfortunately, the mknod system call (and mknod program) have no way to express the size, so it uses size 0, which is equal to infinity. When you read past the end of a block special file WITH a size, the file system returns zero bytes. When you go off the end of a device WITHOUT a size, some drivers return end-of-file (e.g., hard disk, RAM disk), but others (e.g., floppy disk) return an I/O error code. Thus if you make a new block special file for 2/0 and 2/1 (floppy disk) with mknod (i.e., no size) the command cp /dev/fd0 /dev/fd1 will terminate with an error on block 360 (but it will copy the disk perfectly). The only way to make a special file with a size is by making a file system with mkfs. 10. NONEXISTENT DEVICES If you try to open /dev/fd1 on a system with only one floppy disk drive, the system may hang. To avoid this problem, the first time you log in, go to the /dev directory, and rename special files that you do not have to something unusual. For example, if you do not have a hard disk, rename hd0 to HARD_DISK_0, hd1 to HARD_DISK_1, etc. Similarly with one one floppy disk, rename fd1 to FLOPPY_DISK_1 to prevent it being typed by accident. You can also remove them, but due to the mknod problem described above, you can not get them back easily, so it is best just to get them out of the way in case you ever need them again later. 11. PRINTER In order to accommodate buffered and unbuffered printers, the printer driver uses a combination of delay loops and interrupts. The net result is that the driver consumes a fair number of CPU cyles when running. If you expect to do a lot of printing, you might want to consider rewriting the printer interrupt handler, pr_char, in assembly code. 12. DISK SPACE The /usr disk as distributed is nearly full. If you have two floppy disk drives, be sure to mount /user on drive 1 and move your working directory there. If you have only 1 floppy disk drive, remove some files from /usr/bin to make more space. If you have a hard disk, there is no problem. 13. RUNNING /USER TESTS ON A FLOPPY Before running the tests in /user/test, remove the files in /user/commands to create some free space on the disk. Run the tests as superuser. 14. COMMAND LINE LENGTH The maximum initial stack size is 1K. Calls to EXEC which require a larger stack will fail. Thus if you do ls -l * in a large directory, the shell may expand the * so that the command line exceeds 1K and the EXEC will fail, resulting in the message "Cannot execute ls". 15. ARCHIVES ON THE DISTRIBUTION DISKETTES To save space on the distribution diskettes, some of the sources have been compressed and/or archived. Files ending with .archive can be de-archived by typing: ar x file.archive. Files ending with .Z are compressed files, and can be decompressed by typing: compress -d file.Z. Some directories contain archives of compressed files, so first remove the files from the archive and then decompress the resulting .Z files. 16. RECOMPILING FSCK AND OTHER LARGE PROGRAMS If for some reason you don't like the tools/fsck binary and want to recompile it, make sure you have plenty of free space for the compiler's temporary files. On a floppy disk system, this may mean putting fsck on an almost empty diskette before compiling it. When the disk is full, the quality of the compiler's error messages deteriorates rapidly. If you are compiling fsck and getting strange results, check for disk space. Normally /tmp is used for temporaries, but the -T flag can override that. 17. NEWS GROUP If you have access to USENET, you may be interested in knowing that there is a news group, comp.os.minix devoted to discussions of MINIX. This is one of the largest news groups, with over 10,000 readers. If you have access to the Arpanet, Bitnet, or EARN, the news group is gatewayed there. Contact info-minix-request@udel.edu to join. 18. SYSTEM PROBLEMS The IBM PC does not have any hardware for checking for stack overflow. The user must allocate the amount of stack for each program with chmem or use the compiler default (64K - program - data size). Some programs in the distribution have been set to a smaller value, and may, in rare instances with certain arguments, hang. If the system ever gets into a situation where it echoes keystrokes, but ignores DEL and CTRL-\ and appears otherwise to be hung up, hit F1 to see what is going on. If some process is running and there is no way to interrupt it, hit F9. This key is equivalent to the super-user typing: kill -1 9. The result of F9 is that every process in the system is killed, including update and all the shells. Although drastic, F9 will dehang the system instantly. Log in again and then type /etc/update & to restart update. 19. USE OF EXTENDED MEMORY ON ATs If the size of the root file system (either taken from floppy or from /dev/hd3, as described above), is 256K or more, MINIX puts the root device in extended memory, above 1M, leaving the entire 512K or 640K free for MINIX and user programs. To get full advantage of the extended memory, the size of the root file system should be the same as the amount of extended memory present. If the root file system is < 256K, MINIX assumes that there is no extended memory, and puts the root file system in "low" core (below 640K). This feature only works on ATs, so PCs must never have root file systems >= 256K. 20. SOFTWARE SCROLLING FOR EGA CARDS MINIX works with monochrome cards, CGA cards, and IBM EGA cards. However, it does not work with some nonstandard EGA cards. With these cards, the screen will go blank every 25 lines. MINIX can be made to work with these EGA cards by recompiling tty.c (or the whole kernel) with the -DSOFTSCROLL flag. For example, add -DSOFTSCROLL to CFLAGS in kernel/makefile and re-make the kernel. Software scrolling is much slower than hardware scrolling, so this option should only be used if needed. The bootable image in the standard distribution was made by running make -DSOFTSCROLL in the kernel directory. It is suggested that you try making a new kernel (but not mm or fs) without -DSOFTSCROLL. If that one works, use it, since it will be faster than the one in the distribution. 21. NEW FLAGS AND FEATURES Various programs have acquired new flags and features and new programs have been included. Please read all the files in this directory. 22. ANSI ESCAPE SEQUENCES The escape sequences used by the tty driver for both input and output have been changed to the ANSI standard ones. To manipulate the cursor etc., print the following: ESC M: scroll a line backwards (cursor must be on line 1) ESC [ y ; x H move to column x, row y; (1,1) is upper right corner ESC [0J clear from cursor to end of screen ESC [7m go to reverse video ESC [0m go to normal video The 9 numeric pad keys, as well as numeric + and - now generate ESC [ x for some x. Just type them to see which x goes with each key. 23. _CLEANUP NO LONGER NEEDED The exit routine has been changed to call _cleanup automatically. As a result, programs using stdio no longer have to call it explicitly. All calls to _cleanup have been removed from the standard distribution. 24. DISTRIBUTION CHANGES The subdirectories PCIX and C86 have been deleted, as mentioned above. The subdirectories MINIX have been renamed IBM_PC to avoid confusion with files for the ATARI ST (not included here). Before recompiling anything, remove the relevant files from IBM_PC and move them one directory up, e.g. cd minix/kernel; cp IBM_PC/* . In some cases, two makefiles are provided, called pc_makefile and at_makefile. Copy the appropriate one to makefile, depending on whether you have (1) a PC or XT or (2) an AT. Delete the inappropriate one. 25. LINKS The directory /usr/include now contains several subdirectories and also linked files. If you copy this directory to hard disk, link the following files, if possible. /usr/include/sgtty.h to minix/h/sgtty.h /usr/include/signal.h to minix/h/signal.h /usr/include/minix/callnr.h to minix/h/callnr.h /usr/include/minix/com.h to minix/h/com.h /usr/include/minix/const.h to minix/h/const.h /usr/include/minix/type.h to minix/h/type.h /usr/include/sys/stat.h to minix/h/stat.h /usr/include/fs/buf.h to minix/fs/buf.h /usr/include/fs/const.h to minix/fs/const.h /usr/include/fs/super.h to minix/fs/super.h /usr/include/fs/type.h to minix/fs/type.h In addition, the files dosread, dosdir, and doswrite in /usr/bin should all be links to the same file. It determines which it is by looking at argv[0]. 26. SPACE If you are running on a system with limited memory, either 512K RAM or no hard disk, you may encounter difficulties trying to recompile the system. However, there are steps you can take to improve the situation. First, various passes of the compiler are configured with ample stack space. Using chmem you can reduce this stack space to reduce the program's memory requirements. Be careful about not reducing it too much, or strange things will happen. Second, the compiler flag -T can be used to place temporary files in a place other than /tmp. This flag may be useful if /tmp is on the RAM disk, which is too small. Third, the compiler flag -F can be used to run cpp and cem sequentially instead of in parallel. This approach is slower but uses less memory. Fourth, the library, libc.a contains several large routines that are rarely used. By removing these, you can reduce the amount of space the library requires. 27. LIBRARY Not all the sources in minix/lib have been included in libc.a (to save space). If you have a hard disk and enough space, compare the sources and binaries and add the missing files. Remember to compile all library routines with cc -c -LIB file.c. The -LIB flag is essential for libraries. 28. PASCAL AND MODULA 2 COMPILERS FOR MINIX A MINIX compiler for Pascal is available. A MINIX compiler for Modula 2 will available during the course of 1988. Neither is part of the standard distribution. They may be purchased from either of: Unipress Software Transmediair Utrecht B.V. 2025 Lincoln Highway Melkweg 3 Edison, NJ 08817 3721 RG Bilthoven USA Holland Tel: (201) 985-8000 Tel: (30) 78 18 20 These companies also sell the sources to the MINIX C compiler, and the Amsterdam Compiler Kit, from which all the compilers have been derived.