From: Karl Berry Date: Sun, 19 Sep 2004 13:17:06 +0000 (+0000) Subject: skeleton manual X-Git-Tag: cvs-readonly~3947 X-Git-Url: http://erislabs.net/gitweb/?a=commitdiff_plain;h=2b41521150b0141c6bf6730f1820e78efc90e02a;p=gnulib.git skeleton manual --- diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..ff8974f15 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,15 @@ +# $Id: Makefile,v 1.1 2004-09-19 13:17:06 karl Exp $ +# Makefile for gnulib doc. +# Copyright (C) 2004 Free Software Foundation, Inc. +# +# Copying and distribution of this file, with or without modification, +# are permitted in any medium without royalty provided the copyright +# notice and this notice are preserved. + +doc = gnulib + +TEXI2HTML = $(MAKEINFO) --no-split --html +%.html: %.texi + $(TEXI2HTML) -o $@ $< + +all: $(doc).info $(doc).html $(doc).dvi diff --git a/doc/gnulib.texi b/doc/gnulib.texi new file mode 100644 index 000000000..36da884bc --- /dev/null +++ b/doc/gnulib.texi @@ -0,0 +1,205 @@ +\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 diff --git a/doc/xalloc.texi b/doc/xalloc.texi deleted file mode 100644 index 6cccedf11..000000000 --- a/doc/xalloc.texi +++ /dev/null @@ -1,39 +0,0 @@ -@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.