doc/em/env.nr

   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
 106 1       Exit    status:int              Terminate this process
 107 2       Fork            e,flag,pid:int  Spawn new process
 108 3       Read    fildes:int;buf:ptr;nbytes:unsp
 109                         e:int;rbytes:unsp       Read from file
 110 4       Write   fildes:int;buf:ptr;nbytes:unsp
 111                         e:int;wbytes:unsp       Write on a file
 112 5       Open    string:ptr;flag:int
 113                         e,fildes:int    Open file for read and/or write
 114 6       Close   fildes:int      e:int   Close a file
 115 7       Wait            e:int;status,pid:int2
 116                                 Wait for child
 117 8       Creat   string:ptr;mode:int
 118                         e,fildes:int    Create a new file
 119 9       Link    string1,string2:ptr
 120                         e:int   Link to a file
 121 10      Unlink  string:ptr      e:int   Remove directory entry
 122 12      Chdir   string:ptr      e:int   Change default directory
 123 14      Mknod   string:ptr;mode,addr:int2
 124                         e:int   Make a special file
 125 15      Chmod   string:ptr;mode:int2
 126                         e:int   Change mode of file
 127 16      Chown   string:ptr;owner,group:int2
 128                         e:int   Change owner/group of a file
 129 18      Stat    string,statbuf:ptr
 130                         e:int   Get file status
 131 19      Lseek   fildes:int;off:int4;whence:int
 132                         e:int;oldoff:int4       Move read/write pointer
 133 20      Getpid          pid:int2        Get process identification
 134 21      Mount   special,string:ptr;rwflag:int
 135                         e:int   Mount file system
 136 22      Umount  special:ptr     e:int   Unmount file system
 137 23      Setuid  userid:int2     e:int   Set user ID
 138 24      Getuid          e_uid,r_uid:int2        Get user ID
 139 25      Stime   time:int4       e:int   Set time and date
 140 26      Ptrace  request:int;pid:int2;addr:ptr;data:int
 141                         e,value:int     Process trace
 142 27      Alarm   seconds:uns2    previous:uns2   Schedule signal
 143 28      Fstat   fildes:int;statbuf:ptr
 144                         e:int   Get file status
 145 29      Pause                   Stop until signal
 146 30      Utime   string,timep:ptr
 147                         e:int   Set file times
 148 33      Access  string:ptr;mode:int
 149                         e:int   Determine file accessibility
 150 34      Nice    incr:int                Set program priority
 151 35      Ftime   bufp:ptr        e:int   Get date and time
 152 36      Sync                    Update filesystem
 153 37      Kill    pid:int2;sig:int
 154                         e:int   Send signal to a process
 155 41      Dup     fildes,newfildes:int
 156                         e,fildes:int    Duplicate a file descriptor
 157 42      Pipe            e,w_des,r_des:int       Create a pipe
 158 43      Times   buffer:ptr              Get process times
 159 44      Profil  buff:ptr;bufsiz,offset,scale:intp
 160                                 Execution time profile
 161 46      Setgid  gid:int2        e:int   Set group ID
 162 47      Getgid          e_gid,r_gid:int Get group ID
 163 48      Sigtrp  trapno,signo:int
 164                         e,prevtrap:int  See below
 165 51      Acct    file:ptr        e:int   Turn accounting on or off
 166 53      Lock    flag:int        e:int   Lock a process
 167 54      Ioctl   fildes,request:int;argp:ptr
 168                         e:int   Control device
 169 56      Mpxcall cmd:int;vec:ptr e:int   Multiplexed file handling
 170 59      Exece   name,argv,envp:ptr
 171                         e:int   Execute a file
 172 60      Umask   mask:int2       oldmask:int2    Set file creation mode mask
 173 61      Chroot  string:ptr      e:int   Change root directory
 174 .fi
 175 .ad
 176 .LP
 177 Codes 0, 11, 13, 17, 31, 32, 38, 39, 40, 45, 49, 50, 52,
 178 55, 57, 58, 62, and 63 are
 179 not used.
 180 .PP
 181 All monitor calls, except fork and sigtrp
 182 are the same as the UNIX version 7 system calls.
 183 .PP
 184 The sigtrp entry maps UNIX signals onto EM interrupts.
 185 Normally, trapno is in the range 0 to 252.
 186 In that case it requests that signal signo
 187 will cause trap trapno to occur.
 188 When given trap number \-2, default signal handling is reset, and when given
 189 trap number \-3, the signal is ignored.
 190 .PP
 191 The flag returned by fork is 1 in the child process and 0 in
 192 the parent.
 193 The pid returned is the process-id of the other process.