Menu
▾
▴
Tree [47bb31] master / History
Markus Duft
Markus Duft
mduft
mduft
Read Me
SUACOMP - A Library complementing the SUA libc.
-----------------------------------------------
this library is licensed under the BEER-WARE LICENSE, which reads like this:
/* ----------------------------------------------------------------------------
* "THE BEER-WARE LICENSE" (Revision 42):
* <mduft@gentoo.org> wrote this file. As long as you retain this notice you
* can do whatever you want with this stuff. If we meet some day, and you think
* this stuff is worth it, you can buy me a beer in return. Markus Duft
* ---------------------------------------------------------------------------- */
Also, IMHO, you will probably have to drink some beer before reading the source...
HOW TO BUILD:
-------------
you need to define the SHARED_LIBC and STATIC_LIBC variables on the make command line
to be able to build the libraries. Be sure to specify the lib.so.<version> variant of
the shared libc (with FULL version!). on interix 3.5 this is '3.5' on all newer ones
it is '5.2' ('3.5' exists there, but DON'T use it!).
$ make SHARED_LIBC=/usr/lib/libc.so.5.2 STATIC_LIBC=/usr/lib/libc.a
Additionally to the LIBC flags, you can add -DITX_PRELOADABLE to the CFLAGS, to build
the library so that it can be used with LD_PRELOAD (which requires an extra hack)...
HOW TO CHECK:
-------------
currently the test suite is not too big, but tests a whole lot of the basic functionality,
like uid/gid/username/groupname mapping from and to interix, etc. You too need to specify
(at least) SHARED_LIBC. The same rules apply as for building.
Additionally TEST_VERBOSE=1 can be passed to make to increase to verbosity of the test
suite.
$ make SHARED_LIBC=/usr/lib/libc.so.5.2 check
example to get very verbose output:
$ SUACOMP_DEBUG_OUT=stderr make SHARED_LIBC=/usr/lib/libc.so.5.2 \
STATIC_LIBC=/usr/lib/libc.a CFLAGS="-D_DEBUG -D_DEBUG_TRACE" check TEST_VERBOSE=1
HOW TO INSTALL:
---------------
again, SHARED_LIBC and STATIC_LIBC need to be specified, like when building. Additionally,
PREFIX needs to be specified. Optionally DESTDIR can be specified too.
$ make SHARED_LIBC=/usr/lib/libc.so.5.2 STATIC_LIBC=/usr/lib/libc.a PREFIX=/some/prefix
or
$ make SHARED_LIBC=/usr/lib/libc.so.5.2 STATIC_LIBC=/usr/lib/libc.a PREFIX=/some/prefix \
DESTDIR=/where/to/copy/instead/of/prefix
Attention: as suacomp brings a long a few libraries and headers that overrule system libs
and headers, it is not possible to install the package with PREFIX beeing any of "/", "/usr"
or "/usr/" to prevent system files from beeing overwritten. suacomp is meant to be installed
into some arbitrary location. this location needs to be added to all compilations, so that
suacomp is found before (!) /usr/lib/libc.* when searching for libc. this probably means
wrapping/patching the compiler and linker with scripts or other means. this is exactly how
the gentoo prefix for interix toolchain works.
TROUBLESHOOTING:
----------------
the libraries can be built with various debug informations. to enable them, put the
according flag(s) in the CFLAGS variable for make like this:
$ make CFLAGS="-Wall -g -D_DEBUG -D_DEBUG_PASSWD" SHARED_LIBC=... STATIC_LIBC=...
availbale flags ATM are:
_DEBUG enable general debug output
_DEBUG_ACTCACHE enable output regarding file descriptor activity caching.
_DEBUG_MAPPING enable output regarding uid/gid/name mapping.
_DEBUG_DYNLOAD enable output regarding dynamic loading, function lookup, etc.
at runtime, you can influence the debug output behaviour with a view environment
variables. those are:
SUACOMP_DEBUG_OUT location where to put output. either a filename, or one of
the special locations "null", "stdout", "stderr".
SUACOMP_DEBUG_OUT_MODE the mode with which the file is opened. this is a string
as accepted by fopen(3) as "mode" parameter, default is "w"
SUACOMP_DEBUG_OUT_SUFFIX if set, s suffix is appended to the output filename of each
started process. this can be any combination of:
pid the process' id
name the process basename (taken from argv[0])
those can be seperated by any of ' ' (blank), '\t' (tab),
',' (comma) or '|' (pipe/or).
SUACOMP_DEBUG_FILTER filter processes emmittgin debug output based on argv[0]
of each process. multiple filters seperated by ' ', '\t',
',' or '|' are allowd. the process' argv[0] is checked
whether it contains (strstr()) any of the filters, and
debug output is only enabled if one of them matches.
for example setting to 'a.out' will allow debug output
for all processes containing a.out in argv[0]. thus
'./a.out', '/path/to/a.out' and 'a.out' are all valid.
IMPLEMENTATION RELATED NOTES:
-----------------------------
* poll()
The current implementation has one small caveat: It does not detect a romte end
pipe beeing closed. Normally, poll() should return POLLHUP if the remote end of
a pipe closed, but this implementation returns POLLOUT | POLLWRNORM instead.
This is, because the Interix libc provides no means of detecting this situation
using select() or any other provided API.
Otherwise, the poll implementation is tested with the test case also found in
gnulib, which should test more or less all possible use cases for poll().
* strotoll(), strtoull()
Those functions do nothing except wrap around strtoq and strtouq, which are
well available on interix. this is just for compatibility with more or less
broken packages, not doing any checks.
Be aware that no header file containing the signature is given, as this is
there only to satisfy packages assuming it is there.
* authenticateuser(), exec*_asuser()
The authenticateuser() function is deprecated and as such not supported by suacomp.
Use the setuser() function with the SU_CHECK flag instead. The exec*_asuser()
functions are not (yet) wrapped by suacomp. It should work equally well to do a
setuser() with SU_COMPLETE and a normal exec*() after that.
* sysconf()
Some of the values returned by sysconf() (the _SC_ARG_MAX value in particular)
are plain wrong, as they won't work out when used. The suacomp sysconf() mangles
the original values to known good values for all current interix versions.
(for example _SC_ARG_MAX is changed from 1MB to near 56K, which is the highest
working value at the moment)
