@c is:
@c
@c @node New Section Name
-
@c @section New Section Name
@c
@c M-x texinfo-every-node-update will take care of calculating the
@menu
* Introduction::
* Compiler and OS Requirements::
-* Socket API::
-* IPv6 Support::
-* Local Addresses::
-* Host Address Lookup::
+* Networking::
* Thread Safety::
* Shared Libraries::
* Porting Issues::
from install.texi; eventually it will have more detailed information on
the internals of the @value{PRODUCT}.
-@node Compiler and OS Requirements, Socket API, Introduction, Top
+@node Compiler and OS Requirements, Networking, Introduction, Top
@chapter Compiler and OS Requirements
The basic Kerberos libraries are entirely written in C.
places where it helps performance or debugging, but the code should
still work fine with other C compilers.
+Inline functions should always be specified in the code as
+@code{static inline}, as the behavior of other forms vary across GCC
+versions and C and C++ language standards. We assume that static
+copies of inline functions will not be generated if they are not
+needed; under some compilers that behave otherwise (such as the
+current Sun compiler as of this writing) may produce executables and
+libraries much larger than they need to be.
+
On UNIX platforms, ... @i{(should outline what POSIX stuff we
require)}.
(Actually, this is more my view of how we've been doing things than
official policy. ---Ken)
-@node Socket API, IPv6 Support, Compiler and OS Requirements, Top
-@chapter Socket API
+Some of our code uses the SUSv2/C99 functions @code{snprintf} and
+@code{vsnprintf}. Since the two specifications differ, we assume that
+either specification may be followed: If truncation occurs, the return
+value may be the untruncated output length, or it may be negative (or
+may be zero if a zero length was supplied). It is therefore not
+permitted in our code to call these functions with a zero output
+length in order to determine the desired buffer size. A NULL output
+pointer is not permitted. In the header @file{k5-platform.h} we
+provide inline definitions for some platforms where these functions do
+not exist.
+
+We also use the extension functions @code{asprintf} and
+@code{vasprintf}, available on modern GNU and BSD based systems. The
+behaviors of these functions on errors vary between the two system
+types -- BSD stores a NULL as the output pointer, and GNU doesn't set
+it. We assume either may be the case: The output pointer may be
+unchanged or may be overwritten with NULL, and our code should thus
+assume it may be garbage, and should be assigned to if the value
+matters after an error is detected. Again, @file{k5-platform.h}
+provides workarounds for systems where these functions are not
+defined.
+
+Using these functions instead of plain @code{sprintf} without length
+checking may make our code slightly less vulnerable to buffer
+overruns.
+
+If necessary, we may eventually use a @code{[v]asnprintf} interface
+like that of the GNU C library, but we have not done so yet. Do not
+write code using that interface.
+
+@node Networking, Thread Safety, Compiler and OS Requirements, Top
+@chapter Networking
+
+@menu
+* Socket API::
+* IPv6 Support::
+* Local Addresses::
+* Host Address Lookup::
+@end menu
+
+@node Socket API, IPv6 Support, Networking, Networking
+@section Socket API
Someone should describe the API subset we're allowed to use with
sockets, how and when to use @code{SOCKET_ERRNO}, @i{etc}.
Note that all new code doing hostname and address translation should
use @code{getaddrinfo} and friends. (@xref{Host Address Lookup}.)
-@node IPv6 Support, Local Addresses, Socket API, Top
-@chapter IPv6 Support
+@node IPv6 Support, Local Addresses, Socket API, Networking
+@section IPv6 Support
Most of the IPv6 support is keyed on the macro @code{KRB5_USE_INET6}.
If this macro is not defined, there should be no references to
Somewhere between IRIX 6.5.14 and 6.5.16, partial IPv6 support was
introduced to the extent that the configuration system detects the
IPv6 support and attempts to use it. Code compiles, but then upon
-linking, one discovers that ``in6addr_any'' is not defined in any
+linking, one discovers that @code{in6addr_any} is not defined in any
system library. The header file @file{fake-addrinfo.h} provides a
static copy as a workaround. This run time IPv6 code has still not
been tested.
@end table
-@node Local Addresses, Host Address Lookup, IPv6 Support, Top
-@chapter Local Addresses
+@node Local Addresses, Host Address Lookup, IPv6 Support, Networking
+@section Local Addresses
(Last update: 2005-04-21, but most of the information dates back to
early 2002.)
buffer until the unused space is larger than an @code{ifreq} structure
by some safe margin.
-@node Host Address Lookup, Thread Safety, Local Addresses, Top
-@chapter Host Address Lookup
+@node Host Address Lookup, , Local Addresses, Networking
+@section Host Address Lookup
The traditional @code{gethostbyname} function is not thread-safe, and
does not support looking up IPv6 addresses, both of which are becoming
@code{AI_CANONNAME} flag is set. Check for a null pointer before
using it.
-@node Thread Safety, Shared Libraries, Host Address Lookup, Top
+@node Thread Safety, Shared Libraries, Networking, Top
@chapter Thread Safety
Work is still needed as this section is being written. However, we've
* Kerberos API Thread Safety::
* Thread System Requirements::
* Internal Thread API::
+* Thread Shim Layer Implementation::
@end menu
@node Kerberos API Thread Safety, Thread System Requirements, Thread Safety, Thread Safety
Unsafe system routines: @code{setenv}, @code{setlocale}.
-@node Internal Thread API, , Thread System Requirements, Thread Safety
+@node Internal Thread API, Thread Shim Layer Implementation, Thread System Requirements, Thread Safety
@section Internal Thread API
Some ideas were discussed on the @samp{krbdev} mailing list, and while
@code{assert}.
@end deftypefn
-Mutexes are assumed not to be recursive (@i{i.e.}, if a thread has the
-mutex locked already, attempting to lock it again is an error). There
-is also no support assumed for ``trylock'' or ``lock with timeout''
-operations.
+Mutexes should be assumed not to be recursive; if a thread has the
+mutex locked already, attempting to lock it again is an error and may
+have unpredictable results (error return, abort, data corruption).
+There is also no support assumed for ``trylock'' or ``lock with
+timeout'' operations.
-The operating system interface is similar to the above interface, with
-@code{k5_os_} names used for the OS mutex manipulation code. The type
-and macros indicated above are wrappers that optionally add debugging
-code and other stuff. So the Kerberos library code should use the
-macros above, and ports to new thread systems should be done through
-the @code{k5_os_} layer.
+Kerberos library code should use the macros above, and ports to new
+thread systems should be done through the @code{k5_os_} layer.
+(@xref{Thread Shim Layer Implementation}.)
Thread-local storage is managed through another interface layer:
just for convenience, and should not be visible to any application
code.
+@node Thread Shim Layer Implementation, , Internal Thread API, Thread Safety
+@section Thread Shim Layer Implementation
+
+Each of the @code{k5_mutex_} macros has a corresponding
+@code{k5_os_mutex_} macro which incorporates the operating system's
+mutex object, a flag for non-threaded systems, or both if the use of
+the OS pthread support is left until run time. The @code{k5_mutex_}
+wrappers add debugging information like the file and line number of
+the last lock or unlock call, where the mutex was created, @i{etc}.
+There may also be statistical information gathered, such as how long a
+thread waits for a mutex or how long the mutex is held. This is all
+defined in @file{k5-thread.h}.
+
+The thread-specific storage support is defined as macros expanding to
+similar function names with the @code{krb5int_} prefix, which
+functions are defined in @file{util/support/threads.c}. POSIX,
+Windows, and non-threaded versions are defined so far.
+
+The code for collecting and reporting statistics is also mainly in
+that file. Macros defined in @file{k5-thread.h} will expand to
+include calls to these functions, if @code{DEBUG_THREADS_STATS} is
+defined, or do nothing.
+
@node Shared Libraries, Porting Issues, Thread Safety, Top
@chapter Shared Libraries
@menu
* AIX Shared Library Support::
* Alpha OSF/1 Shared Library Support::
+* ELF Shared Library Support::
@end menu
@node AIX Shared Library Support, Alpha OSF/1 Shared Library Support, Operating System Notes for Shared Libraries, Operating System Notes for Shared Libraries
shared @samp{libkrb5.a} when GNU C is used.
-@node Alpha OSF/1 Shared Library Support, , AIX Shared Library Support, Operating System Notes for Shared Libraries
+@node Alpha OSF/1 Shared Library Support, ELF Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries
@subsection Alpha OSF/1 Shared Library Support
Shared library support has been tested with V2.1 and higher of the
@samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
and complete LD_LIBRARY_PATH in our tests.
-The one disadvantage with the method we are using....
+The one disadvantage with the method we are using.... [What?? This
+never got finished!]
+
+@node ELF Shared Library Support, , Alpha OSF/1 Shared Library Support, Operating System Notes for Shared Libraries
+@subsection ELF Shared Library Support
+
+It's tempting to add @samp{-Bsymbolic} to the commands for generating
+shared libraries. We don't explicitly support overriding our
+(internal or public) symbol names by applications, and binding at
+shared library creation time would result in smaller libraries that
+would load faster. However, it won't work. At least with the GNU and
+Solaris linkers and runtime environments, an executable using a data
+symbol exported by a shared library gets a copy of that data,
+initialized at run time by copying, and the program will only function
+properly if that definition can override the one present in the shared
+library. And, sadly, some of our shared libraries export variables
+that are directly referenced from programs.
@node Porting Issues, , Shared Libraries, Top
@chapter Porting Issues
wouldn't work well for VxWorks, for example, where symbol resolution
is done when the object code is loaded into the OS.)
-The configure script generates include/krb5/autoconf.h to influence
+The configure script generates include/autoconf.h to influence
whether certain calls are made or certain headers are included, and
Makefile in each directory to indicate compilation options. Each
source directory has a Makefile.in, and config/pre.in and
configure options. (Aside from always using the config/ fragments,
this is typical of GNU Autoconf based software configuration.)
-Windows host: The "wconfig" program generates the Makefiles in
+Windows host: The ``wconfig'' program generates the Makefiles in
subdirectories, with config/win-pre.in and config/win-post.in used in
-combination with each Makefile.in, and lines starting "##WIN32##" are
-uncommented, but @@FOO@@ substitutions are not done. Instead of
-generating autoconf.h, it's copied from include/win-mac.h, where we've
-hardcoded some of the parameters we care about, and just left a bunch
-of others out. If you work with a Windows host, you may want to
-provide your own makefile fragments, and a replacement for win-mac.h
-or some additional data to go into it conditionalized on some
-preprocessor symbol for pSOS.
+combination with each Makefile.in, and lines starting @code{##WIN32##}
+are uncommented, but @code{@@FOO@@} substitutions are not done.
+Instead of generating @file{autoconf.h}, it's copied from
+@file{include/win-mac.h}, where we've hardcoded some of the parameters
+we care about, and just left a bunch of others out. If you work with
+a Windows host, you may want to provide your own makefile fragments,
+and a replacement for @file{win-mac.h} or some additional data to go
+into it conditionalized on some preprocessor symbol for pSOS.
There are also places where we assume that certain header files or
functions are available, because both (most) UNIX and Windows
platforms (that we care about currently) provide them. And probably a
-handful of places where we check for _WIN32 to decide between "the
-Windows way" and "everything else" (i.e., UNIX); you might need to add
+handful of places where we check for @code{_WIN32} to decide between ``the
+Windows way'' and ``everything else'' (i.e., UNIX); you might need to add
a third branch for pSOS. And some places where we've got hooks for
Kerberos for Mac support, which you can probably ignore.
In the current 1.4 beta code, our library wants to find routines for
making DNS queries (SRV and TXT RR queries specifically) that are
outside the scope of getaddrinfo and friends. We also look for
-/dev/random as a strong random number source, and text files for
-configuration information. Our code assumes that allocating and
+@file{/dev/random} as a strong random number source, and text files
+for configuration information. Our code assumes that allocating and
reallocating lots of little (or not so little) bits of memory isn't
too horribly expensive, and we don't take any special pains to keep
our stack size small. Depending how pSOS works, you may need to add
to the thread support code. (The MIT code doesn't create threads, but
will do locking and such to allow multiple threads to share global
-data. The code in include/k5-thread.h is, uh, kind of involved, and
-some pains have been taken to use macros whenever possible to allow
-assert() calls during debugging to report useful line numbers.) There
-are probably other minor issues to deal with, I'm just making some
-guesses.
+data. The code in @file{include/k5-thread.h} is, uh, kind of
+involved, and some pains have been taken to use macros whenever
+possible to allow @code{assert()} calls during debugging to report
+useful line numbers.) There are probably other minor issues to deal
+with, I'm just making some guesses.
> - what type of Data formats exchanged between Client and Server?
AS-REQ/AS-REP/TGS-REQ/TGS-REP message exchanges, and generating AP-REQ
and accepting AP-REP messages, etc.
-
@contents
@bye
projects / krb5.git / blobdiff