home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / utility / disk / pdos_112 / powerdos.txt < prev   
Text File  |  1993-08-02  |  90KB  |  2,316 lines
  1. PowerDOS Programmer's Manual (well, sort of)
  2.  
  3.  
  4. Revision 1.0 - 08/02/93
  5.  
  6.  
  7. (C) 1993 ViewTouch Corp.
  8. 344 NE Terry Lane
  9. Grants Pass, OR 97526
  10. (503)479-4278
  11.  
  12.  
  13.          Who's primarily at fault - Chris Latham
  14. Lots of chiding and snide remarks - Daniel Hollis
  15.  
  16.  
  17. Welcome to the first incarnation of the wonderful, furry,
  18. spicy (low cholesterol) PowerDOS programmer's Manual (TM)!!
  19.  
  20. Included are all the documents needed to push PowerDOS to
  21. (no, make that OVER) its limits. We assume no responsibility
  22. for system crashes, loss of data, destruction of hardware
  23. (willful or otherwise), loss of limbs, divorces, shattered
  24. lives, insanity, paralysis, deaths, or global thermonuclear war
  25. resulting from the use, misuse, unuse, abuse or refuse of this
  26. program.
  27.  
  28. Do not insert document into ear canal. Keep out of reach
  29. of children. May cause dizziness, convulsions, or vomiting.
  30. Keep away from open flame. Wear safety gloves when handling.
  31.  
  32. With all that legal mumbo jumbo out of the way, fasten your
  33. seat belts and off we go!!
  34.  
  35. Enter at own risk!
  36.  
  37. +----------------------------------------------------------------------+
  38.  
  39. First, let's discuss what multitasking is...
  40.  
  41. Well, multitasking is...wait, let me digress for a moment.
  42. What is a computer....wait, let me digress...
  43. Where is the on/off switch?
  44.  
  45. It's in the back.
  46.  
  47. Now that you fully understand multitasking, we'll launch right
  48. into the functions that PowerDOS provides.
  49.  
  50. +----------------------------------------------------------------------+
  51.  
  52. 4B: Program execution 
  53.  
  54. PowerDOS supports four new execution modes, as described below:
  55.  
  56. long errcode = Pexec(0x10,prgfile,cmdline,envptr)
  57.  
  58. This mode is just like mode 0, except that the parent continues to
  59. operate concurrently with the newly created child task. The error
  60. codes only reflect errors that may occurr while trying to create
  61. the task, such as file not found or out of memory. The only way for
  62. the parent to receive the deathcode from the child task, is if it
  63. executes a Wait() before the child terminates. If no error occurrs,
  64. (d0.l is not negative), then d0.w will be the process ID of the new
  65. task.
  66.  
  67. Also like mode 0, the newly created task gets the largest block of
  68. ram for its basepage+text+bss+heap. Since other, concurrently running
  69. processes in the system may try to do Mallocs before the new task
  70. has shrunk its memory usage, it is advisable that the parent process
  71. issues controls as to the amount of memory that the new task will
  72. receive for both its TPA and Malloc(-1) calls that it may issue as it
  73. executes.
  74.  
  75. Function 0xa3 (Pmaxmem) may be used to set the parents maximum
  76. Malloc(-1) return. This max value will be inherited by the child
  77. process as its maximum Malloc(-1) value. Also, function 0x9f may be
  78. used to set the maximum size of the TPA given to a newly created
  79. process. These two variables taken together will give a large
  80. amount of control as to how the memory in the system is used.
  81.  
  82. long errcode = Pexec(0x16,0L,_psp basepage,0L)
  83.  
  84. This is just like mode 6, except that the parent again continues
  85. to execute concurrently, whith the same problem of receiving the
  86. child's deathcode upon its termination.
  87.  
  88. The next two Pexec modes are for support of multiple threads of
  89. execution within a single program:
  90.  
  91. long errcode = Pexec(0x17,char *proc_name,char *cmdline,char *envptr,
  92.                      void *code_ptr,long bss_size,long data_size)
  93.  
  94. This mode allows you to execute a code fragment that is within the text
  95. segment of the calling process. It creates a basepage, followed by a
  96. data segment of the given size (and copies the data from the parents
  97. data segment, for the data size given), followed by a BSS of the
  98. given size. The user stack pointer is placed at the top of the BSS, so
  99. this must be included in the BSS size. At sp+4 will be a pointer to the
  100. basepage, the same as Pexec mode 0. Also register a5 will point to the
  101. start of the data segment, and register a4 will point to the start of
  102. the BSS. proc_name is the name the process will be known by, and must
  103. be a null terminated string of no more than 13 characters. The code
  104. fragment may directly access or modify variables in its parents
  105. data or BSS segments, using pc relative or absolute addresses. Access
  106. to the thread's private data and BSS segments, however, may only be
  107. accomplished using relative offsets from an address register.
  108.  
  109. long errcode = Pexec(0x18,char *proc_name,char *cmdline,char *envptr,
  110.                      void *code_ptr,long bss_size,long data_size,
  111.                      int var_ints,int *vars[])
  112.  
  113. This is the same as mode 0x17, except that it allows a number of ints
  114. to be placed on the stack of the new task (thus the basepage pointer
  115. will not be at sp+4). var_ints is the number of ints to copy onto the
  116. stack, and vars is a pointer to the ints to copy. 
  117.  
  118. +--------------------------------------------------------------------------+
  119.  
  120. 7.1 5C: Lock/unlock File Access
  121.  
  122. long Flock(handle, mode, start, length)
  123. word handle;
  124. word mode;
  125. long start;
  126. long length;
  127. {
  128. }
  129.  
  130.      +-------------------------------------+ Low memory (parameter
  131.      |         Function Code  0x5c         | Word        block addr)
  132.      +-------------------------------------+
  133.      |             File Handle             | Word 1
  134.      +-------------------------------------+
  135.      |                 Mode                | Word 2
  136.      +-------------------------------------+
  137.      |                                     |
  138.      +            Start of Lock            + Long 1
  139.      |                                     |
  140.      +-------------------------------------+
  141.      |                                     |
  142.      +           Length of Lock            + Long 2
  143.      |                                     |
  144.      +-------------------------------------+ High memory
  145.  
  146. This is not a function call unique to PowerDOS, since it is defined by 
  147. Atari as the record locking standard to be used by all networking or 
  148. multitasking operating systems. However, since this call is not part of 
  149. regular GemDOS, documentation for it is not readily available. It is 
  150. documented here for the convienience of PowerDOS developers or just the 
  151. curious.
  152.  
  153. Word 1 contains the file handle.
  154.  
  155. Word 2 contains a code indicating lock/unlock:
  156.  
  157.        0 = Create a lock of (length) bytes, beginning at (start).
  158.        1 = Remove lock that was previously set. Parameters
  159.            Length and Start MUST match a previous lock call.
  160.  
  161. Long 1 is offset from start of file where the lock will begin.
  162.  
  163. Long 2 is the length of the locked area. Once a lock is set, only
  164.        the handle that owns the lock may read or write that area of the
  165.        file. When a handle is closed, any locks left on the file by the
  166.        handle will automatically be removed. Any handle may have any 
  167.        number of non-overlapping locks on a file. PowerDOS can handle 
  168.        up to 65535 total locks on all open files.
  169.  
  170. Return Parameter:
  171.  
  172. Register D0.L : Contains 0 if the operation was successful (the
  173.                 lock was created or removed, depending on mode),
  174.                 non-zero if an error occurs.
  175.  
  176. New error codes are defined to handle possible error conditions:
  177.  
  178. -58 : Record is locked. This error is returned if the area of the 
  179.       file where a new lock is to be created already has a lock on 
  180.       it, or overlapping it. This error will also be returned during 
  181.       f_read or f_write calls to areas of the file containing locks 
  182.       from other handles.
  183.  
  184. -59 : Matching lock not found for unlock operation. This error 
  185.       will be returned during a lock removal operation if a lock 
  186.       with the proper start/length belonging to the handle was 
  187.       not found as part of the files previously set locks.
  188.  
  189. In assembly language:
  190.  
  191.      move.l  length,-(sp)
  192.      move.l  start,-(sp)
  193.      move.w  mode,-(sp)
  194.      move.w  handle,-(sp)
  195.      move.w  #$5c,-(sp)
  196.      trap    #1
  197.      lea     14(sp),sp     
  198.  
  199. +--------------------------------------------------------------------------+
  200.  
  201. 7.2 80: Get or set Group.User ID of a process
  202.  
  203. long Puserid(process_id,flag,new_group_user)
  204. word process_id;
  205. word flag;
  206. long new_group_user;
  207. }
  208. {
  209.  
  210.      +-------------------------------------+ Low memory (parameter
  211.      |         Function Code  0x80         | Word        block addr)
  212.      +-------------------------------------+
  213.      |             Process ID              | Word 1
  214.      +-------------------------------------+
  215.      |            Get/set flag             | Word 2
  216.      +-------------------------------------+
  217.      |        New group.user ID if         |
  218.      +                                     + Long
  219.      |         flag is <>0 (set)           |
  220.      +-------------------------------------+ High memory
  221.  
  222. Note: Only a super user (group.user ID *.0-31) may set a processes 
  223. group.user ID. All others may only read group.user ID's.
  224.  
  225. Word 1 is ID of process from which to set/get the group.user ID. Zero 
  226.        represents the calling process.
  227.  
  228. Word 2 Get/set flag. Zero means get, else is a set.
  229.  
  230. Long   New group.user ID if flag <> 0. Upper word of long is group ID 
  231.        lower word is user ID.
  232.  
  233. Return Parameter:
  234.  
  235. Register D0.L : Contains the group.user ID if a get, or the new 
  236.                 group.user if a set. Could also possibly be one of 
  237.                 three errors:
  238.  
  239. -62 : Permission violation. Process tried to do a set but was not a 
  240.       super user. 
  241.  
  242. -70 : Unknown process. Process ID is for a process that has never 
  243.       existed (no process descriptor has been created for that PID).
  244.  
  245. -71 : Dead process. The process ID was for a process that has 
  246.       terminated.
  247.  
  248. Note: since the group.user ID can be any number, it is possible to 
  249. mistake a legitimate group.user ID for an error code. The solution to 
  250. this is to not allow a group ID to be > 32767.
  251.  
  252. In assembly language:
  253.  
  254.      move.l  new_group_user,-(sp)
  255.      move.w  flag,-(sp)
  256.      move.w  process_id,-(sp)
  257.      move.w  #$80,-(sp)
  258.      trap    #1
  259.      lea     10(sp),sp
  260.  
  261. +--------------------------------------------------------------------------+
  262.  
  263. 7.3 81: Set or get the priority of given process
  264.  
  265. long Ppriority(process_id,new_priority)
  266. word process_id;
  267. word new_priority;
  268. {
  269. }
  270.  
  271.      +-------------------------------------+ Low memory (parameter
  272.      |         Function Code  0x81         | Word        block addr)
  273.      +-------------------------------------+
  274.      |             Process ID              | Word 1
  275.      +-------------------------------------+
  276.      |  New process priority, or read flag | Word 2
  277.      +-------------------------------------+ High memory
  278.  
  279. Note: you may change process priorities only of processes with the same
  280. group.user id (your processes) or if you are a superuser.
  281.  
  282. Word 1 Process ID from which priority is to be read or changed. If this 
  283.        value is a zero, then the priority to be read/changed is of the
  284.        calling process.
  285.  
  286. Word 2 If zero, is a read (zero is not a valid process priority), else 
  287.        is the new priority for the process.
  288.  
  289. Return Parameter:
  290.  
  291. Register D0.L : If D0.l is positive (no error), then the lower word
  292.                 is the current priority of the given process. If D0.l
  293.                 is negative, represents an error:
  294.  
  295. -62 : Permission violation. Process tried to do a set priority but was
  296.       not a super user or owner. 
  297.  
  298. -70 : Unknown process. Process ID is for a process that has never 
  299.       existed (no process descriptor has been created for that PID).
  300.  
  301. -71 : Dead process. The process ID was for a process that has 
  302.       terminated.
  303.  
  304. In assembly language:
  305.  
  306.      move.w  new_priority,-(sp)
  307.      move.w  process_id,-(sp)
  308.      move.w  #$81,-(sp)
  309.      trap    #1
  310.      addq.l  #6,sp
  311.  
  312. +--------------------------------------------------------------------------+
  313.  
  314. 7.4 82: Get current process' process ID
  315.  
  316. word Pgetpid()
  317. {
  318. }
  319.  
  320.      +-------------------------------------+ Low memory (parameter
  321.      |         Function Code  0x82         | Word        block addr)
  322.      +-------------------------------------+ High memory
  323.  
  324. Return parameter:
  325.  
  326. Register D0.W : Process ID of calling process. This call never fails. 
  327.  
  328. In assembly language:
  329.  
  330.      move.w  #$82,-(sp)
  331.      trap    #1
  332.      addq.l  #2,sp
  333.  
  334. +--------------------------------------------------------------------------+
  335.  
  336. 7.5 83: Get current process' parent's process ID
  337.  
  338. long Pgetppid()
  339. {
  340. }
  341.  
  342.      +-------------------------------------+ Low memory (parameter
  343.      |         Function Code  0x83         | Word        block addr)
  344.      +-------------------------------------+ High memory
  345.  
  346. Return parameter:
  347.  
  348. Register D0.L : If D0.L is not negative, the lower word of D0 is 
  349.                 process ID of parent of calling process. If D0.L is 
  350.                 negative, then possible error is:
  351.  
  352. -87 : Orphaned process. The parent of the caller no longer exists.
  353.  
  354. In assembly language:
  355.  
  356.      move.w  #$83,-(sp)
  357.      trap    #1
  358.      addq.l  #2,sp
  359.  
  360. +--------------------------------------------------------------------------+
  361.  
  362. 7.6 84: Return pointer to process descriptor of given process
  363.  
  364. void *Pgetpd(process_id)
  365. word process_id;
  366. {
  367. }
  368.      +-------------------------------------+ Low memory (parameter
  369.      |         Function Code  0x84         | Word        block addr)
  370.      +-------------------------------------+
  371.      |             Process ID              | Word
  372.      +-------------------------------------+ High memory
  373.  
  374. Note: Only a super user process may directly examine or modify the 
  375. contents of a process descriptor.
  376.  
  377. Word   ID of process whose process descriptor is being sought. If zero, 
  378.        process descriptor of current process is returned.
  379.  
  380. Return Parameter:
  381.  
  382. Register D0.L : Pointer to the process descriptor of the given process 
  383.                 ID, or possible error codes (if negative): 
  384.  
  385. -62 : Permission violation. Non super user process may not gain access 
  386.       to the process descriptor of any process.
  387.  
  388. -70 : Unknown process. Process ID is for a process that has never 
  389.       existed (no process descriptor has been created for that PID).
  390.  
  391. -71 : Dead process. The process ID was for a process that has 
  392.       terminated.
  393.  
  394. In assembly language:
  395.  
  396.      move.w  process_id,-(sp)
  397.      move.w  #$84,-(sp)
  398.      trap    #1
  399.      addq.l  #4,sp
  400.  
  401. +--------------------------------------------------------------------------+
  402.  
  403. 7.7 85: Find the process ID of a process with the given name
  404.  
  405. long Pfindpid(process_name)
  406. char *process_name;
  407. {
  408. }
  409.  
  410.      +-------------------------------------+ Low memory (parameter
  411.      |         Function Code  0x85         | Word        block addr)
  412.      +-------------------------------------+
  413.      |                                     |
  414.      +       Pointer to process name       + Long
  415.      |                                     |
  416.      +-------------------------------------+ High memory
  417.  
  418. Long   Pointer to name of process whose process ID is to be returned. 
  419.        Name is a zero terminated ASCII string. Call is case 
  420.        independent. If a process was created from a disk file, then its 
  421.        name will be that of the disk file (i.e. WWRITER2.PRG). If this 
  422.        is the case, the extension is not required for a match; The 
  423.        string "wwriter2",0 will match the above example.
  424.  
  425. Return Parameter:
  426.  
  427. Register D0.L : If D0.L is not negative, then lower word is process ID 
  428.                 of process with matching name.
  429.  
  430. Possible error:
  431.  
  432. -75 : Process with given name not found.
  433.  
  434. In assembly language:
  435.  
  436.      pea     process_name
  437.      move.w  #$85,-(sp)
  438.      trap    #1
  439.      addq.l  #6,sp
  440.  
  441. +--------------------------------------------------------------------------+
  442.  
  443. 7.8 86: Return information about process
  444.  
  445. typedef struct {
  446.    int pi_pid;                /* Process ID                               */
  447.    int pi_ppid;               /* Parents process ID                       */
  448.    int pi_sibling;            /* First sibling's process ID (0=none)      */
  449.    int pi_child;              /* First child's process ID   (0=none)      */
  450.    unsigned long pi_gu;       /* Group.user ID                            */
  451.    unsigned int pi_priority;  /* Process priority                         */
  452.    unsigned int pi_age;       /* Process current age if in r-t-r queue    */
  453.    unsigned char pi_status;   /* Various status bits                      */
  454.    unsigned char pi_queueID;  /* Queue process resides in                 */
  455.    struct _psp *pi_basepage;  /* Pointer to process basepage              */
  456.    long pi_max_mem;           /* Max memory returned for Malloc(-1)       */
  457.    int pi_ucall;              /* Last user state function call            */
  458.    int pi_scall;              /* Last system state function call          */
  459.    unsigned long pi_ucpu;     /* Number of user state milliseconds used   */ 
  460.    unsigned long pi_scpu;     /* Number of system state milliseconds used */
  461.    unsigned long pi_sleep;    /* Number of milliseconds left if sleeping  */
  462.    unsigned long pi_datetime; /* Date/time process started (XBIOS format) */
  463.    unsigned long pi_fcalls;   /* Number of function calls executed        */
  464.    unsigned long pi_iocalls;  /* Number of i/o calls executed             */
  465.    unsigned long pi_rbytes;   /* Total bytes read from input calls        */
  466.    unsigned long pi_wbytes;   /* Total bytes written from output calls    */
  467.    void *pi_vector;           /* User defined vector                      */
  468.    struct dta *pi_dta;        /* Disk transfer address                    */
  469.    char pi_name[14];          /* Process name (zero terminated ASCII)     */
  470.    char pi_devname[8];        /* Current device name (A:, B:, C: etc)     */
  471.    long pi_totmem;            /* Total memory used by process             */
  472.    void *pi_stack;            /* Current supervisor stack top             */
  473. } PROCINFO;
  474.  
  475. long Pprocinf(process_id,buffer)
  476. word process_id;
  477. struct PROCINFO *buffer;
  478. {
  479. }
  480.  
  481.      +-------------------------------------+ Low memory (parameter
  482.      |         Function Code  0x86         | Word        block addr)
  483.      +-------------------------------------+
  484.      |             Process ID              | Word
  485.      +-------------------------------------+
  486.      |     Pointer to buffer which will    |
  487.      +                                     + Long 
  488.      |     receive process information     |
  489.      +-------------------------------------+ High memory
  490.  
  491. Word   ID of process whose information is being read. If zero, the 
  492.        information is for the calling process.
  493.  
  494. Long   Pointer to a buffer into which the information will be 
  495.        copied. The buffer must be sizeof(PROCINFO) bytes in length.
  496.  
  497. Register D0.L : Zero if call was successful, else error:
  498.  
  499. -70 : Unknown process. Process ID is for a process that has never 
  500.       existed (no process descriptor has been created for that PID).
  501.  
  502. -71 : Dead process. The process ID was for a process that has 
  503.       terminated.
  504.  
  505. In assembly language:
  506.  
  507.      pea     buffer
  508.      move.w  process_id,-(sp)
  509.      move.w  #$86,-(sp)
  510.      trap    #1
  511.      addq.l  #8,sp
  512.  
  513. +--------------------------------------------------------------------------+
  514. 87: Change process priority using a delta
  515.  
  516. long Pnice(process_id,delta)
  517. word process_id;
  518. word delta;
  519. {
  520. }
  521.  
  522.      +-------------------------------------+ Low memory (parameter
  523.      |         Function Code  0x87         | Word        block addr)
  524.      +-------------------------------------+
  525.      |             Process ID              | Word 1
  526.      +-------------------------------------+
  527.      |              Delta                  | Word 2
  528.      +-------------------------------------+ High memory
  529.  
  530. Word 1 Process ID from which priority is to be read or changed. If this 
  531.        value is a zero, then the priority to be read/changed is of the
  532.        calling process.
  533.  
  534. Word 2 A delta (+/-) from the current process ID. If this value is zero, 
  535.        no change is made; just returns the current priority.
  536.  
  537. Return Parameter:
  538.  
  539. Register D0.L : If D0.l is positive (no error), then the lower word
  540.                 is the current priority of the given process. If D0.l
  541.                 is negative, represents an error:
  542.  
  543. -62 : Permission violation. Process tried to change the priority but was
  544.       not a super user or owner. 
  545.  
  546. -70 : Unknown process. Process ID is for a process that has never 
  547.       existed (no process descriptor has been created for that PID).
  548.  
  549. -71 : Dead process. The process ID was for a process that has 
  550.       terminated.
  551.  
  552. In assembly language:
  553.  
  554.      move.w  delta,-(sp)
  555.      move.w  process_id,-(sp)
  556.      move.w  #$87,-(sp)
  557.      trap    #1
  558.      addq.l  #6,sp
  559.  
  560. +--------------------------------------------------------------------------+
  561.  
  562. 7.9 88: Allocate a block of system memory (top down)
  563.  
  564. char *Smalloc(mem_size)
  565. long mem_size;
  566. {
  567. }
  568.  
  569.      +-------------------------------------+ Low memory (parameter
  570.      |         Function Code  0x88         | Word        block addr)
  571.      +-------------------------------------+
  572.      |                                     |
  573.      +      Size of memory to allocate     + Long
  574.      |                                     |
  575.      +-------------------------------------+ High memory
  576.  
  577. This call uses a top down memory allocation technique. Also, the block 
  578. allocated is NOT owned by the calling process, but belongs to the 
  579. operating system. This call is normally used to extend structures used
  580. by the operating system.
  581.  
  582. Long   Size of memory to allocate, or -1 to return size of largest 
  583.        single memory fragment.
  584.  
  585. Return parameter
  586.  
  587. Register D0.L : If input parameter is -1, then is the size of the 
  588.                 largest block, or zero if no memory is available for 
  589.                 allocation. Else is the start of a memory block of 
  590.                 length mem_size, or zero if no block of sufficient size 
  591.                 is avaiable.
  592.  
  593. In assembly language:
  594.  
  595.      move.l  mem_size,-(sp)
  596.      move.w  #$88,-(sp)
  597.      trap    #1
  598.      addq.l  #6,sp
  599.  
  600. +--------------------------------------------------------------------------+
  601.  
  602. 7.10 89: Assign a block of memory owned by calling process to process 
  603.          of given process ID
  604.  
  605. long Massign(process_id,mem_start)
  606. word process_id;
  607. char *mem_start;
  608. {
  609. }
  610.  
  611.      +-------------------------------------+ Low memory (parameter
  612.      |         Function Code  0x89         | Word        block addr)
  613.      +-------------------------------------+
  614.      |  ID of process to assign memory to  | Word
  615.      +-------------------------------------+
  616.      |                                     |
  617.      +  Start address of memory to assign  + Long
  618.      |                                     |
  619.      +-------------------------------------+ High memory
  620.  
  621. This call is used to assign a block of memory owned by the calling 
  622. process to another process. The memory block to assign MUST be owned by 
  623. the caller (it can not have been allocated with Smalloc). Also, the 
  624. process to assign the memory to must exist and not be the same as the 
  625. caller. This call is used primarily by the Pexec routines to assign 
  626. memory allocated by the parent process during the Pexec call, to the 
  627. new process once it has been created.
  628.  
  629. Word   Process ID of process to assign memory to.
  630.  
  631. Long   Pointer to start of the memory block.
  632.  
  633. Return parameter
  634.  
  635. Register D0.L : Zero if no error (block was assigned properly), else 
  636.                 one of following errors:
  637.  
  638. -40 : Invalid memory block address. The calling process did not own the 
  639.       memory it was trying to assign, or was not the start of a memory 
  640.       block. Also caused by the calling process trying to assign its 
  641.       base memory block (where its basepage is located) to another 
  642.       process, which is illegal.
  643.  
  644. -70 : Unknown process. Process ID is for a process that has never 
  645.       existed (no process descriptor has been created for that PID).
  646.  
  647. -71 : Dead process. The process ID was for a process that has 
  648.       terminated.
  649.  
  650. In assembly language:
  651.  
  652.      pea     mem_start
  653.      move.w  process_id,-(sp)
  654.      move.w  #$89,-(sp)
  655.      trap    #1
  656.      addq.l  #8,sp
  657.  
  658. +--------------------------------------------------------------------------+
  659.  
  660. 7.11 8B: Perform various status operations on an open file
  661.  
  662. long Fstatus(handle,sub_function, ... )
  663. word handle;
  664. word sub_function;
  665. {
  666. }
  667.  
  668.      +-------------------------------------+ Low memory (parameter
  669.      |         Function Code  0x8b         | Word        block addr)
  670.      +-------------------------------------+
  671.      |             File handle             | Word 1
  672.      +-------------------------------------+
  673.      |        Status function code         | Word 2
  674.      +-------------------------------------+ High memory
  675.      |        optional parameters          |
  676.      +.....................................+
  677.  
  678.  
  679. This call is primarily used to test for input or output available on an 
  680. open file, though it performs several other functions as well.
  681.  
  682. Word 1 Handle of an open file from which status information is being 
  683.        sought.
  684.  
  685. Word 2 Status function to perform.
  686.  
  687. Sub function codes:
  688.  
  689. #define st_input   0           /* Test for input data available               */
  690. #define st_output  1           /* Test for device output ready                */
  691. #define st_size    2           /* Get size of file                            */
  692. #define st_pos     3           /* Get r/w pointer position                    */
  693. #define st_eof     4           /* Test for end of file                        */
  694. #define st_rlock   5           /* Change record lock attributes               */
  695. /* Takes extra parameters; ?????                                              */
  696. #define st_extfile 6           /* Extend the files length                     */
  697. /* Takes extra parameter; length to add to file                               */
  698. #define st_readopt 7           /* Read options section of path desc           */
  699. /* Takes extra parameter; pointer to buffer to read parameters into           */
  700. #define st_wrtopt  8           /* Write options section of path desc          */
  701. /* Takes extra parameter; pointer to buffer to write parameters from          */
  702. #define st_name    9           /* Copy name of open file to buffer            */
  703. /* Takes extra parameter; pointer to buffer to read name into                 */
  704. #define st_type   10           /* Return the file manager type for the file   */
  705.  
  706. Return parameter
  707.  
  708. Register D0.L : The return from the call is dependent on the sub-
  709.                 function desired. Also may return the following errors:
  710.  
  711. -32 : Invalid function number. In this case, the sub-function number 
  712.       was not legal.
  713.  
  714. -37 : Invalid handle. The handle was not for a currently open file.
  715.  
  716. In assembly language:
  717.  
  718.      move.w  sub_function,-(sp)
  719.      move.w  handle,-(sp)
  720.      move.w  #$8b,-(sp)
  721.      trap    #1
  722.      addq.l  #6,sp
  723.  
  724. +--------------------------------------------------------------------------+
  725.  
  726. 7.12 8C: Perform Fsfirst function with index into directory structure
  727.  
  728. long Fsfirstidx(pathname,attributes,index)
  729. char *pathname;
  730. word attributes;
  731. word index;
  732. {
  733. }
  734.  
  735.      +-------------------------------------+ Low memory (parameter
  736.      |         Function Code  0x8c         | Word        block addr)
  737.      +-------------------------------------+
  738.      |                                     |
  739.      +         Pointer to pathname         + Long
  740.      |                                     |
  741.      +-------------------------------------+
  742.      |     Attributes (as in Fsfirst)      | Word 1
  743.      +-------------------------------------+
  744.      |      Index of file to start at      | Word 2   
  745.      +-------------------------------------+ High memory
  746.  
  747. The primary purpose of this call is to simplify directory searching 
  748. over a network.
  749.  
  750. Long   Pointer to null terminated pathname
  751.  
  752. Word 1 Attribute to search for (same as for Fsfirst)
  753.  
  754. Word 2 Index into directory of file to start at (0 is first file).
  755.  
  756. Return parameter
  757.  
  758. Register D0.L : Return code and errors are the same as for Fsfirst
  759.  
  760. In assembly language:
  761.  
  762.      move.w  index,-(sp)
  763.      move.w  attributes,-(sp)
  764.      pea     pathname
  765.      move    #$8c,-(sp)
  766.      trap    #1
  767.      lea     10(sp),sp
  768.  
  769. +--------------------------------------------------------------------------+
  770.  
  771. 8D: Wake parent process of current process
  772.  
  773. long Wake_parent( code )
  774. int code;
  775. {
  776. }
  777.  
  778.      +-------------------------------------+ Low memory (parameter
  779.      |         Function Code  0x8D         | Word        block addr)
  780.      +-------------------------------------+
  781.      |               Code                  | Word
  782.      +-------------------------------------+ High memory
  783.  
  784. This call is used by the process terminate routine to reactivate the
  785. parent of the teminating process. This call will only restart the
  786. parent process if it is in the Wait queue. It has no effect otherwise.
  787. May be used to reactivate parent process when child process wishes
  788. to run concurrently.
  789.  
  790. Also see description of extended Pexec modes at the beginning of this
  791. document.
  792.  
  793. Return parameter:
  794.  
  795. Register D0.L : If D0.L is zero, no error occurred. Possible error 
  796.                 is:
  797.  
  798. -87 : Orphaned process. The parent of the caller no longer exists.
  799.  
  800. In assembly language:
  801.  
  802.      move.w     #code,-(sp)
  803.      move.w  #$8D,-(sp)
  804.      trap    #1
  805.      addq.l  #4,sp
  806.  
  807. +--------------------------------------------------------------------------+
  808.  
  809. 7.13 8E: Wait for child process to terminate
  810.  
  811. long Wait()
  812. {
  813. }
  814.  
  815.      +-------------------------------------+ Low memory (parameter
  816.      |         Function Code  0x8e         | Word        block addr)
  817.      +-------------------------------------+
  818.  
  819. This allows a process to block itself while awaiting the termination of 
  820. a child process, though a signal can also be used to unblock the 
  821. process. It is used by the Pexec function when using modes 0, 4 or 6.
  822.  
  823. Return parameter
  824.  
  825. Register D0.L : The error code of the terminating child process 
  826.                 (assuming it used Pterm or Ptermres). These error codes 
  827.                 are word in length, so the upper word of D0 will be 
  828.                 zero. If upper word of D0 is not zero, then it could be 
  829.                 a signal received through the Signal call, or a possible 
  830.                 error:
  831.  
  832. -72 : Process has no children to wait for.
  833.  
  834. In assembly language:
  835.  
  836.      move.w  #$8e,-(sp)
  837.      trap    #1
  838.      addq.l  #2,sp
  839.  
  840. +--------------------------------------------------------------------------+
  841.  
  842. 7.14 8F: Sleep (block) for specified time, or indefinately
  843.  
  844. long Sleep(time)
  845. long time;
  846. {
  847. }
  848.  
  849.      +-------------------------------------+ Low memory (parameter
  850.      |         Function Code  0x8f         | Word        block addr)
  851.      +-------------------------------------+
  852.      |                                     |
  853.      +   Milliseconds or ticks to sleep    + Long
  854.      |                                     |
  855.      +-------------------------------------+ High memory
  856.  
  857. This is a general purpose CPU time management facility. It is also 
  858. called by several other PowerDOS function calls.
  859.  
  860. Long   If zero, will sleep indifinately. A positive value is the number 
  861.        of milliseconds to remain dormant. A negative value is taken as 
  862.        the number of system ticks to remain dormant. A value of -1 causes
  863.        no sleep, but will cause a task switch if there is a process in
  864.        the ready-to-run queue with the same or higher priority.
  865.  
  866. Return parameter
  867.  
  868. Register D0.L : The number of ticks left to sleep (if it was a timed 
  869.                 sleep and a signal caused a premature activation).
  870.  
  871. In assembly language:
  872.  
  873.      move.l  time,-(sp)
  874.      move.w  #$8f,-(sp)
  875.      trap    #1
  876.      addq.l  #6,sp
  877.  
  878. +--------------------------------------------------------------------------+
  879.  
  880. 7.15 90: Link to queue of processes waiting for access to I/O
  881.  
  882. long Ioqueue(process_id,time)
  883. word process_id;
  884. long time;
  885. {
  886. }
  887.  
  888.      +-------------------------------------+ Low memory (parameter
  889.      |         Function Code  0x90         | Word        block addr)
  890.      +-------------------------------------+
  891.      |      ID of process to link to       | Word
  892.      +-------------------------------------+
  893.      |                                     |
  894.      +   Milliseconds or ticks to sleep    + Long
  895.      |                                     |
  896.      +-------------------------------------+ High memory
  897.  
  898. This call is used to block while awaiting access to I/O which is 
  899. currently controlled by process_id.
  900.  
  901. Word   ID of process to link to
  902.  
  903. Long   Time to sleep (passed to the Sleep function call)
  904.  
  905. Return parameter
  906.  
  907. Register D0.L : Return parameter from Sleep function call, or possible 
  908.                 errors:
  909.  
  910. -76 : The process is trying to link to a process that is already linked 
  911.       to it. This should never happen, but a check is made for it to 
  912.       stop I/O deadlock from occurring.
  913.  
  914. -70 : Unknown process. Process ID is for a process that has never 
  915.       existed (no process descriptor has been created for that PID).
  916.  
  917. -71 : Dead process. The process ID was for a process that has 
  918.       terminated.
  919.  
  920. In assembly language:
  921.  
  922.      move.l  time,-(sp)
  923.      move.w  process_id,-(sp)
  924.      move.w  #$90,-(sp)
  925.      trap    #1
  926.      addq.l  #8,sp
  927.  
  928. +--------------------------------------------------------------------------+
  929.  
  930. 7.16 91: Wait (block) until a specified date/time
  931.  
  932. long Wait_dt(date_time)
  933. unsigned long date_time;
  934. {
  935. }
  936.  
  937.      +-------------------------------------+ Low memory (parameter
  938.      |         Function Code  0x91         | Word        block addr)
  939.      +-------------------------------------+
  940.      |    Date/time (in XBIOS format) to   |
  941.      +                                     + Long
  942.      |        reactivate process at        |
  943.      +-------------------------------------+ High memory
  944.  
  945. Long   Date and time (in Xbios settime/gettime format) when process is 
  946.        to be reactivated. If the date word is zero, then only the time 
  947.        becomes significant (the date becomes a wildcard). Seconds are 
  948.        not counted; the call will only return on the even minute. If a 
  949.        date is used, but has already occurred, an immediate return 
  950.        results (otherwise the process would never unblock).
  951.  
  952. Return parameter
  953.  
  954. Register D0.L : Always returns zero
  955.  
  956. In assembly language:
  957.  
  958.      move.l  date_time,-(sp)
  959.      move.w  #$91,-(sp)
  960.      trap    #1
  961.      addq.l  #6,sp
  962.  
  963. +--------------------------------------------------------------------------+
  964.  
  965. 7.17 92: Create a new I/O device
  966.  
  967. long Dev_create(dev_name,fm_name,drv_name,path_vars,dev_vars,share)
  968. char *dev_name;
  969. char *fm_name;
  970. char *drv_name;
  971. char *path_vars;
  972. char *dev_vars;
  973. word share;
  974. {
  975. }
  976.  
  977.      +-------------------------------------+ Low memory (parameter
  978.      |         Function Code  0x92         | Word        block addr)
  979.      +-------------------------------------+
  980.      |                                     |
  981.      +  Pointer to name device will have   + Long 1
  982.      |                                     |
  983.      +-------------------------------------+
  984.      |                                     |
  985.      +   Pointer to name of file manager   + Long 2
  986.      |                                     |
  987.      +-------------------------------------+
  988.      |                                     |
  989.      +  Pointer to name of device driver   + Long 3
  990.      |                                     |
  991.      +-------------------------------------+
  992.      |                                     |
  993.      +    Pointer to new path init vars    + Long 4
  994.      |                                     |
  995.      +-------------------------------------+
  996.      |                                     |
  997.      +    Pointer to initial device vars   + Long 5
  998.      |                                     |
  999.      +-------------------------------------+
  1000.      |          Device share flag          | Word
  1001.      +-------------------------------------+ High memory
  1002.  
  1003. This function is used to create (add) a new device to PowerDOS.
  1004. For more information on this call, contact the PowerDOS authors.
  1005.  
  1006. Long 1 Pointer to name the new device will have. Must be seven 
  1007.        characters or less in length, and must be uppercase. String is 
  1008.        null terminated.
  1009.  
  1010. Long 2 Pointer to name of file manager for the device.
  1011.  
  1012. Long 3 Pointer to name of device driver for the device.
  1013.  
  1014. Long 4 Pointer to new path initialization vars. First word is number of 
  1015.        bytes to copy. Must be 40 or less.
  1016.  
  1017. Long 5 Pointer to device initialization vars. First word is number of 
  1018.        bytes to copy. Must be 40 or less.
  1019.  
  1020. Word   Device share flag. If zero, device is shareable.
  1021.  
  1022. Return parameter
  1023.  
  1024. Register D0.L : Zero on success, else possible error codes:
  1025.  
  1026. -73 : I/O device table is full. No more devices may be added to the 
  1027.       system.
  1028.  
  1029. -74 : File manager or device driver was not found.
  1030.  
  1031. In assembly language:
  1032.  
  1033.      move.w  share-(sp)
  1034.      pea     dev_vars
  1035.      pea     path_vars
  1036.      pea     drv_name
  1037.      pea     fm_name
  1038.      pea     dev_name
  1039.      move.w  #$92,-(sp)
  1040.      trap    #1
  1041.      lea     24(sp),sp
  1042.  
  1043. +--------------------------------------------------------------------------+
  1044.  
  1045. 7.18 93: Add a new file manager to the system
  1046.  
  1047. long Fm_add(fm_name,subroutine_tab,fm_vars,fm_type)
  1048. char *fm_name;
  1049. char *subroutine_tab;
  1050. char *fm_vars;
  1051. word fm_type;
  1052. {
  1053. }
  1054.  
  1055.      +-------------------------------------+ Low memory (parameter
  1056.      |         Function Code  0x93         | Word        block addr)
  1057.      +-------------------------------------+
  1058.      |                                     |
  1059.      +     Pointer to file manager name    + Long 1
  1060.      |                                     |
  1061.      +-------------------------------------+
  1062.      |                                     |
  1063.      +  Pointer to subroutine index table  + Long 2
  1064.      |                                     |
  1065.      +-------------------------------------+
  1066.      |                                     |
  1067.      + Pointer to file manager's variables + Long 3
  1068.      |                                     |
  1069.      +-------------------------------------+
  1070.      |         File manager type           | Word
  1071.      +-------------------------------------+ High memory
  1072.  
  1073. This function is used to add a new file manager to PowerDOS. For 
  1074. more information, panic and pick up the phone.
  1075.  
  1076. Long 1 Name by which the file manager will be known to the system. Must 
  1077.        be in uppercase, 7 characters max, null terminated.
  1078.  
  1079. Long 2 Pointer to subroutine index table. Each value in the table is a 
  1080.        signed int that is taken as an offset from the start of the 
  1081.        table to the service function (a relative offset).
  1082.  
  1083. Long 3 Pointer to any global variables that the file manager may 
  1084.        require. This value has no meaning to the kernal. It is simply 
  1085.        loaded into register a6 before calling the file manager service 
  1086.        routines.
  1087.  
  1088. Word   File manager type code. Currently defined values are:
  1089.        0 - Disk File Manager, FAT based storage allocation
  1090.        1 - Pipe file manager
  1091.        2 - Sequencial character file manager (CON:, AUX: PRN:, etc.)
  1092.        3 - Network File Manager (PowerNET)
  1093.        4 - Null file manager (sends data nowhere)
  1094.  
  1095. Return parameter
  1096.  
  1097. Register D0.L : Zero on success, else possible error code:
  1098.  
  1099. -73 : File manager table is full. No more file managers may be added
  1100.       to the system.
  1101.  
  1102. In assembly language:
  1103.  
  1104.      move.w  fm_type,-(sp)
  1105.      pea     fm_vars
  1106.      pea     subroutine_tab
  1107.      pea     fm_name
  1108.      move.w  #$93,-(sp)
  1109.      trap    #1
  1110.      lea     16(sp),sp
  1111.  
  1112. +--------------------------------------------------------------------------+
  1113.  
  1114. 7.19 94: Add a new device driver to the system, or replace an old one
  1115.  
  1116. long Drv_add(drv_name,subroutine_tab,drv_vars)
  1117. char *drv_name;
  1118. char *subroutine_tab;
  1119. char *drv_vars;
  1120. {
  1121. }
  1122.  
  1123. dev_dd_add      macro
  1124.      +-------------------------------------+ Low memory (parameter
  1125.      |         Function Code  0x94         | Word        block addr)
  1126.      +-------------------------------------+
  1127.      |                                     |
  1128.      +    Pointer to device driver name    + Long 1
  1129.      |                                     |
  1130.      +-------------------------------------+
  1131.      |                                     |
  1132.      +  Pointer to subroutine index table  + Long 2
  1133.      |                                     |
  1134.      +-------------------------------------+
  1135.      |                                     |
  1136.      +    Pointer to driver's variables    + Long 3
  1137.      |                                     |
  1138.      +-------------------------------------+ High memory
  1139.  
  1140. This function is used to add a new device driver to PowerDOS, or to 
  1141. replace an existing one. The PowerDOS kernal does not use device 
  1142. drivers directly; it merely notes their existance and allows them to be 
  1143. logically tied to a file manager when a device is created with the 
  1144. Dev_create call. For more information, call, but not collect.
  1145.  
  1146. Long 1 Name by which the driver will be known to the system. Must 
  1147.        be in uppercase, 7 characters max, null terminated.
  1148.  
  1149. Long 2 Pointer to subroutine index table. Each value in the table is a 
  1150.        signed int that is taken as an offset from the start of the 
  1151.        table to the service function (a relative offset). The meaning 
  1152.        of the entries in this table are dependant upon the file manager 
  1153.        for which the driver is designed to service.
  1154.  
  1155. Long 3 Pointer to any global variables that the device driver may 
  1156.        require. This value has no meaning to the file manager. It is 
  1157.        simply loaded into register a6 before calling the driver's 
  1158.        service routines.
  1159.  
  1160. Return parameter
  1161.  
  1162. Register D0.L : Zero on success, else possible error code:
  1163.  
  1164. -73 : Device driver table is full. No more drivers may be added
  1165.       to the system.
  1166.  
  1167. In assembly language:
  1168.      pea     drv_vars
  1169.      pea     subroutine_tab
  1170.      pea     drv_name
  1171.      move.w  #$94,-(sp)
  1172.      trap    #1
  1173.      lea     14(sp),sp
  1174.  
  1175. +--------------------------------------------------------------------------+
  1176.  
  1177. 7.20 95: Return device info for requested device index 
  1178.  
  1179. long Devinfo(idx,buffer)
  1180. word idx;
  1181. struct dev_info *buffer;
  1182. {
  1183. }
  1184.      +-------------------------------------+ Low memory (parameter
  1185.      |         Function Code  0x95         | Word        block addr)
  1186.      +-------------------------------------+
  1187.      |    Index of device name to read     | Word
  1188.      +-------------------------------------+
  1189.      |                                     |
  1190.      +  Pointer to buffer to receive info  + Long
  1191.      |                                     |
  1192.      +-------------------------------------+ High memory
  1193.  
  1194. This function returns three pieces of information about a device whose 
  1195. device index number is provided. The information is placed into the 
  1196. following structure:
  1197.  
  1198. struct dev_info {
  1199.      char dev_name[8];  /* 7 char max device name, null terminated */
  1200.      int fm_type;       /* File manager type code                  */
  1201.      int share_flag;
  1202. };
  1203.  
  1204. Word   Index of device for which information is to be returned. Index 
  1205.        numbers start with zero.
  1206.  
  1207. Long   Pointer to structure which will be filled in with information.
  1208.  
  1209. Return parameter
  1210.  
  1211. Register D0.L : Zero if no error, else possible error codes:
  1212.  
  1213. -85 : No device exists for this device number. The only cause for 
  1214.       this error is that a logical disk device was created at this 
  1215.       index number, but no physical device exists, therefore the device 
  1216.       is invalid.
  1217.  
  1218. -86 : No device exists for this or higher device index numbers, i.e. no 
  1219.       more devices exist.
  1220.  
  1221. In assembly language:
  1222.  
  1223.      pea     buffer
  1224.      move.w  idx,-(sp)
  1225.      move.w  #$95,-(sp)
  1226.      trap    #1
  1227.      addq.l  #8,sp
  1228.  
  1229. +--------------------------------------------------------------------------+
  1230.  
  1231. 7.21 96: Send a signal to a process
  1232.  
  1233. long Send(process_id,signal_code)
  1234. word process_id;
  1235. long signal_code;
  1236. {
  1237. }
  1238.  
  1239.      +-------------------------------------+ Low memory (parameter
  1240.      |         Function Code  0x96         | Word        block addr)
  1241.      +-------------------------------------+
  1242.      |   ID of process to send signal to   | Word
  1243.      +-------------------------------------+
  1244.      |                                     |
  1245.      +     Signal to send to process       + Long
  1246.      |                                     |
  1247.      +-------------------------------------+ High memory
  1248.  
  1249. The Send function sends a signal to a specified process, and is similar 
  1250. to the F$Send function call of OS-9. It can be used as a general 
  1251. purpose interprocess communication facility, providing the information 
  1252. to be exchanged can be represented in 32 bits or less. Also, there are 
  1253. three predefined and reserved values that are interpreted by the Send 
  1254. function itself. Currently, this call is used extensively by the
  1255. kernal and file managers to unblock processes that were blocked for
  1256. I/O. It is not as usefull as the Unix style signals, other than
  1257. passing a longword between processes. At some future date, a Unix like
  1258. signalling facility will probably be added to PowerDOS. 
  1259.   
  1260. Word   Process ID of the process to send the signal to. A process can 
  1261.        send a signal to itself.
  1262.  
  1263. Long   The signal being sent. Three possible values are predefined:
  1264.        0 - Kill
  1265.        1 - Wake
  1266.        2 - Keyboard abort
  1267.  
  1268.        All other codes are user defined. If there is no signal intercept
  1269.        routine installed, an error will be returned, although the
  1270.        receiving process will be unblocked if it was blocked.
  1271.  
  1272. Return parameter
  1273.  
  1274. Register D0.L : Zero if no error, else possible error codes:
  1275.  
  1276. -70 : Unknown process. Process ID is for a process that has never 
  1277.       existed (no process descriptor has been created for that PID).
  1278.  
  1279. -71 : Dead process. The process ID was for a process that has 
  1280.       terminated.
  1281.  
  1282. -88 : Process has no signal intercept routine installed. Signal cannot 
  1283.       be read by intended process.
  1284.  
  1285. In assembly language:
  1286.  
  1287.      move.l  signal_code,-(sp)
  1288.      move.w  process_id,-(sp)
  1289.      move.w  #$96,-(sp)
  1290.      trap    #1  
  1291.      addq.l  #8,sp
  1292.  
  1293. +--------------------------------------------------------------------------+
  1294.  
  1295. 7.22 97: Install signal intercept routine
  1296.  
  1297. long Sig_intercept(intercept_rtn,var_ptr)
  1298. int (*intercept_rtn)(long, void *);
  1299. long *var_ptr;
  1300.  
  1301.      +-------------------------------------+ Low memory (parameter
  1302.      |         Function Code  0x97         | Word        block addr)
  1303.      +-------------------------------------+
  1304.      |                                     |
  1305.      + Address of signal intercept routine + Long 1
  1306.      |                                     |
  1307.      +-------------------------------------+
  1308.      |      Pointer to pass to signal      |
  1309.      +                                     + Long 2
  1310.      |         intercept routine           |
  1311.      +-------------------------------------+ High memory
  1312.  
  1313. This routine allows a process to install a handler for signals that it 
  1314. may receive from other processes. The handler must preserve registers
  1315. a3-a6/d3-d7. It will be executed in supervisor state, and must not
  1316. move to user state. It must not make any OS calls, just do what it
  1317. has to do to deal with the signal (like storing it for later
  1318. processing) and exit with an RTS.
  1319.  
  1320. Long 1 Address of a service routine.
  1321.  
  1322. Long 2 Pointer to any variables that the intercept routine may require.
  1323.        When the service routine is called, this pointer will be passed
  1324.        to it, along with the signal itself.
  1325.  
  1326. Return parameter
  1327.  
  1328. Register D0.L : Always zero, there is never an error
  1329.  
  1330. In assembly language:
  1331.  
  1332.      pea     var_ptr
  1333.      pea     intercept_rtn
  1334.      move.w  #$97,-(sp)
  1335.      trap    #1
  1336.      lea     10(sp),sp
  1337.  
  1338. +--------------------------------------------------------------------------+
  1339. 98: Suspend a process
  1340.  
  1341. long Suspend( process_id )
  1342. int process_id;
  1343. {
  1344. }
  1345.  
  1346.      +-------------------------------------+ Low memory (parameter
  1347.      |         Function Code  0x98         | Word        block addr)
  1348.      +-------------------------------------+
  1349.      |             Process ID              | Word
  1350.      +-------------------------------------+ High memory
  1351.  
  1352. Note: only a super user process may suspend any process. Non-superuser
  1353. processes may only suspend processes with the same group.user id. 
  1354.  
  1355. If the process to be suspended is in user state, it will be moved to
  1356. the event queue. If it is in system state, then it will be moved to the
  1357. event queue as soon as it reenters user state.
  1358.  
  1359. Word   ID of process to suspend. If zero, the calling process will
  1360.        suspend itself.
  1361.  
  1362. Return Parameter:
  1363.  
  1364. Register D0.L : If positive, then lowest byte is current queue of
  1365.                 process (if it was a process other than caller).
  1366.                 Possible error codes (if negative): 
  1367.  
  1368. -62 : Permission violation. Non super user process may not suspend a 
  1369.       process with a different group.user id.
  1370.  
  1371. -70 : Unknown process. Process ID is for a process that has never 
  1372.       existed (no process descriptor has been created for that PID).
  1373.  
  1374. -71 : Dead process. The process ID was for a process that has 
  1375.       terminated.
  1376.  
  1377. In assembly language:
  1378.  
  1379.      move.w  process_id,-(sp)
  1380.      move.w  #$98,-(sp)
  1381.      trap    #1
  1382.      addq.l  #4,sp
  1383.  
  1384. +--------------------------------------------------------------------------+
  1385.  
  1386. 7.23 99: The Message Queue
  1387.  
  1388. int Q_message(mparams)   /* Parameters are passed as a pointer to a structure */ 
  1389. struct mq_params {
  1390.    int cmd;              /* Command to execute (0-5)              */
  1391.    union {
  1392.         char *name;      /* 0 - Create, 1 - Open message queue    */
  1393.         int handle;      /* 2 - Close, 3 - Delete queue           */
  1394.         struct {
  1395.            int handle;
  1396.            struct {
  1397.               long data[4];
  1398.            } *message;
  1399.            long timeout;
  1400.         } r_w;           /* 4 - Read , 5 - Write message          */
  1401.    } cmd_blk;
  1402. } *mparams;
  1403.  
  1404.      +-------------------------------------+ Low memory (parameter
  1405.      |         Function Code  0x99         | Word        block addr)
  1406.      +-------------------------------------+
  1407.      |                                     |
  1408.      +    Pointer to parameter structure   + Long
  1409.      |                                     |
  1410.      +-------------------------------------+ High memory
  1411.  
  1412. This function provides access to the message queue. The messages passed 
  1413. are represented by four longwords. A queue may be created, opened (if 
  1414. it already exists), closed, deleted (if there are no other users), read 
  1415. from and written to.
  1416.  
  1417. Long   Pointer to a structure that contains parameters dependant upon 
  1418.        the function to perform.
  1419.  
  1420. /* To open an existing queue, or create it if it doesn't yet exist  */
  1421. int q_make(name,q_parms)
  1422. char *name;
  1423. struct mq_params *q_parms;
  1424. {
  1425.      int qh;                               /* Queue handle                */
  1426.  
  1427.      q_parms->cmd_blk.name = name;
  1428.      q_parms->cmd = 1;                     /* Try to open existing queue  */
  1429.      if(qh = Q_message(q_parms) < 0){
  1430.          q_parms->cmd = 0;                 /* If failed, try create       */
  1431.          if(qh = Q_message(q_parms) < 0)
  1432.              return(-1);
  1433.      }
  1434.      return(qh);                           /* Queue handle back to caller */ 
  1435. }
  1436.  
  1437. /* Writing a message to a queue */
  1438. int q_write(qh,q_parms,q_msg)
  1439. int qh;
  1440. struct mq_params *q_parms;
  1441. struct qmsg {
  1442.      long message[4];
  1443. } *q_msg;
  1444. {
  1445.      q_parms->cmd_blk.r_w.handle = qh;
  1446.      q_parms->cmd_blk.r_w.message = q_msg;
  1447.      q_parms->cmd = 5;
  1448.      return(Q_message(q_parms));
  1449. }
  1450.  
  1451. /* Reading from a queue */
  1452. int q_read(qh,q_parms,q_msg,timeout)
  1453. int qh;
  1454. struct mq_params *q_parms;
  1455. struct qmsg *q_msg;
  1456. long timeout;            /* Used as parameter to Sleep function */
  1457. {
  1458.      q_parms->cmd_blk.r_w.handle = qh;
  1459.      q_parms->cmd_blk.r_w.message = q_msg;
  1460.      q_parms->cmd_blk.r_w.timeout = timeout;
  1461.      q_parms->cmd = 4;
  1462.      return(Q_message(q_parms));
  1463. }
  1464.  
  1465. /* Closing and possibly deleting the queue */
  1466. int q_close(qh,q_parms)
  1467. int qh;
  1468. struct mq_params *q_parms;
  1469. {
  1470.      int rc;
  1471.  
  1472.      q_parms->cmd = 2;
  1473.      q_parms->cmd_blk.handle = qh;
  1474.      if(rc = Q_message(q_parms) == 0){   /* If we are last to close... */
  1475.          q_parms->cmd = 3;
  1476.          rc = Q_message(q_parms);        /* Then delete the queue      */
  1477.      }
  1478.      return(rc);
  1479. }  
  1480.  
  1481. Return parameter
  1482.  
  1483. Register D0.W : Dependent upon function. If no errors, will return 
  1484.                 queue handle (a positive integer) for create and open; 
  1485.                 zero for delete, read and write; count of queue users 
  1486.                 remaining for close (when close returns zero, no other 
  1487.                 users of queue). Possible errors:
  1488.  
  1489. -52 :  Bad name. Queue name passed to create or open was illegal.
  1490.  
  1491. -61 :  Timeout. No message became available for read before timeout 
  1492.        expired. Returned on read command.
  1493.  
  1494. -73 :  Table full; no room for another queue or message, and no memory 
  1495.        available to allow table expansion. Returned on create and 
  1496.        write.
  1497.   
  1498. -77 :  Queue not found. There is no queue using the name passed in 
  1499.        queue open command.
  1500.  
  1501. -78 :  Unknown queue. Handle passed in close, delete, read or write 
  1502.        does not represent a currently existing queue.
  1503.  
  1504. -79 :  Queue in use. Cannot delete queue, as it is still opened by 
  1505.        another (or same) process.
  1506.  
  1507. -80 :  Queue empty. There is no message to read. Returned from read 
  1508.        command when timeout is set to -1 (immediate exit if no message 
  1509.        available for read).
  1510.  
  1511. -81 :  Queue already exists. Name passed as a parameter to the create 
  1512.        command is in use by another queue.
  1513.  
  1514. In assembly language:
  1515.  
  1516.      pea     mparams
  1517.      move.w  #$99,-(sp)
  1518.      trap    #1
  1519.      addq.l  #6,sp
  1520.  
  1521. +--------------------------------------------------------------------------+
  1522.  
  1523. 7.24 9A: The Semaphore function
  1524.  
  1525. int Semaphore(sparams)   /* Parameters are passed as a pointer to a structure */ 
  1526. struct sparams {
  1527.    int cmd;              /* Command to execute (0-5)           */
  1528.    union {
  1529.         char *name;      /* Create, Open                       */
  1530.         int handle;      /* Close, Delete, Release             */
  1531.         struct {
  1532.            int handle;
  1533.            long timeout;
  1534.         } own;           /* Semaphore own                      */
  1535.    } cmd_blk;
  1536. } *sparams;
  1537.  
  1538.      +-------------------------------------+ Low memory (parameter
  1539.      |         Function Code  0x9a         | Word        block addr)
  1540.      +-------------------------------------+
  1541.      |                                     |
  1542.      +    Pointer to parameter structure   + Long
  1543.      |                                     |
  1544.      +-------------------------------------+ High memory
  1545.  
  1546. This function is exactly like the message queue, except there is no 
  1547. message involved. Issuing a release command simply increments a count, 
  1548. and issuing an own command decrements the count (a process doing an own 
  1549. will be blocked if the count is less than one, for a time specified in 
  1550. the timeout parameter).
  1551.  
  1552. Long   Pointer to a structure that contains parameters dependant upon 
  1553.        the function to perform.
  1554.  
  1555. Return parameter
  1556.  
  1557. Register D0.W : Dependent upon function. If no errors, will return 
  1558.                 semaphore handle (a positive integer) for create and 
  1559.                 open; zero for delete, own and release; count of 
  1560.                 semaphore users remaining for close (when close returns 
  1561.                 zero, no other users of semaphore). Possible errors:
  1562.  
  1563. -52 :  Bad name. Semaphore name passed to create or open was illegal.
  1564.  
  1565. -61 :  Timeout. Count never became greater than zero before timeout 
  1566.        expired. Returned on own command.
  1567.  
  1568. -73 :  Table full; no room for another semaphore, and no memory 
  1569.        available to allow table expansion. Returned on create.
  1570.   
  1571. -77 :  Semaphore not found. There is no semaphore using the name passed 
  1572.        in open command.
  1573.  
  1574. -78 :  Unknown semaphore. Handle passed in close, delete, own or 
  1575.        release does not represent a currently existing semaphore.
  1576.  
  1577. -79 :  Semaphore in use. Cannot delete semaphore, as it is still opened 
  1578.        by another (or same) process.
  1579.  
  1580. -80 :  Semaphore empty. Returned from own command when timeout is set 
  1581.        to -1 (immediate exit if count is less than one).
  1582.  
  1583. -81 :  Semaphore already exists. Name passed as a parameter to the 
  1584.        create command is in use by another semaphore.
  1585.  
  1586. In assembly language:
  1587.  
  1588.      pea     sparams
  1589.      move.w  #$9a,-(sp)
  1590.      trap    #1
  1591.      addq.l  #6,sp
  1592.  
  1593. +--------------------------------------------------------------------------+
  1594.  
  1595. 7.25 9B: Shared memory
  1596.  
  1597. int Mem_share(msparams)  /* Parameters are passed as a pointer to a structure */ 
  1598. struct msparams {
  1599.    int cmd;              /* Command to execute (0-3)           */
  1600.    union {
  1601.         struct {
  1602.            char *name;
  1603.            char *start;  /* Return: start of block             */
  1604.            long length;  /* Input for create, return for open  */
  1605.         } c_o;           /* Create, Open                       */
  1606.         int handle;      /* Close, Delete                      */
  1607.    } cmd_blk;
  1608. } *msparams;
  1609.  
  1610.      +-------------------------------------+ Low memory (parameter
  1611.      |         Function Code  0x9b         | Word        block addr)
  1612.      +-------------------------------------+
  1613.      |                                     |
  1614.      +    Pointer to parameter structure   + Long
  1615.      |                                     |
  1616.      +-------------------------------------+ High memory
  1617.  
  1618. This function provides for a named block of memory. This memory is not 
  1619. owned by any process, but by the operating system; thus if a process 
  1620. using the named memory terminates, the memory won't be freed.
  1621.  
  1622. Long   Pointer to a structure that contains parameters dependant upon 
  1623.        the function to perform.
  1624.  
  1625. Return parameter
  1626.  
  1627. Register D0.W : Dependent upon function. If no errors, will return 
  1628.                 shared memory handle (a positive integer) for create 
  1629.                 and open; zero for delete; count of users remaining 
  1630.                 for close (when close returns zero, no other users 
  1631.                 of shared mamory). Possible errors:
  1632.  
  1633. -52 :  Bad name. Shared memory name passed to create or open was 
  1634.        illegal.
  1635.  
  1636. -73 :  Table full; no room for another name, and no memory available 
  1637.        to allow table expansion (so probably no memory available for
  1638.        the actual shared memory block, either). Returned on create.
  1639.   
  1640. -77 :  Memory name not found. There is no shared memory block using 
  1641.        the name passed in open command.
  1642.  
  1643. -78 :  Unknown memory block. Handle passed in close or delete does 
  1644.        not represent a currently existing named memory block.
  1645.  
  1646. -79 :  Named memory in use. Cannot delete, as it is still opened 
  1647.        by another (or same) process.
  1648.  
  1649. -81 :  Named block already exists. Name passed as a parameter to the 
  1650.        create command is in use by another memory block.
  1651.  
  1652. In assembly language:
  1653.  
  1654.      pea     msparams
  1655.      move.w  #$9b,-(sp)
  1656.      trap    #1
  1657.      addq.l  #6,sp
  1658.  
  1659. +--------------------------------------------------------------------------+
  1660.  
  1661. 7.26 9E: Read or modify a GemDOS, BIOS or XBIOS function vector
  1662.  
  1663. long Chgvector(trap_num,vector_num,new_vector)
  1664. int trap_num;
  1665. int vector_num;
  1666. char *new_vector;
  1667. {
  1668. }
  1669.  
  1670.      +-------------------------------------+ Low memory (parameter
  1671.      |         Function Code  0x9e         | Word        block addr)
  1672.      +-------------------------------------+
  1673.      |     Trap number (1, 13 or 14)       | Word
  1674.      +-------------------------------------+
  1675.      |      Vector number to change        | Word
  1676.      +-------------------------------------+
  1677.      |                                     |
  1678.      +    New vector or read only if -1    + Long
  1679.      |                                     |
  1680.      +-------------------------------------+ High memory
  1681.  
  1682. This function allows a single function vector to be read or modified. 
  1683. For instance, the trap #1 Fopen function could be intercepted, and 
  1684. replaced by a whole new Fopen function.
  1685.  
  1686. Word   Part of operating system for which function vector is to be
  1687.        read or written, given as its trap number. Trap 1 is GemDOS,
  1688.        trap 13 is the BIOS (Basic Input/Output System), and trap 14
  1689.        is the XBIOS (eXtended Basic Input/Output System). 
  1690.  
  1691. Word   Function number of the vector to be read or written.
  1692.  
  1693. Long   New vector, or -1 to denote a read only operation. Note: because
  1694.        of the multitasking nature of PowerDOS, it is possible that
  1695.        another running task could use the new function as soon as the
  1696.        vector is modified. Therefore it is necessary to completely
  1697.        initialize the replacement routine before its vector is
  1698.        inserted into the function table. As soon as this call is made
  1699.        to modify the function table, the replacement routine should be
  1700.        able to handle requests made of it.
  1701.  
  1702. Return parameter
  1703.  
  1704. Register D0.L : If no errors (noted by a negative), will return the 
  1705.                 previous contents of the vector. Possible errors:
  1706.  
  1707. -64 :  Range error. Either an incorrect trap number was given (not
  1708.        1, 13 or 14), or the vector number was too large.
  1709.  
  1710. In assembly language:
  1711.  
  1712.      pea     new_vector
  1713.      move    #vector_num,-(sp)
  1714.      move    #trap_num,-(sp)
  1715.      move    #$9e,-(sp)
  1716.      trap    #1
  1717.      lea     10(sp),sp
  1718.  
  1719. +--------------------------------------------------------------------------+
  1720.  
  1721. 7.27 9f: Read or modify a PowerDOS internal variable
  1722.  
  1723. long Chgsysvar(var_num,flag,new_value)
  1724. int var_num;
  1725. int flag;
  1726. long new_value;
  1727. {
  1728. }
  1729.  
  1730.      +-------------------------------------+ Low memory (parameter
  1731.      |         Function Code  0x9f         | Word        block addr)
  1732.      +-------------------------------------+
  1733.      |  Number of variable to read/change  | Word
  1734.      +-------------------------------------+
  1735.      |          Read/change flag           | Word
  1736.      +-------------------------------------+
  1737.      |    New value if change flag <> 0    |
  1738.      +                                     + Long
  1739.      |   (May be only lsb or lsw of long)  |
  1740.      +-------------------------------------+ High memory
  1741.  
  1742. Some of the internal PowerDOS variables may be read; others may be read 
  1743. or written. This function call provides access to these values. In the
  1744. table below, a 'w' next to the number means it's a writeable value,
  1745. 'r' means read only.
  1746.  
  1747. 0  w = G_maxtpa    long      Max TPA size given to a new process
  1748. 1  r = G_rsvmem    long      Artificial top of ram to limit m_alloc(-1)
  1749. 2  w = G_rsvmaxbl  long      Max block size returned within topmem area
  1750. 3  w = G_max_age   word      Max age to age a process
  1751. 4  w = G_min_pty   word      Minimum ageable priority; if below, don't age
  1752. 5  r = G_timeslice word      Number of milliseconds per tick
  1753. 6  r = G_idlecnt   long      Idle CPU time. In milliseconds
  1754. 7  w = G_fastload  long      Amount of heap to clear on program startup
  1755. 8  w = G_term      long      Vector jumped through on process termination
  1756. 9  w = G_pexec     long   Vector jumped through on process creation
  1757. 10 w = G_trace     long      Vector jumped through during function call trace
  1758. 11 w = G_alias     long      Pointer to first in linked list of device aliases
  1759. 12 w = G_pathcheck long      Vector jumped through for path parse routine
  1760. 13 w = G_extservic long   Pointer to first in linked list of extended service function tables
  1761. 14 r = G_version   long   GemDOS and PowerDOS version numbers
  1762. 15 r = G_sysdate   long      Date/time of PowerDOS system build
  1763. 16 unused
  1764. 17 unused
  1765. 18 unused
  1766. 19 r = int_eos     long      Pointer to system interupt end-of-service handler
  1767.  
  1768. For G_term, G_pexec and G_trace, the vectors are initialized to 0, which
  1769. signals the kernal not to use the vector. Due to the fact that PowerDOS
  1770. uses preemptive multitasking, the only reliable way to grab one of these
  1771. vectors is to go into supervisor mode, set the IPL to 7, issue the call
  1772. to change (and return the old) vector, save the old vector (which may be
  1773. 0L) then drop back to the previous IPL. The kernal will JSR through the
  1774. vector, and each program in the vector chain should do whatever processing
  1775. it needs to do, then fall through the saved vector, UNLESS IT WAS 0L. In
  1776. the later case, it should just RTS.
  1777.  
  1778. When a G_term vector is called, registers d5-d7/a5-a6 must be preserved.
  1779. a5 points to the process descriptor of the dying process. a6 points to
  1780. the kernals variables. G_term may be used to clean up a processes
  1781. environment or some such function.
  1782.  
  1783. G_pexec is called just before the following instructions, which execute
  1784. a new task:
  1785.  
  1786.         movem.l     (sp)+,d0-a6            Get new processes registers
  1787.         rte                                Execute it
  1788.  
  1789. Thus any and all registers may be used. a5 points to the new processes
  1790. process descriptor, and a6 points to the kernals variables.
  1791.  
  1792. G_trace is called when a process makes a Trap #1 call, and has its
  1793. trace bit set (see function 0xa2 below). Register a4 will point to
  1794. the parameters to the call (thus 0(a4) will always be the function
  1795. number of the call being executed), a5 points to the process descriptor,
  1796. and a6 is the kernals variables; register d1 will be a 0 if this is the
  1797. start of the trace (trace is called before the execution of the
  1798. function, and again after the function is finished), or a -1 if this is
  1799. the end of the trace (a4 is undefined at the end of the trace). Registers
  1800. a4-a6 must be preserved. All others may be used (if d1 is -1, then d0 is
  1801. the return code from the function).
  1802.  
  1803. Word   Variable that is to be read or possibly written. Numbered from
  1804.        0 to 19. Currently numbers 16, 17 and 18 are not used, and will
  1805.        return an error if you try to read or change them.
  1806.  
  1807. Word   Read/change flag. Zero means read the variable only.
  1808.  
  1809. Long   New value of variable if flag is not zero. Note that not all of 
  1810.        the variables are changeable. If you try to change a variable 
  1811.        that is read only, no error will be returned, just the contents
  1812.        of the variable. Also, some of the variables are word, and some
  1813.        are long. For word values, only the lower word of the long will
  1814.        be used.
  1815.  
  1816. Register D0.L : If no errors (noted by a negative), will return the 
  1817.                 previous contents of the variable. Possible errors:
  1818.  
  1819. -32 :  Invalid variable number.
  1820.  
  1821. Note: no range checking is performed on the new value for a variable 
  1822. (if flag is <> 0) so it is up to the caller to insure that the new 
  1823. value is in range, else unpredictable results may occur.
  1824.  
  1825. In assembly language:
  1826.  
  1827.      move.l  new_value,-(sp)
  1828.      move    flag,-(sp)
  1829.      move    var_num,-(sp)
  1830.      move    #$9f,-(sp)
  1831.      trap    #1
  1832.      lea     10(sp),sp
  1833.  
  1834. +--------------------------------------------------------------------------+
  1835.  
  1836. A0: Read or modify the name of a process
  1837.  
  1838. long Pname(proc_id,get_set,name)
  1839. int proc_id;
  1840. int get_set;
  1841. char *name;
  1842. {
  1843. }
  1844.  
  1845.      +-------------------------------------+ Low memory (parameter
  1846.      |         Function Code  0xA0         | Word        block addr)
  1847.      +-------------------------------------+
  1848.      |              Process ID             | Word
  1849.      +-------------------------------------+
  1850.      |           Get or set flag           | Word
  1851.      +-------------------------------------+
  1852.      |                                     |
  1853.      +     Pointer to character array      + Long
  1854.      |                                     |
  1855.      +-------------------------------------+ High memory
  1856.  
  1857. This function allows you to read or change the name of a process.
  1858. Note that only the superuser may change the name of any process.
  1859. Non superusers may only change the name of processes with the
  1860. same group.user ID.
  1861.  
  1862. Word   Process ID of the process whose name is to be read or written.
  1863.        Zero stands for the current (calling) process.
  1864.  
  1865. Word   Read or write flag. 0 means read.
  1866.  
  1867. Long   Pointer to character buffer at least 14 bytes long for read,
  1868.        (flag = 0), or null terminated string for new name (max
  1869.        string length is 13 characrters).
  1870.  
  1871. Return parameter
  1872.  
  1873. Register D0.L : Zero if no errors detected. Possible errors:
  1874.  
  1875. -62 : Permission violation. Process tried to change the name but was
  1876.       not a super user or did not have same owner ID. 
  1877.  
  1878. -70 : Unknown process. Process ID is for a process that has never 
  1879.       existed (no process descriptor has been created for that PID).
  1880.  
  1881. -71 : Dead process. The process ID was for a process that has 
  1882.       terminated.
  1883.  
  1884. In assembly language:
  1885.  
  1886.      pea     name
  1887.      move    #get_set,-(sp)
  1888.      move    #proc_id,-(sp)
  1889.      move    #$A0,-(sp)
  1890.      trap    #1
  1891.      lea     10(sp),sp
  1892.  
  1893. +--------------------------------------------------------------------------+
  1894.  
  1895. A1: Read or modify a process' user vector
  1896.  
  1897. long Pvector(proc_id,vector)
  1898. int proc_id;
  1899. long vector;
  1900. {
  1901. }
  1902.  
  1903.      +-------------------------------------+ Low memory (parameter
  1904.      |         Function Code  0xA1         | Word        block addr)
  1905.      +-------------------------------------+
  1906.      |              Process ID             | Word
  1907.      +-------------------------------------+
  1908.      |                                     |
  1909.      +               Vector                + Long
  1910.      |                                     |
  1911.      +-------------------------------------+ High memory
  1912.  
  1913. This function allows you to read or change a user defined vector for
  1914. any process. Note that the kernal doesn't look at or otherwise use
  1915. this vector. It is simply a very low level way to pass data between
  1916. processes. The long value could be a pointer to shared memory, or
  1917. just a longword value that has meaning to the processes involved.
  1918.  
  1919. Word   Process ID of the process whose vector is to be read or
  1920.        written. Zero stands for the current (calling) process.
  1921.  
  1922. Long   If this is zero, then the call just returns the current
  1923.        value of the user vector; else is the new value of the
  1924.        vector. Thus the value zero cannot be used as a data
  1925.        value.
  1926.  
  1927. Return parameter
  1928.  
  1929. Register D0.L : Old vector if no error. Possible errors:
  1930.  
  1931. -70 : Unknown process. Process ID is for a process that has never 
  1932.       existed (no process descriptor has been created for that PID).
  1933.  
  1934. -71 : Dead process. The process ID was for a process that has 
  1935.       terminated.
  1936.  
  1937. Note: it is possible to confuse legitimate values with these two error
  1938.       codes. It is therfore recomended that these values be avoided as
  1939.       potential data.
  1940.  
  1941. In assembly language:
  1942.  
  1943.      move.l  #vector,-(sp)
  1944.      move    #proc_id,-(sp)
  1945.      move    #$A1,-(sp)
  1946.      trap    #1
  1947.      addq.l  #8,sp
  1948.  
  1949. +--------------------------------------------------------------------------+
  1950.  
  1951. A2: Set or clear bits in a process' attribute byte
  1952.  
  1953. long Pattrib(proc_id,flag,mask)
  1954. int proc_id;
  1955. unsigned char flag;
  1956. unsigned char mask;
  1957. {
  1958. }
  1959.  
  1960.      +-------------------------------------+ Low memory (parameter
  1961.      |         Function Code  0xA2         | Word        block addr)
  1962.      +-------------------------------------+
  1963.      |              Process ID             | Word
  1964.      +-------------------------------------+
  1965.      |           Set/Clear flag            | Byte
  1966.      +-------------------------------------+
  1967.      |     Bit mask for bits to change     | Byte
  1968.      +-------------------------------------+ High memory
  1969.  
  1970. This function allows you to selectively set or clear bits in the
  1971. processes attribute byte. Currently, these bits are defined:
  1972.  
  1973. #define B_redirect 0    /* Have BIOS check for con redirection                */
  1974. #define N_redirect 1    /* Make negative handles redirect                     */
  1975. #define proc_trace 3    /* If set, jump through trace vector on function call */
  1976.  
  1977. Word   Process ID of the process whose attribute byte is to be
  1978.        changed. Zero stands for the current (calling) process.
  1979.  
  1980. byte   Set or clear flag. If zero, is a clear bit operation, else is a
  1981.        set bit operation.
  1982.  
  1983. byte   Mask of bits to modify. If a bit is set in this byte, then that
  1984.        particular attribute bit will be changed according to the flag
  1985.        byte.
  1986.  
  1987. Return parameter
  1988.  
  1989. Register D0.L : If not negative, lower byte is attribute byte before
  1990.         operation. Possible errors:
  1991.  
  1992. -70 : Unknown process. Process ID is for a process that has never 
  1993.       existed (no process descriptor has been created for that PID).
  1994.  
  1995. -71 : Dead process. The process ID was for a process that has 
  1996.       terminated.
  1997.  
  1998. In assembly language:
  1999.  
  2000.      lsl.w     #8,d0               d0 is flag byte
  2001.      or.w     d1,d0               d1 is mask
  2002.      move    d0,-(sp)
  2003.      move    #proc_id,-(sp)
  2004.      move    #$A2,-(sp)
  2005.      trap    #1
  2006.      addq.l  #6,sp
  2007.  
  2008. +--------------------------------------------------------------------------+
  2009.  
  2010. A3: Set or get the maximum memory returned for Malloc(-1) for a process
  2011.  
  2012. long Pmaxmem(proc_id,flag,size)
  2013. int proc_id;
  2014. int flag;
  2015. long size;
  2016. {
  2017. }
  2018.  
  2019.      +-------------------------------------+ Low memory (parameter
  2020.      |         Function Code  0xA3         | Word        block addr)
  2021.      +-------------------------------------+
  2022.      |              Process ID             | Word
  2023.      +-------------------------------------+
  2024.      |             Set/get flag            | Word
  2025.      +-------------------------------------+
  2026.      |                                     |
  2027.      +        New max memory value         + Long
  2028.      |                                     |
  2029.      +-------------------------------------+ High memory
  2030.  
  2031. This function allows you to set a maximum for a Malloc(-1) function
  2032. call made by a process. Since most programs will do a Malloc(-1) call
  2033. to determine how much memory is in the system, then malloc all of that
  2034. memory, this function can keep most memory hogs at bay. If this value
  2035. is set to zero for a process, then no maximum is in effect and the
  2036. kernal will return the size of the largest block of ram. Note: a
  2037. newly forked process will inherit its parent's max_mem setting.
  2038. Also, only a super user may change this value for all processes, else
  2039. only processes with the same group.user ID may be changed.
  2040.  
  2041. Word   Process ID of the process whose max memory value is to be
  2042.        read or written. Zero stands for the current (calling) process.
  2043.  
  2044. Word   Set or get flag. If zero, is a get operation, else is a
  2045.        set operation.
  2046.  
  2047. Long   New max memory value for a set call. 
  2048.  
  2049. Return parameter
  2050.  
  2051. Register D0.L : If not negative, is original setting before a set call.
  2052.         Possible errors:
  2053.  
  2054. -62 : Permission violation. Process tried to change the max mem value
  2055.       but was not a super user or did not have same owner ID. 
  2056.  
  2057. -70 : Unknown process. Process ID is for a process that has never 
  2058.       existed (no process descriptor has been created for that PID).
  2059.  
  2060. -71 : Dead process. The process ID was for a process that has 
  2061.       terminated.
  2062.  
  2063. In assembly language:
  2064.  
  2065.      move.l  #size,-(sp)
  2066.      move    #flag,-(sp)
  2067.      move    #proc_id,-(sp)
  2068.      move    #$A3,-(sp)
  2069.      trap    #1
  2070.      lea     10(sp),sp
  2071.  
  2072. +--------------------------------------------------------------------------+
  2073.  
  2074. Following are listings some important PowerDOS structures. These are
  2075. shown, not as C structures, but as Hisoft formatted assembly language
  2076. defines, since PowerDOS was written completely in assembly language.
  2077.  
  2078. The PowerDOS process descriptor:
  2079.  
  2080. Num_files   equ         32          Number of open files per process
  2081.  
  2082.             RSRESET
  2083.  
  2084. PD_ID       rs.w        1           Process ID
  2085. PD_parent   rs.w        1           Parent's ID
  2086. PD_sibling  rs.w        1           Sibling's ID
  2087. PD_child    rs.w        1           First child's ID
  2088. PD_group    rs.w        1           Group ID
  2089. PD_user     rs.w        1           User ID
  2090. PD_priority rs.w        1           Process priority
  2091. PD_age      rs.w        1           Process age
  2092. PD_status   rs.b        1           Process execution status
  2093. PD_queueID  rs.b        1           Current queue (sleep, wait or active)
  2094. PD_basepage rs.l        1           First memory block of process (basepage)  
  2095. PD_max_mem  rs.l        1           Max mem size returned for Malloc #-1
  2096. PD_ucall    rs.w        1           Last user state function call executed
  2097. PD_scall    rs.w        1           Last system state function call executed
  2098. PD_uticks   rs.l        1           Number of user state ticks elapsed
  2099. PD_sticks   rs.l        1           Number of system state ticks elapsed
  2100. PD_sleep    rs.l        1           Count of ticks to remain sleeping
  2101. PD_datetime rs.l        1           Date and time process started
  2102. PD_fcalls   rs.l        1           Number of function calls executed
  2103. PD_iocalls  rs.l        1           Number of i/o calls executed
  2104. PD_rbytes   rs.l        1           Number of bytes read
  2105. PD_wbytes   rs.l        1           Number of bytes written
  2106. PD_vector   rs.l        1           User defined vector
  2107. PD_dta      rs.l        1           Disk transfer address
  2108. PD_name     rs.b        14          Name of process
  2109. PD_devname  rs.b        8           Process current device name (currently only A, B, C, etc.)
  2110. PD_files    rs.w        Num_files   Process local path handles
  2111. PD_reentry  rs.b        1           Count of number of levels of reenterancy to kernal
  2112. PD_attrib   rs.b        1           Various attributes
  2113. PD_memblk   rs.w        1           Index of head of procs mdb's
  2114. PD_pqueue   rs.l        1           Previous process queue pointer
  2115. PD_nqueue   rs.l        1           Next process queue pointer
  2116. PD_pioq     rs.w        1           ID of previous process in i/o queue
  2117. PD_nioq     rs.w        1           ID of next process in i/o queue
  2118. PD_q_ptr    rs.l        1           Pointer or flag for queue functions
  2119. PD_intcpt   rs.l        1           Address of signal intercept routine
  2120. PD_intcptv  rs.l        1           Address of vars needed for intercept
  2121. PD_signal   rs.l        1           Signal code that caused death
  2122. PD_stack    rs.l        1           Process stack pointer
  2123. PD_reg_save rs.l        1           Pointer to current (X)BIOS register save
  2124. PD_trap1    rs.l        1           Save area for "dirty" trap one vector
  2125. PD_alias    rs.l        1           Pointer to alias being used for current i/o operation
  2126. PD_defdirs  rs.l        26          Default directory of up to 26 drives
  2127. * Dir's first cluster number, 0 for root. Copied from parent when created
  2128. * Most file managers that use this feature require only words, but a long
  2129. * is allocated for future file managers.
  2130. PD_status2  rs.b        1           Place for new attributes to be stored
  2131. PD_reserve1 rs.b        1
  2132. PD_reserve2 rs.w        18          Space for additions in the future...
  2133. PD_stackbot rs.b        1000        Process supervisor stack space
  2134. PD_sstack   equ         __RS        Top of process supervisor stack
  2135.             rs.b        162         Allow for 3 levels of reentrancy to (X)BIOS
  2136. PD_bios_sav equ         __RS
  2137. PD_size     equ         __RS        Size of process descriptor
  2138.  
  2139. * Process descriptor block allocation size. First long is pointer to next
  2140. * block. Ten process descriptors per block allocated
  2141. PD_alloc    equ         4+PD_size*10
  2142.  
  2143. * Status flag bits (for PD_status)
  2144.  
  2145. Sys_state   equ         0           Executing in system state
  2146. Wake_sig    equ         1           Process has pending wakeup signal
  2147. Time_out    equ         2           Time slice has expired
  2148. Subtask     equ         3           Process is a subtask (thread) of parent
  2149. Pexec4      equ         4           Assign base memory to parent on exit
  2150. Condemn     equ         5           Process is condemned
  2151. Concurrent  equ         6           Task is running concurrently with parent
  2152. Deskthread  equ         7           Set if process is Desktop process or decendent
  2153.  
  2154. * Bit definitions for PD_attrib
  2155.  
  2156. B_redirect  equ         0           Have BIOS check for con redirection
  2157. N_redirect  equ         1           Make negative handles redirect
  2158. proc_trace  equ         3           If set, jump through trace vector on function call
  2159.  
  2160. * Status flag bits for PD_status2
  2161. s2_preempt  equ         0           Allow preemption when clear, even if process is in system state
  2162. s2_suspend  equ         1           Suspend process at next entry to user state
  2163.  
  2164. * Defined signals
  2165.  
  2166. S_kill      equ         0
  2167. S_wake      equ         1
  2168. S_abort     equ         2
  2169. * (Maybe someday PowerDOS will have a more Unix like signalling system)
  2170.  
  2171. * Queue ID codes (for PD_queueID)
  2172.  
  2173. Q_current   equ         0           No queue, currently running
  2174. Q_active    equ         1           Active process queue
  2175. Q_sleep     equ         2           Sleeping process queue
  2176. Q_wait      equ         3           Waiting process queue
  2177. Q_event     equ         4           Waiting for an event
  2178. Q_dead      equ         5           No queue, dead process
  2179.  
  2180.  
  2181. +--------------------------------------------------------------------------+
  2182.  
  2183. Error code definitions (some are only used internally)
  2184.  
  2185. Edskchg     equ         -14         Disk in drive was changed
  2186.  
  2187. Einvfn      equ         -32         Invalid function number
  2188. Efilnf      equ         -33         File not found
  2189. Epthnf      equ         -34         Pathname not found
  2190. Enhndl      equ         -35         No file handles left
  2191. Eaccdn      equ         -36         Access denied
  2192. Eihndl      equ         -37         Invalid handle number
  2193. Ensmem      equ         -39         Not enough memory left
  2194. Eimba       equ         -40         Invalid memory block address
  2195. Edrive      equ         -46         Invalid drive specification
  2196. Enmfil      equ         -49         No more matching files
  2197.  
  2198. Ebnam       equ         -52         Bad pathname element
  2199. Efaterr     equ         -53         Error with FAT table
  2200. Edskfull    equ         -54         Disk is full
  2201. Elpcl       equ         -55         Clusters looped
  2202. Erootful    equ         -56         Root directory is full
  2203. Edirex      equ         -57         Directory already exists
  2204. Elocked     equ         -58         Record is locked
  2205. Enslock     equ         -59         Can't find requested lock to remove
  2206. Eeof        equ         -60         End of file
  2207. Etime       equ         -61         Device timed out
  2208. Epermit     equ         -62         Permission violation
  2209. Enovol      equ         -63         No volume name, can't change attributes
  2210.  
  2211. Erange      equ         -64         Range error
  2212. Eintrn      equ         -65         Internal error
  2213. Eplfmt      equ         -66         Invalid program load format
  2214. Egsbf       equ         -67         Setblock failure
  2215.  
  2216. Eunknp      equ         -70         Unknown process
  2217. Edeadpr     equ         -71         ID is for dead process
  2218. Enochld     equ         -72         Process has no children
  2219. Etabfull    equ         -73         IO device table is full
  2220. Efmddne     equ         -74         File manager or device driver non-existant
  2221. Eprocnf     equ         -75         Process with this name not found
  2222. Eioqs       equ         -76         Process already part of this ioqueue chain
  2223. Eqnf        equ         -77         Queue not found (by name)
  2224. Eunknq      equ         -78         Unknown queue (by queue_id)
  2225. Eqinuse     equ         -79         Queue in use; can't delete
  2226. Eqempty     equ         -80         Queue has no message or count available
  2227. Eqexist     equ         -81         Can't create; queue w/ same name exists
  2228. Epipex      equ         -82         Can't create; pipe w/ same name exists
  2229. Epipenf     equ         -83         Named pipe not found for open
  2230. Epipewrt    equ         -84         Pipe write error: written data can't be read
  2231. Enodev      equ         -85         No device for given device number
  2232. Enomdev     equ         -86         No devices with given number or higher
  2233. Eorphan     equ         -87         Process is an orphan; it has no parent
  2234. Enosighand  equ         -88         Process has no signal handler installed
  2235.  
  2236. +--------------------------------------------------------------------------+
  2237.  
  2238. Kernal variables:
  2239.  
  2240.             RSRESET
  2241.  
  2242. G_active    rs.l        1           Head of active queue
  2243. G_sleep     rs.l        1           Head of sleeping queue
  2244. G_wait      rs.l        1           Head of waiting queue
  2245. G_event     rs.l        1           Head of event queue
  2246. G_cur_pd    rs.l        1           Process descriptor of current process
  2247. G_totram    rs.l        1           Total ram found in system (TPA size)
  2248. G_bottpa    rs.l        1           Bottom of TPA
  2249. G_toptpa    rs.l        1           Top of TPA
  2250. G_maxtpa    rs.l        1           Maximum tpa size given to process
  2251. G_rsvmem    rs.l        1           High water mark of (S)Malloc(-1) calls
  2252. G_rsvmaxbl  rs.l        1           Max block size returned in G_rsvmem area
  2253. G_mem_mdb   rs.l        1           Points to 1st block of memory descriptor blocks
  2254. G_hmem_st   rs.w        1           Index of head of memory segment list (ST ram)
  2255. G_tmem_st   rs.w        1           Index of tail of memory segment list
  2256. G_sys_mem   rs.w        1           Index of linked system memory blocks
  2257. G_memblks   rs.w        1           Number of free memory block descriptors
  2258. * Extra ram that may be added to the system is allways considered fastram.
  2259. * When a block is added for the first time, the index to the head and tail
  2260. * of the memory (the next two variables) are defined. If any more memory
  2261. * is added after this, it will be added in to the same structure. (If it
  2262. * is not contiguous with previous added ram, there will be a gap, but the
  2263. * memory allocate and free routines deal with this situation properly.)
  2264. G_hmem_alt  rs.w        1           Head of alternate (TT) memory
  2265. G_tmem_alt  rs.w        1           Obviously the tail of said memory
  2266. G_pd        rs.l        1           Points to 1st process descriptor block
  2267. G_pthd      rs.l        1           Points to 1st path descriptor block
  2268. G_queue_dir rs.l        1           Points to 1st queue directory block
  2269. G_queue_buf rs.l        1           Points to 1st queue buffer block
  2270. G_max_age   rs.w        1           Max age to age a process
  2271. G_min_pty   rs.w        1           Min priority of ageable process
  2272. G_timeslice rs.w        1           Number of milliseconds per tick (20)
  2273. G_ticks     rs.w        1           Number of ticks per second (50)
  2274. G_timeout   rs.l        1           Global timeout added to 200 hz clock
  2275. G_idlecnt   rs.l        1           Used to keep track of idle time in 5 ms periods
  2276. G_idlecntdn rs.w        1           Count till next increment
  2277. G_fastload  rs.l        1           Number of k of heap to clear on prg load
  2278. G_aes_stack rs.l        1           Current aes stack top
  2279. G_term      rs.l        1           Vector to jump through on proc term
  2280. G_pexec     rs.l        1           Vector to jump through on proc create
  2281. G_trace     rs.l        1           Vector to jump through to trace a process' function calls
  2282. G_alias     rs.l        1           Pointer to any drive/path replacements
  2283. G_pathcheck rs.l        1           Vector to jump through before path parsing
  2284. * To allow PowerDOS to be expanded (or to emulate other OS's), a pointer
  2285. * to another table of vectors is available (zero when not used). The first
  2286. * long in this table is a pointer to another such table. The third word
  2287. * is the lowest sevice number in the table, and the fourth word is the
  2288. * highest service number. Following this is the long word pointers to
  2289. * the service functions. If a vector in this table is not used (an unused
  2290. * function) it should be set to zero.
  2291. G_extservic rs.l        1           Pointer to a table of extended services
  2292. G_p_run     rs.l        1           GemDOS p_run pointer; points to basepage
  2293. G_version   rs.w        1           Version number of GemDOS we are replacing
  2294. G_sysver    rs.w        1           Version of PowerDOS
  2295. G_sysdate   rs.l        1           Date of PowerDOS build (YYYYMMDD)
  2296. G_flags     rs.b        1           Various flags bits that may be needed
  2297. * Definitions for the bits in G_flags.
  2298. Gf_cookjar  equ         0           Set if PowerDOS installed the cookie jar
  2299. Gf_server   equ         1           Set if system is being used as a network server
  2300. G_reserve   rs.b        1
  2301. * When we launch a concurrent task, we give it clean OS vectors so no tsr
  2302. * programs will also be in the vectors. Such programs tend to fail when
  2303. * used in a multitasking environment. The following are the original
  2304. * vectors set when PowerDOS was installed.
  2305. G_trap1     rs.l        1           Vector for BDOS
  2306. G_trap13    rs.l        1           Vector for BIOS
  2307. G_trap14    rs.l        1           Vector for XBIOS
  2308. * The following is the special reserved block of memory used for video ram. Both
  2309. * its start address and index are given. This is for the Falcon only, to emulate
  2310. * the Mrealloc function call.
  2311. G_videomem  rs.l        1           Start address of special videomem block
  2312. G_videoidx  rs.w        1           Index of MDB of video memory
  2313.  
  2314. +--------------------------------------------------------------------------+
  2315.  
  2316.