From: Owen Shepherd <owen.shepherd@e43.eu>
Date: Tue, 14 Aug 2012 14:54:36 +0000 (+0100)
Subject: (merge)
X-Git-Url: https://pd.if.org/git/?p=pdclib.old;a=commitdiff_plain;h=217a2f477ad6dbbac816981589ee2f5a81dffd67;hp=950d2e48042173a75188b0a2dbe219ed91ff47cf

(merge)
---

diff --git a/man/abort.3 b/man/abort.3
new file mode 100644
index 0000000..4062011
--- /dev/null
+++ b/man/abort.3
@@ -0,0 +1,52 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt abort 3
+.Os
+
+.Sh NAME
+.Nm abort
+.Nd abnormal process termination
+
+.Sh SYNOPSIS
+.In stdlib.h
+.Fn "noreturn void abort" "void"
+
+.Sh DESCRIPTION
+.Fn abort
+causes abnormal process termination to occur.
+
+.Pp
+First,
+.Dv SIGABRT
+will be raised, as if by
+.Fn raise SIGABRT .
+If the signal is not being caught, or the handler which catches the signal 
+returns, 
+.Fn abort
+will then proceed to cause the process to terminate with a failure exit status.
+It is implementation defined whether any open
+.Vt FILE
+streams are flushed before the process exits.
+
+.Sh IMPLEMENTATION NOTES
+PDCLib implements termination (in the case that the 
+.Dv SIGABRT
+handler returns) by calling
+.Fn _Exit EXIT_FAILURE .
+Therefore, stream flushing rules for
+.Nm
+follow those defined for
+.Fn _Exit .
+
+.Sh SEE ALSO
+.Xr exit 3
+.Xr quick_exit 3
+.Xr _Exit 3
+.Xr raise 3
+
+.Sh STANDARDS
+.Fn abort
+is first defined in
+.St -isoC-90 .
\ No newline at end of file
diff --git a/man/assert.3 b/man/assert.3
new file mode 100644
index 0000000..d2874e3
--- /dev/null
+++ b/man/assert.3
@@ -0,0 +1,43 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt assert 3
+.Os
+
+.Sh NAME
+.Nm assert
+.Nd validate assertion
+
+.Sh SYNOPSIS
+.In assert.h
+.Fn "void assert" "<scalar expression>"
+
+.Sh DESCRIPTION
+If
+.Dv NDEBUG
+was defined when
+.In assert.h
+was last included, the macro
+.Nm
+results in no code being generated. Otherwise, if the expression evaluates to 
+false, an error message is printed to 
+.Va stderr
+and execution is terminated by invoking
+.Fn abort .
+.Sh IMPLEMENTATION NOTES
+The enclosing function of the call to
+.Nm
+will only be printed in the error message when compiling for C99, or a later
+revision of the C standard. 
+
+.Sh SEE ALSO
+.Xr _Exit 3
+.Xr quick_exit 3
+.Xr exit 3
+.Xr abort 3
+
+.Sh STANDARDS
+Conforming to
+.St -isoC-90 ,
+.St -isoC-99 .
\ No newline at end of file
diff --git a/man/assert.h.3 b/man/assert.h.3
new file mode 100644
index 0000000..1a532fa
--- /dev/null
+++ b/man/assert.h.3
@@ -0,0 +1,39 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt ASSERT.H 3
+.Os
+.\"
+.Sh NAME
+.Nm assert.h
+.Nd verify program assertion
+.\"
+.Sh SYNOPSIS
+.In assert.h
+.\"
+.Sh DESCRIPTION
+The header
+.In assert.h
+shall define one macro:
+.Dv assert(<scalar expression>) .
+.Pp
+If
+.Dv NDEBUG
+was undefined at the most recent inclusion of this header, then it shall be
+defined as a macro which will evaluate the scalar expression and, if it is
+false, abort the program with a descriptive error message as defined in
+.Xr assert 3 .
+.\"
+.Pp
+If
+.Dv NDEBUG
+was defined at the most recent inclusion of this header, then it shall be
+defined as a macro which evaluates as a void expression and
+.Sy does not
+evaluate its parameter.
+.\"
+.Sh STANDARDS
+Conforming to
+.St -isoC-90 ,
+.St -isoC-99 .
\ No newline at end of file
diff --git a/man/atexit.3 b/man/atexit.3
new file mode 100644
index 0000000..a210266
--- /dev/null
+++ b/man/atexit.3
@@ -0,0 +1,100 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt atexit 3
+.Os
+
+.Sh NAME
+.Nm atexit
+.Nd registration of functions to be invoked before process termination
+
+.Sh SYNOPSIS
+.In stdlib.h
+.Fn "int atexit" "void (*handler)(void)"
+.Fn "int at_quick_exit" "void (*handler)(void)" 
+(C11, C++11)
+
+.Sh DESCRIPTION
+These functions register a function to be called when the corresponding process
+exit function is invoked. For
+.Fn atexit 
+the function will be invoked when the process is terminated by calling
+.Fn exit ;
+for
+.Fn at_quick_exit
+the function will be invoked when the process is terminated by calling
+.Fn quick_exit .
+
+.Pp
+These functions are used in order to permit a program to perform actions before
+a process is terminated; for example, releasing an interprocess semaphore. 
+Special care should be taken when writing 
+.Fn at_quick_exit
+handlers; the purpose of 
+.Fn quick_exit
+is to support the abandonning of a process when normal process termination might
+not be possible; at_quick_exit handlers should therefore be used sparingly and
+only when their use is essential.
+
+.Pp
+The standard guarantees that 
+.Fn atexit
+and
+.Fn at_quick_exit
+may each be called at least 32 times successfully.
+
+.Pp
+.Fn atexit 
+and
+.Fn at_quick_exit
+handlers are called in reverse order of the order they were registered in. For
+precise details of their ordering, see
+.Xr exit 3 .
+
+.Pp
+The result of exiting from a handler registered with
+.Fn atexit
+or
+.Fn at_quick_exit
+by use of 
+.Fn longjmp
+is undefined. If any function or destructor invoked by
+.Fn exit
+or
+.Fn quick_exit
+should throw, 
+.Fn std::terminate
+is invoked.
+
+.Pp
+Undefined behaviour results if an 
+.Fn atexit
+or
+.Fn at_quick_exit
+handler calls
+.Fn exit
+or
+.Fn quick_exit . 
+
+.Sh RETURN VALUES
+Returns 0 to indicate success; nonzero returns indicate failure.
+
+.Sh ERRORS
+No errors are defined
+
+.Sh SEE ALSO
+.Xr abort 3
+.Xr exit 3
+.Xr quick_exit 3
+.Xr _Exit 3
+
+.Sh STANDARDS
+.Fn atexit
+is first defined in
+.St -isoC-90 ;
+.Fn at_quick_exit
+was introduced in
+.St -isoC-2011 
+and
+ISO/IEC 14882:2011 "C++ 2011" .
\ No newline at end of file
diff --git a/man/exit.3 b/man/exit.3
new file mode 100644
index 0000000..ac8ae99
--- /dev/null
+++ b/man/exit.3
@@ -0,0 +1,119 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt exit 3
+.Os
+
+.Sh NAME
+.Nm exit
+.Nd terminates the process
+
+.Sh SYNOPSIS
+.In stdlib.h
+.Fn "noreturn void exit" "int status"
+.Fn "noreturn void quick_exit" "int status"
+.Fn "noreturn void _Exit" "int exitcode"
+
+.Sh DESCRIPTION
+Calling any of these three functions terminates the current process, returning 
+the exit code passed as a parameter. The interpretation of the exit code is 
+undefined, except that 0 or
+.Dv EXIT_SUCCESS
+shall indicate successful completion and
+.Dv EXIT_FAILURE
+shall indicate a non-successful completion.
+
+.Pp
+.Fn exit
+first destroys all objects with C++ thread local storage duration (the C 
+standard leaves whether or not thread local objects are destroyed or not 
+undefined). Next, the destructors of all C++ objects of static storage duration 
+are invoked along with all functions passed to
+.Fn atexit 
+in reverse order of registration (the time of registration for C++ objects of 
+static storage duration is taken to be the time at which the constructor 
+completes). It then flushes all open
+.Vt FILE
+streams with unwritten data and closes them. Finally, files created by
+.Fn tmpfile
+are removed, before handing control back to the host environment. Note in 
+particular that functions registered with
+.Fn at_quick_exit
+are
+.Sy not
+called.
+
+.Pp
+.Fn quick_exit
+invokes any functions registered with
+.Fn at_quick_exit
+in reverse order of registration, then returns control to the host 
+environment by calling
+.Fn _Exit .
+No signal handlers are called, nor are any functions registered with
+.Fn atexit .
+
+.Pp
+.Fn _Exit
+returns control to the controlling environment without invoking any functions
+registered by
+.Fn atexit ,
+.Fn at_quick_exit ,
+any signal handlers, or the destructors of any thread local objects or C++ 
+objects of static storage duration. Whether or not any open 
+.Vt FILE
+streams with unwritten data are flushed or not is undefined.
+
+.Pp
+The result of aborting a call to 
+.Fn exit
+or
+.Fn quick_exit
+by use of 
+.Fn longjmp
+is undefined. If any function or destructor invoked by
+.Fn exit
+or
+.Fn quick_exit
+should throw, 
+.Fn std::terminate
+is invoked.
+
+.Pp
+Undefined behaviour results if, while a call to
+.Fn exit
+or
+.Fn quick_exit
+is in progress, a call to 
+.Fn exit
+or
+.Fn quick_exit
+is made. 
+
+.Sh IMPLEMENTATION NOTES
+PDCLib implements the process of flushing streams in
+.Fn _Exit ,
+and therefore
+.Fn exit
+calls it after all
+.Fn atexit
+handlers have been invoked.
+
+.Sh SEE ALSO
+.Xr abort 3
+.Xr atexit 3
+.Xr at_quick_exit 3
+
+.Sh STANDARDS
+.Fn exit
+is first defined in
+.St -isoC-90 ;
+.Fn _Exit
+was introduced in
+.St -isoC-99 .
+.Fn quick_exit
+was introduced in
+.St -isoC-11 
+and
+ISO/IEC 14882:2011 "C++ 2011" .
\ No newline at end of file
diff --git a/man/pdclib.3 b/man/pdclib.3
new file mode 100644
index 0000000..f0f90a4
--- /dev/null
+++ b/man/pdclib.3
@@ -0,0 +1,95 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt PDCLIB 3
+.Os
+
+.Sh NAME
+.Nm PDCLib
+.Nd Public domain, portable C library
+
+.Sh LIBRARY
+.Lb pdclib
+.Sh SYNOPSIS
+.In assert.h
+.In ctype.h
+.In errno.h
+.In inttypes.h
+.In iso646.h
+.In limits.h
+.In locale.h
+.In signal.h
+.In stdarg.h
+.In stdbool.h
+.In stddef.h
+.In stdint.h
+.In stdio.h
+.In stdlib.h
+.In stdnoreturn.h
+.In string.h
+.In threads.h
+.In time.h
+
+.Sh DESCRIPTION
+The
+.Nm
+library is a portable, public domain C library. It aims at full conformance with
+ISO C89, C95, C99 and C11 when used in combination with a conformant compiler. 
+In addition, it aims at conformance with the portion of ISO C++97 and C++2011 
+which is derived from said standards.
+.Pp
+.Nm
+aims for strict conformance with the selected C/C++ standard. Therefore, unlike
+most C libraries, it does not by default expose any extensions. Some extensions
+(from POSIX or the Single Unix Specification) can be selected by defining the 
+appropriate feature selection macro, such as 
+.Dv _POSIX_C_SOURCE
+or
+.Dv _XOPEN_SOURCE
+to the appropriate value. For example, in the following definition:
+.Bd -offset indent
+.Sy #define _XOPEN_SOURCE || _POSIX_C_SOURCE >= 200809L
+.br
+.Sy #include
+.In string.h
+.br
+.Fn "char * strdup" "const char *"
+.Ed
+
+it is documented that defining either 
+.Dv _XOPEN_SOURCE
+or
+.Dv _POSIX_C_SOURCE
+to have a value greater than
+.Li 200809L
+before the first inclusion of
+.In string.h
+will expose a definition of the function
+.Fn strdup
+
+.Sh SEE ALSO
+.Xr cc 1 ,
+.Xr c++ 7
+.Sh STANDARDS
+When compiled with a C compiler, conformant with 
+.St -isoC-90 ,
+.St -isoC-amd1 ,
+.St -isoC-tcor1 ,
+.St -isoC-tcor2 ,
+.St -isoC-99 or
+.St -isoC-2011
+as dependent upon the version of C the compiler declares conformance with.
+.Pp
+When compiled with a C++ compiler, conformant with ISO/IEC 14882:1997 or ISO/IEC
+14882:2011 "The C++ Programming Language" as dependent upon the version of C++
+the compiler declares conformance with.
+.Sh AUTHORS
+The
+.Nm
+library is maintained by by
+.An Owen Shepherd ,
+.Mt pdclib@owenshepherd.net .
+Based upon work by
+.An Martin "Solar" Baute ,
+.Mt solar@rootdirectory.de .
diff --git a/man/strdup.3 b/man/strdup.3
new file mode 100644
index 0000000..8ac67e0
--- /dev/null
+++ b/man/strdup.3
@@ -0,0 +1,59 @@
+.\" This file is part of the Public Domain C Library (PDCLib).
+.\" Permission is granted to use, modify, and / or redistribute at will.
+.\"
+.Dd
+.Dt strdup 3
+.Os
+
+.Sh NAME
+.Nm strdup
+.Nd string duplication
+
+.Sh SYNOPSIS
+.Sy #define _XOPEN_SOURCE || _POSIX_C_SOURCE >= 200809L
+.In string.h
+.Fn "char *strdup" "const char *str"
+.Pp
+.Sy #define _POSIX_C_SOURCE >= 200809L
+.In string.h
+.Fn "char *strndup" "const char *str" "size_t len"
+
+.Sh DESCRIPTION
+.Fn strdup
+allocates a new buffer of sufficient size as to be able to hold the entirety of
+.Va str ,
+including the terminating character, and copies the contents of
+.Va str
+into it.
+
+.Pp
+.Fn strndup
+allocates a buffer large enough to contain
+.Va len
+characters, plus a trailing null character, or sufficient to contain the 
+entirety of
+.Va str
+including the trailing null character, whichever is smaller. The first 
+.Va len
+characters of 
+.Va str
+are then copied into it, and a null character appended.
+
+.Pp
+The buffers returned by these functions must be released by a call to
+.Fn free .
+
+.Sh SEE ALSO
+.Xr free 3
+.Xr malloc 3
+.Xr strcpy 3
+.Xr strncpy 3
+
+.Sh STANDARDS
+.Fn strdup
+first specified in 
+.St -xpg3 .
+Moved into POSIX, and
+.Fn strndup
+added, with
+.St -p1003.1-2008 .
\ No newline at end of file