From: Keith Marshall Date: Sat, 11 Apr 2020 19:58:43 +0000 (+0100) Subject: Manpage stylistic consistency updates. X-Git-Tag: wsl-5.3.1-release~3 X-Git-Url: http://git.osdn.net/view?p=mingw%2Fmingw-org-wsl.git;a=commitdiff_plain;h=45437ae46ecd1f4f82758b394771420ddca71062 Manpage stylistic consistency updates. --- diff --git a/mingwrt/ChangeLog b/mingwrt/ChangeLog index b815907..716810f 100644 --- a/mingwrt/ChangeLog +++ b/mingwrt/ChangeLog @@ -1,3 +1,10 @@ +2020-04-11 Keith Marshall + + Manpage stylistic consistency updates. + + * man/dirname.3.man man/getline.3.man: Miscellaneous stylistic + formatting changes. + 2020-04-08 Keith Marshall Ensure PDF manpages are generated from local sources. diff --git a/mingwrt/man/dirname.3.man b/mingwrt/man/dirname.3.man index 99926e5..98e44fd 100644 --- a/mingwrt/man/dirname.3.man +++ b/mingwrt/man/dirname.3.man @@ -1,6 +1,6 @@ '\" t .\" vim: ft=nroff -.TH %PAGEREF% MinGW "Programmer's Reference Manual" +.TH %PAGEREF% MinGW "MinGW Programmer's Reference Manual" . .SH NAME . @@ -48,16 +48,16 @@ Additionally, if the .I second character of -.I path +.I \%path is a colon .RB (\(dq : \(dq), the first two characters of -.I path +.I \%path are interpreted as an MS\-Windows drive designator, which will be included in the .B directory name component of -.IR path , +.IR \%path , but is never considered to form part of the .B file name component. @@ -66,13 +66,13 @@ component. In normal usage, .BR \%dirname () returns a pointer to a string representing the path name component of -.IR path , +.IR \%path , up to but not including the rightmost directory separator, while .BR \%basename () returns a pointer to the component following this separator. Any trailing directory separators present in -.I path +.I \%path are disregarded, when determining the rightmost separator, and, in the case of the return value from @@ -82,7 +82,7 @@ are each reduced to a single such character. . .PP If -.I path +.I \%path contains no MS\-Windows drive designator, and no directory separator character, then @@ -92,9 +92,9 @@ returns the string and .BR \%basename () returns a copy of -.IR path. +.IR \%path. If -.I path +.I \%path does commence with an MS\-Windows drive designator, but contains no directory separators, then @@ -107,14 +107,14 @@ represents the drive designator, while .BR \%basename () returns a copy of -.IR path , +.IR \%path , with its initial two characters, (i.e.\ the drive designator), deleted. . .PP If -.I path +.I \%path is a NULL pointer, or is a pointer to an empty string, then both @@ -126,7 +126,7 @@ return the string . .PP If -.I path +.I \%path is the string .RB \(dq / \(dq, or the string @@ -143,7 +143,7 @@ respectively. . .PP If -.I path +.I \%path commences with .I exactly two directory separator characters, @@ -156,13 +156,13 @@ This construct does not affect the string returned by neither is this behaviour replicated by .BR \%dirname (), if -.I path +.I \%path includes an MS\-Windows drive designator. . .PP In the special case, where -.I path +.I \%path is specified as .I exactly two identical directory separator characters, @@ -170,7 +170,7 @@ with no MS\-Windows drive designator, and no following path name, .BR \%dirname () returns -.I path +.I \%path unchanged; .BR \%basename () normalises the return string to only a single character, @@ -179,7 +179,7 @@ either or .RB \(dq \e \(dq, matching the characters used to specify -.IR path . +.IR \%path . . .PP Concatenating the string returned by @@ -222,7 +222,7 @@ the test program defines the following function:\(em . .PP .RS -.nf +.EX #include #include #include @@ -238,7 +238,7 @@ void result( char *path ) free( dir ); free( file ); } -.fi +.EE .RE .PP This illustrates the correct use of the @@ -247,14 +247,14 @@ and the .BR \%basename () functions, with copies of the original -.I path +.I \%path string being passed in the function calls. Note that the return values from each function are used immediately, in the -.BR printf () +.BR \%printf () call, and the temporary copies of -.I path +.I \%path are discarded, and the associated memory is freed, before these go out of scope. @@ -373,7 +373,7 @@ The .BR \%dirname () function returns a pointer to a null terminated string, which represents the directory path component of the passed -.I path +.I \%path string, without any trailing directory separator character, and with all internal sequences of directory separator characters @@ -385,13 +385,13 @@ The function returns a pointer to a null terminated string, which represents the rightmost element of the passed -.I path +.I \%path string, with all trailing directory separator characters removed. . .PP If any MS\-Windows drive designator is specified in the input -.I path +.I \%path string, it is included in the return value of the .BR \%dirname () @@ -413,10 +413,10 @@ The and .BR \%basename () functions may modify the -.I path +.I \%path string passed to them. Therefore, it is an error to pass a character constant as the -.I path +.I \%path parameter; to do so may result in memory violation errors, (segmentation faults), @@ -424,14 +424,14 @@ and consequent abnormal program termination. .PP Also note that, since the -.I path +.I \%path argument may be modified by the .BR \%dirname () or the .BR \%basename () function call, if you wish to preserve the original content of -.IR path , +.IR \%path , you should pass a copy to the function. Furthermore, either function may return its result in a statically allocated buffer, @@ -443,13 +443,13 @@ and .BR \%basename () functions parse path name strings, they are basically just -.I string +.I \%string functions. The presence of an MS\-Windows drive designator is determined by the appearance of a colon .RB (\(dq : \(dq) as the second character of the -.I path +.I \%path string, but neither function performs any check to ensure that the first character represents a valid file system device; @@ -461,7 +461,8 @@ represents a valid path name. .SH AUTHOR . This manpage was written by \%Keith\ Marshall, -\%, to document the +\%, +to document the .BR \%basename () and .BR \%dirname () @@ -469,7 +470,7 @@ functions as they have been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by -the original author remains unchanged. +the original author remains in place. . . .\" EOF diff --git a/mingwrt/man/getline.3.man b/mingwrt/man/getline.3.man index b33bb4f..4bf71ca 100644 --- a/mingwrt/man/getline.3.man +++ b/mingwrt/man/getline.3.man @@ -1,5 +1,5 @@ .\" vim: ft=nroff -.TH %PAGEREF% MinGW "Programmer's Reference Manual" +.TH %PAGEREF% MinGW "MinGW Programmer's Reference Manual" . .SH NAME .BR getline ,\0 getdelim @@ -28,8 +28,7 @@ .BI * stream .B ); . -.PP -.in -4n +.IP \& -4n Feature Test Macro Requirements for libmingwex: .TP 4 .BR getdelim (),\~ getline (): @@ -41,52 +40,52 @@ Available since libmingwex version 3.22: . .SH DESCRIPTION The -.BR getdelim () +.BR \%getdelim () function reads data from -.IR stream , +.IR \%stream , until either a character entity matching -.IR delim , +.IR \%delim , or .I EOF is encountered; the data so read, including the -.I delim +.I \%delim character if present, is stored into the buffer referenced by the pointer at .B *\c -.IR linebuf , +.IR \%linebuf , and is .I NUL terminated. .PP The -.BR getline () +.BR \%getline () function is a special case of -.BR getdelim (), +.BR \%getdelim (), with the -.I delim +.I \%delim argument implicitly specified as the POSIX newline character, .IR '\en' . . .PP The -.I linebuf +.I \%linebuf argument must be a reference to a pointer which is safe to pass to -.BR free (); +.BR \%free (); either a -.I NULL +.I \%NULL pointer, or a pointer to a buffer of size as indicated by .B *\c .IR n , allocated by -.BR malloc (). +.BR \%malloc (). Passing a value of -.I NULL +.I \%NULL in .B *\c -.IR linebuf , +.IR \%linebuf , with a value of zero in .B *\c .IR n , @@ -96,7 +95,7 @@ of a default buffer. . .PP The -.I delim +.I \%delim argument is specified as an .BR int ; it must be passed a value which is representable as an @@ -108,21 +107,21 @@ otherwise the behaviour is undefined. If .BI * linebuf is initially passed as a -.I NULL +.I \%NULL pointer, then -.BR getdelim () +.BR \%getdelim () or -.BR getline () +.BR \%getline () will call -.BR malloc (), +.BR \%malloc (), in an attempt to allocate .BI * n bytes, or an arbitrarily sized smaller default buffer, if such an allocation is not achievable. In either case, -.BI * linebuf +.BI \%* linebuf and .BI * n will be updated to reflect the allocated buffer location, @@ -132,11 +131,11 @@ and the actual size allocated. If, at any time during collection of the input record, the buffer referenced by -.BI * linebuf +.BI \%* linebuf becomes too small to store the record, it will be expanded as necessary, and both -.BI * linebuf +.BI \%* linebuf and .BI * n will be adjusted to reflect the change in allocation. @@ -145,14 +144,14 @@ will be adjusted to reflect the change in allocation. .SH RETURN VALUE . On successful completion, -.BR getline () +.BR \%getline () and -.BR getdelim () +.BR \%getdelim () return the number of characters stored into the buffer at .B *\c -.IR linebuf , +.IR \%linebuf , including the -.I delim +.I \%delim character if this was encountered before .IR EOF , but excluding the terminating @@ -162,22 +161,22 @@ character. .PP If no characters were read, and -.I stream +.I \%stream is at end-of-file, -.BR getline () +.BR \%getline () and -.BR getdelim () +.BR \%getdelim () return \(mi1, and the end-of-file indicator is set for -.IR stream . +.IR \%stream . . .PP If an error occurs, -.BR getline () +.BR \%getline () and -.BR getdelim () +.BR \%getdelim () set -.IR errno , +.IR \%errno , as indicated under the heading .B ERROR CONDITIONS below, @@ -186,95 +185,100 @@ and return \(mi1. . .SH ERROR CONDITIONS . -.BR getline () +.BR \%getline () and -.BR getdelim +.BR \%getdelim may fail for any of the reasons described as failure conditions for -.BR fgetc (); +.BR \%fgetc (); when any such error occurs, -.I errno +.I \%errno is left as set by -.BR fgetc (), +.BR \%fgetc (), and -.BR getline () +.BR \%getline () or -.BR getdelim () +.BR \%getdelim () returns \(mi1. . .PP In addition to -.BR fgetc () +.BR \%fgetc () failure conditions, -.BR getline () +.BR \%getline () and -.BR getdelim () +.BR \%getdelim () may fail, returning \(mi1 after setting -.I errno +.I \%errno to indicate occurrence of any of the following errors: . .RS 4 .TP 10 -.B EINVAL -.I linebuf +.B \%EINVAL +.I \%linebuf or .I n is -.IR NULL . +.IR \%NULL . . .TP 10 .B EBADF -.I stream +.I \%stream is a -.I NULL +.I \%NULL pointer, or otherwise is not a valid stream opened for reading, as determined by -.BR fgetc (). +.BR \%fgetc (). . .TP 10 .B ENOMEM An attempt to allocate a buffer, or to expand the buffer referenced by .B * -.IR linebuf , +.IR \%linebuf , was unsuccessful. . .TP 10 .B ERANGE More than -.B SSIZE_MAX +.B \%SSIZE_MAX characters were read, without finding -.IR delim . -(Note that POSIX specifies that +.IR \%delim . +(Note that +.B \%POSIX.1 +specifies that .I errno should be set to -.B EOVERFLOW +.B \%EOVERFLOW for this error condition; see heading .B CAVEATS AND BUGS below, for the rationale for the use of -.B ERANGE +.B \%ERANGE in this implementation). .RE . . -.SH CONFORMING TO +.SH STANDARDS CONFORMANCE . Originally implemented as GNU extension functions, both -.BR getline () +.BR \%getline () and -.BR getdelim () -were adopted into POSIX.1-2008; -implementations conforming to this POSIX standard have been -integrated into libmingwex from version 3.22 onwards. +.BR \%getdelim () +were adopted into +.BR \%POSIX.1\(hy2008 ; +implementations conforming to this +.B \%POSIX.1 +standard have been integrated into libmingwex +from version 3.22 onwards. . . .SH EXAMPLE -.nf +.EX #include #include @@ -297,62 +301,63 @@ int main () fclose (fp); return 0; } -.fi +.EE . . .SH CAVEATS AND BUGS . A return value of \(mi1 may indicate that -.I stream +.I \%stream is already at end-of-file when -.BR getline () +.BR \%getline () or -.BR getdelim () +.BR \%getdelim () is called, or it may indicate an error condition; use -.BR ferror () +.BR \%ferror () or -.BR feof () +.BR \%feof () to distinguish error and end-of-file conditions. . .PP The return type of -.I ssize_t +.I \%ssize_t can accommodate a maximum character count of -.BR SSIZE_MAX , +.BR \%SSIZE_MAX , and thus, the return value will overflow if -.BR getline () +.BR \%getline () or -.BR getdelim () +.BR \%getdelim () reads -.B SSIZE_MAX +.B \%SSIZE_MAX characters without encountering a line delimiter; for this overflow condition, -POSIX.1-2008 stipulates an +.B \%POSIX.1\(hy2008 +stipulates an .I errno condition code of -.B EOVERFLOW . +.B \%EOVERFLOW . However, MSVCRT.DLL provides no significant interpretation for an arbitrarily assigned -.B EOVERFLOW -.I errno +.B \%EOVERFLOW +.I \%errno code. Thus, this implementation of -.BR getline () +.BR \%getline () and -.BR getdelim () +.BR \%getdelim () substitutes the semantically similar, (but not semantically identical), -.B ERANGE -.I errno +.B \%ERANGE +.I \%errno code for -.BR EOVERFLOW , +.BR \%EOVERFLOW , to ensure that MSVCRT.DLL's -.BR strerror () +.BR \%strerror () can return an acceptable description for this error condition. . . @@ -361,20 +366,21 @@ can return an acceptable description for this error condition. Please refer to Microsoft's documentation, on MSDN, for standard I/O streams, -.BR fgetc (), -.BR ferror (), -.BR feof (), -.BR malloc (), -.BR free (), -.BR strerror (), +.BR \%fgetc (), +.BR \%ferror (), +.BR \%feof (), +.BR \%malloc (), +.BR \%free (), +.BR \%strerror (), and -.BR errno . +.BR \%errno . . . .SH AUTHOR . This manpage was written by \%Keith\ Marshall, -\%, to document the +\%, +to document the .BR \%getline () and .BR \%getdelim () @@ -382,6 +388,6 @@ functions as they have been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by -the original author remains unchanged. +the original author remains in place. . .\" EOF