Return to mint.doc CVS log

Up to [Atari MiNT] / MiNT / doc

Annotation of MiNT/doc/mint.doc, revision 1.1

1.1     ! root        1: MiNT is Not TOS: A Multitasking Operating System Extension for the Atari ST
        !             2: 
        !             3: 
        !             4: 
        !             5: Copyright 1990,1991,1992 Eric R. Smith. All rights reserved. See the file
        !             6: 
        !             7: "copying" for conditions of redistribution.
        !             8: 
        !             9: 
        !            10: 
        !            11: WARNING: This program does some very low level things to your computer.
        !            12: 
        !            13: MiNT works well on my machine, and I trust my data to it. But
        !            14: 
        !            15: then, I make regular backups, so even if a horrible bug in MiNT that
        !            16: 
        !            17: I haven't found yet trashes my hard drive, I won't lose much. You'll
        !            18: 
        !            19: have to decide for yourself about trusting your data to MiNT. I would
        !            20: 
        !            21: certainly recommend regular backups in any event.
        !            22: 
        !            23: 
        !            24: 
        !            25: MiNT COMES WITH ABSOLUTELY NO WARRANTY, NOR WILL I BE LIABLE FOR ANY
        !            26: 
        !            27: DAMAGES INCURRED FROM THE USE OF IT. USE ENTIRELY AT YOUR OWN RISK!!!
        !            28: 
        !            29: 
        !            30: 
        !            31: Introduction
        !            32: 
        !            33: 
        !            34: 
        !            35: MiNT is an extension of (and eventually, I hope, a replacement for) TOS.
        !            36: 
        !            37: It provides extra services such as multitasking and pipes. If you don't
        !            38: 
        !            39: know what those terms mean, MiNT is probably not for you -- at this stage,
        !            40: 
        !            41: MiNT is still very incomplete and should be regarded as "experimental".
        !            42: 
        !            43: 
        !            44: 
        !            45: MiNT will run a great number of ("most", I hope) TOS programs, including
        !            46: 
        !            47: GEM. As the name says, though, MiNT is not TOS, so it can't be expected to
        !            48: 
        !            49: run all TOS programs, or even all well-behaved TOS programs (although I hope
        !            50: 
        !            51: that it will run "almost all" of the latter!). There are two classes of
        !            52: 
        !            53: incompatibilities with TOS: bugs and features. Bugs are undoubtedly
        !            54: 
        !            55: present; if you find any please report them to me. There are also some
        !            56: 
        !            57: features of MiNT that may cause incompatibilites. Most of these are listed
        !            58: 
        !            59: in the accompanying "features" file. 
        !            60: 
        !            61: 
        !            62: 
        !            63: MiNT tries to emulate TOS 1.4 very closely. If you have TOS 1.0 or 1.2,
        !            64: 
        !            65: you may think you can use MiNT instead of buying TOS 1.4. This isn't really
        !            66: 
        !            67: a very good idea, because MiNT calls TOS, and so having the newer version
        !            68: 
        !            69: of TOS will really speed things up. Besides, the GEM that comes with TOS 1.4
        !            70: 
        !            71: is a lot better than the old GEM.
        !            72: 
        !            73: 
        !            74: 
        !            75: 
        !            76: 
        !            77: Using MiNT
        !            78: 
        !            79: 
        !            80: 
        !            81: MiNT can be started from an AUTO folder, by setting it as a BOOT program
        !            82: 
        !            83: on the desktop (TOS 1.4 or higher only) or by running it. I prefer the AUTO
        !            84: 
        !            85: folder way myself.
        !            86: 
        !            87: 
        !            88: 
        !            89: If you put it in an AUTO folder, it should be the last thing in the folder
        !            90: 
        !            91: (since any later programs in the folder will run only after MiNT is finished,
        !            92: 
        !            93: and MiNT should never finish). MiNT will try to run a program called
        !            94: 
        !            95: "init.prg" in the current directory  (which is the root directory if MiNT
        !            96: 
        !            97: was started from an AUTO folder). If this program isn't found, MiNT will
        !            98: 
        !            99: boot up GEM. You can change the name of the initial program to run
        !           100: 
        !           101: via the "mint.cnf" file (see below).
        !           102: 
        !           103: 
        !           104: 
        !           105: Once MiNT is running, the computer should behave just as it does under TOS,
        !           106: 
        !           107: except that some new drives (U, Q, V, and X) will be available, background
        !           108: 
        !           109: processes can be started, and programs can use the new features of MiNT.
        !           110: 
        !           111: 
        !           112: 
        !           113: MiNT can be asked to provide a trace of the currently executing programs.
        !           114: 
        !           115: Hitting CTRL-ALT-F1 increases the debugging level; hitting CTRL-ALT-F2
        !           116: 
        !           117: decreases it, and hitting CTRL-ALT-F3 changes where the debugging output
        !           118: 
        !           119: goes; pressing it once changes it from the screen to the printer, pressing
        !           120: 
        !           121: it again changes it to the RS232 port, pressing a third time sends debugging
        !           122: 
        !           123: output to the MIDI port. Pressing CTRL-ALT-F4 resets output to the screen.
        !           124: 
        !           125: This feature was designed to aid in debugging MiNT itself, but can also be
        !           126: 
        !           127: useful in finding problems with user programs. Debugging level 0 (the normal)
        !           128: 
        !           129: prints messages only when something goes seriously wrong inside of MiNT itself. 
        !           130: 
        !           131: Debugging level 1 prints a message when any system call fails. Debugging level
        !           132: 
        !           133: 2 provides a (sickeningly) exhaustive trace of what's going on in the system.
        !           134: 
        !           135: 
        !           136: 
        !           137: CTRL-ALT-F5 shows what memory is being used in the system
        !           138: 
        !           139: CTRL-ALT-F6 prints a list of all processes in the system
        !           140: 
        !           141: CTRL-ALT-DEL provides a (warm) boot, as in TOS >= 1.4, and
        !           142: 
        !           143: CTRL-ALT-SHIFT-DEL provides a cold boot.
        !           144: 
        !           145: 
        !           146: 
        !           147: Some other keys are recognized by MiNT if the process is doing I/O in
        !           148: 
        !           149: "cooked" mode:
        !           150: 
        !           151: ^C (CTRL-C): interrupt running program with signal SIGINT. This (usually)
        !           152: 
        !           153:        will kill the process, unless it has made arrangements to catch it.
        !           154: 
        !           155:        Note that ^C takes effect immediately under MiNT, whereas under TOS
        !           156: 
        !           157:        it only takes effect when the process reads or writes.
        !           158: 
        !           159: ^\: send a QUIT signal to a process; usually the same end result as ^C, but
        !           160: 
        !           161:        it is guaranteed to kill a TOS program (only MiNT specific programs
        !           162: 
        !           163:        know how to catch it). Use with caution.
        !           164: 
        !           165: ^Z: suspend the current process
        !           166: 
        !           167: 
        !           168: 
        !           169: These keys do *not* have any effect on processes operating in "raw" mode,
        !           170: 
        !           171: such as editors. However, you can force these to work even on such programs
        !           172: 
        !           173: by holding down the ALT key as well, i.e. CTRL-ALT-Z will always suspend
        !           174: 
        !           175: the process. You should use caution when doing this, since some programs
        !           176: 
        !           177: will function incorrectly and/or lose data if interrupted when they
        !           178: 
        !           179: aren't expecting it.
        !           180: 
        !           181: 
        !           182: 
        !           183: 
        !           184: 
        !           185: The MiNT Configuration File
        !           186: 
        !           187: 
        !           188: 
        !           189: If MiNT finds a file called "mint.cnf" in the directory that it was
        !           190: 
        !           191: started from, it will read some configuration information from it. This
        !           192: 
        !           193: file is an ordinary ASCII text file; it can be created with any editor
        !           194: 
        !           195: that will produce plain ASCII files (if you're using a fancy word
        !           196: 
        !           197: processor, make sure you save the file as "plain ASCII text" or
        !           198: 
        !           199: "unformatted text" or whatever).
        !           200: 
        !           201: 
        !           202: 
        !           203: The commands in mint.cnf are placed one per line, and may be of the following
        !           204: 
        !           205: forms:
        !           206: 
        !           207: 
        !           208: 
        !           209: INIT=d:\foo\bar.prg
        !           210: 
        !           211:        This specifies the drive and full path name to the program you
        !           212: 
        !           213:        want MiNT to run at boot up time. The default is try ".\init.prg",
        !           214: 
        !           215:        if that file exists, otherwise to run the GEM desktop.
        !           216: 
        !           217: HARDSCROLL=25
        !           218: 
        !           219:        This specifies that hardware scrolling should be used for
        !           220: 
        !           221:        the u:\dev\fasttext text accelerator. This dramatically speeds
        !           222: 
        !           223:        up text operations, but may interfere with GEM and graphics
        !           224: 
        !           225:        programs. Put this line *before* any use of u:\dev\fasttext.
        !           226: 
        !           227: CON=u:\dev\fasttext
        !           228: 
        !           229:        Specifies the use of MiNT's built in text accelerator instead
        !           230: 
        !           231:        of the normal BIOS console. This speeds up text output quite
        !           232: 
        !           233:        a bit (more than 300%) but may not be completely compatible;
        !           234: 
        !           235:        in particular, the escape codes for setting foreground/background
        !           236: 
        !           237:        character colors are not supported.
        !           238: 
        !           239: PRN=d:\foo\bar
        !           240: 
        !           241:        Specifies a file that should be used for all printer output.
        !           242: 
        !           243:        (The default is u:\dev\centr, which is the device corresponding
        !           244: 
        !           245:        to the centronics port.)
        !           246: 
        !           247: 
        !           248: 
        !           249: cd d:\foo
        !           250: 
        !           251:        Change the current drive and directory. This isn't terribly
        !           252: 
        !           253:        useful, unless your initial program (see above) expects to run
        !           254: 
        !           255:        with some particular directory as the current one.
        !           256: 
        !           257: 
        !           258: 
        !           259: exec d:\bin\prog.prg arg1 arg2 ...
        !           260: 
        !           261:        Execute a program, with some arguments. The full path name and
        !           262: 
        !           263:        extension (.prg, .tos, .ttp, or whatever) of the program to
        !           264: 
        !           265:        execute must be given.
        !           266: 
        !           267: 
        !           268: 
        !           269: ren d:\nm1 d:\nm2
        !           270: 
        !           271:        Rename a file or directory. This is useful mainly on the pseudo-drive
        !           272: 
        !           273:        v:, which refers to devices. For example, the RS232 port on the ST
        !           274: 
        !           275:        is called "v:\modem1". Earlier versions of MiNT called this
        !           276: 
        !           277:        "v:\rs232", so if your programs care about this you might want
        !           278: 
        !           279:        to put "ren v:\modem1 v:\rs232" to maintain compatibility.
        !           280: 
        !           281:        Similarly, if your software has been ported from Unix and expects
        !           282: 
        !           283:        terminals to be called "tty*", then you might want to put
        !           284: 
        !           285:        "ren v:\modem1 v:\tty1" instead.
        !           286: 
        !           287: 
        !           288: 
        !           289: setenv FOO BAR
        !           290: 
        !           291:        Set the environment variable FOO to the value BAR. NOTE: If any
        !           292: 
        !           293:        setenv commands are given in mint.cnf, an entirely new environment
        !           294: 
        !           295:        is constructed; this means that any environment variables set by
        !           296: 
        !           297:        a program in the AUTO folder will be ignored by programs run under
        !           298: 
        !           299:        MiNT. This allows you to have two default environments, one for
        !           300: 
        !           301:        running under MiNT set in mint.cnf, and one for normal TOS set
        !           302: 
        !           303:        by an AUTO folder program.
        !           304: 
        !           305: 
        !           306: 
        !           307: sln d:\foo\bar u:\baz
        !           308: 
        !           309:        Create a symbolic link called "u:\baz" for the file (or directory)
        !           310: 
        !           311:        d:\foo\bar. Only drive u: supports symbolic links, so the second
        !           312: 
        !           313:        name *must* be on drive u:; the first name can be anything.
        !           314: 
        !           315:        A symbolic link is just an alias or nickname for a file; if the
        !           316: 
        !           317:        sample line is included in your mint.cnf file, then references
        !           318: 
        !           319:        to u:\baz are automatically translated by the kernel so that
        !           320: 
        !           321:        they "really" refer to d:\foo\bar. If d:\foo\bar is actually
        !           322: 
        !           323:        a subdirectory, with the file "frob.txt" in it, then that
        !           324: 
        !           325:        file can be accessed either through the name "d:\foo\bar\frob.txt"
        !           326: 
        !           327:        or "u:\baz\frob.txt".
        !           328: 
        !           329: 
        !           330: 
        !           331:        Symbolic links are often used to tell programs where to look for
        !           332: 
        !           333:        files; in this respect they're somewhat like environment variables.
        !           334: 
        !           335:        Some "standard" links are:
        !           336: 
        !           337:                u:\bin          directory to find programs in
        !           338: 
        !           339:                u:\etc          directory to find certain general
        !           340: 
        !           341:                                configuration files (e.g. passwd and termcap)
        !           342: 
        !           343:                u:\local        directory to find node-specific files in
        !           344: 
        !           345:                                (for networked systems)
        !           346: 
        !           347:                u:\lib          directory to find C libraries in
        !           348: 
        !           349:                u:\include      directory to find C header files in
        !           350: 
        !           351:        You can use whatever of these are convenient, or add some others
        !           352: 
        !           353:        of your own.
        !           354: 
        !           355: 
        !           356: 
        !           357: 
        !           358: 
        !           359: Pseudo Drives
        !           360: 
        !           361: 
        !           362: 
        !           363: MiNT provides some fake "disk drives"; if the contents of these drives
        !           364: 
        !           365: are listed, various "files" are shown. These "files" are not necessarily
        !           366: 
        !           367: real files, but may represent other objects such as executing programs or
        !           368: 
        !           369: regions of memory.
        !           370: 
        !           371: 
        !           372: 
        !           373: The most important of these pseudo drives is drive U:. This is a
        !           374: 
        !           375: "unified" file system that has all other drives as subdirectories.
        !           376: 
        !           377: For example, U:\A\FOO\BAR is another name for the file A:\FOO\BAR.
        !           378: 
        !           379: Symbolic links can also be created from drive U: to other drives;
        !           380: 
        !           381: e.g. if the line
        !           382: 
        !           383:        sln U:\ETC C:\UNIX\ETC
        !           384: 
        !           385: appears in mint.cnf, then the file U:\ETC\TERMCAP will be another
        !           386: 
        !           387: name for the file C:\UNIX\ETC\TERMCAP, and so on.
        !           388: 
        !           389: 
        !           390: 
        !           391: Finally, drive U: contains some special subdirectories, as follows:
        !           392: 
        !           393: 
        !           394: 
        !           395: U:\PIPE contains files which are FIFO queues (e.g. pipes). All files
        !           396: 
        !           397: created in this directory are temporary; when the last program using a FIFO
        !           398: 
        !           399: closes it, it is erased. Normally, U:\PIPE will be empty, but it will
        !           400: 
        !           401: have items on it when you're running a window manager, print spooler,
        !           402: 
        !           403: or similar program that uses FIFOs or pseudo-ttys for communication.
        !           404: 
        !           405: 
        !           406: 
        !           407: U:\DEV contains files which correspond to the BIOS devices; this allows
        !           408: 
        !           409: you to access these devices from within programs. For example, saving an
        !           410: 
        !           411: ASCII text file to "U:\DEV:\PRN" should cause it to be printed on your printer.
        !           412: 
        !           413: Of course, this will work *only* with ASCII data, so don't expect to get
        !           414: 
        !           415: anything meaningful printed if you try to save your spreadsheet to "U\DEV\PRN"!
        !           416: 
        !           417: The following devices are available:
        !           418: 
        !           419:    CENTR: the centronics printer port
        !           420: 
        !           421:    MODEM1: the RS232 serial port
        !           422: 
        !           423:    MIDI: midi port
        !           424: 
        !           425:    KBD: intelligent keyboard controller
        !           426: 
        !           427:    PRN: printer device (not necessarily the real printer if redirected)
        !           428: 
        !           429:    AUX: auxiliary terminal (usually, but not always, the rs232 port)
        !           430: 
        !           431:    CON: current control terminal (NOT necessarily the keyboard/screen!)
        !           432: 
        !           433:    TTY: same as above
        !           434: 
        !           435:    STDIN: current file handle 0 (standard input)
        !           436: 
        !           437:    STDOUT: current file handle 1 (standard output)
        !           438: 
        !           439:    STDERR: current file handle 2 (standard error)
        !           440: 
        !           441:    CONSOLE: (physical console) the keyboard/screen
        !           442: 
        !           443:    FASTTEXT: an alternate, faster text device for the console screen
        !           444: 
        !           445:    MOUSE: a Sun compatible mouse device. Don't use this directly;
        !           446: 
        !           447:           use the AES/VDI functions instead.
        !           448: 
        !           449:    NULL: a null device (like Unix's /dev/null)
        !           450: 
        !           451: 
        !           452: 
        !           453: The "STD*" file handles are useful for providing I/O redirection to programs
        !           454: 
        !           455: that normally require file names on the command line; for example, if you
        !           456: 
        !           457: want to run such a program in a pipeline.
        !           458: 
        !           459: 
        !           460: 
        !           461: U:\PROC has special files that represent all currently executing
        !           462: 
        !           463: processes, such as whether they're running, ready, or waiting, their process
        !           464: 
        !           465: i.d. numbers, and the amount of memory they've taken. Deleting one of the
        !           466: 
        !           467: "files" kills the corresponding process. (Killing MiNT is impossible;
        !           468: 
        !           469: killing GEM is a very bad idea). The "files" will have names like "INIT.001";
        !           470: 
        !           471: this means that the process name is "INIT" (presumably because it was started
        !           472: 
        !           473: from a file like "INIT.PRG"), and its process i.d. is 1. You can rename
        !           474: 
        !           475: processes just as if they were files, except that any extension you give is
        !           476: 
        !           477: always replaced with the process i.d. (e.g. if you rename INIT.001 to FOO.BAR,
        !           478: 
        !           479: it will really become FOO.001). The size of a process is the amount of memory
        !           480: 
        !           481: that is allocated to it. Its date/time stamp indicates when it started
        !           482: 
        !           483: executing. A process' current state is reflected by its attribute bits; most
        !           484: 
        !           485: of these are not visible from the desktop, alas, but here are the combinations
        !           486: 
        !           487: and their meanings:
        !           488: 
        !           489:        attribute         process state
        !           490: 
        !           491:          0x00          currently running
        !           492: 
        !           493:          0x01          ready to run
        !           494: 
        !           495:          0x20          waiting for an event (e.g. for a child to finish)
        !           496: 
        !           497:          0x21          waiting for I/O
        !           498: 
        !           499:          0x22          zombie (exited, but parent doesn't know yet)
        !           500: 
        !           501:          0x02          terminated and resident
        !           502: 
        !           503:          0x24          stopped by a signal
        !           504: 
        !           505: Deleting a "file" in U:\PROC will send a SIGTERM signal to the corresponding
        !           506: 
        !           507: process, which will usually result in that process being terminated. It
        !           508: 
        !           509: is not possible to delete processes which are terminated and resident,
        !           510: 
        !           511: or zombie processes.
        !           512: 
        !           513: 
        !           514: 
        !           515: U:\SHM is a place for shared memory. A program may create a file in U:\SHM
        !           516: 
        !           517: and attach a block of memory to it. Thereafter, other programs may open
        !           518: 
        !           519: that file and use the memory. This provides a fast way to transfer large
        !           520: 
        !           521: amounts of data between processes.
        !           522: 
        !           523: 
        !           524: 
        !           525: Other pseudo drives that are available are Q:, V:, and X:. These are just
        !           526: 
        !           527: aliases for U:\PIPE, U:\DEV, and U:\PROC, respectively, and exist for
        !           528: 
        !           529: backwards compatibility. Don't use them in new applications; they will
        !           530: 
        !           531: go away soon.
        !           532: 
        !           533: 
        !           534: 
        !           535: Note that the TOS 1.0 desktop won't recognize drives above P. Other versions
        !           536: 
        !           537: of TOS will, though, so you can use the Install Drive menu selection to
        !           538: 
        !           539: install the pseudo drives so that the desktop can recognize them.
        !           540: 
        !           541: 
        !           542: 
        !           543: 
        !           544: 
        !           545: File Handles and Devices
        !           546: 
        !           547: 
        !           548: 
        !           549: File handle -1 refers to the current control terminal, NOT necessarily
        !           550: 
        !           551: the console (this is where it points by default). BIOS handle 2 also
        !           552: 
        !           553: refers to the control terminal, so that e.g. Bconout(2, c) outputs
        !           554: 
        !           555: a character to the control terminal. Thus,
        !           556: 
        !           557:        Fforce(-1, Fopen("U:\DEV\MODEM1", 3));
        !           558: 
        !           559:        r = Bconin(2);
        !           560: 
        !           561: reads a character from the RS232 port under MiNT. This is done so that
        !           562: 
        !           563: programs that use the BIOS for I/O will be able to run in windows or
        !           564: 
        !           565: over the modem. Similarly, the DOS device CON: refers to the current
        !           566: 
        !           567: control terminal, so Fopen("CON:", 3) is normally equivalent to Fdup(-1).
        !           568: 
        !           569: To access the physical console, use device U:\DEV\CONSOLE.
        !           570: 
        !           571: 
        !           572: 
        !           573: In a similar fashion, file handle -2 and bios device 1 (DOS device AUX:)
        !           574: 
        !           575: may be redirected away from the RS232 port (device U:\DEV\MODEM1), and
        !           576: 
        !           577: file handle -3 and bios device 0 (DOS device PRN:) may be directed away
        !           578: 
        !           579: from the Centronics printer port (device U:\DEV\CENTR). Since both the DOS
        !           580: 
        !           581: handles and BIOS device numbers are redirected, any program at all will
        !           582: 
        !           583: obey the redirection unless it accesses the hardware directly (or unless
        !           584: 
        !           585: it was written for MiNT and specifically uses the new device names
        !           586: 
        !           587: like U:\DEV\CENTR; this should be done only if *absolutely* necessary!).
        !           588: 
        !           589: See also the PRN= and CON= commands for mint.cnf, which provide another
        !           590: 
        !           591: way to redirect the printer and console (actually, it's just another
        !           592: 
        !           593: interface to the same method of redirection).
        !           594: 
        !           595: 
        !           596: 
        !           597: File handles -4 and -5 are new with MiNT, and refer to the MIDI input
        !           598: 
        !           599: and output devices respectively. Redirecting these handles will affect
        !           600: 
        !           601: BIOS operations on bios device 4 (the MIDI port).
        !           602: 
        !           603: 
        !           604: 
        !           605: 
        !           606: 
        !           607: Background Processes
        !           608: 
        !           609: 
        !           610: 
        !           611: (Note that the programs bg.ttp and pipe.ttp, along with some other
        !           612: 
        !           613: sample MiNT utilities, are found in a separate file called
        !           614: 
        !           615: "mntutl.zoo").
        !           616: 
        !           617: 
        !           618: 
        !           619: Programs may be started in the background. A sample program ("bg.ttp")
        !           620: 
        !           621: is provided that will do this for you. It works best from a shell;
        !           622: 
        !           623: for example, to make foo.ttp in the background from gulam, type:
        !           624: 
        !           625:        cd \foo\src
        !           626: 
        !           627:        bg.ttp -o make.out make foo.ttp
        !           628: 
        !           629: The "-o make.out" tells "bg" to redirect the command's standard tty,
        !           630: 
        !           631: output, and error output (handles -1, 1, and 2) to "make.out".
        !           632: 
        !           633: You might also want to redirect the standard input from an empty
        !           634: 
        !           635: file, or from a file that will never have input waiting (like V:\NUL)
        !           636: 
        !           637: so that "make" won't try to read anything from your console.
        !           638: 
        !           639: 
        !           640: 
        !           641: Shells designed to work with MiNT (for example, the "mintshel.ttp" that is
        !           642: 
        !           643: provided with the MiNT utilities) may use the Unix "&" notation for running
        !           644: 
        !           645: processes in the background; with this notation, the job above would be:
        !           646: 
        !           647:        cd \foo\src
        !           648: 
        !           649:        make foo.ttp >make.out &
        !           650: 
        !           651: (here the ">make.out" is the notation for redirecting the standard output
        !           652: 
        !           653: of a process). Note that the sample shell does not provide a way of
        !           654: 
        !           655: redirecting the standard error output; however, it does provide job
        !           656: 
        !           657: control, and processes that try to write on the terminal
        !           658: 
        !           659: will be stopped automatically. See "Job Control" below.
        !           660: 
        !           661: 
        !           662: 
        !           663: 
        !           664: 
        !           665: Pipes
        !           666: 
        !           667: 
        !           668: 
        !           669: Pipes are special files that are used to communicate between processes. The
        !           670: 
        !           671: data in a pipe is always in memory, so using a pipe instead of a temporary
        !           672: 
        !           673: file is usually faster; it also doesn't consume disk space. Only 2048 bytes
        !           674: 
        !           675: can be held in a pipe at once; when a process tries to write more data,
        !           676: 
        !           677: it is suspended until another process reads some data, thus "emptying"
        !           678: 
        !           679: the pipe. If there are no more readers, a process writing on a pipe is
        !           680: 
        !           681: terminated.
        !           682: 
        !           683: 
        !           684: 
        !           685: A simple "pipe" program is provided to run two programs concurrently,
        !           686: 
        !           687: passing data between them in a pipe. The syntax is
        !           688: 
        !           689:        pipe.ttp cmd1 cmd2
        !           690: 
        !           691: which is equivalent to the Unix "cmd1 | cmd2". Note that if cmd1 or cmd2
        !           692: 
        !           693: contain arguments, then you must run the "pipe" program from a shell that
        !           694: 
        !           695: supports the Atari standard extended argument convention, and that you
        !           696: 
        !           697: must enclose the commands in quotes, e.g. in gulam:
        !           698: 
        !           699:        set env_style mw        # extended arguments
        !           700: 
        !           701:        pipe 'ls.ttp -l foo' 'fgrep.ttp myfile'
        !           702: 
        !           703: does the same as the Unix command
        !           704: 
        !           705:        ls -l foo | fgrep myfile
        !           706: 
        !           707: or using a temporary file
        !           708: 
        !           709:        ls -l foo >junk; fgrep myfile <junk; rm junk
        !           710: 
        !           711: 
        !           712: 
        !           713: Shells designed to work explicitly with MiNT will probably not need the
        !           714: 
        !           715: external "pipe" command, and instead will use the Unix notation for
        !           716: 
        !           717: pipelines. This second method is preferable, as it provides a way of
        !           718: 
        !           719: joining more than two programs in a pipeline.
        !           720: 
        !           721: 
        !           722: 
        !           723: 
        !           724: 
        !           725: Job Control
        !           726: 
        !           727: 
        !           728: 
        !           729: MiNT supports a terminal access protocol for job control. The ^Z
        !           730: 
        !           731: (control-Z) key can be used to suspend a process. The process can
        !           732: 
        !           733: be restarted again if it is sent the appropriate signal. There is
        !           734: 
        !           735: also a "delayed" suspend key, ^Y, that takes effect only when
        !           736: 
        !           737: a process attempts to read it.
        !           738: 
        !           739: 
        !           740: 
        !           741: Some programs written for TOS put the terminal in "raw" mode, where no
        !           742: 
        !           743: control characters are interpreted. You can use CTRL-ALT-Z to achieve
        !           744: 
        !           745: the effect of ^Z for such programs. However, this feature should be used
        !           746: 
        !           747: with caution -- it's possible that the TOS program had a good reason
        !           748: 
        !           749: for not wanting to be interrupted!
        !           750: 
        !           751: 
        !           752: 
        !           753: Once a program has been suspended, it must be restarted again. MiNT
        !           754: 
        !           755: aware shells (e.g. mintshel.ttp) usually provide some sort of
        !           756: 
        !           757: "fg" command that restarts the suspended process and brings it to
        !           758: 
        !           759: the foreground. This suspend-restart cycle may be performed any
        !           760: 
        !           761: number of times.
        !           762: 
        !           763: 
        !           764: 
        !           765: If the terminal mode "tostop" is set (this is the default), then any
        !           766: 
        !           767: background program that tries to write to the console will be suspended
        !           768: 
        !           769: automatically; it must then be brought to the foreground with the
        !           770: 
        !           771: "fg" command before the write continues. This behavior may be changed
        !           772: 
        !           773: with the "stty" utility; after an "stty -tostop" command is issued,
        !           774: 
        !           775: background programs will no longer be suspended when they write to the
        !           776: 
        !           777: terminal.
        !           778: 
        !           779: 
        !           780: 
        !           781: Background programs that try to read input from the console will also
        !           782: 
        !           783: be automatically suspended until brought into the foreground. This
        !           784: 
        !           785: happens regardless of the setting of the "tostop" flag.
        !           786: 
        !           787: 
        !           788: 
        !           789: 
        !           790: 
        !           791: Programming with MiNT
        !           792: 
        !           793: 
        !           794: 
        !           795: A file (mintbind.h) is provided that gives a C interface to the new
        !           796: 
        !           797: MiNT system calls. Users of other programming languages will have to write
        !           798: 
        !           799: the interfaces themselves; it should be relatively straightforward, as long
        !           800: 
        !           801: as your compiler provides a way to call GEMDOS directly.
        !           802: 
        !           803: 
        !           804: 
        !           805: Testing for the presence of MiNT:
        !           806: 
        !           807: 
        !           808: 
        !           809: There are several ways to check to see if MiNT is active. The best
        !           810: 
        !           811: way is to check the cookie jar; MiNT installs a cookie of
        !           812: 
        !           813: 0x4d694e54 (in ASCII, 'MiNT'), with a value consisting of the major/
        !           814: 
        !           815: minor version numbers in the high/low bytes of the low word. Thus, MiNT
        !           816: 
        !           817: version 1.2 will have a cookie value of 0x00000102L. (This isn't
        !           818: 
        !           819: the place to explain the cookie jar, but basically it's a list of
        !           820: 
        !           821: (cookie, value) pairs of longwords, terminated by cookie 0; a pointer
        !           822: 
        !           823: to the jar is found at 0x5a0. MiNT always installs a cookie jar; versions
        !           824: 
        !           825: of TOS prior to 1.6 don't always, in which case 0x5a0 will contain 0).
        !           826: 
        !           827: 
        !           828: 
        !           829: A "quick and dirty" way to see if MiNT is active is to make a system
        !           830: 
        !           831: call that only exists under MiNT (preferably one with no side effects!).
        !           832: 
        !           833: Pgetpid() or Syield() are good choices. If MiNT is not active, these
        !           834: 
        !           835: calls will fail, returning -32 (invalid function). This method has the
        !           836: 
        !           837: disadvantage that future versions of TOS, or other multitasking programs,
        !           838: 
        !           839: may use the same trap numbers as MiNT, but have different meanings.
        !           840: 
        !           841: For this reason, the "cookie jar" method is preferred.
        !           842: 
        !           843: 
        !           844: 
        !           845: Interprocess Communication:
        !           846: 
        !           847: 
        !           848: 
        !           849: MiNT provides 5 forms of interprocess communication (IPC): signals, fifos,
        !           850: 
        !           851: shared memory, message passing, and semaphores.
        !           852: 
        !           853: 
        !           854: 
        !           855: Signals:
        !           856: 
        !           857: 
        !           858: 
        !           859: Signals are a way of notifying a process of an event. The Pkill(pid, sig)
        !           860: 
        !           861: system call is used to send signal number "sig" to the process with process
        !           862: 
        !           863: id "pid". It is called "Pkill" because the default action of most signals is
        !           864: 
        !           865: to terminate the process. If a process wishes to catch a signal and do
        !           866: 
        !           867: processing, it can use the Psignal(sig, func) system call to arrange to have
        !           868: 
        !           869: function "func" called when signal "sig" is received. If func is 0, then
        !           870: 
        !           871: the default action is restored. If func is 1, then the signal will be ignored.
        !           872: 
        !           873: 
        !           874: 
        !           875: Processes can temporarily block receipt of signals via the Psigblock() and
        !           876: 
        !           877: Psigsetmask() system calls.
        !           878: 
        !           879: 
        !           880: 
        !           881: See the file "signal.doc" for a more complete explanation of signals.
        !           882: 
        !           883: 
        !           884: 
        !           885: Fifos:
        !           886: 
        !           887: 
        !           888: 
        !           889: Fifos are "first in first out" message queues. Pipes are a special kind of
        !           890: 
        !           891: (unidirectional) fifo. Fifos are represented by files in the subdirectory
        !           892: 
        !           893: "PIPE" on drive "U:". They are created with the Fcreate(name, flags)
        !           894: 
        !           895: system call. "name" will be the name under which the fifo is known
        !           896: 
        !           897: (maximum 13 characters); "flags" is explained below. The returned file handle
        !           898: 
        !           899: is treated just like an ordinary file, and may be written to and read from
        !           900: 
        !           901: (unless the fifo is unidirectional, in which case it may only be written to).
        !           902: 
        !           903: The program that creates the fifo is normally called the "server". Other
        !           904: 
        !           905: programs ("clients") may use the Fopen(name, mode) system call to open the
        !           906: 
        !           907: other end of the fifo and read the data that the server writes, or write data
        !           908: 
        !           909: for the server to read. When the last program (either client or server) using
        !           910: 
        !           911: a fifo closes it, the fifo is deleted automatically. Note that one program can
        !           912: 
        !           913: be both client and server, if it creates a fifo with Fcreate and then opens it
        !           914: 
        !           915: again with Fopen. Also, children of the server can inherit the Fcreate'd file
        !           916: 
        !           917: handle and thus have access to the "server" side of the fifo.
        !           918: 
        !           919: 
        !           920: 
        !           921: The bits in the "flags" argument to Fcreate have the following meanings:
        !           922: 
        !           923: 0x01: make fifo unidirectional (server can write, clients can read)
        !           924: 
        !           925: 0x02: cause reads to return EOF if no other processes are writing, and writes
        !           926: 
        !           927:       to raise the SIGPIPE signal if no other processes are reading. The
        !           928: 
        !           929:       default action (if this flag is not given) is to block waiting for
        !           930: 
        !           931:       reads and writes
        !           932: 
        !           933: 0x04: make the fifo a pseudo-tty; to client processes, the fifo will act
        !           934: 
        !           935:       just like a terminal with the server "typing" the characters; for
        !           936: 
        !           937:       example, if the server writes a ^C, SIGINT will be sent to clients
        !           938: 
        !           939: 
        !           940: 
        !           941: Attempting to Fcreate() a fifo with the same name as an already existing
        !           942: 
        !           943: one will result in an access error (i.e. the Fcreate will fail).
        !           944: 
        !           945: 
        !           946: 
        !           947: Pipes may be created through the Fpipe() system call as well as through
        !           948: 
        !           949: the Fcreate/Fopen pair; the former method is easier, since the kernel
        !           950: 
        !           951: takes care of name conflicts, etc.
        !           952: 
        !           953: 
        !           954: 
        !           955: Fifos may be locked by processes via the Fcntl system call, as follows:
        !           956: 
        !           957: 
        !           958: 
        !           959: struct flock {
        !           960: 
        !           961:        short l_type;           /* type of lock */
        !           962: 
        !           963: #define F_RDLCK                0
        !           964: 
        !           965: #define F_WRLCK                1
        !           966: 
        !           967: #define F_UNLCK                3
        !           968: 
        !           969:        short l_whence;         /* what is the lock relative to? */
        !           970: 
        !           971:                /* 0 == start of file, 1 == current pos. in file, 2 == EOF */
        !           972: 
        !           973:        long l_start;           /* start of locked region */
        !           974: 
        !           975:        long l_len;             /* 0 for rest of file */
        !           976: 
        !           977:        short l_pid;            /* set by F_GETLK */
        !           978: 
        !           979: };
        !           980: 
        !           981: 
        !           982: 
        !           983: Fcntl(fd, &lock, F_SETLK): set a lock as specified by the lock structure.
        !           984: 
        !           985: The current version of MiNT only understands locks on the whole FIFO,
        !           986: 
        !           987: so lock.l_start and lock.l_len should both be 0. If lock.l_type is F_UNLCK,
        !           988: 
        !           989: then the lock is released. Otherwise, the file whole file is locked
        !           990: 
        !           991: (future versions of MiNT may distinguish between read and write locks,
        !           992: 
        !           993: but for now all locks are treated as write locks (F_WRLCK) and block both
        !           994: 
        !           995: reads and writes). If another process has locked the fifo, returns -36
        !           996: 
        !           997: (access denied). If a process holding a lock terminates, the fifo is
        !           998: 
        !           999: automatically unlocked.
        !          1000: 
        !          1001: 
        !          1002: 
        !          1003: Fcntl(fd, &lock, F_GETLK): if a lock exists on the fifo, set lock to
        !          1004: 
        !          1005: indicate what kind of lock it is; otherwise, set lock.l_type to F_UNLCK.
        !          1006: 
        !          1007: 
        !          1008: 
        !          1009: Locks are only "advisory"; that is, programs may ignore locks if they
        !          1010: 
        !          1011: choose to do so. However, they are a good way to insure that two clients'
        !          1012: 
        !          1013: data are not mixed together in a fifo.
        !          1014: 
        !          1015: 
        !          1016: 
        !          1017: NOTE: file locking will eventually be implemented for all files, but
        !          1018: 
        !          1019: for now only fifos support file locking.
        !          1020: 
        !          1021: 
        !          1022: 
        !          1023: See the sample LPR and LPD utilites for a demonstration of how to use fifos.
        !          1024: 
        !          1025: 
        !          1026: 
        !          1027: Shared memory:
        !          1028: 
        !          1029: 
        !          1030: 
        !          1031: Children created with the Pexec(4,...) or with Pexec(104,...) share all of
        !          1032: 
        !          1033: their parent's memory, as do children created with the Pvfork() system call.
        !          1034: 
        !          1035: Hence, they may communicate with their parent (or with each other) via
        !          1036: 
        !          1037: global variables.
        !          1038: 
        !          1039: 
        !          1040: 
        !          1041: A more general shared memory mechanism is provided by U:\SHM. Files in
        !          1042: 
        !          1043: that directory represent blocks of memory. A program may offer to share
        !          1044: 
        !          1045: its memory by creating a file in U:\SHM and executing an Fcntl call
        !          1046: 
        !          1047: (SHMSETBLK) to associate a block of memory with the file. Other programs
        !          1048: 
        !          1049: may then open the file and do a SHMGETBLK call to gain access to that
        !          1050: 
        !          1051: memory.
        !          1052: 
        !          1053: 
        !          1054: 
        !          1055: Rendezvous:
        !          1056: 
        !          1057: 
        !          1058: 
        !          1059: The Pmsg() system call provides a simple message based form of IPC. See
        !          1060: 
        !          1061: the manual page for Pmsg for further details. The use of FIFOs is generally
        !          1062: 
        !          1063: to be preferred to Pmsg(), since they are more flexible.
        !          1064: 
        !          1065: 
        !          1066: 
        !          1067: Semaphores:
        !          1068: 
        !          1069: 
        !          1070: 
        !          1071: Semaphores may be created and otherwise accessed via the Psemaphore
        !          1072: 
        !          1073: system call. See the manual page for Psemaphore for more details.
        !          1074: 
        !          1075: 
        !          1076: 
        !          1077: 
        !          1078: 
        !          1079: MiNT extensions to GEMDOS calls:
        !          1080: 
        !          1081: 
        !          1082: 
        !          1083: Fsfirst/Fsnext:
        !          1084: 
        !          1085:     MiNT domain processes (see the Pdomain()) system call below) get
        !          1086: 
        !          1087: lower case filenames from Fsfirst/Fsnext on a TOS filesystem. This is
        !          1088: 
        !          1089: because most programs end up converting them to lowercase anyways, to
        !          1090: 
        !          1091: be more Unix-like. *Please* don't do this translation yourself, let
        !          1092: 
        !          1093: MiNT handle it -- some filesystems (e.g. the minix one) are case
        !          1094: 
        !          1095: sensitive! If you really, truly, prefer uppercase filenames, run in
        !          1096: 
        !          1097: the TOS domain.
        !          1098: 
        !          1099: 
        !          1100: 
        !          1101: Pexec(100, name, cmdline, environment):
        !          1102: 
        !          1103:     Similar to Pexec(0, ...), except the calling program does not wait for
        !          1104: 
        !          1105: the child to finish. Returns a negative error code, or the (positive)
        !          1106: 
        !          1107: process I.D. of the child.
        !          1108: 
        !          1109: 
        !          1110: 
        !          1111: Pexec(104, name, basepage, 0L):
        !          1112: 
        !          1113:     Similar to Pexec(4, ...); starts executing a basepage previously
        !          1114: 
        !          1115: set up by Pexec mode 3, 5, or 7. The caller does not wait for
        !          1116: 
        !          1117: the child to finish. Returns a negative error code, or the process I.D.
        !          1118: 
        !          1119: of the child. Note that the child's environment and basepage are
        !          1120: 
        !          1121: owned by both the child and the parent (indeed, the child shares all
        !          1122: 
        !          1123: memory owned by the parent). "name" is a pointer to a string
        !          1124: 
        !          1125: to be used to supply a name for the new process; if it is NULL, then
        !          1126: 
        !          1127: the parent's name is used.
        !          1128: 
        !          1129: 
        !          1130: 
        !          1131: Pexec(106, name, basepage, 0L):
        !          1132: 
        !          1133:     Similar to Pexec(104,...) except that the child's environment and
        !          1134: 
        !          1135: basepage are *not* owned by the parent; nor does the child share
        !          1136: 
        !          1137: any memory allocated to the parent.
        !          1138: 
        !          1139: 
        !          1140: 
        !          1141: Pexec(200, name, cmdline, environment):
        !          1142: 
        !          1143:     As with Pexec(0,...) and Pexec(100,...) this runs a program. However,
        !          1144: 
        !          1145: with this variant the caller is completely replaced with the executing
        !          1146: 
        !          1147: program. The process retains its process i.d. and most other attributes,
        !          1148: 
        !          1149: but all of its memory is freed and a new address space is set up for it
        !          1150: 
        !          1151: containing the code from the indicated program. Whereas Pexec(0,...)
        !          1152: 
        !          1153: is like a subroutine call, Pexec(200,...) is like a "goto". It returns
        !          1154: 
        !          1155: only if an error occurs that makes it impossible to run the indicated
        !          1156: 
        !          1157: program (e.g. if not enough memory is available, or the file is not
        !          1158: 
        !          1159: found).
        !          1160: 
        !          1161: 
        !          1162: 
        !          1163: 
        !          1164: 
        !          1165: New MiNT calls:
        !          1166: 
        !          1167: 
        !          1168: 
        !          1169: See the manual pages in the man/ subdirectory for descriptions of
        !          1170: 
        !          1171: these calls.
        !          1172: 
        !          1173: 
        !          1174: 
        !          1175: void Syield():                                 [ GEMDOS 0xff ]
        !          1176: 
        !          1177: word Fpipe( word *ptr ):                       [ GEMDOS 0x100 ]
        !          1178: 
        !          1179: long Fcntl( word f, long arg, word cmd):       [ GEMDOS 0x104 ]
        !          1180: 
        !          1181: long Finstat( word f ):                                [ GEMDOS 0x105 ]
        !          1182: 
        !          1183: long Foutstat( word f )                                [ GEMDOS 0x106 ]
        !          1184: 
        !          1185: long Fgetchar(word f, word mode):              [ GEMDOS 0x107 ]
        !          1186: 
        !          1187: long Fputchar( word f, long c, word mode ):    [ GEMDOS 0x108 ]
        !          1188: 
        !          1189: long Pwait():                                  [ GEMDOS 0x109 ]
        !          1190: 
        !          1191: word Pnice( word delta ):                      [ GEMDOS 0x10a ]
        !          1192: 
        !          1193: word Pgetpid():                                        [ GEMDOS 0x10b ]
        !          1194: 
        !          1195: word Pgetppid():                               [ GEMDOS 0x10c ]
        !          1196: 
        !          1197: word Pgetpgrp():                               [ GEMDOS 0x10d ]
        !          1198: 
        !          1199: word Psetpgrp(pid, newgrp):                    [ GEMDOS 0x10e ]
        !          1200: 
        !          1201: word Pgetuid():                                        [ GEMDOS 0x10f ]
        !          1202: 
        !          1203: word Psetuid( word id ):                       [ GEMDOS 0x110 ]
        !          1204: 
        !          1205: word Pkill( word pid, word sig ):              [ GEMDOS 0x111 ]
        !          1206: 
        !          1207: long Psignal(word sig, long handler):          [ GEMDOS 0x112 ]
        !          1208: 
        !          1209: word Pvfork():                                 [ GEMDOS 0x113 ]
        !          1210: 
        !          1211: word Pgetgid():                                        [ GEMDOS 0x114 ]
        !          1212: 
        !          1213: word Psetgid(word id):                         [ GEMDOS 0x115 ]
        !          1214: 
        !          1215: long Psigblock(long mask):                     [ GEMDOS 0x116 ]
        !          1216: 
        !          1217: long Psigsetmask(long mask):                   [ GEMDOS 0x117 ]
        !          1218: 
        !          1219: long Pusrval(long arg):                                [ GEMDOS 0x118 ]
        !          1220: 
        !          1221: word Pdomain(word newdom):                     [ GEMDOS 0x119 ]
        !          1222: 
        !          1223: void Psigreturn():                             [ GEMDOS 0x11a ]
        !          1224: 
        !          1225: word Pfork():                                  [ GEMDOS 0x11b ]
        !          1226: 
        !          1227: long Pwait3(word flag, long *rusage):          [ GEMDOS 0x11c ]
        !          1228: 
        !          1229: word Fselect(word timeout, long *rfds, long *wfds, long *xfds):
        !          1230: 
        !          1231:                                                [ GEMDOS 0x11d ]
        !          1232: 
        !          1233: void Prusage( long r[8] ):                     [ GEMDOS 0x11e ]
        !          1234: 
        !          1235: long Psetlimit(word lim, long value):          [ GEMDOS 0x11f ]
        !          1236: 
        !          1237: long Talarm( long secs ):                      [ GEMDOS 0x120 ]
        !          1238: 
        !          1239: void Pause():                                  [ GEMDOS 0x121 ]
        !          1240: 
        !          1241: long Sysconf( word n ):                                [ GEMDOS 0x122 ]
        !          1242: 
        !          1243: long Psigpending()                             [ GEMDOS 0x123 ]
        !          1244: 
        !          1245: long Dpathconf( char *name, word n ):          [ GEMDOS 0x124 ]
        !          1246: 
        !          1247: long Pmsg( word mode, long mbox, void *msg ):  [ GEMDOS 0x125 ]
        !          1248: 
        !          1249: long Fmidipipe( word pid, word in, word out ): [ GEMDOS 0x126 ]
        !          1250: 
        !          1251: word Prenice( word pid, word delta ):          [ GEMDOS 0x127 ]
        !          1252: 
        !          1253: long Dopendir( char *name, word flag ):                [ GEMDOS 0x128 ]
        !          1254: 
        !          1255: long Dreaddir( word buflen, long dir, char *buf):[GEMDOS 0x129 ]
        !          1256: 
        !          1257: long Drewinddir( long dir ):                   [ GEMDOS 0x12a ]
        !          1258: 
        !          1259: long Dclosedir( long dir ):                    [ GEMDOS 0x12b ]
        !          1260: 
        !          1261: long Fxattr( word flag, char *name, void *buf ):[ GEMDOS 0x12c ]
        !          1262: 
        !          1263: long Flink( char *oldname, char *newname ):    [ GEMDOS 0x12d ]
        !          1264: 
        !          1265: long Fsymlink( char *oldname, char *newname ): [ GEMDOS 0x12e ]
        !          1266: 
        !          1267: long Freadlink( word siz, char *buf, char *name):[GEMDOS 0x12f ]
        !          1268: 
        !          1269: long Dcntl( word cmd, char *name, long arg ):  [ GEMDOS 0x130 ]
        !          1270: 
        !          1271: long Fchown( char *name, word uid, word gid):  [ GEMDOS 0x131 ]
        !          1272: 
        !          1273: long Fchmod( char *name, word mode ):          [ GEMDOS 0x132 ]
        !          1274: 
        !          1275: word Pumask( word mask ):                      [ GEMDOS 0x133 ]
        !          1276: 
        !          1277: long Psemaphore(word mode, long id, long timeout): [ GEMDOS 0x134 ]
        !          1278: 
        !          1279: word Dlock( word mode, word drive ):           [ GEMDOS 0x135 ]
        !          1280: 
        !          1281: void Psigpause( long sigmask ):                        [ GEMDOS 0x136 ]
        !          1282: 
        !          1283: long Psigaction( word sig, long act, long oact):[ GEMDOS 0x137 ]
        !          1284: 
        !          1285: long Pgeteuid():                               [ GEMDOS 0x138 ]
        !          1286: 
        !          1287: long Pgetegid():                               [ GEMDOS 0x139 ]
        !          1288: 

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