Content: * 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. Style: * Tighten cross reference. It wastes words to tell people to look elsewhere "for more information". Why else would they look there? * Set introduction of a defined term in italics. * Use passive voice less. Markup: * Use `P` instead of `PP` paragraphing macro. --- man3/intro.3 | 92 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/man3/intro.3 b/man3/intro.3 index e85c0677a..3daabc2b6 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -7,37 +7,44 @@ .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). -.PP +(with one exception) +to the linker through the specification of an +.I \-l +flag, +documented in the page's \(lqLibrary\(rq section. +.P +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. +.P 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. -(Where required, these feature test macros must be defined before including +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 +must be defined before including .I any header files.) -In such cases, the required macro is described in the man page. -For further information on feature test macros, see -.BR feature_test_macros (7). +In such cases, +the required macro is described in the applicable man page. +See +.BR \%feature_test_macros (7). .\" .\" There .\" are various function groups which can be identified by a letter which @@ -65,19 +72,26 @@ For further information on feature test macros, see .\" Various special libraries. The manual pages documenting their functions .\" specify the library names. .SS Subsections -Section 3 of this manual is organized into subsections +The Linux +.I man-pages +organize section 3 into subsections that reflect the complex structure of the standard C library -and its many implementations: -.IP \(bu 3 -3const -.IP \(bu -3head -.IP \(bu -3type -.PP -This difficult history frequently makes it a poor example to follow -in design, implementation, and presentation. -.PP +and its many implementations. +.IR libc 's +difficult history frequently makes it a poor example to follow +in design, +implementation, +and presentation. +.TP 10n +.B 3const +Constants. +.TP +.B 3head +Header files. +.TP +.B 3type +Data types. +.P Ideally, a library for the C language is designed such that each header file -- 2.30.2
Attachment:
signature.asc
Description: PGP signature
