home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 3 / 3296 / README < prev    next >
Encoding:
Text File  |  1991-05-07  |  6.1 KB  |  121 lines
  1. kstuff 0.18, 5/6/91, Daniel J. Bernstein.
  2.  
  3. This code is in alpha test. That means you shouldn't be surprised at
  4. bugs, annoying restrictions, exceedingly poor documentation, etc.
  5. However, I don't know of any bugs, and you should feel free to use the
  6. libraries in other programs. Some of the previous contributors to ofiles
  7. may want some rights to getdevicename.c, getuser.c, getvmseg.c,
  8. mntops.c, stattimeout.c, getnode.c, and virtype.c; other than that, this
  9. is all public-domain. (Nothing here is derived from any AT&T or Berkeley
  10. or GPL-infected code.) Please send any comments, criticism, or code to
  11. me at brnstnd@nyu.edu.
  12.  
  13. Be sure to apply the changes indicated at the top of Makefile for your
  14. system. Particular thanks to Vic Abell for portability mods, bug fixes,
  15. and extensive testing.
  16.  
  17. This package includes, among other things: load, a fast version of
  18. uptime; pff, an improved replacement for ofiles/fstat; authd, a revised
  19. version of the RFC 931 server; netstatuids, a version of netstat plus
  20. usernames on both sides; kmem, nlist, strerr, and u area libraries; the
  21. authuser library. See README.authd for an updated extract of the
  22. authd/authuser documentation.
  23.  
  24. To compile, just make. To install, run INSTALL from a root shell.
  25. (INSTALL checks each action with you before doing it.) To test, run
  26. ``make tests'' as any user.
  27.  
  28. I've included the findinode package here in directory findinode. It's
  29. entirely independent of kstuff, but pff can make good use of it. You
  30. probably want to look at that directory, and perhaps make and install
  31. findinode, before continuing with kstuff.
  32.  
  33.  
  34. Programs:
  35.  
  36. load is a fast version of uptime with a slightly different output
  37. format, meant to illustrate how to use these libraries. I don't know why
  38. uptime is so slow. Documentation is in load.1.
  39.  
  40. pff (process-file-file) is a mostly rewritten version of the popular
  41. ofiles utility. See pff.doc for some documentation. (Man page donations
  42. would be appreciated. :-)) See OFILES.hist for a history of ofiles.
  43. Although I think I've included almost every popular feature from the
  44. Dupuy-Leres ofiles, the Abell ofiles, and the Christiansen fstat, as
  45. well as some extras, pff should be quite a bit more portable than any of
  46. its predecessors. pff handles open files (and filesystems), network
  47. connections, mmaps, process texts, cwds, root directories, and
  48. controlling ttys. It works over NFS. It even handles process texts on
  49. the Convex, unlike the Christiansen fstat. Late addition: if you have
  50. findinode running, pff gives you filenames! Please send me any further
  51. extensions and portability mods you have. Thanks to all the ofiles and
  52. fstat authors for lots of code and ideas.
  53.  
  54. netstatuids uses the RFC 931 authuser library in authuser.c and the
  55. kernel libraries here to show you all active TCP connections, with the
  56. usernames on both sides. Naturally, it's faster than netstat -n, though
  57. I suppose this is excusable since netstat shows more information. Thanks
  58. to Seth Robertson for suggesting this program and writing a prototype.
  59.  
  60. authd is a revised version of the RFC 931 authd server (previous version
  61. available separately). It should be somewhat faster and somewhat more
  62. portable. Thanks to Kim Hoeglund for comments and code. Documentation is
  63. in authd.8, tcpuid.8, and tcpuname.8, copied from the authd 3.01
  64. distribution. (tcpuid and tcpuname should be linked to authd.)
  65.  
  66.  
  67. Libraries:
  68.  
  69. kmem.h and nlistlist.h are kmem/nlist libraries meant to provide an
  70. intuitive yet powerful interface. (mmem.h and smem.h are like kmem.h but
  71. handle /dev/mem and /dev/drum instead of /dev/kmem.) Intuitive:
  72. kmemcpy() works just like memcpy() but out of kmem. Powerful: If
  73. libraries X and Y are developed independently but both need to use kmem
  74. and nlist, normally they'd open independent descriptors and do separate
  75. nlist()s. This is horrendously inefficient. These libraries solve the
  76. problem. See avenrun.c, boottime.c, and load.c for examples.
  77.  
  78. getuser.h is a reasonably portable library to get the u area of a given
  79. struct proc. Together with kmem.h and nlistlist.h, getuser.h provides an
  80. interface about as useful as Sun's kvm library for kernel-reading
  81. applications but a lot more portable. (Well, I cheated a bit: under
  82. #ifdef sun, getuser.h just calls kvm_getu. The point is that
  83. applications don't have to worry whether getuser() is running on a Sun
  84. or not.)
  85.  
  86. avenrun.h, boottime.h, filetable.h, getfcred.h, inpcblist.h, and
  87. proctable.h are straightforward applications of the kmem and nlistlist
  88. libraries.
  89.  
  90. netinp.h is an experiment. I will probably eliminate it if inpcblist.h
  91. turns out to be portable enough. Thanks again to Kim Hoeglund.
  92.  
  93. strerr.h is another piece of my forthcoming error-handling library. It
  94. lets you set up libraries or sections of code so that callers can get a
  95. meaningful error message with a single function call. strerr handles
  96. recursion, so that if one library forwards an error from another library
  97. it called, the error message will include an error from the sublibrary.
  98. But none of the libraries have to worry about malloc()ing space or
  99. concatenating messages manually. Oh, yeah, and strerr(strerrno) is
  100. equivalent to ANSI C's strerror(errno) if you don't have ANSI libraries.
  101.  
  102. struct*.h are meant to keep you (well, me) from going insane when using
  103. vendor include files. If you #include "structproc.h", then no matter how
  104. badly structured the vendor's include files are, no matter how many of
  105. their files neglect to include their dependencies, no matter how many
  106. files blow up if they are included twice, you should get a working
  107. struct proc and the definitions necessary to use that struct. (You may
  108. not understand what struct proc is for, but that's a separate problem.
  109. :-))
  110.  
  111. conf*.h form a two-level #include system. Why is it good to have a
  112. single file for each #define, like confgnode.h for #ifdef GNODE? Among
  113. other reasons, this opens up the chance of vendors standardizing these
  114. #include files with the same names and meanings they have here. It also
  115. insulates the main code from OS changes. Feel free to use conf*.h in
  116. other packages. I am considering setting up a central registration
  117. system for files like this.
  118.  
  119. I know, there are lots of other libraries here... I'll document them
  120. soon.
  121.