Internal review up to end of p11.

[userv.git] / INSTALL

diff --git a/INSTALL b/INSTALL
new file mode 100644 (file)
index 0000000..d7211b6
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,81 @@
+INSTALLATION INSTRUCTIONS:
+
+   $ ./configure
+   $ make
+   # make install
+
+This will not install the documentation, which is shipped as
+pre-prepared HTML and PostScript as well as debiandoc-sgml source.
+Put that (spec.html/ and spec.ps) where you will.
+
+SYSTEM REQUIREMENTS:
+
+Programs:
+
+* md5sum (Colin Plumb's or the GNU version)
+* GNU m4
+* GNU make
+* GNU flex
+* GCC is preferred but other compilers ought to work (though
+  no portability testing has yet been done).  ANSI C only.
+  ints must be at least 32 bits.
+* A sensible /bin/cat which notices write errors (ie not
+  SunOS4, BSD 4.3, or many others.)
+
+C Library:
+
+* [v]snprintf - a real version, not just [v]sprintf with a wrapper
+  that throws the argument away.
+* strsignal;
+* fnmatch;
+* BSD syslog(3);
+* strtoul;
+* memcpy, memset, memcpy;
+* realloc(0,size) must work and be equivalent to malloc(size).
+* <stdarg.h> (not varargs) and v[sf][n]printf.
+
+System interfaces:
+
+* setreuid(2), getreuid(2), getgroups(2), initgroups(3), with
+  the ability for root to (a) swap euid and ruid and
+  (b) give away all privilege by calling setreuid(ruid,ruid)
+  twice.
+* wait3 and waitpid, <wait.h> with WNOHANG, WIFSIGNALED,
+  WIFEXITEED, WTERMSIG, WEXITSTATUS and WCOREDUMP.
+* gid_t, uid_t, pid_t.
+* Unix-domain (AF_UNIX) stream sockets, for use with:
+  * BSD sockets - socket(), bind(), listen(), accept(), connect();
+  * socketpair(2);
+* lstat(2) (though stat(2) will be safe on systems without symlinks).
+* Pipes:
+  * creating using pipe(2) and mkfifo(2);
+  * proper interaction between open(O_RDWR), open(O_RDONLY),
+    open(O_WRONLY), close(), dup2, EPIPE, SIGPIPE, &c.;
+* POSIX signal handling - sigaction(2), sigprocmask(2), sigsuspend(2);
+
+To format the documentation:
+
+* debiandoc-sgml, and hence sp (aka nsgmls) and sgmlspm.
+* For PostScript output, Lout and possibly psutils.
+
+For debugging version (./configure --enable-debug):
+
+* initgroups(3) must use setgroups(2) and dynamic
+  linking must allow overriding setgroups(2) for initgroups(3);
+
+REENTRANCY IN THE LIBC:
+
+We assume, both in the client and server, that it is safe to use one
+stdio stream in a signal handler which interrupts use of a _different_
+stdio stream in another.  We make sure using setvbuf that we have
+pre-allocated buffers so that stdio doesn't need to use malloc() when
+we actually read or write.  stdio had better not do anything else
+weird.
+
+Furthermore, we assume that it is safe to use syslog in a signal
+handler which has interrupted a stdio operation (but we don't require
+that it be safe to invoke when the signal has interrupted a call to
+malloc, unless stdio makes gratuitous mallocs).  openlog will already
+have been called (but syslog will not necessarily have been called).
+
+We assume that strerror is completely reentrant.