![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mint.doc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Atari MiNT] / MiNT / doc|
Return to mint.doc CVS log | Up to [Atari MiNT] / MiNT / doc |
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.