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