intro.3: Revise discussion
PATCH 9/9 intro.3: Revise discussion
* Recast introduction to discuss the purpose of section 3 as a whole instead of focussing solely on the standard C library.
* 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).
* Make crystal clear what Alex's new subsections are for.
Signed-off-by G. Branden Robinson <[email protected]>
--- man3/intro.3 | 67 +++++++++++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 32 deletions(-)
man3/intro.3 +35 -32
@@ -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
@@ -86,12 +86,15 @@ 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 +.TP 10n +.B 3const +Constants. +.TP +.B 3head +Header files. +.TP +.B 3type +Data types. .PP Ideally, a library for the C language
Signature · 1 line
2.30.2