doc: Rework libc man pages - scc - simple c99 compiler
HTML git clone git://git.simple-cc.org/scc
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
DIR commit eb46f82c0e2e5f410e96b02e3fde0662ee69ea02
DIR parent 6c484fefde07d8e674e4a9016347ff30cfd16319
HTML Author: Roberto E. Vargas Caballero <k0ga@shike2.net>
Date: Tue, 17 Mar 2026 09:30:05 +0100
doc: Rework libc man pages
Diffstat:
M doc/man3/clock.3 | 18 +++++++++++-------
M doc/man3/ctime.3 | 83 ++++++++++++++++---------------
M doc/man3/difftime.3 | 14 ++++++++------
M doc/man3/locale.h.3 | 111 +++++++++++++++----------------
M doc/man3/localeconv.3 | 28 ++++++++++++----------------
M doc/man3/mbtowc.3 | 71 ++++++++++++++-----------------
M doc/man3/memchr.3 | 28 +++++++++++++---------------
M doc/man3/memcmp.3 | 27 +++++++++++----------------
M doc/man3/memcpy.3 | 20 +++++++++-----------
M doc/man3/memmove.3 | 20 ++++++++++----------
M doc/man3/memset.3 | 25 ++++++++++++-------------
M doc/man3/setjmp.3 | 64 +++++++++++++++----------------
M doc/man3/setjmp.h.3 | 16 +++++++---------
M doc/man3/setlocale.3 | 59 +++++++++++++++----------------
M doc/man3/strcat.3 | 21 +++++++++------------
M doc/man3/strchr.3 | 18 ++++++++++--------
M doc/man3/strcmp.3 | 30 +++++++++++-------------------
M doc/man3/strcoll.3 | 40 +++++++++++++++----------------
M doc/man3/strcpy.3 | 15 +++++++--------
M doc/man3/strcspn.3 | 13 ++++---------
M doc/man3/strerror.3 | 28 +++++++++++++---------------
M doc/man3/strftime.3 | 243 ++++++++++++++-----------------
M doc/man3/string.h.3 | 2 +-
M doc/man3/strlen.3 | 12 +++++++-----
M doc/man3/strncat.3 | 32 ++++++++++++++++----------------
M doc/man3/strncmp.3 | 38 +++++++++++++++----------------
M doc/man3/strncpy.3 | 38 ++++++++++++++++----------------
M doc/man3/strpbrk.3 | 15 +++++++--------
M doc/man3/strrchr.3 | 21 +++++++++++----------
M doc/man3/strspn.3 | 13 ++++---------
M doc/man3/strstr.3 | 25 +++++++++++--------------
M doc/man3/strtok.3 | 75 ++++++++++++-------------------
M doc/man3/strxfrm.3 | 49 +++++++++++++++----------------
M doc/man3/time.3 | 15 ++++++++-------
M doc/man3/time.h.3 | 65 +++++++++++++++----------------
M doc/man3/wchar.h.3 | 42 ++++++++++++++-----------------
36 files changed, 663 insertions(+), 771 deletions(-)
---
DIR diff --git a/doc/man3/clock.3 b/doc/man3/clock.3
@@ -1,6 +1,6 @@
.TH CLOCK 3
.SH NAME
-clock - determine processor time
+clock - query processor time used by the program
.SH SYNOPSIS
#include <time.h>
@@ -8,13 +8,17 @@ clock_t clock(void)
.SH DESCRIPTION
The
.BR clock ()
-function returns an approximation of processor time used by the program.
+function returns an approximation of the processor time
+consumed by the running program.
.SH RETURN VALUE
-The value returned is the CPU time used so far as a clock_t.
-In order to get the number of seconds used, divide by
-.BR CLOCKS_PER_SEC .
-If the processor time used is not available or its value cannot
-be represented, the function returns the value (clock_t)-1.
+The accumulated processor time is returned as a
+.IR clock_t .
+Dividing the result by
+.B CLOCKS_PER_SEC
+gives the time in seconds.
+If the processor time is unavailable or cannot be represented,
+.B (clock_t)-1
+is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.23.2.1 Paragraph 1,2,3
.SH SEE ALSO
DIR diff --git a/doc/man3/ctime.3 b/doc/man3/ctime.3
@@ -1,7 +1,6 @@
.TH CTIME 3
.SH NAME
-asctime, ctime, gmtime, localtime, mktime - transform date and time to
-broken-down time
+asctime, ctime, gmtime, localtime, mktime - convert between calendar time and broken-down time
.SH SYNOPSIS
#include <time.h>
@@ -18,108 +17,110 @@ The
.B gmtime
and
.B localtime
-functions all take an argument of data type
-.BR time_t ,
-which represents calendar time.
+functions each accept a
+.B time_t
+argument representing calendar time.
The
.B asctime
and
.B mktime
-functions both takes an argument representing broken-down time,
-which is a representation separated into year, month, day and so on.
+functions each accept a pointer to a broken-down time structure,
+which separates calendar time into components such as
+year, month, and day.
-Broken-down time is stored in the struct tm.
+Broken-down time is stored in a
+.B struct tm
+object.
-The call
+Calling
.B ctime(t)
-is equivalent to
+is equivalent to calling
.BR asctime(localtime(t)) .
It converts the calendar time
.I t
-into a null-terminated string of the form:
+to a null-terminated string with the form:
- "Wed Jun 30 21:49:08 1993\\n\\0"
+ "Wed Jun 30 21:49:08 1993\n\0"
-In C locale, the abbreviations for the days of the week are
+In the C locale, the day-of-week abbreviations are
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", and "Sat";
-the abbreviations for the months are "Jan", "Feb", "Mar", "Apr",
+the month abbreviations are "Jan", "Feb", "Mar", "Apr",
"May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and "Dec".
The
.B gmtime
function converts the calendar time
.I timep
-into broken-down time representation, expressed as
+to a broken-down time expressed as
Coordinated Universal Time (UTC).
-It may return NULL if the specified time cannot be converted to UTC.
+It may return NULL when the conversion is not possible.
The
.B localtime
function converts the calendar time
.I timep
-to broken-down time representation,
-expressed relative to the user's specified timezone.
+to a broken-down time expressed in the user's local timezone.
The
.B asctime
-function converts the broken-down time value
+function converts the broken-down time
.I tm
-into a null-terminated string with the same format as
-.B ctime
-function.
+to a null-terminated string using the same format as
+.BR ctime .
The
.B mktime
-function converts a broken-down time structure,
-expressed as local time, to calendar time representation.
-The function ignores
-the values supplied by the caller in the
+function converts a broken-down local time to a calendar time value.
+The
.B tm_wday
and
.B tm_yday
-fields and the original values of other fields
-are not restricted to the ranges indicated above.
-On successful completion, the values of
+fields of the input structure are ignored.
+The remaining fields are not required to lie within their normal ranges.
+Upon success, the structure is updated so that all fields reflect
+the calendar time within their standard ranges,
+with
.B tm_wday
and
.B tm_yday
-are set appropriately and the other components are set to represent
-the specified calendar time within their respective ranges.
+computed accordingly.
The final value of
.B tm_mday
-is not set until
+is resolved only after
.B tm_mon
and
.B tm_year
-are determined.
+have been determined.
.SH RETURN VALUE
On success,
.B gmtime
and
.B localtime
-functions return a pointer to a struct tm.
+return a pointer to a
+.B struct tm .
On success,
.B asctime
and
.B ctime
-functions return a pointer to a string.
+return a pointer to the formatted string.
On success,
.B mktime
-function returns the calendar time, expressed as a value of type
-.BR time_t .
+returns the calendar time as a
+.B time_t
+value.
-On error,
+On failure,
.B mktime
-function returns the value
+returns
.BR (time_t)-1 .
-The remaining functions return NULL on error.
+All other functions return NULL on failure.
On error,
.B errno
-is set to indicate the cause of the error.
+is set to indicate the cause.
.SH STANDARDS
.nf
ISO/IEC 9899:1999 7.23.2.3 Paragraph 1,2,3
DIR diff --git a/doc/man3/difftime.3 b/doc/man3/difftime.3
@@ -1,6 +1,6 @@
.TH DIFFTIME 3
.SH NAME
-difftime - calculate time difference
+difftime - compute the difference between two calendar times
.SH SYNOPSIS
#include <time.h>
@@ -8,14 +8,16 @@ double difftime(time_t time1, time_t time0)
.SH DESCRIPTION
The
.BR difftime ()
-function returns the difference (time1 - time0)
-between time
+function computes the elapsed time between two calendar times,
.I time1
-and time
+and
.IR time0 .
.SH RETURN VALUE
-The value returned is the number of seconds elapsed,
-represented as a double.
+The elapsed time in seconds from
+.I time0
+to
+.I time1
+is returned as a double.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.23.2.2 Paragraph 1,2,3
.SH SEE ALSO
DIR diff --git a/doc/man3/locale.h.3 b/doc/man3/locale.h.3
@@ -1,6 +1,6 @@
.TH locale.h 3
.SH NAME
-locale.h - category macros
+locale.h - localization category macros
.SH SYNOPSIS
#include <locale.h>
@@ -23,14 +23,14 @@ LC_NUMERIC
LC_TIME
.fi
-These macros expand to integer constant expressions with distinct values,
-suitable for use as the first argument,
-.IR category ,
-to the
-.B setlocale
-function.
+Each macro expands to a distinct integer constant expression
+that may be passed as the
+.I category
+argument to
+.BR setlocale .
-The locale.h header declares the lconv structure defined as follows:
+The locale.h header also declares the lconv structure with at least
+the following members:
.nf
char *currency_symbol
@@ -64,104 +64,97 @@ The members of the
structure are:
.TP 10
currency_symbol
-The local currency symbol applicable to the current locale.
+The currency symbol used in the current locale.
.TP
decimal_point
-The decimal-point character used to format monetary quantities.
+The decimal separator for non-monetary numeric values.
.TP
thousands_sep
-The character used to separate groups of digits
-before the decimal-point character in formatted monetary quantities.
+The character that separates digit groups
+to the left of the decimal point in non-monetary values.
.TP
grouping
-A string whose elements indicate the size of each group of digits in
-formatted nonmonetary quantities.
+A string encoding the sizes of digit groups in
+formatted non-monetary quantities.
.TP
mon_decimal_point
-The decimal-point used to format monetary quantities.
+The decimal separator used in monetary values.
.TP
mon_thousands_sep
-The separator for groups of digits before
-the decimal-point in formatted monetary quantities.
+The digit group separator for monetary quantities.
.TP
mon_grouping
-A string whose elements indicate the size of each group of digits in
+A string encoding the sizes of digit groups in
formatted monetary quantities.
.TP
positive_sign
-The string used to indicate a nonnegative-valued formatted monetary
-quantity.
+The string used to mark a non-negative monetary value.
.TP
negative_sign
-The string used to indicate a negative-valued formatted
-monetary quantity.
+The string used to mark a negative monetary value.
.TP
frac_digits
-The number of fractional digits (those after the decimal-point)
-to be displayed in a locally formatted monetary quantity.
+The number of digits after the decimal point in a locally
+formatted monetary quantity.
.TP
p_cs_precedes
-Set to 1 or 0 if the currency_symbol respectively precedes or
-succeeds the value for a nonnegative locally formatted
-monetary quantity.
+Set to 1 if currency_symbol comes before the value
+for a non-negative locally formatted monetary quantity,
+or 0 if it follows.
.TP
n_cs_precedes
-Set to 1 or 0 if the currency_symbol respectively precedes or
-succeeds the value for a negative locally formatted
-monetary quantity
+Set to 1 if currency_symbol comes before the value
+for a negative locally formatted monetary quantity,
+or 0 if it follows.
.TP
p_sep_by_space
-Set to a value indicating the separation of the currency_symbol,
-the sign string, and the value for a nonnegative locally formatted
-monetary quantity.
+Encodes the spacing between currency_symbol, the sign string,
+and the value for a non-negative locally formatted monetary quantity.
.TP
n_sep_by_space
-Set to a value indicating the separation of the currency_symbol,
-the sign string, and the value for a negative locally formatted
-monetary quantity.
+Encodes the spacing between currency_symbol, the sign string,
+and the value for a negative locally formatted monetary quantity.
.TP
p_sign_posn
-Set to a value indicating the positioning of the positive_sign for
-a nonnegative locally formatted monetary quantity.
+Encodes where the positive_sign is placed for a non-negative
+locally formatted monetary quantity.
.TP
n_sign_posn
-Set to a value indicating the positioning of the negative_sign for
-a negative locally formatted monetary quantity.
+Encodes where the negative_sign is placed for a negative
+locally formatted monetary quantity.
.TP
int_curr_symbol
-The international currency symbol applicable to the current locale.
+The international currency symbol for the current locale.
.TP
int_frac_digits
-The number of fractional digits (those after the decimal-point) to be
-displayed in an internationally formatted monetary quantity.
+The number of digits after the decimal point in an internationally
+formatted monetary quantity.
.TP
int_p_cs_precedes
-Set to 1 or 0 if the int_curr_symbol respectively precedes or
-succeeds the value for a nonnegative internationally formatted
-monetary quantity.
+Set to 1 if int_curr_symbol comes before the value
+for a non-negative internationally formatted monetary quantity,
+or 0 if it follows.
.TP
int_n_cs_precedes
-Set to 1 or 0 if the int_curr_symbol respectively precedes or
-succeeds the value for a negative internationally formatted
-monetary quantity.
+Set to 1 if int_curr_symbol comes before the value
+for a negative internationally formatted monetary quantity,
+or 0 if it follows.
.TP
int_p_sep_by_space
-Set to a value indicating the separation of the int_curr_symbol,
-the sign string, and the value for a nonnegative internationally
-formatted monetary quantity.
+Encodes the spacing between int_curr_symbol, the sign string,
+and the value for a non-negative internationally formatted monetary quantity.
.TP
int_n_sep_by_space
-Set to a value indicating the separation of the int_curr_symbol,
-the sign string, and the value for a negative internationally
-formatted monetary quantity.
+Encodes the spacing between int_curr_symbol, the sign string,
+and the value for a negative internationally formatted monetary quantity.
.TP
int_p_sign_posn
-Set to a value indicating the positioning of the positive_sign for
-a nonnegative internationally formatted monetary quantity.
+Encodes where the positive_sign is placed for a non-negative
+internationally formatted monetary quantity.
.TP
int_n_sign_posn
-Set to a value indicating the positioning of the negative_sign for
-a negative internationally formatted monetary quantity.
+Encodes where the negative_sign is placed for a negative
+internationally formatted monetary quantity.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.11
DIR diff --git a/doc/man3/localeconv.3 b/doc/man3/localeconv.3
@@ -1,6 +1,6 @@
.TH localeconv 3
.SH NAME
-localeconv - get numeric formatting information
+localeconv - retrieve numeric formatting conventions for the current locale
.SH SYNOPSIS
#include <locale.h>
@@ -8,23 +8,19 @@ struct lconv *localeconv(void);
.SH DESCRIPTION
The
.BR localeconv ()
-function is used to set
-the components of an object with type struct lconv
-with values appropriate for the formatting of numeric quantities
-according to the rules of the current locale and return a pointer to it.
+function fills the fields of an internal object of type struct lconv
+with the numeric and monetary formatting rules of the active locale
+and returns a pointer to that object.
.SH RETURN VALUE
-The
-.B localeconv
-function returns a pointer to the filled-in object.
-The structure pointed to by the return value
-shall not be modified by the program,
-but may be overwritten by a subsequent call to the
-.B localeconv
-function.
-In addition, calls to
+A pointer to the internal
+.I lconv
+structure is returned.
+The program must not modify the returned structure;
+its contents may be replaced by a subsequent call to
+.BR localeconv ()
+or by calls to
.B setlocale
-function with categories LC_ALL, LC_MONETARY, or LC_NUMERIC
-may overwrite the contents of the structure.
+with a category of LC_ALL, LC_MONETARY, or LC_NUMERIC.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.11.2.1 Paragraph 1,2,8
.SH SEE ALSO
DIR diff --git a/doc/man3/mbtowc.3 b/doc/man3/mbtowc.3
@@ -1,67 +1,60 @@
.TH MBTOWC 3
.SH NAME
-mbtowc - converts from multibyte encoding to wchar_t
+mbtowc - convert a multibyte sequence to a wide character
.SH SYNOPSIS
#include <stdlib.h>
int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n)
.SH DESCRIPTION
-if
+When
.I s
is not a null pointer,
the
.BR mbtowc ()
-function inspects at most
+function examines up to
.I n
-bytes beginning with the byte pointed to by
+bytes starting at
.I s
-to determine the number of bytes needed
-to complete the next multibyte character
-(including any shift sequences).
-If the function determines
-that the next multibyte character is complete and valid,
-it determines the value of the corresponding wide character
-and then,
+to determine how many bytes form the next complete multibyte character,
+including any required shift sequences.
+If a complete, valid multibyte character is found,
+the corresponding wide character value is computed and,
if
.I pwc
is not a null pointer,
-stores that value in the object pointed to by
+stored in the object at
.IR pwc .
-If the corresponding wide character is the null wide character,
-the function is left in the initial conversion state.
+When the converted character is the null wide character,
+the conversion state is reset to its initial value.
.SH RETURN VALUE
-If
+When
.I s
is a null pointer,
-the
-.BR mbtowc ()
-function returns a nonzero or zero value,
-if multibyte character encodings,
-respectively,
-do or do not have state-dependent encodings.
-If
-.I s
-is not a null pointer,
-the
.BR mbtowc ()
-function either returns 0
-(if
+returns non-zero if the current encoding has state-dependent sequences,
+or zero otherwise.
+When
+.I s
+is not a null pointer, the function returns:
+.TP
+0
+if
.I s
-points to the null character),
-or returns the number of bytes
-that are contained in the converted multibyte character
-(if the next
+points to the null character;
+.TP
+positive
+the number of bytes consumed to produce the wide character,
+when the next
.I n
-or fewer bytes form a valid multibyte character),
-or returns -1
-(if they do not form a valid multibyte character).
+or fewer bytes form a valid multibyte character;
+.TP
+\-1
+if the bytes do not form a valid multibyte character.
.PP
-In no case will the value returned be
-greater than
+The return value never exceeds
.I n
-or the value of the
-.I MB_CUR_MAX
-macro.
+or the value of
+.IR MB_CUR_MAX .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.20.7.2 Paragraph 1,2,3,4,5
.SH SEE ALSO
DIR diff --git a/doc/man3/memchr.3 b/doc/man3/memchr.3
@@ -1,6 +1,6 @@
.TH memchr 3
.SH NAME
-memchr - find byte in memory
+memchr - search for a byte in a memory block
.SH SYNOPSIS
#include <string.h>
@@ -8,25 +8,23 @@ void *memchr(const void *s, int c, size_t n)
.SH DESCRIPTION
The
.BR memchr ()
-function locates the first occurence of
-.I c
-(converted to an unsigned char)
-in the initial
+function scans the first
.I n
-characters
-(each interpreted as unsigned char)
-of the object pointed to by
-.IR s .
-.PP
-The function shall not try to locate
+bytes of the memory block pointed to by
+.I s
+for the first occurrence of the byte value
+obtained by converting
.I c
-if
+to unsigned char.
+Each byte in the block is treated as unsigned char.
+.PP
+When
.I n
-is equal to 0.
+is zero, the search is not performed.
.SH RETURN VALUE
The
.BR memchr ()
-function shall return a pointer to the located character
-or a null pointer if the character does not occur in the object.
+function returns a pointer to the first matching byte,
+or a null pointer if the byte is not found within the block.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.1
DIR diff --git a/doc/man3/memcmp.3 b/doc/man3/memcmp.3
@@ -1,6 +1,6 @@
.TH MEMCMP 3
.SH NAME
-memcmp - compare bytes in memory
+memcmp - compare two memory blocks byte by byte
.SH SYNOPSIS
#include <string.h>
@@ -10,25 +10,20 @@ The
.BR memcmp ()
function compares the first
.I n
-bytes of the object pointed to by
+bytes of the memory blocks pointed to by
.I s1
-to the first
-.I n
-bytes of the object pointed to by
+and
.IR s2 .
-The value returned shall be used to determine
-if an object is lexicographically greater than,
-lesser than or equal to another object.
+The comparison is performed as if each byte were unsigned char.
.SH RETURN VALUE
-The
-.BR memcmp ()
-function shall return an integer greater than,
-equal to, or lesser than 0,
-if the object pointed to by
+A positive integer is returned if
.I s1
-is greater than,
-equal to, or lesser than the object pointed to by
+is lexicographically greater than
.IR s2 ,
-respectively.
+zero if the two blocks are equal,
+and a negative integer if
+.I s1
+is lexicographically less than
+.IR s2 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.4.1
DIR diff --git a/doc/man3/memcpy.3 b/doc/man3/memcpy.3
@@ -1,6 +1,6 @@
.TH memcpy 3
.SH NAME
-memcpy - copy bytes in memory
+memcpy - copy bytes between non-overlapping memory regions
.SH SYNOPSIS
#include <string.h>
@@ -8,23 +8,21 @@ void *memcpy (void *restrict s1, const void *restrict s2, size_t n)
.SH DESCRIPTION
The
.BR memcpy ()
-function copies the first
+function copies
.I n
-bytes of the object pointed to by
+bytes from the memory block pointed to by
.I s2
-into the object pointed to by
+into the memory block pointed to by
.IR s1 .
-The function does not modify
-.I s1
-if
+When
.I n
-is equal to 0.
-If copying takes place between objects that overlap,
-the behavior is undefined.
+is zero, nothing is copied.
+The source and destination must not overlap;
+if they do, the behavior is undefined.
.SH RETURN VALUE
The
.BR memcpy ()
-function shall always return the pointer
+function always returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.2.1
DIR diff --git a/doc/man3/memmove.3 b/doc/man3/memmove.3
@@ -1,6 +1,6 @@
.TH memmove 3
.SH NAME
-memmove - copy bytes in memory with overlapping areas
+memmove - copy bytes between memory regions that may overlap
.SH SYNOPSIS
#include <string.h>
@@ -8,22 +8,22 @@ void *memmove (void *s1, const void *s2, size_t n)
.SH DESCRIPTION
The
.BR memmove ()
-function copies the first
+function copies
.I n
-bytes of the object pointed to by
+bytes from the memory block pointed to by
.I s2
-to the object pointed to by
+to the memory block pointed to by
.IR s1 .
-The
-.BR memmove ()
-function facilitates copying between overlapping memory blocks.
-The function shall not copy anything if
+Unlike
+.BR memcpy ,
+the source and destination regions may overlap.
+When
.I n
-is equal to 0.
+is zero, nothing is copied.
.SH RETURN VALUE
The
.BR memmove ()
-function shall return the pointer
+function returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.2.2
DIR diff --git a/doc/man3/memset.3 b/doc/man3/memset.3
@@ -1,6 +1,6 @@
.TH memset 3
.SH NAME
-memset - set bytes in memory
+memset - fill memory with a constant byte
.SH SYNOPSIS
#include <string.h>
@@ -8,22 +8,21 @@ void *memset(void *s, int c, size_t n)
.SH DESCRIPTION
The
.BR memset ()
-function copies the value of
-.I c
-(converted to an unsigned char)
-into each of the first
+function fills the first
.I n
-characters of the object
-pointed to by
-.IR s .
-.PP
-The function does not modify
+bytes of the memory block pointed to by
.I s
-if
+with the constant byte obtained by converting
+.I c
+to unsigned char.
+.PP
+When
.I n
-is equal to 0.
+is zero, the memory block is left unmodified.
.SH RETURN VALUE
-The function shall return the value of
+The
+.BR memset ()
+function returns its first argument,
.IR s .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.6.1
DIR diff --git a/doc/man3/setjmp.3 b/doc/man3/setjmp.3
@@ -1,6 +1,6 @@
.TH SETJMP 3
.SH NAME
-setjmp - non-local jumps
+setjmp - save and restore the calling environment for non-local jumps
.SH SYNOPSIS
#include <setjmp.h>
@@ -11,57 +11,55 @@ void longjmp(jmp_buf env, int val)
.SH DESCRIPTION
The
.BR setjmp ()
-function saves it calling environment in its argument
-.I env
-for later use by the
-.BR longjmp .
+function saves the current execution environment into
+.IR env ,
+which may later be passed to
+.BR longjmp ()
+to transfer control back to the point of the
+.B setjmp
+call.
The
.BR longjmp ()
-function restores the environment saved
-by the most recent invocation of
+function restores the execution environment previously captured by
.B setjmp
-in the same invocation of the program
-with the corresponding
+in the same program invocation, using the matching
.I env
-as argument.
+buffer.
-If there has been no such invocation,
-or if the function containing the invocation of
+Calling
+.BR longjmp ()
+is only valid if the corresponding
.B setjmp
-has terminated execution,
-or if the invocation of
+was made in the same program invocation,
+the function that called
.B setjmp
-was within the scope of an identifier with variably modified type
-and execution has left that scope in interim,
-the behavior is undefined.
+has not yet returned,
+and execution has not left the scope of any variably modified type
+that was in scope at the time of the
+.B setjmp
+call.
+Violating these conditions produces undefined behavior.
.SH RETURN VALUE
-If the return is from a direct invocation,
+When called directly,
.B setjmp
-shall return the value zero.
-If the return is from a call to
+returns zero.
+When control is transferred via
.BR longjmp ,
.B setjmp
-shall return a nonzero value.
+returns a non-zero value.
-After the function
+After
.B longjmp
-is called,
-program execution continues as
-if the corresponding invocation of
+is called, execution resumes as though
.B setjmp
-has just returned the value specified by
+had just returned
.IR val .
-The function
-.B longjmp
-shall not cause the function
-.B setjmp
-to return the value 0.
If
.I val
-is set to 0,
+is zero,
.B setjmp
-shall return the value 1.
+returns 1 instead.
.SH STANDARDS
.nf
ISO/IEC 9899:1999 Section 7.13.1.1 Paragraph 1,2,3
DIR diff --git a/doc/man3/setjmp.h.3 b/doc/man3/setjmp.h.3
@@ -1,6 +1,6 @@
.TH setjmp.h 3
.SH NAME
-setjmp.h - non-local jumps
+setjmp.h - support for non-local jumps
.SH SYNOPSIS
#include <setjmp.h>
@@ -16,15 +16,13 @@ The setjmp.h header defines the type
.B jmp_buf
-It is an array type suitable for holding
-the information needed to restore a calling environment.
-The environment of a call to
-.B setjmp
-consists of information
-that is essential for a call to
+This is an array type large enough to hold all information
+required to restore the execution state of a call to
+.BR setjmp ,
+so that
.B longjmp
-to return execution to the respective block,
-and the invocation of that block, were it called recursively.
+can later return execution to that point as if the block were
+being re-entered.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.13.1 Paragraph 1,2,3
.SH SEE ALSO
DIR diff --git a/doc/man3/setlocale.3 b/doc/man3/setlocale.3
@@ -1,6 +1,6 @@
.TH setlocale 3
.SH NAME
-setlocale - set the current locale
+setlocale - query or modify the program's current locale
.SH SYNOPSIS
#include <locale.h>
@@ -8,16 +8,15 @@ char *setlocale(int category, const char *locale);
.SH DESCRIPTION
The
.BR setlocale ()
-function is used to set or query the program's current locale.
-It can be used to set or query the locale entirely or partially.
-If
+function allows querying and changing the active locale of the program,
+either in full or in part.
+When
.I locale
is not NULL,
-the program's current locale is modified according to the arguments.
-The argument
+the program locale is updated according to the given arguments.
+The
.I category
-determines which parts of the program's current locale
-should be modified.
+argument selects which aspect of the locale to modify:
.nf
Category Governs
@@ -29,34 +28,32 @@ LC_NUMERIC Formatting of nonmonetary numeric values
LC_TIME Formatting of date and time values
.fi
-A value of
-.B C
-for
-.I locale
-specifies the minimum environment for C translation;
-a value of " " for
+A
.I locale
-specifies the locale-specific native environment.
+value of
+.B C
+selects the minimal environment for C programs;
+a value of
+.B ""
+selects the native environment of the host system.
-At program startup,
-.BR setlocale (LC_ALL,"C");
-is executed.
+At program startup, the locale behaves as if
+.BR setlocale (LC_ALL,"C")
+had been called.
.SH RETURN VALUE
-A pointer to the string associated with the specified
-.I category
-for the new
-.I locale
-is returned if it can be honored.
-A pointer to the string associated with the specified
+On success, a pointer to a string identifying the locale
+associated with the specified
.I category
-for the current locale is returned if
+is returned.
+If
.I locale
-is NULL.
-The string returned is such that a subsequent call
-with that string value and its associated category
-will restore that part of the program's locale.
-The string pointed to shall not be modified by the program,
-but may be overwritten by a subsequent call to the setlocale function.
+is NULL, the string describes the current locale for that category.
+A subsequent call to
+.B setlocale
+with this string and category will restore that locale.
+The returned string must not be modified by the program;
+it may be overwritten by the next call to
+.BR setlocale .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.11.1.1 Paragraph 1,2,3,4,6,7,8
.SH SEE ALSO
DIR diff --git a/doc/man3/strcat.3 b/doc/man3/strcat.3
@@ -8,25 +8,22 @@ char *strcat(char *restrict s1, const char *restrict s2)
.SH DESCRIPTION
The
.BR strcat ()
-function appends a copy of the string
-pointed to by
+function appends a copy of the null-terminated string at
.I s2
-(including the terminating null character)
-to the end of the string pointed to by
-.IR s1 .
+to the end of the string at
+.IR s1 ,
+including its terminating null byte.
.PP
-The initial character of
+The first byte of
.I s2
-overwrites the null character
-at the end of
-.I s1
+replaces the null terminator at the end of
+.IR s1 .
.PP
-If copying takes place between objects that overlap,
-the behaviour is undefined.
+Overlapping source and destination regions produce undefined behavior.
.SH RETURN VALUE
The
.BR strcat ()
-function shall return the pointer
+function returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.3.1
DIR diff --git a/doc/man3/strchr.3 b/doc/man3/strchr.3
@@ -1,6 +1,6 @@
.TH strchr 3
.SH NAME
-strchr - find character in string
+strchr - find the first occurrence of a character in a string
.SH SYNOPSIS
#include <string.h>
@@ -8,16 +8,18 @@ char *strchr(const char *s, int c)
.SH DESCRIPTION
The
.BR strchr ()
-function locates the first occurence of
+function searches the string pointed to by
+.I s
+for the first occurrence of
.I c
-(converted to a char)
-in the string pointed to by
-.IR s .
-The terminating null character is considered to be part of the string.
+after conversion to char.
+The terminating null byte is considered part of the string.
.SH RETURN VALUE
The
.BR strchr ()
-function shall return a pointer to the located character
-or a null pointer if the character does not occur in the string.
+function returns a pointer to the first matching character,
+or a null pointer if
+.I c
+does not appear in the string.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.2
DIR diff --git a/doc/man3/strcmp.3 b/doc/man3/strcmp.3
@@ -1,6 +1,6 @@
.TH strcmp 3
.SH NAME
-strcmp - compare strings
+strcmp - compare two strings
.SH SYNOPSIS
#include <string.h>
@@ -8,28 +8,20 @@ int strcmp(const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strcmp ()
-function compares the string
-pointed to by
+function performs a lexicographic comparison of the string at
.I s1
-to the string pointed to by
+against the string at
.IR s2 .
-.PP
-The value returned shall be used to determine
-if a string is lexicographically
-greater than, lesser than or equal to
-the other string.
-.PP
-The function shall not modify either of the strings.
+Neither string is modified during the comparison.
.SH RETURN VALUE
-The
-.BR strcmp ()
-function shall return an integer
-greater than, equal to or lesser than 0,
-if the string pointed to by
+A positive integer is returned if
.I s1
-is greater than, equal to or lesser than
-the string pointed to by
+is lexicographically greater than
.IR s2 ,
-respectively.
+zero if the two strings are equal,
+and a negative integer if
+.I s1
+is lexicographically less than
+.IR s2 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.4.2
DIR diff --git a/doc/man3/strcoll.3 b/doc/man3/strcoll.3
@@ -1,6 +1,6 @@
.TH strcoll 3
.SH NAME
-strcoll - compare two strings using the current locale
+strcoll - compare two strings according to the current locale
.SH SYNOPSIS
#include <string.h>
@@ -8,30 +8,28 @@ int strcoll (const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strcoll ()
-function compares the string
-pointed to by
+function performs a locale-aware comparison of the string at
.I s1
-to the string pointed to by
-.IR s2 ,
-both interpreted
-as appropriate to the
-LC_COLLATE category of the current locale.
+with the string at
+.IR s2 .
+Both strings are interpreted according to the LC_COLLATE category
+of the current locale.
.PP
-The value returned shall be used to determine
-if a string is lexicographically
-greater than, lesser than or equal to
-the other string,
-according to the current locale.
+The result indicates whether
+.I s1
+is lexicographically greater than, equal to, or less than
+.I s2
+under the ordering rules of the active locale.
.SH RETURN VALUE
-The
-.BR strcoll ()
-function shall return an integer
-greater than, equal to or lesser than 0,
-if the string pointed to by
+A positive integer is returned if
+.I s1
+is greater than
+.IR s2 ,
+zero if the two strings are equal,
+and a negative integer if
.I s1
-is greater than, equal to or lesser than
-the string pointed to by
+is less than
.IR s2 ,
-respectively.
+according to the current locale collation order.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.4.3
DIR diff --git a/doc/man3/strcpy.3 b/doc/man3/strcpy.3
@@ -8,18 +8,17 @@ char *strcpy(char *restrict s1, const char *restrict s2)
.SH DESCRIPTION
The
.BR strcpy ()
-function copies the string
-pointed to by
+function copies the null-terminated string at
.I s2
-(including the terminating null character)
-into the character array pointed to by
-.IR s1 .
-If copying takes place between objects that overlap,
-behaviour is undefined.
+into the character array at
+.IR s1 ,
+including the terminating null byte.
+The source and destination must not overlap;
+if they do, the behavior is undefined.
.SH RETURN VALUE
The
.BR strcpy ()
-function shall return the pointer
+function returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.2.3
DIR diff --git a/doc/man3/strcspn.3 b/doc/man3/strcspn.3
@@ -1,6 +1,6 @@
.TH strcspn 3
.SH NAME
-strcspn - get length of complementary substring
+strcspn - compute the length of the initial segment not containing given characters
.SH SYNOPSIS
#include <string.h>
@@ -8,16 +8,11 @@ size_t strcspn(const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strcspn ()
-function computes the length
-of the maximum initial segment
-of string pointed to by
+function calculates the length of the longest prefix of the string at
.I s1
-which consists entirely of characters
-not from the string pointed to by
+that contains no characters found in the string at
.IR s2 .
.SH RETURN VALUE
-The
-.BR strcspn ()
-function shall return the length of the segment.
+The length of the prefix is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.3
DIR diff --git a/doc/man3/strerror.3 b/doc/man3/strerror.3
@@ -1,6 +1,6 @@
.TH strerror 3
.SH NAME
-strerror - get error message string
+strerror - look up an error message string
.SH SYNOPSIS
#include <string.h>
@@ -8,22 +8,20 @@ char *strerror(int errnum)
.SH DESCRIPTION
The
.BR strerror ()
-function maps the number passed with errnum
-to a message string.
-.PP
-Typically, the values for
+function maps
+.I errnum
+to a locale-specific message string describing the error.
+Although values of
.I errnum
-come from errno,
-but strerror shall map any value of type int to a message.
+typically come from
+.IR errno ,
+the function accepts any value of type int.
.PP
-The array pointed to by the pointer returned
-shall not be modified by the program,
-but may be overwritten
-by a subsequent call to the
-.B strerror
-function.
+The program must not modify the string pointed to by the return value;
+it may be overwritten by the next call to
+.BR strerror .
.SH RETURN VALUE
-The function returns a pointer to the string,
-the contents of which are locale-specific.
+A pointer to the error message string is returned.
+The content of the string is locale-specific.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.6.2
DIR diff --git a/doc/man3/strftime.3 b/doc/man3/strftime.3
@@ -1,6 +1,6 @@
.TH STRFTIME 3
.SH NAME
-strftime - formats the broken-down time according to specified format
+strftime - format a broken-down time value into a string
.SH SYNOPSIS
#include <time.h>
@@ -13,125 +13,117 @@ size_t strftime(char * restrict s,
.SH DESCRIPTION
The
.BR strftime ()
-function places characters into the array pointed to by
+function writes characters into the array pointed to by
.I s
-as controlled by the string pointed to by
+under control of the string pointed to by
.IR format .
The
.I format
-shall be a multibyte character sequence,
-beginning and ending in its initial shift state.
-The
-.I format
-shall consist of zero or more conversion specifiers and
-ordinary characters.
-A conversion specifier consists of a % character,
-possibly followed by an E or O modifier character,
-followed by a character that determines the behavior of the conversion
-specifier.
-All ordinary characters
-(including the terminating null character) are copied unchanged into the
-array.
+string is a multibyte character sequence that begins and ends
+in its initial shift state.
+It consists of zero or more conversion specifiers
+interspersed with ordinary characters.
+Each conversion specifier begins with a
+.B %
+character, optionally followed by an
+.B E
+or
+.B O
+modifier, and ends with a character that determines what is substituted.
+Ordinary characters, including the terminating null byte,
+are copied to the output without modification.
No more than
.I maxsize
characters are placed into the array.
-The format specification is a null-terminated string and
-shall contain special character sequences, called conversion specifiers,
-which get replaced with the appropriate characters as described in the
-following list:
+The following conversion specifiers are recognized:
.TP
.B %a
-The abbreviated name of the day of the week according to the current
-locale.
+The abbreviated weekday name for the current locale.
.TP
.B %A
-THe full name of the day of the week according to the current locale.
+The full weekday name for the current locale.
.TP
.B %b
-The abbreviated name of the month according to the current locale.
+The abbreviated month name for the current locale.
.TP
.B %B
-The full name of the month according to the current locale.
+The full month name for the current locale.
.TP
.B %c
The preferred date and time representation for the current locale.
.TP
.B %C
-The decimal number representing the year divided by 100 and truncated
-to an integer (century number).
+The year divided by 100, truncated to an integer (the century).
.TP
.B %d
-The day of the month as a decimal number between 01 and 31.
+The day of the month as a two-digit decimal number (01 to 31).
.TP
.B %D
-Equivalent to "%m/%d/%y"
+Equivalent to "%m/%d/%y".
.TP
.B %e
-The day of the month as a decimal number between 0 and 31;
-a single digit is preceded by a space.
+The day of the month as a decimal number; single digits are padded with a space.
.TP
.B %F
-Equivalent to "%y-%m-%d"
-(the ISO 8601 date format).
+Equivalent to "%Y-%m-%d" (ISO 8601 date format).
.TP
.B %G
-The ISO 8601 week-based-year with century as a decimal number.
-The 4-digit year corresponding to the ISO week number. (Calculated
-from
+The ISO 8601 week-based year, including the century.
+(Derived from
.BR tm_year ,
.BR tm_yday ,
and
-.BR tm_wday )
+.BR tm_wday .)
.TP
.B %g
Like
.B %G
-but without century, that is, with a 2-digit year (00-99).
-(Calculated from
+but without the century (two-digit year, 00 to 99).
+(Derived from
.BR tm_year ,
.BR tm_yday ,
and
-.BR tm_wday )
+.BR tm_wday .)
.TP
.B %h
Equivalent to
.BR %b .
-(Calculated from
-.BR tm_mon )
+(Derived from
+.BR tm_mon .)
.TP
.B %H
-The hour as a decimal number using a 24-hour clock between
-00 and 23.
-(Calculated from
-.BR tm_hour )
+The hour on a 24-hour clock as a two-digit decimal number (00 to 23).
+(Derived from
+.BR tm_hour .)
.TP
.B %I
-The hour as a decimal number using a 12-hour clock between 01 and 12
-(Calculated from
-.BR tm_hour )
+The hour on a 12-hour clock as a two-digit decimal number (01 to 12).
+(Derived from
+.BR tm_hour .)
.TP
.B %j
-The day of the year as a decimal number between 001 and 366.
-(Calculated from
-.BR tm_yday )
+The day of the year as a three-digit decimal number (001 to 366).
+(Derived from
+.BR tm_yday .)
.TP
.B %m
-The month as a decimal number between 01 and 12
-(Calculated from
-.BR tm_mon )
+The month as a two-digit decimal number (01 to 12).
+(Derived from
+.BR tm_mon .)
.TP
.B %M
-The minute as a decimal number between 00 and 59
+The minute as a two-digit decimal number (00 to 59).
.TP
.B %n
A newline character.
.TP
.B %p
-Either "AM" or "PM" according to the given time value.
-(Calculated from
-.BR tm_hour )
+Either "AM" or "PM" according to the time of day.
+(Derived from
+.BR tm_hour .)
+.TP
.B %r
The locale's 12-hour clock time.
.TP
@@ -139,9 +131,9 @@ The locale's 12-hour clock time.
The time in 24-hour notation (%H:%M).
.TP
.B %S
-The second as a decimal number between 00 and 60.
-(Calculated from
-.BR tm_sec ).
+The second as a two-digit decimal number (00 to 60).
+(Derived from
+.BR tm_sec .)
.TP
.B %t
A tab character.
@@ -150,70 +142,63 @@ A tab character.
The time in 24-hour notation (%H:%M:%S).
.TP
.B %u
-The day of the week (ISO 8601) as a decimal between 1 and 7,
-Monday being 1.
-(Calculated from
-.BR tm_wday )
+The weekday as a decimal number per ISO 8601 (1 to 7, Monday = 1).
+(Derived from
+.BR tm_wday .)
.TP
.B %U
-The week number of the current year as a decimal number
-between 00 and 53,
-starting with the first Sunday as the first day of week 01. (Calculated from
+The week number of the year as a two-digit decimal (00 to 53),
+counting from the first Sunday as day 1 of week 1.
+(Derived from
.BR tm_year ,
.BR tm_wday ,
-.BR tm_yday )
+.BR tm_yday .)
.TP
.B %V
-The ISO 8601 week (see NOTES) number of the current year as a decimal number
-between 01 and 53,
-where week 1 is the first week that has at least 4 days in the new year.
+The ISO 8601 week number of the year (01 to 53),
+where week 1 is the first week containing at least four days of the new year.
.TP
.B %w
-The day of the week as a decimal between 0 and 6,
-Sunday being 0.
+The weekday as a decimal number (0 to 6, Sunday = 0).
.TP
.B %W
-The week number of the current year as a decimal number
-between 00 and 53,
-starting with the first Monday as the first day of week 01.
-(Calculated from
+The week number of the year as a two-digit decimal (00 to 53),
+counting from the first Monday as day 1 of week 1.
+(Derived from
.B tm_yday
and
-.BR tm_wday ).
+.BR tm_wday .)
.TP
.B %x
-The preferred date representation for the current locale without the
-time.
+The preferred date representation for the current locale, without the time.
.TP
.B %X
-The preferred time representation for the current locale without the
-date.
+The preferred time representation for the current locale, without the date.
.TP
.B %y
-The year as a decimal number without a century between 00 and 99.
+The year without the century (00 to 99).
.TP
.B %Y
-The year as a decimal number including the century.
+The year including the century.
.TP
.B %z
-The +hhmm or -hhmm numeric timezone
-(that is, the hour and minute offset from UTC in ISO 8601 format).
+The UTC offset as +hhmm or -hhmm (ISO 8601 format).
.TP
.B %Z
The timezone name or abbreviation.
.TP
.B %%
-This is replaced with %.
+A literal percent sign.
.P
-Some conversion specifiers can be modified by the inclusion of an
+The
.B E
-or
+and
.B O
-modifier character to indicate an alternative format or specification.
-If the alternative format or character doesn't exist for the current locale,
-the modifier is ignored.
+modifier characters may precede certain conversion specifiers
+to request an alternative locale-specific representation.
+When no alternative exists, the modifier is ignored.
-The C Standard mentions the following specifiers:
+The C standard recognizes the following modified specifiers:
.BR %Ec ,
.BR %EC ,
.BR %Ex ,
@@ -232,22 +217,22 @@ The C Standard mentions the following specifiers:
.BR %OV ,
.BR %Ow ,
.BR %OW ,
-.BR %Oy ,
-where the effect of the
+.BR %Oy .
+The
.B O
-modifier is to use
-alternative numeric symbols, and that of the
+modifier requests locale alternative numeric symbols;
+the
.B E
-modifier is to use a locale-dependent alternative representation.
+modifier requests a locale-dependent alternative representation.
-In the "C" locale, the E and O modifiers are ignored and the
-replacement strings for the following specifiers are:
+In the "C" locale, both modifiers are ignored and
+the following substitutions apply:
.TP
.B %a
the first three characters of %A
.TP
.B %A
-one of Sunday ,Monday, ..., Saturday
+one of Sunday, Monday, ..., Saturday
.TP
.B %b
the first three characters of %B
@@ -271,43 +256,29 @@ equivalent to %m/%d/%y
equivalent to %T
.TP
.B %Z
-The timezone name or abbreviation.
+the timezone name or abbreviation
.SH RETURN VALUE
-If the total number of resulting characters
-including the terminating null character doesn't exceed
-.IR maxsize ,
-then
-.I strftime
-function returns the number of characters
-placed into the array pointed to by
-.I s
-not including the terminating null character. Otherwise, zero is
-returned and the contents of the array are indeterminate.
+When the formatted result, including the terminating null byte,
+fits within
+.I maxsize
+characters,
+.B strftime
+returns the number of characters written, excluding the null byte.
+If the result does not fit, zero is returned and the contents
+of the array are unspecified.
.SH NOTES
-In the ISO 8601 week-based year, weeks begin on a Monday and week 1
-of the year is the week that includes January 4th, which also includes
-the first Thursday of the year, and is also the first week that
-contains at least four days in the year. As mentioned above,
-.B %g, %G,
+ISO 8601 week-based years begin on Monday, with week 1 defined as
+the week containing January 4th (equivalently, the first week with
+at least four days in the new year, or the week containing the
+first Thursday of the year).
+The specifiers
+.BR %g ,
+.BR %G ,
and
.B %V
-are dependent on ISO 8601 week-based year, and the following examples
-are provided for illustrative purposes:
-
-If the first Monday of January is the 2nd, 3rd, or 4th,
-the preceding days are part of the last week of the preceding year;
-thus, for Saturday 2nd January 1999,
-.B %G
-is replaced by 1998 and
-.B %V
-is replaced with 53. Similarly,
-if December 29th, 30th or 31st is a Monday,
-it and following days are part of week 1 and hence,
-for Tuesday 30th December 1997,
-.B %G
-is replaced by 1998 and
-.B %V
-is replaced with 01.
+follow this convention. For example, Saturday January 2nd 1999
+falls in week 53 of 1998 (%G = 1998, %V = 53);
+Tuesday December 30th 1997 falls in week 1 of 1998 (%G = 1998, %V = 01).
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.23.3.5 Paragraph 1,2,3,4,5,6,7
.SH SEE ALSO
DIR diff --git a/doc/man3/string.h.3 b/doc/man3/string.h.3
@@ -1,6 +1,6 @@
.TH string.h 3
.SH NAME
-string.h - string operations
+string.h - string and memory operation functions
.SH SYNOPSIS
#include <string.h>
DIR diff --git a/doc/man3/strlen.3 b/doc/man3/strlen.3
@@ -1,6 +1,6 @@
.TH strlen 3
.SH NAME
-strlen - get the length of a string
+strlen - determine the length of a string
.SH SYNOPSIS
#include <string.h>
@@ -8,11 +8,13 @@ size_t strlen(const char *s)
.SH DESCRIPTION
The
.BR strlen ()
-function computes the length of the string
+function counts the number of bytes in the null-terminated string
pointed to by
-.I s
+.IR s ,
+not including the terminating null byte.
.SH RETURN VALUE
-The function shall return the length of the string
-.IR s .
+The number of bytes preceding the terminating null byte in
+.I s
+is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.6.3
DIR diff --git a/doc/man3/strncat.3 b/doc/man3/strncat.3
@@ -1,6 +1,6 @@
.TH strncat 3
.SH NAME
-strncat - concatenate a string with a part of another
+strncat - concatenate a string with a bounded portion of another
.SH SYNOPSIS
#include <string.h>
@@ -8,31 +8,31 @@ char *strncat(char *restrict s1, const char *restrict s2, size_t n)
.SH DESCRIPTION
The
.BR strncat ()
-function appends not more than n characters
-(a null character and characters that follow are not appended)
-from the array pointed to by
+function appends at most
+.I n
+bytes from the array at
.I s2
-to the end of the string pointed to by
+to the end of the string at
.IR s1 .
+Null bytes and any bytes after them in
+.I s2
+are not appended.
.PP
-The initial character of
+The first byte of
.I s2
-overwrites the null character
-at the end of
+replaces the terminating null byte of
.IR s1 .
.PP
-A terminating null character is always appended to the result.
-The function shall not append anything to
-.I s1
-if
+A null terminator is always written after the last appended character.
+When
.I n
-is equal to 0.
-If copying takes place between objects that overlap,
-the behaviour is undefined.
+is zero, nothing is appended to
+.IR s1 .
+Overlapping source and destination regions produce undefined behavior.
.SH RETURN VALUE
The
.BR strncat ()
-function shall return the pointer
+function returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.3.2
DIR diff --git a/doc/man3/strncmp.3 b/doc/man3/strncmp.3
@@ -1,6 +1,6 @@
.TH strncmp 3
.SH NAME
-strncmp - compare part of two strings
+strncmp - compare up to n characters of two strings
.SH SYNOPSIS
#include <string.h>
@@ -8,33 +8,31 @@ int strncmp(const char *s1, const char *s2, size_t n)
.SH DESCRIPTION
The
.BR strncmp ()
-function compares not more than
+function compares at most
.I n
-characters
-(characters that follow a null character are not compared)
-from the array pointed to by
+characters of the array at
.I s1
-to the array pointed to by
+with the array at
.IR s2 .
+Characters following a null byte are not compared.
.PP
-The value returned shall be used to determine
-if a string is lexicographically
-greater than, lesser than or equal to
-the other string.
+The result indicates the lexicographic ordering of
+.I s1
+relative to
+.IR s2 .
.SH RETURN VALUE
-The
-.BR strncmp ()
-function shall return an integer greater than,
-equal to, or lesser than 0,
-if the string pointed to by
+A positive integer is returned if
.I s1
-is greater than,
-equal to, or lesser than the string pointed to by
+is lexicographically greater than
.IR s2 ,
-respectively.
+zero if the compared portions are equal,
+and a negative integer if
+.I s1
+is lexicographically less than
+.IR s2 .
.PP
-The function shall return 0 if
+When
.I n
-is equal to 0.
+is zero, zero is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.4.4
DIR diff --git a/doc/man3/strncpy.3 b/doc/man3/strncpy.3
@@ -1,6 +1,6 @@
.TH strncpy 3
.SH NAME
-strncpy - copy bounded-length string
+strncpy - copy a string with a length limit
.SH SYNOPSIS
#include <string.h>
@@ -8,35 +8,35 @@ char *strncpy(char *restrict s1, const char *restrict s2, size_t n)
.SH DESCRIPTION
The
.BR strncpy ()
-function copies not more than
+function copies at most
.I n
-characters
-(characters that follow a null character are not copied)
-from the array pointed to by
+characters from the array at
.I s2
-into the array pointed to by
+into the array at
.IR s1 .
+Characters that follow a null byte in
+.I s2
+are not copied.
.PP
-If copying takes place between objects that overlap,
-the behaviour is undefined.
+Overlapping source and destination regions produce undefined behavior.
.PP
-If the array pointed to by
+When the string at
.I s2
-is a string that is shorter than
+is shorter than
+.I n
+characters, the remaining positions in
+.I s1
+are filled with null bytes until exactly
.I n
-characters,
-null characters are appended
-to the copy in the array pointed to by
-.IR s1 ,
-until n characters in all have been written.
+bytes have been written.
.PP
-The function shall not copy anything if
+When
.I n
-is equal to 0.
+is zero, nothing is copied.
.SH RETURN VALUE
The
-.BR strcpy ()
-function shall return the pointer
+.BR strncpy ()
+function returns its first argument,
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.2.4
DIR diff --git a/doc/man3/strpbrk.3 b/doc/man3/strpbrk.3
@@ -1,6 +1,6 @@
.TH strpbrk 3
.SH NAME
-strpbrk - scan a string for a byte
+strpbrk - find the first occurrence of any character from a set in a string
.SH SYNOPSIS
#include <string.h>
@@ -8,20 +8,19 @@ char *strpbrk(const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strpbrk ()
-function locates the first occurence
-in the string pointed to by
+function scans the string pointed to by
.I s1
-of any character from
+for the first character that also appears anywhere in
the string pointed to by
.IR s2 .
.SH RETURN VALUE
The
.BR strpbrk ()
-function shall return a pointer to the character in
-.I s1
-or a null pointer if
+function returns a pointer to the first matching character in
+.IR s1 ,
+or a null pointer if no character from
.I s2
-does not occur in
+is found in
.IR s1 .
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.4
DIR diff --git a/doc/man3/strrchr.3 b/doc/man3/strrchr.3
@@ -1,6 +1,6 @@
.TH strrchr 3
.SH NAME
-strrchr - find character in string
+strrchr - find the last occurrence of a character in a string
.SH SYNOPSIS
#include <string.h>
@@ -8,17 +8,18 @@ char *strrchr(const char *s, int c)
.SH DESCRIPTION
The
.BR strrchr ()
-function locates the last occurence of
+function searches the string pointed to by
+.I s
+for the last occurrence of
.I c
-(converted to a char)
-in the string pointed to by
-.IR s .
-.PP
-The terminating null character is considered to be part of the string.
+after conversion to char.
+The terminating null byte is treated as part of the string.
.SH RETURN VALUE
The
-.BR strchr ()
-function shall return a pointer to the located character
-or a null pointer if the character does not occur in the string.
+.BR strrchr ()
+function returns a pointer to the last matching character,
+or a null pointer if
+.I c
+does not appear in the string.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.5
DIR diff --git a/doc/man3/strspn.3 b/doc/man3/strspn.3
@@ -1,6 +1,6 @@
.TH strspn 3
.SH NAME
-strspn - get length of substring
+strspn - compute the length of the initial segment containing only given characters
.SH SYNOPSIS
#include <string.h>
@@ -8,16 +8,11 @@ size_t strspn(const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strspn ()
-function computes the length
-of the maximum initial segment
-of string pointed to by
+function calculates the length of the longest prefix of the string at
.I s1
-which consists entirely of characters
-from the string pointed to by
+that consists entirely of characters found in the string at
.IR s2 .
.SH RETURN VALUE
-The
-.BR strcspn ()
-function shall return the length of the segment.
+The length of the prefix is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.6
DIR diff --git a/doc/man3/strstr.3 b/doc/man3/strstr.3
@@ -1,6 +1,6 @@
.TH strstr 3
.SH NAME
-strstr - find substring in string
+strstr - locate a substring within a string
.SH SYNOPSIS
#include <string.h>
@@ -8,25 +8,22 @@ char *strstr(const char *s1, const char *s2)
.SH DESCRIPTION
The
.BR strstr ()
-function locates the first occurence
-in the string pointed to by
+function searches the string pointed to by
.I s1
-of the sequence of characters
-(excluding the terminating null character)
-in the string pointed to by
+for the first occurrence of the character sequence
+(not including its terminating null byte)
+given by the string pointed to by
.IR s2 .
.SH RETURN VALUE
-The
-.BR strchr ()
-function shall return a pointer to the located string
-or a null pointer if
-.I s2
-is not found.
+A pointer to the first match in
+.I s1
+is returned,
+or a null pointer if the substring is not found.
.PP
If
.I s2
points to an empty string,
-the function returns
-.IR s1 .
+.I s1
+is returned.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.7
DIR diff --git a/doc/man3/strtok.3 b/doc/man3/strtok.3
@@ -1,6 +1,6 @@
.TH strtok 3
.SH NAME
-strtok - split a string into tokens
+strtok - break a string into tokens
.SH SYNOPSIS
#include <string.h>
@@ -8,61 +8,44 @@ char *strtok(char *restrict s1, const char *restrict s2)
.SH DESCRIPTION
The
.BR strtok ()
-function, called in sequence,
-breaks the string pointed to by
+function splits the string at
.I s1
-into a sequence of tokens,
-each of which is delimited by a character
-from the string pointed to by
+into a series of tokens, each bounded by one or more delimiter characters
+drawn from the string at
.IR s2 .
+It is called repeatedly to extract successive tokens.
.PP
-The first call in the sequence has a non-null first argument;
-subsequent calls in the sequence have a null first argument.
+The first call must pass the string to tokenize as
+.IR s1 ;
+subsequent calls must pass NULL as
+.I s1
+to continue where the previous call left off.
.PP
-The separator string pointed to by
+The delimiter set in
.I s2
-may be different from call to call.
+may differ between calls.
.PP
-The first call in the sequence
-searches the string pointed to by
-.I s1
-for the first character
-that is not contained in the current separator
-string pointed to by
-.IR s2 .
-If no such character is found,
-then there are
-no tokens in the string pointed to by s1
-and the strtok function returns a null pointer.
-If such a character is found,
-it is the start of the first token.
+On each call, the function advances past any leading delimiter characters,
+then locates the next delimiter in the remainder of the string.
+If no non-delimiter character is found, no tokens remain
+and a null pointer is returned.
+Otherwise, that character marks the start of a new token.
.PP
-The strtok function then searches from there
-for a character that is contained
-in the current separator string.
-If no such character is found,
-the current token extends to
-the end of the string pointed to by
-.IR s1 ,
-and subsequent searches for a token will return a null pointer.
-If such a character is found,
-it is overwritten by a null character,
-which terminates the current token.
-The strtok function saves
-a pointer to the following character,
-from which the next search for a token will start.
+When the end of the token is found,
+it is terminated by overwriting the delimiter character with a null byte.
+A pointer to the next character is saved internally
+and used as the starting point for the following call.
+If no delimiter follows the token,
+subsequent calls will return a null pointer.
.PP
-Each subsequent call,
-with a null pointer as the value of the first argument,
-starts searching from the saved pointer
-and behaves as described above.
-The function returns a pointer to the first
-character of a token,
-or a null pointer if there is no token.
+After the first call, each subsequent call with NULL as
+.I s1
+resumes scanning from the saved position,
+applying the same logic described above.
.SH RETURN VALUE
The
.BR strtok ()
-function shall return a pointer to the first character of a token,
-or a null pointer if there is no token.
+function returns a pointer to the first character of the current token,
+or a null pointer when no more tokens are found.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.5.8
DIR diff --git a/doc/man3/strxfrm.3 b/doc/man3/strxfrm.3
@@ -1,6 +1,6 @@
.TH strxfrm 3
.SH NAME
-strxfrm - string transformation
+strxfrm - transform a string for locale-aware comparison
.SH SYNOPSIS
#include <string.h>
@@ -8,40 +8,37 @@ size_t strxfrm(char *restrict s1, const char *restrict s2, size_t n)
.SH DESCRIPTION
The
.BR strxfrm ()
-function transforms
-the string pointed to by
+function transforms the string at
.I s2
-and places the resulting string
-into the array pointed to by
+and writes the result into the array at
.IR s1 .
-The transformation is such that
-if the strcmp function is applied to two transformed strings,
-it returns a value
-greater than, equal to or less than zero,
-corresponding to the result of the strcoll function
-applied to the same two original strings.
+The transformation is defined such that applying
+.B strcmp
+to two transformed strings yields the same ordering as applying
+.B strcoll
+to the corresponding original strings.
.PP
-No more than n characters shall be placed into
-the resulting array pointed to by
-.IR s1 ,
-including the terminating null character.
-If n is zero,
+At most
+.I n
+characters, including the terminating null byte,
+are written to
+.IR s1 .
+When
+.I n
+is zero,
.I s1
-is permitted to be a null pointer.
+may be a null pointer.
.PP
-If copying takes place between objects that overlap,
-the behaviour is undefined.
+Overlapping source and destination regions produce undefined behavior.
.SH RETURN VALUE
The
.BR strxfrm ()
-function shall return the length of
-the transformed string
-(not including the terminating null character).
-If the value returned is
+function returns the length of the transformed string,
+not counting the terminating null byte.
+If the returned value is
.I n
-or more,
-the contents of the array pointed to
+or greater, the content of
.I s1
-are indeterminate.
+is indeterminate.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.21.4.5
DIR diff --git a/doc/man3/time.3 b/doc/man3/time.3
@@ -1,6 +1,6 @@
.TH TIME 3
.SH NAME
-time - determines the current calendar time
+time - retrieve the current calendar time
.SH SYNOPSIS
#include <time.h>
@@ -8,15 +8,16 @@ time_t time(time_t *timer)
.SH DESCRIPTION
The
.BR time ()
-function determines the current calendar time.
+function retrieves the current calendar time from the system.
.SH RETURN VALUE
-The value returned is the best approximation
-to the current calendar time. The value
+The best available approximation of the current calendar time is returned.
+If calendar time cannot be determined,
.B (time_t)-1
-is returned if the calendar time is unavailable. If
+is returned.
+When
.I timer
-is not a null pointer,
-the return value is also assigned to the object it points to.
+is not a null pointer, the return value is also stored in
+the object it points to.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.23.2.4 Paragraph 1,2,3
.SH SEE ALSO
DIR diff --git a/doc/man3/time.h.3 b/doc/man3/time.h.3
@@ -1,6 +1,6 @@
.TH time.h 3
.SH NAME
-time.h - time types
+time.h - time and date types and functions
.SH SYNOPSIS
#include <time.h>
@@ -24,37 +24,39 @@ The time.h header defines the following macros:
.B NULL
-It expands to an implementation-defined null pointer constant,
-as defined in stddef.h header.
+An implementation-defined null pointer constant,
+identical to the one defined in stddef.h.
.B CLOCKS_PER_SEC
-A number used to convert the value returned by the
+The number of clock ticks per second,
+used to convert the value returned by
.BR clock ()
-function into seconds. The value is an expression with type
-clock_t.
+to seconds. Its type is
+.IR clock_t .
-The time.h header defines the following types:
+The time.h header defines the types
.BR clock_t ,
.BR size_t ,
+and
.BR time_t .
-The
-time.h header declares the
+The time.h header declares the
.B tm
structure,
-which includes at least the following members:
+which holds a broken-down representation of time
+and contains at least the following members:
.nf
-int tm_sec Seconds[0,60]
-int tm_min Minutes[0,59]
-int tm_hour Hour[0,23]
-int tm_mday Day of month [1,31]
-int tm_mon Month of year [0,11]
-int tm_year Years since 1900
-int tm_wday Day of week [0,6] (Sunday =0)
-int tm_yday Day of year [0,365]
-int tm_isdst Daylight Savings flag
+int tm_sec Seconds [0,60]
+int tm_min Minutes [0,59]
+int tm_hour Hour [0,23]
+int tm_mday Day of month [1,31]
+int tm_mon Month of year [0,11]
+int tm_year Years since 1900
+int tm_wday Day of week [0,6] (Sunday = 0)
+int tm_yday Day of year [0,365]
+int tm_isdst Daylight Savings flag
.fi
The members of the
@@ -62,36 +64,33 @@ The members of the
structure are:
.TP 10
tm_sec
-The number of seconds after the minute, normally in the range 0 to 59,
-but can be up to 60 to allow for leap seconds.
+Seconds elapsed after the minute, normally 0 to 59,
+but up to 60 to accommodate leap seconds.
.TP
tm_min
-The number of minutes after the hour, in the range 0 to 59.
+Minutes elapsed after the hour, in the range 0 to 59.
.TP
tm_hour
-The number of hours past midnight, in the range 0 to 23.
+Hours elapsed since midnight, in the range 0 to 23.
.TP
tm_mday
-The day of the month, in the range 1 to 31.
+The calendar day of the month, in the range 1 to 31.
.TP
tm_mon
-The number of months since January, in the range 0 to 11.
+Months elapsed since January, in the range 0 to 11.
.TP
tm_year
-The number of years since 1900.
+Years elapsed since 1900.
.TP
tm_wday
-The number of days since Sunday, in the range 0 to 6.
+Days elapsed since Sunday, in the range 0 to 6.
.TP
tm_yday
-The number of days since January 1, in the range 0 to 365.
+Days elapsed since January 1st, in the range 0 to 365.
.TP
tm_isdst
-A flag that indicates whether daylight saving time is
-in effect at the time described.
-The value is positive if daylight saving time is in
-effect, zero if it is not, and negative if the information is not
-available.
+A flag indicating whether daylight saving time applies.
+Positive if in effect, zero if not, and negative if unknown.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.23.1 Paragraph 1,2,3,4
.SH SEE ALSO
DIR diff --git a/doc/man3/wchar.h.3 b/doc/man3/wchar.h.3
@@ -1,7 +1,7 @@
.TH wchar.h 3
.SH NAME
-wchar.h - wide char opetarions
-.SH SYPNOSIS
+wchar.h - wide character operations
+.SH SYNOPSIS
#include <wchar.h>
The wchar.h header declares the following functions:
@@ -74,31 +74,27 @@ The wchar.h header defines the macros
.BR NULL ,
.BR WCHAR_MIN ,
and
+.BR WEOF .
.B WEOF
-which expands to a constant expression of type
+expands to a constant expression of type
.B wint_t
-whose value does not correspond to any member of the extended character set.
-It is accepted (and returned) by several functions in this header
-to indicate end-of-file, that is,
-no more input from a stream.
-It is also used as a wide character value
-that does not correspond to any member of the extended character set.
+with a value that does not correspond to any member of the extended character set.
+It is used by several functions in this header to signal end-of-file
+or to represent a wide character value outside the extended character set.
.PP
-It also defines the types
-.BR size_t ,
-.BR wchar_t ,
-.B mbstate_t
-which is an object type other than an array type
-that can hold the conversion state information necessary
-to convert between sequences of multibyte characters and wide characters;
-.B wint_t
-which is an integer type unchanged by default argument promotions
-that can hold any value corresponding to members of the extended character set,
-as well as at least one value
-that does not correspond to any member of the extended character set
+The header also defines the following types:
+.BR size_t ;
+.BR wchar_t ;
+.BR mbstate_t ,
+an object type (not an array) capable of holding
+the state information needed to convert between multibyte and wide character sequences;
+.BR wint_t ,
+an integer type that is not narrowed by default argument promotions
+and can represent all members of the extended character set
+plus at least one additional value outside that set;
and
-.B struct tm
-which is declared as an incomplete structure type.
+.BR "struct tm" ,
+declared as an incomplete structure type.
.SH STANDARDS
ISO/IEC 9899:1999 Section 7.24.1
.SH SEE ALSO