* Recast introduction to discuss the purpose of section 3 as a whole instead of focussing solely on the standard C library. * Provide historical context for usage of subsections in section 3. Resurrect information from comments, in rewritten form, of section 3 subsections, so as to contrast them with the current approach developed by Alex. Be even more emphatic that those documenting other C libraries should not mess with subsections. * Explain basic principles of usage of any C library to the novice. (This page _is_ called "intro".) * Drop material about organization of glibc, now moved to libc(7). Signed-off-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> --- man3/intro.3 | 122 +++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 63 deletions(-) diff --git a/man3/intro.3 b/man3/intro.3 index bbaef525e..f5a47b566 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -7,34 +7,34 @@ .SH NAME intro \- introduction to library functions .SH DESCRIPTION -Section 3 of the manual describes all library functions -excluding the library functions -(system call wrappers) -described in Section 2, -which implement system calls. -.PP -Many of the functions described in the section are part of the -Standard C Library -.RI ( libc ). -Some functions are part of other libraries -(e.g., -the math library, -.IR libm , -or the real-time library, -.IR librt ) -in which case the manual page will indicate -the linker option needed to link against the required library -(e.g., -.I \-lm +Section 3 of the manual describes library functions +generally useful to programmers, +excluding the system calls described in section 2. +Use of a C\~language library entails two requirements: +its symbol names must be exposed to the compiler +through the inclusion of a +.IR "header file" , +presented at the beginning of a man page's \(lqSynopsis\(rq section; and -.IR \-lrt , -respectively, -for the aforementioned libraries). +(with one exception) +to the linker through the specification of an +.I \-l +flag, +documented in the page's \(lqLibrary\(rq section. +.PP +Many of the functions described are part of the Standard C Library +(see +.BR libc (7)). +C\~linkers link with +.I libc +implicitly by default; +an +.I \-lc +option is redundant. .PP -In some cases, -the programmer must define a feature test macro in order to obtain -the declaration of a function from the header file specified -in the man page SYNOPSIS section. +Sometimes, +the programmer must define a C\~preprocessor macro +to access the declaration of a symbol from a header file. (Where required, these .I feature test macros @@ -45,54 +45,50 @@ In such cases, the relevant function's man page describes the required macro. See .BR feature_test_macros (7). -.\" -.\" There -.\" are various function groups which can be identified by a letter which -.\" is appended to the chapter number: -.\" .IP (3C) -.\" These functions, -.\" the functions from chapter 2 and from chapter 3S are -.\" contained in the C standard library libc, -.\" which will be used by -.\" .BR cc (1) -.\" by default. -.\" .IP (3S) -.\" These functions are parts of the -.\" .BR stdio (3) -.\" library. They are contained in the standard C library libc. -.\" .IP (3M) -.\" These functions are contained in the arithmetic library libm. They are -.\" used by the -.\" .BR f77 (1) -.\" FORTRAN compiler by default, -.\" but not by the -.\" .BR cc (1) -.\" C compiler, -.\" which needs the option \fI\-lm\fP. .\" .IP (3F) .\" These functions are part of the FORTRAN library libF77. There are no .\" special compiler flags needed to use these functions. -.\" .IP (3X) -.\" Various special libraries. The manual pages documenting their functions -.\" specify the library names. .SS Subsections +In Unix systems circa 1980, +section 3 of the programmer's manual documented +.I libc +functions in subsections; +.\" V7 (1979-01) used an unsuffixed "3"; System III (1980-06) used 3C. +.\" BSD at first ignored this shift; it is not seen in 3BSD (late 1979) +.\" or 4BSD (1980-11), but both conventions are documented in 4.1cBSD's +.\" intro(3) (1983-04). +\(lq3C\(rq was used for most, +with +\(lq3M\(rq for those from the math library, +and +\(lq3S\(rq for the standard I/O package. +\(lq3X\(rq was reserved for \(lqvarious specialized libraries\(rq. +.PP The Linux .I man-pages -organize section 3 into subsections -that reflect the complex structure of the standard C library -and its many implementations. +project prefers to employ subsections differently, +recognizing that the many constants, +data types, +and header file names +defined by +.I libc +are as important as the names of its functions. +.TP 10n +.B 3const +Constants. +.TP +.B 3head +Header files. +.TP +.B 3type +Data types. +.PP +We discourage use of these subsections to document any other library. .IR libc 's difficult history frequently makes it a poor example to follow in design, implementation, and presentation. -.IP \(bu 3 -3const -.IP \(bu -3head -.IP \(bu -3type -.PP Ideally, a library for the C language is designed such that each header file -- 2.30.2
Attachment:
signature.asc
Description: PGP signature
