home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / unix / unixlib36d / src / readme < prev   
Text File  |  1993-02-14  |  10KB  |  196 lines
  1.  
  2.  
  3.         UnixLib v3.6c Maintenance Documentation
  4.  
  5.  
  6. Directories marked '#' below contain proprietary source code. Source code
  7. in these directories is Copyright 1990/1991/1992/1993 H.Rogers and XFM
  8. Software, and may only be distributed or modified in connection with UnixLib
  9. development. All other use or distribution is strictly prohibited.
  10. This entire paragraph and the list of directories below must be present
  11. in a file called "ReadMe" in a prominent place on all media used to
  12. distribute the aforementioned source code or derivations thereof. Failure
  13. to comply with the above requirements is breach of copyright and other
  14. international laws.
  15.  
  16.  
  17.     !Alias              * Alias file (see "ReadMe")
  18.     !Boot            !Boot for UnixLib maintenance
  19.     clib              * Library directory
  20.     clib.h              * UnixLib ANSI header files
  21.     clib.o              * UnixLib directory
  22.     clib.o.unixlib          * UnixLib itself
  23.     clib.sys.h          * UnixLib specific header files
  24.     etc              * UnixLib version of /etc
  25.     ReadMe              * Documentation for UnixLib - this file
  26.     src            Source code
  27.     src.ReadMe        Documentation for source code
  28.     src.o            UnixLib portable object code
  29.     src.c              # UnixLib portable source code
  30.     src.stdio.o        UnixLib stdio object code
  31.     src.stdio.c          # UnixLib stdio source code
  32.     src.unix.c        UnixLib UNIX emulation source code
  33.     src.unix.o        UnixLib UNIX emulation object code
  34.     src.sys.c        UnixLib RiscOS related source code
  35.     src.sys.s        UnixLib RiscOS related source code (ARM code)
  36.     src.sys.o        UnixLib RiscOS related object code
  37.     test            UnixLib test programs
  38.     test.ReadMe        Documentation for test programs
  39.  
  40.  
  41. Asterisked files/directories are those that are necessary to compile
  42. programs with UnixLib. If you are installing UnixLib onto a hard disk you
  43. are advised not to change the organization of the directory tree other than
  44. to move etc into the root directory, since updates will be issued with
  45. this structure.
  46.  
  47.         How UnixLib Works
  48.  
  49. First - a comment on how the functions/variable definitions are
  50. split up between various object files. Storage allocation has been
  51. carefully thought out so as to minimise loading of unnecessary
  52. object files. This is why work variables used only in a particular
  53. object file, but which have to be initialised, will not be defined
  54. in the same place as where they are used. Thus: beware of shifting code
  55. or variables from one file to another. The minimum executable size is
  56. currently 24k.
  57.  
  58. In particular the stdio and vfork initialization/exit routines are
  59. conditionally linked in using AOF 'weak links' - if a program doesn't
  60. use stdio it won't get linked in with it. Similarly vfork(). The weak
  61. links are in sys.s._syslib and are documented in <sys/syslib.h>.
  62.  
  63. It is a good idea to look at the header files <sys/syslib.h> and
  64. <sys/unix.h> when reading this document - they are (hopefully :-))
  65. well commented. Also <sys/dev.h> and <sys/tty.h> should be understood.
  66.  
  67. The entry point for all programs is in sys.s._syslib. This is __main().
  68. __main() sets up the stack (__stack), break (cf UNIX) (__break), pointer
  69. to the command line used to invoke the program (__cli), and program
  70. start time (__time). The stack grows down from the top of user memory
  71. (as read by OS_GetEnv), and the break grows upwards from the top of the
  72. program data (RW) area.
  73.     __main() then calls _main() which is a C function (in sys.c.syslib).
  74. _main() initialises the signal handlers, exception handlers, floating point
  75. status (__fpflag), memory allocation (malloc() etc.), unix (calling
  76. __unixinit()), and stdio (calling __stdioinit()), in that order. Lastly
  77. _main() calls main() with the argc,argv that were generated by __unixinit().
  78.     __unixinit() first checks for the presence of the environment variable
  79. UnixLib$env. If this is set, it contains a value which is the address of a
  80. proc structure that should be inherited by the process, and no further
  81. initialisation is necessary (see <sys/unix.h> for details of the proc
  82. structure) - this is the case when one UnixLib program calls another using
  83. vfork() and execve(). The proc structure is pointed to by __u and is
  84. documented in <sys/unix.h> - look at this.
  85.     If UnixLib$env is unset, a default proc structure and FD set are
  86. generated, and FDs 0,1 and 2 are connected to the terminal defined by
  87. Unix$tty. The invoking command line (__cli) is copied in SVC mode, then
  88. scanned to form the argc, argv array and set any command line redirection.
  89. Lastly the environment variable Unix$uid is checked & processed as described
  90. in "ReadMe". __unixinit() also initialises the __fsdir[] structure array and
  91. __pipedir according to UnixFS$xxx and Unix$pipe as described in "ReadMe".
  92.  
  93. Various function calls are generated inline by the C compiler, and these
  94. functions are all in sys.s._syslib. They include the division, modulus,
  95. pointer check, stack overflow & profiling functions. The __memcpy() and
  96. __memset() functions are now in sys.s._mem: These are also called by the
  97. library memcpy() and memset() functions (and are written with some care in
  98. order to be particularly fast - approx. 4 times faster than in v3.2).
  99. Note the profiling functions merely return - profiling remains effectively
  100. unimplemented.
  101.  
  102. The low level exception handlers are in sys.s._signal, and the higher
  103. level UNIX abstraction (signal handlers) are dealt with in sys.c.signal.
  104. Note the use of OS_CallBack. It is unwise to mess with the ARM code in
  105. s._signal and s._syslib unless you *really* understand what's going on -
  106. the exception handling in particular is (and has to be) extremely nasty.
  107. Note UnixLib can recover from *all* signals/exceptions, unlike Acorn's
  108. AnsiLib, and implements far more (see <signal.h> and <sys/syslib.h>). 
  109.  
  110. UNIX system calls are implemented in unix.c.*, with the exception of alarm(),
  111. brk(), exit(), sbrk(), execve(), raise(), signal(), & vfork() since these
  112. interact closely with both RiscOS and the UnixLib internals - they are in
  113. sys.c.*.
  114.  
  115. sys.c.errlist contains the UNIX error list; RiscOS errors are flagged by
  116. calling __seterr() - in sys.c.os. This sets errno to EOS and sets the error
  117. string for perror() etc. You can also set the error string returned by
  118. perror() by calling __seterr_().
  119.  
  120. Also in the sys.s directory are the FP math routines, setjmp() & longjmp(),
  121. the ARM code parts of execve() and vfork(), and the RiscOS interface os_*().
  122. setjmp() & longjmp() modify their behaviour according to whether the FP is
  123. present or not - if not they don't bother saving the FP status and thus avoid
  124. generating SIGILL. execve() and vfork() are documented below.
  125.     The RiscOS interface is documented in <sys/os.h> and is pretty
  126. comprehensive. You can pass a null pointer to OS functions that store result
  127. registers in integer arrays, in which case no results are stored. os_swi(n,0)
  128. calls SWI n and assumes it doesn't require arguments (if it does it'll use
  129. garbage). os_print() & os_prhex() are useful for debugging messages as they
  130. guarantee output - note you must use OS newlines with os_print() i.e. "\r\n"
  131. not just "\n" as unix expects.
  132.  
  133. vfork() is implemented as an alias to setjmp() and longjmp() with some
  134. manipulation of the UNIX environment... Read the source code (sys.c.vfork
  135. and sys.s._vfork) to understand what it does/how it works. Also read the UNIX
  136. man page for vfork() - it's semantics are *not* normal. Despite it's
  137. restrictions vfork() can be used interchangeably with fork() as long as some
  138. care is taken...
  139.  
  140. execve() checks whether the current process is a child from a previous call
  141. to vfork() - if it isn't then it calls __reset() (see <sys/syslib.h>) and
  142. then overlays the current program with the new one (as per UNIX). If on the
  143. other hand it's a child, then it:
  144.  
  145.     0) Overwrites argv,argc and sets up a cli from the argc,argv array to
  146. subsequently pass to OS_CLI.
  147.     1) Closes all O_EXECCL file descriptors & turns off any alarm().
  148.     2) Turns off the __U_PPROC flag (see <sys/unix.h>) so that the
  149. subprogram is forced to exit fully.
  150.     3) Resets all exception handlers.
  151.     4) Calculates __exshift - the gap between the break and bottom of the
  152. stack - this is the amount by which the program will be copied up freeing
  153. memory for the subprogram.
  154.     5) Modifies the proc structure using the ushift() macro so that when
  155. it is copied up, all pointers are offset