summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorWaldemar Brodkorb <wbx@openadk.org>2017-06-23 23:56:56 +0200
committerWaldemar Brodkorb <wbx@openadk.org>2017-06-23 23:57:01 +0200
commitdc7ad97385c940c0a0d67b924c1b78159da5549d (patch)
tree8a2aeab9793e9bf101e8e328e73f6765ff853eec /docs
parent041cdc2769407c4d3869b218ad7ee7638e1c306e (diff)
docs: cleanup directory, fix some porting information
Diffstat (limited to 'docs')
-rw-r--r--docs/man/arc4random.3110
-rw-r--r--docs/man/ldconfig.873
-rw-r--r--docs/man/ldd.117
-rw-r--r--docs/porting.txt (renamed from docs/PORTING)19
-rw-r--r--docs/probe_math_exception.c64
-rw-r--r--docs/sigaction.txt249
6 files changed, 4 insertions, 528 deletions
diff --git a/docs/man/arc4random.3 b/docs/man/arc4random.3
deleted file mode 100644
index 933d2eb0c..000000000
--- a/docs/man/arc4random.3
+++ /dev/null
@@ -1,110 +0,0 @@
-.\" $OpenBSD: arc4random.3,v 1.19 2005/07/17 08:50:55 jaredy Exp $
-.\"
-.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by Niels Provos.
-.\" 4. The name of the author may not be used to endorse or promote products
-.\" derived from this software without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
-.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.\" Manual page, using -mandoc macros
-.\"
-.Dd April 15, 1997
-.Dt ARC4RANDOM 3
-.Os
-.Sh NAME
-.Nm arc4random ,
-.Nm arc4random_stir ,
-.Nm arc4random_addrandom
-.Nd arc4 random number generator
-.Sh SYNOPSIS
-.Fd #include <stdlib.h>
-.Ft uint32_t
-.Fn arc4random "void"
-.Ft void
-.Fn arc4random_stir "void"
-.Ft void
-.Fn arc4random_addrandom "u_char *dat" "int datlen"
-.Sh DESCRIPTION
-The
-.Fn arc4random
-function provides a high quality 32-bit pseudo-random
-number very quickly.
-.Fn arc4random
-seeds itself on a regular basis from the kernel strong random number
-subsystem described in
-.Xr random 4 .
-On each call, an ARC4 generator is used to generate a new result.
-The
-.Fn arc4random
-function uses the ARC4 cipher key stream generator,
-which uses 8*8 8-bit S-Boxes.
-The S-Boxes can be in about (2**1700) states.
-.Pp
-.Fn arc4random
-fits into a middle ground not covered by other subsystems such as
-the strong, slow, and resource expensive random
-devices described in
-.Xr random 4
-versus the fast but poor quality interfaces described in
-.Xr rand 3 ,
-.Xr random 3 ,
-and
-.Xr drand48 3 .
-.Pp
-The
-.Fn arc4random_stir
-function reads data from a pseudo-random device, usually
-.Pa /dev/urandom,
-and uses it to permute the S-Boxes via
-.Fn arc4random_addrandom .
-.Pp
-There is no need to call
-.Fn arc4random_stir
-before using
-.Fn arc4random ,
-since
-.Fn arc4random
-automatically initializes itself.
-.Sh SEE ALSO
-.Xr rand 3 ,
-.Xr rand48 3 ,
-.Xr random 3
-.Sh HISTORY
-An algorithm called
-.Pa RC4
-was designed by RSA Data Security, Inc.
-It was considered a trade secret.
-Because it was a trade secret, it obviously could not be patented.
-A clone of this was posted anonymously to USENET and confirmed to
-be equivalent by several sources who had access to the original cipher.
-Because of the trade secret situation, RSA Data Security, Inc. can do
-nothing about the release of the ARC4 algorithm.
-Since
-.Pa RC4
-used to be a trade secret, the cipher is now referred to as
-.Pa ARC4 .
-.Pp
-These functions first appeared in
-.Ox 2.1 .
diff --git a/docs/man/ldconfig.8 b/docs/man/ldconfig.8
deleted file mode 100644
index 208d63df1..000000000
--- a/docs/man/ldconfig.8
+++ /dev/null
@@ -1,73 +0,0 @@
-.TH LDCONFIG 8 2005-08-15 uClibc "Linux Programmer's Manual"
-.SH NAME
-ldconfig \- updates symlinks and cache for shared libraries
-.SH SYNOPSIS
-.B ldconfig
-[
-.B -DvqnNX
-] [
-.B -f conf
-] [
-.B -C cache
-] [
-.B -r root
-]
-.B dir ...
-.br
-.B ldconfig -l
-[
-.B -Dv
-]
-.B lib ...
-.br
-.B ldconfig -p
-.SH DESCRIPTION
-.B ldconfig
-creates the necessary links and cache to the most recent shared libraries
-found in the directories specified on the command line, in the file
-\fI/etc/ld.so.conf\fR, and in the default trusted directories (\fI/lib\fR and
-\fI/usr/lib\fR). The cache is used by the run-time linker.
-.B ldconfig
-checks the header and file names of the libraries it encounters when
-determining which versions should have their links updated.
-
-.B Note:
-Some features may not exist depending on how uClibc was built
-.SH OPTIONS
-.TP
-.B -C cache
-use specified \fIcache\fR instead of default
-.TP
-.B -D
-debug mode, do not update links
-.TP
-.B -f conf
-use specified \fIconf\fR instead of default
-.TP
-.B -l
-library mode, manually link libraries
-.TP
-.B -n
-do not process standard trusted directories
-.TP
-.B -N
-do not update the library cache
-.TP
-.B -p
-print the current library cache
-.TP
-.B -q
-quiet mode, do not print warnings you should actually be reading
-.TP
-.B -r root
-chroot to \fIroot\fR before running
-.TP
-.B -v
-verbose mode, print things as we go, and generally be annoying
-.TP
-.B -X
-do not update the library links
-.SH BUGS
-Probably, make sure you complain when you find them:
-.br
-http://bugs.uclibc.org/
diff --git a/docs/man/ldd.1 b/docs/man/ldd.1
deleted file mode 100644
index 0b69f730d..000000000
--- a/docs/man/ldd.1
+++ /dev/null
@@ -1,17 +0,0 @@
-.TH LDD 1 2005-08-15 uClibc "Linux Programmer's Manual"
-.SH NAME
-ldd \- Print shared library dependencies
-.SH SYNOPSIS
-.B ldd
-[
-.B OPTIONS
-]
-.B FILE ...
-.SH DESCRIPTION
-Prints shared library dependencies.
-.SH OPTIONS
-None actually, we lied about that part.
-.SH BUGS
-Probably, make sure you complain when you find them:
-.br
-http://bugs.uclibc.org/
diff --git a/docs/PORTING b/docs/porting.txt
index d04f3b4f5..380645801 100644
--- a/docs/PORTING
+++ b/docs/porting.txt
@@ -57,12 +57,6 @@ you are hacking on.
write them in C ... see other ports for more information
====================
-=== pthread deps ===
-====================
-
-TODO: nptl / linuxthreads / linuxthreads.old
-
-====================
=== ldso sysdeps ===
====================
- elf.h - presumably you've already taught binutils all about the random ELF
@@ -72,17 +66,12 @@ TODO: nptl / linuxthreads / linuxthreads.old
- enable ldso/shared options in your extra/Configs/Config.ARCH file
- you will need to create the following files in ldso/ldso/ARCH/
- dl-debug.h dl-startup.h dl-syscalls.h dl-sysdep.h elfinterp.c resolve.S
-
-- dl-debug.h: define string versions of all the relocations of your arch in the
- _dl_reltypes_tab array ... the index should match the actual reloc type, so
- if the value of say R_X86_64_PC16 is 13, then "R_X86_64_PC16" better be at
- index 13 of the array
+ dl-startup.h dl-syscalls.h dl-sysdep.h elfinterp.c resolve.S
- dl-startup.h:
- define the _start function which should call _dl_start which takes just one
parameter ... a pointer to argc (usually on the stack)
- glibc stores this function in libc/sysdeps/ARCH/dl-machine.h as RTLD_START
+ glibc stores this function in sysdeps/ARCH/dl-machine.h as RTLD_START
- define the GET_ARGV() macro which calculates the value of argv based upon
the parameter passed to _dl_start (usually it's simply just ARGS+1)
- define PERFORM_BOOTSTRAP_RELOC() macro which will handle just the relocs
@@ -105,7 +94,7 @@ TODO: nptl / linuxthreads / linuxthreads.old
- define elf_machine_type_class() macro
- define the inline functions elf_machine_dynamic, elf_machine_load_address,
and elf_machine_relative
- glibc stores a bunch of these values in libc/sysdeps/ARCH/dl-machine.h
+ glibc stores a bunch of these values in sysdeps/ARCH/dl-machine.h
- elfinterp.c:
define all the relocation functions ... it's best if you just copy from
@@ -119,7 +108,7 @@ TODO: nptl / linuxthreads / linuxthreads.old
- call _dl_linux_resolver()
- clean up after call
- jump to function address now stored in PLT
- glibc stores this function in libc/sysdeps/ARCH/dl-trampoline.S
+ glibc stores this function in sysdeps/ARCH/dl-trampoline.S
- utils/ldd.c - if you want support for ldso cache files (spoiler: you do),
then you'll need to teach ldd a little. generally, the fallback code
diff --git a/docs/probe_math_exception.c b/docs/probe_math_exception.c
deleted file mode 100644
index dbc9020d4..000000000
--- a/docs/probe_math_exception.c
+++ /dev/null
@@ -1,64 +0,0 @@
-/* Small test program for probing how various math functions
- * with specific operands set floating point exceptions
- */
-
-#define _ISOC99_SOURCE 1
-#define _GNU_SOURCE 1
-
-#include <stdint.h>
-#include <math.h>
-#include <fenv.h>
-#include <stdio.h>
-
-int main(int argc, char **argv)
-{
- float largest, small, t, inf_float;
-
- largest = small = 1;
- while (1) {
- t = largest + small;
- /* optimizations may make plain "t == largest" unreliable */
- if (memcmp(&t, &largest, sizeof(float)) == 0)
- break;
- if (isfinite(t)) {
- largest = t;
- small *= 2;
- continue;
- }
- small /= 2;
- }
- inf_float = largest + largest;
- //printf("%.40g ", largest);
- //printf("[%llx]\n", (long long) (*(uint32_t *)&largest));
-
- feclearexcept(FE_ALL_EXCEPT);
-
- //t = 1.0 / 0.0; // simple test: FE_DIVBYZERO
- //t = nextafterf(largest, 1); // glibc 2.8: no math exceptions raised
- //t = nextafterf(largest, largest); // glibc 2.8: no math exceptions raised
- //t = nextafterf(largest, inf_float); // glibc 2.8: FE_INEXACT FE_OVERFLOW
-
-#define PREX(ex) do { if (fetestexcept(ex)) printf(#ex " "); } while(0)
-#ifdef FE_INEXACT
- PREX(FE_INEXACT);
-#endif
-#ifdef FE_DIVBYZERO
- PREX(FE_DIVBYZERO);
-#endif
-#ifdef FE_UNDERFLOW
- PREX(FE_UNDERFLOW);
-#endif
-#ifdef FE_OVERFLOW
- PREX(FE_OVERFLOW);
-#endif
-#ifdef FE_INVALID
- PREX(FE_INVALID);
-#endif
- if (fetestexcept(FE_ALL_EXCEPT))
- printf("\n");
- else
- printf("no math exceptions raised\n");
-
- printf("%.40g\n", t);
- return 0;
-}
diff --git a/docs/sigaction.txt b/docs/sigaction.txt
deleted file mode 100644
index 667eeba41..000000000
--- a/docs/sigaction.txt
+++ /dev/null
@@ -1,249 +0,0 @@
- All what you never wanted to know about sigaction(),
- struct sigaction, and sigset_t.
-
-
-Before vda started messing with sigset_t, struct sigaction
-and sigaction() functions, things looked this way:
-
-
- Structures
-
-MIPS:
-
-Ignoring bogus "#if defined(__mips__) ..." block in
-libc/sysdeps/linux/common/bits/kernel_sigaction.h
-and using
-libc/sysdeps/linux/mips/bits/kernel_sigaction.h
-as an authoritative source:
-
-HAVE_SA_RESTORER is #defined
-struct old_kernel_sigaction {
- unsigned sa_flags;
- sighandler_t k_sa_handler;
- unsigned long sa_mask;
- unsigned pad0[3]; /* reserved, keep size constant */
- /* Abi says here follows reserved int[2] */
- void (*sa_restorer)(void);
-#if (_MIPS_SZPTR < 64)
- /* For 32 bit code we have to pad struct sigaction to get
- * constant size for the ABI */
- int pad1[1]; /* reserved */
-#endif
-};
-struct kernel_sigaction {
- unsigned int sa_flags;
- sighandler_t k_sa_handler;
- kernel_sigset_t sa_mask;
- void (*sa_restorer)(void);
- int s_resv[1]; /* reserved */
-};
-struct sigaction {
- unsigned sa_flags;
- sighandler_t sa_handler;
- sigset_t sa_mask;
- /* The ABI says here are two unused ints following. */
- /* Restore handler. */
- void (*sa_restorer)(void);
-#if _MIPS_SZPTR < 64
- int sa_resv[1];
-#endif
-};
-
-IA64:
-
-Has no old_sigaction. What a relief.
-
-struct kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned long sa_flags;
- sigset_t sa_mask;
-};
-struct sigaction {
- sighandler_t sa_handler;
- unsigned long sa_flags;
- sigset_t sa_mask;
-};
-
-Alpha:
-
-struct old_kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned long sa_mask;
- unsigned sa_flags;
-};
-struct kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned sa_flags;
- sigset_t sa_mask;
-};
-struct sigaction {
- sighandler_t sa_handler;
- sigset_t sa_mask;
- unsigned sa_flags;
-};
-
-HPPA:
-
-struct kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned long sa_flags;
- sigset_t sa_mask;
-};
-struct sigaction {
- sighandler_t sa_handler;
- unsigned long sa_flags;
- sigset_t sa_mask;
-};
-
-The rest, kernel side:
-
-HAVE_SA_RESTORER #defined
-struct old_kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned long sa_mask;
- unsigned long sa_flags;
- void (*sa_restorer)(void);
-};
-struct kernel_sigaction {
- sighandler_t k_sa_handler;
- unsigned long sa_flags;
- void (*sa_restorer)(void);
- sigset_t sa_mask;
-};
-
-On userspace side, Sparc has special struct sigaction:
-
-struct sigaction {
- sighandler_t sa_handler;
- sigset_t sa_mask;
- unsigned long sa_flags;
- void (*sa_restorer)(void); /* Not used by Linux/Sparc */
-};
-
-And finally the rest has:
-
-struct sigaction {
- sighandler_t sa_handler;
- sigset_t sa_mask;
- int sa_flags;
- void (*sa_restorer)(void);
-};
-
-Userspace sigset_t was uniformly defined as vector of longs
-big enough to hold 1024 (!) bits - carried over from glibc.
-Since the only arch whose struct kernel_sigaction contains sa_mask
-not as a last member is MIPS, MIPS has special kernel_sigset_t,
-which is an array of longs long enough for 128 bits.
-Other arches still used userspace sigset_t in struct kernel_sigaction,
-but it did not really matter because overlong kernel_sigaction
-does not hurt in sigaction() [explained below].
-On kernel side, all arches define _NSIG to 65 (meaning
-there are 64 signals, 1..64) except MIPS, which define it to 129.
-
-
- Functions
-
-sigaction() [libc function] usually has two kernel_sigaction's
-on stack and copy (userspace) struct sigaction members into
-first one, executes syscall, then pulls out the result from
-second one. This accomodates differences in layouts of structs.
-
-The only typically present quirk is what to do with sa_restorer.
-
- libc/sysdeps/linux/arm/sigaction.c
-
-if HAVE_SA_RESTORER and (sa_flags & SA_RESTORER) is not set,
-sets sa_restorer to
-(flags & SA_SIGINFO) ? __default_rt_sa_restorer : __default_sa_restorer,
-and sets SA_RESTORER,
-otherwise passes it as-is. Which is kinda strange, because AFAICS
-HAVE_SA_RESTORER is *not* defined for ARM.
-
- libc/sysdeps/linux/i386/sigaction.c
-
-Forcibly sets SA_RESTORER and sa_restorer:
-kact.sa_flags = act->sa_flags | SA_RESTORER;
-kact.sa_restorer = ((act->sa_flags & SA_SIGINFO) ? &restore_rt : &restore);
-
- libc/sysdeps/linux/x86_64/sigaction.c
-
-Forcibly sets SA_RESTORER and sa_restorer:
-kact.sa_flags = act->sa_flags | SA_RESTORER;
-kact.sa_restorer = &restore_rt;
-
- libc/sysdeps/linux/mips/sigaction.c
-
-# ifdef HAVE_SA_RESTORER
-# if _MIPS_SIM == _ABIO32
- kact.sa_restorer = act->sa_restorer;
-# else
- kact.sa_restorer = &restore_rt;
-# endif
-# endif
-No confusion here, HAVE_SA_RESTORER is #defined for MIPS
-
- libc/sysdeps/linux/avr32/sigaction.c
-
-if (kact.sa_flags & SA_RESTORER) {
- kact.sa_restorer = act->sa_restorer;
-} else {
- kact.sa_restorer = __default_rt_sa_restorer;
- kact.sa_flags |= SA_RESTORER;
-}
-Does not check HAVE_SA_RESTORER, but avr32 falls
-in "completely ordinary" category on both kernel and
-userspace sides, and those have it defined.
-
- libc/sysdeps/linux/xtensa/sigaction.c
-
-if (kact.sa_flags & SA_RESTORER) {
- kact.sa_restorer = act->sa_restorer;
-} else {
- kact.sa_restorer = __default_sa_restorer;
- kact.sa_flags |= SA_RESTORER;
-}
-Thus, similar to avr32.
-
- libc/signal/sigaction.c (i.e. the all other arches)
-
-# ifdef HAVE_SA_RESTORER
- kact.sa_restorer = act->sa_restorer;
-# endif
-Plain translation, just sa_restorer copy is protected
-by HAVE_SA_RESTORER #define check. Looks like here
-HAVE_SA_RESTORER will be undef'ed only for IA64,
-Alpha an HPPA.
-
-
- Proposed overhaul past 0.9.30
-
-Since we can define libc-side structures at will:
-make sigset_t and struct sigaction identical on kernel side and libc side
-within each arch. If arches do not need special handling of sa_restorer,
-then sigaction() can directly use passed struct sigaction as-is.
-Otherwise, a copy is still needed, although sigaction() might have
-just one struct kernel_sigaction on stack and use it both for passing
-data to kernel and for receiving it back. Might save a few bytes.
-
-To this effect:
-
-* Make sigset_t size match kernel side on all arches.
- This is easy since all arches have 64 signals and only MIPS has 128.
-
-* Modify libc/sysdeps/linux/$ARCH/bits/sigaction.h
- so that its struct sigaction matches kernel's. If sa_restorer
- field is present in libc but is missing in kernel_sigaction,
- add it at the bottom in order to not mess up kernel_sigaction layout.
-
-* Modify libc/sysdeps/linux/$ARCH/sigaction.c
- to implement the logic above. In "common" pseudo-arch
- (libc/signal/sigaction.c file),
- we would not even need to do any copying, as described above.
-
-* Document discovered arch quirks while debugging this mess.
-
-* struct old_kernel_sigaction can't be disposed of in a similar way,
- we need to have userspace struct sigaction unchanged regardless
- whether we use "old" or "new" kernel sigaction() syscall.
- It's moot anyway because "old" one is long unused, it's from
- pre-2.2 kernels.