env.nr 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  1. .bp
  2. .P1 "ENVIRONMENT INTERACTIONS"
  3. .PP
  4. EM programs can interact with their environment in three ways.
  5. Two, starting/stopping and monitor calls, are dealt with in this chapter.
  6. The remaining way to interact, interrupts, will be treated
  7. together with traps in chapter 9.
  8. .P2 "Program starting and stopping"
  9. .PP
  10. EM user programs start with a call to a procedure called
  11. _m_a_i_n.
  12. The assembler and backends look for the definition of a procedure
  13. with this name in their input.
  14. The call passes three parameters to the procedure.
  15. The parameters are similar to the parameters supplied by the
  16. .UX
  17. operating system to C programs.
  18. These parameters are often called \fBargc\fP, \fBargv\fP and \fBenvp\fP.
  19. Argc is the parameter nearest to LB and is a wordsized integer.
  20. The other two are pointers to the first element of an array of
  21. string pointers.
  22. The \fBargv\fP array contains \fBargc\fP
  23. strings, the first of which contains the program call name.
  24. The other strings in the \fBargv\fP
  25. array are the program parameters.
  26. .PP
  27. The \fBenvp\fP
  28. array contains strings in the form "name=string", where 'name'
  29. is the name of an environment variable and string its value.
  30. The \fBenvp\fP
  31. is terminated by a zero pointer.
  32. .PP
  33. An EM user program stops if the program returns from the first
  34. invocation of _m_a_i_n.
  35. The contents of the function return area are used to procure a
  36. wordsized program return code.
  37. EM programs also stop when traps and interrupts occur that are
  38. not caught and when the exit monitor call is executed.
  39. .P2 "Input/Output and other monitor calls"
  40. .PP
  41. EM differs from most conventional machines in that it has high level i/o
  42. instructions.
  43. Typical instructions are OPEN FILE and READ FROM FILE instead
  44. of low level instructions such as setting and clearing
  45. bits in device registers.
  46. By providing such high level i/o primitives, the task of implementing
  47. EM on various non EM machines is made considerably easier.
  48. .PP
  49. I/O is initiated by the MON instruction, which expects an iocode on top
  50. of the stack.
  51. Often there are also parameters which are pushed on the
  52. stack in reverse order, that is: last
  53. parameter first.
  54. Some i/o functions also provide results, which are returned on the stack.
  55. In the list of monitor calls we use several types of parameters and results,
  56. these types consist of integers and unsigneds of varying sizes, but never
  57. smaller than the wordsize, and the two pointer types.
  58. .LP
  59. The names of the types used are:
  60. .DS
  61. .TS
  62. tab(:);
  63. l l.
  64. int:an integer of wordsize
  65. int2:an integer whose size is the maximum of the wordsize and 2 bytes
  66. int4:an integer whose size is the maximum of the wordsize and 4 bytes
  67. intp:an integer with the size of a pointer
  68. uns2:an unsigned integer whose size is the maximum of the wordsize and 2
  69. unsp:an unsigned integer with the size of a pointer
  70. ptr:a pointer into data space
  71. .TE
  72. .DE
  73. .LP
  74. The table below lists the i/o codes with their results and
  75. parameters.
  76. This list is similar to the system calls of the UNIX Version 7
  77. operating system.
  78. .QQ
  79. To execute a monitor call, proceed as follows:
  80. .IP a)
  81. Stack the parameters, in reverse order, last parameter first.
  82. .IP b)
  83. Push the monitor call number (iocode) onto the stack.
  84. .IP c)
  85. Execute the MON instruction.
  86. .LP
  87. An error code is present on the top of the stack after
  88. execution of most monitor calls.
  89. If this error code is zero, the call performed the action
  90. requested and the results are available on top of the stack.
  91. Non-zero error codes indicate a failure, in this case no
  92. results are available and the error code has been pushed twice.
  93. This construction enables programs to test for failure with a
  94. single instruction (~TEQ or TNE~) and still find out the cause of
  95. the failure.
  96. The result name 'e' is reserved for the error code.
  97. .ne 5
  98. .LP
  99. List of monitor calls.
  100. .LP
  101. .nf
  102. .na
  103. .ta 4n 13n 29n 52n
  104. nr name parameters results function
  105. 1 Exit status:int Terminate this process
  106. 2 Fork e,flag,pid:int Spawn new process
  107. 3 Read fildes:int;buf:ptr;nbytes:unsp
  108. e:int;rbytes:unsp Read from file
  109. 4 Write fildes:int;buf:ptr;nbytes:unsp
  110. e:int;wbytes:unsp Write on a file
  111. 5 Open string:ptr;flag:int
  112. e,fildes:int Open file for read and/or write
  113. 6 Close fildes:int e:int Close a file
  114. 7 Wait e:int;status,pid:int2
  115. Wait for child
  116. 8 Creat string:ptr;mode:int
  117. e,fildes:int Create a new file
  118. 9 Link string1,string2:ptr
  119. e:int Link to a file
  120. 10 Unlink string:ptr e:int Remove directory entry
  121. 12 Chdir string:ptr e:int Change default directory
  122. 14 Mknod string:ptr;mode,addr:int2
  123. e:int Make a special file
  124. 15 Chmod string:ptr;mode:int2
  125. e:int Change mode of file
  126. 16 Chown string:ptr;owner,group:int2
  127. e:int Change owner/group of a file
  128. 18 Stat string,statbuf:ptr
  129. e:int Get file status
  130. 19 Lseek fildes:int;off:int4;whence:int
  131. e:int;oldoff:int4 Move read/write pointer
  132. 20 Getpid pid:int2 Get process identification
  133. 21 Mount special,string:ptr;rwflag:int
  134. e:int Mount file system
  135. 22 Umount special:ptr e:int Unmount file system
  136. 23 Setuid userid:int2 e:int Set user ID
  137. 24 Getuid e_uid,r_uid:int2 Get user ID
  138. 25 Stime time:int4 e:int Set time and date
  139. 26 Ptrace request:int;pid:int2;addr:ptr;data:int
  140. e,value:int Process trace
  141. 27 Alarm seconds:uns2 previous:uns2 Schedule signal
  142. 28 Fstat fildes:int;statbuf:ptr
  143. e:int Get file status
  144. 29 Pause Stop until signal
  145. 30 Utime string,timep:ptr
  146. e:int Set file times
  147. 33 Access string:ptr;mode:int
  148. e:int Determine file accessibility
  149. 34 Nice incr:int Set program priority
  150. 35 Ftime bufp:ptr e:int Get date and time
  151. 36 Sync Update filesystem
  152. 37 Kill pid:int2;sig:int
  153. e:int Send signal to a process
  154. 41 Dup fildes,newfildes:int
  155. e,fildes:int Duplicate a file descriptor
  156. 42 Pipe e,w_des,r_des:int Create a pipe
  157. 43 Times buffer:ptr Get process times
  158. 44 Profil buff:ptr;bufsiz,offset,scale:intp
  159. Execution time profile
  160. 46 Setgid gid:int2 e:int Set group ID
  161. 47 Getgid e_gid,r_gid:int Get group ID
  162. 48 Sigtrp trapno,signo:int
  163. e,prevtrap:int See below
  164. 51 Acct file:ptr e:int Turn accounting on or off
  165. 53 Lock flag:int e:int Lock a process
  166. 54 Ioctl fildes,request:int;argp:ptr
  167. e:int Control device
  168. 56 Mpxcall cmd:int;vec:ptr e:int Multiplexed file handling
  169. 59 Exece name,argv,envp:ptr
  170. e:int Execute a file
  171. 60 Umask mask:int2 oldmask:int2 Set file creation mode mask
  172. 61 Chroot string:ptr e:int Change root directory
  173. .fi
  174. .ad
  175. .LP
  176. Codes 0, 11, 13, 17, 31, 32, 38, 39, 40, 45, 49, 50, 52,
  177. 55, 57, 58, 62, and 63 are
  178. not used.
  179. .PP
  180. All monitor calls, except fork and sigtrp
  181. are the same as the UNIX version 7 system calls.
  182. .PP
  183. The sigtrp entry maps UNIX signals onto EM interrupts.
  184. Normally, trapno is in the range 0 to 252.
  185. In that case it requests that signal signo
  186. will cause trap trapno to occur.
  187. When given trap number \-2, default signal handling is reset, and when given
  188. trap number \-3, the signal is ignored.
  189. .PP
  190. The flag returned by fork is 1 in the child process and 0 in
  191. the parent.
  192. The pid returned is the process-id of the other process.