--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@comment $Id: gnulib.texi,v 1.1 2004-09-19 13:17:06 karl Exp $
+@comment %**start of header
+@setfilename gnulib.info
+@settitle GNU Gnulib
+@syncodeindex pg cp
+@syncodeindex fn cp
+@comment %**end of header
+
+@set UPDATED $Date: 2004-09-19 13:17:06 $
+
+@copying
+This manual is for GNU Gnulib (updated @value{UPDATED}),
+which is a library of common routines intended to be shared at the
+source level.
+
+Copyright @copyright{} 2004 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory Software development
+@direntry
+* gnulib: (gnulib). Source files to share among distributions.
+@end direntry
+
+@titlepage
+@title GNU Gnulib
+@subtitle updated @value{UPDATED}
+@author @email{bug-gnulib@@gnu.org}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU Gnulib
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Gnulib::
+* Invoking gnulib-tool::
+* Copying This Manual::
+* Index::
+@end menu
+
+
+@node Gnulib
+@chapter Gnulib
+
+This is not a real manual. It's just a place to store random notes
+until someone (you?) gets around to actually writing a manual.
+
+Getting started:
+
+@itemize
+@item Gnulib is hosted at Savannah:
+ @url{http://savannah.gnu.org/projects/gnulib}. Get the sources
+ through CVS from there.
+@item The Gnulib home page:
+ @url{http://www.gnu.org/software/gnulib/}.
+@end itemize
+
+@menu
+* Comments::
+* ctime::
+* inet_ntoa::
+* Out of memory handling::
+@end menu
+
+@node Comments
+@section Comments
+
+@cindex comments describing functions
+@cindex describing functions, locating
+Where to put comments describing functions: Because of risk of
+divergence, we prefer to keep most function describing comments in
+only one place: just above the actual function definition. Some
+people prefer to put that documentation in the .h file. In any case,
+it should appear in just one place unless you can ensure that the
+multiple copies will always remain identical.
+
+
+@node ctime
+@section ctime
+@findex ctime
+
+The @code{ctime} function need not be reentrant, and consequently is
+not required to be thread safe. Implementations of @code{ctime}
+typically write the time stamp into static buffer. If two threads
+call @code{ctime} at roughly the same time, you might end up with the
+wrong date in one of the threads, or some undefined string. There is
+a re-entrant interface @code{ctime_r}, that take a pre-allocated
+buffer and length of the buffer, and return @code{NULL} on errors.
+The input buffer should be at least 26 bytes in size. The output
+string is locale-independent. However, years can have more than 4
+digits if @code{time_t} is sufficiently wide, so the length of the
+required output buffer is not easy to determine. Increasing the
+buffer size when @code{ctime_r} return @code{NULL} is not necessarily
+sufficient. The @code{NULL} return value could mean some other error
+condition, which will not go away by increasing the buffer size.
+
+A more flexible function is @code{strftime}. However, note that it is
+locale dependent.
+
+
+@node inet_ntoa
+@section inet_ntoa
+@findex inet_ntoa
+
+The @code{inet_ntoa} function need not be reentrant, and consequently
+is not required to be thread safe. Implementations of
+@code{inet_ntoa} typically write the time stamp into static buffer.
+If two threads call @code{inet_ntoa} at roughly the same time, you
+might end up with the wrong date in one of the threads, or some
+undefined string. Further, @code{inet_ntoa} is specific for
+@acronym{IPv4} addresses.
+
+A protocol independent function is @code{inet_ntop}.
+
+
+@node Out of memory handling
+@section Out of memory handling
+
+@cindex Out of Memory handling
+@cindex Memory allocation failure
+The GSS API does not have a standard error code for the out of memory
+error condition. Instead of adding a non-standard error code, this
+library has chosen to adopt a different strategy. Out of memory
+handling happens in rare situations, but performing the out of memory
+error handling after almost all API function invocations pollute your
+source code and might make it harder to spot more serious problems.
+The strategy chosen improve code readability and robustness.
+
+@cindex Aborting execution
+For most applications, aborting the application with an error message
+when the out of memory situation occur is the best that can be wished
+for. This is how the library behaves by default.
+
+@vindex xalloc_fail_func
+However, we realize that some applications may not want to have the
+GSS library abort execution in any situation. The GSS library support
+a hook to let the application regain control and perform its own
+cleanups when an out of memory situation has occured. The application
+can define a function (having a @code{void} prototype, i.e., no return
+value and no parameters) and set the library variable
+@code{xalloc_fail_func} to that function. The variable should be
+declared as follows.
+
+@example
+extern void (*xalloc_fail_func) (void);
+@end example
+
+The GSS library will invoke this function if an out of memory error
+occurs. Note that after this the GSS library is in an undefined
+state, so you must unload or restart the application to continue call
+GSS library functions. The hook is only intended to allow the
+application to log the situation in a special way. Of course, care
+must be taken to not allocate more memory, as that will likely also
+fail.
+
+
+@node Invoking gnulib-tool
+@chapter Invoking gnulib-tool
+
+@pindex gnulib-tool
+@cindex invoking @command{gnulib-tool}
+
+Run @samp{gnulib-tool --help}, and use the source.
+@command{gnulib-tool} is the way to import Gnulib modules.
+
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License:: License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+++ /dev/null
-@node Out of Memory handling
-@section Out of Memory handling
-
-@cindex Out of Memory handling
-@cindex Memory allocation failure
-The GSS API does not have a standard error code for the out of memory
-error condition. Instead of adding a non-standard error code, this
-library has chosen to adopt a different strategy. Out of memory
-handling happens in rare situations, but performing the out of memory
-error handling after almost all API function invocations pollute your
-source code and might make it harder to spot more serious problems.
-The strategy chosen improve code readability and robustness.
-
-@cindex Aborting execution
-For most applications, aborting the application with an error message
-when the out of memory situation occur is the best that can be wished
-for. This is how the library behaves by default.
-
-@vindex xalloc_fail_func
-However, we realize that some applications may not want to have the
-GSS library abort execution in any situation. The GSS library support
-a hook to let the application regain control and perform its own
-cleanups when an out of memory situation has occured. The application
-can define a function (having a @code{void} prototype, i.e., no return
-value and no parameters) and set the library variable
-@code{xalloc_fail_func} to that function. The variable should be
-declared as follows.
-
-@example
-extern void (*xalloc_fail_func) (void);
-@end example
-
-The GSS library will invoke this function if an out of memory error
-occurs. Note that after this the GSS library is in an undefined
-state, so you must unload or restart the application to continue call
-GSS library functions. The hook is only intended to allow the
-application to log the situation in a special way. Of course, care
-must be taken to not allocate more memory, as that will likely also
-fail.
projects / pspp / commitdiff