diff options
Diffstat (limited to 'man/man3')
1704 files changed, 99828 insertions, 0 deletions
diff --git a/man/man3/CIRCLEQ_EMPTY.3 b/man/man3/CIRCLEQ_EMPTY.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_ENTRY.3 b/man/man3/CIRCLEQ_ENTRY.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FIRST.3 b/man/man3/CIRCLEQ_FIRST.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FOREACH.3 b/man/man3/CIRCLEQ_FOREACH.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FOREACH_REVERSE.3 b/man/man3/CIRCLEQ_FOREACH_REVERSE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FOREACH_REVERSE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_HEAD.3 b/man/man3/CIRCLEQ_HEAD.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 b/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INIT.3 b/man/man3/CIRCLEQ_INIT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INIT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_AFTER.3 b/man/man3/CIRCLEQ_INSERT_AFTER.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_BEFORE.3 b/man/man3/CIRCLEQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_HEAD.3 b/man/man3/CIRCLEQ_INSERT_HEAD.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_TAIL.3 b/man/man3/CIRCLEQ_INSERT_TAIL.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LAST.3 b/man/man3/CIRCLEQ_LAST.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LAST.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LOOP_NEXT.3 b/man/man3/CIRCLEQ_LOOP_NEXT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LOOP_NEXT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LOOP_PREV.3 b/man/man3/CIRCLEQ_LOOP_PREV.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LOOP_PREV.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_NEXT.3 b/man/man3/CIRCLEQ_NEXT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_PREV.3 b/man/man3/CIRCLEQ_PREV.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_PREV.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_REMOVE.3 b/man/man3/CIRCLEQ_REMOVE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CMSG_ALIGN.3 b/man/man3/CMSG_ALIGN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_ALIGN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_DATA.3 b/man/man3/CMSG_DATA.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_DATA.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_FIRSTHDR.3 b/man/man3/CMSG_FIRSTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_FIRSTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_LEN.3 b/man/man3/CMSG_LEN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_LEN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_NXTHDR.3 b/man/man3/CMSG_NXTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_NXTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_SPACE.3 b/man/man3/CMSG_SPACE.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_SPACE.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CPU_ALLOC.3 b/man/man3/CPU_ALLOC.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ALLOC.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ALLOC_SIZE.3 b/man/man3/CPU_ALLOC_SIZE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ALLOC_SIZE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_AND.3 b/man/man3/CPU_AND.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_AND.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_AND_S.3 b/man/man3/CPU_AND_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_AND_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_CLR.3 b/man/man3/CPU_CLR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_CLR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_CLR_S.3 b/man/man3/CPU_CLR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_CLR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_COUNT.3 b/man/man3/CPU_COUNT.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_COUNT.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_COUNT_S.3 b/man/man3/CPU_COUNT_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_COUNT_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_EQUAL.3 b/man/man3/CPU_EQUAL.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_EQUAL.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_EQUAL_S.3 b/man/man3/CPU_EQUAL_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_EQUAL_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_FREE.3 b/man/man3/CPU_FREE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_FREE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ISSET.3 b/man/man3/CPU_ISSET.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ISSET.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ISSET_S.3 b/man/man3/CPU_ISSET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ISSET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_OR.3 b/man/man3/CPU_OR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_OR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_OR_S.3 b/man/man3/CPU_OR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_OR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_SET.3 b/man/man3/CPU_SET.3 new file mode 100644 index 0000000..b937a8e --- /dev/null +++ b/man/man3/CPU_SET.3 @@ -0,0 +1,348 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH CPU_SET 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, +CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, +CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, +CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S, +CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \- +macros for manipulating CPU sets +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <sched.h> +.P +.BI "void CPU_ZERO(cpu_set_t *" set ); +.P +.BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); +.BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); +.BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); +.P +.BI "int CPU_COUNT(cpu_set_t *" set ); +.P +.BI "void CPU_AND(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.P +.BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); +.P +.BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); +.BI "void CPU_FREE(cpu_set_t *" set ); +.BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); +.P +.BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); +.P +.BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.P +.BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); +.P +.BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.P +.BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ +", cpu_set_t *" set2 ); +.fi +.SH DESCRIPTION +The +.I cpu_set_t +data structure represents a set of CPUs. +CPU sets are used by +.BR sched_setaffinity (2) +and similar interfaces. +.P +The +.I cpu_set_t +data type is implemented as a bit mask. +However, the data structure should be treated as opaque: +all manipulation of CPU sets should be done via the macros +described in this page. +.P +The following macros are provided to operate on the CPU set +.IR set : +.TP +.BR CPU_ZERO () +Clears +.IR set , +so that it contains no CPUs. +.TP +.BR CPU_SET () +Add CPU +.I cpu +to +.IR set . +.TP +.BR CPU_CLR () +Remove CPU +.I cpu +from +.IR set . +.TP +.BR CPU_ISSET () +Test to see if CPU +.I cpu +is a member of +.IR set . +.TP +.BR CPU_COUNT () +Return the number of CPUs in +.IR set . +.P +Where a +.I cpu +argument is specified, it should not produce side effects, +since the above macros may evaluate the argument more than once. +.P +The first CPU on the system corresponds to a +.I cpu +value of 0, the next CPU corresponds to a +.I cpu +value of 1, and so on. +No assumptions should be made about particular CPUs being +available, or the set of CPUs being contiguous, since CPUs can +be taken offline dynamically or be otherwise absent. +The constant +.B CPU_SETSIZE +(currently 1024) specifies a value one greater than the maximum CPU +number that can be stored in +.IR cpu_set_t . +.P +The following macros perform logical operations on CPU sets: +.TP +.BR CPU_AND () +Store the intersection of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_OR () +Store the union of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_XOR () +Store the XOR of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +The XOR means the set of CPUs that are in either +.I srcset1 +or +.IR srcset2 , +but not both. +.TP +.BR CPU_EQUAL () +Test whether two CPU set contain exactly the same CPUs. +.SS Dynamically sized CPU sets +Because some applications may require the ability to dynamically +size CPU sets (e.g., to allocate sets larger than that +defined by the standard +.I cpu_set_t +data type), glibc nowadays provides a set of macros to support this. +.P +The following macros are used to allocate and deallocate CPU sets: +.TP +.BR CPU_ALLOC () +Allocate a CPU set large enough to hold CPUs +in the range 0 to +.IR num_cpus\-1 . +.TP +.BR CPU_ALLOC_SIZE () +Return the size in bytes of the CPU set that would be needed to +hold CPUs in the range 0 to +.IR num_cpus\-1 . +This macro provides the value that can be used for the +.I setsize +argument in the +.BR CPU_*_S () +macros described below. +.TP +.BR CPU_FREE () +Free a CPU set previously allocated by +.BR CPU_ALLOC (). +.P +The macros whose names end with "_S" are the analogs of +the similarly named macros without the suffix. +These macros perform the same tasks as their analogs, +but operate on the dynamically allocated CPU set(s) whose size is +.I setsize +bytes. +.SH RETURN VALUE +.BR CPU_ISSET () +and +.BR CPU_ISSET_S () +return nonzero if +.I cpu +is in +.IR set ; +otherwise, it returns 0. +.P +.BR CPU_COUNT () +and +.BR CPU_COUNT_S () +return the number of CPUs in +.IR set . +.P +.BR CPU_EQUAL () +and +.BR CPU_EQUAL_S () +return nonzero if the two CPU sets are equal; otherwise they return 0. +.P +.BR CPU_ALLOC () +returns a pointer on success, or NULL on failure. +(Errors are as for +.BR malloc (3).) +.P +.BR CPU_ALLOC_SIZE () +returns the number of bytes required to store a +CPU set of the specified cardinality. +.P +The other functions do not return a value. +.SH STANDARDS +Linux. +.SH HISTORY +The +.BR CPU_ZERO (), +.BR CPU_SET (), +.BR CPU_CLR (), +and +.BR CPU_ISSET () +macros were added in glibc 2.3.3. +.P +.BR CPU_COUNT () +first appeared in glibc 2.6. +.P +.BR CPU_AND (), +.BR CPU_OR (), +.BR CPU_XOR (), +.BR CPU_EQUAL (), +.BR CPU_ALLOC (), +.BR CPU_ALLOC_SIZE (), +.BR CPU_FREE (), +.BR CPU_ZERO_S (), +.BR CPU_SET_S (), +.BR CPU_CLR_S (), +.BR CPU_ISSET_S (), +.BR CPU_AND_S (), +.BR CPU_OR_S (), +.BR CPU_XOR_S (), +and +.BR CPU_EQUAL_S () +first appeared in glibc 2.7. +.SH NOTES +To duplicate a CPU set, use +.BR memcpy (3). +.P +Since CPU sets are bit masks allocated in units of long words, +the actual number of CPUs in a dynamically +allocated CPU set will be rounded up to the next multiple of +.IR "sizeof(unsigned long)" . +An application should consider the contents of these extra bits +to be undefined. +.P +Notwithstanding the similarity in the names, +note that the constant +.B CPU_SETSIZE +indicates the number of CPUs in the +.I cpu_set_t +data type (thus, it is effectively a count of the bits in the bit mask), +while the +.I setsize +argument of the +.BR CPU_*_S () +macros is a size in bytes. +.P +The data types for arguments and return values shown +in the SYNOPSIS are hints what about is expected in each case. +However, since these interfaces are implemented as macros, +the compiler won't necessarily catch all type errors +if you violate the suggestions. +.SH BUGS +On 32-bit platforms with glibc 2.8 and earlier, +.BR CPU_ALLOC () +allocates twice as much space as is required, and +.BR CPU_ALLOC_SIZE () +returns a value twice as large as it should. +This bug should not affect the semantics of a program, +but does result in wasted memory +and less efficient operation of the macros that +operate on dynamically allocated CPU sets. +These bugs are fixed in glibc 2.9. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029 +.SH EXAMPLES +The following program demonstrates the use of some of the macros +used for dynamically allocated CPU sets. +.P +.\" SRC BEGIN (CPU_SET.c) +.EX +#define _GNU_SOURCE +#include <sched.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#include <assert.h> +\& +int +main(int argc, char *argv[]) +{ + cpu_set_t *cpusetp; + size_t size, num_cpus; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + num_cpus = atoi(argv[1]); +\& + cpusetp = CPU_ALLOC(num_cpus); + if (cpusetp == NULL) { + perror("CPU_ALLOC"); + exit(EXIT_FAILURE); + } +\& + size = CPU_ALLOC_SIZE(num_cpus); +\& + CPU_ZERO_S(size, cpusetp); + for (size_t cpu = 0; cpu < num_cpus; cpu += 2) + CPU_SET_S(cpu, size, cpusetp); +\& + printf("CPU_COUNT() of set: %d\en", CPU_COUNT_S(size, cpusetp)); +\& + CPU_FREE(cpusetp); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7) diff --git a/man/man3/CPU_SET_S.3 b/man/man3/CPU_SET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_SET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_XOR.3 b/man/man3/CPU_XOR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_XOR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_XOR_S.3 b/man/man3/CPU_XOR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_XOR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ZERO.3 b/man/man3/CPU_ZERO.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ZERO.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ZERO_S.3 b/man/man3/CPU_ZERO_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ZERO_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/DES_FAILED.3 b/man/man3/DES_FAILED.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/DES_FAILED.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/FD_CLR.3 b/man/man3/FD_CLR.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_CLR.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_ISSET.3 b/man/man3/FD_ISSET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_ISSET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_SET.3 b/man/man3/FD_SET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_SET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_ZERO.3 b/man/man3/FD_ZERO.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_ZERO.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/HUGE_VAL.3 b/man/man3/HUGE_VAL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VAL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/HUGE_VALF.3 b/man/man3/HUGE_VALF.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VALF.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/HUGE_VALL.3 b/man/man3/HUGE_VALL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VALL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/INFINITY.3 b/man/man3/INFINITY.3 new file mode 100644 index 0000000..334c79d --- /dev/null +++ b/man/man3/INFINITY.3 @@ -0,0 +1,85 @@ +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH INFINITY 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL \- floating-point constants +.SH LIBRARY +Math library +.RI ( libm ) +.SH SYNOPSIS +.nf +.BR "#define _ISOC99_SOURCE" " /* See feature_test_macros(7) */" +.B #include <math.h> +.P +.B INFINITY +.P +.B NAN +.P +.B HUGE_VAL +.B HUGE_VALF +.B HUGE_VALL +.fi +.SH DESCRIPTION +The macro +.B INFINITY +expands to a +.I float +constant representing positive infinity. +.P +The macro +.B NAN +expands to a +.I float +constant representing a quiet NaN +(when supported). +A +.I quiet +NaN is a NaN ("not-a-number") that does not raise exceptions +when it is used in arithmetic. +The opposite is a +.I signaling +NaN. +See IEC 60559:1989. +.P +The macros +.BR HUGE_VAL , +.BR HUGE_VALF , +.B HUGE_VALL +expand to constants of types +.IR double , +.IR float , +and +.IR "long double" , +respectively, +that represent a large positive value, possibly positive infinity. +.SH STANDARDS +C11. +.SH HISTORY +C99. +.P +On a glibc system, the macro +.B HUGE_VAL +is always available. +Availability of the +.B NAN +macro can be tested using +.BR "#ifdef NAN" , +and similarly for +.BR INFINITY , +.BR HUGE_VALF , +.BR HUGE_VALL . +They will be defined by +.I <math.h> +if +.B _ISOC99_SOURCE +or +.B _GNU_SOURCE +is defined, or +.B __STDC_VERSION__ +is defined +and has a value not less than 199901L. +.SH SEE ALSO +.BR fpclassify (3), +.BR math_error (7) diff --git a/man/man3/LIST_EMPTY.3 b/man/man3/LIST_EMPTY.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_ENTRY.3 b/man/man3/LIST_ENTRY.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_FIRST.3 b/man/man3/LIST_FIRST.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_FOREACH.3 b/man/man3/LIST_FOREACH.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_HEAD.3 b/man/man3/LIST_HEAD.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_HEAD_INITIALIZER.3 b/man/man3/LIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INIT.3 b/man/man3/LIST_INIT.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INIT.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_AFTER.3 b/man/man3/LIST_INSERT_AFTER.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_BEFORE.3 b/man/man3/LIST_INSERT_BEFORE.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_HEAD.3 b/man/man3/LIST_INSERT_HEAD.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_NEXT.3 b/man/man3/LIST_NEXT.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_REMOVE.3 b/man/man3/LIST_REMOVE.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/MAX.3 b/man/man3/MAX.3 new file mode 100644 index 0000000..e290554 --- /dev/null +++ b/man/man3/MAX.3 @@ -0,0 +1,75 @@ +.\" Copyright (C) 2021 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MAX, MIN \- maximum or minimum of two values +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/param.h> +.P +.BI MAX( a ", " b ); +.BI MIN( a ", " b ); +.fi +.SH DESCRIPTION +These macros return the maximum or minimum of +.I a +and +.IR b . +.SH RETURN VALUE +These macros return the value of one of their arguments, +possibly converted to a different type (see BUGS). +.SH ERRORS +These macros may raise the "invalid" floating-point exception +when any of the arguments is NaN. +.SH STANDARDS +GNU, BSD. +.SH NOTES +If either of the arguments is of a floating-point type, +you might prefer to use +.BR fmax (3) +or +.BR fmin (3), +which can handle NaN. +.P +The arguments may be evaluated more than once, or not at all. +.P +Some UNIX systems might provide these macros in a different header, +or not at all. +.SH BUGS +Due to the usual arithmetic conversions, +the result of these macros may be very different from either of the arguments. +To avoid this, ensure that both arguments have the same type. +.SH EXAMPLES +.\" SRC BEGIN (MAX.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <sys/param.h> +\& +int +main(int argc, char *argv[]) +{ + int a, b, x; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <num> <num>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + a = atoi(argv[1]); + b = atoi(argv[2]); + x = MAX(a, b); + printf("MAX(%d, %d) is %d\en", a, b, x); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fmax (3), +.BR fmin (3) diff --git a/man/man3/MB_CUR_MAX.3 b/man/man3/MB_CUR_MAX.3 new file mode 100644 index 0000000..3c6e34e --- /dev/null +++ b/man/man3/MB_CUR_MAX.3 @@ -0,0 +1,43 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_CUR_MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MB_CUR_MAX \- maximum length of a multibyte character in the current locale +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.fi +.SH DESCRIPTION +The +.B MB_CUR_MAX +macro defines an integer expression giving +the maximum number of bytes needed to represent a single +wide character in the current locale. +This value is locale dependent and therefore not a compile-time constant. +.SH RETURN VALUE +An integer in the range [1, +.BR MB_LEN_MAX ]. +The value 1 denotes traditional 8-bit encoded characters. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR MB_LEN_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/MB_LEN_MAX.3 b/man/man3/MB_LEN_MAX.3 new file mode 100644 index 0000000..a38d675 --- /dev/null +++ b/man/man3/MB_LEN_MAX.3 @@ -0,0 +1,51 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_LEN_MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MB_LEN_MAX \- maximum multibyte length of a character across all locales +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <limits.h> +.fi +.SH DESCRIPTION +The +.B MB_LEN_MAX +macro is the maximum number of bytes needed to represent a single +wide character, in any of the supported locales. +.SH RETURN VALUE +A constant integer greater than zero. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The entities +.B MB_LEN_MAX +and +.I sizeof(wchar_t) +are totally unrelated. +In glibc, +.B MB_LEN_MAX +is typically 16 +.\" For an explanation of why the limit was raised to 16, see +.\" http://lists.gnu.org/archive/html/bug-gnulib/2015-05/msg00001.html +.\" From: Bruno Haible +.\" Subject: Re: why is MB_LEN_MAX so large (16) on glibc +.\" Date: Thu, 14 May 2015 02:30:14 +0200 +(6 in glibc versions earlier than 2.2), while +.I sizeof(wchar_t) +is 4. +.SH SEE ALSO +.BR MB_CUR_MAX (3) diff --git a/man/man3/MIN.3 b/man/man3/MIN.3 new file mode 100644 index 0000000..9938abd --- /dev/null +++ b/man/man3/MIN.3 @@ -0,0 +1 @@ +.so man3/MAX.3 diff --git a/man/man3/NAN.3 b/man/man3/NAN.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/NAN.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/SIMPLEQ_EMPTY.3 b/man/man3/SIMPLEQ_EMPTY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_ENTRY.3 b/man/man3/SIMPLEQ_ENTRY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_FIRST.3 b/man/man3/SIMPLEQ_FIRST.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_FOREACH.3 b/man/man3/SIMPLEQ_FOREACH.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_HEAD.3 b/man/man3/SIMPLEQ_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 b/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INIT.3 b/man/man3/SIMPLEQ_INIT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INIT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_AFTER.3 b/man/man3/SIMPLEQ_INSERT_AFTER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_HEAD.3 b/man/man3/SIMPLEQ_INSERT_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_TAIL.3 b/man/man3/SIMPLEQ_INSERT_TAIL.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_NEXT.3 b/man/man3/SIMPLEQ_NEXT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_REMOVE.3 b/man/man3/SIMPLEQ_REMOVE.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_REMOVE_HEAD.3 b/man/man3/SIMPLEQ_REMOVE_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SLIST_EMPTY.3 b/man/man3/SLIST_EMPTY.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_ENTRY.3 b/man/man3/SLIST_ENTRY.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_FIRST.3 b/man/man3/SLIST_FIRST.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_FOREACH.3 b/man/man3/SLIST_FOREACH.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_HEAD.3 b/man/man3/SLIST_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_HEAD_INITIALIZER.3 b/man/man3/SLIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INIT.3 b/man/man3/SLIST_INIT.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INIT.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INSERT_AFTER.3 b/man/man3/SLIST_INSERT_AFTER.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INSERT_HEAD.3 b/man/man3/SLIST_INSERT_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_NEXT.3 b/man/man3/SLIST_NEXT.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_REMOVE.3 b/man/man3/SLIST_REMOVE.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_REMOVE_HEAD.3 b/man/man3/SLIST_REMOVE_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/STAILQ_CONCAT.3 b/man/man3/STAILQ_CONCAT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_EMPTY.3 b/man/man3/STAILQ_EMPTY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_ENTRY.3 b/man/man3/STAILQ_ENTRY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_FIRST.3 b/man/man3/STAILQ_FIRST.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_FOREACH.3 b/man/man3/STAILQ_FOREACH.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_HEAD.3 b/man/man3/STAILQ_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_HEAD_INITIALIZER.3 b/man/man3/STAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INIT.3 b/man/man3/STAILQ_INIT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_AFTER.3 b/man/man3/STAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_HEAD.3 b/man/man3/STAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_TAIL.3 b/man/man3/STAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_NEXT.3 b/man/man3/STAILQ_NEXT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_REMOVE.3 b/man/man3/STAILQ_REMOVE.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_REMOVE_HEAD.3 b/man/man3/STAILQ_REMOVE_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/S_ISBLK.3 b/man/man3/S_ISBLK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISBLK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISCHR.3 b/man/man3/S_ISCHR.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISCHR.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISDIR.3 b/man/man3/S_ISDIR.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISDIR.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISFIFO.3 b/man/man3/S_ISFIFO.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISFIFO.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISLNK.3 b/man/man3/S_ISLNK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISLNK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISREG.3 b/man/man3/S_ISREG.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISREG.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISSOCK.3 b/man/man3/S_ISSOCK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISSOCK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/TAILQ_CONCAT.3 b/man/man3/TAILQ_CONCAT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_EMPTY.3 b/man/man3/TAILQ_EMPTY.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_ENTRY.3 b/man/man3/TAILQ_ENTRY.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FIRST.3 b/man/man3/TAILQ_FIRST.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FOREACH.3 b/man/man3/TAILQ_FOREACH.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FOREACH_REVERSE.3 b/man/man3/TAILQ_FOREACH_REVERSE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FOREACH_REVERSE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_HEAD.3 b/man/man3/TAILQ_HEAD.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_HEAD_INITIALIZER.3 b/man/man3/TAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INIT.3 b/man/man3/TAILQ_INIT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_AFTER.3 b/man/man3/TAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_BEFORE.3 b/man/man3/TAILQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_HEAD.3 b/man/man3/TAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_TAIL.3 b/man/man3/TAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_LAST.3 b/man/man3/TAILQ_LAST.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_LAST.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_NEXT.3 b/man/man3/TAILQ_NEXT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_PREV.3 b/man/man3/TAILQ_PREV.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_PREV.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_REMOVE.3 b/man/man3/TAILQ_REMOVE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_SWAP.3 b/man/man3/TAILQ_SWAP.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_SWAP.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TIMESPEC_TO_TIMEVAL.3 b/man/man3/TIMESPEC_TO_TIMEVAL.3 new file mode 100644 index 0000000..30ab755 --- /dev/null +++ b/man/man3/TIMESPEC_TO_TIMEVAL.3 @@ -0,0 +1 @@ +.so man3/TIMEVAL_TO_TIMESPEC.3 diff --git a/man/man3/TIMEVAL_TO_TIMESPEC.3 b/man/man3/TIMEVAL_TO_TIMESPEC.3 new file mode 100644 index 0000000..30f3ed1 --- /dev/null +++ b/man/man3/TIMEVAL_TO_TIMESPEC.3 @@ -0,0 +1,32 @@ +.\" Copyright (C) 2024 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH TIMEVAL_TO_TIMESPEC 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +TIMEVAL_TO_TIMESPEC, +TIMESPEC_TO_TIMEVAL +\- +convert between time structures +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include <sys/time.h> +.P +.BI "void TIMEVAL_TO_TIMESPEC(const struct timeval *" tv ", struct timespec *" ts ); +.BI "void TIMESPEC_TO_TIMEVAL(struct timeval *" tv ", const struct timespec *" ts ); +.fi +.SH DESCRIPTION +These macros convert from a +.BR timeval (3type) +to a +.BR timespec (3type) +structure, +and vice versa, +respectively. +.P +This is especially useful for writing interfaces that receive a type, +but are implemented with calls to functions that receive the other one. +.SH STANDARDS +GNU, +BSD. diff --git a/man/man3/_Generic.3 b/man/man3/_Generic.3 new file mode 100644 index 0000000..f8e8b1b --- /dev/null +++ b/man/man3/_Generic.3 @@ -0,0 +1,64 @@ +.\" Copyright (C) 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH _Generic 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +_Generic \- type-generic selection +.SH SYNOPSIS +.nf +.BR _Generic( \fIexpression\fP ", type1: " e1 ", " "... /*" \ +", default: " "e */" ); +.fi +.SH DESCRIPTION +.BR _Generic () +evaluates the path of code under the type selector +that is compatible with the type of the controlling +.IR expression , +or +.B default: +if no type is compatible. +.P +.I expression +is not evaluated. +.P +This is especially useful for writing type-generic macros, +that will behave differently depending on the type of the argument. +.SH STANDARDS +C11. +.SH HISTORY +C11. +.SH EXAMPLES +The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.IP +.\" SRC BEGIN (_Generic.c) +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define my_imaxabs _Generic(INTMAX_C(0), \e + long: labs, \e + long long: llabs \e +/* long long long: lllabs */ \e +) +\& +int +main(void) +{ + off_t a; +\& + a = \-42; + printf("imaxabs(%jd) == %jd\en", (intmax_t) a, my_imaxabs(a)); + printf("&imaxabs == %p\en", &my_imaxabs); + printf("&labs == %p\en", &labs); + printf("&llabs == %p\en", &llabs); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END diff --git a/man/man3/_Static_assert.3 b/man/man3/_Static_assert.3 new file mode 100644 index 0000000..30f6353 --- /dev/null +++ b/man/man3/_Static_assert.3 @@ -0,0 +1 @@ +.so man3/static_assert.3 diff --git a/man/man3/__after_morecore_hook.3 b/man/man3/__after_morecore_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__after_morecore_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__fbufsize.3 b/man/man3/__fbufsize.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fbufsize.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__flbf.3 b/man/man3/__flbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__flbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fpending.3 b/man/man3/__fpending.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fpending.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fpurge.3 b/man/man3/__fpurge.3 new file mode 100644 index 0000000..d7cfd49 --- /dev/null +++ b/man/man3/__fpurge.3 @@ -0,0 +1 @@ +.so man3/fpurge.3 diff --git a/man/man3/__freadable.3 b/man/man3/__freadable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__freadable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__freading.3 b/man/man3/__freading.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__freading.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__free_hook.3 b/man/man3/__free_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__free_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__fsetlocking.3 b/man/man3/__fsetlocking.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fsetlocking.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fwritable.3 b/man/man3/__fwritable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fwritable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fwriting.3 b/man/man3/__fwriting.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fwriting.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__malloc_hook.3 b/man/man3/__malloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__malloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__malloc_initialize_hook.3 b/man/man3/__malloc_initialize_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__malloc_initialize_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__memalign_hook.3 b/man/man3/__memalign_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__memalign_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__ppc_get_timebase.3 b/man/man3/__ppc_get_timebase.3 new file mode 100644 index 0000000..7a8064d --- /dev/null +++ b/man/man3/__ppc_get_timebase.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2012, IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_get_timebase 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__ppc_get_timebase, __ppc_get_timebase_freq \- get the current value +of the Time Base Register on Power architecture and its frequency. +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/platform/ppc.h> +.P +.B uint64_t __ppc_get_timebase(void); +.B uint64_t __ppc_get_timebase_freq(void); +.fi +.SH DESCRIPTION +.BR __ppc_get_timebase () +reads the current value of the Time Base Register and returns its +value, while +.BR __ppc_get_timebase_freq () +returns the frequency in which the Time Base Register is updated. +.P +The Time Base Register is a 64-bit register provided by Power Architecture +processors. +It stores a monotonically incremented value that is updated at a +system-dependent frequency that may be different from the processor +frequency. +.SH RETURN VALUE +.BR __ppc_get_timebase () +returns a 64-bit unsigned integer that represents the current value of the +Time Base Register. +.P +.BR __ppc_get_timebase_freq () +returns a 64-bit unsigned integer that represents the frequency at +which the Time Base Register is updated. +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR __ppc_get_timebase () +.\" commit d9dc34cd569bcfe714fe8c708e58c028106e8b2e +glibc 2.16. +.TP +.BR __ppc_get_timebase_freq () +.\" commit 8ad11b9a9cf1de82bd7771306b42070b91417c11 +glibc 2.17. +.SH EXAMPLES +The following program will calculate the time, in microseconds, spent +between two calls to +.BR __ppc_get_timebase (). +.SS Program source +\& +.\" SRC BEGIN (__ppc_get_timebase.c) +.EX +#include <inttypes.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/platform/ppc.h> +\& +/* Maximum value of the Time Base Register: 2\[ha]60 \- 1. + Source: POWER ISA. */ +#define MAX_TB 0xFFFFFFFFFFFFFFF +\& +int +main(void) +{ + uint64_t tb1, tb2, diff; + uint64_t freq; +\& + freq = __ppc_get_timebase_freq(); + printf("Time Base frequency = %"PRIu64" Hz\en", freq); +\& + tb1 = __ppc_get_timebase(); +\& + // Do some stuff... +\& + tb2 = __ppc_get_timebase(); +\& + if (tb2 > tb1) { + diff = tb2 \- tb1; + } else { + /* Treat Time Base Register overflow. */ + diff = (MAX_TB \- tb2) + tb1; + } +\& + printf("Elapsed time = %1.2f usecs\en", + (double) diff * 1000000 / freq); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR usleep (3) diff --git a/man/man3/__ppc_get_timebase_freq.3 b/man/man3/__ppc_get_timebase_freq.3 new file mode 100644 index 0000000..8599293 --- /dev/null +++ b/man/man3/__ppc_get_timebase_freq.3 @@ -0,0 +1 @@ +.so man3/__ppc_get_timebase.3 diff --git a/man/man3/__ppc_mdoio.3 b/man/man3/__ppc_mdoio.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man/man3/__ppc_mdoio.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man/man3/__ppc_mdoom.3 b/man/man3/__ppc_mdoom.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man/man3/__ppc_mdoom.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man/man3/__ppc_set_ppr_low.3 b/man/man3/__ppc_set_ppr_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_med.3 b/man/man3/__ppc_set_ppr_med.3 new file mode 100644 index 0000000..dbfdced --- /dev/null +++ b/man/man3/__ppc_set_ppr_med.3 @@ -0,0 +1,113 @@ +'\" t +.\" Copyright (c) 2015, 2016 IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_set_ppr_med 3 2024-05-02 "Linux man-pages (unreleased)" +Programmer's Manual" +.SH NAME +__ppc_set_ppr_med, __ppc_set_ppr_very_low, __ppc_set_ppr_low, +__ppc_set_ppr_med_low, __ppc_set_ppr_med_high \- +Set the Program Priority Register +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/platform/ppc.h> +.P +.B void __ppc_set_ppr_med(void); +.B void __ppc_set_ppr_very_low(void); +.B void __ppc_set_ppr_low(void); +.B void __ppc_set_ppr_med_low(void); +.B void __ppc_set_ppr_med_high(void); +.fi +.SH DESCRIPTION +These functions provide access to the +.I Program Priority Register +(PPR) on the Power architecture. +.P +The PPR is a 64-bit register that controls the program's priority. +By adjusting the PPR value the programmer may improve system +throughput by causing system resources to be used more +efficiently, especially in contention situations. +The available unprivileged states are covered by the following functions: +.TP +.BR __ppc_set_ppr_med () +sets the Program Priority Register value to +.I medium +(default). +.TP +.BR __ppc_set_ppr_very_low () +sets the Program Priority Register value to +.IR "very low" . +.TP +.BR __ppc_set_ppr_low () +sets the Program Priority Register value to +.IR low . +.TP +.BR __ppc_set_ppr_med_low () +sets the Program Priority Register value to +.IR "medium low" . +.P +The privileged state +.I medium high +may also be set during certain time intervals by problem-state (unprivileged) +programs, with the following function: +.TP +.BR __ppc_set_ppr_med_high () +sets the Program Priority to +.IR "medium high" . +.P +If the program priority is medium high when the time interval expires or if an +attempt is made to set the priority to medium high when it is not allowed, the +priority is set to medium. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __ppc_set_ppr_med (), +.BR __ppc_set_ppr_very_low (), +.BR __ppc_set_ppr_low (), +.BR __ppc_set_ppr_med_low (), +.BR __ppc_set_ppr_med_high () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR __ppc_set_ppr_med () +.TQ +.BR __ppc_set_ppr_low () +.TQ +.BR __ppc_set_ppr_med_low () +glibc 2.18. +.TP +.BR __ppc_set_ppr_very_low () +.TQ +.BR __ppc_set_ppr_med_high () +glibc 2.23. +.SH NOTES +The functions +.BR __ppc_set_ppr_very_low () +and +.BR __ppc_set_ppr_med_high () +will be defined by +.I <sys/platform/ppc.h> +if +.B _ARCH_PWR8 +is defined. +Availability of these functions can be tested using +.BR "#ifdef _ARCH_PWR8" . +.SH SEE ALSO +.BR __ppc_yield (3) +.P +.I Power ISA, Book\~II - Section\ 3.1 (Program Priority Registers) diff --git a/man/man3/__ppc_set_ppr_med_high.3 b/man/man3/__ppc_set_ppr_med_high.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_med_high.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_med_low.3 b/man/man3/__ppc_set_ppr_med_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_med_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_very_low.3 b/man/man3/__ppc_set_ppr_very_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_very_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_yield.3 b/man/man3/__ppc_yield.3 new file mode 100644 index 0000000..55f3701 --- /dev/null +++ b/man/man3/__ppc_yield.3 @@ -0,0 +1,67 @@ +'\" t +.\" Copyright (c) 2015, IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_yield 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__ppc_yield, __ppc_mdoio, __ppc_mdoom \- +Hint the processor to release shared resources +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/platform/ppc.h> +.P +.B void __ppc_yield(void); +.B void __ppc_mdoio(void); +.B void __ppc_mdoom(void); +.fi +.SH DESCRIPTION +These functions +provide hints about the usage of resources that are shared with other +processors on the Power architecture. +They can be used, for example, if a program waiting on a lock intends +to divert the shared resources to be used by other processors. +.P +.BR __ppc_yield () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released for use by +other processors. +.P +.BR __ppc_mdoio () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to caching-inhibited storage have been +completed. +.P +.BR __ppc_mdoom () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to cacheable storage for which the data +is not in the cache have been completed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __ppc_yield (), +.BR __ppc_mdoio (), +.BR __ppc_mdoom () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.18. +.SH SEE ALSO +.BR __ppc_set_ppr_med (3) +.P +.I Power ISA, Book\~II - Section\~3.2 ("or" architecture) diff --git a/man/man3/__realloc_hook.3 b/man/man3/__realloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__realloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__setfpucw.3 b/man/man3/__setfpucw.3 new file mode 100644 index 0000000..0b0dd26 --- /dev/null +++ b/man/man3/__setfpucw.3 @@ -0,0 +1,72 @@ +.\" Written Sat Mar 8 10:35:08 MEZ 1997 by +.\" J. "MUFTI" Scheurich (mufti@csv.ica.uni-stuttgart.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH __setfpucw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__setfpucw \- set FPU control word on i386 architecture (obsolete) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <i386/fpu_control.h> +.P +.BI "[[deprecated]] void __setfpucw(unsigned short " control_word ); +.fi +.SH DESCRIPTION +.BR __setfpucw () +transfers +.I control_word +to the registers of the FPU (floating-point unit) on the i386 architecture. +This was used to control floating-point precision, +rounding and floating-point exceptions. +.SH STANDARDS +GNU. +.SH HISTORY +Removed in glibc 2.1. +.SH NOTES +There are new functions from C99, with prototypes in +.IR <fenv.h> , +to control FPU rounding modes, like +.BR fegetround (3), +.BR fesetround (3), +and the floating-point environment, like +.BR fegetenv (3), +.BR feholdexcept (3), +.BR fesetenv (3), +.BR feupdateenv (3), +and FPU exception handling, like +.BR feclearexcept (3), +.BR fegetexceptflag (3), +.BR feraiseexcept (3), +.BR fesetexceptflag (3), +and +.BR fetestexcept (3). +.P +If direct access to the FPU control word is still needed, the +.B _FPU_GETCW +and +.B _FPU_SETCW +macros from +.I <fpu_control.h> +can be used. +.SH EXAMPLES +.B __setfpucw(0x1372) +.P +Set FPU control word on the i386 architecture to +.RS +.PD 0 +.IP \[bu] 3 +extended precision +.IP \[bu] +rounding to nearest +.IP \[bu] +exceptions on overflow, zero divide and NaN +.PD +.RE +.SH SEE ALSO +.BR feclearexcept (3) +.P +.I <fpu_control.h> diff --git a/man/man3/_flushlbf.3 b/man/man3/_flushlbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/_flushlbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/a64l.3 b/man/man3/a64l.3 new file mode 100644 index 0000000..9fe156a --- /dev/null +++ b/man/man3/a64l.3 @@ -0,0 +1,111 @@ +'\" t +\t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Corrected, aeb, 2002-05-30 +.\" +.TH a64l 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +a64l, l64a \- convert between long and base-64 +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "long a64l(const char *" str64 ); +.BI "char *l64a(long " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR a64l (), +.BR l64a (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions provide a conversion between 32-bit long integers +and little-endian base-64 ASCII strings (of length zero to six). +If the string used as argument for +.BR a64l () +has length greater than six, only the first six bytes are used. +If the type +.I long +has more than 32 bits, then +.BR l64a () +uses only the low order 32 bits of +.IR value , +and +.BR a64l () +sign-extends its 32-bit result. +.P +The 64 digits in the base-64 system are: +.P +.RS +.nf +\&\[aq].\[aq] represents a 0 +\&\[aq]/\[aq] represents a 1 +0-9 represent 2-11 +A-Z represent 12-37 +a-z represent 38-63 +.fi +.RE +.P +So 123 = 59*64\[ha]0 + 1*64\[ha]1 = "v/". +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR l64a () +T} Thread safety MT-Unsafe race:l64a +T{ +.na +.nh +.BR a64l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The value returned by +.BR l64a () +may be a pointer to a static buffer, possibly overwritten +by later calls. +.P +The behavior of +.BR l64a () +is undefined when +.I value +is negative. +If +.I value +is zero, it returns an empty string. +.P +These functions are broken before glibc 2.2.5 +(puts most significant digit first). +.P +This is not the encoding used by +.BR uuencode (1). +.SH SEE ALSO +.BR uuencode (1), +.\" .BR itoa (3), +.BR strtoul (3) diff --git a/man/man3/abort.3 b/man/man3/abort.3 new file mode 100644 index 0000000..874ce2b --- /dev/null +++ b/man/man3/abort.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright 2007 (C) Michael Kerrisk <mtk.manpages@gmail.com> +.\" some parts Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 4 10:51:53 2000 - patch from Joseph S. Myers +.\" 2007-12-15, mtk, Mostly rewritten +.\" +.TH abort 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +abort \- cause abnormal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B [[noreturn]] void abort(void); +.fi +.SH DESCRIPTION +The +.BR abort () +function first unblocks the +.B SIGABRT +signal, and then raises that signal for the calling process +(as though +.BR raise (3) +was called). +This results in the abnormal termination of the process unless the +.B SIGABRT +signal is caught and the signal handler does not return +(see +.BR longjmp (3)). +.P +If the +.B SIGABRT +signal is ignored, or caught by a handler that returns, the +.BR abort () +function will still terminate the process. +It does this by restoring the default disposition for +.B SIGABRT +and then raising the signal for a second time. +.P +As with other cases of abnormal termination the functions registered with +.BR atexit (3) +and +.BR on_exit (3) +are not called. +.SH RETURN VALUE +The +.BR abort () +function never returns. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR abort () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001, 4.3BSD, C89. +.P +Up until glibc 2.26, +if the +.BR abort () +function caused process termination, +all open streams were closed and flushed (as with +.BR fclose (3)). +However, in some cases this could result in deadlocks and data corruption. +Therefore, starting with glibc 2.27, +.\" glibc commit 91e7cf982d0104f0e71770f5ae8e3faf352dea9f +.BR abort () +terminates the process without flushing streams. +POSIX.1 permits either possible behavior, saying that +.BR abort () +"may include an attempt to effect fclose() on all open streams". +.SH SEE ALSO +.BR gdb (1), +.BR sigaction (2), +.BR assert (3), +.BR exit (3), +.BR longjmp (3), +.BR raise (3) diff --git a/man/man3/abs.3 b/man/man3/abs.3 new file mode 100644 index 0000000..2b8f650 --- /dev/null +++ b/man/man3/abs.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:31:13 1993, David Metcalfe +.\" Modified Sun Jun 6 23:27:50 1993, David Metcalfe +.\" Modified Sat Jul 24 21:45:37 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Dec 16 15:02:59 2000, Joseph S. Myers +.\" +.TH abs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +abs, labs, llabs, imaxabs \- compute the absolute value of an integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int abs(int " j ); +.BI "long labs(long " j ); +.BI "long long llabs(long long " j ); +.P +.B #include <inttypes.h> +.P +.BI "intmax_t imaxabs(intmax_t " j ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR llabs (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR abs () +function computes the absolute value of the integer +argument \fIj\fP. +The +.BR labs (), +.BR llabs (), +and +.BR imaxabs () +functions compute the absolute value of the argument \fIj\fP of the +appropriate integer type for the function. +.SH RETURN VALUE +Returns the absolute value of the integer argument, of the appropriate +integer type for the function. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR abs (), +.BR labs (), +.BR llabs (), +.BR imaxabs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99, SVr4, 4.3BSD. +.\" POSIX.1 (1996 edition) requires only the +.\" .BR abs () +.\" function. +.P +C89 only +includes the +.BR abs () +and +.BR labs () +functions; the functions +.BR llabs () +and +.BR imaxabs () +were added in C99. +.SH NOTES +Trying to take the absolute value of the most negative integer +is not defined. +.P +The +.BR llabs () +function is included since glibc 2.0. +The +.BR imaxabs () +function is included since glibc 2.1.1. +.P +For +.BR llabs () +to be declared, it may be necessary to define +\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the +version of glibc) before including any standard headers. +.P +By default, +GCC handles +.BR abs (), +.BR labs (), +and (since GCC 3.0) +.BR llabs () +and +.BR imaxabs () +as built-in functions. +.SH SEE ALSO +.BR cabs (3), +.BR ceil (3), +.BR fabs (3), +.BR floor (3), +.BR rint (3) diff --git a/man/man3/acos.3 b/man/man3/acos.3 new file mode 100644 index 0000000..9ba9515 --- /dev/null +++ b/man/man3/acos.3 @@ -0,0 +1,121 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH acos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acos, acosf, acosl \- arc cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double acos(double " x ); +.BI "float acosf(float " x ); +.BI "long double acosl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR acosf (), +.BR acosl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the arc cosine of +.IR x ; +that is +the value whose cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the arc cosine of +.I x +in radians; the return value is in the range [0,\ pi]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +1, ++0 is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR acos (), +.BR acosf (), +.BR acosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cacos (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/acosf.3 b/man/man3/acosf.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man/man3/acosf.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man/man3/acosh.3 b/man/man3/acosh.3 new file mode 100644 index 0000000..1fb3ed1 --- /dev/null +++ b/man/man3/acosh.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH acosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acosh, acoshf, acoshl \- inverse hyperbolic cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double acosh(double " x ); +.BI "float acoshf(float " x ); +.BI "long double acoshl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR acosh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR acoshf (), +.BR acoshl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic cosine of +.IR x ; +that is the value whose hyperbolic cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +1, +0 is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is less than 1, +a domain error occurs, +and the functions return a NaN. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is less than 1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR acosh (), +.BR acoshf (), +.BR acoshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR asinh (3), +.BR atanh (3), +.BR cacosh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/acoshf.3 b/man/man3/acoshf.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man/man3/acoshf.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man/man3/acoshl.3 b/man/man3/acoshl.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man/man3/acoshl.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man/man3/acosl.3 b/man/man3/acosl.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man/man3/acosl.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man/man3/addmntent.3 b/man/man3/addmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/addmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/addseverity.3 b/man/man3/addseverity.3 new file mode 100644 index 0000000..68335cc --- /dev/null +++ b/man/man3/addseverity.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" adapted glibc info page +.\" +.\" polished a little, aeb +.TH addseverity 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +addseverity \- introduce new severity classes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.B #include <fmtmsg.h> +.P +.BI "int addseverity(int " severity ", const char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR addseverity (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +This function allows the introduction of new severity classes +which can be addressed by the +.I severity +argument of the +.BR fmtmsg (3) +function. +By default, that function knows only how to +print messages for severity 0-4 (with strings (none), HALT, +ERROR, WARNING, INFO). +This call attaches the given string +.I s +to the given value +.IR severity . +If +.I s +is NULL, the severity class with the numeric value +.I severity +is removed. +It is not possible to overwrite or remove one of the default +severity classes. +The severity value must be nonnegative. +.SH RETURN VALUE +Upon success, the value +.B MM_OK +is returned. +Upon error, the return value is +.BR MM_NOTOK . +Possible errors include: out of memory, attempt to remove a +nonexistent or default severity class. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR addseverity () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +System V. +.SH NOTES +New severity classes can also be added by setting the environment variable +.BR SEV_LEVEL . +.SH SEE ALSO +.BR fmtmsg (3) diff --git a/man/man3/adjtime.3 b/man/man3/adjtime.3 new file mode 100644 index 0000000..80f1485 --- /dev/null +++ b/man/man3/adjtime.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH adjtime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +adjtime \- correct the time to synchronize the system clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/time.h> +.P +.BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR adjtime (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR adjtime () +function gradually adjusts the system clock (as returned by +.BR gettimeofday (2)). +The amount of time by which the clock is to be adjusted is specified +in the structure pointed to by +.IR delta . +This structure has the following form: +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +If the adjustment in +.I delta +is positive, then the system clock is speeded up by some +small percentage (i.e., by adding a small +amount of time to the clock value in each second) until the adjustment +has been completed. +If the adjustment in +.I delta +is negative, then the clock is slowed down in a similar fashion. +.P +If a clock adjustment from an earlier +.BR adjtime () +call is already in progress +at the time of a later +.BR adjtime () +call, and +.I delta +is not NULL for the later call, then the earlier adjustment is stopped, +but any already completed part of that adjustment is not undone. +.P +If +.I olddelta +is not NULL, then the buffer that it points to is used to return +the amount of time remaining from any previous adjustment that +has not yet been completed. +.SH RETURN VALUE +On success, +.BR adjtime () +returns 0. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The adjustment in +.I delta +is outside the permitted range. +.TP +.B EPERM +The caller does not have sufficient privilege to adjust the time. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR adjtime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, System V. +.SH NOTES +The adjustment that +.BR adjtime () +makes to the clock is carried out in such a manner that the clock +is always monotonically increasing. +Using +.BR adjtime () +to adjust the time prevents the problems that could be caused for certain +applications (e.g., +.BR make (1)) +by abrupt positive or negative jumps in the system time. +.P +.BR adjtime () +is intended to be used to make small adjustments to the system time. +Most systems impose a limit on the adjustment that can be specified in +.IR delta . +In the glibc implementation, +.I delta +must be less than or equal to (INT_MAX / 1000000 \- 2) +and greater than or equal to (INT_MIN / 1000000 + 2) +(respectively 2145 and \-2145 seconds on i386). +.SH BUGS +A longstanding bug +.\" http://sourceware.org/bugzilla/show_bug?id=2449 +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6761 +meant that if +.I delta +was specified as NULL, +no valid information about the outstanding clock adjustment was returned in +.IR olddelta . +(In this circumstance, +.BR adjtime () +should return the outstanding clock adjustment, without changing it.) +This bug is fixed +.\" Thanks to the new adjtimex() ADJ_OFFSET_SS_READ flag +on systems with glibc 2.8 or later and +Linux kernel 2.6.26 or later. +.SH SEE ALSO +.BR adjtimex (2), +.BR gettimeofday (2), +.BR time (7) diff --git a/man/man3/aio_cancel.3 b/man/man3/aio_cancel.3 new file mode 100644 index 0000000..6ddb301 --- /dev/null +++ b/man/man3/aio_cancel.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_cancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_cancel \- cancel an outstanding asynchronous I/O request +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_cancel () +function attempts to cancel outstanding asynchronous I/O requests +for the file descriptor +.IR fd . +If +.I aiocbp +is NULL, all such requests are canceled. +Otherwise, only the request +described by the control block pointed to by +.I aiocbp +is canceled. +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +Normal asynchronous notification occurs for canceled requests (see +.BR aio (7) +and +.BR sigevent (3type)). +The request return status +.RB ( aio_return (3)) +is set to \-1, and the request error status +.RB ( aio_error (3)) +is set to +.BR ECANCELED . +The control block of requests that cannot be canceled is not changed. +.P +If the request could not be canceled, +then it will terminate in the usual way after performing the I/O operation. +(In this case, +.BR aio_error (3) +will return the status +.BR EINPROGRESSS .) +.P +If +.I aiocbp +is not NULL, and +.I fd +differs from the file descriptor with which the asynchronous operation +was initiated, unspecified results occur. +.P +Which operations are cancelable is implementation-defined. +.\" FreeBSD: not those on raw disk devices. +.SH RETURN VALUE +The +.BR aio_cancel () +function returns one of the following values: +.TP +.B AIO_CANCELED +All requests were successfully canceled. +.TP +.B AIO_NOTCANCELED +At least one of the +requests specified was not canceled because it was in progress. +In this case, one may check the status of individual requests using +.BR aio_error (3). +.TP +.B AIO_ALLDONE +All requests had already been completed before the call. +.TP +\-1 +An error occurred. +The cause of the error can be found by inspecting +.IR errno . +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +.BR aio_cancel () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_cancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_error.3 b/man/man3/aio_error.3 new file mode 100644 index 0000000..f00e35c --- /dev/null +++ b/man/man3/aio_error.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_error 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_error \- get error status of asynchronous I/O operation +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int aio_error(const struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_error () +function returns the error status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.SH RETURN VALUE +This function returns one of the following: +.TP +.B EINPROGRESS +if the request has not been +completed yet. +.TP +.B ECANCELED +if the request was canceled. +.TP +.B 0 +if the request completed successfully. +.TP +.RB "> " 0 +A positive error number, if the asynchronous I/O operation failed. +This is the same value that would have been stored in the +.I errno +variable in the case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2), +or +.BR fdatasync (2) +call. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status (see +.BR aio_return (3)) +has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_error () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_error () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_fsync.3 b/man/man3/aio_fsync.3 new file mode 100644 index 0000000..f9f22c6 --- /dev/null +++ b/man/man3/aio_fsync.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_fsync 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_fsync \- asynchronous file synchronization +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int aio_fsync(int " op ", struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_fsync () +function does a sync on all outstanding asynchronous I/O operations +associated with +.IR aiocbp\->aio_fildes . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +More precisely, if +.I op +is +.BR O_SYNC , +then all currently queued I/O operations shall be +completed as if by a call of +.BR fsync (2), +and if +.I op +is +.BR O_DSYNC , +this call is the asynchronous analog of +.BR fdatasync (2). +.P +Note that this is a request only; it does not wait for I/O completion. +.P +Apart from +.IR aio_fildes , +the only field in the structure pointed to by +.I aiocbp +that is used by this call is the +.I aio_sigevent +field (a +.I sigevent +structure, described in +.BR sigevent (3type)), +which indicates the desired type of asynchronous notification at completion. +All other fields are ignored. +.SH RETURN VALUE +On success (the sync request was successfully queued) +this function returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EINVAL +Synchronized I/O is not supported for this file, or +.I op +is not +.B O_SYNC +or +.BR O_DSYNC . +.TP +.B ENOSYS +.BR aio_fsync () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_fsync () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR sigevent (3type) diff --git a/man/man3/aio_init.3 b/man/man3/aio_init.3 new file mode 100644 index 0000000..67a58cf --- /dev/null +++ b/man/man3/aio_init.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH aio_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_init \- asynchronous I/O initialization +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include <aio.h>" +.P +.BI "void aio_init(const struct aioinit *" init ); +.fi +.SH DESCRIPTION +The GNU-specific +.BR aio_init () +function allows the caller to provide tuning hints to the +glibc POSIX AIO implementation. +Use of this function is optional, but to be effective, +it must be called before employing any other functions in the POSIX AIO API. +.P +The tuning information is provided in the buffer pointed to by the argument +.IR init . +This buffer is a structure of the following form: +.P +.in +4n +.EX +struct aioinit { + int aio_threads; /* Maximum number of threads */ + int aio_num; /* Number of expected simultaneous + requests */ + int aio_locks; /* Not used */ + int aio_usedba; /* Not used */ + int aio_debug; /* Not used */ + int aio_numusers; /* Not used */ + int aio_idle_time; /* Number of seconds before idle thread + terminates (since glibc 2.2) */ + int aio_reserved; +}; +.EE +.in +.P +The following fields are used in the +.I aioinit +structure: +.TP +.I aio_threads +This field specifies the maximum number of worker threads that +may be used by the implementation. +If the number of outstanding I/O operations exceeds this limit, +then excess operations will be queued until a worker thread becomes free. +If this field is specified with a value less than 1, the value 1 is used. +The default value is 20. +.TP +.I aio_num +This field should specify the maximum number of simultaneous I/O requests +that the caller expects to enqueue. +If a value less than 32 is specified for this field, +it is rounded up to 32. +.\" FIXME . But, if aio_num > 32, the behavior looks strange. See +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12083 +The default value is 64. +.TP +.I aio_idle_time +This field specifies the amount of time in seconds that a +worker thread should wait for further requests before terminating, +after having completed a previous request. +The default value is 1. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR aio (7) diff --git a/man/man3/aio_read.3 b/man/man3/aio_read.3 new file mode 100644 index 0000000..66d1b66 --- /dev/null +++ b/man/man3/aio_read.3 @@ -0,0 +1,159 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_read 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_read \- asynchronous read +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int aio_read(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_read () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR read (2). +The arguments of the call +.P +.in +4n +.EX +read(fd, buf, count) +.EE +.in +.P +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.I aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +The data is read starting at the absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +After the call, +the value of the file offset is unspecified. +.P +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the read may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained by +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.I aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (3type) +for details. +.P +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.P +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.P +No data is read from a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set to indicate the error. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\[em]whatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for reading. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +or +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_read () +is not implemented. +.TP +.B EOVERFLOW +The file is a regular file, we start reading before end-of-file +and want at least one byte, but the starting position is past +the maximum offset for this file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_read () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the read operation +is in progress. +The buffer area being read into +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_return.3 b/man/man3/aio_return.3 new file mode 100644 index 0000000..c3bd55f --- /dev/null +++ b/man/man3/aio_return.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_return 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_return \- get return status of asynchronous I/O operation +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "ssize_t aio_return(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_return () +function returns the final return status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +This function should be called only once for any given request, after +.BR aio_error (3) +returns something other than +.BR EINPROGRESS . +.SH RETURN VALUE +If the asynchronous I/O operation has completed, this function returns +the value that would have been returned in case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2), +or +.BR fdatasync (2), +call. +On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. +.P +If the asynchronous I/O operation has not yet completed, +the return value and effect of +.BR aio_return () +are undefined. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_return () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_return () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_suspend.3 b/man/man3/aio_suspend.3 new file mode 100644 index 0000000..a011534 --- /dev/null +++ b/man/man3/aio_suspend.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2010 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_suspend 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_suspend \- wait for asynchronous I/O operation or timeout +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.P +.B "#include <aio.h>" +.P +.BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems , +.BI " const struct timespec *restrict " timeout ); +.fi +.SH DESCRIPTION +The +.BR aio_suspend () +function suspends the calling thread until one of the following occurs: +.IP \[bu] 3 +One or more of the asynchronous I/O requests in the list +.I aiocb_list +has completed. +.IP \[bu] +A signal is delivered. +.IP \[bu] +.I timeout +is not NULL and the specified time interval has passed. +(For details of the +.I timespec +structure, see +.BR nanosleep (2).) +.P +The +.I nitems +argument specifies the number of items in +.IR aiocb_list . +Each item in the list pointed to by +.I aiocb_list +must be either NULL (and then is ignored), +or a pointer to a control block on which I/O was initiated using +.BR aio_read (3), +.BR aio_write (3), +or +.BR lio_listio (3). +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +If +.B CLOCK_MONOTONIC +is supported, this clock is used to measure +the timeout interval (see +.BR clock_gettime (2)). +.SH RETURN VALUE +If this function returns after completion of one of the I/O +requests specified in +.IR aiocb_list , +0 is returned. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The call timed out before any of the indicated operations +had completed. +.TP +.B EINTR +The call was ended by signal +(possibly the completion signal of one of the operations we were +waiting for); see +.BR signal (7). +.TP +.B ENOSYS +.BR aio_suspend () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_suspend () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +POSIX doesn't specify the parameters to be +.IR restrict ; +that is specific to glibc. +.SH NOTES +One can achieve polling by using a non-NULL +.I timeout +that specifies a zero time interval. +.P +If one or more of the asynchronous I/O operations specified in +.I aiocb_list +has already completed at the time of the call to +.BR aio_suspend (), +then the call returns immediately. +.P +To determine which I/O operations have completed +after a successful return from +.BR aio_suspend (), +use +.BR aio_error (3) +to scan the list of +.I aiocb +structures pointed to by +.IR aiocb_list . +.SH BUGS +The glibc implementation of +.BR aio_suspend () +is not async-signal-safe, +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 +in violation of the requirements of POSIX.1. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR time (7) diff --git a/man/man3/aio_write.3 b/man/man3/aio_write.3 new file mode 100644 index 0000000..800ff3b --- /dev/null +++ b/man/man3/aio_write.3 @@ -0,0 +1,161 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_write 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_write \- asynchronous write +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int aio_write(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_write () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR write (2). +The arguments of the call +.P +.in +4n +.EX +write(fd, buf, count) +.EE +.in +.P +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.I aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +If +.B O_APPEND +is not set, the data is written starting at the +absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +If +.B O_APPEND +is set, data is written at the end of the file in the same order as +.BR aio_write () +calls are made. +After the call, the value of the file offset is unspecified. +.P +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the write may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.I aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (3type) +for details. +.P +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.P +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.P +No data is written to a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set to indicate the error. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\[em]whatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EFBIG +The file is a regular file, we want to write at least one byte, +but the starting position is at or beyond the maximum offset for this file. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_write () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_write () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the write operation +is in progress. +The buffer area being written out +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/aligned_alloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/alloca.3 b/man/man3/alloca.3 new file mode 100644 index 0000000..934825f --- /dev/null +++ b/man/man3/alloca.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 +.\" +.\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2002-07-17, aeb +.\" 2008-01-24, mtk: +.\" Various rewrites and additions (notes on longjmp() and SIGSEGV). +.\" Weaken warning against use of alloca() (as per Debian bug 461100). +.\" +.TH alloca 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +alloca \- allocate memory that is automatically freed +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <alloca.h> +.P +.BI "void *alloca(size_t " size ); +.fi +.SH DESCRIPTION +The +.BR alloca () +function allocates +.I size +bytes of space in the stack frame of the caller. +This temporary space is +automatically freed when the function that called +.BR alloca () +returns to its caller. +.SH RETURN VALUE +The +.BR alloca () +function returns a pointer to the beginning of the allocated space. +If the allocation causes stack overflow, program behavior is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR alloca () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +PWB, 32V. +.SH NOTES +The +.BR alloca () +function is machine- and compiler-dependent. +Because it allocates from the stack, it's faster than +.BR malloc (3) +and +.BR free (3). +In certain cases, +it can also simplify memory deallocation in applications that use +.BR longjmp (3) +or +.BR siglongjmp (3). +Otherwise, its use is discouraged. +.P +Because the space allocated by +.BR alloca () +is allocated within the stack frame, +that space is automatically freed if the function return +is jumped over by a call to +.BR longjmp (3) +or +.BR siglongjmp (3). +.P +The space allocated by +.BR alloca () +is +.I not +automatically deallocated if the pointer that refers to it +simply goes out of scope. +.P +Do not attempt to +.BR free (3) +space allocated by +.BR alloca ()! +.P +By necessity, +.BR alloca () +is a compiler built-in, also known as +.BR __builtin_alloca (). +By default, modern compilers automatically translate all uses of +.BR alloca () +into the built-in, but this is forbidden if standards conformance is requested +.RI ( "\-ansi" , +.IR "\-std=c*" ), +in which case +.I <alloca.h> +is required, lest a symbol dependency be emitted. +.P +The fact that +.BR alloca () +is a built-in means it is impossible to take its address +or to change its behavior by linking with a different library. +.P +Variable length arrays (VLAs) are part of the C99 standard, +optional since C11, and can be used for a similar purpose. +However, they do not port to standard C++, and, being variables, +live in their block scope and don't have an allocator-like interface, +making them unfit for implementing functionality like +.BR strdupa (3). +.SH BUGS +Due to the nature of the stack, it is impossible to check if the allocation +would overflow the space available, and, hence, neither is indicating an error. +(However, the program is likely to receive a +.B SIGSEGV +signal if it attempts to access unavailable space.) +.P +On many systems +.BR alloca () +cannot be used inside the list of arguments of a function call, because +the stack space reserved by +.BR alloca () +would appear on the stack in the middle of the space for the +function arguments. +.SH SEE ALSO +.BR brk (2), +.BR longjmp (3), +.BR malloc (3) diff --git a/man/man3/alphasort.3 b/man/man3/alphasort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/alphasort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/arc4random.3 b/man/man3/arc4random.3 new file mode 100644 index 0000000..44e6674 --- /dev/null +++ b/man/man3/arc4random.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH arc4random 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +arc4random, arc4random_uniform, arc4random_buf +\- cryptographically-secure pseudorandom number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B uint32_t arc4random(void); +.BI "uint32_t arc4random_uniform(uint32_t " upper_bound ); +.BI "void arc4random_buf(void " buf [. n "], size_t " n ); +.fi +.SH DESCRIPTION +These functions give cryptographically-secure pseudorandom numbers. +.P +.BR arc4random () +returns a uniformly-distributed value. +.P +.BR arc4random_uniform () +returns a uniformly-distributed value less than +.I upper_bound +(see BUGS). +.P +.BR arc4random_buf () +fills the memory pointed to by +.IR buf , +with +.I n +bytes of pseudorandom data. +.P +The +.BR rand (3) +and +.BR drand48 (3) +families of functions should only be used where +the quality of the pseudorandom numbers is not a concern +.I and +there's a need for repeatability of the results. +Unless you meet both of those conditions, +use the +.BR arc4random () +functions. +.SH RETURN VALUE +.BR arc4random () +returns a pseudorandom number. +.P +.BR arc4random_uniform () +returns a pseudorandom number less than +.I upper_bound +for valid input, or +.B 0 +when +.I upper_bound +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH HISTORY +OpenBSD 2.1, +FreeBSD 3.0, +NetBSD 1.6, +DragonFly 1.0, +libbsd, +glibc 2.36. +.SH BUGS +An +.I upper_bound +of +.B 0 +doesn't make sense in a call to +.BR arc4random_uniform (). +Such a call will fail, and return +.BR 0 . +Be careful, +since that value is +.I not +less than +.IR upper_bound . +In some cases, +such as accessing an array, +using that value could result in Undefined Behavior. +.SH SEE ALSO +.BR getrandom (3), +.BR rand (3), +.BR drand48 (3), +.BR random (7) diff --git a/man/man3/arc4random_buf.3 b/man/man3/arc4random_buf.3 new file mode 100644 index 0000000..74a34ce --- /dev/null +++ b/man/man3/arc4random_buf.3 @@ -0,0 +1 @@ +.so man3/arc4random.3 diff --git a/man/man3/arc4random_uniform.3 b/man/man3/arc4random_uniform.3 new file mode 100644 index 0000000..74a34ce --- /dev/null +++ b/man/man3/arc4random_uniform.3 @@ -0,0 +1 @@ +.so man3/arc4random.3 diff --git a/man/man3/argz.3 b/man/man3/argz.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_add.3 b/man/man3/argz_add.3 new file mode 100644 index 0000000..0e8f468 --- /dev/null +++ b/man/man3/argz_add.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH argz_add 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +argz_add, argz_add_sep, argz_append, argz_count, argz_create, +argz_create_sep, argz_delete, argz_extract, argz_insert, +argz_next, argz_replace, argz_stringify \- functions to handle an argz list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <argz.h>" +.P +.BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len , +.BI " const char *restrict " str ); +.P +.BI "error_t argz_add_sep(char **restrict " argz \ +", size_t *restrict " argz_len , +.BI " const char *restrict " str ", int " delim ); +.P +.BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len , +.BI " const char *restrict " buf ", size_t " buf_len ); +.P +.BI "size_t argz_count(const char *" argz ", size_t " argz_len ); +.P +.BI "error_t argz_create(char *const " argv "[], char **restrict " argz , +.BI " size_t *restrict " argz_len ); +.P +.BI "error_t argz_create_sep(const char *restrict " str ", int " sep , +.BI " char **restrict " argz ", size_t *restrict " argz_len ); +.P +.BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len , +.BI " char *restrict " entry ); +.P +.BI "void argz_extract(const char *restrict " argz ", size_t " argz_len , +.BI " char **restrict " argv ); +.P +.BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len , +.BI " char *restrict " before ", const char *restrict " entry ); +.P +.BI "char *argz_next(const char *restrict " argz ", size_t " argz_len , +.BI " const char *restrict " entry ); +.P +.BI "error_t argz_replace(char **restrict " argz \ +", size_t *restrict " argz_len , +.BI " const char *restrict " str ", const char *restrict " with , +.BI " unsigned int *restrict " replace_count ); +.P +.BI "void argz_stringify(char *" argz ", size_t " len ", int " sep ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.P +An argz vector is a pointer to a character buffer together with a length. +The intended interpretation of the character buffer is an array +of strings, where the strings are separated by null bytes (\[aq]\e0\[aq]). +If the length is nonzero, the last byte of the buffer must be a null byte. +.P +These functions are for handling argz vectors. +The pair (NULL,0) is an argz vector, and, conversely, +argz vectors of length 0 must have null pointer. +Allocation of nonempty argz vectors is done using +.BR malloc (3), +so that +.BR free (3) +can be used to dispose of them again. +.P +.BR argz_add () +adds the string +.I str +at the end of the array +.IR *argz , +and updates +.I *argz +and +.IR *argz_len . +.P +.BR argz_add_sep () +is similar, but splits the string +.I str +into substrings separated by the delimiter +.IR delim . +For example, one might use this on a UNIX search path with +delimiter \[aq]:\[aq]. +.P +.BR argz_append () +appends the argz vector +.RI ( buf ,\ buf_len ) +after +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +(Thus, +.I *argz_len +will be increased by +.IR buf_len .) +.P +.BR argz_count () +counts the number of strings, that is, +the number of null bytes (\[aq]\e0\[aq]), in +.RI ( argz ,\ argz_len ). +.P +.BR argz_create () +converts a UNIX-style argument vector +.IR argv , +terminated by +.IR "(char\ *)\ 0" , +into an argz vector +.RI ( *argz ,\ *argz_len ). +.P +.BR argz_create_sep () +converts the null-terminated string +.I str +into an argz vector +.RI ( *argz ,\ *argz_len ) +by breaking it up at every occurrence of the separator +.IR sep . +.P +.BR argz_delete () +removes the substring pointed to by +.I entry +from the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +.P +.BR argz_extract () +is the opposite of +.BR argz_create (). +It takes the argz vector +.RI ( argz ,\ argz_len ) +and fills the array starting at +.I argv +with pointers to the substrings, and a final NULL, +making a UNIX-style argv vector. +The array +.I argv +must have room for +.IR argz_count ( argz ", " argz_len ") + 1" +pointers. +.P +.BR argz_insert () +is the opposite of +.BR argz_delete (). +It inserts the argument +.I entry +at position +.I before +into the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +If +.I before +is NULL, then +.I entry +will inserted at the end. +.P +.BR argz_next () +is a function to step through the argz vector. +If +.I entry +is NULL, the first entry is returned. +Otherwise, the entry +following is returned. +It returns NULL if there is no following entry. +.P +.BR argz_replace () +replaces each occurrence of +.I str +with +.IR with , +reallocating argz as necessary. +If +.I replace_count +is non-NULL, +.I *replace_count +will be incremented by the number of replacements. +.P +.BR argz_stringify () +is the opposite of +.BR argz_create_sep (). +It transforms the argz vector into a normal string by replacing +all null bytes (\[aq]\e0\[aq]) except the last by +.IR sep . +.SH RETURN VALUE +All argz functions that do memory allocation have a return type of +.I error_t +(an integer type), +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR argz_add (), +.BR argz_add_sep (), +.BR argz_append (), +.BR argz_count (), +.BR argz_create (), +.BR argz_create_sep (), +.BR argz_delete (), +.BR argz_extract (), +.BR argz_insert (), +.BR argz_next (), +.BR argz_replace (), +.BR argz_stringify () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH BUGS +Argz vectors without a terminating null byte may lead to +Segmentation Faults. +.SH SEE ALSO +.BR envz_add (3) diff --git a/man/man3/argz_add_sep.3 b/man/man3/argz_add_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_add_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_append.3 b/man/man3/argz_append.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_append.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_count.3 b/man/man3/argz_count.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_count.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_create.3 b/man/man3/argz_create.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_create.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_create_sep.3 b/man/man3/argz_create_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_create_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_delete.3 b/man/man3/argz_delete.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_delete.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_extract.3 b/man/man3/argz_extract.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_extract.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_insert.3 b/man/man3/argz_insert.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_insert.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_next.3 b/man/man3/argz_next.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_next.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_replace.3 b/man/man3/argz_replace.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_replace.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_stringify.3 b/man/man3/argz_stringify.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_stringify.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/asctime.3 b/man/man3/asctime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/asctime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/asctime_r.3 b/man/man3/asctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/asctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/asin.3 b/man/man3/asin.3 new file mode 100644 index 0000000..132d797 --- /dev/null +++ b/man/man3/asin.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH asin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asin, asinf, asinl \- arc sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double asin(double " x ); +.BI "float asinf(float " x ); +.BI "long double asinl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asinf (), +.BR asinl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc sine of +.IR x ; +that is the value whose sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc sine of +.I x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asin (), +.BR asinf (), +.BR asinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR atan (3), +.BR atan2 (3), +.BR casin (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/asinf.3 b/man/man3/asinf.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man/man3/asinf.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man/man3/asinh.3 b/man/man3/asinh.3 new file mode 100644 index 0000000..36e1930 --- /dev/null +++ b/man/man3/asinh.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH asinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asinh, asinhf, asinhl \- inverse hyperbolic sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double asinh(double " x ); +.BI "float asinhf(float " x ); +.BI "long double asinhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asinh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR asinhf (), +.BR asinhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic sine of +.IR x ; +that is the value whose hyperbolic sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asinh (), +.BR asinhf (), +.BR asinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR acosh (3), +.BR atanh (3), +.BR casinh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/asinhf.3 b/man/man3/asinhf.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man/man3/asinhf.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man/man3/asinhl.3 b/man/man3/asinhl.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man/man3/asinhl.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man/man3/asinl.3 b/man/man3/asinl.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man/man3/asinl.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man/man3/asprintf.3 b/man/man3/asprintf.3 new file mode 100644 index 0000000..79d92d5 --- /dev/null +++ b/man/man3/asprintf.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Text fragments inspired by Martin Schulze <joey@infodrom.org>. +.\" +.TH asprintf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asprintf, vasprintf \- print to allocated string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <stdio.h> +.P +.BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);" +.BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt , +.BI " va_list " ap ); +.fi +.SH DESCRIPTION +The functions +.BR asprintf () +and +.BR vasprintf () +are analogs of +.BR sprintf (3) +and +.BR vsprintf (3), +except that they allocate a string large enough to hold the output +including the terminating null byte (\[aq]\e0\[aq]), +and return a pointer to it via the first argument. +This pointer should be passed to +.BR free (3) +to release the allocated storage when it is no longer needed. +.SH RETURN VALUE +When successful, these functions return the number of bytes printed, +just like +.BR sprintf (3). +If memory allocation wasn't possible, or some other error occurs, +these functions will return \-1, and the contents of +.I strp +are undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asprintf (), +.BR vasprintf () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +The FreeBSD implementation sets +.I strp +to NULL on error. +.SH STANDARDS +GNU, BSD. +.SH SEE ALSO +.BR free (3), +.BR malloc (3), +.BR printf (3) diff --git a/man/man3/assert.3 b/man/man3/assert.3 new file mode 100644 index 0000000..f6cc4b6 --- /dev/null +++ b/man/man3/assert.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos <nmav@redhat.com> +.TH assert 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +assert \- abort the program if assertion is false +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <assert.h> +.P +.BI "void assert(scalar " expression ); +.fi +.SH DESCRIPTION +This macro can help programmers find bugs in their programs, +or handle exceptional cases +via a crash that will produce limited debugging output. +.P +If +.I expression +is false (i.e., compares equal to zero), +.BR assert () +prints an error message to standard error +and terminates the program by calling +.BR abort (3). +The error message includes the name of the file and function containing the +.BR assert () +call, the source code line number of the call, and the text of the argument; +something like: +.P +.in +4n +.EX +prog: some_file.c:16: some_func: Assertion \`val == 0\[aq] failed. +.EE +.in +.P +If the macro +.B NDEBUG +is defined at the moment +.I <assert.h> +was last included, the macro +.BR assert () +generates no code, and hence does nothing at all. +It is not recommended to define +.B NDEBUG +if using +.BR assert () +to detect error conditions since the software +may behave non-deterministically. +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR assert () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, C99, POSIX.1-2001. +.P +In C89, +.I expression +is required to be of type +.I int +and undefined behavior results if it is not, but in C99 +it may have any scalar type. +.\" See Defect Report 107 for more details. +.SH BUGS +.BR assert () +is implemented as a macro; if the expression tested has side-effects, +program behavior will be different depending on whether +.B NDEBUG +is defined. +This may create Heisenbugs which go away when debugging +is turned on. +.SH SEE ALSO +.BR abort (3), +.BR assert_perror (3), +.BR exit (3) diff --git a/man/man3/assert_perror.3 b/man/man3/assert_perror.3 new file mode 100644 index 0000000..c2fcb59 --- /dev/null +++ b/man/man3/assert_perror.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de>. +.\" +.TH assert_perror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +assert_perror \- test errnum and abort +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <assert.h> +.P +.BI "void assert_perror(int " errnum ); +.fi +.SH DESCRIPTION +If the macro +.B NDEBUG +was defined at the moment +.I <assert.h> +was last included, the macro +.BR assert_perror () +generates no code, and hence does nothing at all. +Otherwise, the macro +.BR assert_perror () +prints an error message to standard error and terminates the program +by calling +.BR abort (3) +if +.I errnum +is nonzero. +The message contains the filename, function name and +line number of the macro call, and the output of +.IR strerror(errnum) . +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR assert_perror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH BUGS +The purpose of the assert macros is to help programmers find bugs in +their programs, things that cannot happen unless there was a coding mistake. +However, with system or library calls the situation is rather different, +and error returns can happen, and will happen, and should be tested for. +Not by an assert, where the test goes away when +.B NDEBUG +is defined, +but by proper error handling code. +Never use this macro. +.SH SEE ALSO +.BR abort (3), +.BR assert (3), +.BR exit (3), +.BR strerror (3) diff --git a/man/man3/atan.3 b/man/man3/atan.3 new file mode 100644 index 0000000..b5b101e --- /dev/null +++ b/man/man3/atan.3 @@ -0,0 +1,103 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atan, atanf, atanl \- arc tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double atan(double " x ); +.BI "float atanf(float " x ); +.BI "long double atanl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atanf (), +.BR atanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR x ; +that is the value whose tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.I x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +pi/2 (\-pi/2) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atan (), +.BR atanf (), +.BR atanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan2 (3), +.BR carg (3), +.BR catan (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/atan2.3 b/man/man3/atan2.3 new file mode 100644 index 0000000..d51c4db --- /dev/null +++ b/man/man3/atan2.3 @@ -0,0 +1,174 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atan2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atan2, atan2f, atan2l \- arc tangent function of two variables +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double atan2(double " y ", double " x ); +.BI "float atan2f(float " y ", float " x ); +.BI "long double atan2l(long double " y ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atan2f (), +.BR atan2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR y/x , +using the signs of the two arguments to determine +the quadrant of the result. +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.I y/x +in radians; the return value is in the range [\-pi,\ pi]. +.P +If +.I y +is +0 (\-0) and +.I x +is less than 0, +pi (\-pi) is returned. +.P +If +.I y +is +0 (\-0) and +.I x +is greater than 0, +0 (\-0) is returned. +.P +If +.I y +is less than 0 and +.I x +is +0 or \-0, \-pi/2 is returned. +.P +If +.I y +is greater than 0 and +.I x +is +0 or \-0, pi/2 is returned. +.P +.\" POSIX.1 says: +.\" If +.\" .I x +.\" is 0, a pole error shall not occur. +.\" +If either +.I x +or +.I y +is NaN, a NaN is returned. +.P +.\" POSIX.1 says: +.\" If the result underflows, a range error may occur and +.\" .I y/x +.\" should be returned. +.\" +If +.I y +is +0 (\-0) and +.I x +is \-0, +pi (\-pi) is returned. +.P +If +.I y +is +0 (\-0) and +.I x +is +0, +0 (\-0) is returned. +.P +If +.I y +is a finite value greater (less) than 0, and +.I x +is negative infinity, +pi (\-pi) is returned. +.P +If +.I y +is a finite value greater (less) than 0, and +.I x +is positive infinity, +0 (\-0) is returned. +.P +If +.I y +is positive infinity (negative infinity), and +.I x +is finite, +pi/2 (\-pi/2) is returned. +.P +If +.I y +is positive infinity (negative infinity) and +.I x +is negative infinity, +3*pi/4 (\-3*pi/4) is returned. +.P +If +.I y +is positive infinity (negative infinity) and +.I x +is positive infinity, +pi/4 (\-pi/4) is returned. +.\" +.\" POSIX.1 says: +.\" If both arguments are 0, a domain error shall not occur. +.SH ERRORS +No errors occur. +.\" POSIX.1 documents an optional underflow error +.\" glibc 2.8 does not do this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atan2 (), +.BR atan2f (), +.BR atan2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR carg (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/atan2f.3 b/man/man3/atan2f.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man/man3/atan2f.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man/man3/atan2l.3 b/man/man3/atan2l.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man/man3/atan2l.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man/man3/atanf.3 b/man/man3/atanf.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man/man3/atanf.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man/man3/atanh.3 b/man/man3/atanh.3 new file mode 100644 index 0000000..bf36b7f --- /dev/null +++ b/man/man3/atanh.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atanh, atanhf, atanhl \- inverse hyperbolic tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double atanh(double " x ); +.BI "float atanhf(float " x ); +.BI "long double atanhl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atanh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR atanhf (), +.BR atanhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic tangent of +.IR x ; +that is the value whose hyperbolic tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is +1 or \-1, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.P +If the absolute value of +.I x +is greater than 1, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-1 or greater than +1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is +1 or \-1 +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atanh (), +.BR atanhf (), +.BR atanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc 2.9 and earlier, +.\" Bug: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6759 +.\" This can be seen in sysdeps/ieee754/k_standard.c +when a pole error occurs, +.I errno +is set to +.B EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, glibc does the right thing. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR catanh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/atanhf.3 b/man/man3/atanhf.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man/man3/atanhf.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man/man3/atanhl.3 b/man/man3/atanhl.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man/man3/atanhl.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man/man3/atanl.3 b/man/man3/atanl.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man/man3/atanl.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man/man3/atexit.3 b/man/man3/atexit.3 new file mode 100644 index 0000000..15ada04 --- /dev/null +++ b/man/man3/atexit.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-10-25, Walter Harms +.\" +.TH atexit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atexit \- register a function to be called at normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int atexit(void (*" function )(void)); +.fi +.SH DESCRIPTION +The +.BR atexit () +function registers the given +.I function +to be +called at normal process termination, either via +.BR exit (3) +or via return from the program's +.IR main (). +Functions so registered are called in +the reverse order of their registration; no arguments are passed. +.P +The same function may be registered multiple times: +it is called once for each registration. +.P +POSIX.1 requires that an implementation allow at least +.\" POSIX.1-2001, POSIX.1-2008 +.B ATEXIT_MAX +(32) such functions to be registered. +The actual limit supported by an implementation can be obtained using +.BR sysconf (3). +.P +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, +all registrations are removed. +.SH RETURN VALUE +The +.BR atexit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atexit () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 says that the result of calling +.\" POSIX.1-2001, POSIX.1-2008 +.BR exit (3) +more than once (i.e., calling +.BR exit (3) +within a function registered using +.BR atexit ()) +is undefined. +On some systems (but not Linux), this can result in an infinite recursion; +.\" This can happen on OpenBSD 4.2 for example, and is documented +.\" as occurring on FreeBSD as well. +.\" glibc does "the Right Thing" -- invocation of the remaining +.\" exit handlers carries on as normal. +portable programs should not invoke +.BR exit (3) +inside a function registered using +.BR atexit (). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Functions registered using +.BR atexit () +(and +.BR on_exit (3)) +are not called if a process terminates abnormally because +of the delivery of a signal. +.P +If one of the registered functions calls +.BR _exit (2), +then any remaining functions are not invoked, +and the other process termination steps performed by +.BR exit (3) +are not performed. +.P +The +.BR atexit () +and +.BR on_exit (3) +functions register functions on the same list: +at normal process termination, +the registered functions are invoked in reverse order +of their registration by these two functions. +.P +According to POSIX.1, the result is undefined if +.BR longjmp (3) +is used to terminate execution of one of the functions registered using +.BR atexit (). +.\" In glibc, things seem to be handled okay +.SS Linux notes +Since glibc 2.2.3, +.BR atexit () +(and +.BR on_exit (3)) +can be used within a shared library to establish functions +that are called when the shared library is unloaded. +.SH EXAMPLES +.\" SRC BEGIN (atexit.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +void +bye(void) +{ + printf("That was all, folks\en"); +} +\& +int +main(void) +{ + long a; + int i; +\& + a = sysconf(_SC_ATEXIT_MAX); + printf("ATEXIT_MAX = %ld\en", a); +\& + i = atexit(bye); + if (i != 0) { + fprintf(stderr, "cannot set exit function\en"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR _exit (2), +.BR dlopen (3), +.BR exit (3), +.BR on_exit (3) diff --git a/man/man3/atof.3 b/man/man3/atof.3 new file mode 100644 index 0000000..a626b63 --- /dev/null +++ b/man/man3/atof.3 @@ -0,0 +1,67 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:24 1993, David Metcalfe +.\" Modified Sat Jul 24 21:39:22 1993, Rik Faith (faith@cs.unc.edu) +.TH atof 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atof \- convert a string to a double +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "double atof(const char *" nptr ); +.fi +.SH DESCRIPTION +The +.BR atof () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR double . +The behavior is the same as +.P +.in +4n +.EX +strtod(nptr, NULL); +.EE +.in +.P +except that +.BR atof () +does not detect errors. +.SH RETURN VALUE +The converted value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atof () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR atoi (3), +.BR atol (3), +.BR strfromd (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/atoi.3 b/man/man3/atoi.3 new file mode 100644 index 0000000..3df2e6b --- /dev/null +++ b/man/man3/atoi.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:41 1993, David Metcalfe +.\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers +.\" +.TH atoi 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atoi, atol, atoll \- convert a string to an integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int atoi(const char *" nptr ); +.BI "long atol(const char *" nptr ); +.BI "long long atoll(const char *" nptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atoll (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR atoi () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR int . +The behavior is the same as +.P +.in +4n +.EX +strtol(nptr, NULL, 10); +.EE +.in +.P +except that +.BR atoi () +does not detect errors. +.P +The +.BR atol () +and +.BR atoll () +functions behave the same as +.BR atoi (), +except that they convert the initial portion of the +string to their return type of \fIlong\fP or \fIlong long\fP. +.SH RETURN VALUE +The converted value or 0 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atoi (), +.BR atol (), +.BR atoll () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +POSIX.1 leaves the return value of +.BR atoi () +on error unspecified. +On glibc, musl libc, and uClibc, 0 is returned on error. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001, SVr4, 4.3BSD. +.P +C89 and +POSIX.1-1996 include the functions +.BR atoi () +and +.BR atol () +only. +.\" .SH NOTES +.\" Linux libc provided +.\" .BR atoq () +.\" as an obsolete name for +.\" .BR atoll (); +.\" .BR atoq () +.\" is not provided by glibc. +.\" The +.\" .BR atoll () +.\" function is present since glibc 2.0.2, but +.\" not in libc4 or libc5. +.SH BUGS +.I errno +is not set on error so there is no way to distinguish between 0 as an +error and as the converted value. +No checks for overflow or underflow are done. +Only base-10 input can be converted. +It is recommended to instead use the +.BR strtol () +and +.BR strtoul () +family of functions in new programs. +.SH SEE ALSO +.BR atof (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/atol.3 b/man/man3/atol.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atol.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/atoll.3 b/man/man3/atoll.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atoll.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/atoq.3 b/man/man3/atoq.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atoq.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/auth_destroy.3 b/man/man3/auth_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/auth_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authnone_create.3 b/man/man3/authnone_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authnone_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authunix_create.3 b/man/man3/authunix_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authunix_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authunix_create_default.3 b/man/man3/authunix_create_default.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authunix_create_default.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/backtrace.3 b/man/man3/backtrace.3 new file mode 100644 index 0000000..04762c5 --- /dev/null +++ b/man/man3/backtrace.3 @@ -0,0 +1,283 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH backtrace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +backtrace, backtrace_symbols, backtrace_symbols_fd \- support +for application self-debugging +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <execinfo.h> +.P +.BI "int backtrace(void *" buffer [. size "], int " size ); +.P +.BI "char **backtrace_symbols(void *const " buffer [. size "], int " size ); +.BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \ +int " fd ); +.fi +.SH DESCRIPTION +.BR backtrace () +returns a backtrace for the calling program, +in the array pointed to by +.IR buffer . +A backtrace is the series of currently active function calls for +the program. +Each item in the array pointed to by +.I buffer +is of type +.IR "void\ *" , +and is the return address from +the corresponding stack frame. +The +.I size +argument specifies the maximum number of addresses +that can be stored in +.IR buffer . +If the backtrace is larger than +.IR size , +then the addresses corresponding to the +.I size +most recent function calls are returned; +to obtain the complete backtrace, make sure that +.I buffer +and +.I size +are large enough. +.P +Given the set of addresses returned by +.BR backtrace () +in +.IR buffer , +.BR backtrace_symbols () +translates the addresses into an array of strings that describe +the addresses symbolically. +The +.I size +argument specifies the number of addresses in +.IR buffer . +The symbolic representation of each address consists of the function name +(if this can be determined), a hexadecimal offset into the function, +and the actual return address (in hexadecimal). +The address of the array of string pointers is returned +as the function result of +.BR backtrace_symbols (). +This array is +.BR malloc (3)ed +by +.BR backtrace_symbols (), +and must be freed by the caller. +(The strings pointed to by the array of pointers +need not and should not be freed.) +.P +.BR backtrace_symbols_fd () +takes the same +.I buffer +and +.I size +arguments as +.BR backtrace_symbols (), +but instead of returning an array of strings to the caller, +it writes the strings, one per line, to the file descriptor +.IR fd . +.BR backtrace_symbols_fd () +does not call +.BR malloc (3), +and so can be employed in situations where the latter function might +fail, but see NOTES. +.SH RETURN VALUE +.BR backtrace () +returns the number of addresses returned in +.IR buffer , +which is not greater than +.IR size . +If the return value is less than +.IR size , +then the full backtrace was stored; if it is equal to +.IR size , +then it may have been truncated, in which case the addresses of the +oldest stack frames are not returned. +.P +On success, +.BR backtrace_symbols () +returns a pointer to the array +.BR malloc (3)ed +by the call; +on error, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR backtrace (), +.BR backtrace_symbols (), +.BR backtrace_symbols_fd () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH NOTES +These functions make some assumptions about how a function's return +address is stored on the stack. +Note the following: +.IP \[bu] 3 +Omission of the frame pointers (as +implied by any of +.BR gcc (1)'s +nonzero optimization levels) may cause these assumptions to be +violated. +.IP \[bu] +Inlined functions do not have stack frames. +.IP \[bu] +Tail-call optimization causes one stack frame to replace another. +.IP \[bu] +.BR backtrace () +and +.BR backtrace_symbols_fd () +don't call +.BR malloc () +explicitly, but they are part of +.IR libgcc , +which gets loaded dynamically when first used. +Dynamic loading usually triggers a call to +.BR malloc (3). +If you need certain calls to these two functions to not allocate memory +(in signal handlers, for example), you need to make sure +.I libgcc +is loaded beforehand. +.P +The symbol names may be unavailable without the use of special linker +options. +For systems using the GNU linker, it is necessary to use the +.I \-rdynamic +linker option. +Note that names of "static" functions are not exposed, +and won't be available in the backtrace. +.SH EXAMPLES +The program below demonstrates the use of +.BR backtrace () +and +.BR backtrace_symbols (). +The following shell session shows what we might see when running the +program: +.P +.in +4n +.EX +.RB "$" " cc \-rdynamic prog.c \-o prog" +.RB "$" " ./prog 3" +backtrace() returned 8 addresses +\&./prog(myfunc3+0x5c) [0x80487f0] +\&./prog [0x8048871] +\&./prog(myfunc+0x21) [0x8048894] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(main+0x65) [0x80488fb] +\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c] +\&./prog [0x8048711] +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (backtrace.c) +.EX +#include <execinfo.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define BT_BUF_SIZE 100 +\& +void +myfunc3(void) +{ + int nptrs; + void *buffer[BT_BUF_SIZE]; + char **strings; +\& + nptrs = backtrace(buffer, BT_BUF_SIZE); + printf("backtrace() returned %d addresses\en", nptrs); +\& + /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) + would produce similar output to the following: */ +\& + strings = backtrace_symbols(buffer, nptrs); + if (strings == NULL) { + perror("backtrace_symbols"); + exit(EXIT_FAILURE); + } +\& + for (size_t j = 0; j < nptrs; j++) + printf("%s\en", strings[j]); +\& + free(strings); +} +\& +static void /* "static" means don\[aq]t export the symbol... */ +myfunc2(void) +{ + myfunc3(); +} +\& +void +myfunc(int ncalls) +{ + if (ncalls > 1) + myfunc(ncalls \- 1); + else + myfunc2(); +} +\& +int +main(int argc, char *argv[]) +{ + if (argc != 2) { + fprintf(stderr, "%s num\-calls\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + myfunc(atoi(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR addr2line (1), +.BR gcc (1), +.BR gdb (1), +.BR ld (1), +.BR dlopen (3), +.BR malloc (3) diff --git a/man/man3/backtrace_symbols.3 b/man/man3/backtrace_symbols.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man/man3/backtrace_symbols.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man/man3/backtrace_symbols_fd.3 b/man/man3/backtrace_symbols_fd.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man/man3/backtrace_symbols_fd.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man/man3/basename.3 b/man/man3/basename.3 new file mode 100644 index 0000000..5d1e7fc --- /dev/null +++ b/man/man3/basename.3 @@ -0,0 +1,187 @@ +'\" t +.\" Copyright (c) 2000 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH basename 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +basename, dirname \- parse pathname components +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <libgen.h> +.P +.BI "char *dirname(char *" path ); +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.BR basename (); +see below. +.P +The functions +.BR dirname () +and +.BR basename () +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.BR dirname () +returns the string up to, but not including, the final \[aq]/\[aq], and +.BR basename () +returns the component following the final \[aq]/\[aq]. +Trailing \[aq]/\[aq] characters are not counted as part of the pathname. +.P +If +.I path +does not contain a slash, +.BR dirname () +returns the string "." while +.BR basename () +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.BR dirname () +and +.BR basename () +return the string "/". +If +.I path +is a null pointer or points to an empty string, then both +.BR dirname () +and +.BR basename () +return the string ".". +.P +Concatenating the string returned by +.BR dirname (), +a "/", and the string returned by +.BR basename () +yields a complete pathname. +.P +Both +.BR dirname () +and +.BR basename () +may modify the contents of +.IR path , +so it may be desirable to pass a copy when calling one of +these functions. +.P +These functions may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +Alternatively, they may return a pointer to some part of +.IR path , +so that the string referred to by +.I path +should not be modified or freed until the pointer returned by +the function is no longer required. +.P +The following list of examples (taken from SUSv2) +shows the strings returned by +.BR dirname () +and +.BR basename () +for different paths: +.RS +.TS +lb lb lb +l l l l. +path dirname basename +/usr/lib /usr lib +/usr/ / usr +usr . usr +/ / / +\&. . . +\&.. . .. +.TE +.RE +.SH RETURN VALUE +Both +.BR dirname () +and +.BR basename () +return pointers to null-terminated strings. +(Do not pass these pointers to +.BR free (3).) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR basename (), +.BR dirname () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +There are two different versions of +.BR basename () +- the POSIX version described above, and the GNU version, which one gets +after +.P +.in +4n +.EX +.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B " #include <string.h>" +.EE +.in +.P +The GNU version never modifies its argument, and returns the +empty string when +.I path +has a trailing slash, and in particular also when it is "/". +There is no GNU version of +.BR dirname (). +.P +With glibc, one gets the POSIX version of +.BR basename () +when +.I <libgen.h> +is included, and the GNU version otherwise. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +In the glibc implementation, +the POSIX versions of these functions modify the +.I path +argument, and segfault when called with a static string +such as "/usr/". +.P +Before glibc 2.2.1, the glibc version of +.BR dirname () +did not correctly handle pathnames with trailing \[aq]/\[aq] characters, +and generated a segfault if given a NULL argument. +.SH EXAMPLES +The following code snippet demonstrates the use of +.BR basename () +and +.BR dirname (): +.in +4n +.EX +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; +\& +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\en", dname, bname); +.EE +.in +.SH SEE ALSO +.BR basename (1), +.BR dirname (1) diff --git a/man/man3/bcmp.3 b/man/man3/bcmp.3 new file mode 100644 index 0000000..4c509de --- /dev/null +++ b/man/man3/bcmp.3 @@ -0,0 +1,30 @@ +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcmp \- compare byte sequences +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "[[deprecated]] int bcmp(const void " s1 [. n "], const void " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +.BR bcmp () +is identical to +.BR memcmp (3); +use the latter instead. +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +Marked as LEGACY in POSIX.1-2001; +removed in POSIX.1-2008. +.SH SEE ALSO +.BR memcmp (3) diff --git a/man/man3/bcopy.3 b/man/man3/bcopy.3 new file mode 100644 index 0000000..5688b6f --- /dev/null +++ b/man/man3/bcopy.3 @@ -0,0 +1,76 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sun Feb 26 14:52:00 1995 by Rik Faith <faith@cs.unc.edu> +.\" Modified Tue Oct 22 23:48:10 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" " +.TH bcopy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcopy \- copy byte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "[[deprecated]] void bcopy(const void " src [. n "], void " dest [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bcopy () +function copies +.I n +bytes from +.I src +to +.IR dest . +The result is correct, even when both areas overlap. +.SH RETURN VALUE +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bcopy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.P +Marked as LEGACY in POSIX.1-2001: use +.BR memcpy (3) +or +.BR memmove (3) +in new programs. +Note that the first two arguments +are interchanged for +.BR memcpy (3) +and +.BR memmove (3). +POSIX.1-2008 removes the specification of +.BR bcopy (). +.SH SEE ALSO +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man/man3/be16toh.3 b/man/man3/be16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/be32toh.3 b/man/man3/be32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/be64toh.3 b/man/man3/be64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/bindresvport.3 b/man/man3/bindresvport.3 new file mode 100644 index 0000000..1eef397 --- /dev/null +++ b/man/man3/bindresvport.3 @@ -0,0 +1,116 @@ +'\" t +.\" Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-05-31, mtk: Rewrite and substantial additional text. +.\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors +.\" +.TH bindresvport 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bindresvport \- bind a socket to a privileged IP port +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <netinet/in.h> +.P +.BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin ); +.fi +.SH DESCRIPTION +.BR bindresvport () +is used to bind the socket referred to by the +file descriptor +.I sockfd +to a privileged anonymous IP port, +that is, a port number arbitrarily selected from the range 512 to 1023. +.\" glibc actually starts searching with a port # in the range 600 to 1023 +.P +If the +.BR bind (2) +performed by +.BR bindresvport () +is successful, and +.I sin +is not NULL, then +.I sin\->sin_port +returns the port number actually allocated. +.P +.I sin +can be NULL, in which case +.I sin\->sin_family +is implicitly taken to be +.BR AF_INET . +However, in this case, +.BR bindresvport () +has no way to return the port number actually allocated. +(This information can later be obtained using +.BR getsockname (2).) +.SH RETURN VALUE +.BR bindresvport () +returns 0 on success; otherwise \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR bindresvport () +can fail for any of the same reasons as +.BR bind (2). +In addition, the following errors may occur: +.TP +.B EACCES +The calling process was not privileged +(on Linux: the calling process did not have the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace). +.TP +.B EADDRINUSE +All privileged ports are in use. +.TP +.BR EAFNOSUPPORT " (" EPFNOSUPPORT " in glibc 2.7 and earlier)" +.I sin +is not NULL and +.I sin\->sin_family +is not +.BR AF_INET . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bindresvport () +T} Thread safety T{ +.na +.nh +glibc\ >=\ 2.17: MT-Safe; +.\" commit f6da27e53695ad1cc0e2a9490358decbbfdff5e5 +glibc\ <\ 2.17: MT-Unsafe +T} +.TE +.P +The +.BR bindresvport () +function uses a static variable that was not protected by a lock +before glibc 2.17, rendering the function MT-Unsafe. +.SH VERSIONS +Present on the BSDs, Solaris, and many other systems. +.SH NOTES +Unlike some +.BR bindresvport () +implementations, +the glibc implementation ignores any value that the caller supplies in +.IR sin\->sin_port . +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2) diff --git a/man/man3/bsd_signal.3 b/man/man3/bsd_signal.3 new file mode 100644 index 0000000..183ab2e --- /dev/null +++ b/man/man3/bsd_signal.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bsd_signal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bsd_signal \- signal handling with BSD semantics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR bsd_signal (): +.nf + Since glibc 2.26: + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + && ! (_POSIX_C_SOURCE >= 200809L) + glibc 2.25 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR bsd_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.P +The difference between the two is that +.BR bsd_signal () +is guaranteed to provide reliable signal semantics, that is: +a) the disposition of the signal is not reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is blocked while +the signal handler is executing; and +c) if the handler interrupts a blocking system call, +then the system call is automatically restarted. +A portable application cannot rely on +.BR signal (2) +to provide these guarantees. +.SH RETURN VALUE +The +.BR bsd_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bsd_signal () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use of +.BR bsd_signal () +should be avoided; use +.BR sigaction (2) +instead. +.P +On modern Linux systems, +.BR bsd_signal () +and +.BR signal (2) +are equivalent. +But on older systems, +.BR signal (2) +provided unreliable signal semantics; see +.BR signal (2) +for details. +.P +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if the +.B _GNU_SOURCE +feature test macro is defined. +.SH STANDARDS +None. +.SH HISTORY +4.2BSD, POSIX.1-2001. +Removed in POSIX.1-2008, +recommending the use of +.BR sigaction (2) +instead. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR sysv_signal (3), +.BR signal (7) diff --git a/man/man3/bsearch.3 b/man/man3/bsearch.3 new file mode 100644 index 0000000..3e6bff4 --- /dev/null +++ b/man/man3/bsearch.3 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe +.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) +.TH bsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bsearch \- binary search of a sorted array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "void *bsearch(const void " key [. size "], \ +const void " base [. size " * ." nmemb ], +.BI " size_t " nmemb ", size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size ])); +.fi +.SH DESCRIPTION +The +.BR bsearch () +function searches an array of +.I nmemb +objects, +the initial member of which is pointed to by +.IR base , +for a member +that matches the object pointed to by +.IR key . +The size of each member +of the array is specified by +.IR size . +.P +The contents of the array should be in ascending sorted order according +to the comparison function referenced by +.IR compar . +The +.I compar +routine is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and should return an integer +less than, equal to, or greater than zero if the +.I key +object is found, +respectively, to be less than, to match, or be greater than the array +member. +.SH RETURN VALUE +The +.BR bsearch () +function returns a pointer to a matching member of the +array, or NULL if no match is found. +If there are multiple elements that +match the key, the element returned is unspecified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bsearch () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH EXAMPLES +The example below first sorts an array of structures using +.BR qsort (3), +then retrieves desired elements using +.BR bsearch (). +.P +.\" SRC BEGIN (bsearch.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +struct mi { + int nr; + const char *name; +}; +\& +static struct mi months[] = { + { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, + { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, + { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } +}; +\& +static int +compmi(const void *m1, const void *m2) +{ + const struct mi *mi1 = m1; + const struct mi *mi2 = m2; +\& + return strcmp(mi1\->name, mi2\->name); +} +\& +int +main(int argc, char *argv[]) +{ + qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi); + for (size_t i = 1; i < argc; i++) { + struct mi key; + struct mi *res; +\& + key.name = argv[i]; + res = bsearch(&key, months, ARRAY_SIZE(months), + sizeof(months[0]), compmi); + if (res == NULL) + printf("\[aq]%s\[aq]: unknown month\en", argv[i]); + else + printf("%s: month #%d\en", res\->name, res\->nr); + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3), +.BR tsearch (3) diff --git a/man/man3/bstring.3 b/man/man3/bstring.3 new file mode 100644 index 0000000..3f05757 --- /dev/null +++ b/man/man3/bstring.3 @@ -0,0 +1,76 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-12, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-01-20, Walter Harms +.TH bstring 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, +memmove, memset \- byte string operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "int bcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.P +.BI "void bcopy(const void " src [. n "], void " dest [. n "], size_t " n ); +.P +.BI "void bzero(void " s [. n "], size_t " n ); +.P +.BI "void *memccpy(void " dest [. n "], const void " src [. n "], int " c ", \ +size_t " n ); +.P +.BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); +.P +.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.P +.BI "void *memcpy(void " dest [. n "], const void " src [. n "], size_t " n ); +.P +.BI "void *memfrob(void " s [. n "], size_t " n ); +.P +.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , +.BI " const void " needle [. needlelen "], size_t " needlelen ); +.P +.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); +.P +.BI "void *memset(void " s [. n "], int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The byte string functions perform operations on strings (byte arrays) +that are not necessarily null-terminated. +See the individual man pages +for descriptions of each function. +.SH NOTES +The functions +.BR bcmp () +and +.BR bcopy () +are obsolete. +Use +.BR memcmp () +and +.BR memmove () +instead. +.\" The old functions are not even available on some non-GNU/Linux systems. +.SH SEE ALSO +.BR bcmp (3), +.BR bcopy (3), +.BR bzero (3), +.BR memccpy (3), +.BR memchr (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memfrob (3), +.BR memmem (3), +.BR memmove (3), +.BR memset (3), +.BR string (3) diff --git a/man/man3/bswap.3 b/man/man3/bswap.3 new file mode 100644 index 0000000..0e4808f --- /dev/null +++ b/man/man3/bswap.3 @@ -0,0 +1,68 @@ +.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bswap 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bswap_16, bswap_32, bswap_64 \- reverse order of bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <byteswap.h> +.P +.BI "uint16_t bswap_16(uint16_t " x ); +.BI "uint32_t bswap_32(uint32_t " x ); +.BI "uint64_t bswap_64(uint64_t " x ); +.fi +.SH DESCRIPTION +These functions return a value in which the order of the bytes +in their 2-, 4-, or 8-byte arguments is reversed. +.SH RETURN VALUE +These functions return the value of their argument with the bytes reversed. +.SH ERRORS +These functions always succeed. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below swaps the bytes of the 8-byte integer supplied as +its command-line argument. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +$ \fB./a.out 0x0123456789abcdef\fP +0x123456789abcdef ==> 0xefcdab8967452301 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (bswap.c) +.EX +#include <byteswap.h> +#include <inttypes.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + uint64_t x; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s <num>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + x = strtoull(argv[1], NULL, 0); + printf("%#" PRIx64 " ==> %#" PRIx64 "\en", x, bswap_64(x)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR byteorder (3), +.BR endian (3) diff --git a/man/man3/bswap_16.3 b/man/man3/bswap_16.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_16.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/bswap_32.3 b/man/man3/bswap_32.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_32.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/bswap_64.3 b/man/man3/bswap_64.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_64.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/btowc.3 b/man/man3/btowc.3 new file mode 100644 index 0000000..518211a --- /dev/null +++ b/man/man3/btowc.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH btowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +btowc \- convert single byte to wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wint_t btowc(int " c ); +.fi +.SH DESCRIPTION +The +.BR btowc () +function converts \fIc\fP, +interpreted as a multibyte sequence +of length 1, starting in the initial shift state, to a wide character and +returns it. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +the +.BR btowc () +function returns +.BR WEOF . +.SH RETURN VALUE +The +.BR btowc () +function returns the wide character +converted from the single byte \fIc\fP. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +it returns +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR btowc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR btowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function should never be used. +It does not work for encodings which have +state, and unnecessarily treats single bytes differently from multibyte +sequences. +Use either +.BR mbtowc (3) +or the thread-safe +.BR mbrtowc (3) +instead. +.SH SEE ALSO +.BR mbrtowc (3), +.BR mbtowc (3), +.BR wctob (3) diff --git a/man/man3/btree.3 b/man/man3/btree.3 new file mode 100644 index 0000000..4919008 --- /dev/null +++ b/man/man3/btree.3 @@ -0,0 +1,229 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" +.TH btree 3 2024-05-02 "Linux man-pages (unreleased)" +.\".UC 7 +.SH NAME +btree \- btree database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include <sys/types.h> +#include <db.h> +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is btree files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the btree-specific information. +.P +The btree data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.P +The btree access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I <db.h> +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + int maxkeypage; + int minkeypage; + unsigned int psize; + int (*compare)(const DBT *key1, const DBT *key2); + size_t (*prefix)(const DBT *key1, const DBT *key2); + int lorder; +} BTREEINFO; +.EE +.in +.P +The elements of this structure are as follows: +.TP +.I flags +The flag value is specified by ORing any of the following values: +.RS +.TP +.B R_DUP +Permit duplicate keys in the tree, that is, +permit insertion if the key to be +inserted already exists in the tree. +The default behavior, as described in +.BR dbopen (3), +is to overwrite a matching key when inserting a new key or to fail if +the +.B R_NOOVERWRITE +flag is specified. +The +.B R_DUP +flag is overridden by the +.B R_NOOVERWRITE +flag, and if the +.B R_NOOVERWRITE +flag is specified, attempts to insert duplicate keys into +the tree will fail. +.IP +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.I get +routine is used, however, +.I seq +routine calls with the +.B R_CURSOR +flag set will always return the logical +"first" of any group of duplicate keys. +.RE +.TP +.I cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.I only +advisory, and the access method will allocate more memory rather than fail. +Since every search examines the root page of the tree, caching the most +recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a moderate +cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood of +corruption or lost data if the system crashes while a tree is being modified. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the btree data structure works, +.\" .I maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .I maxkeypage +.\" is 0 (no maximum number of keys is specified), the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.TP +.I minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, that is, if a key or data item is longer than the pagesize divided +by the minkeypage value, it will be stored on overflow pages instead +of in the page itself. +If +.I minkeypage +is 0 (no minimum number of keys is specified), a value of 2 is used. +.TP +.I psize +Page size is the size (in bytes) of the pages used for nodes in the tree. +The minimum page size is 512 bytes and the maximum page size is 64\ KiB. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +.TP +.I compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if the +first key argument is considered to be respectively less than, equal to, +or greater than the second key argument. +The same comparison function must be used on a given tree every time it +is opened. +If +.I compare +is NULL (no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.TP +.I prefix +Prefix is the prefix comparison function. +If specified, this routine must return the number of bytes of the second key +argument which are necessary to determine that it is greater than the first +key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data-dependent, but, in some +data sets can produce significantly reduced tree sizes and search times. +If +.I prefix +is NULL (no prefix function is specified), +.I and +no comparison function is specified, a default lexical comparison routine +is used. +If +.I prefix +is NULL and a comparison routine is specified, no prefix comparison is +done. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.P +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for the arguments +.IR flags , +.IR lorder , +and +.I psize +are ignored +in favor of the values used when the tree was created. +.P +Forward sequential scans of a tree are from the least key to the greatest. +.P +Space freed up by deleting key/data pairs from the tree is never reclaimed, +although it is normally made available for reuse. +This means that the btree storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a fresh +tree periodically from a scan of an existing one. +.P +Searches, insertions, and deletions in a btree will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into btrees results in a low fill factor. +This implementation has been modified to make ordered insertion the best +case, resulting in a much better than normal page fill factor. +.SH ERRORS +The +.I btree +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR dbopen (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "The Ubiquitous B-tree" , +Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. +.P +.IR "Prefix B-trees" , +Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 +(March 1977), 11-26. +.P +.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , +D.E. Knuth, 1968, pp 471-480. diff --git a/man/man3/byteorder.3 b/man/man3/byteorder.3 new file mode 100644 index 0000000..2e82db2 --- /dev/null +++ b/man/man3/byteorder.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Jul 26 14:06:20 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH BYTEORDER 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network +byte order +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <arpa/inet.h> +.P +.BI "uint32_t htonl(uint32_t " hostlong ); +.BI "uint16_t htons(uint16_t " hostshort ); +.P +.BI "uint32_t ntohl(uint32_t " netlong ); +.BI "uint16_t ntohs(uint16_t " netshort ); +.fi +.SH DESCRIPTION +The +.BR htonl () +function converts the unsigned integer +.I hostlong +from host byte order to network byte order. +.P +The +.BR htons () +function converts the unsigned short integer +.I hostshort +from host byte order to network byte order. +.P +The +.BR ntohl () +function converts the unsigned integer +.I netlong +from network byte order to host byte order. +.P +The +.BR ntohs () +function converts the unsigned short integer +.I netshort +from network byte order to host byte order. +.P +On the i386 the host byte order is Least Significant Byte first, +whereas the network byte order, as used on the Internet, is Most +Significant Byte first. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR htonl (), +.BR htons (), +.BR ntohl (), +.BR ntohs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR bswap (3), +.BR endian (3), +.BR gethostbyname (3), +.BR getservent (3) diff --git a/man/man3/bzero.3 b/man/man3/bzero.3 new file mode 100644 index 0000000..a50746f --- /dev/null +++ b/man/man3/bzero.3 @@ -0,0 +1,158 @@ +'\" t +.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bzero 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bzero, explicit_bzero \- zero a byte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "void bzero(void " s [. n "], size_t " n ); +.P +.B #include <string.h> +.P +.BI "void explicit_bzero(void " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bzero () +function erases the data in the +.I n +bytes of the memory starting at the location pointed to by +.IR s , +by writing zeros (bytes containing \[aq]\e0\[aq]) to that area. +.P +The +.BR explicit_bzero () +function performs the same task as +.BR bzero (). +It differs from +.BR bzero () +in that it guarantees that compiler optimizations will not remove the +erase operation if the compiler deduces that the operation is "unnecessary". +.SH RETURN VALUE +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bzero (), +.BR explicit_bzero () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR explicit_bzero () +glibc 2.25. +.IP +The +.BR explicit_bzero () +function is a nonstandard extension that is also present on some of the BSDs. +Some other implementations have a similar function, such as +.BR memset_explicit () +or +.BR memset_s (). +.TP +.BR bzero () +4.3BSD. +.IP +Marked as LEGACY in POSIX.1-2001. +Removed in POSIX.1-2008. +.SH NOTES +The +.BR explicit_bzero () +function addresses a problem that security-conscious applications +may run into when using +.BR bzero (): +if the compiler can deduce that the location to be zeroed will +never again be touched by a +.I correct +program, then it may remove the +.BR bzero () +call altogether. +This is a problem if the intent of the +.BR bzero () +call was to erase sensitive data (e.g., passwords) +to prevent the possibility that the data was leaked +by an incorrect or compromised program. +Calls to +.BR explicit_bzero () +are never optimized away by the compiler. +.P +The +.BR explicit_bzero () +function does not solve all problems associated with erasing sensitive data: +.IP \[bu] 3 +The +.BR explicit_bzero () +function does +.I not +guarantee that sensitive data is completely erased from memory. +(The same is true of +.BR bzero ().) +For example, there may be copies of the sensitive data in +a register and in "scratch" stack areas. +The +.BR explicit_bzero () +function is not aware of these copies, and can't erase them. +.IP \[bu] +In some circumstances, +.BR explicit_bzero () +can +.I decrease +security. +If the compiler determined that the variable containing the +sensitive data could be optimized to be stored in a register +(because it is small enough to fit in a register, +and no operation other than the +.BR explicit_bzero () +call would need to take the address of the variable), then the +.BR explicit_bzero () +call will force the data to be copied from the register +to a location in RAM that is then immediately erased +(while the copy in the register remains unaffected). +The problem here is that data in RAM is more likely to be exposed +by a bug than data in a register, and thus the +.BR explicit_bzero () +call creates a brief time window where the sensitive data is more +vulnerable than it would otherwise have been +if no attempt had been made to erase the data. +.P +Note that declaring the sensitive variable with the +.B volatile +qualifier does +.I not +eliminate the above problems. +Indeed, it will make them worse, since, for example, +it may force a variable that would otherwise have been optimized +into a register to instead be maintained in (more vulnerable) +RAM for its entire lifetime. +.P +Notwithstanding the above details, for security-conscious applications, using +.BR explicit_bzero () +is generally preferable to not using it. +The developers of +.BR explicit_bzero () +anticipate that future compilers will recognize calls to +.BR explicit_bzero () +and take steps to ensure that all copies of the sensitive data are erased, +including copies in registers or in "scratch" stack areas. +.SH SEE ALSO +.BR bstring (3), +.BR memset (3), +.BR swab (3) diff --git a/man/man3/cabs.3 b/man/man3/cabs.3 new file mode 100644 index 0000000..2a7a7c6 --- /dev/null +++ b/man/man3/cabs.3 @@ -0,0 +1,54 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cabs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cabs, cabsf, cabsl \- absolute value of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double cabs(double complex " z ); +.BI "float cabsf(float complex " z ); +.BI "long double cabsl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the absolute value of the complex number +.IR z . +The result is a real number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cabs (), +.BR cabsf (), +.BR cabsl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +The function is actually an alias for +.I "hypot(a,\ b)" +(or, equivalently, +.IR "sqrt(a*a\ +\ b*b)" ). +.SH SEE ALSO +.BR abs (3), +.BR cimag (3), +.BR hypot (3), +.BR complex (7) diff --git a/man/man3/cabsf.3 b/man/man3/cabsf.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man/man3/cabsf.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man/man3/cabsl.3 b/man/man3/cabsl.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man/man3/cabsl.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man/man3/cacos.3 b/man/man3/cacos.3 new file mode 100644 index 0000000..5319074 --- /dev/null +++ b/man/man3/cacos.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cacos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cacos, cacosf, cacosl \- complex arc cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cacos(double complex " z ); +.BI "float complex cacosf(float complex " z ); +.BI "long double complex cacosl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc cosine of +.IR z . +If \fIy\ =\ cacos(z)\fP, then \fIz\ =\ ccos(y)\fP. +The real part of +.I y +is chosen in the interval [0,pi]. +.P +One has: +.P +.nf + cacos(z) = \-i * clog(z + i * csqrt(1 \- z * z)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cacos (), +.BR cacosf (), +.BR cacosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (cacos.c) +.EX +/* Link with "\-lm" */ +\& +#include <complex.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <real> <imag>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = cacos(z); +\& + printf("cacos() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = \-i * clog(z + i * csqrt(1 \- z * z)); +\& + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR complex (7) diff --git a/man/man3/cacosf.3 b/man/man3/cacosf.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man/man3/cacosf.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man/man3/cacosh.3 b/man/man3/cacosh.3 new file mode 100644 index 0000000..c36f08f --- /dev/null +++ b/man/man3/cacosh.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright 2002 Walter Harms(walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cacosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cacosh(double complex " z ); +.BI "float complex cacoshf(float complex " z ); +.BI "long double complex cacoshl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic cosine of +.IR z . +If \fIy\ =\ cacosh(z)\fP, then \fIz\ =\ ccosh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +The real part of +.I y +is chosen nonnegative. +.P +One has: +.P +.nf + cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z \- 1) / 2)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cacosh (), +.BR cacoshf (), +.BR cacoshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +glibc 2.1. +.SH EXAMPLES +.\" SRC BEGIN (cacosh.c) +.EX +/* Link with "\-lm" */ +\& +#include <complex.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <real> <imag>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = cacosh(z); + printf("cacosh() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = 2 * clog(csqrt((z + 1)/2) + csqrt((z \- 1)/2)); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR acosh (3), +.BR cabs (3), +.BR ccosh (3), +.BR cimag (3), +.BR complex (7) diff --git a/man/man3/cacoshf.3 b/man/man3/cacoshf.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man/man3/cacoshf.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man/man3/cacoshl.3 b/man/man3/cacoshl.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man/man3/cacoshl.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man/man3/cacosl.3 b/man/man3/cacosl.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man/man3/cacosl.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man/man3/calloc.3 b/man/man3/calloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/calloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/callrpc.3 b/man/man3/callrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/callrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/canonicalize_file_name.3 b/man/man3/canonicalize_file_name.3 new file mode 100644 index 0000000..a421057 --- /dev/null +++ b/man/man3/canonicalize_file_name.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright 2013 Michael Kerrisk <mtk.manpages@gmail.com> +.\" (Replaces an earlier page by Walter Harms and Michael Kerrisk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH canonicalize_file_name 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +canonicalize_file_name \- return the canonicalized absolute pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <stdlib.h> +.P +.BI "char *canonicalize_file_name(const char *" path ");" +.fi +.SH DESCRIPTION +The +.BR canonicalize_file_name () +function returns a null-terminated string containing +the canonicalized absolute pathname corresponding to +.IR path . +In the returned string, symbolic links are resolved, as are +.I . +and +.I .. +pathname components. +Consecutive slash +.RI ( / ) +characters are replaced by a single slash. +.P +The returned string is dynamically allocated by +.BR canonicalize_file_name () +and the caller should deallocate it with +.BR free (3) +when it is no longer required. +.P +The call +.I canonicalize_file_name(path) +is equivalent to the call: +.P +.in +4n +.EX +realpath(path, NULL); +.EE +.in +.SH RETURN VALUE +On success, +.BR canonicalize_file_name () +returns a null-terminated string. +On error (e.g., a pathname component is unreadable or does not exist), +.BR canonicalize_file_name () +returns NULL and sets +.I errno +to indicate the error. +.SH ERRORS +See +.BR realpath (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR canonicalize_file_name () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR readlink (2), +.BR realpath (3) diff --git a/man/man3/carg.3 b/man/man3/carg.3 new file mode 100644 index 0000000..8773247 --- /dev/null +++ b/man/man3/carg.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH carg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +carg, cargf, cargl \- calculate the complex argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double carg(double complex " z ");" +.BI "float cargf(float complex " z ");" +.BI "long double cargl(long double complex " z ");" +.fi +.SH DESCRIPTION +These functions calculate the complex argument (also called phase angle) of +.IR z , +with a branch cut along the negative real axis. +.P +A complex number can be described by two real coordinates. +One may use rectangular coordinates and gets +.P +.in +4n +.EX +z = x + I * y +.EE +.in +.P +where +.I x\~=\~creal(z) +and +.IR y\~=\~cimag(z) . +.P +Or one may use polar coordinates and gets +.P +.in +4n +.EX +z = r * cexp(I * a) +.EE +.in +.P +where +.I r\~=\~cabs(z) +is the "radius", the "modulus", the absolute value of +.IR z , +and +.I a\~=\~carg(z) +is the "phase angle", the argument of +.IR z . +.P +One has: +.P +.in +4n +.EX +tan(carg(z)) = cimag(z) / creal(z) +.EE +.in +.SH RETURN VALUE +The return value is in the range of [\-pi,pi]. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR carg (), +.BR cargf (), +.BR cargl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) diff --git a/man/man3/cargf.3 b/man/man3/cargf.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man/man3/cargf.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man/man3/cargl.3 b/man/man3/cargl.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man/man3/cargl.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man/man3/casin.3 b/man/man3/casin.3 new file mode 100644 index 0000000..95b308c --- /dev/null +++ b/man/man3/casin.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH casin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +casin, casinf, casinl \- complex arc sine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex casin(double complex " z ); +.BI "float complex casinf(float complex " z ); +.BI "long double complex casinl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc sine of +.IR z . +If \fIy\ =\ casin(z)\fP, then \fIz\ =\ csin(y)\fP. +The real part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.nf + casin(z) = \-i clog(iz + csqrt(1 \- z * z)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR casin (), +.BR casinf (), +.BR casinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR clog (3), +.BR csin (3), +.BR complex (7) diff --git a/man/man3/casinf.3 b/man/man3/casinf.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man/man3/casinf.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man/man3/casinh.3 b/man/man3/casinh.3 new file mode 100644 index 0000000..950f011 --- /dev/null +++ b/man/man3/casinh.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH casinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +casinh, casinhf, casinhl \- complex arc sine hyperbolic +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex casinh(double complex " z ); +.BI "float complex casinhf(float complex " z ); +.BI "long double complex casinhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic sine of +.IR z . +If \fIy\~=\~casinh(z)\fP, then \fIz\~=\~csinh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.in +4n +.EX +casinh(z) = clog(z + csqrt(z * z + 1)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR casinh (), +.BR casinhf (), +.BR casinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR asinh (3), +.BR cabs (3), +.BR cimag (3), +.BR csinh (3), +.BR complex (7) diff --git a/man/man3/casinhf.3 b/man/man3/casinhf.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man/man3/casinhf.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man/man3/casinhl.3 b/man/man3/casinhl.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man/man3/casinhl.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man/man3/casinl.3 b/man/man3/casinl.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man/man3/casinl.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man/man3/catan.3 b/man/man3/catan.3 new file mode 100644 index 0000000..67be9c2 --- /dev/null +++ b/man/man3/catan.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH catan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catan, catanf, catanl \- complex arc tangents +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex catan(double complex " z ); +.BI "float complex catanf(float complex " z ); +.BI "long double complex catanl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc tangent of +.IR z . +If \fIy\~=\~catan(z)\fP, then \fIz\~=\~ctan(y)\fP. +The real part of +.I y +is chosen in the interval [\-pi/2, pi/2]. +.P +One has: +.P +.in +4n +.EX +catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catan (), +.BR catanf (), +.BR catanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (catan.c) +.EX +/* Link with "\-lm" */ +\& +#include <complex.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <real> <imag>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = catan(z); + printf("catan() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/catanf.3 b/man/man3/catanf.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man/man3/catanf.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man/man3/catanh.3 b/man/man3/catanh.3 new file mode 100644 index 0000000..4567495 --- /dev/null +++ b/man/man3/catanh.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH catanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catanh, catanhf, catanhl \- complex arc tangents hyperbolic +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex catanh(double complex " z ); +.BI "float complex catanhf(float complex " z ); +.BI "long double complex catanhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic tangent of +.IR z . +If \fIy\~=\~catanh(z)\fP, then \fIz\~=\~ctanh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.in +4n +.EX +catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catanh (), +.BR catanhf (), +.BR catanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (catanh.c) +.EX +/* Link with "\-lm" */ +\& +#include <complex.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <real> <imag>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = catanh(z); + printf("catanh() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = 0.5 * (clog(1 + z) \- clog(1 \- z)); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR atanh (3), +.BR cabs (3), +.BR cimag (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/catanhf.3 b/man/man3/catanhf.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man/man3/catanhf.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man/man3/catanhl.3 b/man/man3/catanhl.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man/man3/catanhl.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man/man3/catanl.3 b/man/man3/catanl.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man/man3/catanl.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man/man3/catclose.3 b/man/man3/catclose.3 new file mode 100644 index 0000000..92ff666 --- /dev/null +++ b/man/man3/catclose.3 @@ -0,0 +1 @@ +.so man3/catopen.3 diff --git a/man/man3/catgets.3 b/man/man3/catgets.3 new file mode 100644 index 0000000..02dc5bc --- /dev/null +++ b/man/man3/catgets.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Updated, aeb, 980809 +.TH catgets 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catgets \- get message from a message catalog +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <nl_types.h> +.P +.BI "char *catgets(nl_catd " catalog ", int " set_number \ +", int " message_number , +.BI " const char *" message ); +.fi +.SH DESCRIPTION +.BR catgets () +reads the message +.IR message_number , +in set +.IR set_number , +from the message catalog identified by +.IR catalog , +where +.I catalog +is a catalog descriptor returned from an earlier call to +.BR catopen (3). +The fourth argument, +.IR message , +points to a default message string which will be returned by +.BR catgets () +if the identified message catalog is not currently available. +The +message-text is contained in an internal buffer area and should be copied by +the application if it is to be saved or modified. +The return string is +always terminated with a null byte (\[aq]\e0\[aq]). +.SH RETURN VALUE +On success, +.BR catgets () +returns a pointer to an internal buffer area +containing the null-terminated message string. +On failure, +.BR catgets () +returns the value +.IR message . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catgets () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +The +.BR catgets () +function is available only in libc.so.4.4.4c and above. +.P +The Jan 1987 X/Open Portability Guide specifies a more subtle +error return: +.I message +is returned if the message catalog specified by +.I catalog +is not available, while an empty string is returned +when the message catalog is available but does not contain +the specified message. +These two possible error returns seem to be discarded in SUSv2 +in favor of always returning +.IR message . +.SH SEE ALSO +.BR catopen (3), +.BR setlocale (3) diff --git a/man/man3/catopen.3 b/man/man3/catopen.3 new file mode 100644 index 0000000..278213f --- /dev/null +++ b/man/man3/catopen.3 @@ -0,0 +1,199 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze <joey@infodrom.org> +.\" Modified 2001-12-14 aeb +.\" +.TH catopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catopen, catclose \- open/close a message catalog +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <nl_types.h> +.P +.BI "nl_catd catopen(const char *" name ", int " flag ); +.BI "int catclose(nl_catd " catalog ); +.fi +.SH DESCRIPTION +The function +.BR catopen () +opens a message catalog and returns a catalog descriptor. +The descriptor remains valid until +.BR catclose () +or +.BR execve (2). +If a file descriptor is used to implement catalog descriptors, +then the +.B FD_CLOEXEC +flag will be set. +.P +The argument +.I name +specifies the name of the message catalog to be opened. +If +.I name +specifies an absolute path (i.e., contains a \[aq]/\[aq]), +then +.I name +specifies a pathname for the message catalog. +Otherwise, the environment variable +.B NLSPATH +is used with +.I name +substituted for +.B %N +(see +.BR locale (7)). +It is unspecified whether +.B NLSPATH +will be used when the process has root privileges. +If +.B NLSPATH +does not exist in the environment, +or if a message catalog cannot be opened +in any of the paths specified by it, +then an implementation defined path is used. +This latter default path may depend on the +.B LC_MESSAGES +locale setting when the +.I flag +argument is +.B NL_CAT_LOCALE +and on the +.B LANG +environment variable when the +.I flag +argument is 0. +Changing the +.B LC_MESSAGES +part of the locale may invalidate +open catalog descriptors. +.P +The +.I flag +argument to +.BR catopen () +is used to indicate the source for the language to use. +If it is set to +.BR NL_CAT_LOCALE , +then it will use the current locale setting for +.BR LC_MESSAGES . +Otherwise, it will use the +.B LANG +environment variable. +.P +The function +.BR catclose () +closes the message catalog identified by +.IR catalog . +It invalidates any subsequent references to the message catalog +defined by +.IR catalog . +.SH RETURN VALUE +The function +.BR catopen () +returns a message catalog descriptor of type +.I nl_catd +on success. +On failure, it returns +.I (nl_catd)\~\-1 +and sets +.I errno +to indicate the error. +The possible error values include all +possible values for the +.BR open (2) +call. +.P +The function +.BR catclose () +returns 0 on success, or \-1 on failure. +.SH ENVIRONMENT +.TP +.B LC_MESSAGES +May be the source of the +.B LC_MESSAGES +locale setting, and thus +determine the language to use if +.I flag +is set to +.BR NL_CAT_LOCALE . +.TP +.B LANG +The language to use if +.I flag +is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catopen () +T} Thread safety MT-Safe env +T{ +.na +.nh +.BR catclose () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The above is the POSIX.1 description. +The glibc value for +.B NL_CAT_LOCALE +is 1. +.\" (Compare +.\" .B MCLoadAll +.\" below.) +The default path varies, but usually looks at a number of places below +.IR /usr/share/locale . +.\" .SS Linux notes +.\" These functions are available for Linux since libc 4.4.4c. +.\" In the case of linux libc4 and libc5, the catalog descriptor +.\" .I nl_catd +.\" is a +.\" .BR mmap (2)'ed +.\" area of memory and not a file descriptor. +.\" The +.\" .I flag +.\" argument to +.\" .BR catopen () +.\" should be either +.\" .B MCLoadBySet +.\" (=0) or +.\" .B MCLoadAll +.\" (=1). +.\" The former value indicates that a set from the catalog is to be +.\" loaded when needed, whereas the latter causes the initial call to +.\" .BR catopen () +.\" to load the entire catalog into memory. +.\" The default search path varies, but usually looks at a number of places below +.\" .I /etc/locale +.\" and +.\" .IR /usr/lib/locale . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.\" In XPG 1987, Vol. 3 it says: +.\" .I "The flag argument of catopen is reserved for future use" +.\" .IR "and should be set to 0" . +.\" +.\" It is unclear what the source was for the constants +.\" .B MCLoadBySet +.\" and +.\" .B MCLoadAll +.\" (see below). +.SH SEE ALSO +.BR catgets (3), +.BR setlocale (3) diff --git a/man/man3/cbc_crypt.3 b/man/man3/cbc_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/cbc_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/cbrt.3 b/man/man3/cbrt.3 new file mode 100644 index 0000000..bf5a62b --- /dev/null +++ b/man/man3/cbrt.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" changed `square root' into `cube root' - aeb, 950919 +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH cbrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cbrt, cbrtf, cbrtl \- cube root function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double cbrt(double " x ); +.BI "float cbrtf(float " x ); +.BI "long double cbrtl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cbrt (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR cbrtf (), +.BR cbrtl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the (real) cube root of +.IR x . +This function cannot fail; +every representable real value +has a real cube root, +and rounding it to a representable value +never causes overflow nor underflow. +.SH RETURN VALUE +These functions return the cube root of +.IR x . +.P +If +.I x +is +0, \-0, positive infinity, negative infinity, or NaN, +.I x +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cbrt (), +.BR cbrtf (), +.BR cbrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.\" .BR cbrt () +.\" was a GNU extension. It is now a C99 requirement. +.SH SEE ALSO +.BR pow (3), +.BR sqrt (3) diff --git a/man/man3/cbrtf.3 b/man/man3/cbrtf.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man/man3/cbrtf.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man/man3/cbrtl.3 b/man/man3/cbrtl.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man/man3/cbrtl.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man/man3/ccos.3 b/man/man3/ccos.3 new file mode 100644 index 0000000..b0c7303 --- /dev/null +++ b/man/man3/ccos.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ccos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ccos, ccosf, ccosl \- complex cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex ccos(double complex " z ); +.BI "float complex ccosf(float complex " z ); +.BI "long double complex ccosl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex cosine of +.IR z . +.P +The complex cosine function is defined as: +.P +.in +4n +.EX +ccos(z) = (exp(i * z) + exp(\-i * z)) / 2 +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ccos (), +.BR ccosf (), +.BR ccosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cacos (3), +.BR csin (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/ccosf.3 b/man/man3/ccosf.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man/man3/ccosf.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man/man3/ccosh.3 b/man/man3/ccosh.3 new file mode 100644 index 0000000..2261873 --- /dev/null +++ b/man/man3/ccosh.3 @@ -0,0 +1,40 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ccosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ccosh, ccoshf, ccoshl \- complex hyperbolic cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex ccosh(double complex " z ); +.BI "float complex ccoshf(float complex " z ); +.BI "long double complex ccoshl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic cosine of +.IR z . +.P +The complex hyperbolic cosine function is defined as: +.P +.in +4n +.EX +ccosh(z) = (exp(z)+exp(\-z))/2 +.EE +.in +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cacosh (3), +.BR csinh (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/ccoshf.3 b/man/man3/ccoshf.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man/man3/ccoshf.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man/man3/ccoshl.3 b/man/man3/ccoshl.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man/man3/ccoshl.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man/man3/ccosl.3 b/man/man3/ccosl.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man/man3/ccosl.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man/man3/ceil.3 b/man/man3/ceil.3 new file mode 100644 index 0000000..b0f26c6 --- /dev/null +++ b/man/man3/ceil.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ceil 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ceil, ceilf, ceill \- ceiling function: smallest integral value not +less than argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double ceil(double " x ); +.BI "float ceilf(float " x ); +.BI "long double ceill(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ceilf (), +.BR ceill (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the smallest integral value that is not less than +.IR x . +.P +For example, +.I ceil(0.5) +is 1.0, and +.I ceil(\-0.5) +is 0.0. +.SH RETURN VALUE +These functions return the ceiling of +.IR x . +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ceil (), +.BR ceilf (), +.BR ceill () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/ceilf.3 b/man/man3/ceilf.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man/man3/ceilf.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man/man3/ceill.3 b/man/man3/ceill.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man/man3/ceill.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man/man3/cexp.3 b/man/man3/cexp.3 new file mode 100644 index 0000000..6894c0d --- /dev/null +++ b/man/man3/cexp.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cexp, cexpf, cexpl \- complex exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cexp(double complex " z ); +.BI "float complex cexpf(float complex " z ); +.BI "long double complex cexpl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate e (2.71828..., the base of natural logarithms) +raised to the power of +.IR z . +.P +One has: +.P +.in +4n +.EX +cexp(I * z) = ccos(z) + I * csin(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cexp (), +.BR cexpf (), +.BR cexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp2 (3), +.BR clog (3), +.BR cpow (3), +.BR complex (7) diff --git a/man/man3/cexp2.3 b/man/man3/cexp2.3 new file mode 100644 index 0000000..dcc4839 --- /dev/null +++ b/man/man3/cexp2.3 @@ -0,0 +1,31 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cexp2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cexp2(double complex " z ); +.BI "float complex cexp2f(float complex " z ); +.BI "long double complex cexp2l(long double complex " z ); +.fi +.SH DESCRIPTION +The function returns 2 raised to the power of +.IR z . +.SH STANDARDS +These function names are reserved for future use in C99. +.P +As at glibc 2.31, these functions are not provided in glibc. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR complex (7) diff --git a/man/man3/cexp2f.3 b/man/man3/cexp2f.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man/man3/cexp2f.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man/man3/cexp2l.3 b/man/man3/cexp2l.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man/man3/cexp2l.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man/man3/cexpf.3 b/man/man3/cexpf.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man/man3/cexpf.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man/man3/cexpl.3 b/man/man3/cexpl.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man/man3/cexpl.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man/man3/cfgetispeed.3 b/man/man3/cfgetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfgetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfgetospeed.3 b/man/man3/cfgetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfgetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfmakeraw.3 b/man/man3/cfmakeraw.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfmakeraw.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfree.3 b/man/man3/cfree.3 new file mode 100644 index 0000000..7862e9a --- /dev/null +++ b/man/man3/cfree.3 @@ -0,0 +1,132 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH cfree 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cfree \- free allocated memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.B "#include <stdlib.h>" +.P +/* In SunOS 4 */ +.BI "int cfree(void *" ptr ); +.P +/* In glibc or FreeBSD libcompat */ +.BI "void cfree(void *" ptr ); +.P +/* In SCO OpenServer */ +.BI "void cfree(char " ptr [. size " * ." num "], unsigned int " num ", \ +unsigned int " size ); +.P +/* In Solaris watchmalloc.so.1 */ +.BI "void cfree(void " ptr [. elsize " * ." nelem "], size_t " nelem ", \ +size_t " elsize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cfree (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +This function should never be used. +Use +.BR free (3) +instead. +Starting with glibc 2.26, it has been removed from glibc. +.SS 1-arg cfree +In glibc, the function +.BR cfree () +is a synonym for +.BR free (3), +"added for compatibility with SunOS". +.P +Other systems have other functions with this name. +The declaration is sometimes in +.I <stdlib.h> +and sometimes in +.IR <malloc.h> . +.SS 3-arg cfree +Some SCO and Solaris versions have malloc libraries with a 3-argument +.BR cfree (), +apparently as an analog to +.BR calloc (3). +.P +If you need it while porting something, add +.P +.in +4n +.EX +#define cfree(p, n, s) free((p)) +.EE +.in +.P +to your file. +.P +A frequently asked question is "Can I use +.BR free (3) +to free memory allocated with +.BR calloc (3), +or do I need +.BR cfree ()?" +Answer: use +.BR free (3). +.P +An SCO manual writes: "The cfree routine is provided for compliance +to the iBCSe2 standard and simply calls free. +The num and size +arguments to cfree are not used." +.SH RETURN VALUE +The SunOS version of +.BR cfree () +(which is a synonym for +.BR free (3)) +returns 1 on success and 0 on failure. +In case of error, +.I errno +is set to +.BR EINVAL : +the value of +.I ptr +was not a pointer to a block previously allocated by +one of the routines in the +.BR malloc (3) +family. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cfree () +T} Thread safety MT-Safe /* In glibc */ +.TE +.SH VERSIONS +The 3-argument version of +.BR cfree () +as used by SCO conforms to the iBCSe2 standard: +Intel386 Binary Compatibility Specification, Edition 2. +.SH STANDARDS +None. +.SH HISTORY +.\" commit 025b33ae84bb8f15b2748a1d8605dca453fce112 +Removed in glibc 2.26. +.SH SEE ALSO +.BR malloc (3) diff --git a/man/man3/cfsetispeed.3 b/man/man3/cfsetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfsetospeed.3 b/man/man3/cfsetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfsetspeed.3 b/man/man3/cfsetspeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetspeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cimag.3 b/man/man3/cimag.3 new file mode 100644 index 0000000..bc231fd --- /dev/null +++ b/man/man3/cimag.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cimag 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cimag, cimagf, cimagl \- get imaginary part of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double cimag(double complex " z ); +.BI "float cimagf(float complex " z ); +.BI "long double cimagl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the imaginary part of the complex number +.IR z . +.P +One has: +.P +.in +4n +.EX +z = creal(z) + I * cimag(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cimag (), +.BR cimagf (), +.BR cimagl () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +GCC also supports __imag__. +That is a GNU extension. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR creal (3), +.BR complex (7) diff --git a/man/man3/cimagf.3 b/man/man3/cimagf.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man/man3/cimagf.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man/man3/cimagl.3 b/man/man3/cimagl.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man/man3/cimagl.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man/man3/circleq.3 b/man/man3/circleq.3 new file mode 100644 index 0000000..5fd74f2 --- /dev/null +++ b/man/man3/circleq.3 @@ -0,0 +1,318 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH CIRCLEQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CIRCLEQ_EMPTY, +CIRCLEQ_ENTRY, +CIRCLEQ_FIRST, +CIRCLEQ_FOREACH, +CIRCLEQ_FOREACH_REVERSE, +CIRCLEQ_HEAD, +CIRCLEQ_HEAD_INITIALIZER, +CIRCLEQ_INIT, +CIRCLEQ_INSERT_AFTER, +CIRCLEQ_INSERT_BEFORE, +CIRCLEQ_INSERT_HEAD, +CIRCLEQ_INSERT_TAIL, +CIRCLEQ_LAST, +CIRCLEQ_LOOP_NEXT, +CIRCLEQ_LOOP_PREV, +CIRCLEQ_NEXT, +CIRCLEQ_PREV, +CIRCLEQ_REMOVE +\- implementation of a doubly linked circular queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/queue.h> +.P +.B CIRCLEQ_ENTRY(TYPE); +.P +.B CIRCLEQ_HEAD(HEADNAME, TYPE); +.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ); +.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ); +.P +.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ); +.P +.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.P +.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ); +.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ); +.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.P +.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head , +.BI " CIRCLEQ_ENTRY " NAME ); +.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head , +.BI " CIRCLEQ_ENTRY " NAME ); +.P +.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm , +.BI " CIRCLEQ_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked circular queues. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR CIRCLEQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR CIRCLEQ_HEAD (). +.SS Creation +A circular queue is headed by a structure defined by the +.BR CIRCLEQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the queue +and the other to the last element in the queue. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the queue. +New elements can be added to the queue +after an existing element, +before an existing element, +at the head of the queue, +or at the end of the queue. +A +.I CIRCLEQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +CIRCLEQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the queue. +A pointer to the head of the queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR CIRCLEQ_ENTRY () +declares a structure that connects the elements in the queue. +.P +.BR CIRCLEQ_HEAD_INITIALIZER () +evaluates to an initializer for the queue +.IR head . +.P +.BR CIRCLEQ_INIT () +initializes the queue referenced by +.IR head . +.P +.BR CIRCLEQ_EMPTY () +evaluates to true if there are no items on the queue. +.SS Insertion +.BR CIRCLEQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the queue. +.P +.BR CIRCLEQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the queue. +.P +.BR CIRCLEQ_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR CIRCLEQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR CIRCLEQ_FIRST () +returns the first item on the queue. +.P +.BR CIRCLEQ_LAST () +returns the last item on the queue. +.P +.BR CIRCLEQ_PREV () +returns the previous item on the queue, or +.I &head +if this item is the first one. +.P +.BR CIRCLEQ_NEXT () +returns the next item on the queue, or +.I &head +if this item is the last one. +.P +.BR CIRCLEQ_LOOP_PREV () +returns the previous item on the queue. +If +.I elm +is the first element on the queue, the last element is returned. +.P +.BR CIRCLEQ_LOOP_NEXT () +returns the next item on the queue. +If +.I elm +is the last element on the queue, the first element is returned. +.P +.BR CIRCLEQ_FOREACH () +traverses the queue referenced by +.I head +in the forward direction, assigning each element in turn to +.IR var . +.I var +is set to +.I &head +if the loop completes normally, or if there were no elements. +.P +.BR CIRCLEQ_FOREACH_REVERSE () +traverses the queue referenced by +.I head +in the reverse direction, +assigning each element in turn to +.IR var . +.SS Removal +.BR CIRCLEQ_REMOVE () +removes the element +.I elm +from the queue. +.SH RETURN VALUE +.BR CIRCLEQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR CIRCLEQ_FIRST (), +.BR CIRCLEQ_LAST (), +.BR CIRCLEQ_LOOP_PREV (), +and +.BR CIRCLEQ_LOOP_NEXT () +return a pointer to the first, last, previous, or next +.I TYPE +structure, respectively. +.P +.BR CIRCLEQ_PREV (), +and +.BR CIRCLEQ_NEXT () +are similar to their +.BR CIRCLEQ_LOOP_* () +counterparts, +except that if the argument is the first or last element, respectively, +they return +.IR &head . +.P +.BR CIRCLEQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH STANDARDS +BSD. +.SH BUGS +.BR CIRCLEQ_FOREACH () +and +.BR CIRCLEQ_FOREACH_REVERSE () +don't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR CIRCLEQ_FOREACH_SAFE () +and +.BR CIRCLEQ_FOREACH_REVERSE_SAFE (), +which are present on the BSDs but are not present in glibc, +fix this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (circleq.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> +\& +struct entry { + int data; + CIRCLEQ_ENTRY(entry) entries; /* Queue */ +}; +\& +CIRCLEQ_HEAD(circlehead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct circlehead head; /* Queue head */ + int i; +\& + CIRCLEQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + CIRCLEQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + CIRCLEQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + CIRCLEQ_INSERT_BEFORE(&head, n2, n3, entries); +\& + CIRCLEQ_REMOVE(&head, n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + i = 0; + CIRCLEQ_FOREACH(np, &head, entries) + np\->data = i++; + /* Reverse traversal */ + CIRCLEQ_FOREACH_REVERSE(np, &head, entries) + printf("%i\en", np\->data); + /* Queue deletion */ + n1 = CIRCLEQ_FIRST(&head); + while (n1 != (void *)&head) { + n2 = CIRCLEQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + CIRCLEQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/clearenv.3 b/man/man3/clearenv.3 new file mode 100644 index 0000000..5a6a738 --- /dev/null +++ b/man/man3/clearenv.3 @@ -0,0 +1,137 @@ +'\" t +.\" Copyright 2001 John Levon <moz@compsoc.man.ac.uk> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Additions, aeb, 2001-10-17. +.TH clearenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clearenv \- clear the environment +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B "int clearenv(void);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clearenv (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR clearenv () +function clears the environment of all name-value +pairs and sets the value of the external variable +.I environ +to NULL. +After this call, new variables can be added to the environment using +.BR putenv (3) +and +.BR setenv (3). +.SH RETURN VALUE +The +.BR clearenv () +function returns zero on success, and a nonzero +value on failure. +.\" Most versions of UNIX return -1 on error, or do not even have errors. +.\" glibc info and the Watcom C library document "a nonzero value". +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clearenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +.TP +.BR putenv () +POSIX.1-2008. +.TP +.BR clearenv () +None. +.SH HISTORY +.TP +.BR putenv () +glibc 2.0. +POSIX.1-2001. +.TP +.BR clearenv () +glibc 2.0. +.P +Various UNIX variants (DG/UX, HP-UX, QNX, ...). +POSIX.9 (bindings for FORTRAN77). +POSIX.1-1996 did not accept +.BR clearenv () +and +.BR putenv (3), +but changed its mind and scheduled these functions for some +later issue of this standard (see \[sc]B.4.6.1). +However, POSIX.1-2001 +adds only +.BR putenv (3), +and rejected +.BR clearenv (). +.SH NOTES +On systems where +.BR clearenv () +is unavailable, the assignment +.P +.in +4n +.EX +environ = NULL; +.EE +.in +.P +will probably do. +.P +The +.BR clearenv () +function may be useful in security-conscious applications that want to +precisely control the environment that is passed to programs +executed using +.BR exec (3). +The application would do this by first clearing the environment +and then adding select environment variables. +.P +Note that the main effect of +.BR clearenv () +is to adjust the value of the pointer +.BR environ (7); +this function does not erase the contents of the buffers +containing the environment definitions. +.P +The DG/UX and Tru64 man pages write: If +.I environ +has been modified by anything other than the +.BR putenv (3), +.BR getenv (3), +or +.BR clearenv () +functions, then +.BR clearenv () +will return an error and the process environment will remain unchanged. +.\" .P +.\" HP-UX has a ENOMEM error return. +.SH SEE ALSO +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) diff --git a/man/man3/clearerr.3 b/man/man3/clearerr.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man/man3/clearerr.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man/man3/clearerr_unlocked.3 b/man/man3/clearerr_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/clearerr_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/clnt_broadcast.3 b/man/man3/clnt_broadcast.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_broadcast.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_call.3 b/man/man3/clnt_call.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_call.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_control.3 b/man/man3/clnt_control.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_control.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_create.3 b/man/man3/clnt_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_destroy.3 b/man/man3/clnt_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_freeres.3 b/man/man3/clnt_freeres.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_freeres.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_geterr.3 b/man/man3/clnt_geterr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_geterr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_pcreateerror.3 b/man/man3/clnt_pcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_pcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_perrno.3 b/man/man3/clnt_perrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_perrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_perror.3 b/man/man3/clnt_perror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_perror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_spcreateerror.3 b/man/man3/clnt_spcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_spcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_sperrno.3 b/man/man3/clnt_sperrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_sperrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_sperror.3 b/man/man3/clnt_sperror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_sperror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntraw_create.3 b/man/man3/clntraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnttcp_create.3 b/man/man3/clnttcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnttcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntudp_bufcreate.3 b/man/man3/clntudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntudp_create.3 b/man/man3/clntudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clock.3 b/man/man3/clock.3 new file mode 100644 index 0000000..0019552 --- /dev/null +++ b/man/man3/clock.3 @@ -0,0 +1,101 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 21:27:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 14 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on differences from other UNIX systems with respect to +.\" waited-for children. +.TH clock 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock \- determine processor time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.B clock_t clock(void); +.fi +.SH DESCRIPTION +The +.BR clock () +function returns an approximation of processor time used by the program. +.SH RETURN VALUE +The value returned is the CPU time used so far as a +.IR clock_t ; +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 +.IR (clock_t)\ \-1 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clock () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +XSI requires that +.B CLOCKS_PER_SEC +equals 1000000 independent +of the actual resolution. +.P +On several other implementations, +the value returned by +.BR clock () +also includes the times of any children whose status has been +collected via +.BR wait (2) +(or another wait-type call). +Linux does not include the times of waited-for children in the +value returned by +.BR clock (). +.\" I have seen this behavior on Irix 6.3, and the OSF/1, HP/UX, and +.\" Solaris manual pages say that clock() also does this on those systems. +.\" POSIX.1-2001 doesn't explicitly allow this, nor is there an +.\" explicit prohibition. -- MTK +The +.BR times (2) +function, which explicitly returns (separate) information about the +caller and its children, may be preferable. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.P +In glibc 2.17 and earlier, +.BR clock () +was implemented on top of +.BR times (2). +For improved accuracy, +since glibc 2.18, it is implemented on top of +.BR clock_gettime (2) +(using the +.B CLOCK_PROCESS_CPUTIME_ID +clock). +.SH NOTES +The C standard allows for arbitrary values at the start of the program; +subtract the value returned from a call to +.BR clock () +at the start of the program to get maximum portability. +.P +Note that the time can wrap around. +On a 32-bit system where +.B CLOCKS_PER_SEC +equals 1000000 this function will return the same +value approximately every 72 minutes. +.SH SEE ALSO +.BR clock_gettime (2), +.BR getrusage (2), +.BR times (2) diff --git a/man/man3/clock_getcpuclockid.3 b/man/man3/clock_getcpuclockid.3 new file mode 100644 index 0000000..24884d0 --- /dev/null +++ b/man/man3/clock_getcpuclockid.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH clock_getcpuclockid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock_getcpuclockid \- obtain ID of a process CPU-time clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ), +since glibc 2.17 +.P +Before glibc 2.17, +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.B #include <time.h> +.nf +.P +.BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clockid ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clock_getcpuclockid (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR clock_getcpuclockid () +function obtains the ID of the CPU-time clock of the process whose ID is +.IR pid , +and returns it in the location pointed to by +.IR clockid . +If +.I pid +is zero, then the clock ID of the CPU-time clock +of the calling process is returned. +.SH RETURN VALUE +On success, +.BR clock_getcpuclockid () +returns 0; +on error, it returns one of the positive error numbers listed in ERRORS. +.SH ERRORS +.TP +.B ENOSYS +The kernel does not support obtaining the per-process +CPU-time clock of another process, and +.I pid +does not specify the calling process. +.TP +.B EPERM +The caller does not have permission to access +the CPU-time clock of the process specified by +.IR pid . +(Specified in POSIX.1-2001; +does not occur on Linux unless the kernel does not support +obtaining the per-process CPU-time clock of another process.) +.TP +.B ESRCH +There is no process with the ID +.IR pid . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clock_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +Calling +.BR clock_gettime (2) +with the clock ID obtained by a call to +.BR clock_getcpuclockid () +with a +.I pid +of 0, +is the same as using the clock ID +.BR CLOCK_PROCESS_CPUTIME_ID . +.SH EXAMPLES +The example program below obtains the +CPU-time clock ID of the process whose ID is given on the command line, +and then uses +.BR clock_gettime (2) +to obtain the time on that clock. +An example run is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 1" " # Show CPU clock of init process" +CPU\-time clock for PID 1 is 2.213466748 seconds +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (clock_getcpuclockid.c) +.EX +#define _XOPEN_SOURCE 600 +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + clockid_t clockid; + struct timespec ts; +\& + if (argc != 2) { + fprintf(stderr, "%s <process\-ID>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (clock_getcpuclockid(atoi(argv[1]), &clockid) != 0) { + perror("clock_getcpuclockid"); + exit(EXIT_FAILURE); + } +\& + if (clock_gettime(clockid, &ts) == \-1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } +\& + printf("CPU\-time clock for PID %s is %jd.%09ld seconds\en", + argv[1], (intmax_t) ts.tv_sec, ts.tv_nsec); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_getres (2), +.BR timer_create (2), +.BR pthread_getcpuclockid (3), +.BR time (7) diff --git a/man/man3/clog.3 b/man/man3/clog.3 new file mode 100644 index 0000000..6f363dc --- /dev/null +++ b/man/man3/clog.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog, clogf, clogl \- natural logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex clog(double complex " z ); +.BI "float complex clogf(float complex " z ); +.BI "long double complex clogl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex natural logarithm of +.IR z , +with a branch cut along the negative real axis. +.P +The logarithm +.BR clog () +is the inverse function of the exponential +.BR cexp (3). +Thus, if \fIy\ =\ clog(z)\fP, then \fIz\ =\ cexp(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +.P +One has: +.P +.in +4n +.EX +clog(z) = log(cabs(z)) + I * carg(z) +.EE +.in +.P +Note that +.I z +close to zero will cause an overflow. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clog (), +.BR clogf (), +.BR clogl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR clog2 (3), +.BR complex (7) diff --git a/man/man3/clog10.3 b/man/man3/clog10.3 new file mode 100644 index 0000000..0ad3cdc --- /dev/null +++ b/man/man3/clog10.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog10, clog10f, clog10l \- base-10 logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <complex.h> +.P +.BI "double complex clog10(double complex " z ); +.BI "float complex clog10f(float complex " z ); +.BI "long double complex clog10l(long double complex " z ); +.fi +.SH DESCRIPTION +The call +.I clog10(z) +is equivalent to: +.P +.in +4n +.EX +clog(z)/log(10) +.EE +.in +.P +or equally: +.P +.in +4n +.EX +log10(cabs(c)) + I * carg(c) / log(10) +.EE +.in +.P +The other functions perform the same task for +.I float +and +.IR "long double" . +.P +Note that +.I z +close to zero will cause an overflow. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clog10 (), +.BR clog10f (), +.BR clog10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.P +The identifiers are reserved for future use in C99 and C11. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog2 (3), +.BR complex (7) diff --git a/man/man3/clog10f.3 b/man/man3/clog10f.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man/man3/clog10f.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man/man3/clog10l.3 b/man/man3/clog10l.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man/man3/clog10l.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man/man3/clog2.3 b/man/man3/clog2.3 new file mode 100644 index 0000000..155f8b4 --- /dev/null +++ b/man/man3/clog2.3 @@ -0,0 +1,45 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog2, clog2f, clog2l \- base-2 logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex clog2(double complex " z ); +.BI "float complex clog2f(float complex " z ); +.BI "long double complex clog2l(long double complex " z ); +.fi +.SH DESCRIPTION +The call +.I clog2(z) +is equivalent to +.IR clog(z)/log(2) . +.P +The other functions perform the same task for +.I float +and +.IR "long double" . +.P +Note that +.I z +close to zero will cause an overflow. +.SH STANDARDS +None. +.SH HISTORY +These function names are reserved for future use in C99. +.P +Not yet in glibc, as at glibc 2.19. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog10 (3), +.BR complex (7) diff --git a/man/man3/clog2f.3 b/man/man3/clog2f.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man/man3/clog2f.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man/man3/clog2l.3 b/man/man3/clog2l.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man/man3/clog2l.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man/man3/clogf.3 b/man/man3/clogf.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man/man3/clogf.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man/man3/clogl.3 b/man/man3/clogl.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man/man3/clogl.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man/man3/closedir.3 b/man/man3/closedir.3 new file mode 100644 index 0000000..f2142d9 --- /dev/null +++ b/man/man3/closedir.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH closedir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +closedir \- close a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <dirent.h> +.P +.BI "int closedir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR closedir () +function closes the directory stream associated with +.IR dirp . +A successful call to +.BR closedir () +also closes the underlying file descriptor associated with +.IR dirp . +The directory stream descriptor +.I dirp +is not available +after this call. +.SH RETURN VALUE +The +.BR closedir () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor +.IR dirp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR closedir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR close (2), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/closelog.3 b/man/man3/closelog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/closelog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/cmsg.3 b/man/man3/cmsg.3 new file mode 100644 index 0000000..6a4eee4 --- /dev/null +++ b/man/man3/cmsg.3 @@ -0,0 +1,261 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" +.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ +.TH CMSG 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.P +.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); +.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh , +.BR " struct cmsghdr *" cmsg ); +.BI "size_t CMSG_ALIGN(size_t " length ); +.BI "size_t CMSG_SPACE(size_t " length ); +.BI "size_t CMSG_LEN(size_t " length ); +.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); +.fi +.SH DESCRIPTION +These macros are used to create and access control messages (also called +ancillary data) that are not a part of the socket payload. +This control information may +include the interface the packet was received on, various rarely used header +fields, an extended error description, a set of file descriptors, or UNIX +credentials. +For instance, control messages can be used to send +additional header fields such as IP options. +Ancillary data is sent by calling +.BR sendmsg (2) +and received by calling +.BR recvmsg (2). +See their manual pages for more information. +.P +Ancillary data is a sequence of +.I cmsghdr +structures with appended data. +See the specific protocol man pages for the available control message types. +The maximum ancillary buffer size allowed per socket can be set using +.IR /proc/sys/net/core/optmem_max ; +see +.BR socket (7). +.P +The +.I cmsghdr +structure is defined as follows: +.P +.in +4n +.EX +struct cmsghdr { + size_t cmsg_len; /* Data byte count, including header + (type is socklen_t in POSIX) */ + int cmsg_level; /* Originating protocol */ + int cmsg_type; /* Protocol\-specific type */ +/* followed by + unsigned char cmsg_data[]; */ +}; +.EE +.in +.P +The sequence of +.I cmsghdr +structures should never be accessed directly. +Instead, use only the following macros: +.TP +.BR CMSG_FIRSTHDR () +returns a pointer to the first +.I cmsghdr +in the ancillary +data buffer associated with the passed +.IR msghdr . +It returns NULL if there isn't enough space for a +.I cmsghdr +in the buffer. +.TP +.BR CMSG_NXTHDR () +returns the next valid +.I cmsghdr +after the passed +.IR cmsghdr . +It returns NULL when there isn't enough space left in the buffer. +.IP +When initializing a buffer that will contain a series of +.I cmsghdr +structures (e.g., to be sent with +.BR sendmsg (2)), +that buffer should first be zero-initialized +to ensure the correct operation of +.BR CMSG_NXTHDR (). +.TP +.BR CMSG_ALIGN (), +given a length, returns it including the required alignment. +This is a +constant expression. +.TP +.BR CMSG_SPACE () +returns the number of bytes an ancillary element with payload of the +passed data length occupies. +This is a constant expression. +.TP +.BR CMSG_DATA () +returns a pointer to the data portion of a +.IR cmsghdr . +The pointer returned cannot be assumed to be suitably aligned for +accessing arbitrary payload data types. +Applications should not cast it to a pointer type matching the payload, +but should instead use +.BR memcpy (3) +to copy data to or from a suitably declared object. +.TP +.BR CMSG_LEN () +returns the value to store in the +.I cmsg_len +member of the +.I cmsghdr +structure, taking into account any necessary +alignment. +It takes the data length as an argument. +This is a constant +expression. +.P +To create ancillary data, first initialize the +.I msg_controllen +member of the +.I msghdr +with the length of the control message buffer. +Use +.BR CMSG_FIRSTHDR () +on the +.I msghdr +to get the first control message and +.BR CMSG_NXTHDR () +to get all subsequent ones. +In each control message, initialize +.I cmsg_len +(with +.BR CMSG_LEN ()), +the other +.I cmsghdr +header fields, and the data portion using +.BR CMSG_DATA (). +Finally, the +.I msg_controllen +field of the +.I msghdr +should be set to the sum of the +.BR CMSG_SPACE () +of the length of +all control messages in the buffer. +For more information on the +.IR msghdr , +see +.BR recvmsg (2). +.SH VERSIONS +For portability, ancillary data should be accessed using only the macros +described here. +.P +In Linux, +.BR CMSG_LEN (), +.BR CMSG_DATA (), +and +.BR CMSG_ALIGN () +are constant expressions (assuming their argument is constant), +meaning that these values can be used to declare the size of global variables. +This may not be portable, however. +.SH STANDARDS +.TP +.BR CMSG_FIRSTHDR () +.TQ +.BR CMSG_NXTHDR () +.TQ +.BR CMSG_DATA () +POSIX.1-2008. +.TP +.BR CMSG_SPACE () +.TQ +.BR CMSG_LEN () +.TQ +.BR CMSG_ALIGN () +Linux. +.SH HISTORY +This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, +the IPv6 advanced API described in RFC\ 2292 and SUSv2. +.P +.BR CMSG_SPACE () +and +.BR CMSG_LEN () +.\" https://www.austingroupbugs.net/view.php?id=978#c3242 +will be included in the next POSIX release (Issue 8). +.SH EXAMPLES +This code looks for the +.B IP_TTL +option in a received ancillary buffer: +.P +.in +4n +.EX +struct msghdr msgh; +struct cmsghdr *cmsg; +int received_ttl; +\& +/* Receive auxiliary data in msgh */ +\& +for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msgh, cmsg)) { + if (cmsg\->cmsg_level == IPPROTO_IP + && cmsg\->cmsg_type == IP_TTL) { + memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl)); + break; + } +} +\& +if (cmsg == NULL) { + /* Error: IP_TTL not enabled or small buffer or I/O error */ +} +.EE +.in +.P +The code below passes an array of file descriptors over a +UNIX domain socket using +.BR SCM_RIGHTS : +.P +.in +4n +.EX +struct msghdr msg = { 0 }; +struct cmsghdr *cmsg; +int myfds[NUM_FD]; /* Contains the file descriptors to pass */ +char iobuf[1]; +struct iovec io = { + .iov_base = iobuf, + .iov_len = sizeof(iobuf) +}; +union { /* Ancillary data buffer, wrapped in a union + in order to ensure it is suitably aligned */ + char buf[CMSG_SPACE(sizeof(myfds))]; + struct cmsghdr align; +} u; +\& +msg.msg_iov = &io; +msg.msg_iovlen = 1; +msg.msg_control = u.buf; +msg.msg_controllen = sizeof(u.buf); +cmsg = CMSG_FIRSTHDR(&msg); +cmsg\->cmsg_level = SOL_SOCKET; +cmsg\->cmsg_type = SCM_RIGHTS; +cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds)); +memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); +.EE +.in +.P +For a complete code example that shows passing of file descriptors +over a UNIX domain socket, see +.BR seccomp_unotify (2). +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2) +.P +RFC\ 2292 diff --git a/man/man3/confstr.3 b/man/man3/confstr.3 new file mode 100644 index 0000000..bdc0c1a --- /dev/null +++ b/man/man3/confstr.3 @@ -0,0 +1,156 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Many more values for 'name' are supported, some of which +.\" are documented under 'info libc confstr'. +.\" See <bits/confname.h> for the rest. +.\" These should all be added to this page. +.\" See also the POSIX.1-2001 specification of confstr() +.\" +.TH confstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +confstr \- get configuration dependent string variables +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "size_t confstr(int " "name" ", char " buf [. size "], size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR confstr (): +.nf + _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR confstr () +gets the value of configuration-dependent string variables. +.P +The +.I name +argument is the system variable to be queried. +The following variables are supported: +.TP +.BR _CS_GNU_LIBC_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the GNU C library version on this system +(e.g., "glibc 2.3.4"). +.TP +.BR _CS_GNU_LIBPTHREAD_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the POSIX implementation supplied by this +C library (e.g., "NPTL 2.3.4" or "linuxthreads\-0.10"). +.TP +.B _CS_PATH +A value for the +.B PATH +variable which indicates where all the POSIX.2 standard utilities can +be found. +.P +If +.I buf +is not NULL and +.I size +is not zero, +.BR confstr () +copies the value of the string to +.I buf +truncated to +.I size \- 1 +bytes if necessary, with a null byte (\[aq]\e0\[aq]) as terminator. +This can be detected by comparing the return value of +.BR confstr () +against +.IR size . +.P +If +.I size +is zero and +.I buf +is NULL, +.BR confstr () +just returns the value as defined below. +.SH RETURN VALUE +If +.I name +is a valid configuration variable, +.BR confstr () +returns the number of bytes (including the terminating null byte) +that would be required to hold the entire value of that variable. +This value may be greater than +.IR size , +which means that the value in +.I buf +is truncated. +.P +If +.I name +is a valid configuration variable, +but that variable does not have a value, then +.BR confstr () +returns 0. +If +.I name +does not correspond to a valid configuration variable, +.BR confstr () +returns 0, and +.I errno +is set to +.BR EINVAL . +.SH ERRORS +.TP +.B EINVAL +The value of +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR confstr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The following code fragment determines the path where to find +the POSIX.2 system utilities: +.P +.in +4n +.EX +char *pathbuf; +size_t n; +\& +n = confstr(_CS_PATH, NULL, (size_t) 0); +pathbuf = malloc(n); +if (pathbuf == NULL) + abort(); +confstr(_CS_PATH, pathbuf, n); +.EE +.in +.SH SEE ALSO +.BR getconf (1), +.BR sh (1), +.BR exec (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR sysconf (3), +.BR system (3) diff --git a/man/man3/conj.3 b/man/man3/conj.3 new file mode 100644 index 0000000..0924417 --- /dev/null +++ b/man/man3/conj.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH conj 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +conj, conjf, conjl \- calculate the complex conjugate +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex conj(double complex " z ); +.BI "float complex conjf(float complex " z ); +.BI "long double complex conjl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the complex conjugate value of +.IR z . +That is the value obtained by changing the sign of the imaginary part. +.P +One has: +.P +.in +4n +.EX +cabs(z) = csqrt(z * conj(z)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR conj (), +.BR conjf (), +.BR conjl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR csqrt (3), +.BR complex (7) diff --git a/man/man3/conjf.3 b/man/man3/conjf.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man/man3/conjf.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man/man3/conjl.3 b/man/man3/conjl.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man/man3/conjl.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man/man3/copysign.3 b/man/man3/copysign.3 new file mode 100644 index 0000000..2a99367 --- /dev/null +++ b/man/man3/copysign.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.TH copysign 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +copysign, copysignf, copysignl \- copy sign of a number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double copysign(double " x ", double " y ); +.BI "float copysignf(float " x ", float " y ); +.BI "long double copysignl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR copysign (), +.BR copysignf (), +.BR copysignl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value whose absolute value matches that of +.IR x , +but whose sign bit matches that of +.IR y . +.P +For example, +.I "copysign(42.0,\ \-1.0)" +and +.I "copysign(\-42.0, \-1.0)" +both return \-42.0. +.SH RETURN VALUE +On success, these functions return a value whose magnitude is taken from +.I x +and whose sign is taken from +.IR y . +.P +If +.I x +is a NaN, +a NaN with the sign bit of +.I y +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR copysign (), +.BR copysignf (), +.BR copysignl () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On architectures where the floating-point formats are not IEEE 754 compliant, +these functions may treat a negative zero as positive. +.SH STANDARDS +C11, POSIX.1-2008. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH HISTORY +C99, POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR signbit (3) diff --git a/man/man3/copysignf.3 b/man/man3/copysignf.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man/man3/copysignf.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man/man3/copysignl.3 b/man/man3/copysignl.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man/man3/copysignl.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man/man3/cos.3 b/man/man3/cos.3 new file mode 100644 index 0000000..65f4454 --- /dev/null +++ b/man/man3/cos.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH cos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cos, cosf, cosl \- cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double cos(double " x ); +.BI "float cosf(float " x ); +.BI "long double cosl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cosf (), +.BR cosl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the cosine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cos (), +.BR cosf (), +.BR cosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6780 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR ccos (3), +.BR sin (3), +.BR sincos (3), +.BR tan (3) diff --git a/man/man3/cosf.3 b/man/man3/cosf.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man/man3/cosf.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man/man3/cosh.3 b/man/man3/cosh.3 new file mode 100644 index 0000000..aea372e --- /dev/null +++ b/man/man3/cosh.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH cosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cosh, coshf, coshl \- hyperbolic cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double cosh(double " x ); +.BI "float coshf(float " x ); +.BI "long double coshl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR coshf (), +.BR coshl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic cosine of +.IR x , +which is defined mathematically as: +.P +.in +4n +.EX +cosh(x) = (exp(x) + exp(\-x)) / 2 +.EE +.in +.SH RETURN VALUE +On success, these functions return the hyperbolic cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 or \-0, 1 is returned. +.P +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cosh (), +.BR coshf (), +.BR coshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc 2.3.4 and earlier, +an overflow floating-point +.RB ( FE_OVERFLOW ) +exception is not raised when an overflow occurs. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR ccos (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/coshf.3 b/man/man3/coshf.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man/man3/coshf.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man/man3/coshl.3 b/man/man3/coshl.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man/man3/coshl.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man/man3/cosl.3 b/man/man3/cosl.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man/man3/cosl.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man/man3/cpow.3 b/man/man3/cpow.3 new file mode 100644 index 0000000..47666b5 --- /dev/null +++ b/man/man3/cpow.3 @@ -0,0 +1,53 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cpow 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cpow, cpowf, cpowl \- complex power function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cpow(double complex " x ", double complex " z ); +.BI "float complex cpowf(float complex " x ", float complex " z ); +.BI "long double complex cpowl(long double complex " x , +.BI " long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate +.I x +raised to the power +.I z +(with a branch cut for +.I x +along the negative real axis). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cpow (), +.BR cpowf (), +.BR cpowl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR pow (3), +.BR complex (7) diff --git a/man/man3/cpowf.3 b/man/man3/cpowf.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man/man3/cpowf.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man/man3/cpowl.3 b/man/man3/cpowl.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man/man3/cpowl.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man/man3/cproj.3 b/man/man3/cproj.3 new file mode 100644 index 0000000..07b1de3 --- /dev/null +++ b/man/man3/cproj.3 @@ -0,0 +1,59 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cproj 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cproj, cprojf, cprojl \- project into Riemann Sphere +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex cproj(double complex " z ");" +.BI "float complex cprojf(float complex " z ");" +.BI "long double complex cprojl(long double complex " z ");" +.fi +.SH DESCRIPTION +These functions project a point in the plane onto the surface of a +Riemann Sphere, the one-point compactification of the complex plane. +Each finite point +.I z +projects to +.I z +itself. +Every complex infinite value is projected to a single infinite value, +namely to positive infinity on the real axis. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cproj (), +.BR cprojf (), +.BR cprojl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +In glibc 2.11 and earlier, the implementation does something different +(a +.I stereographic +projection onto a Riemann Sphere). +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=10401 +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) diff --git a/man/man3/cprojf.3 b/man/man3/cprojf.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man/man3/cprojf.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man/man3/cprojl.3 b/man/man3/cprojl.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man/man3/cprojl.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man/man3/creal.3 b/man/man3/creal.3 new file mode 100644 index 0000000..c4e5293 --- /dev/null +++ b/man/man3/creal.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH creal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +creal, crealf, creall \- get real part of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double creal(double complex " z ); +.BI "float crealf(float complex " z ); +.BI "long double creall(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the real part of the complex number +.IR z . +.P +One has: +.P +.nf + z = creal(z) + I * cimag(z) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR creal (), +.BR crealf (), +.BR creall () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +GCC supports also __real__. +That is a GNU extension. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cimag (3), +.BR complex (7) diff --git a/man/man3/crealf.3 b/man/man3/crealf.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man/man3/crealf.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man/man3/creall.3 b/man/man3/creall.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man/man3/creall.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man/man3/crypt.3 b/man/man3/crypt.3 new file mode 100644 index 0000000..831a530 --- /dev/null +++ b/man/man3/crypt.3 @@ -0,0 +1,319 @@ +'\" t +.\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de) +.\" Sat Sep 3 22:00:30 MET DST 1994 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away +.\" +.\" TO DO: This manual page should go more into detail how DES is perturbed, +.\" which string will be encrypted, and what determines the repetition factor. +.\" Is a simple repetition using ECB used, or something more advanced? I hope +.\" the presented explanations are at least better than nothing, but by no +.\" means enough. +.\" +.\" added _XOPEN_SOURCE, aeb, 970705 +.\" added GNU MD5 stuff, aeb, 011223 +.\" +.TH crypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +crypt, crypt_r \- password hashing +.SH LIBRARY +Password hashing library +.RI ( libcrypt ", " \-lcrypt ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "char *crypt(const char *" key ", const char *" salt ); +.P +.B #include <crypt.h> +.P +.BI "char *crypt_r(const char *" key ", const char *" salt , +.BI " struct crypt_data *restrict " data ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR crypt (): +.nf + Since glibc 2.28: + _DEFAULT_SOURCE + glibc 2.27 and earlier: + _XOPEN_SOURCE +.fi +.P +.BR crypt_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR crypt () +is the password hashing function. +It is based on the Data Encryption +Standard algorithm with variations intended (among other things) to +discourage use of hardware implementations of a key search. +.P +.I key +is a user's typed password. +.P +.I salt +is a two-character string chosen from the set +[\fBa\-zA\-Z0\-9./\fP]. +This string is used to +perturb the algorithm in one of 4096 different ways. +.P +By taking the lowest 7 bits of each of the first eight characters of the +.IR key , +a 56-bit key is obtained. +This 56-bit key is used to encrypt repeatedly a +constant string (usually a string consisting of all zeros). +The returned +value points to the hashed password, a series of 13 printable ASCII +characters (the first two characters represent the salt itself). +The return value points to static data whose content is +overwritten by each call. +.P +Warning: the key space consists of +.if t 2\s-2\u56\s0\d +.if n 2**56 +equal 7.2e16 possible values. +Exhaustive searches of this key space are +possible using massively parallel computers. +Software, such as +.BR crack (1), +is available which will search the portion of this key space that is +generally used by humans for passwords. +Hence, password selection should, +at minimum, avoid common words and names. +The use of a +.BR passwd (1) +program that checks for crackable passwords during the selection process is +recommended. +.P +The DES algorithm itself has a few quirks which make the use of the +.BR crypt () +interface a very poor choice for anything other than password +authentication. +If you are planning on using the +.BR crypt () +interface for a cryptography project, don't do it: get a good book on +encryption and one of the widely available DES libraries. +.P +.BR crypt_r () +is a reentrant version of +.BR crypt (). +The structure pointed to by +.I data +is used to store result data and bookkeeping information. +Other than allocating it, +the only thing that the caller should do with this structure is to set +.I data\->initialized +to zero before the first call to +.BR crypt_r (). +.SH RETURN VALUE +On success, a pointer to the hashed password is returned. +On error, NULL is returned. +.SH ERRORS +.TP +.B EINVAL +.I salt +has the wrong format. +.TP +.B ENOSYS +The +.BR crypt () +function was not implemented, probably because of U.S.A. export restrictions. +.\" This level of detail is not necessary in this man page. . . +.\" .P +.\" When encrypting a plain text P using DES with the key K results in the +.\" encrypted text C, then the complementary plain text P' being encrypted +.\" using the complementary key K' will result in the complementary encrypted +.\" text C'. +.\" .P +.\" Weak keys are keys which stay invariant under the DES key transformation. +.\" The four known weak keys 0101010101010101, fefefefefefefefe, +.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. +.\" .P +.\" There are six known half weak key pairs, which keys lead to the same +.\" encrypted data. Keys which are part of such key clusters should be +.\" avoided. +.\" Sorry, I could not find out what they are. +.\"" +.\" .P +.\" Heavily redundant data causes trouble with DES encryption, when used in the +.\" .I codebook +.\" mode that +.\" .BR crypt () +.\" implements. The +.\" .BR crypt () +.\" interface should be used only for its intended purpose of password +.\" verification, and should not be used as part of a data encryption tool. +.\" .P +.\" The first and last three output bits of the fourth S-box can be +.\" represented as function of their input bits. Empiric studies have +.\" shown that S-boxes partially compute the same output for similar input. +.\" It is suspected that this may contain a back door which could allow the +.\" NSA to decrypt DES encrypted data. +.\" .P +.\" Making encrypted data computed using crypt() publicly available has +.\" to be considered insecure for the given reasons. +.TP +.B EPERM +.I /proc/sys/crypto/fips_enabled +has a nonzero value, +and an attempt was made to use a weak hashing type, such as DES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR crypt () +T} Thread safety MT-Unsafe race:crypt +T{ +.na +.nh +.BR crypt_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR crypt () +POSIX.1-2008. +.TP +.BR crypt_r () +GNU. +.SH HISTORY +.TP +.BR crypt () +POSIX.1-2001, SVr4, 4.3BSD. +.SS Availability in glibc +The +.BR crypt (), +.BR encrypt (3), +and +.BR setkey (3) +functions are part of the POSIX.1-2008 XSI Options Group for Encryption +and are optional. +If the interfaces are not available, then the symbolic constant +.B _XOPEN_CRYPT +is either not defined, +or it is defined to \-1 and availability can be checked at run time with +.BR sysconf (3). +This may be the case if the downstream distribution has switched from glibc +crypt to +.IR libxcrypt . +When recompiling applications in such distributions, +the programmer must detect if +.B _XOPEN_CRYPT +is not available and include +.I <crypt.h> +for the function prototypes; +otherwise +.I libxcrypt +is an ABI-compatible drop-in replacement. +.SH NOTES +.SS Features in glibc +The glibc version of this function supports additional +hashing algorithms. +.P +If +.I salt +is a character string starting with the characters "$\fIid\fP$" +followed by a string optionally terminated by "$", +then the result has the form: +.RS +.P +$\fIid\fP$\fIsalt\fP$\fIhashed\fP +.RE +.P +.I id +identifies the hashing method used instead of DES and this +then determines how the rest of the password string is interpreted. +The following values of +.I id +are supported: +.RS +.TS +lb lb +l lx. +ID Method +_ +1 MD5 +2a T{ +Blowfish (not in mainline glibc; added in some +Linux distributions) +T} +.\" openSUSE has Blowfish, but AFAICS, this option is not supported +.\" natively by glibc -- mtk, Jul 08 +.\" +.\" md5 | Sun MD5 +.\" glibc doesn't appear to natively support Sun MD5; I don't know +.\" if any distros add the support. +5 SHA-256 (since glibc 2.7) +6 SHA-512 (since glibc 2.7) +.TE +.RE +.P +Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP +contain the password hashed with, respectively, functions +based on SHA-256 and SHA-512. +.P +"\fIsalt\fP" stands for the up to 16 characters +following "$\fIid\fP$" in the salt. +The "\fIhashed\fP" +part of the password string is the actual computed password. +The size of this string is fixed: +.RS +.TS +lb l. +MD5 22 characters +SHA-256 43 characters +SHA-512 86 characters +.TE +.RE +.P +The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set +[\fBa\-zA\-Z0\-9./\fP]. +In the MD5 and SHA implementations the entire +.I key +is significant (instead of only the first +8 bytes in DES). +.P +Since glibc 2.7, +.\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05 +the SHA-256 and SHA-512 implementations support a user-supplied number of +hashing rounds, defaulting to 5000. +If the "$\fIid\fP$" characters in the salt are +followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the +result has the form +.RS +.P +$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP +.RE +.P +where \fIyyy\fP is the number of hashing rounds actually used. +The number of rounds actually used is 1000 if +.I xxx +is less than +1000, 999999999 if +.I xxx +is greater than 999999999, and +is equal to +.I xxx +otherwise. +.SH SEE ALSO +.BR login (1), +.BR passwd (1), +.BR encrypt (3), +.BR getpass (3), +.BR passwd (5) diff --git a/man/man3/crypt_r.3 b/man/man3/crypt_r.3 new file mode 100644 index 0000000..3944ebd --- /dev/null +++ b/man/man3/crypt_r.3 @@ -0,0 +1 @@ +.so man3/crypt.3 diff --git a/man/man3/csin.3 b/man/man3/csin.3 new file mode 100644 index 0000000..350205a --- /dev/null +++ b/man/man3/csin.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csin, csinf, csinl \- complex sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex csin(double complex " z ); +.BI "float complex csinf(float complex " z ); +.BI "long double complex csinl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex sine of +.IR z . +.P +The complex sine function is defined as: +.P +.in +4n +.EX +csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csin (), +.BR csinf (), +.BR csinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR casin (3), +.BR ccos (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/csinf.3 b/man/man3/csinf.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man/man3/csinf.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man/man3/csinh.3 b/man/man3/csinh.3 new file mode 100644 index 0000000..e6e4378 --- /dev/null +++ b/man/man3/csinh.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csinh, csinhf, csinhl \- complex hyperbolic sine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex csinh(double complex " z ); +.BI "float complex csinhf(float complex " z ); +.BI "long double complex csinhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic sine of +.IR z . +.P +The complex hyperbolic sine function is defined as: +.P +.in +4n +.EX +csinh(z) = (exp(z)\-exp(\-z))/2 +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csinh (), +.BR csinhf (), +.BR csinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR casinh (3), +.BR ccosh (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/csinhf.3 b/man/man3/csinhf.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man/man3/csinhf.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man/man3/csinhl.3 b/man/man3/csinhl.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man/man3/csinhl.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man/man3/csinl.3 b/man/man3/csinl.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man/man3/csinl.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man/man3/csqrt.3 b/man/man3/csqrt.3 new file mode 100644 index 0000000..b047a6d --- /dev/null +++ b/man/man3/csqrt.3 @@ -0,0 +1,51 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csqrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csqrt, csqrtf, csqrtl \- complex square root +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex csqrt(double complex " z ); +.BI "float complex csqrtf(float complex " z ); +.BI "long double complex csqrtl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex square root of +.IR z , +with a branch cut along the negative real axis. +(That means that \fIcsqrt(\-1+eps*I)\fP will be close to I while +\fIcsqrt(\-1\-eps*I)\fP will be close to \-I, \fIif eps\fP is a small positive +real number.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csqrt (), +.BR csqrtf (), +.BR csqrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR complex (7) diff --git a/man/man3/csqrtf.3 b/man/man3/csqrtf.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man/man3/csqrtf.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man/man3/csqrtl.3 b/man/man3/csqrtl.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man/man3/csqrtl.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man/man3/ctan.3 b/man/man3/ctan.3 new file mode 100644 index 0000000..4bde5fa --- /dev/null +++ b/man/man3/ctan.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ctan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctan, ctanf, ctanl \- complex tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex ctan(double complex " z ); +.BI "float complex ctanf(float complex " z ); +.BI "long double complex ctanl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex tangent of +.IR z . +.P +The complex tangent function is defined as: +.P +.in +4n +.EX +ctan(z) = csin(z) / ccos(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctan (), +.BR ctanf (), +.BR ctanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR catan (3), +.BR ccos (3), +.BR csin (3), +.BR complex (7) diff --git a/man/man3/ctanf.3 b/man/man3/ctanf.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man/man3/ctanf.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man/man3/ctanh.3 b/man/man3/ctanh.3 new file mode 100644 index 0000000..cd1d161 --- /dev/null +++ b/man/man3/ctanh.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ctanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctanh, ctanhf, ctanhl \- complex hyperbolic tangent +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <complex.h> +.P +.BI "double complex ctanh(double complex " z ); +.BI "float complex ctanhf(float complex " z ); +.BI "long double complex ctanhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic tangent of +.IR z . +.P +The complex hyperbolic tangent function is defined +mathematically as: +.P +.in +4n +.EX +ctanh(z) = csinh(z) / ccosh(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctanh (), +.BR ctanhf (), +.BR ctanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR catanh (3), +.BR ccosh (3), +.BR csinh (3), +.BR complex (7) diff --git a/man/man3/ctanhf.3 b/man/man3/ctanhf.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man/man3/ctanhf.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man/man3/ctanhl.3 b/man/man3/ctanhl.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man/man3/ctanhl.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man/man3/ctanl.3 b/man/man3/ctanl.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man/man3/ctanl.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man/man3/ctermid.3 b/man/man3/ctermid.3 new file mode 100644 index 0000000..b3983a2 --- /dev/null +++ b/man/man3/ctermid.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:51:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH ctermid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctermid \- get controlling terminal name +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.\" POSIX also requires this function to be declared in <unistd.h>, +.\" and glibc does so if suitable feature test macros are defined. +.P +.BI "char *ctermid(char *" "s" ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ctermid (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +.BR ctermid () +returns a string which is the pathname for the current +controlling terminal for this process. +If +.I s +is NULL, +a static buffer is used, otherwise +.I s +points to a buffer used to hold the terminal pathname. +The symbolic constant +.B L_ctermid +is the maximum number of characters in the returned pathname. +.SH RETURN VALUE +The pointer to the pathname. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctermid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, Svr4. +.SH BUGS +The returned pathname may not uniquely identify the controlling +terminal; it may, for example, be +.IR /dev/tty . +.P +It is not assured that the program can open the terminal. +.\" in glibc 2.3.x, x >= 4, the glibc headers threw an error +.\" if ctermid() was given an argument; fixed in glibc 2.4. +.SH SEE ALSO +.BR ttyname (3) diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 0000000..cb33421 --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,429 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) +.\" Modified 2001-11-13, aeb +.\" Modified 2001-12-13, joey, aeb +.\" Modified 2004-11-16, mtk +.\" +.TH ctime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, +localtime_r \- transform date and time to broken-down time or ASCII +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "char *asctime(const struct tm *" tm ); +.BI "char *asctime_r(const struct tm *restrict " tm , +.BI " char " buf "[restrict 26]);" +.P +.BI "char *ctime(const time_t *" timep ); +.BI "char *ctime_r(const time_t *restrict " timep , +.BI " char " buf "[restrict 26]);" +.P +.BI "struct tm *gmtime(const time_t *" timep ); +.BI "struct tm *gmtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "struct tm *localtime(const time_t *" timep ); +.BI "struct tm *localtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "time_t mktime(struct tm *" tm ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +functions all take +an argument of data type \fItime_t\fP, which represents calendar time. +When interpreted as an absolute time value, it represents the number of +seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +The +.BR asctime () +and +.BR mktime () +functions both take an argument +representing broken-down time, which is a representation +separated into year, month, day, and so on. +.P +Broken-down time is stored in the structure +.IR tm , +described in +.BR tm (3type). +.P +The call +.BI ctime( t ) +is equivalent to +.BI asctime(localtime( t )) \fR. +It converts the calendar time \fIt\fP into a +null-terminated string of the form +.P +.in +4n +.EX +"Wed Jun 30 21:49:08 1993\en" +.EE +.in +.P +The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", +"Thu", "Fri", and "Sat". +The abbreviations for the months are "Jan", +"Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and +"Dec". +The return value points to a statically allocated string which +might be overwritten by subsequent calls to any of the date and time +functions. +The function also sets the external +variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see +.BR tzset (3)) +with information about the current timezone. +The reentrant version +.BR ctime_r () +does the same, but stores the +string in a user-supplied buffer +which should have room for at least 26 bytes. +It need not +set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.P +The +.BR gmtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, expressed in Coordinated Universal Time +(UTC). +It may return NULL when the year does not fit into an integer. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR gmtime_r () +function does the same, but stores the data in a +user-supplied struct. +.P +The +.BR localtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, +expressed relative to the user's specified timezone. +The function acts as if it called +.BR tzset (3) +and sets the external variables \fItzname\fP with +information about the current timezone, \fItimezone\fP with the difference +between Coordinated Universal Time (UTC) and local standard time in +seconds, and \fIdaylight\fP to a nonzero value if daylight savings +time rules apply during some part of the year. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR localtime_r () +function does the same, but stores the data in a +user-supplied struct. +It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.P +The +.BR asctime () +function converts the broken-down time value +\fItm\fP into a null-terminated string with the same format as +.BR ctime (). +The return value points to a statically allocated string which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR asctime_r () +function does the same, but stores the string in +a user-supplied buffer which should have room for at least 26 bytes. +.P +The +.BR 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 +.I tm_wday +and +.I tm_yday +fields. +The value specified in the +.I tm_isdst +field informs +.BR mktime () +whether or not daylight saving time (DST) +is in effect for the time supplied in the +.I tm +structure: +a positive value means DST is in effect; +zero means that DST is not in effect; +and a negative value means that +.BR mktime () +should (use timezone information and system databases to) +attempt to determine whether DST is in effect at the specified time. +.P +The +.BR mktime () +function modifies the fields of the +.I tm +structure as follows: +.I tm_wday +and +.I tm_yday +are set to values determined from the contents of the other fields; +if structure members are outside their valid interval, they will be +normalized (so that, for example, 40 October is changed into 9 November); +.I tm_isdst +is set (regardless of its initial value) +to a positive value or to 0, respectively, +to indicate whether DST is or is not in effect at the specified time. +Calling +.BR mktime () +also sets the external variable \fItzname\fP with +information about the current timezone. +.P +If the specified broken-down +time cannot be represented as calendar time (seconds since the Epoch), +.BR mktime () +returns +.I (time_t)\ \-1 +and does not alter the +members of the broken-down time structure. +.SH RETURN VALUE +On success, +.BR gmtime () +and +.BR localtime () +return a pointer to a +.IR "struct\ tm" . +.P +On success, +.BR gmtime_r () +and +.BR localtime_r () +return the address of the structure pointed to by +.IR result . +.P +On success, +.BR asctime () +and +.BR ctime () +return a pointer to a string. +.P +On success, +.BR asctime_r () +and +.BR ctime_r () +return a pointer to the string pointed to by +.IR buf . +.P +On success, +.BR mktime () +returns the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +.P +On error, +.BR mktime () +returns the value +.IR "(time_t)\ \-1" . +The remaining functions return NULL on error. +On error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:asctime locale +T} +T{ +.na +.nh +.BR asctime_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +T{ +.na +.nh +.BR ctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf +race:asctime env locale +T} +T{ +.na +.nh +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (), +.BR mktime () +T} Thread safety T{ +.na +.nh +MT-Safe env locale +T} +T{ +.na +.nh +.BR gmtime (), +.BR localtime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf env locale +T} +.TE +.SH VERSIONS +POSIX doesn't specify the parameters of +.BR ctime_r () +to be +.IR restrict ; +that is specific to glibc. +.P +In many implementations, including glibc, a 0 in +.I tm_mday +is interpreted as meaning the last day of the preceding month. +.P +According to POSIX.1-2001, +.BR localtime () +is required to behave as though +.BR tzset (3) +was called, while +.BR localtime_r () +does not have this requirement. +.\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ +For portable code, +.BR tzset (3) +should be called before +.BR localtime_r (). +.SH STANDARDS +.TP +.BR asctime () +.TQ +.BR ctime () +.TQ +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C11, POSIX.1-2008. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +.TQ +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C89, POSIX.1-2001. +.TP +.BR asctime () +.TQ +.BR ctime () +C89, POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.TP +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2001. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.SH NOTES +The four functions +.BR asctime (), +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +return a pointer to static data and hence are not thread-safe. +The thread-safe versions, +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r (), +and +.BR localtime_r (), +are specified by SUSv2. +.P +POSIX.1-2001 says: +"The +.BR asctime (), +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +functions shall return values in one of two static objects: +a broken-down time structure and an array of type +.IR char . +Execution of any of the functions may overwrite the information returned +in either of these objects by any of the other functions." +This can occur in the glibc implementation. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR utime (2), +.BR clock (3), +.BR difftime (3), +.BR strftime (3), +.BR strptime (3), +.BR timegm (3), +.BR tzset (3), +.BR time (7) diff --git a/man/man3/ctime_r.3 b/man/man3/ctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/ctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/cuserid.3 b/man/man3/cuserid.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man/man3/cuserid.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man/man3/daemon.3 b/man/man3/daemon.3 new file mode 100644 index 0000000..a3d8794 --- /dev/null +++ b/man/man3/daemon.3 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 +.\" Added mentioning of glibc weirdness wrt unistd.h. 5/11/98, Al Viro +.TH daemon 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +daemon \- run in the background +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int daemon(int " nochdir ", int " noclose ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR daemon (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The +.BR daemon () +function is for programs wishing to detach themselves from the +controlling terminal and run in the background as system daemons. +.P +If +.I nochdir +is zero, +.BR daemon () +changes the process's current working directory +to the root directory ("/"); +otherwise, the current working directory is left unchanged. +.P +If +.I noclose +is zero, +.BR daemon () +redirects standard input, standard output, and standard error +to +.IR /dev/null ; +otherwise, no changes are made to these file descriptors. +.SH RETURN VALUE +(This function forks, and if the +.BR fork (2) +succeeds, the parent calls +.\" not .IR in order not to underline _ +.BR _exit (2), +so that further errors are seen by the child only.) +On success +.BR daemon () +returns zero. +If an error occurs, +.BR daemon () +returns \-1 and sets +.I errno +to any of the errors specified for the +.BR fork (2) +and +.BR setsid (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR daemon () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +A similar function appears on the BSDs. +.P +The glibc implementation can also return \-1 when +.I /dev/null +exists but is not a character device with the expected +major and minor numbers. +In this case, +.I errno +need not be set. +.SH STANDARDS +None. +.SH HISTORY +4.4BSD. +.SH BUGS +The GNU C library implementation of this function was taken from BSD, +and does not employ the double-fork technique (i.e., +.BR fork (2), +.BR setsid (2), +.BR fork (2)) +that is necessary to ensure that the resulting daemon process is +not a session leader. +Instead, the resulting daemon +.I is +a session leader. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=19144 +.\" Tested using a program that uses daemon() and then opens an +.\" otherwise unused console device (/dev/ttyN) that does not +.\" have an associated getty process. +On systems that follow System V semantics (e.g., Linux), +this means that if the daemon opens a terminal that is not +already a controlling terminal for another session, +then that terminal will inadvertently become +the controlling terminal for the daemon. +.SH SEE ALSO +.BR fork (2), +.BR setsid (2), +.BR daemon (7), +.BR logrotate (8) diff --git a/man/man3/daylight.3 b/man/man3/daylight.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/daylight.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/db.3 b/man/man3/db.3 new file mode 100644 index 0000000..03ede66 --- /dev/null +++ b/man/man3/db.3 @@ -0,0 +1 @@ +.so man3/dbopen.3 diff --git a/man/man3/dbopen.3 b/man/man3/dbopen.3 new file mode 100644 index 0000000..e18596f --- /dev/null +++ b/man/man3/dbopen.3 @@ -0,0 +1,536 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 +.\" +.TH dbopen 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +dbopen \- database access methods +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <limits.h> +.B #include <db.h> +.B #include <fcntl.h> +.P +.BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ +", DBTYPE " type , +.BI " const void *" openinfo ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +.BR dbopen () +is the library interface to database files. +The supported file formats are btree, hashed, and UNIX file oriented. +The btree format is a representation of a sorted, balanced tree structure. +The hashed format is an extensible, dynamic hashing scheme. +The flat-file format is a byte stream file with fixed or variable length +records. +The formats and file-format-specific information are described in detail +in their respective manual pages +.BR btree (3), +.BR hash (3), +and +.BR recno (3). +.P +.BR dbopen () +opens +.I file +for reading and/or writing. +Files never intended to be preserved on disk may be created by setting +the +.I file +argument to NULL. +.P +The +.I flags +and +.I mode +arguments are as specified to the +.BR open (2) +routine, however, only the +.BR O_CREAT , +.BR O_EXCL , +.BR O_EXLOCK , +.BR O_NONBLOCK , +.BR O_RDONLY , +.BR O_RDWR , +.BR O_SHLOCK , +and +.B O_TRUNC +flags are meaningful. +(Note, opening a database file +.B O_WRONLY +is not possible.) +.\"Three additional options may be specified by ORing +.\"them into the +.\".I flags +.\"argument. +.\".TP +.\"DB_LOCK +.\"Do the necessary locking in the database to support concurrent access. +.\"If concurrent access isn't needed or the database is read-only this +.\"flag should not be set, as it tends to have an associated performance +.\"penalty. +.\".TP +.\"DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".TP +.\"DB_TXN +.\"Support transactions in the database. +.\"The DB_LOCK and DB_SHMEM flags must be set as well. +.P +The +.I type +argument is of type +.I DBTYPE +(as defined in the +.I <db.h> +include file) and +may be set to +.BR DB_BTREE , +.BR DB_HASH , +or +.BR DB_RECNO . +.P +The +.I openinfo +argument is a pointer to an access-method-specific structure described +in the access method's manual page. +If +.I openinfo +is NULL, each access method will use defaults appropriate for the system +and the access method. +.P +.BR dbopen () +returns a pointer to a +.I DB +structure on success and NULL on error. +The +.I DB +structure is defined in the +.I <db.h> +include file, and contains at +least the following fields: +.P +.in +4n +.EX +typedef struct { + DBTYPE type; + int (*close)(const DB *db); + int (*del)(const DB *db, const DBT *key, unsigned int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, DBT *key, DBT *data, + unsigned int flags); + int (*put)(const DB *db, DBT *key, const DBT *data, + unsigned int flags); + int (*sync)(const DB *db, unsigned int flags); + int (*seq)(const DB *db, DBT *key, DBT *data, + unsigned int flags); +} DB; +.EE +.in +.P +These elements describe a database type and a set of functions performing +various actions. +These functions take a pointer to a structure as returned by +.BR dbopen (), +and sometimes one or more pointers to key/data structures and a flag value. +.TP +.I type +The type of the underlying access method (and file format). +.TP +.I close +A pointer to a routine to flush any cached information to disk, free any +allocated resources, and close the underlying file(s). +Since key/data pairs may be cached in memory, failing to sync the file +with a +.I close +or +.I sync +function may result in inconsistent or lost information. +.I close +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.TP +.I del +A pointer to a routine to remove key/data pairs from the database. +.IP +The argument +.I flag +may be set to the following value: +.RS +.TP +.B R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.RE +.IP +.I delete +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the specified +.I key +was not in the file. +.TP +.I fd +A pointer to a routine which returns a file descriptor representative +of the underlying database. +A file descriptor referencing the same file will be returned to all +processes which call +.BR dbopen () +with the same +.I file +name. +This file descriptor may be safely used as an argument to the +.BR fcntl (2) +and +.BR flock (2) +locking functions. +The file descriptor is not necessarily associated with any of the +underlying files used by the access method. +No file descriptor is available for in memory databases. +.I fd +routines return \-1 on error (setting +.IR errno ), +and the file descriptor on success. +.TP +.I get +A pointer to a routine which is the interface for keyed retrieval from +the database. +The address and length of the data associated with the specified +.I key +are returned in the structure referenced by +.IR data . +.I get +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.I key +was not in the file. +.TP +.I put +A pointer to a routine to store key/data pairs in the database. +.IP +The argument +.I flag +may be set to one of the following values: +.RS +.TP +.B R_CURSOR +Replace the key/data pair referenced by the cursor. +The cursor must have previously been initialized. +.TP +.B R_IAFTER +Append the data immediately after the data referenced by +.IR key , +creating a new key/data pair. +The record number of the appended key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_IBEFORE +Insert the data immediately before the data referenced by +.IR key , +creating a new key/data pair. +The record number of the inserted key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_NOOVERWRITE +Enter the new key/data pair only if the key does not previously exist. +.TP +.B R_SETCURSOR +Store the key/data pair, setting or initializing the position of the +cursor to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_SETCURSOR +is available only for the +.B DB_BTREE +and +.B DB_RECNO +access +methods because it implies that the keys have an inherent order +which does not change. +.IP +.B R_IAFTER +and +.B R_IBEFORE +are available only for the +.B DB_RECNO +access method because they each imply that the access method is able to +create new keys. +This is true only if the keys are ordered and independent, record numbers +for example. +.IP +The default behavior of the +.I put +routines is to enter the new key/data pair, replacing any previously +existing key. +.IP +.I put +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.B R_NOOVERWRITE +.I flag +was set and the key already exists in the file. +.TP +.I seq +A pointer to a routine which is the interface for sequential +retrieval from the database. +The address and length of the key are returned in the structure +referenced by +.IR key , +and the address and length of the data are returned in the +structure referenced +by +.IR data . +.IP +Sequential key/data pair retrieval may begin at any time, and the +position of the "cursor" is not affected by calls to the +.IR del , +.IR get , +.IR put , +or +.I sync +routines. +Modifications to the database during a sequential scan will be reflected +in the scan, that is, +records inserted behind the cursor will not be returned +while records inserted in front of the cursor will be returned. +.IP +The flag value +.B must +be set to one of the following values: +.RS +.TP +.B R_CURSOR +The data associated with the specified key is returned. +This differs from the +.I get +routines in that it sets or initializes the cursor to the location of +the key as well. +(Note, for the +.B DB_BTREE +access method, the returned key is not necessarily an +exact match for the specified key. +The returned key is the smallest key greater than or equal to the specified +key, permitting partial key matches and range searches.) +.TP +.B R_FIRST +The first key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +.TP +.B R_LAST +The last key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.TP +.B R_NEXT +Retrieve the key/data pair immediately after the cursor. +If the cursor is not yet set, this is the same as the +.B R_FIRST +flag. +.TP +.B R_PREV +Retrieve the key/data pair immediately before the cursor. +If the cursor is not yet set, this is the same as the +.B R_LAST +flag. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_LAST +and +.B R_PREV +are available only for the +.B DB_BTREE +and +.B DB_RECNO +access methods because they each imply that the keys have an inherent +order which does not change. +.IP +.I seq +routines return \-1 on error (setting +.IR errno ), +0 on success and 1 if there are no key/data pairs less than or greater +than the specified or current key. +If the +.B DB_RECNO +access method is being used, and if the database file +is a character special file and no complete key/data pairs are currently +available, the +.I seq +routines return 2. +.TP +.I sync +A pointer to a routine to flush any cached information to disk. +If the database is in memory only, the +.I sync +routine has no effect and will always succeed. +.IP +The flag value may be set to the following value: +.RS +.TP +.B R_RECNOSYNC +If the +.B DB_RECNO +access method is being used, this flag causes +the sync routine to apply to the btree file which underlies the +recno file, not the recno file itself. +(See the +.I bfname +field of the +.BR recno (3) +manual page for more information.) +.RE +.IP +.I sync +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.SS Key/data pairs +Access to all file types is based on key/data pairs. +Both keys and data are represented by the following data structure: +.P +.in +4n +.EX +typedef struct { + void *data; + size_t size; +} DBT; +.EE +.in +.P +The elements of the +.I DBT +structure are defined as follows: +.TP +.I data +A pointer to a byte string. +.TP +.I size +The length of the byte string. +.P +Key and data byte strings may reference strings of essentially unlimited +length although any two of them must fit into available memory at the same +time. +It should be noted that the access methods provide no guarantees about +byte string alignment. +.SH ERRORS +The +.BR dbopen () +routine may fail and set +.I errno +for any of the errors specified for the library routines +.BR open (2) +and +.BR malloc (3) +or the following: +.TP +.B EFTYPE +A file is incorrectly formatted. +.TP +.B EINVAL +A parameter has been specified (hash function, pad byte, etc.) that is +incompatible with the current file specification or which is not +meaningful for the function (for example, use of the cursor without +prior initialization) or there is a mismatch between the version +number of file and the software. +.P +The +.I close +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR close (2), +.BR read (2), +.BR write (2), +.BR free (3), +or +.BR fsync (2). +.P +The +.IR del , +.IR get , +.IR put , +and +.I seq +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +.BR free (3), +or +.BR malloc (3). +.P +The +.I fd +routines will fail and set +.I errno +to +.B ENOENT +for in memory databases. +.P +The +.I sync +routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR fsync (2). +.SH BUGS +The typedef +.I DBT +is a mnemonic for "data base thang", and was used +because no one could think of a reasonable name that wasn't already used. +.P +The file descriptor interface is a kludge and will be deleted in a +future version of the interface. +.P +None of the access methods provide any form of concurrent access, +locking, or transactions. +.SH SEE ALSO +.BR btree (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "LIBTP: Portable, Modular Transactions for UNIX" , +Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. diff --git a/man/man3/des_crypt.3 b/man/man3/des_crypt.3 new file mode 100644 index 0000000..a21638a --- /dev/null +++ b/man/man3/des_crypt.3 @@ -0,0 +1,164 @@ +'\" t +.\" @(#)des_crypt.3 2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI; +.\" +.\" Taken from libc4 sources, which say: +.\" Copyright (C) 1993 Eric Young - can be distributed under GPL. +.\" +.\" However, the above header line suggests that this file in fact is +.\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use, +.\" see other Sun RPC sources). +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH des_crypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast +DES encryption +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.\" Sun version +.\" .B #include <des_crypt.h> +.B #include <rpc/des_crypt.h> +.P +.BI "[[deprecated]] int ecb_crypt(char *" key ", char " data [. datalen ], +.BI " unsigned int " datalen ", \ +unsigned int " mode ); +.BI "[[deprecated]] int cbc_crypt(char *" key ", char " data [. datalen ], +.BI " unsigned int " datalen ", \ +unsigned int " mode , +.BI " char *" ivec ); +.P +.BI "[[deprecated]] void des_setparity(char *" key ); +.P +.BI "[[deprecated]] int DES_FAILED(int " status ); +.fi +.SH DESCRIPTION +.BR ecb_crypt () +and +.BR cbc_crypt () +implement the +NBS +DES +(Data Encryption Standard). +These routines are faster and more general purpose than +.BR crypt (3). +They also are able to utilize +DES +hardware if it is available. +.BR ecb_crypt () +encrypts in +ECB +(Electronic Code Book) +mode, which encrypts blocks of data independently. +.BR cbc_crypt () +encrypts in +CBC +(Cipher Block Chaining) +mode, which chains together +successive blocks. +CBC +mode protects against insertions, deletions, and +substitutions of blocks. +Also, regularities in the clear text will +not appear in the cipher text. +.P +Here is how to use these routines. +The first argument, +.IR key , +is the 8-byte encryption key with parity. +To set the key's parity, which for +DES +is in the low bit of each byte, use +.BR des_setparity (). +The second argument, +.IR data , +contains the data to be encrypted or decrypted. +The +third argument, +.IR datalen , +is the length in bytes of +.IR data , +which must be a multiple of 8. +The fourth argument, +.IR mode , +is formed by ORing together some things. +For the encryption direction OR in either +.B DES_ENCRYPT +or +.BR DES_DECRYPT . +For software versus hardware +encryption, OR in either +.B DES_HW +or +.BR DES_SW . +If +.B DES_HW +is specified, and there is no hardware, then the encryption is performed +in software and the routine returns +.BR DESERR_NOHWDEVICE . +For +.BR cbc_crypt (), +the argument +.I ivec +is the 8-byte initialization +vector for the chaining. +It is updated to the next initialization +vector upon return. +.SH RETURN VALUE +.TP +.B DESERR_NONE +No error. +.TP +.B DESERR_NOHWDEVICE +Encryption succeeded, but done in software instead of the requested hardware. +.TP +.B DESERR_HWERROR +An error occurred in the hardware or driver. +.TP +.B DESERR_BADPARAM +Bad argument to routine. +.P +Given a result status +.IR stat , +the macro +.\" .BR DES_FAILED\c +.\" .BR ( stat ) +.BI DES_FAILED( stat ) +is false only for the first two statuses. +.\" So far the Sun page +.\" Some additions - aeb +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecb_crypt (), +.BR cbc_crypt (), +.BR des_setparity () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +glibc 2.1. +Removed in glibc 2.28. +.P +Because they employ the DES block cipher, +which is no longer considered secure, +these functions were removed. +Applications should switch to a modern cryptography library, such as +.BR libgcrypt . +.SH SEE ALSO +.BR des (1), +.BR crypt (3), +.BR xcrypt (3) diff --git a/man/man3/des_setparity.3 b/man/man3/des_setparity.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/des_setparity.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/difftime.3 b/man/man3/difftime.3 new file mode 100644 index 0000000..aa6b248 --- /dev/null +++ b/man/man3/difftime.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:48:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH difftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +difftime \- calculate time difference +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "double difftime(time_t " time1 ", time_t " time0 ); +.fi +.SH DESCRIPTION +The +.BR difftime () +function returns the number of seconds elapsed +between time \fItime1\fP and time \fItime0\fP, represented as a +.IR double . +Each time is a count of seconds. +.P +.I difftime(b,\~a) +acts like +.I (b\-a) +except that the result does not overflow and is rounded to +.IR double . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR difftime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR gmtime (3), +.BR localtime (3) diff --git a/man/man3/dirfd.3 b/man/man3/dirfd.3 new file mode 100644 index 0000000..8fab3c0 --- /dev/null +++ b/man/man3/dirfd.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dirfd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dirfd \- get directory stream file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <dirent.h> +.P +.BI "int dirfd(DIR *" dirp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR dirfd (): +.nf + /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The function +.BR dirfd () +returns the file descriptor associated with the directory stream +.IR dirp . +.P +This file descriptor is the one used internally by the directory stream. +As a result, it is useful only for functions which do not depend on +or alter the file position, such as +.BR fstat (2) +and +.BR fchdir (2). +It will be automatically closed when +.BR closedir (3) +is called. +.SH RETURN VALUE +On success, +.BR dirfd () +returns a file descriptor (a nonnegative integer). +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +POSIX.1-2008 specifies two errors, +neither of which is returned by the current +.\" glibc 2.8 +implementation. +.TP +.B EINVAL +.I dirp +does not refer to a valid directory stream. +.TP +.B ENOTSUP +The implementation does not support the association of a file +descriptor with a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dirfd () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.3BSD-Reno (not in 4.2BSD). +.\" It is present in libc5 (since 5.1.2) and in glibc 2. +.SH SEE ALSO +.BR open (2), +.BR openat (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/dirname.3 b/man/man3/dirname.3 new file mode 100644 index 0000000..9099c1a --- /dev/null +++ b/man/man3/dirname.3 @@ -0,0 +1 @@ +.so man3/basename.3 diff --git a/man/man3/div.3 b/man/man3/div.3 new file mode 100644 index 0000000..36e8a6e --- /dev/null +++ b/man/man3/div.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb +.\" +.TH div 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of +an integer division +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "div_t div(int " numerator ", int " denominator ); +.BI "ldiv_t ldiv(long " numerator ", long " denominator ); +.BI "lldiv_t lldiv(long long " numerator ", long long " denominator ); +.P +.B #include <inttypes.h> +.P +.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR lldiv (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR div () +function computes the value +\fInumerator\fP/\fIdenominator\fP and +returns the quotient and remainder in a structure +named \fIdiv_t\fP that contains +two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. +The quotient is rounded toward zero. +The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. +.P +The +.BR ldiv (), +.BR lldiv (), +and +.BR imaxdiv () +functions do the same, +dividing numbers of the indicated type and +returning the result in a structure +of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP +of the same type as the function arguments. +.SH RETURN VALUE +The \fIdiv_t\fP (etc.) structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR div (), +.BR ldiv (), +.BR lldiv (), +.BR imaxdiv () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.P +.BR lldiv () +and +.BR imaxdiv () +were added in C99. +.SH EXAMPLES +After +.P +.in +4n +.EX +div_t q = div(\-5, 3); +.EE +.in +.P +the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. +.SH SEE ALSO +.BR abs (3), +.BR remainder (3) diff --git a/man/man3/dl_iterate_phdr.3 b/man/man3/dl_iterate_phdr.3 new file mode 100644 index 0000000..a533155 --- /dev/null +++ b/man/man3/dl_iterate_phdr.3 @@ -0,0 +1,345 @@ +'\" t +.\" Copyright (c) 2003, 2017 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dl_iterate_phdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dl_iterate_phdr \- walk through list of shared objects +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <link.h> +.P +.B int dl_iterate_phdr( +.BI " int (*" callback ")(struct dl_phdr_info *" info , +.BI " size_t " size ", void *" data ), +.BI " void *" data ); +.fi +.SH DESCRIPTION +The +.BR dl_iterate_phdr () +function allows an application to inquire at run time to find +out which shared objects it has loaded, +and the order in which they were loaded. +.P +The +.BR dl_iterate_phdr () +function walks through the list of an +application's shared objects and calls the function +.I callback +once for each object, +until either all shared objects have been processed or +.I callback +returns a nonzero value. +.P +Each call to +.I callback +receives three arguments: +.IR info , +which is a pointer to a structure containing information +about the shared object; +.IR size , +which is the size of the structure pointed to by +.IR info ; +and +.IR data , +which is a copy of whatever value was passed by the calling +program as the second argument (also named +.IR data ) +in the call to +.BR dl_iterate_phdr (). +.P +The +.I info +argument is a structure of the following type: +.P +.in +4n +.EX +struct dl_phdr_info { + ElfW(Addr) dlpi_addr; /* Base address of object */ + const char *dlpi_name; /* (Null\-terminated) name of + object */ + const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of + ELF program headers + for this object */ + ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */ +\& + /* The following fields were added in glibc 2.4, after the first + version of this structure was available. Check the \fIsize\fP + argument passed to the dl_iterate_phdr callback to determine + whether or not each later member is available. */ +\& + unsigned long long dlpi_adds; + /* Incremented when a new object may + have been added */ + unsigned long long dlpi_subs; + /* Incremented when an object may + have been removed */ + size_t dlpi_tls_modid; + /* If there is a PT_TLS segment, its module + ID as used in TLS relocations, else zero */ + void *dlpi_tls_data; + /* The address of the calling thread\[aq]s instance + of this module\[aq]s PT_TLS segment, if it has + one and it has been allocated in the calling + thread, otherwise a null pointer */ +}; +.EE +.in +.P +(The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 32-bit platform, +.I ElfW(Addr) +yields the data type name +.IR Elf32_Addr . +Further information on these types can be found in the +.IR <elf.h> " and " <link.h> +header files.) +.P +The +.I dlpi_addr +field indicates the base address of the shared object +(i.e., the difference between the virtual memory address of +the shared object and the offset of that object in the file +from which it was loaded). +The +.I dlpi_name +field is a null-terminated string giving the pathname +from which the shared object was loaded. +.P +To understand the meaning of the +.I dlpi_phdr +and +.I dlpi_phnum +fields, we need to be aware that an ELF shared object consists +of a number of segments, each of which has a corresponding +program header describing the segment. +The +.I dlpi_phdr +field is a pointer to an array of the program headers for this +shared object. +The +.I dlpi_phnum +field indicates the size of this array. +.P +These program headers are structures of the following form: +.P +.in +4n +.EX +typedef struct { + Elf32_Word p_type; /* Segment type */ + Elf32_Off p_offset; /* Segment file offset */ + Elf32_Addr p_vaddr; /* Segment virtual address */ + Elf32_Addr p_paddr; /* Segment physical address */ + Elf32_Word p_filesz; /* Segment size in file */ + Elf32_Word p_memsz; /* Segment size in memory */ + Elf32_Word p_flags; /* Segment flags */ + Elf32_Word p_align; /* Segment alignment */ +} Elf32_Phdr; +.EE +.in +.P +Note that we can calculate the location of a particular program header, +.IR x , +in virtual memory using the formula: +.P +.in +4n +.EX +addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; +.EE +.in +.P +Possible values for +.I p_type +include the following (see +.I <elf.h> +for further details): +.P +.in +4n +.EX +#define PT_LOAD 1 /* Loadable program segment */ +#define PT_DYNAMIC 2 /* Dynamic linking information */ +#define PT_INTERP 3 /* Program interpreter */ +#define PT_NOTE 4 /* Auxiliary information */ +#define PT_SHLIB 5 /* Reserved */ +#define PT_PHDR 6 /* Entry for header table itself */ +#define PT_TLS 7 /* Thread\-local storage segment */ +#define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */ +#define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */ +.\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518 +#define PT_GNU_RELRO 0x6474e552 /* Read\-only after relocation */ +.EE +.in +.SH RETURN VALUE +The +.BR dl_iterate_phdr () +function returns whatever value was returned by the last call to +.IR callback . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dl_iterate_phdr () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Various other systems provide a version of this function, +although details of the returned +.I dl_phdr_info +structure differ. +On the BSDs and Solaris, the structure includes the fields +.IR dlpi_addr , +.IR dlpi_name , +.IR dlpi_phdr , +and +.I dlpi_phnum +in addition to other implementation-specific fields. +.P +Future versions of the C library may add further fields to the +.I dl_phdr_info +structure; in that event, the +.I size +argument provides a mechanism for the callback function to discover +whether it is running on a system with added fields. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.2.4. +.SH NOTES +The first object visited by +.I callback +is the main program. +For the main program, the +.I dlpi_name +field will be an empty string. +.SH EXAMPLES +The following program displays a list of pathnames of the +shared objects it has loaded. +For each shared object, the program lists some information +(virtual address, size, flags, and type) +for each of the objects ELF segments. +.P +The following shell session demonstrates the output +produced by the program on an x86-64 system. +The first shared object for which output is displayed +(where the name is an empty string) +is the main program. +.P +.in +4n +.EX +$ \fB./a.out\fP +Name: "" (9 segments) + 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR + 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP + 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD + 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD + 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC + 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE + 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME + 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK + 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO +Name: "linux\-vdso.so.1" (4 segments) + 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD + 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC + 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE + 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME +Name: "/lib64/libc.so.6" (10 segments) + 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR + 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP + 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD + 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD + 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC + 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE + 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS + 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME + 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK + 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO +Name: "/lib64/ld\-linux\-x86\-64.so.2" (7 segments) + 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD + 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD + 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC + 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE + 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME + 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK + 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dl_iterate_phdr.c) +.EX +#define _GNU_SOURCE +#include <link.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +\& +static int +callback(struct dl_phdr_info *info, size_t size, void *data) +{ + char *type; + int p_type; +\& + printf("Name: \e"%s\e" (%d segments)\en", info\->dlpi_name, + info\->dlpi_phnum); +\& + for (size_t j = 0; j < info\->dlpi_phnum; j++) { + p_type = info\->dlpi_phdr[j].p_type; + type = (p_type == PT_LOAD) ? "PT_LOAD" : + (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_NOTE) ? "PT_NOTE" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_PHDR) ? "PT_PHDR" : + (p_type == PT_TLS) ? "PT_TLS" : + (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" : + (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" : + (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL; +\& + printf(" %2zu: [%14p; memsz:%7jx] flags: %#jx; ", j, + (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr), + (uintmax_t) info\->dlpi_phdr[j].p_memsz, + (uintmax_t) info\->dlpi_phdr[j].p_flags); + if (type != NULL) + printf("%s\en", type); + else + printf("[other (%#x)]\en", p_type); + } +\& + return 0; +} +\& +int +main(void) +{ + dl_iterate_phdr(callback, NULL); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldd (1), +.BR objdump (1), +.BR readelf (1), +.BR dladdr (3), +.BR dlopen (3), +.BR elf (5), +.BR ld.so (8) +.P +.IR "Executable and Linking Format Specification" , +available at various locations online. diff --git a/man/man3/dladdr.3 b/man/man3/dladdr.3 new file mode 100644 index 0000000..889f60a --- /dev/null +++ b/man/man3/dladdr.3 @@ -0,0 +1,275 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dladdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dladdr, dladdr1 \- translate address to symbolic information +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include <dlfcn.h> +.P +.BI "int dladdr(const void *" addr ", Dl_info *" info ); +.BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info , +.BI " int " flags ); +.fi +.SH DESCRIPTION +The function +.BR dladdr () +determines whether the address specified in +.I addr +is located in one of the shared objects loaded by the calling application. +If it is, then +.BR dladdr () +returns information about the shared object and symbol that overlaps +.IR addr . +This information is returned in a +.I Dl_info +structure: +.P +.in +4n +.EX +typedef struct { + const char *dli_fname; /* Pathname of shared object that + contains address */ + void *dli_fbase; /* Base address at which shared + object is loaded */ + const char *dli_sname; /* Name of symbol whose definition + overlaps \fIaddr\fP */ + void *dli_saddr; /* Exact address of symbol named + in \fIdli_sname\fP */ +} Dl_info; +.EE +.in +.P +If no symbol matching +.I addr +could be found, then +.I dli_sname +and +.I dli_saddr +are set to NULL. +.P +The function +.BR dladdr1 () +is like +.BR dladdr (), +but returns additional information via the argument +.IR extra_info . +The information returned depends on the value specified in +.IR flags , +which can have one of the following values: +.TP +.B RTLD_DL_LINKMAP +Obtain a pointer to the link map for the matched file. +The +.I extra_info +argument points to a pointer to a +.I link_map +structure (i.e., +.IR "struct link_map\~**" ), +defined in +.I <link.h> +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ +\& + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.B RTLD_DL_SYMENT +Obtain a pointer to the ELF symbol table entry of the matching symbol. +The +.I extra_info +argument is a pointer to a symbol pointer: +.IR "const ElfW(Sym) **" . +The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 64-bit platform, +.I ElfW(Sym) +yields the data type name +.IR Elf64_Sym , +which is defined in +.I <elf.h> +as: +.IP +.in +4n +.EX +typedef struct { + Elf64_Word st_name; /* Symbol name */ + unsigned char st_info; /* Symbol type and binding */ + unsigned char st_other; /* Symbol visibility */ + Elf64_Section st_shndx; /* Section index */ + Elf64_Addr st_value; /* Symbol value */ + Elf64_Xword st_size; /* Symbol size */ +} Elf64_Sym; +.EE +.in +.IP +The +.I st_name +field is an index into the string table. +.IP +The +.I st_info +field encodes the symbol's type and binding. +The type can be extracted using the macro +.B ELF64_ST_TYPE(st_info) +(or +.B ELF32_ST_TYPE() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STT_NOTYPE Symbol type is unspecified +STT_OBJECT Symbol is a data object +STT_FUNC Symbol is a code object +STT_SECTION Symbol associated with a section +STT_FILE Symbol's name is filename +STT_COMMON Symbol is a common data object +STT_TLS Symbol is thread-local data object +STT_GNU_IFUNC Symbol is indirect code object +.TE +.in +.IP +The symbol binding can be extracted from the +.I st_info +field using the macro +.B ELF64_ST_BIND(st_info) +(or +.B ELF32_ST_BIND() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STB_LOCAL Local symbol +STB_GLOBAL Global symbol +STB_WEAK Weak symbol +STB_GNU_UNIQUE Unique symbol +.TE +.in +.IP +The +.I st_other +field contains the symbol's visibility, which can be extracted using the macro +.B ELF64_ST_VISIBILITY(st_info) +(or +.B ELF32_ST_VISIBILITY() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STV_DEFAULT Default symbol visibility rules +STV_INTERNAL Processor-specific hidden class +STV_HIDDEN Symbol unavailable in other modules +STV_PROTECTED Not preemptible, not exported +.TE +.in +.SH RETURN VALUE +On success, these functions return a nonzero value. +If the address specified in +.I addr +could be matched to a shared object, +but not to a symbol in the shared object, then the +.I info\->dli_sname +and +.I info\->dli_saddr +fields are set to NULL. +.P +If the address specified in +.I addr +could not be matched to a shared object, then these functions return 0. +In this case, an error message is +.I not +.\" According to the FreeBSD man page, dladdr1() does signal an +.\" error via dlerror() for this case. +available via +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dladdr (), +.BR dladdr1 () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR dladdr () +glibc 2.0. +.TP +.BR dladdr1 () +glibc 2.3.3. +.P +Solaris. +.SH BUGS +Sometimes, the function pointers you pass to +.BR dladdr () +may surprise you. +On some architectures (notably i386 and x86-64), +.I dli_fname +and +.I dli_fbase +may end up pointing back at the object from which you called +.BR dladdr (), +even if the function used as an argument should come from +a dynamically linked library. +.P +The problem is that the function pointer will still be resolved +at compile time, but merely point to the +.I plt +(Procedure Linkage Table) +section of the original object (which dispatches the call after +asking the dynamic linker to resolve the symbol). +To work around this, +you can try to compile the code to be position-independent: +then, the compiler cannot prepare the pointer +at compile time any more and +.BR gcc (1) +will generate code that just loads the final symbol address from the +.I got +(Global Offset Table) at run time before passing it to +.BR dladdr (). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) diff --git a/man/man3/dladdr1.3 b/man/man3/dladdr1.3 new file mode 100644 index 0000000..43979e5 --- /dev/null +++ b/man/man3/dladdr1.3 @@ -0,0 +1 @@ +.so man3/dladdr.3 diff --git a/man/man3/dlclose.3 b/man/man3/dlclose.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man/man3/dlclose.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man/man3/dlerror.3 b/man/man3/dlerror.3 new file mode 100644 index 0000000..85c904a --- /dev/null +++ b/man/man3/dlerror.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dlerror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlerror \- obtain error diagnostic for functions in the dlopen API +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include <dlfcn.h> +.P +.B "char *dlerror(void);" +.fi +.SH DESCRIPTION +The +.BR dlerror () +function returns a human-readable, +null-terminated string describing the most recent error +that occurred from a call to one of the functions in the dlopen API +since the last call to +.BR dlerror (). +The returned string does +.I not +include a trailing newline. +.P +.BR dlerror () +returns NULL if no errors have occurred since initialization or since +it was last called. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlerror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.P +SunOS. +.SH NOTES +The message returned by +.BR dlerror () +may reside in a statically allocated buffer that is +overwritten by subsequent +.BR dlerror () +calls. +.\" .P +.\" The string returned by +.\" .BR dlerror () +.\" should not be modified. +.\" Some systems give the prototype as +.\" .sp +.\" .in +5 +.\" .B "const char *dlerror(void);" +.\" .in +.SH EXAMPLES +See +.BR dlopen (3). +.SH SEE ALSO +.BR dladdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3) diff --git a/man/man3/dlinfo.3 b/man/man3/dlinfo.3 new file mode 100644 index 0000000..a9239d9 --- /dev/null +++ b/man/man3/dlinfo.3 @@ -0,0 +1,317 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dlinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlinfo \- obtain information about a dynamically loaded object +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include <link.h> +.B #include <dlfcn.h> +.P +.BR "int dlinfo(void *restrict " handle ", int " request \ +", void *restrict " info ); +.fi +.SH DESCRIPTION +The +.BR dlinfo () +function obtains information about the dynamically loaded object +referred to by +.I handle +(typically obtained by an earlier call to +.BR dlopen (3) +or +.BR dlmopen (3)). +The +.I request +argument specifies which information is to be returned. +The +.I info +argument is a pointer to a buffer used to store information +returned by the call; the type of this argument depends on +.IR request . +.P +The following values are supported for +.I request +(with the corresponding type for +.I info +shown in parentheses): +.TP +.BR RTLD_DI_LMID " (\fILmid_t *\fP)" +Obtain the ID of the link-map list (namespace) in which +.I handle +is loaded. +.TP +.BR RTLD_DI_LINKMAP " (\fIstruct link_map **\fP)" +Obtain a pointer to the +.I link_map +structure corresponding to +.IR handle . +The +.I info +argument points to a pointer to a +.I link_map +structure, defined in +.I <link.h> +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ +\& + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.BR RTLD_DI_ORIGIN " (\fIchar *\fP)" +Copy the pathname of the origin of the shared object corresponding to +.I handle +to the location pointed to by +.IR info . +.TP +.BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)" +Obtain the library search paths for the shared object referred to by +.IR handle . +The +.I info +argument is a pointer to a +.I Dl_serinfo +that contains the search paths. +Because the number of search paths may vary, +the size of the structure pointed to by +.I info +can vary. +The +.B RTLD_DI_SERINFOSIZE +request described below allows applications to size the buffer suitably. +The caller must perform the following steps: +.RS +.IP (1) 5 +Use a +.B RTLD_DI_SERINFOSIZE +request to populate a +.I Dl_serinfo +structure with the size +.RI ( dls_size ) +of the structure needed for the subsequent +.B RTLD_DI_SERINFO +request. +.IP (2) +Allocate a +.I Dl_serinfo +buffer of the correct size +.RI ( dls_size ). +.IP (3) +Use a further +.B RTLD_DI_SERINFOSIZE +request to populate the +.I dls_size +and +.I dls_cnt +fields of the buffer allocated in the previous step. +.IP (4) +Use a +.B RTLD_DI_SERINFO +to obtain the library search paths. +.RE +.IP +The +.I Dl_serinfo +structure is defined as follows: +.IP +.in +4n +.EX +typedef struct { + size_t dls_size; /* Size in bytes of + the whole buffer */ + unsigned int dls_cnt; /* Number of elements + in \[aq]dls_serpath\[aq] */ + Dl_serpath dls_serpath[1]; /* Actually longer, + \[aq]dls_cnt\[aq] elements */ +} Dl_serinfo; +.EE +.in +.IP +Each of the +.I dls_serpath +elements in the above structure is a structure of the following form: +.IP +.in +4n +.EX +typedef struct { + char *dls_name; /* Name of library search + path directory */ + unsigned int dls_flags; /* Indicates where this + directory came from */ +} Dl_serpath; +.EE +.in +.IP +The +.I dls_flags +field is currently unused, and always contains zero. +.TP +.BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)" +Populate the +.I dls_size +and +.I dls_cnt +fields of the +.I Dl_serinfo +structure pointed to by +.I info +with values suitable for allocating a buffer for use in a subsequent +.B RTLD_DI_SERINFO +request. +.TP +.BR RTLD_DI_TLS_MODID " (\fIsize_t *\fP, since glibc 2.4)" +Obtain the module ID of this shared object's TLS (thread-local storage) +segment, as used in TLS relocations. +If this object does not define a TLS segment, zero is placed in +.IR *info . +.TP +.BR RTLD_DI_TLS_DATA " (\fIvoid **\fP, since glibc 2.4)" +Obtain a pointer to the calling +thread's TLS block corresponding to this shared object's TLS segment. +If this object does not define a PT_TLS segment, +or if the calling thread has not allocated a block for it, +NULL is placed in +.IR *info . +.SH RETURN VALUE +On success, +.BR dlinfo () +returns 0. +On failure, it returns \-1; the cause of the error can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlinfo () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The sets of requests supported by the various implementations +overlaps only partially. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.3.3. +Solaris. +.SH EXAMPLES +The program below opens a shared objects using +.BR dlopen (3) +and then uses the +.B RTLD_DI_SERINFOSIZE +and +.B RTLD_DI_SERINFO +requests to obtain the library search path list for the library. +Here is an example of what we might see when running the program: +.P +.in +4n +.EX +$ \fB./a.out /lib64/libm.so.6\fP +dls_serpath[0].dls_name = /lib64 +dls_serpath[1].dls_name = /usr/lib64 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dlinfo.c) +.EX +#define _GNU_SOURCE +#include <dlfcn.h> +#include <link.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + void *handle; + Dl_serinfo serinfo; + Dl_serinfo *sip; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s <libpath>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Obtain a handle for shared object specified on command line. */ +\& + handle = dlopen(argv[1], RTLD_NOW); + if (handle == NULL) { + fprintf(stderr, "dlopen() failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Discover the size of the buffer that we must pass to + RTLD_DI_SERINFO. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Allocate the buffer for use with RTLD_DI_SERINFO. */ +\& + sip = malloc(serinfo.dls_size); + if (sip == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* Initialize the \[aq]dls_size\[aq] and \[aq]dls_cnt\[aq] fields in the newly + allocated buffer. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Fetch and print library search list. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFO failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + for (size_t j = 0; j < serinfo.dls_cnt; j++) + printf("dls_serpath[%zu].dls_name = %s\en", + j, sip\->dls_serpath[j].dls_name); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) diff --git a/man/man3/dlmopen.3 b/man/man3/dlmopen.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man/man3/dlmopen.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man/man3/dlopen.3 b/man/man3/dlopen.3 new file mode 100644 index 0000000..14f1689 --- /dev/null +++ b/man/man3/dlopen.3 @@ -0,0 +1,624 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" written by Adam J. Richter (adam@yggdrasil.com), +.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). +.\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28. +.\" Applied patch by Terran Melconian, aeb, 2001-12-14. +.\" Modified by Hacksaw <hacksaw@hacksaw.org> 2003-03-13. +.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete +.\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16. +.\" Modified by Walter Harms: dladdr, dlvsym +.\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat +.\" +.TH dlopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlclose, dlopen, dlmopen \- +open and close a shared object +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include <dlfcn.h> +.P +.BI "void *dlopen(const char *" filename ", int " flags ); +.BI "int dlclose(void *" handle ); +.P +.B #define _GNU_SOURCE +.br +.B #include <dlfcn.h> +.P +.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags ); +.fi +.SH DESCRIPTION +.SS dlopen() +The function +.BR dlopen () +loads the dynamic shared object (shared library) +file named by the null-terminated +string +.I filename +and returns an opaque "handle" for the loaded object. +This handle is employed with other functions in the dlopen API, such as +.BR dlsym (3), +.BR dladdr (3), +.BR dlinfo (3), +and +.BR dlclose (). +.P +If +.I filename +.\" FIXME On Solaris, when handle is NULL, we seem to get back +.\" a handle for (something like) the root of the namespace. +.\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then +.\" the filename==NULL case returns a different handle than +.\" in the initial namespace. But, on glibc, the same handle is +.\" returned. This is probably a bug in glibc. +.\" +is NULL, then the returned handle is for the main program. +If +.I filename +contains a slash ("/"), then it is interpreted as a (relative +or absolute) pathname. +Otherwise, the dynamic linker searches for the object as follows +(see +.BR ld.so (8) +for further details): +.IP \[bu] 3 +(ELF only) If the calling object +(i.e., the shared library or executable from which +.BR dlopen () +is called) +contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, +then the directories listed in the DT_RPATH tag are searched. +.IP \[bu] +If, at the time that the program was started, the environment variable +.B LD_LIBRARY_PATH +was defined to contain a colon-separated list of directories, +then these are searched. +(As a security measure, this variable is ignored for set-user-ID and +set-group-ID programs.) +.IP \[bu] +(ELF only) If the calling object +contains a DT_RUNPATH tag, then the directories listed in that tag +are searched. +.IP \[bu] +The cache file +.I /etc/ld.so.cache +(maintained by +.BR ldconfig (8)) +is checked to see whether it contains an entry for +.IR filename . +.IP \[bu] +The directories +.I /lib +and +.I /usr/lib +are searched (in that order). +.P +If the object specified by +.I filename +has dependencies on other shared objects, +then these are also automatically loaded by the dynamic linker +using the same rules. +(This process may occur recursively, +if those objects in turn have dependencies, and so on.) +.P +One of the following two values must be included in +.IR flags : +.TP +.B RTLD_LAZY +Perform lazy binding. +Resolve symbols only as the code that references them is executed. +If the symbol is never referenced, then it is never resolved. +(Lazy binding is performed only for function references; +references to variables are always immediately bound when +the shared object is loaded.) +Since glibc 2.1.1, +.\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072 +this flag is overridden by the effect of the +.B LD_BIND_NOW +environment variable. +.TP +.B RTLD_NOW +If this value is specified, or the environment variable +.B LD_BIND_NOW +is set to a nonempty string, +all undefined symbols in the shared object are resolved before +.BR dlopen () +returns. +If this cannot be done, an error is returned. +.P +Zero or more of the following values may also be ORed in +.IR flags : +.TP +.B RTLD_GLOBAL +The symbols defined by this shared object will be +made available for symbol resolution of subsequently loaded shared objects. +.TP +.B RTLD_LOCAL +This is the converse of +.BR RTLD_GLOBAL , +and the default if neither flag is specified. +Symbols defined in this shared object are not made available to resolve +references in subsequently loaded shared objects. +.TP +.BR RTLD_NODELETE " (since glibc 2.2)" +Do not unload the shared object during +.BR dlclose (). +Consequently, the object's static and global variables are not reinitialized +if the object is reloaded with +.BR dlopen () +at a later time. +.TP +.BR RTLD_NOLOAD " (since glibc 2.2)" +Don't load the shared object. +This can be used to test if the object is already resident +.RB ( dlopen () +returns NULL if it is not, or the object's handle if it is resident). +This flag can also be used to promote the flags on a shared object +that is already loaded. +For example, a shared object that was previously loaded with +.B RTLD_LOCAL +can be reopened with +.BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . +.\" +.TP +.BR RTLD_DEEPBIND " (since glibc 2.3.4)" +.\" Inimitably described by UD in +.\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. +Place the lookup scope of the symbols in this +shared object ahead of the global scope. +This means that a self-contained object will use +its own symbols in preference to global symbols with the same name +contained in objects that have already been loaded. +.P +If +.I filename +is NULL, then the returned handle is for the main program. +When given to +.BR dlsym (3), +this handle causes a search for a symbol in the main program, +followed by all shared objects loaded at program startup, +and then all shared objects loaded by +.BR dlopen () +with the flag +.BR RTLD_GLOBAL . +.P +Symbol references in the shared object are resolved using (in order): +symbols in the link map of objects loaded for the main program and its +dependencies; +symbols in shared objects (and their dependencies) +that were previously opened with +.BR dlopen () +using the +.B RTLD_GLOBAL +flag; +and definitions in the shared object itself +(and any dependencies that were loaded for that object). +.P +Any global symbols in the executable that were placed into +its dynamic symbol table by +.BR ld (1) +can also be used to resolve references in a dynamically loaded shared object. +Symbols may be placed in the dynamic symbol table +either because the executable was linked with the flag "\-rdynamic" +(or, synonymously, "\-\-export\-dynamic"), which causes all of +the executable's global symbols to be placed in the dynamic symbol table, +or because +.BR ld (1) +noted a dependency on a symbol in another object during static linking. +.P +If the same shared object is opened again with +.BR dlopen (), +the same object handle is returned. +The dynamic linker maintains reference +counts for object handles, so a dynamically loaded shared object is not +deallocated until +.BR dlclose () +has been called on it as many times as +.BR dlopen () +has succeeded on it. +Constructors (see below) are called only when the object is actually loaded +into memory (i.e., when the reference count increases to 1). +.P +A subsequent +.BR dlopen () +call that loads the same shared object with +.B RTLD_NOW +may force symbol resolution for a shared object earlier loaded with +.BR RTLD_LAZY . +Similarly, an object that was previously opened with +.B RTLD_LOCAL +can be promoted to +.B RTLD_GLOBAL +in a subsequent +.BR dlopen (). +.P +If +.BR dlopen () +fails for any reason, it returns NULL. +.\" +.SS dlmopen() +This function performs the same task as +.BR dlopen ()\[em]the +.I filename +and +.I flags +arguments, as well as the return value, are the same, +except for the differences noted below. +.P +The +.BR dlmopen () +function differs from +.BR dlopen () +primarily in that it accepts an additional argument, +.IR lmid , +that specifies the link-map list (also referred to as a +.IR namespace ) +in which the shared object should be loaded. +(By comparison, +.BR dlopen () +adds the dynamically loaded shared object to the same namespace as +the shared object from which the +.BR dlopen () +call is made.) +The +.I Lmid_t +type is an opaque handle that refers to a namespace. +.P +The +.I lmid +argument is either the ID of an existing namespace +.\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? +(which can be obtained using the +.BR dlinfo (3) +.B RTLD_DI_LMID +request) or one of the following special values: +.TP +.B LM_ID_BASE +Load the shared object in the initial namespace +(i.e., the application's namespace). +.TP +.B LM_ID_NEWLM +Create a new namespace and load the shared object in that namespace. +The object must have been correctly linked +to reference all of the other shared objects that it requires, +since the new namespace is initially empty. +.P +If +.I filename +is NULL, then the only permitted value for +.I lmid +is +.BR LM_ID_BASE . +.SS dlclose() +The function +.BR dlclose () +decrements the reference count on the +dynamically loaded shared object referred to by +.IR handle . +.P +If the object's reference count drops to zero +and no symbols in this object are required by other objects, +then the object is unloaded +after first calling any destructors defined for the object. +(Symbols in this object might be required in another object +because this object was opened with the +.B RTLD_GLOBAL +flag and one of its symbols satisfied a relocation in another object.) +.P +All shared objects that were automatically loaded when +.BR dlopen () +was invoked on the object referred to by +.I handle +are recursively closed in the same manner. +.P +A successful return from +.BR dlclose () +does not guarantee that the symbols associated with +.I handle +are removed from the caller's address space. +In addition to references resulting from explicit +.BR dlopen () +calls, a shared object may have been implicitly loaded +(and reference counted) because of dependencies in other shared objects. +Only when all references have been released can the shared object +be removed from the address space. +.SH RETURN VALUE +On success, +.BR dlopen () +and +.BR dlmopen () +return a non-NULL handle for the loaded object. +On error +(file could not be found, was not readable, had the wrong format, +or caused errors during loading), +these functions return NULL. +.P +On success, +.BR dlclose () +returns 0; on error, it returns a nonzero value. +.P +Errors from these functions can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlopen (), +.BR dlmopen (), +.BR dlclose () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR dlopen () +.TQ +.BR dlclose () +POSIX.1-2008. +.TP +.BR dlmopen () +.TQ +.B RTLD_NOLOAD +.TQ +.B RTLD_NODELETE +GNU. +.TP +.B RTLD_DEEPBIND +Solaris. +.SH HISTORY +.TP +.BR dlopen () +.TQ +.BR dlclose () +glibc 2.0. +POSIX.1-2001. +.TP +.BR dlmopen () +glibc 2.3.4. +.SH NOTES +.SS dlmopen() and namespaces +A link-map list defines an isolated namespace for the +resolution of symbols by the dynamic linker. +Within a namespace, +dependent shared objects are implicitly loaded according to the usual rules, +and symbol references are likewise resolved according to the usual rules, +but such resolution is confined to the definitions provided by the +objects that have been (explicitly and implicitly) loaded into the namespace. +.P +The +.BR dlmopen () +function permits object-load isolation\[em]the ability +to load a shared object in a new namespace without +exposing the rest of the application to the symbols +made available by the new object. +Note that the use of the +.B RTLD_LOCAL +flag is not sufficient for this purpose, +since it prevents a shared object's symbols from being available to +.I any +other shared object. +In some cases, +we may want to make the symbols provided by a dynamically +loaded shared object available to (a subset of) other shared objects +without exposing those symbols to the entire application. +This can be achieved by using a separate namespace and the +.B RTLD_GLOBAL +flag. +.P +The +.BR dlmopen () +function also can be used to provide better isolation than the +.B RTLD_LOCAL +flag. +In particular, shared objects loaded with +.B RTLD_LOCAL +may be promoted to +.B RTLD_GLOBAL +if they are dependencies of another shared object loaded with +.BR RTLD_GLOBAL . +Thus, +.B RTLD_LOCAL +is insufficient to isolate a loaded shared object except in the (uncommon) +case where one has explicit control over all shared object dependencies. +.P +Possible uses of +.BR dlmopen () +are plugins where the author of the plugin-loading framework +can't trust the plugin authors and does not wish +any undefined symbols from the plugin framework to be resolved to plugin +symbols. +Another use is to load the same object more than once. +Without the use of +.BR dlmopen (), +this would require the creation of distinct copies of the shared object file. +Using +.BR dlmopen (), +this can be achieved by loading the same shared object file into +different namespaces. +.P +The glibc implementation supports a maximum of +.\" DL_NNS +16 namespaces. +.\" +.SS Initialization and finalization functions +Shared objects may export functions using the +.B __attribute__((constructor)) +and +.B __attribute__((destructor)) +function attributes. +Constructor functions are executed before +.BR dlopen () +returns, and destructor functions are executed before +.BR dlclose () +returns. +A shared object may export multiple constructors and destructors, +and priorities can be associated with each function +to determine the order in which they are executed. +See the +.B gcc +info pages (under "Function attributes") +.\" info gcc "C Extensions" "Function attributes" +for further information. +.P +An older method of (partially) achieving the same result is via the use of +two special symbols recognized by the linker: +.B _init +and +.BR _fini . +If a dynamically loaded shared object exports a routine named +.BR _init (), +then that code is executed after loading a shared object, before +.BR dlopen () +returns. +If the shared object exports a routine named +.BR _fini (), +then that routine is called just before the object is unloaded. +In this case, one must avoid linking against the system startup files, +which contain default versions of these files; +this can be done by using the +.BR gcc (1) +.I \-nostartfiles +command-line option. +.P +Use of +.B _init +and +.B _fini +is now deprecated in favor of the aforementioned +constructors and destructors, +which among other advantages, +permit multiple initialization and finalization functions to be defined. +.\" +.\" Using these routines, or the gcc +.\" .B \-nostartfiles +.\" or +.\" .B \-nostdlib +.\" options, is not recommended. +.\" Their use may result in undesired behavior, +.\" since the constructor/destructor routines will not be executed +.\" (unless special measures are taken). +.\" .\" void _init(void) __attribute__((constructor)); +.\" .\" void _fini(void) __attribute__((destructor)); +.\" +.P +Since glibc 2.2.3, +.BR atexit (3) +can be used to register an exit handler that is automatically +called when a shared object is unloaded. +.SS History +These functions are part of the dlopen API, derived from SunOS. +.SH BUGS +As at glibc 2.24, specifying the +.B RTLD_GLOBAL +flag when calling +.BR dlmopen () +.\" dlerror(): "invalid mode" +generates an error. +Furthermore, specifying +.B RTLD_GLOBAL +when calling +.BR dlopen () +results in a program crash +.RB ( SIGSEGV ) +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684 +if the call is made from any object loaded in a +namespace other than the initial namespace. +.SH EXAMPLES +The program below loads the (glibc) math library, +looks up the address of the +.BR cos (3) +function, and prints the cosine of 2.0. +The following is an example of building and running the program: +.P +.in +4n +.EX +$ \fBcc dlopen_demo.c \-ldl\fP +$ \fB./a.out\fP +\-0.416147 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dlopen.c) +.EX +#include <dlfcn.h> +#include <stdio.h> +#include <stdlib.h> +\& +#include <gnu/lib\-names.h> /* Defines LIBM_SO (which will be a + string such as "libm.so.6") */ +int +main(void) +{ + void *handle; + double (*cosine)(double); + char *error; +\& + handle = dlopen(LIBM_SO, RTLD_LAZY); + if (!handle) { + fprintf(stderr, "%s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + dlerror(); /* Clear any existing error */ +\& + cosine = (double (*)(double)) dlsym(handle, "cos"); +\& + /* According to the ISO C standard, casting between function + pointers and \[aq]void *\[aq], as done above, produces undefined results. + POSIX.1\-2001 and POSIX.1\-2008 accepted this state of affairs and + proposed the following workaround: +\& + *(void **) (&cosine) = dlsym(handle, "cos"); +\& + This (clumsy) cast conforms with the ISO C standard and will + avoid any compiler warnings. +\& + The 2013 Technical Corrigendum 1 to POSIX.1\-2008 improved matters + by requiring that conforming implementations support casting + \[aq]void *\[aq] to a function pointer. Nevertheless, some compilers + (e.g., gcc with the \[aq]\-pedantic\[aq] option) may complain about the + cast used in this program. */ +.\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 +.\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 +.\" http://austingroupbugs.net/view.php?id=74 +\& + error = dlerror(); + if (error != NULL) { + fprintf(stderr, "%s\en", error); + exit(EXIT_FAILURE); + } +\& + printf("%f\en", (*cosine)(2.0)); + dlclose(handle); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlsym (3), +.BR rtld\-audit (7), +.BR ld.so (8), +.BR ldconfig (8) +.P +gcc info pages, ld info pages diff --git a/man/man3/dlsym.3 b/man/man3/dlsym.3 new file mode 100644 index 0000000..dd5fb99 --- /dev/null +++ b/man/man3/dlsym.3 @@ -0,0 +1,171 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dlsym 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlsym, dlvsym \- obtain address of a symbol in a shared object or executable +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include <dlfcn.h> +.P +.BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol ); +.P +.B #define _GNU_SOURCE +.B #include <dlfcn.h> +.P +.BI "void *dlvsym(void *restrict " handle ", const char *restrict " symbol , +.BI " const char *restrict " version ); +.fi +.SH DESCRIPTION +The function +.BR dlsym () +takes a "handle" of a dynamic loaded shared object returned by +.BR dlopen (3) +along with a null-terminated symbol name, +and returns the address where that symbol is +loaded into memory. +If the symbol is not found, in the specified +object or any of the shared objects that were automatically loaded by +.BR dlopen (3) +when that object was loaded, +.BR dlsym () +returns NULL. +(The search performed by +.BR dlsym () +is breadth first through the dependency tree of these shared objects.) +.P +In unusual cases (see NOTES) the value of the symbol could actually be NULL. +Therefore, a NULL return from +.BR dlsym () +need not indicate an error. +The correct way to distinguish an error from a symbol whose value is NULL +is to call +.BR dlerror (3) +to clear any old error conditions, then call +.BR dlsym (), +and then call +.BR dlerror (3) +again, saving its return value into a variable, and check whether +this saved value is not NULL. +.P +There are two special pseudo-handles that may be specified in +.IR handle : +.TP +.B RTLD_DEFAULT +Find the first occurrence of the desired symbol +using the default shared object search order. +The search will include global symbols in the executable +and its dependencies, +as well as symbols in shared objects that were dynamically loaded with the +.B RTLD_GLOBAL +flag. +.TP +.B RTLD_NEXT +Find the next occurrence of the desired symbol in the search order +after the current object. +This allows one to provide a wrapper +around a function in another shared object, so that, for example, +the definition of a function in a preloaded shared object +(see +.B LD_PRELOAD +in +.BR ld.so (8)) +can find and invoke the "real" function provided in another shared object +(or for that matter, the "next" definition of the function in cases +where there are multiple layers of preloading). +.P +The +.B _GNU_SOURCE +feature test macro must be defined in order to obtain the +definitions of +.B RTLD_DEFAULT +and +.B RTLD_NEXT +from +.IR <dlfcn.h> . +.P +The function +.BR dlvsym () +does the same as +.BR dlsym () +but takes a version string as an additional argument. +.SH RETURN VALUE +On success, +these functions return the address associated with +.IR symbol . +On failure, they return NULL; +the cause of the error can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlsym (), +.BR dlvsym () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR dlsym () +POSIX.1-2008. +.TP +.BR dlvsym () +GNU. +.SH HISTORY +.TP +.BR dlsym () +glibc 2.0. +POSIX.1-2001. +.TP +.BR dlvsym () +glibc 2.1. +.SH NOTES +There are several scenarios when the address of a global symbol is NULL. +For example, a symbol can be placed at zero address by the linker, via +a linker script or with +.I \-\-defsym +command-line option. +Undefined weak symbols also have NULL value. +Finally, the symbol value may be the result of +a GNU indirect function (IFUNC) resolver function that returns +NULL as the resolved value. +In the latter case, +.BR dlsym () +also returns NULL without error. +However, in the former two cases, the +behavior of GNU dynamic linker is inconsistent: relocation processing +succeeds and the symbol can be observed to have NULL value, but +.BR dlsym () +fails and +.BR dlerror () +indicates a lookup error. +.\" +.SS History +The +.BR dlsym () +function is part of the dlopen API, derived from SunOS. +That system does not have +.BR dlvsym (). +.SH EXAMPLES +See +.BR dlopen (3). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR ld.so (8) diff --git a/man/man3/dlvsym.3 b/man/man3/dlvsym.3 new file mode 100644 index 0000000..df2ca09 --- /dev/null +++ b/man/man3/dlvsym.3 @@ -0,0 +1 @@ +.so man3/dlsym.3 diff --git a/man/man3/dn_comp.3 b/man/man3/dn_comp.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/dn_comp.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/dn_expand.3 b/man/man3/dn_expand.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/dn_expand.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/dprintf.3 b/man/man3/dprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/dprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/drand48.3 b/man/man3/drand48.3 new file mode 100644 index 0000000..6d61a08 --- /dev/null +++ b/man/man3/drand48.3 @@ -0,0 +1,262 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH drand48 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, +lcong48 \- generate uniformly distributed pseudo-random numbers +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B double drand48(void); +.BI "double erand48(unsigned short " xsubi [3]); +.P +.B long lrand48(void); +.BI "long nrand48(unsigned short " xsubi [3]); +.P +.B long mrand48(void); +.BI "long jrand48(unsigned short " xsubi [3]); +.P +.BI "void srand48(long " seedval ); +.BI "unsigned short *seed48(unsigned short " seed16v [3]); +.BI "void lcong48(unsigned short " param [7]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR drand48 (), +.\" .BR erand48 (), +.\" .BR lrand48 (), +.\" .BR nrand48 (), +.\" .BR mrand48 (), +.\" .BR jrand48 (), +.\" .BR srand48 (), +.\" .BR seed48 (), +.\" .BR lcong48 (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions generate pseudo-random numbers using the linear congruential +algorithm and 48-bit integer arithmetic. +.P +The +.BR drand48 () +and +.BR erand48 () +functions return nonnegative +double-precision floating-point values uniformly distributed over the interval +[0.0,\ 1.0). +.P +The +.BR lrand48 () +and +.BR nrand48 () +functions return nonnegative +long integers uniformly distributed over the interval [0,\ 2\[ha]31). +.P +The +.BR mrand48 () +and +.BR jrand48 () +functions return signed long +integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31). +.P +The +.BR srand48 (), +.BR seed48 (), +and +.BR lcong48 () +functions are +initialization functions, one of which should be called before using +.BR drand48 (), +.BR lrand48 (), +or +.BR mrand48 (). +The functions +.BR erand48 (), +.BR nrand48 (), +and +.BR jrand48 () +do not require +an initialization function to be called first. +.P +All the functions work by generating a sequence of 48-bit integers, +.IR Xi , +according to the linear congruential formula: +.P +.in +4n +.EX +.B Xn+1 = (aXn + c) mod m, where n >= 0 +.EE +.in +.P +The parameter +.I m += 2\[ha]48, hence 48-bit integer arithmetic is performed. +Unless +.BR lcong48 () +is called, +.I a +and +.I c +are given by: +.P +.in +4n +.EX +.B a = 0x5DEECE66D +.B c = 0xB +.EE +.in +.P +The value returned by any of the functions +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 (), +or +.BR jrand48 () +is +computed by first generating the next 48-bit +.I Xi +in the sequence. +Then the appropriate number of bits, according to the type of data item to +be returned, is copied from the high-order bits of +.I Xi +and transformed +into the returned value. +.P +The functions +.BR drand48 (), +.BR lrand48 (), +and +.BR mrand48 () +store +the last 48-bit +.I Xi +generated in an internal buffer. +The functions +.BR erand48 (), +.BR nrand48 (), +and +.BR jrand48 () +require the calling +program to provide storage for the successive +.I Xi +values in the array +argument +.IR xsubi . +The functions are initialized by placing the initial +value of +.I Xi +into the array before calling the function for the first +time. +.P +The initializer function +.BR srand48 () +sets the high order 32-bits of +.I Xi +to the argument +.IR seedval . +The low order 16-bits are set +to the arbitrary value 0x330E. +.P +The initializer function +.BR seed48 () +sets the value of +.I Xi +to +the 48-bit value specified in the array argument +.IR seed16v . +The +previous value of +.I Xi +is copied into an internal buffer and a +pointer to this buffer is returned by +.BR seed48 (). +.P +The initialization function +.BR lcong48 () +allows the user to specify +initial values for +.IR Xi , +.IR a , +and +.IR c . +Array argument +elements +.I param[0\-2] +specify +.IR Xi , +.I param[3\-5] +specify +.IR a , +and +.I param[6] +specifies +.IR c . +After +.BR lcong48 () +has been called, a subsequent call to either +.BR srand48 () +or +.BR seed48 () +will restore the standard values of +.I a +and +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 (), +.BR jrand48 (), +.BR srand48 (), +.BR seed48 (), +.BR lcong48 () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:drand48 +T} +.TE +.P +The above +functions record global state information for the random number generator, +so they are not thread-safe. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SH SEE ALSO +.BR rand (3), +.BR random (3) diff --git a/man/man3/drand48_r.3 b/man/man3/drand48_r.3 new file mode 100644 index 0000000..8191baa --- /dev/null +++ b/man/man3/drand48_r.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright 2003 Walter Harms, 2004 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 2004-10-31. Text taken from a page by Walter Harms, 2003-09-08 +.\" +.TH drand48_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, +srand48_r, seed48_r, lcong48_r +\- generate uniformly distributed pseudo-random numbers reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int drand48_r(struct drand48_data *restrict " buffer , +.BI " double *restrict " result ); +.BI "int erand48_r(unsigned short " xsubi [3] "," +.BI " struct drand48_data *restrict "buffer , +.BI " double *restrict " result ");" +.P +.BI "int lrand48_r(struct drand48_data *restrict " buffer , +.BI " long *restrict " result ); +.BI "int nrand48_r(unsigned short " xsubi[3] "," +.BI " struct drand48_data *restrict "buffer , +.BI " long *restrict " result ");" +.P +.BI "int mrand48_r(struct drand48_data *restrict " buffer , +.BI " long *restrict " result ");" +.BI "int jrand48_r(unsigned short " xsubi[3] "," +.BI " struct drand48_data *restrict " buffer , +.BI " long *restrict " result ");" +.P +.BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" +.BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer ); +.BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR drand48_r (), +.\" .BR erand48_r (), +.\" .BR lrand48_r (), +.\" .BR nrand48_r (), +.\" .BR mrand48_r (), +.\" .BR jrand48_r (), +.\" .BR srand48_r (), +.\" .BR seed48_r (), +.\" .BR lcong48_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are the reentrant analogs of the functions described in +.BR drand48 (3). +Instead of modifying the global random generator state, they use +the supplied data +.IR buffer . +.P +Before the first use, this struct must be initialized, for example, +by filling it with zeros, or by calling one of the functions +.BR srand48_r (), +.BR seed48_r (), +or +.BR lcong48_r (). +.SH RETURN VALUE +The return value is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drand48_r (), +.BR erand48_r (), +.BR lrand48_r (), +.BR nrand48_r (), +.BR mrand48_r (), +.BR jrand48_r (), +.BR srand48_r (), +.BR seed48_r (), +.BR lcong48_r () +T} Thread safety MT-Safe race:buffer +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) diff --git a/man/man3/drem.3 b/man/man3/drem.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/drem.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/dremf.3 b/man/man3/dremf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/dremf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/dreml.3 b/man/man3/dreml.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/dreml.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/duplocale.3 b/man/man3/duplocale.3 new file mode 100644 index 0000000..6ef42bb --- /dev/null +++ b/man/man3/duplocale.3 @@ -0,0 +1,168 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH duplocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +duplocale \- duplicate a locale object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.BI "locale_t duplocale(locale_t " locobj ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR duplocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR duplocale () +function creates a duplicate of the locale object referred to by +.IR locobj . +.P +If +.I locobj +is +.BR LC_GLOBAL_LOCALE , +.BR duplocale () +creates a locale object containing a copy of the global locale +determined by +.BR setlocale (3). +.SH RETURN VALUE +On success, +.BR duplocale () +returns a handle for the new locale object. +On error, it returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create the duplicate locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +.SH NOTES +Duplicating a locale can serve the following purposes: +.IP \[bu] 3 +To create a copy of a locale object in which one of more categories +are to be modified (using +.BR newlocale (3)). +.IP \[bu] +To obtain a handle for the current locale which can used in +other functions that employ a locale handle, such as +.BR toupper_l (3). +This is done by applying +.BR duplocale () +to the value returned by the following call: +.IP +.in +4n +.EX +loc = uselocale((locale_t) 0); +.EE +.in +.IP +This technique is necessary, because the above +.BR uselocale (3) +call may return the value +.BR LC_GLOBAL_LOCALE , +which results in undefined behavior if passed to functions such as +.BR toupper_l (3). +Calling +.BR duplocale () +can be used to ensure that the +.B LC_GLOBAL_LOCALE +value is converted into a usable locale object. +See EXAMPLES, below. +.P +Each locale object created by +.BR duplocale () +should be deallocated using +.BR freelocale (3). +.SH EXAMPLES +The program below uses +.BR uselocale (3) +and +.BR duplocale () +to obtain a handle for the current locale which is then passed to +.BR toupper_l (3). +The program takes one command-line argument, +a string of characters that is converted to uppercase and +displayed on standard output. +An example of its use is the following: +.P +.in +4n +.EX +$ \fB./a.out abc\fP +ABC +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (duplocale.c) +.EX +#define _XOPEN_SOURCE 700 +#include <ctype.h> +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + locale_t loc, nloc; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* This sequence is necessary, because uselocale() might return + the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an + argument to toupper_l(). */ +\& + loc = uselocale((locale_t) 0); + if (loc == (locale_t) 0) + errExit("uselocale"); +\& + nloc = duplocale(loc); + if (nloc == (locale_t) 0) + errExit("duplocale"); +\& + for (char *p = argv[1]; *p; p++) + putchar(toupper_l(*p, nloc)); +\& + printf("\en"); +\& + freelocale(nloc); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/dysize.3 b/man/man3/dysize.3 new file mode 100644 index 0000000..40c7410 --- /dev/null +++ b/man/man3/dysize.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright 2001 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" aeb: some corrections +.TH dysize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dysize \- get number of days for a given year +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <time.h>" +.P +.BI "int dysize(int " year ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR dysize (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The function returns 365 for a normal year and 366 for a leap year. +The calculation for leap year is based on: +.P +.in +4n +.EX +(year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0) +.EE +.in +.P +The formula is defined in the macro +.I __isleap(year) +also found in +.IR <time.h> . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dysize () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SunOS 4.x. +.P +This is a compatibility function only. +Don't use it in new programs. +.\" The SCO version of this function had a year-2000 problem. +.SH SEE ALSO +.BR strftime (3) diff --git a/man/man3/eaccess.3 b/man/man3/eaccess.3 new file mode 100644 index 0000000..9e50351 --- /dev/null +++ b/man/man3/eaccess.3 @@ -0,0 +1 @@ +.so man3/euidaccess.3 diff --git a/man/man3/ecb_crypt.3 b/man/man3/ecb_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/ecb_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/ecvt.3 b/man/man3/ecvt.3 new file mode 100644 index 0000000..539d182 --- /dev/null +++ b/man/man3/ecvt.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH ecvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ecvt, fcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "[[deprecated]] char *ecvt(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *fcvt(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ecvt (), +.BR fcvt (): +.nf + Since glibc 2.17 + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200809L)) + || /* glibc >= 2.20 */ _DEFAULT_SOURCE + || /* glibc <= 2.19 */ _SVID_SOURCE + glibc 2.12 to glibc 2.16: + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200112L)) + || _SVID_SOURCE + Before glibc 2.12: + _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR ecvt () +function converts \fInumber\fP to a null-terminated +string of \fIndigits\fP digits (where \fIndigits\fP is reduced to a +system-specific limit determined by the precision of a +.IR double ), +and returns a pointer to the string. +The high-order digit is nonzero, unless +.I number +is zero. +The low order digit is rounded. +The string itself does not contain a decimal point; however, +the position of the decimal point relative to the start of the string +is stored in \fI*decpt\fP. +A negative value for \fI*decpt\fP means that +the decimal point is to the left of the start of the string. +If the sign of +\fInumber\fP is negative, \fI*sign\fP is set to a nonzero value, +otherwise it is set to 0. +If +.I number +is zero, it is unspecified whether \fI*decpt\fP is 0 or 1. +.P +The +.BR fcvt () +function is identical to +.BR ecvt (), +except that +\fIndigits\fP specifies the number of digits after the decimal point. +.SH RETURN VALUE +Both the +.BR ecvt () +and +.BR fcvt () +functions return a pointer to a +static string containing the ASCII representation of \fInumber\fP. +The static string is overwritten by each call to +.BR ecvt () +or +.BR fcvt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecvt () +T} Thread safety MT-Unsafe race:ecvt +T{ +.na +.nh +.BR fcvt () +T} Thread safety MT-Unsafe race:fcvt +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr2; +marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removes the specifications of +.BR ecvt () +and +.BR fcvt (), +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH NOTES +.\" Linux libc4 and libc5 specified the type of +.\" .I ndigits +.\" as +.\" .IR size_t . +Not all locales use a point as the radix character ("decimal point"). +.SH SEE ALSO +.BR ecvt_r (3), +.BR gcvt (3), +.BR qecvt (3), +.BR setlocale (3), +.BR sprintf (3) diff --git a/man/man3/ecvt_r.3 b/man/man3/ecvt_r.3 new file mode 100644 index 0000000..4f83f65 --- /dev/null +++ b/man/man3/ecvt_r.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de>. +.\" +.\" Corrected return types; from Fabian; 2004-10-05 +.\" +.TH ecvt_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "[[deprecated]] int ecvt_r(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.BI "[[deprecated]] int fcvt_r(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.P +.BI "[[deprecated]] int qecvt_r(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.BI "[[deprecated]] int qfcvt_r(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +.BR qfcvt_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +and +.BR qfcvt_r () +are identical to +.BR ecvt (3), +.BR fcvt (3), +.BR qecvt (3), +and +.BR qfcvt (3), +respectively, except that they do not return their result in a static +buffer, but instead use the supplied +.I buf +of size +.IR len . +See +.BR ecvt (3) +and +.BR qecvt (3). +.SH RETURN VALUE +These functions return 0 on success, and \-1 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +.BR qfcvt_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +These functions are obsolete. +Instead, +.BR sprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR qecvt (3), +.BR sprintf (3) diff --git a/man/man3/edata.3 b/man/man3/edata.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man/man3/edata.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 new file mode 100644 index 0000000..10ec9ec --- /dev/null +++ b/man/man3/encrypt.3 @@ -0,0 +1,211 @@ +'\" t +.\" Copyright 2000 Nicolás Lichtmaier <nick@debian.org> +.\" Created 2000-07-22 00:52-0300 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2002-07-23 19:21:35 CEST 2002 Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de> +.\" +.\" Modified 2003-04-04, aeb +.\" +.TH encrypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages +.SH LIBRARY +Password hashing library +.RI ( libcrypt ", " \-lcrypt ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <unistd.h> +.P +.BI "[[deprecated]] void encrypt(char " block "[64], int " edflag ); +.P +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <stdlib.h> +.P +.BI "[[deprecated]] void setkey(const char *" key ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <crypt.h> +.P +.BI "[[deprecated]] void setkey_r(const char *" key ", struct crypt_data *" data ); +.BI "[[deprecated]] void encrypt_r(char *" block ", int " edflag , +.BI " struct crypt_data *" data ); +.fi +.SH DESCRIPTION +These functions encrypt and decrypt 64-bit messages. +The +.BR setkey () +function sets the key used by +.BR encrypt (). +The +.I key +argument used here is an array of 64 bytes, each of which has +numerical value 1 or 0. +The bytes key[n] where n=8*i-1 are ignored, +so that the effective key length is 56 bits. +.P +The +.BR encrypt () +function modifies the passed buffer, encoding if +.I edflag +is 0, and decoding if 1 is being passed. +Like the +.I key +argument, also +.I block +is a bit vector representation of the actual value that is encoded. +The result is returned in that same vector. +.P +These two functions are not reentrant, that is, the key data is +kept in static storage. +The functions +.BR setkey_r () +and +.BR encrypt_r () +are the reentrant versions. +They use the following +structure to hold the key data: +.P +.in +4n +.EX +struct crypt_data { + char keysched[16 * 8]; + char sb0[32768]; + char sb1[32768]; + char sb2[32768]; + char sb3[32768]; + char crypt_3_buf[14]; + char current_salt[2]; + long current_saltbits; + int direction; + int initialized; +}; +.EE +.in +.P +Before calling +.BR setkey_r () +set +.I data\->initialized +to zero. +.SH RETURN VALUE +These functions do not return any value. +.SH ERRORS +Set +.I errno +to zero before calling the above functions. +On success, +.I errno +is unchanged. +.TP +.B ENOSYS +The function is not provided. +(For example because of former USA export restrictions.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR encrypt (), +.BR setkey () +T} Thread safety MT-Unsafe race:crypt +T{ +.na +.nh +.BR encrypt_r (), +.BR setkey_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR encrypt () +.TQ +.BR setkey () +POSIX.1-2008. +.TP +.BR encrypt_r () +.TQ +.BR setkey_r () +None. +.SH HISTORY +Removed in glibc 2.28. +.P +Because they employ the DES block cipher, +which is no longer considered secure, +these functions were removed from glibc. +Applications should switch to a modern cryptography library, such as +.BR libgcrypt . +.TP +.BR encrypt () +.TQ +.BR setkey () +POSIX.1-2001, SUS, SVr4. +.SS Availability in glibc +See +.BR crypt (3). +.SS Features in glibc +In glibc 2.2, these functions use the DES algorithm. +.SH EXAMPLES +.\" SRC BEGIN (encrypt.c) +.EX +#define _XOPEN_SOURCE +#include <crypt.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(void) +{ + char key[64]; + char orig[9] = "eggplant"; + char buf[64]; + char txt[9]; +\& + for (size_t i = 0; i < 64; i++) { + key[i] = rand() & 1; + } +\& + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0; j < 8; j++) { + buf[i * 8 + j] = orig[i] >> j & 1; + } + setkey(key); + } + printf("Before encrypting: %s\en", orig); +\& + encrypt(buf, 0); + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0, txt[i] = \[aq]\e0\[aq]; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \[aq]\e0\[aq]; + } + printf("After encrypting: %s\en", txt); +\& + encrypt(buf, 1); + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0, txt[i] = \[aq]\e0\[aq]; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \[aq]\e0\[aq]; + } + printf("After decrypting: %s\en", txt); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR cbc_crypt (3), +.BR crypt (3), +.BR ecb_crypt (3) +.\" .BR fcrypt (3) diff --git a/man/man3/encrypt_r.3 b/man/man3/encrypt_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/encrypt_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/end.3 b/man/man3/end.3 new file mode 100644 index 0000000..3628107 --- /dev/null +++ b/man/man3/end.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH end 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +etext, edata, end \- end of program segments +.SH SYNOPSIS +.nf +.BI extern " etext" ; +.BI extern " edata" ; +.BI extern " end" ; +.fi +.SH DESCRIPTION +The addresses of these symbols indicate the end of various program +segments: +.TP +.I etext +This is the first address past the end of the text segment +(the program code). +.TP +.I edata +This is the first address past the end of the +initialized data segment. +.TP +.I end +This is the first address past the end of the +uninitialized data segment (also known as the BSS segment). +.SH STANDARDS +None. +.SH HISTORY +Although these symbols have long been provided on most UNIX systems, +they are not standardized; use with caution. +.SH NOTES +The program must explicitly declare these symbols; +they are not defined in any header file. +.P +On some systems the names of these symbols are preceded by underscores, +thus: +.IR _etext , +.IR _edata , +and +.IR _end . +These symbols are also defined for programs compiled on Linux. +.P +At the start of program execution, +the program break will be somewhere near +.I &end +(perhaps at the start of the following page). +However, the break will change as memory is allocated via +.BR brk (2) +or +.BR malloc (3). +Use +.BR sbrk (2) +with an argument of zero to find the current value of the program break. +.SH EXAMPLES +When run, the program below produces output such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out" +First address past: + program text (etext) 0x8048568 + initialized data (edata) 0x804a01c + uninitialized data (end) 0x804a024 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (end.c) +.EX +#include <stdio.h> +#include <stdlib.h> +\& +extern char etext, edata, end; /* The symbols must have some type, + or "gcc \-Wall" complains */ +\& +int +main(void) +{ + printf("First address past:\en"); + printf(" program text (etext) %10p\en", &etext); + printf(" initialized data (edata) %10p\en", &edata); + printf(" uninitialized data (end) %10p\en", &end); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR objdump (1), +.BR readelf (1), +.BR sbrk (2), +.BR elf (5) diff --git a/man/man3/endaliasent.3 b/man/man3/endaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/endaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/endfsent.3 b/man/man3/endfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/endfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/endgrent.3 b/man/man3/endgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man/man3/endgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man/man3/endhostent.3 b/man/man3/endhostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/endhostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/endian.3 b/man/man3/endian.3 new file mode 100644 index 0000000..7ff7053 --- /dev/null +++ b/man/man3/endian.3 @@ -0,0 +1,164 @@ +.\" Copyright (C) 2009, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" a few pieces remain from an earlier version +.\" Copyright (C) 2008, Nanno Langstraat <nal@ii.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH endian 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, +htobe64, htole64, be64toh, le64toh \- +convert values between host and big-/little-endian byte order +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <endian.h> +.P +.BI "uint16_t htobe16(uint16_t " host_16bits ); +.BI "uint16_t htole16(uint16_t " host_16bits ); +.BI "uint16_t be16toh(uint16_t " big_endian_16bits ); +.BI "uint16_t le16toh(uint16_t " little_endian_16bits ); +.P +.BI "uint32_t htobe32(uint32_t " host_32bits ); +.BI "uint32_t htole32(uint32_t " host_32bits ); +.BI "uint32_t be32toh(uint32_t " big_endian_32bits ); +.BI "uint32_t le32toh(uint32_t " little_endian_32bits ); +.P +.BI "uint64_t htobe64(uint64_t " host_64bits ); +.BI "uint64_t htole64(uint64_t " host_64bits ); +.BI "uint64_t be64toh(uint64_t " big_endian_64bits ); +.BI "uint64_t le64toh(uint64_t " little_endian_64bits ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR htobe16 (), +.BR htole16 (), +.BR be16toh (), +.BR le16toh (), +.BR htobe32 (), +.BR htole32 (), +.BR be32toh (), +.BR le32toh (), +.BR htobe64 (), +.BR htole64 (), +.BR be64toh (), +.BR le64toh (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.ad +.SH DESCRIPTION +These functions convert the byte encoding of integer values from +the byte order that the current CPU (the "host") uses, +to and from little-endian and big-endian byte order. +.P +The number, +.IR nn , +in the name of each function indicates the size of +integer handled by the function, either 16, 32, or 64 bits. +.P +The functions with names of the form "htobe\fInn\fP" convert +from host byte order to big-endian order. +.P +The functions with names of the form "htole\fInn\fP" convert +from host byte order to little-endian order. +.P +The functions with names of the form "be\fInn\fPtoh" convert +from big-endian order to host byte order. +.P +The functions with names of the form "le\fInn\fPtoh" convert +from little-endian order to host byte order. +.SH VERSIONS +Similar functions are present on the BSDs, +where the required header file is +.I <sys/endian.h> +instead of +.IR <endian.h> . +Unfortunately, +NetBSD, FreeBSD, and glibc haven't followed the original +OpenBSD naming convention for these functions, +whereby the +.I nn +component always appears at the end of the function name +(thus, for example, in NetBSD, FreeBSD, and glibc, +the equivalent of OpenBSDs "betoh32" is "be32toh"). +.SH STANDARDS +None. +.SH HISTORY +glibc 2.9. +.P +These functions are similar to the older +.BR byteorder (3) +family of functions. +For example, +.BR be32toh () +is identical to +.BR ntohl (). +.P +The advantage of the +.BR byteorder (3) +functions is that they are standard functions available +on all UNIX systems. +On the other hand, the fact that they were designed +for use in the context of TCP/IP means that +they lack the 64-bit and little-endian variants described in this page. +.SH EXAMPLES +The program below display the results of converting an integer +from host byte order to both little-endian and big-endian byte order. +Since host byte order is either little-endian or big-endian, +only one of these conversions will have an effect. +When we run this program on a little-endian system such as x86-32, +we see the following: +.P +.in +4n +.EX +$ \fB./a.out\fP +x.u32 = 0x44332211 +htole32(x.u32) = 0x44332211 +htobe32(x.u32) = 0x11223344 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (endian.c) +.EX +#include <endian.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + union { + uint32_t u32; + uint8_t arr[4]; + } x; +\& + x.arr[0] = 0x11; /* Lowest\-address byte */ + x.arr[1] = 0x22; + x.arr[2] = 0x33; + x.arr[3] = 0x44; /* Highest\-address byte */ +\& + printf("x.u32 = %#x\en", x.u32); + printf("htole32(x.u32) = %#x\en", htole32(x.u32)); + printf("htobe32(x.u32) = %#x\en", htobe32(x.u32)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bswap (3), +.BR byteorder (3) diff --git a/man/man3/endmntent.3 b/man/man3/endmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/endmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/endnetent.3 b/man/man3/endnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/endnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/endnetgrent.3 b/man/man3/endnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/endnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/endprotoent.3 b/man/man3/endprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/endprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/endpwent.3 b/man/man3/endpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man/man3/endpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man/man3/endrpcent.3 b/man/man3/endrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/endrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/endservent.3 b/man/man3/endservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/endservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/endspent.3 b/man/man3/endspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/endspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/endttyent.3 b/man/man3/endttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/endttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/endusershell.3 b/man/man3/endusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man/man3/endusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man/man3/endutent.3 b/man/man3/endutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/endutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/endutxent.3 b/man/man3/endutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/endutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/envz.3 b/man/man3/envz.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_add.3 b/man/man3/envz_add.3 new file mode 100644 index 0000000..888fc07 --- /dev/null +++ b/man/man3/envz_add.3 @@ -0,0 +1,168 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH envz_add 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +envz_add, envz_entry, envz_get, envz_merge, +envz_remove, envz_strip \- environment string support +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <envz.h> +.P +.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name \ +", const char *restrict " value ); +.P +.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.P +.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.P +.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " envz2 ", size_t " envz2_len , +.BI " int " override ); +.P +.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name ); +.P +.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.P +An argz vector is a pointer to a character buffer together with a length, +see +.BR argz_add (3). +An envz vector is a special argz vector, namely one where the strings +have the form "name=value". +Everything after the first \[aq]=\[aq] is considered +to be the value. +If there is no \[aq]=\[aq], the value is taken to be NULL. +(While the value in case of a trailing \[aq]=\[aq] is the empty string "".) +.P +These functions are for handling envz vectors. +.P +.BR envz_add () +adds the string +.RI \&" name = value \&" +(in case +.I value +is non-NULL) or +.RI \&" name \&" +(in case +.I value +is NULL) to the envz vector +.RI ( *envz ,\ *envz_len ) +and updates +.I *envz +and +.IR *envz_len . +If an entry with the same +.I name +existed, it is removed. +.P +.BR envz_entry () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the entry if found, or NULL if not. +.P +.BR envz_get () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the value if found, or NULL if not. +(Note that the value can also be NULL, namely when there is +an entry for +.I name +without \[aq]=\[aq] sign.) +.P +.BR envz_merge () +adds each entry in +.I envz2 +to +.IR *envz , +as if with +.BR envz_add (). +If +.I override +is true, then values in +.I envz2 +will supersede those with the same name in +.IR *envz , +otherwise not. +.P +.BR envz_remove () +removes the entry for +.I name +from +.RI ( *envz ,\ *envz_len ) +if there was one. +.P +.BR envz_strip () +removes all entries with value NULL. +.SH RETURN VALUE +All envz functions that do memory allocation have a return type of +.I error_t +(an integer type), +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR envz_add (), +.BR envz_entry (), +.BR envz_get (), +.BR envz_merge (), +.BR envz_remove (), +.BR envz_strip () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH EXAMPLES +.\" SRC BEGIN (envz_add.c) +.EX +#include <envz.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[], char *envp[]) +{ + char *str; + size_t e_len = 0; +\& + for (size_t i = 0; envp[i] != NULL; i++) + e_len += strlen(envp[i]) + 1; +\& + str = envz_entry(*envp, e_len, "HOME"); + printf("%s\en", str); + str = envz_get(*envp, e_len, "HOME"); + printf("%s\en", str); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR argz_add (3) diff --git a/man/man3/envz_entry.3 b/man/man3/envz_entry.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_entry.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_get.3 b/man/man3/envz_get.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_get.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_merge.3 b/man/man3/envz_merge.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_merge.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_remove.3 b/man/man3/envz_remove.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_remove.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_strip.3 b/man/man3/envz_strip.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_strip.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/erand48.3 b/man/man3/erand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/erand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/erand48_r.3 b/man/man3/erand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/erand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/erf.3 b/man/man3/erf.3 new file mode 100644 index 0000000..3cdfb0a --- /dev/null +++ b/man/man3/erf.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH erf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +erf, erff, erfl \- error function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double erf(double " x ); +.BI "float erff(float " x ); +.BI "long double erfl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR erf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR erff (), +.BR erfl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the error function of +.IR x , +defined as +.P +.in +4n +.EX +erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt +.EE +.in +.SH RETURN VALUE +On success, these functions return the value of the error function of +.IR x , +a value in the range [\-1,\ 1]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.P +If +.I x +is subnormal, +a range error occurs, +and the return value is 2*x/sqrt(pi). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow (\fIx\fP is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" It is intentional that these functions do not set errno for this case +.\" see https://www.sourceware.org/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR erf (), +.BR erff (), +.BR erfl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cerf (3), +.BR erfc (3), +.BR exp (3) diff --git a/man/man3/erfc.3 b/man/man3/erfc.3 new file mode 100644 index 0000000..70bdd7a --- /dev/null +++ b/man/man3/erfc.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH erfc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +erfc, erfcf, erfcl \- complementary error function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double erfc(double " x ); +.BI "float erfcf(float " x ); +.BI "long double erfcl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR erfc (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR erfcf (), +.BR erfcl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the complementary error function of +.IR x , +that is, 1.0 \- erf(x). +.SH RETURN VALUE +On success, these functions return the complementary error function of +.IR x , +a value in the range [0,2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 or \-0, 1 is returned. +.P +If +.I x +is positive infinity, ++0 is returned. +.P +If +.I x +is negative infinity, ++2 is returned. +.P +If the function result underflows and produces an unrepresentable value, +the return value is 0.0. +.P +If the function result underflows but produces a representable +(i.e., subnormal) value, +.\" e.g., erfc(27) on x86-32 +that value is returned, and +a range error occurs. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow (result is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" It is intentional that these functions do not set errno for this case +.\" see https://www.sourceware.org/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR erfc (), +.BR erfcf (), +.BR erfcl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH NOTES +The +.BR erfc (), +.BR erfcf (), +and +.BR erfcl () +functions are provided to avoid the loss accuracy that +would occur for the calculation 1-erf(x) for large values of +.I x +(for which the value of erf(x) approaches 1). +.SH SEE ALSO +.BR cerf (3), +.BR erf (3), +.BR exp (3) diff --git a/man/man3/erfcf.3 b/man/man3/erfcf.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man/man3/erfcf.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man/man3/erfcl.3 b/man/man3/erfcl.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man/man3/erfcl.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man/man3/erff.3 b/man/man3/erff.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man/man3/erff.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man/man3/erfl.3 b/man/man3/erfl.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man/man3/erfl.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man/man3/err.3 b/man/man3/err.3 new file mode 100644 index 0000000..3db6703 --- /dev/null +++ b/man/man3/err.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $ +.\" +.\" 2011-09-10, mtk, Converted from mdoc to man macros +.\" +.TH err 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <err.h> +.P +.BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);" +.BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);" +.P +.BI "void warn(const char *" fmt ", ...);" +.BI "void warnx(const char *" fmt ", ...);" +.P +.B #include <stdarg.h> +.P +.BI "[[noreturn]] void verr(int " eval ", const char *" fmt ", va_list " args ); +.BI "[[noreturn]] void verrx(int " eval ", const char *" fmt ", va_list " args ); +.P +.BI "void vwarn(const char *" fmt ", va_list " args ); +.BI "void vwarnx(const char *" fmt ", va_list " args ); +.fi +.SH DESCRIPTION +The +.BR err () +and +.BR warn () +family of functions display a formatted error message on the standard +error output. +In all cases, the last component of the program name, a colon character, +and a space are output. +If the +.I fmt +argument is not NULL, the +.BR printf (3)-like +formatted error message is output. +The output is terminated by a newline character. +.P +The +.BR err (), +.BR verr (), +.BR warn (), +and +.BR vwarn () +functions append an error message obtained from +.BR strerror (3) +based on the global variable +.IR errno , +preceded by another colon and space unless the +.I fmt +argument is +NULL. +.P +The +.BR errx () +and +.BR warnx () +functions do not append an error message. +.P +The +.BR err (), +.BR verr (), +.BR errx (), +and +.BR verrx () +functions do not return, but exit with the value of the argument +.IR eval . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR err (), +.BR errx (), +.BR warn (), +.BR warnx (), +.BR verr (), +.BR verrx (), +.BR vwarn (), +.BR vwarnx () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +.TP +.BR err () +.TQ +.BR warn () +4.4BSD. +.SH EXAMPLES +Display the current +.I errno +information string and exit: +.P +.in +4n +.EX +p = malloc(size); +if (p == NULL) + err(EXIT_FAILURE, NULL); +fd = open(file_name, O_RDONLY, 0); +if (fd == \-1) + err(EXIT_FAILURE, "%s", file_name); +.EE +.in +.P +Display an error message and exit: +.P +.in +4n +.EX +if (tm.tm_hour < START_TIME) + errx(EXIT_FAILURE, "too early, wait until %s", + start_time_string); +.EE +.in +.P +Warn of an error: +.P +.in +4n +.EX +fd = open(raw_device, O_RDONLY, 0); +if (fd == \-1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +fd = open(block_device, O_RDONLY, 0); +if (fd == \-1) + err(EXIT_FAILURE, "%s", block_device); +.EE +.in +.SH SEE ALSO +.BR error (3), +.BR exit (3), +.BR perror (3), +.BR printf (3), +.BR strerror (3) diff --git a/man/man3/errno.3 b/man/man3/errno.3 new file mode 100644 index 0000000..72185eb --- /dev/null +++ b/man/man3/errno.3 @@ -0,0 +1,655 @@ +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 5 Oct 2002, Modified by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Updated for POSIX.1 2001 +.\" 2004-12-17 Martin Schulze <joey@infodrom.org>, mtk +.\" Removed errno declaration prototype, added notes +.\" 2006-02-09 Kurt Wall, mtk +.\" Added non-POSIX errors +.\" +.TH errno 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +errno \- number of last error +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <errno.h> +.\".P +.\".BI "extern int " errno ; +.fi +.SH DESCRIPTION +The +.I <errno.h> +header file defines the integer variable +.IR errno , +which is set by system calls and some library functions in the event +of an error to indicate what went wrong. +.\" +.SS errno +The value in +.I errno +is significant only when the return value of +the call indicated an error +(i.e., \-1 from most system calls; +\-1 or NULL from most library functions); +a function that succeeds +.I is +allowed to change +.IR errno . +The value of +.I errno +is never set to zero by any system call or library function. +.P +For some system calls and library functions (e.g., +.BR getpriority (2)), +\-1 is a valid return on success. +In such cases, a successful return can be distinguished from an error +return by setting +.I errno +to zero before the call, and then, +if the call returns a status that indicates that an error +may have occurred, checking to see if +.I errno +has a nonzero value. +.P +.I errno +is defined by the ISO C standard to be a modifiable lvalue +of type +.IR int , +and must not be explicitly declared; +.I errno +may be a macro. +.I errno +is thread-local; setting it in one thread +does not affect its value in any other thread. +.\" +.SS Error numbers and names +Valid error numbers are all positive numbers. +The +.I <errno.h> +header file defines symbolic names for each +of the possible error numbers that may appear in +.IR errno . +.P +All the error names specified by POSIX.1 +must have distinct values, with the exception of +.B EAGAIN +and +.BR EWOULDBLOCK , +which may be the same. +On Linux, these two have the same value on all architectures. +.P +The error numbers that correspond to each symbolic name +vary across UNIX systems, +and even across different architectures on Linux. +Therefore, numeric values are not included as part of the list of +error names below. +The +.BR perror (3) +and +.BR strerror (3) +functions can be used to convert these names to +corresponding textual error messages. +.P +On any particular Linux system, +one can obtain a list of all symbolic error names and +the corresponding error numbers using the +.BR errno (1) +command (part of the +.I moreutils +package): +.P +.in +4n +.EX +$ \fBerrno \-l\fP +EPERM 1 Operation not permitted +ENOENT 2 No such file or directory +ESRCH 3 No such process +EINTR 4 Interrupted system call +EIO 5 Input/output error +\&... +.EE +.in +.P +The +.BR errno (1) +command can also be used to look up individual error numbers and names, +and to search for errors using strings from the error description, +as in the following examples: +.P +.in +4n +.EX +$ \fBerrno 2\fP +ENOENT 2 No such file or directory +$ \fBerrno ESRCH\fP +ESRCH 3 No such process +$ \fBerrno \-s permission\fP +EACCES 13 Permission denied +.EE +.in +.\".P +.\" POSIX.1 (2001 edition) lists the following symbolic error names. Of +.\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C +.\" Amendment 1 defines the additional error number \fBEILSEQ\fP for +.\" coding errors in multibyte or wide characters. +.\" +.SS List of error names +In the list of the symbolic error names below, +various names are marked as follows: +.TP +.I POSIX.1-2001 +The name is defined by POSIX.1-2001, +and is defined in later POSIX.1 versions, unless otherwise indicated. +.TP +.I POSIX.1-2008 +The name is defined in POSIX.1-2008, +but was not present in earlier POSIX.1 standards. +.TP +.I C99 +The name is defined by C99. +.P +Below is a list of the symbolic error names that are defined on Linux: +.TP 16 +.B E2BIG +Argument list too long (POSIX.1-2001). +.TP +.B EACCES +Permission denied (POSIX.1-2001). +.TP +.B EADDRINUSE +Address already in use (POSIX.1-2001). +.TP +.B EADDRNOTAVAIL +Address not available (POSIX.1-2001). +.\" EADV is only an error on HURD(?) +.TP +.B EAFNOSUPPORT +Address family not supported (POSIX.1-2001). +.TP +.B EAGAIN +Resource temporarily unavailable (may be the same value as +.BR EWOULDBLOCK ) +(POSIX.1-2001). +.TP +.B EALREADY +Connection already in progress (POSIX.1-2001). +.TP +.B EBADE +Invalid exchange. +.TP +.B EBADF +Bad file descriptor (POSIX.1-2001). +.TP +.B EBADFD +File descriptor in bad state. +.TP +.B EBADMSG +Bad message (POSIX.1-2001). +.TP +.B EBADR +Invalid request descriptor. +.TP +.B EBADRQC +Invalid request code. +.TP +.B EBADSLT +Invalid slot. +.\" EBFONT is defined but appears not to be used by kernel or glibc. +.TP +.B EBUSY +Device or resource busy (POSIX.1-2001). +.TP +.B ECANCELED +Operation canceled (POSIX.1-2001). +.TP +.B ECHILD +No child processes (POSIX.1-2001). +.TP +.B ECHRNG +Channel number out of range. +.TP +.B ECOMM +Communication error on send. +.TP +.B ECONNABORTED +Connection aborted (POSIX.1-2001). +.TP +.B ECONNREFUSED +Connection refused (POSIX.1-2001). +.TP +.B ECONNRESET +Connection reset (POSIX.1-2001). +.TP +.B EDEADLK +Resource deadlock avoided (POSIX.1-2001). +.TP +.B EDEADLOCK +On most architectures, a synonym for +.BR EDEADLK . +On some architectures (e.g., Linux MIPS, PowerPC, SPARC), +it is a separate error code "File locking deadlock error". +.TP +.B EDESTADDRREQ +Destination address required (POSIX.1-2001). +.TP +.B EDOM +Mathematics argument out of domain of function (POSIX.1, C99). +.\" EDOTDOT is defined but appears to be unused +.TP +.B EDQUOT +.\" POSIX just says "Reserved" +Disk quota exceeded (POSIX.1-2001). +.TP +.B EEXIST +File exists (POSIX.1-2001). +.TP +.B EFAULT +Bad address (POSIX.1-2001). +.TP +.B EFBIG +File too large (POSIX.1-2001). +.TP +.B EHOSTDOWN +Host is down. +.TP +.B EHOSTUNREACH +Host is unreachable (POSIX.1-2001). +.TP +.B EHWPOISON +Memory page has hardware error. +.TP +.B EIDRM +Identifier removed (POSIX.1-2001). +.TP +.B EILSEQ +Invalid or incomplete multibyte or wide character (POSIX.1, C99). +.IP +The text shown here is the glibc error description; +in POSIX.1, this error is described as "Illegal byte sequence". +.TP +.B EINPROGRESS +Operation in progress (POSIX.1-2001). +.TP +.B EINTR +Interrupted function call (POSIX.1-2001); see +.BR signal (7). +.TP +.B EINVAL +Invalid argument (POSIX.1-2001). +.TP +.B EIO +Input/output error (POSIX.1-2001). +.TP +.B EISCONN +Socket is connected (POSIX.1-2001). +.TP +.B EISDIR +Is a directory (POSIX.1-2001). +.TP +.B EISNAM +Is a named type file. +.TP +.B EKEYEXPIRED +Key has expired. +.TP +.B EKEYREJECTED +Key was rejected by service. +.TP +.B EKEYREVOKED +Key has been revoked. +.TP +.B EL2HLT +Level 2 halted. +.TP +.B EL2NSYNC +Level 2 not synchronized. +.TP +.B EL3HLT +Level 3 halted. +.TP +.B EL3RST +Level 3 reset. +.TP +.B ELIBACC +Cannot access a needed shared library. +.TP +.B ELIBBAD +Accessing a corrupted shared library. +.TP +.B ELIBMAX +Attempting to link in too many shared libraries. +.TP +.B ELIBSCN +\&.lib section in a.out corrupted +.TP +.B ELIBEXEC +Cannot exec a shared library directly. +.TP +.B ELNRNG +.\" ELNRNG appears to be used by a few drivers +Link number out of range. +.TP +.B ELOOP +Too many levels of symbolic links (POSIX.1-2001). +.TP +.B EMEDIUMTYPE +Wrong medium type. +.TP +.B EMFILE +Too many open files (POSIX.1-2001). +Commonly caused by exceeding the +.B RLIMIT_NOFILE +resource limit described in +.BR getrlimit (2). +Can also be caused by exceeding the limit specified in +.IR /proc/sys/fs/nr_open . +.TP +.B EMLINK +Too many links (POSIX.1-2001). +.TP +.B EMSGSIZE +Message too long (POSIX.1-2001). +.TP +.B EMULTIHOP +.\" POSIX says "Reserved" +Multihop attempted (POSIX.1-2001). +.TP +.B ENAMETOOLONG +Filename too long (POSIX.1-2001). +.\" ENAVAIL is defined, but appears not to be used +.TP +.B ENETDOWN +Network is down (POSIX.1-2001). +.TP +.B ENETRESET +Connection aborted by network (POSIX.1-2001). +.TP +.B ENETUNREACH +Network unreachable (POSIX.1-2001). +.TP +.B ENFILE +Too many open files in system (POSIX.1-2001). +On Linux, this is probably a result of encountering the +.I /proc/sys/fs/file\-max +limit (see +.BR proc (5)). +.TP +.B ENOANO +.\" ENOANO appears to be used by a few drivers +No anode. +.TP +.B ENOBUFS +No buffer space available (POSIX.1 (XSI STREAMS option)). +.\" ENOCSI is defined but appears to be unused. +.TP +.B ENODATA +The named attribute does not exist, +or the process has no access to this attribute; see +.BR xattr (7). +.IP +In POSIX.1-2001 (XSI STREAMS option), +this error was described as +"No message is available on the STREAM head read queue". +.TP +.B ENODEV +No such device (POSIX.1-2001). +.TP +.B ENOENT +No such file or directory (POSIX.1-2001). +.IP +Typically, this error results when a specified pathname does not exist, +or one of the components in the directory prefix of a pathname does not exist, +or the specified pathname is a dangling symbolic link. +.TP +.B ENOEXEC +Exec format error (POSIX.1-2001). +.TP +.B ENOKEY +Required key not available. +.TP +.B ENOLCK +No locks available (POSIX.1-2001). +.TP +.B ENOLINK +.\" POSIX says "Reserved" +Link has been severed (POSIX.1-2001). +.TP +.B ENOMEDIUM +No medium found. +.TP +.B ENOMEM +Not enough space/cannot allocate memory (POSIX.1-2001). +.TP +.B ENOMSG +No message of the desired type (POSIX.1-2001). +.TP +.B ENONET +Machine is not on the network. +.TP +.B ENOPKG +Package not installed. +.TP +.B ENOPROTOOPT +Protocol not available (POSIX.1-2001). +.TP +.B ENOSPC +No space left on device (POSIX.1-2001). +.TP +.B ENOSR +No STREAM resources (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSTR +Not a STREAM (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSYS +Function not implemented (POSIX.1-2001). +.TP +.B ENOTBLK +Block device required. +.TP +.B ENOTCONN +The socket is not connected (POSIX.1-2001). +.TP +.B ENOTDIR +Not a directory (POSIX.1-2001). +.TP +.B ENOTEMPTY +Directory not empty (POSIX.1-2001). +.\" ENOTNAM is defined but appears to be unused. +.TP +.B ENOTRECOVERABLE +State not recoverable (POSIX.1-2008). +.TP +.B ENOTSOCK +Not a socket (POSIX.1-2001). +.TP +.B ENOTSUP +Operation not supported (POSIX.1-2001). +.TP +.B ENOTTY +Inappropriate I/O control operation (POSIX.1-2001). +.TP +.B ENOTUNIQ +Name not unique on network. +.TP +.B ENXIO +No such device or address (POSIX.1-2001). +.TP +.B EOPNOTSUPP +Operation not supported on socket (POSIX.1-2001). +.IP +.RB ( ENOTSUP +and +.B EOPNOTSUPP +have the same value on Linux, but +according to POSIX.1 these error values should be distinct.) +.TP +.B EOVERFLOW +Value too large to be stored in data type (POSIX.1-2001). +.TP +.B EOWNERDEAD +.\" Used at least by the user-space side of rubost mutexes +Owner died (POSIX.1-2008). +.TP +.B EPERM +Operation not permitted (POSIX.1-2001). +.TP +.B EPFNOSUPPORT +Protocol family not supported. +.TP +.B EPIPE +Broken pipe (POSIX.1-2001). +.TP +.B EPROTO +Protocol error (POSIX.1-2001). +.TP +.B EPROTONOSUPPORT +Protocol not supported (POSIX.1-2001). +.TP +.B EPROTOTYPE +Protocol wrong type for socket (POSIX.1-2001). +.TP +.B ERANGE +Result too large (POSIX.1, C99). +.TP +.B EREMCHG +Remote address changed. +.TP +.B EREMOTE +Object is remote. +.TP +.B EREMOTEIO +Remote I/O error. +.TP +.B ERESTART +Interrupted system call should be restarted. +.TP +.B ERFKILL +.\" ERFKILL appears to be used by various drivers +Operation not possible due to RF-kill. +.TP +.B EROFS +Read-only filesystem (POSIX.1-2001). +.TP +.B ESHUTDOWN +Cannot send after transport endpoint shutdown. +.TP +.B ESPIPE +Invalid seek (POSIX.1-2001). +.TP +.B ESOCKTNOSUPPORT +Socket type not supported. +.TP +.B ESRCH +No such process (POSIX.1-2001). +.\" ESRMNT is defined but appears not to be used +.TP +.B ESTALE +Stale file handle (POSIX.1-2001). +.IP +This error can occur for NFS and for other filesystems. +.TP +.B ESTRPIPE +Streams pipe error. +.TP +.B ETIME +Timer expired +(POSIX.1 (XSI STREAMS option)). +.IP +(POSIX.1 says "STREAM +.BR ioctl (2) +timeout".) +.TP +.B ETIMEDOUT +Connection timed out (POSIX.1-2001). +.TP +.B ETOOMANYREFS +.\" ETOOMANYREFS seems to be used in net/unix/af_unix.c +Too many references: cannot splice. +.TP +.B ETXTBSY +Text file busy (POSIX.1-2001). +.TP +.B EUCLEAN +Structure needs cleaning. +.TP +.B EUNATCH +Protocol driver not attached. +.TP +.B EUSERS +Too many users. +.TP +.B EWOULDBLOCK +Operation would block (may be same value as +.BR EAGAIN ) +(POSIX.1-2001). +.TP +.B EXDEV +Invalid cross-device link (POSIX.1-2001). +.TP +.B EXFULL +Exchange full. +.SH NOTES +A common mistake is to do +.P +.in +4n +.EX +if (somecall() == \-1) { + printf("somecall() failed\en"); + if (errno == ...) { ... } +} +.EE +.in +.P +where +.I errno +no longer needs to have the value it had upon return from +.IR somecall () +(i.e., it may have been changed by the +.BR printf (3)). +If the value of +.I errno +should be preserved across a library call, it must be saved: +.P +.in +4n +.EX +if (somecall() == \-1) { + int errsv = errno; + printf("somecall() failed\en"); + if (errsv == ...) { ... } +} +.EE +.in +.P +Note that the POSIX threads APIs do +.I not +set +.I errno +on error. +Instead, on failure they return an error number as the function result. +These error numbers have the same meanings as the error numbers returned in +.I errno +by other APIs. +.P +On some ancient systems, +.I <errno.h> +was not present or did not declare +.IR errno , +so that it was necessary to declare +.I errno +manually +(i.e., +.IR "extern int errno" ). +.BR "Do not do this" . +It long ago ceased to be necessary, +and it will cause problems with modern versions of the C library. +.SH SEE ALSO +.BR errno (1), \" In the moreutils package +.BR err (3), +.BR error (3), +.BR perror (3), +.BR strerror (3) diff --git a/man/man3/error.3 b/man/man3/error.3 new file mode 100644 index 0000000..f341c86 --- /dev/null +++ b/man/man3/error.3 @@ -0,0 +1,171 @@ +'\" t +.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH error 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +error, error_at_line, error_message_count, error_one_per_line, +error_print_progname \- glibc error reporting functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <error.h> +.P +.BI "void error(int " status ", int " errnum ", const char *" format ", ...);" +.BI "void error_at_line(int " status ", int " errnum ", const char *" filename , +.BI " unsigned int " linenum ", const char *" format ", ...);" +.P +.BI "extern unsigned int " error_message_count ; +.BI "extern int " error_one_per_line ; +.P +.BI "extern void (*" error_print_progname ")(void);" +.fi +.SH DESCRIPTION +.BR error () +is a general error-reporting function. +It flushes +.IR stdout , +and then outputs to +.I stderr +the program name, a colon and a space, the message specified by the +.BR printf (3)-style +format string \fIformat\fP, and, if \fIerrnum\fP is +nonzero, a second colon and a space followed by the string given by +.IR strerror(errnum) . +Any arguments required for +.I format +should follow +.I format +in the argument list. +The output is terminated by a newline character. +.P +The program name printed by +.BR error () +is the value of the global variable +.BR program_invocation_name (3). +.I program_invocation_name +initially has the same value as +.IR main ()'s +.IR argv[0] . +The value of this variable can be modified to change the output of +.BR error (). +.P +If \fIstatus\fP has a nonzero value, then +.BR error () +calls +.BR exit (3) +to terminate the program using the given value as the exit status; +otherwise it returns after printing the error message. +.P +The +.BR error_at_line () +function is exactly the same as +.BR error (), +except for the addition of the arguments +.I filename +and +.IR linenum . +The output produced is as for +.BR error (), +except that after the program name are written: a colon, the value of +.IR filename , +a colon, and the value of +.IR linenum . +The preprocessor values \fB__LINE__\fP and +\fB__FILE__\fP may be useful when calling +.BR error_at_line (), +but other values can also be used. +For example, these arguments could refer to a location in an input file. +.P +If the global variable \fIerror_one_per_line\fP is set nonzero, +a sequence of +.BR error_at_line () +calls with the +same value of \fIfilename\fP and \fIlinenum\fP will result in only +one message (the first) being output. +.P +The global variable \fIerror_message_count\fP counts the number of +messages that have been output by +.BR error () +and +.BR error_at_line (). +.P +If the global variable \fIerror_print_progname\fP +is assigned the address of a function +(i.e., is not NULL), then that function is called +instead of prefixing the message with the program name and colon. +The function should print a suitable string to +.IR stderr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR error () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR error_at_line () +T} Thread safety T{ +.na +.nh +MT-Unsafe\ race: error_at_line/\:error_one_per_line locale +T} +.TE +.P +The internal +.I error_one_per_line +variable is accessed (without any form of synchronization, but since it's an +.I int +used once, it should be safe enough) and, if +.I error_one_per_line +is set nonzero, the internal static variables (not exposed to users) +used to hold the last printed filename and line number are accessed +and modified without synchronization; the update is not atomic and it +occurs before disabling cancelation, so it can be interrupted only after +one of the two variables is modified. +After that, +.BR error_at_line () +is very much like +.BR error (). +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR exit (3), +.BR perror (3), +.BR program_invocation_name (3), +.BR strerror (3) diff --git a/man/man3/error_at_line.3 b/man/man3/error_at_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_at_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_message_count.3 b/man/man3/error_message_count.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_message_count.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_one_per_line.3 b/man/man3/error_one_per_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_one_per_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_print_progname.3 b/man/man3/error_print_progname.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_print_progname.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/errx.3 b/man/man3/errx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/errx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/etext.3 b/man/man3/etext.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man/man3/etext.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man/man3/ether_aton.3 b/man/man3/ether_aton.3 new file mode 100644 index 0000000..dbc6c2f --- /dev/null +++ b/man/man3/ether_aton.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright 2002 Ian Redfern (redferni@logica.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" FreeBSD 4.4 man pages +.\" +.\" Minor additions, aeb, 2013-06-21 +.\" +.TH ether_aton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, +ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netinet/ether.h> +.P +.BI "char *ether_ntoa(const struct ether_addr *" addr ); +.BI "struct ether_addr *ether_aton(const char *" asc ); +.P +.BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr ); +.BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr ); +.P +.BI "int ether_line(const char *" line ", struct ether_addr *" addr , +.BI " char *" hostname ); +.P +/* GNU extensions */ +.BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); +.P +.BI "struct ether_addr *ether_aton_r(const char *" asc , +.BI " struct ether_addr *" addr ); +.fi +.SH DESCRIPTION +.BR ether_aton () +converts the 48-bit Ethernet host address +.I asc +from the standard hex-digits-and-colons notation into binary data in +network byte order and returns a pointer to it in a statically +allocated buffer, which subsequent calls will +overwrite. +.BR ether_aton () +returns NULL if the address is invalid. +.P +The +.BR ether_ntoa () +function converts the Ethernet host address +.I addr +given in network byte order to a string in standard +hex-digits-and-colons notation, omitting leading zeros. +The string is returned in a statically allocated buffer, +which subsequent calls will overwrite. +.P +The +.BR ether_ntohost () +function maps an Ethernet address to the +corresponding hostname in +.I /etc/ethers +and returns nonzero if it cannot be found. +.P +The +.BR ether_hostton () +function maps a hostname to the +corresponding Ethernet address in +.I /etc/ethers +and returns nonzero if it cannot be found. +.P +The +.BR ether_line () +function parses a line in +.I /etc/ethers +format (ethernet address followed by whitespace followed by +hostname; \[aq]#\[aq] introduces a comment) and returns an address +and hostname pair, or nonzero if it cannot be parsed. +The buffer pointed to by +.I hostname +must be sufficiently long, for example, have the same length as +.IR line . +.P +The functions +.BR ether_ntoa_r () +and +.BR ether_aton_r () +are reentrant +thread-safe versions of +.BR ether_ntoa () +and +.BR ether_aton () +respectively, and do not use static buffers. +.P +The structure +.I ether_addr +is defined in +.I <net/ethernet.h> +as: +.P +.in +4n +.EX +struct ether_addr { + uint8_t ether_addr_octet[6]; +} +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ether_aton (), +.BR ether_ntoa () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR ether_ntohost (), +.BR ether_hostton (), +.BR ether_line (), +.BR ether_ntoa_r (), +.BR ether_aton_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, SunOS. +.SH BUGS +In glibc 2.2.5 and earlier, the implementation of +.BR ether_line () +.\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7 +.\" which was in glibc 2.3 +is broken. +.SH SEE ALSO +.BR ethers (5) diff --git a/man/man3/ether_aton_r.3 b/man/man3/ether_aton_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_aton_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_hostton.3 b/man/man3/ether_hostton.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_hostton.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_line.3 b/man/man3/ether_line.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_line.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntoa.3 b/man/man3/ether_ntoa.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntoa.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntoa_r.3 b/man/man3/ether_ntoa_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntoa_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntohost.3 b/man/man3/ether_ntohost.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntohost.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/euidaccess.3 b/man/man3/euidaccess.3 new file mode 100644 index 0000000..7a896a1 --- /dev/null +++ b/man/man3/euidaccess.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH euidaccess 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +euidaccess, eaccess \- check effective user's permissions for a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <unistd.h> +.P +.BI "int euidaccess(const char *" pathname ", int " mode ); +.BI "int eaccess(const char *" pathname ", int " mode ); +.fi +.SH DESCRIPTION +Like +.BR access (2), +.BR euidaccess () +checks permissions and existence of the file identified by its argument +.IR pathname . +However, whereas +.BR access (2) +performs checks using the real user and group identifiers of the process, +.BR euidaccess () +uses the effective identifiers. +.P +.I mode +is a mask consisting of one or more of +.BR R_OK ", " W_OK ", " X_OK ", and " F_OK , +with the same meanings as for +.BR access (2). +.P +.BR eaccess () +is a synonym for +.BR euidaccess (), +provided for compatibility with some other systems. +.SH RETURN VALUE +On success (all requested permissions granted), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or some other error occurred), +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +As for +.BR access (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR euidaccess (), +.BR eaccess () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Some other systems have an +.\" e.g., FreeBSD 6.1. +.BR eaccess () +function. +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR eaccess () +glibc 2.4. +.SH NOTES +.IR Warning : +Using this function to check a process's permissions on a file before +performing some operation based on that information leads to race conditions: +the file permissions may change between the two steps. +Generally, it is safer just to attempt the desired operation and handle +any permission error that occurs. +.P +This function always dereferences symbolic links. +If you need to check the permissions on a symbolic link, use +.BR faccessat (2) +with the flags +.B AT_EACCESS +and +.BR AT_SYMLINK_NOFOLLOW . +.SH SEE ALSO +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR faccessat (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR credentials (7), +.BR path_resolution (7) diff --git a/man/man3/eventfd_read.3 b/man/man3/eventfd_read.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man/man3/eventfd_read.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man/man3/eventfd_write.3 b/man/man3/eventfd_write.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man/man3/eventfd_write.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man/man3/exec.3 b/man/man3/exec.3 new file mode 100644 index 0000000..a94a2f1 --- /dev/null +++ b/man/man3/exec.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added note on casting NULL +.\" +.TH exec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +execl, execlp, execle, execv, execvp, execvpe \- execute a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B extern char **environ; +.P +.BI "int execl(const char *" pathname ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execlp(const char *" file ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execle(const char *" pathname ", const char *" arg ", ..." +.BI " /*, (char *) NULL, char *const " envp "[] */);" +.BI "int execv(const char *" pathname ", char *const " argv "[]);" +.BI "int execvp(const char *" file ", char *const " argv "[]);" +.BI "int execvpe(const char *" file ", char *const " argv \ +"[], char *const " envp "[]);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR execvpe (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR exec () +family of functions replaces the current process image with a new process +image. +The functions described in this manual page are layered on top of +.BR execve (2). +(See the manual page for +.BR execve (2) +for further details about the replacement of the current process image.) +.P +The initial argument for these functions is the name of a file that is +to be executed. +.P +The functions can be grouped based on the letters following the "exec" prefix. +.\" +.SS l - execl(), execlp(), execle() +The +.I "const char\ *arg" +and subsequent ellipses can be thought of as +.IR arg0 , +.IR arg1 , +\&..., +.IR argn . +Together they describe a list of one or more pointers to null-terminated +strings that represent the argument list available to the executed program. +The first argument, by convention, should point to the filename associated +with the file being executed. +The list of arguments +.I must +be terminated by a null pointer, +and, since these are variadic functions, this pointer must be cast +.IR "(char\ *) NULL" . +.P +By contrast with the 'l' functions, the 'v' functions (below) specify the +command-line arguments of the executed program as a vector. +.\" +.SS v - execv(), execvp(), execvpe() +The +.I "char\ *const argv[]" +argument is an array of pointers to null-terminated strings that +represent the argument list available to the new program. +The first argument, by convention, should point to the filename +associated with the file being executed. +The array of pointers +.I must +be terminated by a null pointer. +.SS e - execle(), execvpe() +The environment of the new process image is specified via the argument +.IR envp . +The +.I envp +argument is an array of pointers to null-terminated strings and +.I must +be terminated by a null pointer. +.P +All other +.BR exec () +functions (which do not include 'e' in the suffix) +take the environment for the new process +image from the external variable +.I environ +in the calling process. +.SS p - execlp(), execvp(), execvpe() +These functions duplicate the actions of the shell in +searching for an executable file +if the specified filename does not contain a slash (/) character. +The file is sought in the colon-separated list of directory pathnames +specified in the +.B PATH +environment variable. +If this variable isn't defined, the path list defaults to +a list that includes the directories returned by +.I confstr(_CS_PATH) +(which typically returns the value "/bin:/usr/bin") +and possibly also the current working directory; +see NOTES for further details. +.P +.BR execvpe () +searches for the program using the value of +.B PATH +from the caller's environment, not from the +.I envp +argument. +.P +If the specified filename includes a slash character, then +.B PATH +is ignored, and the file at the specified pathname is executed. +.P +In addition, certain errors are treated specially. +.P +If permission is denied for a file (the attempted +.BR execve (2) +failed with the error +.BR EACCES ), +these functions will continue searching the rest of the search path. +If no other file is found, however, +they will return with +.I errno +set to +.BR EACCES . +.P +If the header of a file isn't recognized (the attempted +.BR execve (2) +failed with the error +.BR ENOEXEC ), +these functions will execute the shell +.RI ( /bin/sh ) +with the path of the file as its first argument. +(If this attempt fails, no further searching is done.) +.P +All other +.BR exec () +functions (which do not include 'p' in the suffix) +take as their first argument a (relative or absolute) pathname +that identifies the program to be executed. +.SH RETURN VALUE +The +.BR exec () +functions return only if an error has occurred. +The return value is \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +All of these functions may fail and set +.I errno +for any of the errors specified for +.BR execve (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR execl (), +.BR execle (), +.BR execv () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR execlp (), +.BR execvp (), +.BR execvpe () +T} Thread safety MT-Safe env +.TE +.SH VERSIONS +The default search path (used when the environment +does not contain the variable \fBPATH\fR) +shows some variation across systems. +It generally includes +.I /bin +and +.I /usr/bin +(in that order) and may also include the current working directory. +On some other systems, the current working is included after +.I /bin +and +.IR /usr/bin , +as an anti-Trojan-horse measure. +The glibc implementation long followed the traditional default where +the current working directory is included at the start of the search path. +However, some code refactoring during the development of glibc 2.24 +.\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83 +caused the current working directory to be dropped altogether +from the default search path. +This accidental behavior change is considered mildly beneficial, +and won't be reverted. +.P +The behavior of +.BR execlp () +and +.BR execvp () +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified by +the POSIX standard. +BSD (and possibly other systems) do an automatic +sleep and retry if +.B ETXTBSY +is encountered. +Linux treats it as a hard +error and returns immediately. +.P +Traditionally, the functions +.BR execlp () +and +.BR execvp () +ignored all errors except for the ones described above and +.B ENOMEM +and +.BR E2BIG , +upon which they returned. +They now return if any error other than the ones +described above occurs. +.SH STANDARDS +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2008. +.TP +.BR execvpe () +GNU. +.SH HISTORY +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2001. +.TP +.BR execvpe () +glibc 2.11. +.SH BUGS +Before glibc 2.24, +.BR execl () +and +.BR execle () +employed +.BR realloc (3) +internally and were consequently not async-signal-safe, +in violation of the requirements of POSIX.1. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.\" +.SS Architecture-specific details +On sparc and sparc64, +.BR execv () +is provided as a system call by the kernel +(with the prototype shown above) +for compatibility with SunOS. +This function is +.I not +employed by the +.BR execv () +wrapper function on those architectures. +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR execveat (2), +.BR fork (2), +.BR ptrace (2), +.BR fexecve (3), +.BR system (3), +.BR environ (7) diff --git a/man/man3/execl.3 b/man/man3/execl.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execl.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execle.3 b/man/man3/execle.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execle.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execlp.3 b/man/man3/execlp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execlp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execv.3 b/man/man3/execv.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execv.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execvp.3 b/man/man3/execvp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execvp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execvpe.3 b/man/man3/execvpe.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execvpe.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/exit.3 b/man/man3/exit.3 new file mode 100644 index 0000000..4fa48e0 --- /dev/null +++ b/man/man3/exit.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" FIXME . There are a lot of other process termination actions that +.\" could be listed on this page. See, for example, the list in the +.\" POSIX exit(3p) page. +.\" +.TH exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exit \- cause normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "[[noreturn]] void exit(int " status ); +.fi +.SH DESCRIPTION +The +.BR exit () +function causes normal process termination and the least significant byte of +.I status +(i.e., \fIstatus & 0xFF\fP) is returned to the parent (see +.BR wait (2)). +.P +All functions registered with +.BR atexit (3) +and +.BR on_exit (3) +are called, in the reverse order of their registration. +(It is possible for one of these functions to use +.BR atexit (3) +or +.BR on_exit (3) +to register an additional +function to be executed during exit processing; +the new registration is added to the front of the list of functions +that remain to be called.) +If one of these functions does not return +(e.g., it calls +.BR _exit (2), +or kills itself with a signal), +then none of the remaining functions is called, +and further exit processing (in particular, flushing of +.BR stdio (3) +streams) is abandoned. +If a function has been registered multiple times using +.BR atexit (3) +or +.BR on_exit (3), +then it is called as many times as it was registered. +.P +All open +.BR stdio (3) +streams are flushed and closed. +Files created by +.BR tmpfile (3) +are removed. +.P +The C standard specifies two constants, +\fBEXIT_SUCCESS\fP and \fBEXIT_FAILURE\fP, +that may be passed to +.BR exit () +to indicate successful or unsuccessful +termination, respectively. +.SH RETURN VALUE +The +.BR exit () +function does not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exit () +T} Thread safety MT-Unsafe race:exit +.TE +.P +The +.BR exit () +function uses a global variable that is not protected, +so it is not thread-safe. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +The behavior is undefined if one of the functions registered using +.BR atexit (3) +and +.BR on_exit (3) +calls either +.BR exit () +or +.BR longjmp (3). +Note that a call to +.BR execve (2) +removes registrations created using +.BR atexit (3) +and +.BR on_exit (3). +.P +The use of +.B EXIT_SUCCESS +and +.B EXIT_FAILURE +is slightly more portable +(to non-UNIX environments) than the use of 0 and some nonzero value +like 1 or \-1. +In particular, VMS uses a different convention. +.P +BSD has attempted to standardize exit codes +(which some C libraries such as the GNU C library have also adopted); +see the file +.IR <sysexits.h> . +.P +After +.BR exit (), +the exit status must be transmitted to the +parent process. +There are three cases: +.IP \[bu] 3 +If the parent has set +.BR SA_NOCLDWAIT , +or has set the +.B SIGCHLD +handler to +.BR SIG_IGN , +the status is discarded and the child dies immediately. +.IP \[bu] +If the parent was waiting on the child, +it is notified of the exit status and the child dies immediately. +.IP \[bu] +Otherwise, +the child becomes a "zombie" process: +most of the process resources are recycled, +but a slot containing minimal information about the child process +(termination status, resource usage statistics) is retained in process table. +This allows the parent to subsequently use +.BR waitpid (2) +(or similar) to learn the termination status of the child; +at that point the zombie process slot is released. +.P +If the implementation supports the +.B SIGCHLD +signal, this signal +is sent to the parent. +If the parent has set +.BR SA_NOCLDWAIT , +it is undefined whether a +.B SIGCHLD +signal is sent. +.\" +.SS Signals sent to other processes +If the exiting process is a session leader and its controlling terminal +is the controlling terminal of the session, then each process in +the foreground process group of this controlling terminal +is sent a +.B SIGHUP +signal, and the terminal is disassociated +from this session, allowing it to be acquired by a new controlling +process. +.P +If the exit of the process causes a process group to become orphaned, +and if any member of the newly orphaned process group is stopped, +then a +.B SIGHUP +signal followed by a +.B SIGCONT +signal will be +sent to each process in this process group. +See +.BR setpgid (2) +for an explanation of orphaned process groups. +.P +Except in the above cases, +where the signalled processes may be children of the terminating process, +termination of a process does +.I not +in general cause a signal to be sent to children of that process. +However, a process can use the +.BR prctl (2) +.B PR_SET_PDEATHSIG +operation to arrange that it receives a signal if its parent terminates. +.SH SEE ALSO +.BR _exit (2), +.BR get_robust_list (2), +.BR setpgid (2), +.BR wait (2), +.BR atexit (3), +.BR on_exit (3), +.BR tmpfile (3) diff --git a/man/man3/exp.3 b/man/man3/exp.3 new file mode 100644 index 0000000..85a3f8f --- /dev/null +++ b/man/man3/exp.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH exp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp, expf, expl \- base-e exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double exp(double " x ); +.BI "float expf(float " x ); +.BI "long double expl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR expf (), +.BR expl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the value of e (the base of natural +logarithms) raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the exponential value of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity, +positive infinity is returned. +.P +If +.I x +is negative infinity, ++0 is returned. +.P +If the result underflows, +a range error occurs, +and zero is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp (), +.BR expf (), +.BR expl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp (3), +.BR exp10 (3), +.BR exp2 (3), +.BR expm1 (3), +.BR sqrt (3) diff --git a/man/man3/exp10.3 b/man/man3/exp10.3 new file mode 100644 index 0000000..69b6094 --- /dev/null +++ b/man/man3/exp10.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH exp10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp10, exp10f, exp10l \- base-10 exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <math.h> +.P +.BI "double exp10(double " x ); +.BI "float exp10f(float " x ); +.BI "long double exp10l(long double " x ); +.fi +.SH DESCRIPTION +These functions return the value of 10 +raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-10 exponential value of +.IR x . +.P +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp10 (), +.BR exp10f (), +.BR exp10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH BUGS +Before glibc 2.19, the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +when an underflow error occurred. +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6787 +.SH SEE ALSO +.BR cbrt (3), +.BR exp (3), +.BR exp2 (3), +.BR log10 (3), +.BR sqrt (3) diff --git a/man/man3/exp10f.3 b/man/man3/exp10f.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man/man3/exp10f.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man/man3/exp10l.3 b/man/man3/exp10l.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man/man3/exp10l.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man/man3/exp2.3 b/man/man3/exp2.3 new file mode 100644 index 0000000..728deb0 --- /dev/null +++ b/man/man3/exp2.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH exp2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp2, exp2f, exp2l \- base-2 exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double exp2(double " x ); +.BI "float exp2f(float " x ); +.BI "long double exp2l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR exp2 (), +.BR exp2f (), +.BR exp2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the value of 2 raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-2 exponential value of +.IR x . +.P +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp2 (), +.BR exp2f (), +.BR exp2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp2 (3), +.BR exp (3), +.BR exp10 (3), +.BR sqrt (3) diff --git a/man/man3/exp2f.3 b/man/man3/exp2f.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man/man3/exp2f.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man/man3/exp2l.3 b/man/man3/exp2l.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man/man3/exp2l.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man/man3/expf.3 b/man/man3/expf.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man/man3/expf.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man/man3/expl.3 b/man/man3/expl.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man/man3/expl.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man/man3/explicit_bzero.3 b/man/man3/explicit_bzero.3 new file mode 100644 index 0000000..8a43e76 --- /dev/null +++ b/man/man3/explicit_bzero.3 @@ -0,0 +1 @@ +.so man3/bzero.3 diff --git a/man/man3/expm1.3 b/man/man3/expm1.3 new file mode 100644 index 0000000..0bdfc6b --- /dev/null +++ b/man/man3/expm1.3 @@ -0,0 +1,165 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com> +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH expm1 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +expm1, expm1f, expm1l \- exponential minus 1 +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double expm1(double " x ); +.BI "float expm1f(float " x ); +.BI "long double expm1l(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR expm1 (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR expm1f (), +.BR expm1l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value equivalent to +.P +.nf + exp(x) \- 1 +.fi +.P +The result is computed in a way that is accurate even if the value of +.I x +is near +zero\[em]a case where +.I "exp(x) \- 1" +would be inaccurate due to +subtraction of two numbers that are nearly equal. +.SH RETURN VALUE +On success, these functions return +.IR "exp(x)\ \-\ 1" . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is negative infinity, \-1 is returned. +.P +If the result overflows, a range error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.B ERANGE +(but see BUGS). +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" +.\" POSIX.1 specifies an optional range error (underflow) if +.\" x is subnormal. glibc does not implement this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR expm1 (), +.BR expm1f (), +.BR expm1l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +BSD. +.SH BUGS +Before glibc 2.17, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6778 +on certain architectures (e.g., x86, but not x86_64) +.BR expm1 () +raised a bogus underflow floating-point exception +for some large negative +.I x +values (where the function result approaches \-1). +.P +Before approximately glibc 2.11, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6814 +.\" e.g., expm1(1e5) through expm1(1.00199970127e5), +.\" but not expm1(1.00199970128e5) and beyond. +.BR expm1 () +raised a bogus invalid floating-point exception in addition to the expected +overflow exception, and returned a NaN instead of positive infinity, +for some large positive +.I x +values. +.P +Before glibc 2.11, +.\" It looks like the fix was in glibc 2.11, or possibly glibc 2.12. +.\" I have no test system for glibc 2.11, but glibc 2.12 passes. +.\" From the source (sysdeps/i386/fpu/s_expm1.S) it looks +.\" like the changes were in glibc 2.11. +the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6788 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR log (3), +.BR log1p (3) diff --git a/man/man3/expm1f.3 b/man/man3/expm1f.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man/man3/expm1f.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man/man3/expm1l.3 b/man/man3/expm1l.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man/man3/expm1l.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man/man3/fabs.3 b/man/man3/fabs.3 new file mode 100644 index 0000000..6e6ed08 --- /dev/null +++ b/man/man3/fabs.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added fabsl, fabsf, aeb, 2001-06-07 +.\" +.TH fabs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fabs, fabsf, fabsl \- absolute value of floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fabs(double " x ); +.BI "float fabsf(float " x ); +.BI "long double fabsl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fabsf (), +.BR fabsl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the absolute value of the floating-point +number +.IR x . +.SH RETURN VALUE +These functions return the absolute value of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is \-0, +0 is returned. +.P +If +.I x +is negative infinity or positive infinity, positive infinity is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fabs (), +.BR fabsf (), +.BR fabsl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR abs (3), +.BR cabs (3), +.BR ceil (3), +.BR floor (3), +.BR labs (3), +.BR rint (3) diff --git a/man/man3/fabsf.3 b/man/man3/fabsf.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man/man3/fabsf.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man/man3/fabsl.3 b/man/man3/fabsl.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man/man3/fabsl.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man/man3/fclose.3 b/man/man3/fclose.3 new file mode 100644 index 0000000..a39aaa8 --- /dev/null +++ b/man/man3/fclose.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fclose.3 6.7 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:19:14 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org> +.\" +.TH fclose 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fclose \- close a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fclose(FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fclose () +function flushes the stream pointed to by +.I stream +(writing any buffered output data using +.BR fflush (3)) +and closes the underlying file descriptor. +.SH RETURN VALUE +Upon successful completion, 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +In either case, any further access +(including another call to +.BR fclose ()) +to the stream results in undefined behavior. +.SH ERRORS +.TP +.B EBADF +The file descriptor underlying +.I stream +is not valid. +.\" This error cannot occur unless you are mixing ANSI C stdio operations and +.\" low-level file operations on the same stream. If you do get this error, +.\" you must have closed the stream's low-level file descriptor using +.\" something like close(fileno(stream)). +.P +The +.BR fclose () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR close (2), +.BR write (2), +or +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fclose () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +Note that +.BR fclose () +flushes only the user-space buffers provided by the +C library. +To ensure that the data is physically stored +on disk the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR close (2), +.BR fcloseall (3), +.BR fflush (3), +.BR fileno (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/fcloseall.3 b/man/man3/fcloseall.3 new file mode 100644 index 0000000..b7ed34b --- /dev/null +++ b/man/man3/fcloseall.3 @@ -0,0 +1,64 @@ +'\" t +.\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fcloseall 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fcloseall \- close all open streams +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <stdio.h> +.P +.B int fcloseall(void); +.fi +.SH DESCRIPTION +The +.BR fcloseall () +function closes all of the calling process's open streams. +Buffered output for each stream is written before it is closed +(as for +.BR fflush (3)); +buffered input is discarded. +.P +The standard streams, +.IR stdin , +.IR stdout , +and +.I stderr +are also closed. +.SH RETURN VALUE +This function returns 0 if all files were successfully closed; +on error, +.B EOF +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fcloseall () +T} Thread safety MT-Unsafe race:streams +.TE +.P +The +.BR fcloseall () +function does not lock the streams, so it is not thread-safe. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR close (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/fcvt.3 b/man/man3/fcvt.3 new file mode 100644 index 0000000..39d3770 --- /dev/null +++ b/man/man3/fcvt.3 @@ -0,0 +1 @@ +.so man3/ecvt.3 diff --git a/man/man3/fcvt_r.3 b/man/man3/fcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/fcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/fdim.3 b/man/man3/fdim.3 new file mode 100644 index 0000000..271d853 --- /dev/null +++ b/man/man3/fdim.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 2003 Walter Harms, Andries Brouwer +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fdim 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fdim, fdimf, fdiml \- positive difference +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fdim(double " x ", double " y ); +.BI "float fdimf(float " x ", float " y ); +.BI "long double fdiml(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdimf (), +.BR fdiml (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the positive difference, max(\fIx\fP-\fIy\fP,0), +between their arguments. +.SH RETURN VALUE +On success, these functions return the positive difference. +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fdim (), +.BR fdimf (), +.BR fdiml () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH BUGS +Before glibc 2.24 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6796 +on certain architectures (e.g., x86, but not x86_64) +these functions did not set +.IR errno . +.SH SEE ALSO +.BR fmax (3) diff --git a/man/man3/fdimf.3 b/man/man3/fdimf.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man/man3/fdimf.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man/man3/fdiml.3 b/man/man3/fdiml.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man/man3/fdiml.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man/man3/fdopen.3 b/man/man3/fdopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man/man3/fdopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man/man3/fdopendir.3 b/man/man3/fdopendir.3 new file mode 100644 index 0000000..55b720e --- /dev/null +++ b/man/man3/fdopendir.3 @@ -0,0 +1 @@ +.so man3/opendir.3 diff --git a/man/man3/feclearexcept.3 b/man/man3/feclearexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feclearexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fedisableexcept.3 b/man/man3/fedisableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fedisableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feenableexcept.3 b/man/man3/feenableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feenableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetenv.3 b/man/man3/fegetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetexcept.3 b/man/man3/fegetexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetexceptflag.3 b/man/man3/fegetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetround.3 b/man/man3/fegetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feholdexcept.3 b/man/man3/feholdexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feholdexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fenv.3 b/man/man3/fenv.3 new file mode 100644 index 0000000..04f3dca --- /dev/null +++ b/man/man3/fenv.3 @@ -0,0 +1,334 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2000-08-14 added GNU additions from Andreas Jaeger +.\" 2000-12-05 some changes inspired by acahalan's remarks +.\" +.TH fenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, +fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, +fesetenv, feupdateenv, feenableexcept, fedisableexcept, +fegetexcept \- floating-point rounding and exception handling +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <fenv.h> +.P +.BI "int feclearexcept(int " excepts ); +.BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts ); +.BI "int feraiseexcept(int " excepts ); +.BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts ); +.BI "int fetestexcept(int " excepts ); +.P +.B "int fegetround(void);" +.BI "int fesetround(int " rounding_mode ); +.P +.BI "int fegetenv(fenv_t *" envp ); +.BI "int feholdexcept(fenv_t *" envp ); +.BI "int fesetenv(const fenv_t *" envp ); +.BI "int feupdateenv(const fenv_t *" envp ); +.fi +.SH DESCRIPTION +These eleven functions were defined in C99, and describe the handling +of floating-point rounding and exceptions (overflow, zero-divide, etc.). +.SS Exceptions +The +.I divide-by-zero +exception occurs when an operation on finite numbers +produces infinity as exact answer. +.P +The +.I overflow +exception occurs when a result has to be represented as a +floating-point number, but has (much) larger absolute value than the +largest (finite) floating-point number that is representable. +.P +The +.I underflow +exception occurs when a result has to be represented as a +floating-point number, but has smaller absolute value than the smallest +positive normalized floating-point number (and would lose much accuracy +when represented as a denormalized number). +.P +The +.I inexact +exception occurs when the rounded result of an operation +is not equal to the infinite precision result. +It may occur whenever +.I overflow +or +.I underflow +occurs. +.P +The +.I invalid +exception occurs when there is no well-defined result +for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1). +.SS Exception handling +Exceptions are represented in two ways: as a single bit +(exception present/absent), and these bits correspond in some +implementation-defined way with bit positions in an integer, +and also as an opaque structure that may contain more information +about the exception (perhaps the code address where it occurred). +.P +Each of the macros +.BR FE_DIVBYZERO , +.BR FE_INEXACT , +.BR FE_INVALID , +.BR FE_OVERFLOW , +.B FE_UNDERFLOW +is defined when the implementation supports handling +of the corresponding exception, and if so then +defines the corresponding bit(s), so that one can call +exception handling functions, for example, using the integer argument +.BR FE_OVERFLOW | FE_UNDERFLOW . +Other exceptions may be supported. +The macro +.B FE_ALL_EXCEPT +is the bitwise OR of all bits corresponding to supported exceptions. +.P +The +.BR feclearexcept () +function clears the supported exceptions represented by the bits +in its argument. +.P +The +.BR fegetexceptflag () +function stores a representation of the state of the exception flags +represented by the argument +.I excepts +in the opaque object +.IR *flagp . +.P +The +.BR feraiseexcept () +function raises the supported exceptions represented by the bits in +.IR excepts . +.P +The +.BR fesetexceptflag () +function sets the complete status for the exceptions represented by +.I excepts +to the value +.IR *flagp . +This value must have been obtained by an earlier call of +.BR fegetexceptflag () +with a last argument that contained all bits in +.IR excepts . +.P +The +.BR fetestexcept () +function returns a word in which the bits are set that were +set in the argument +.I excepts +and for which the corresponding exception is currently set. +.SS Rounding mode +The rounding mode determines how the result of floating-point operations +is treated when the result cannot be exactly represented in the significand. +Various rounding modes may be provided: +round to nearest (the default), +round up (toward positive infinity), +round down (toward negative infinity), and +round toward zero. +.P +Each of the macros +.BR FE_TONEAREST , +.BR FE_UPWARD , +.BR FE_DOWNWARD , +and +.B FE_TOWARDZERO +is defined when the implementation supports getting and setting +the corresponding rounding direction. +.P +The +.BR fegetround () +function returns the macro corresponding to the current +rounding mode. +.P +The +.BR fesetround () +function sets the rounding mode as specified by its argument +and returns zero when it was successful. +.P +C99 and POSIX.1-2008 specify an identifier, +.BR FLT_ROUNDS , +defined in +.IR <float.h> , +which indicates the implementation-defined rounding +behavior for floating-point addition. +This identifier has one of the following values: +.TP +.B \-1 +The rounding mode is not determinable. +.TP +.B 0 +Rounding is toward 0. +.TP +.B 1 +Rounding is toward nearest number. +.TP +.B 2 +Rounding is toward positive infinity. +.TP +.B 3 +Rounding is toward negative infinity. +.P +Other values represent machine-dependent, nonstandard rounding modes. +.P +The value of +.B FLT_ROUNDS +should reflect the current rounding mode as set by +.BR fesetround () +(but see BUGS). +.SS Floating-point environment +The entire floating-point environment, including +control modes and status flags, can be handled +as one opaque object, of type +.IR fenv_t . +The default environment is denoted by +.B FE_DFL_ENV +(of type +.IR "const fenv_t\ *" ). +This is the environment setup at program start and it is defined by +ISO C to have round to nearest, all exceptions cleared and a nonstop +(continue on exceptions) mode. +.P +The +.BR fegetenv () +function saves the current floating-point environment in the object +.IR *envp . +.P +The +.BR feholdexcept () +function does the same, then clears all exception flags, +and sets a nonstop (continue on exceptions) mode, +if available. +It returns zero when successful. +.P +The +.BR fesetenv () +function restores the floating-point environment from +the object +.IR *envp . +This object must be known to be valid, for example, the result of a call to +.BR fegetenv () +or +.BR feholdexcept () +or equal to +.BR FE_DFL_ENV . +This call does not raise exceptions. +.P +The +.BR feupdateenv () +function installs the floating-point environment represented by +the object +.IR *envp , +except that currently raised exceptions are not cleared. +After calling this function, the raised exceptions will be a bitwise OR +of those previously set with those in +.IR *envp . +As before, the object +.I *envp +must be known to be valid. +.SH RETURN VALUE +These functions return zero on success and nonzero if an error occurred. +.\" Earlier seven of these functions were listed as returning void. +.\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E)) +.\" of the C99 Standard. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.nh +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR feclearexcept (), +.BR fegetexceptflag (), +.BR feraiseexcept (), +.BR fesetexceptflag (), +.BR fetestexcept (), +.BR fegetround (), +.BR fesetround (), +.BR fegetenv (), +.BR feholdexcept (), +.BR fesetenv (), +.BR feupdateenv (), +.BR feenableexcept (), +.BR fedisableexcept (), +.BR fegetexcept () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.hy +.SH STANDARDS +C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854. +.SH HISTORY +C99, POSIX.1-2001. +glibc 2.1. +.SH NOTES +.SS glibc notes +If possible, the GNU C Library defines a macro +.B FE_NOMASK_ENV +which represents an environment where every exception raised causes a +trap to occur. +You can test for this macro using +.BR #ifdef . +It is defined only if +.B _GNU_SOURCE +is defined. +The C99 standard does not define a way to set individual bits in the +floating-point mask, for example, to trap on specific flags. +Since glibc 2.2, glibc supports the functions +.BR feenableexcept () +and +.BR fedisableexcept () +to set individual floating-point traps, and +.BR fegetexcept () +to query the state. +.P +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include <fenv.h>" +.P +.BI "int feenableexcept(int " excepts ); +.BI "int fedisableexcept(int " excepts ); +.B "int fegetexcept(void);" +.fi +.P +The +.BR feenableexcept () +and +.BR fedisableexcept () +functions enable (disable) traps for each of the exceptions represented by +.I excepts +and return the previous set of enabled exceptions when successful, +and \-1 otherwise. +The +.BR fegetexcept () +function returns the set of all currently enabled exceptions. +.SH BUGS +C99 specifies that the value of +.B FLT_ROUNDS +should reflect changes to the current rounding mode, as set by +.BR fesetround (). +Currently, +.\" Aug 08, glibc 2.8 +this does not occur: +.B FLT_ROUNDS +always has the value 1. +.\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html +.SH SEE ALSO +.BR math_error (7) diff --git a/man/man3/feof.3 b/man/man3/feof.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man/man3/feof.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man/man3/feof_unlocked.3 b/man/man3/feof_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/feof_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/feraiseexcept.3 b/man/man3/feraiseexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feraiseexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/ferror.3 b/man/man3/ferror.3 new file mode 100644 index 0000000..cdfc3a7 --- /dev/null +++ b/man/man3/ferror.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (C) 2021 Michael Kerrisk <mtk.manpages@gmail.com> +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)ferror.3 6.8 (Berkeley) 6/29/91 +.\" +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" +.TH ferror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clearerr, feof, ferror \- check and reset stream status +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "void clearerr(FILE *" stream ); +.BI "int feof(FILE *" stream ); +.BI "int ferror(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR clearerr () +clears the end-of-file and error indicators for the stream pointed to by +.IR stream . +.P +The function +.BR feof () +tests the end-of-file indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The end-of-file indicator can be cleared only by the function +.BR clearerr (). +.P +The function +.BR ferror () +tests the error indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The error indicator can be reset only by the +.BR clearerr () +function. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR feof () +function returns nonzero if the end-of-file indicator is set for +.IR stream ; +otherwise, it returns zero. +.P +The +.BR ferror () +function returns nonzero if the error indicator is set for +.IR stream ; +otherwise, it returns zero. +.SH ERRORS +These functions should not fail and do not set +.IR errno . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clearerr (), +.BR feof (), +.BR ferror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +POSIX.1-2008 specifies +.\"https://www.austingroupbugs.net/view.php?id=401 +that these functions shall not change the value of +.I errno +if +.I stream +is valid. +.SH CAVEATS +Normally, +programs should read the return value of an input function, +such as +.BR fgetc (3), +before using functions of the +.BR feof (3) +family. +Only when the function returned the sentinel value +.B EOF +it makes sense to distinguish between the end of a file or an error with +.BR feof (3) +or +.BR ferror (3). +.SH SEE ALSO +.BR open (2), +.BR fdopen (3), +.BR fileno (3), +.BR stdio (3), +.BR unlocked_stdio (3) diff --git a/man/man3/ferror_unlocked.3 b/man/man3/ferror_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/ferror_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fesetenv.3 b/man/man3/fesetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fesetexceptflag.3 b/man/man3/fesetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fesetround.3 b/man/man3/fesetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fetestexcept.3 b/man/man3/fetestexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fetestexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feupdateenv.3 b/man/man3/feupdateenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feupdateenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fexecve.3 b/man/man3/fexecve.3 new file mode 100644 index 0000000..d040127 --- /dev/null +++ b/man/man3/fexecve.3 @@ -0,0 +1,172 @@ +'\" t +.\" Copyright (c) 2006, 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fexecve 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fexecve \- execute program specified via file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fexecve (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR fexecve () +performs the same task as +.BR execve (2), +with the difference that the file to be executed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +The file descriptor +.I fd +must be opened read-only +.RB ( O_RDONLY ) +or with the +.B O_PATH +flag +and the caller must have permission to execute the file that it refers to. +.SH RETURN VALUE +A successful call to +.BR fexecve () +never returns. +On error, the function does return, with a result value of \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR execve (2), +with the following additions: +.TP +.B EINVAL +.I fd +is not a valid file descriptor, or +.I argv +is NULL, or +.I envp +is NULL. +.TP +.B ENOENT +The close-on-exec flag is set on +.IR fd , +and +.I fd +refers to a script. +See BUGS. +.TP +.B ENOSYS +The kernel does not provide the +.BR execveat (2) +system call, and the +.I /proc +filesystem could not be accessed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fexecve () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3.2. +.P +On Linux with glibc versions 2.26 and earlier, +.BR fexecve () +is implemented using the +.BR proc (5) +filesystem, so +.I /proc +needs to be mounted and available at the time of the call. +Since glibc 2.27, +.\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60 +if the underlying kernel supports the +.BR execveat (2) +system call, then +.BR fexecve () +is implemented using that system call, with the benefit that +.I /proc +does not need to be mounted. +.SH NOTES +The idea behind +.BR fexecve () +is to allow the caller to verify (checksum) the contents of +an executable before executing it. +Simply opening the file, checksumming the contents, and then doing an +.BR execve (2) +would not suffice, since, between the two steps, the filename, +or a directory prefix of the pathname, could have been exchanged +(by, for example, modifying the target of a symbolic link). +.BR fexecve () +does not mitigate the problem that the +.I contents +of a file could be changed between the checksumming and the call to +.BR fexecve (); +for that, the solution is to ensure that the permissions on the file +prevent it from being modified by malicious users. +.P +The natural idiom when using +.BR fexecve () +is to set the close-on-exec flag on +.IR fd , +so that the file descriptor does not leak through to the program +that is executed. +This approach is natural for two reasons. +First, it prevents file descriptors being consumed unnecessarily. +(The executed program normally has no need of a file descriptor +that refers to the program itself.) +Second, if +.BR fexecve () +is used recursively, +employing the close-on-exec flag prevents the file descriptor exhaustion +that would result from the fact that each step in the recursion would +cause one more file descriptor to be passed to the new program. +(But see BUGS.) +.SH BUGS +If +.I fd +refers to a script (i.e., it is an executable text file that names +a script interpreter with a first line that begins with the characters +.IR #! ) +and the close-on-exec flag has been set for +.IR fd , +then +.BR fexecve () +fails with the error +.BR ENOENT . +This error occurs because, +by the time the script interpreter is executed, +.I fd +has already been closed because of the close-on-exec flag. +Thus, the close-on-exec flag can't be set on +.I fd +if it refers to a script, leading to the problems described in NOTES. +.SH SEE ALSO +.BR execve (2), +.BR execveat (2) diff --git a/man/man3/fflush.3 b/man/man3/fflush.3 new file mode 100644 index 0000000..5670ba4 --- /dev/null +++ b/man/man3/fflush.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fflush.3 5.4 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org> +.\" Modified 2001-10-16 by John Levon <moz@compsoc.man.ac.uk> +.\" +.TH fflush 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fflush \- flush a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fflush(FILE *_Nullable " stream ); +.fi +.SH DESCRIPTION +For output streams, +.BR fflush () +forces a write of all user-space buffered data for the given output or update +.I stream +via the stream's underlying write function. +.P +For input streams associated with seekable files +(e.g., disk files, but not pipes or terminals), +.BR fflush () +discards any buffered data that has been fetched from the underlying file, +but has not been consumed by the application. +.P +The open status of the stream is unaffected. +.P +If the +.I stream +argument is NULL, +.BR fflush () +flushes +.I all +open output streams. +.\" mtk: POSIX specifies that only output streams are flushed for this case. +.\" Also verified for glibc by experiment. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +Upon successful completion 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream, or is not open for writing. +.P +The function +.BR fflush () +may also fail and set +.I errno +for any of the errors specified for +.BR write (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fflush () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001, POSIX.1-2008. +.P +POSIX.1-2001 did not specify the behavior for flushing of input streams, +but the behavior is specified in POSIX.1-2008. +.SH NOTES +Note that +.BR fflush () +flushes only the user-space buffers provided by the C library. +To ensure that the data is physically stored on disk +the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR fsync (2), +.BR sync (2), +.BR write (2), +.BR fclose (3), +.BR fileno (3), +.BR fopen (3), +.BR fpurge (3), +.BR setbuf (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fflush_unlocked.3 b/man/man3/fflush_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fflush_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/ffs.3 b/man/man3/ffs.3 new file mode 100644 index 0000000..f3ce65e --- /dev/null +++ b/man/man3/ffs.3 @@ -0,0 +1,97 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:39:35 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ffs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ffs, ffsl, ffsll \- find first bit set in a word +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "int ffs(int " i ); +.BI "int ffsl(long " i ); +.BI "int ffsll(long long " i ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ffs (): +.nf + Since glibc 2.12: + _XOPEN_SOURCE >= 700 + || ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.12: + none +.fi +.P +.BR ffsl (), +.BR ffsll (): +.nf + Since glibc 2.27: +.\" glibc commit 68fe16dd327c895c08b9ee443b234c49c13b36e9 + _DEFAULT_SOURCE + Before glibc 2.27: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR ffs () +function returns the position of the first +(least significant) bit set in the word \fIi\fP. +The least significant bit is position 1 and the +most significant position is, for example, 32 or 64. +The functions +.BR ffsll () +and +.BR ffsl () +do the same but take +arguments of possibly different size. +.SH RETURN VALUE +These functions return the position of the first bit set, +or 0 if no bits are set in +.IR i . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ffs (), +.BR ffsl (), +.BR ffsll () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR ffs () +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.TP +.BR ffsl () +.TQ +.BR ffsll () +GNU. +.SH SEE ALSO +.BR memchr (3) diff --git a/man/man3/ffsl.3 b/man/man3/ffsl.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man/man3/ffsl.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man/man3/ffsll.3 b/man/man3/ffsll.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man/man3/ffsll.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man/man3/fgetc.3 b/man/man3/fgetc.3 new file mode 100644 index 0000000..0393712 --- /dev/null +++ b/man/man3/fgetc.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.TH fgetc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetc, fgets, getc, getchar, ungetc \- input of characters and strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fgetc(FILE *" stream ); +.BI "int getc(FILE *" stream ); +.B "int getchar(void);" +.P +.BI "char *fgets(char " s "[restrict ." size "], int " size ", \ +FILE *restrict " stream ); +.P +.BI "int ungetc(int " c ", FILE *" stream ); +.fi +.SH DESCRIPTION +.BR fgetc () +reads the next character from +.I stream +and returns it as an +.I unsigned char +cast to an +.IR int , +or +.B EOF +on end of file or error. +.P +.BR getc () +is equivalent to +.BR fgetc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.P +.BR getchar () +is equivalent to +.BI "getc(" stdin ) \fR. +.P +.BR fgets () +reads in at most one less than +.I size +characters from +.I stream +and stores them into the buffer pointed to by +.IR s . +Reading stops after an +.B EOF +or a newline. +If a newline is read, it is stored into the buffer. +A terminating null byte (\[aq]\e0\[aq]) +is stored after the last character in the buffer. +.P +.BR ungetc () +pushes +.I c +back to +.IR stream , +cast to +.IR "unsigned char" , +where it is available for subsequent read operations. +Pushed-back characters +will be returned in reverse order; only one pushback is guaranteed. +.P +Calls to the functions described here can be mixed with each other and with +calls to other input functions from the +.I stdio +library for the same input stream. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fgetc (), +.BR getc (), +and +.BR getchar () +return the character read as an +.I unsigned char +cast to an +.I int +or +.B EOF +on end of file or error. +.P +.BR fgets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +.P +.BR ungetc () +returns +.I c +on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetc (), +.BR fgets (), +.BR getc (), +.BR getchar (), +.BR ungetc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH NOTES +It is not advisable to mix calls to input functions from the +.I stdio +library with low-level calls to +.BR read (2) +for the file descriptor associated with the input stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR gets (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) diff --git a/man/man3/fgetc_unlocked.3 b/man/man3/fgetc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetgrent.3 b/man/man3/fgetgrent.3 new file mode 100644 index 0000000..b69572c --- /dev/null +++ b/man/man3/fgetgrent.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:38:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH fgetgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetgrent \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <sys/types.h> +.B #include <grp.h> +.P +.BI "struct group *fgetgrent(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fgetgrent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR fgetgrent () +function returns a pointer to a structure containing +the group information from the file referred to by +.IR stream . +The first time it is called +it returns the first entry; thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/group +(see +.BR group (5)). +.P +The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I group +structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetgrent () +T} Thread safety MT-Unsafe race:fgetgrent +.TE +.\" FIXME The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetgrent: MT-Unsafe race:fgrent +.\" +.\" We think race:fgrent in glibc may be hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetgrent, however, something about the copyright impeded the +.\" progress. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent_r (3), +.BR fopen (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR setgrent (3), +.BR group (5) diff --git a/man/man3/fgetgrent_r.3 b/man/man3/fgetgrent_r.3 new file mode 100644 index 0000000..7c6dfe4 --- /dev/null +++ b/man/man3/fgetgrent_r.3 @@ -0,0 +1 @@ +.so man3/getgrent_r.3 diff --git a/man/man3/fgetpos.3 b/man/man3/fgetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/fgetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/fgetpwent.3 b/man/man3/fgetpwent.3 new file mode 100644 index 0000000..42dd016 --- /dev/null +++ b/man/man3/fgetpwent.3 @@ -0,0 +1,127 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de) +.\" +.TH fgetpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetpwent \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <sys/types.h> +.B #include <pwd.h> +.P +.BI "struct passwd *fgetpwent(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fgetpwent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR fgetpwent () +function returns a pointer to a structure containing +the broken out fields of a line in the file \fIstream\fP. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/passwd +(see +.BR passwd (5)). +.P +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetpwent () +T} Thread safety MT-Unsafe race:fgetpwent +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetpwent: MT-Unsafe race:fpwent +.\" +.\" We think race:fpwent in glibc maybe hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetpwent, however, something about the copyright impeded the +.\" progress. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent_r (3), +.BR fopen (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/fgetpwent_r.3 b/man/man3/fgetpwent_r.3 new file mode 100644 index 0000000..b2393bb --- /dev/null +++ b/man/man3/fgetpwent_r.3 @@ -0,0 +1 @@ +.so man3/getpwent_r.3 diff --git a/man/man3/fgets.3 b/man/man3/fgets.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/fgets.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/fgets_unlocked.3 b/man/man3/fgets_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgets_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetspent.3 b/man/man3/fgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/fgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/fgetspent_r.3 b/man/man3/fgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/fgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/fgetwc.3 b/man/man3/fgetwc.3 new file mode 100644 index 0000000..510a72d --- /dev/null +++ b/man/man3/fgetwc.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon <moz@compsoc.man.ac.uk> +.TH fgetwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetwc, getwc \- read a wide character from a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <wchar.h> +.P +.BI "wint_t fgetwc(FILE *" stream ); +.BI "wint_t getwc(FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fgetwc () +function is the wide-character equivalent +of the +.BR fgetc (3) +function. +It reads a wide character from \fIstream\fP and returns it. +If the end of stream is reached, or if \fIferror(stream)\fP becomes true, +it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +\fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +.P +The +.BR getwc () +function or macro functions identically to +.BR fgetwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fgetwc () +returns the next wide-character from the stream. +Otherwise, +.B WEOF +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +The data obtained from the input stream does not +form a valid character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetwc (), +.BR getwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fgetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetwc () +will actually read a multibyte sequence +from the stream and then convert it to a wide character. +.SH SEE ALSO +.BR fgetws (3), +.BR fputwc (3), +.BR ungetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fgetwc_unlocked.3 b/man/man3/fgetwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetws.3 b/man/man3/fgetws.3 new file mode 100644 index 0000000..4d4f6e1 --- /dev/null +++ b/man/man3/fgetws.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon <moz@compsoc.man.ac.uk> +.TH fgetws 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetws \- read a wide-character string from a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *fgetws(wchar_t " ws "[restrict ." n "], int " n \ +", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR fgetws () +function is the wide-character equivalent +of the +.BR fgets (3) +function. +It reads a string of at most \fIn\-1\fP wide characters into the +wide-character array pointed to by \fIws\fP, +and adds a terminating null wide character (L\[aq]\e0\[aq]). +It stops reading wide characters after it has encountered and +stored a newline wide character. +It also stops when end of stream is reached. +.P +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIws\fP. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fgetws () +function, if successful, returns \fIws\fP. +If end of stream +was already reached or if an error occurred, it returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetws () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fgetws () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetws () +will actually read a multibyte string +from the stream and then convert it to a wide-character string. +.P +This function is unreliable, +because it does not permit to deal properly with +null wide characters that may be present in the input. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fgetws_unlocked.3 b/man/man3/fgetws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fileno.3 b/man/man3/fileno.3 new file mode 100644 index 0000000..81bafb7 --- /dev/null +++ b/man/man3/fileno.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (C) 2021 Michael Kerrisk <mtk.manpages@gmail.com> +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" Added remark on EBADF for fileno, aeb, 2001-03-22 +.\" +.TH fileno 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fileno \- obtain file descriptor of a stdio stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fileno(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fileno (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The function +.BR fileno () +examines the argument +.I stream +and returns the integer file descriptor used to implement this stream. +The file descriptor is still owned by +.I stream +and will be closed when +.BR fclose (3) +is called. +Duplicate the file descriptor with +.BR dup (2) +before passing it to code that might close it. +.P +For the nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fileno () +returns the file descriptor associated with +.IR stream . +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not associated with a file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fileno () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR open (2), +.BR fdopen (3), +.BR stdio (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fileno_unlocked.3 b/man/man3/fileno_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fileno_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/finite.3 b/man/man3/finite.3 new file mode 100644 index 0000000..8cc426d --- /dev/null +++ b/man/man3/finite.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH finite 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \- +BSD floating-point classification functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "int finite(double " x ); +.BI "int finitef(float " x ); +.BI "int finitel(long double " x ); +.P +.BI "int isinf(double " x ); +.BI "int isinff(float " x ); +.BI "int isinfl(long double " x ); +.P +.BI "int isnan(double " x ); +.BI "int isnanf(float " x ); +.BI "int isnanl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR finite (), +.BR finitef (), +.BR finitel (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.P +.BR isinf (): + _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isinff (), +.BR isinfl (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isnan (): +.nf + _XOPEN_SOURCE || _ISOC99_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isnanf (), +.BR isnanl (): +.nf + _XOPEN_SOURCE >= 600 + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR finite (), +.BR finitef (), +and +.BR finitel () +functions return a nonzero value if +.I x +is neither infinite +nor a "not-a-number" (NaN) value, and 0 otherwise. +.P +The +.BR isnan (), +.BR isnanf (), +and +.BR isnanl () +functions return a nonzero value if +.I x +is a NaN value, +and 0 otherwise. +.P +The +.BR isinf (), +.BR isinff (), +and +.BR isinfl () +functions return 1 if +.I x +is positive infinity, \-1 if +.I x +is negative infinity, and 0 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR finite (), +.BR finitef (), +.BR finitel (), +.BR isinf (), +.BR isinff (), +.BR isinfl (), +.BR isnan (), +.BR isnanf (), +.BR isnanl () +T} Thread safety MT-Safe +.TE +.SH NOTES +Note that these functions are obsolete. +C99 defines macros +.BR isfinite (), +.BR isinf (), +and +.BR isnan () +(for all types) replacing them. +Further note that the C99 +.BR isinf () +has weaker guarantees on the return value. +See +.BR fpclassify (3). +.\" +.\" finite* not on HP-UX; they exist on Tru64. +.\" .SH HISTORY +.\" The +.\" .BR finite () +.\" function occurs in 4.3BSD. +.\" see IEEE.3 in the 4.3BSD manual +.SH SEE ALSO +.BR fpclassify (3) diff --git a/man/man3/finitef.3 b/man/man3/finitef.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/finitef.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/finitel.3 b/man/man3/finitel.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/finitel.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/flockfile.3 b/man/man3/flockfile.3 new file mode 100644 index 0000000..325a676 --- /dev/null +++ b/man/man3/flockfile.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH flockfile 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +flockfile, ftrylockfile, funlockfile \- lock FILE for stdio +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "void flockfile(FILE *" filehandle ); +.BI "int ftrylockfile(FILE *" filehandle ); +.BI "void funlockfile(FILE *" filehandle ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L + || /* glibc <= 2.23: */ _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The stdio functions are thread-safe. +This is achieved by assigning +to each +.I FILE +object a lockcount and (if the lockcount is nonzero) +an owning thread. +For each library call, these functions wait until the +.I FILE +object +is no longer locked by a different thread, then lock it, do the +requested I/O, and unlock the object again. +.P +(Note: this locking has nothing to do with the file locking done +by functions like +.BR flock (2) +and +.BR lockf (3).) +.P +All this is invisible to the C-programmer, but there may be two +reasons to wish for more detailed control. +On the one hand, maybe +a series of I/O actions by one thread belongs together, and should +not be interrupted by the I/O of some other thread. +On the other hand, maybe the locking overhead should be avoided +for greater efficiency. +.P +To this end, a thread can explicitly lock the +.I FILE +object, +then do its series of I/O actions, then unlock. +This prevents +other threads from coming in between. +If the reason for doing +this was to achieve greater efficiency, one does the I/O with +the nonlocking versions of the stdio functions: with +.BR getc_unlocked (3) +and +.BR putc_unlocked (3) +instead of +.BR getc (3) +and +.BR putc (3). +.P +The +.BR flockfile () +function waits for +.I *filehandle +to be +no longer locked by a different thread, then makes the +current thread owner of +.IR *filehandle , +and increments +the lockcount. +.P +The +.BR funlockfile () +function decrements the lock count. +.P +The +.BR ftrylockfile () +function is a nonblocking version +of +.BR flockfile (). +It does nothing in case some other thread +owns +.IR *filehandle , +and it obtains ownership and increments +the lockcount otherwise. +.SH RETURN VALUE +The +.BR ftrylockfile () +function returns zero for success +(the lock was obtained), and nonzero for failure. +.SH ERRORS +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR flockfile (), +.BR ftrylockfile (), +.BR funlockfile () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +These functions are available when +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH SEE ALSO +.BR unlocked_stdio (3) diff --git a/man/man3/floor.3 b/man/man3/floor.3 new file mode 100644 index 0000000..88d8503 --- /dev/null +++ b/man/man3/floor.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH floor 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +floor, floorf, floorl \- largest integral value not greater than argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double floor(double " x ); +.BI "float floorf(float " x ); +.BI "long double floorl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR floorf (), +.BR floorl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the largest integral value that is not greater than +.IR x . +.P +For example, +.I floor(0.5) +is 0.0, and +.I floor(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the floor of +.IR x . +.P +If +.I x +is integral, +0, \-0, NaN, or an infinity, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR floor (), +.BR floorf (), +.BR floorl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.P +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.SH SEE ALSO +.BR ceil (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/floorf.3 b/man/man3/floorf.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man/man3/floorf.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man/man3/floorl.3 b/man/man3/floorl.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man/man3/floorl.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man/man3/fma.3 b/man/man3/fma.3 new file mode 100644 index 0000000..ecf1140 --- /dev/null +++ b/man/man3/fma.3 @@ -0,0 +1,167 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2004-11-15, Added further text on FLT_ROUNDS +.\" as suggested by AEB and Fabian Kreutz +.\" +.TH fma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fma, fmaf, fmal \- floating-point multiply and add +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fma(double " x ", double " y ", double " z ); +.BI "float fmaf(float " x ", float " y ", float " z ); +.BI "long double fmal(long double " x ", long double " y ", long double " z ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fma (), +.BR fmaf (), +.BR fmal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions compute +.IR x " * " y " + " z . +The result is rounded as one ternary operation according to the +current rounding mode (see +.BR fenv (3)). +.SH RETURN VALUE +These functions return the value of +.IR x " * " y " + " z , +rounded as one ternary operation. +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +times +.I y +is an exact infinity, and +.I z +is an infinity with the opposite sign, +a domain error occurs, +and a NaN is returned. +.P +.\" POSIX.1-2008 allows some possible differences for the following two +.\" domain error cases, but on Linux they are treated the same (AFAICS). +.\" Nevertheless, we'll mirror POSIX.1 and describe the two cases +.\" separately. +If one of +.I x +or +.I y +is an infinity, the other is 0, and +.I z +is not a NaN, +a domain error occurs, and +a NaN is returned. +.\" POSIX.1 says that a NaN or an implementation-defined value shall +.\" be returned for this case. +.P +If one of +.I x +or +.I y +is an infinity, and the other is 0, and +.I z +is a NaN, +.\" POSIX.1 makes the domain error optional for this case. +a domain error occurs, and +a NaN is returned. +.P +If +.I x +times +.I y +is not an infinity times zero (or vice versa), and +.I z +is a NaN, +a NaN is returned. +.P +If the result overflows, +a range error occurs, and +an infinity with the correct sign is returned. +.P +If the result underflows, +a range error occurs, and +a signed 0 is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \ +or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6801 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fma (), +.BR fmaf (), +.BR fmal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR remainder (3), +.BR remquo (3) diff --git a/man/man3/fmaf.3 b/man/man3/fmaf.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man/man3/fmaf.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man/man3/fmal.3 b/man/man3/fmal.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man/man3/fmal.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man/man3/fmax.3 b/man/man3/fmax.3 new file mode 100644 index 0000000..9a388c7 --- /dev/null +++ b/man/man3/fmax.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmax, fmaxf, fmaxl \- determine maximum of two floating-point numbers +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fmax(double " x ", double " y ); +.BI "float fmaxf(float " x ", float " y ); +.BI "long double fmaxl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmax (), +.BR fmaxf (), +.BR fmaxl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the larger value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the maximum of +.I x +and +.IR y . +.P +If one argument is a NaN, the other argument is returned. +.P +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmax (), +.BR fmaxf (), +.BR fmaxl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fdim (3), +.BR fmin (3) diff --git a/man/man3/fmaxf.3 b/man/man3/fmaxf.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man/man3/fmaxf.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man/man3/fmaxl.3 b/man/man3/fmaxl.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man/man3/fmaxl.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man/man3/fmemopen.3 b/man/man3/fmemopen.3 new file mode 100644 index 0000000..eb68fd3 --- /dev/null +++ b/man/man3/fmemopen.3 @@ -0,0 +1,352 @@ +'\" t +.\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmemopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmemopen \- open memory as stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *fmemopen(void " buf [. size "], size_t " size ", \ +const char *" mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmemopen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR fmemopen () +function opens a stream that permits the access specified by +.IR mode . +The stream allows I/O to be performed on the string or memory buffer +pointed to by +.IR buf . +.P +The +.I mode +argument specifies the semantics of I/O on the stream, +and is one of the following: +.TP +.I r +The stream is opened for reading. +.TP +.I w +The stream is opened for writing. +.TP +.I a +Append; open the stream for writing, +with the initial buffer position set to the first null byte. +.TP +.I r+ +Open the stream for reading and writing. +.TP +.I w+ +Open the stream for reading and writing. +The buffer contents are truncated +(i.e., \[aq]\e0\[aq] is placed in the first byte of the buffer). +.TP +.I a+ +Append; open the stream for reading and writing, +with the initial buffer position set to the first null byte. +.P +The stream maintains the notion of a current position, +the location where the next I/O operation will be performed. +The current position is implicitly updated by I/O operations. +It can be explicitly updated using +.BR fseek (3), +and determined using +.BR ftell (3). +In all modes other than append, +the initial position is set to the start of the buffer. +In append mode, if no null byte is found within the buffer, +then the initial position is +.IR size+1 . +.P +If +.I buf +is specified as NULL, then +.BR fmemopen () +allocates a buffer of +.I size +bytes. +This is useful for an application that wants to write data to +a temporary buffer and then read it back again. +The initial position is set to the start of the buffer. +The buffer is automatically freed when the stream is closed. +Note that the caller has no way to obtain a pointer to the +temporary buffer allocated by this call (but see +.BR open_memstream (3)). +.P +If +.I buf +is not NULL, then it should point to a buffer of at least +.I size +bytes allocated by the caller. +.P +When a stream that has been opened for writing is flushed +.RB ( fflush (3)) +or closed +.RB ( fclose (3)), +a null byte is written at the end of the buffer if there is space. +The caller should ensure that an extra byte is available in the +buffer +(and that +.I size +counts that byte) +to allow for this. +.P +In a stream opened for reading, +null bytes (\[aq]\e0\[aq]) in the buffer do not cause read +operations to return an end-of-file indication. +A read from the buffer will indicate end-of-file +only when the current buffer position advances +.I size +bytes past the start of the buffer. +.P +Write operations take place either at the current position +(for modes other than append), or at the current size of the stream +(for append modes). +.P +Attempts to write more than +.I size +bytes to the buffer result in an error. +By default, such errors will be visible +(by the absence of data) only when the +.I stdio +buffer is flushed. +Disabling buffering with the following call +may be useful to detect errors at the time of an output operation: +.P +.in +4n +.EX +setbuf(stream, NULL); +.EE +.in +.SH RETURN VALUE +Upon successful completion, +.BR fmemopen () +returns a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmemopen (), +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 1.0.x. +POSIX.1-2008. +.P +POSIX.1-2008 specifies that \[aq]b\[aq] in +.I mode +shall be ignored. +However, Technical Corrigendum 1 +.\" http://austingroupbugs.net/view.php?id=396 +adjusts the standard to allow implementation-specific treatment for this case, +thus permitting the glibc treatment of \[aq]b\[aq]. +.P +With glibc 2.22, binary mode (see below) was removed, +many longstanding bugs in the implementation of +.BR fmemopen () +were fixed, and a new versioned symbol was created for this interface. +.\" +.SS Binary mode +From glibc 2.9 to glibc 2.21, the glibc implementation of +.BR fmemopen () +supported a "binary" mode, +enabled by specifying the letter \[aq]b\[aq] as the second character in +.IR mode . +In this mode, +writes don't implicitly add a terminating null byte, and +.BR fseek (3) +.B SEEK_END +is relative to the end of the buffer (i.e., the value specified by the +.I size +argument), rather than the current string length. +.P +An API bug afflicted the implementation of binary mode: +to specify binary mode, the \[aq]b\[aq] must be the +.I second +character in +.IR mode . +Thus, for example, "wb+" has the desired effect, but "w+b" does not. +This is inconsistent with the treatment of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836 +.I mode +by +.BR fopen (3). +.P +Binary mode was removed in glibc 2.22; a \[aq]b\[aq] specified in +.I mode +has no effect. +.SH NOTES +There is no file descriptor associated with the file stream +returned by this function +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.SH BUGS +Before glibc 2.22, if +.I size +is specified as zero, +.BR fmemopen () +fails with the error +.BR EINVAL . +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216 +It would be more consistent if this case successfully created +a stream that then returned end-of-file on the first attempt at reading; +since glibc 2.22, the glibc implementation provides that behavior. +.P +Before glibc 2.22, +specifying append mode ("a" or "a+") for +.BR fmemopen () +sets the initial buffer position to the first null byte, but +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152 +(if the current position is reset to a location other than +the end of the stream) +does not force subsequent writes to append at the end of the stream. +This bug is fixed in glibc 2.22. +.P +Before glibc 2.22, if the +.I mode +argument to +.BR fmemopen () +specifies append ("a" or "a+"), and the +.I size +argument does not cover a null byte in +.IR buf , +then, according to POSIX.1-2008, +the initial buffer position should be set to +the next byte after the end of the buffer. +However, in this case the glibc +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151 +.BR fmemopen () +sets the buffer position to \-1. +This bug is fixed in glibc 2.22. +.P +Before glibc 2.22, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292 +when a call to +.BR fseek (3) +with a +.I whence +value of +.B SEEK_END +was performed on a stream created by +.BR fmemopen (), +the +.I offset +was +.I subtracted +from the end-of-stream position, instead of being added. +This bug is fixed in glibc 2.22. +.P +The glibc 2.9 addition of "binary" mode for +.BR fmemopen () +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 +silently changed the ABI: previously, +.BR fmemopen () +ignored \[aq]b\[aq] in +.IR mode . +.SH EXAMPLES +The program below uses +.BR fmemopen () +to open an input buffer, and +.BR open_memstream (3) +to open a dynamically sized output buffer. +The program scans its input string (taken from the program's +first command-line argument) reading integers, +and writes the squares of these integers to the output buffer. +An example of the output produced by this program is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]1 23 43\[aq]" +size=11; ptr=1 529 1849 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (fmemopen.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + FILE *out, *in; + int v, s; + size_t size; + char *ptr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \[aq]<num>...\[aq]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + in = fmemopen(argv[1], strlen(argv[1]), "r"); + if (in == NULL) + err(EXIT_FAILURE, "fmemopen"); +\& + out = open_memstream(&ptr, &size); + if (out == NULL) + err(EXIT_FAILURE, "open_memstream"); +\& + for (;;) { + s = fscanf(in, "%d", &v); + if (s <= 0) + break; +\& + s = fprintf(out, "%d ", v * v); + if (s == \-1) + err(EXIT_FAILURE, "fprintf"); + } +\& + fclose(in); + fclose(out); +\& + printf("size=%zu; ptr=%s\en", size, ptr); +\& + free(ptr); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fopen (3), +.BR fopencookie (3), +.BR open_memstream (3) diff --git a/man/man3/fmin.3 b/man/man3/fmin.3 new file mode 100644 index 0000000..45b83de --- /dev/null +++ b/man/man3/fmin.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmin, fminf, fminl \- determine minimum of two floating-point numbers +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fmin(double " x ", double " y ); +.BI "float fminf(float " x ", float " y ); +.BI "long double fminl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmin (), +.BR fminf (), +.BR fminl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the lesser value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the minimum of +.I x +and +.IR y . +.P +If one argument is a NaN, the other argument is returned. +.P +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmin (), +.BR fminf (), +.BR fminl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fdim (3), +.BR fmax (3) diff --git a/man/man3/fminf.3 b/man/man3/fminf.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man/man3/fminf.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man/man3/fminl.3 b/man/man3/fminl.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man/man3/fminl.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man/man3/fmod.3 b/man/man3/fmod.3 new file mode 100644 index 0000000..211b2f8 --- /dev/null +++ b/man/man3/fmod.3 @@ -0,0 +1,183 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH fmod 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmod, fmodf, fmodl \- floating-point remainder function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double fmod(double " x ", double " y ); +.BI "float fmodf(float " x ", float " y ); +.BI "long double fmodl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmodf (), +.BR fmodl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions compute the floating-point remainder of dividing +.I x +by +.IR y . +The return value is +.I x +\- +.I n +* +.IR y , +where +.I n +is the quotient of +.I x +/ +.IR y , +rounded toward zero to an integer. +.P +To obtain the modulus, more specifically, the Least Positive Residue, +you will need to adjust the result from fmod like so: +.P +.in +4n +.nf +z = fmod(x, y); +if (z < 0) + z += y; +.fi +.in +.P +An alternate way to express this is with +.IR "fmod(fmod(x, y) + y, y)" , +but the second +.BR fmod () +usually costs way more than the one branch. +.SH RETURN VALUE +On success, these +functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP, +for some integer +.IR n , +such that the returned value has the same sign as +.I x +and a magnitude less than the magnitude of +.IR y . +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +a domain error occurs, and +a NaN is returned. +.P +If +.I x +is +0 (\-0), and +.I y +is not zero, +0 (\-0) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Domain error: \fIy\fP is zero +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.\" POSIX.1 documents an optional underflow error, but AFAICT it doesn't +.\" (can't?) occur -- mtk, Jul 2008 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmod (), +.BR fmodf (), +.BR fmodl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6784 +.I errno +to +.B EDOM +when a domain error occurred for an infinite +.IR x . +.SH EXAMPLES +The call +.I fmod(372, 360) +returns 348. +.P +The call +.I fmod(-372, 360) +returns -12. +.P +The call +.I fmod(-372, -360) +also returns -12. +.SH SEE ALSO +.BR remainder (3) diff --git a/man/man3/fmodf.3 b/man/man3/fmodf.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man/man3/fmodf.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man/man3/fmodl.3 b/man/man3/fmodl.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man/man3/fmodl.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man/man3/fmtmsg.3 b/man/man3/fmtmsg.3 new file mode 100644 index 0000000..b4fc2cc --- /dev/null +++ b/man/man3/fmtmsg.3 @@ -0,0 +1,337 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" adapted glibc info page +.\" +.\" This should run as 'Guru Meditation' (amiga joke :) +.\" The function is quite complex and deserves an example +.\" +.\" Polished, aeb, 2003-11-01 +.TH fmtmsg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmtmsg \- print formatted error messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <fmtmsg.h> +.P +.BI "int fmtmsg(long " classification ", const char *" label , +.BI " int " severity ", const char *" text , +.BI " const char *" action ", const char *" tag ); +.fi +.SH DESCRIPTION +This function displays a message described by its arguments on the device(s) +specified in the +.I classification +argument. +For messages written to +.IR stderr , +the format depends on the +.B MSGVERB +environment variable. +.P +The +.I label +argument identifies the source of the message. +The string must consist +of two colon separated parts where the first part has not more +than 10 and the second part not more than 14 characters. +.P +The +.I text +argument describes the condition of the error. +.P +The +.I action +argument describes possible steps to recover from the error. +If it is printed, it is prefixed by "TO FIX: ". +.P +The +.I tag +argument is a reference to the online documentation where more +information can be found. +It should contain the +.I label +value and a unique identification number. +.SS Dummy arguments +Each of the arguments can have a dummy value. +The dummy classification value +.B MM_NULLMC +(0L) does not specify any output, so nothing is printed. +The dummy severity value +.B NO_SEV +(0) says that no severity is supplied. +The values +.BR MM_NULLLBL , +.BR MM_NULLTXT , +.BR MM_NULLACT , +.B MM_NULLTAG +are synonyms for +.IR "((char\ *)\ 0)" , +the empty string, and +.B MM_NULLSEV +is a synonym for +.BR NO_SEV . +.SS The classification argument +The +.I classification +argument is the sum of values describing 4 types of information. +.P +The first value defines the output channel. +.TP 12n +.B MM_PRINT +Output to +.IR stderr . +.TP +.B MM_CONSOLE +Output to the system console. +.TP +.B "MM_PRINT | MM_CONSOLE" +Output to both. +.P +The second value is the source of the error: +.TP 12n +.B MM_HARD +A hardware error occurred. +.TP +.B MM_FIRM +A firmware error occurred. +.TP +.B MM_SOFT +A software error occurred. +.P +The third value encodes the detector of the problem: +.TP 12n +.B MM_APPL +It is detected by an application. +.TP +.B MM_UTIL +It is detected by a utility. +.TP +.B MM_OPSYS +It is detected by the operating system. +.P +The fourth value shows the severity of the incident: +.TP 12n +.B MM_RECOVER +It is a recoverable error. +.TP +.B MM_NRECOV +It is a nonrecoverable error. +.SS The severity argument +The +.I severity +argument can take one of the following values: +.TP 12n +.B MM_NOSEV +No severity is printed. +.TP +.B MM_HALT +This value is printed as HALT. +.TP +.B MM_ERROR +This value is printed as ERROR. +.TP +.B MM_WARNING +This value is printed as WARNING. +.TP +.B MM_INFO +This value is printed as INFO. +.P +The numeric values are between 0 and 4. +Using +.BR addseverity (3) +or the environment variable +.B SEV_LEVEL +you can add more levels and strings to print. +.SH RETURN VALUE +The function can return 4 values: +.TP 12n +.B MM_OK +Everything went smooth. +.TP +.B MM_NOTOK +Complete failure. +.TP +.B MM_NOMSG +Error writing to +.IR stderr . +.TP +.B MM_NOCON +Error writing to the console. +.SH ENVIRONMENT +The environment variable +.B MSGVERB +("message verbosity") can be used to suppress parts of +the output to +.IR stderr . +(It does not influence output to the console.) +When this variable is defined, is non-NULL, and is a colon-separated +list of valid keywords, then only the parts of the message corresponding +to these keywords is printed. +Valid keywords are "label", "severity", "text", "action", and "tag". +.P +The environment variable +.B SEV_LEVEL +can be used to introduce new severity levels. +By default, only the five severity levels described +above are available. +Any other numeric value would make +.BR fmtmsg () +print nothing. +If the user puts +.B SEV_LEVEL +with a format like +.P +.RS +SEV_LEVEL=[description[:description[:...]]] +.RE +.P +in the environment of the process before the first call to +.BR fmtmsg (), +where each description is of the form +.P +.RS +severity-keyword,level,printstring +.RE +.P +then +.BR fmtmsg () +will also accept the indicated values for the level (in addition to +the standard levels 0\[en]4), and use the indicated printstring when +such a level occurs. +.P +The severity-keyword part is not used by +.BR fmtmsg () +but it has to be present. +The level part is a string representation of a number. +The numeric value must be a number greater than 4. +This value must be used in the severity argument of +.BR fmtmsg () +to select this class. +It is not possible to overwrite +any of the predefined classes. +The printstring +is the string printed when a message of this class is processed by +.BR fmtmsg (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmtmsg () +T} Thread safety T{ +.na +.nh +glibc\ >=\ 2.16: MT-Safe; +glibc\ <\ 2.16: MT-Unsafe +T} +.TE +.P +Before glibc 2.16, the +.BR fmtmsg () +function uses a static variable that is not protected, +so it is not thread-safe. +.P +Since glibc 2.16, +.\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 +the +.BR fmtmsg () +function uses a lock to protect the static variable, so it is thread-safe. +.SH STANDARDS +.TP +.BR fmtmsg () +.TQ +.B MSGVERB +POSIX.1-2008. +.SH HISTORY +.TP +.BR fmtmsg () +System V. +POSIX.1-2001 and POSIX.1-2008. +glibc 2.1. +.TP +.B MSGVERB +System V. +POSIX.1-2001 and POSIX.1-2008. +.TP +.B SEV_LEVEL +System V. +.P +System V and UnixWare man pages tell us that these functions +have been replaced by "pfmt() and addsev()" or by "pfmt(), +vpfmt(), lfmt(), and vlfmt()", and will be removed later. +.SH EXAMPLES +.\" SRC BEGIN (fmtmsg.c) +.EX +#include <fmtmsg.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; + int err; +\& + err = fmtmsg(class, "util\-linux:mount", MM_ERROR, + "unknown mount option", "See mount(8).", + "util\-linux:mount:017"); + switch (err) { + case MM_OK: + break; + case MM_NOTOK: + printf("Nothing printed\en"); + break; + case MM_NOMSG: + printf("Nothing printed to stderr\en"); + break; + case MM_NOCON: + printf("No console output\en"); + break; + default: + printf("Unknown error from fmtmsg()\en"); + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +The output should be: +.P +.in +4n +.EX +util\-linux:mount: ERROR: unknown mount option +TO FIX: See mount(8). util\-linux:mount:017 +.EE +.in +.P +and after +.P +.in +4n +.EX +MSGVERB=text:action; export MSGVERB +.EE +.in +.P +the output becomes: +.P +.in +4n +.EX +unknown mount option +TO FIX: See mount(8). +.EE +.in +.SH SEE ALSO +.BR addseverity (3), +.BR perror (3) diff --git a/man/man3/fnmatch.3 b/man/man3/fnmatch.3 new file mode 100644 index 0000000..c359a1d --- /dev/null +++ b/man/man3/fnmatch.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:35:54 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Oct 16 00:16:29 2000 following Joseph S. Myers +.\" +.TH fnmatch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fnmatch \- match filename or pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <fnmatch.h> +.P +.BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR fnmatch () +function checks whether the +.I string +argument matches the +.I pattern +argument, which is a shell wildcard pattern (see +.BR glob (7)). +.P +The +.I flags +argument modifies the behavior; it is the bitwise OR of zero or more +of the following flags: +.TP +.B FNM_NOESCAPE +If this flag is set, treat backslash as an ordinary character, +instead of an escape character. +.TP +.B FNM_PATHNAME +If this flag is set, match a slash in +.I string +only with a slash in +.I pattern +and not by an asterisk (*) or a question mark (?) metacharacter, +nor by a bracket expression ([]) containing a slash. +.TP +.B FNM_PERIOD +If this flag is set, a leading period in +.I string +has to be matched exactly by a period in +.IR pattern . +A period is considered to be leading if it is the first character in +.IR string , +or if both +.B FNM_PATHNAME +is set and the period immediately follows a slash. +.TP +.B FNM_FILE_NAME +This is a GNU synonym for +.BR FNM_PATHNAME . +.TP +.B FNM_LEADING_DIR +If this flag (a GNU extension) is set, the pattern is considered to be +matched if it matches an initial segment of +.I string +which is followed by a slash. +This flag is mainly for the internal +use of glibc and is implemented only in certain cases. +.TP +.B FNM_CASEFOLD +If this flag (a GNU extension) is set, the pattern is matched +case-insensitively. +.TP +.B FNM_EXTMATCH +If this flag (a GNU extension) is set, extended patterns are +supported, as introduced by \&'ksh' and now supported by other shells. +The extended format is as follows, with \fIpattern\-list\fR +being a \&'|' separated list of patterns. +.TP +\&'?(\fIpattern\-list\fR)' +The pattern matches if zero or one occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'*(\fIpattern\-list\fR)' +The pattern matches if zero or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'+(\fIpattern\-list\fR)' +The pattern matches if one or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'@(\fIpattern\-list\fR)' +The pattern matches if exactly one occurrence of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'!(\fIpattern\-list\fR)' +The pattern matches if the input \fIstring\fR cannot be matched with +any of the patterns in the \fIpattern\-list\fR. +.SH RETURN VALUE +Zero if +.I string +matches +.IR pattern , +.B FNM_NOMATCH +if there is no match or another nonzero value if there is an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fnmatch () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR fnmatch () +POSIX.1-2008. +.TP +.B FNM_FILE_NAME +.TQ +.B FNM_LEADING_DIR +.TQ +.B FNM_CASEFOLD +GNU. +.SH HISTORY +.TP +.BR fnmatch () +POSIX.1-2001, POSIX.2. +.SH SEE ALSO +.BR sh (1), +.BR glob (3), +.BR scandir (3), +.BR wordexp (3), +.BR glob (7) diff --git a/man/man3/fopen.3 b/man/man3/fopen.3 new file mode 100644 index 0000000..bf09c62 --- /dev/null +++ b/man/man3/fopen.3 @@ -0,0 +1,405 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" Modified, aeb, 960421, 970806 +.\" Modified, joey, aeb, 2002-01-03 +.\" +.TH fopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fopen, fdopen, freopen \- stream open functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *fopen(const char *restrict " pathname \ +", const char *restrict " mode ); +.BI "FILE *fdopen(int " fd ", const char *" mode ); +.BI "FILE *freopen(const char *restrict " pathname \ +", const char *restrict " mode , +.BI " FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdopen (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR fopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates a stream with it. +.P +The argument +.I mode +points to a string beginning with one of the following sequences +(possibly followed by additional characters, as described below): +.TP +.B r +Open text file for reading. +The stream is positioned at the beginning of the file. +.TP +.B r+ +Open for reading and writing. +The stream is positioned at the beginning of the file. +.TP +.B w +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. +.TP +.B w+ +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of +the file. +.TP +.B a +Open for appending (writing at end of file). +The file is created if it does not exist. +The stream is positioned at the end of the file. +.TP +.B a+ +Open for reading and appending (writing at end of file). +The file is created if it does not exist. +Output is always appended to the end of the file. +POSIX is silent on what the initial read position is when using this mode. +For glibc, the initial file position for reading is at +the beginning of the file, but for Android/BSD/MacOS, the +initial file position for reading is at the end of the file. +.P +The +.I mode +string can also include the letter \[aq]b\[aq] either as a last character or as +a character between the characters in any of the two-character strings +described above. +This is strictly for compatibility with ISO C +and has no effect; the \[aq]b\[aq] is ignored on all POSIX +conforming systems, including Linux. +(Other systems may treat text files and binary files differently, +and adding the \[aq]b\[aq] may be a good idea if you do I/O to a binary +file and expect that your program may be ported to non-UNIX +environments.) +.P +See NOTES below for details of glibc extensions for +.IR mode . +.P +Any created file will have the mode +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH +(0666), as modified by the process's umask value (see +.BR umask (2)). +.P +Reads and writes may be intermixed on read/write streams in any order. +Note that ANSI C requires that a file positioning function intervene +between output and input, unless an input operation encounters end-of-file. +(If this condition is not met, then a read is allowed to return the +result of writes other than the most recent.) +Therefore it is good practice (and indeed sometimes necessary +under Linux) to put an +.BR fseek (3) +or +.BR fsetpos (3) +operation between write and read operations on such a stream. +This operation may be an apparent no-op +(as in \fIfseek(..., 0L, SEEK_CUR)\fP +called for its synchronizing side effect). +.P +Opening a file in append mode (\fBa\fP as the first character of +.IR mode ) +causes all subsequent write operations to this stream to occur +at end-of-file, as if preceded by the call: +.P +.in +4n +.EX +fseek(stream, 0, SEEK_END); +.EE +.in +.P +The file descriptor associated with the stream is opened as if by a call to +.BR open (2) +with the following flags: +.RS +.TS +allbox; +lb lb +c l. +fopen() mode open() flags +\fIr\fP O_RDONLY +\fIw\fP O_WRONLY | O_CREAT | O_TRUNC +\fIa\fP O_WRONLY | O_CREAT | O_APPEND +\fIr+\fP O_RDWR +\fIw+\fP O_RDWR | O_CREAT | O_TRUNC +\fIa+\fP O_RDWR | O_CREAT | O_APPEND +.TE +.RE +.\" +.SS fdopen() +The +.BR fdopen () +function associates a stream with the existing file descriptor, +.IR fd . +The +.I mode +of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") +must be compatible with the mode of the file descriptor. +The file position indicator of the new stream is set to that +belonging to +.IR fd , +and the error and end-of-file indicators are cleared. +Modes "w" or "w+" do not cause truncation of the file. +The file descriptor is not dup'ed, and will be closed when +the stream created by +.BR fdopen () +is closed. +The result of applying +.BR fdopen () +to a shared memory object is undefined. +.\" +.SS freopen() +The +.BR freopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates the stream pointed to by +.I stream +with it. +The original stream (if it exists) is closed. +The +.I mode +argument is used just as in the +.BR fopen () +function. +.P +If the +.I pathname +argument is a null pointer, +.BR freopen () +changes the mode of the stream to that specified in +.IR mode ; +that is, +.BR freopen () +reopens the pathname that is associated with the stream. +The specification for this behavior was added in the C99 standard, which says: +.P +.RS +In this case, +the file descriptor associated with the stream need not be closed +if the call to +.BR freopen () +succeeds. +It is implementation-defined which changes of mode are permitted (if any), +and under what circumstances. +.RE +.P +The primary use of the +.BR freopen () +function is to change the file associated with a standard text stream +.RI ( stderr ", " stdin ", or " stdout ). +.SH RETURN VALUE +Upon successful completion +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I mode +provided to +.BR fopen (), +.BR fdopen (), +or +.BR freopen () +was invalid. +.P +The +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +functions may also fail and set +.I errno +for any of the errors specified for the routine +.BR malloc (3). +.P +The +.BR fopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR open (2). +.P +The +.BR fdopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR fcntl (2). +.P +The +.BR freopen () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3), +and +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fopen (), +.BR fdopen (), +.BR freopen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR fopen () +.TQ +.BR freopen () +C11, POSIX.1-2008. +.TP +.BR fdopen () +POSIX.1-2008. +.SH HISTORY +.TP +.BR fopen () +.TQ +.BR freopen () +POSIX.1-2001, C89. +.TP +.BR fdopen () +POSIX.1-2001. +.SH NOTES +.SS glibc notes +The GNU C library allows the following extensions for the string specified in +.IR mode : +.TP +.BR c " (since glibc 2.3.3)" +Do not make the open operation, +or subsequent read and write operations, +thread cancelation points. +This flag is ignored for +.BR fdopen (). +.TP +.BR e " (since glibc 2.7)" +Open the file with the +.B O_CLOEXEC +flag. +See +.BR open (2) +for more information. +This flag is ignored for +.BR fdopen (). +.TP +.BR m " (since glibc 2.3)" +Attempt to access the file using +.BR mmap (2), +rather than I/O system calls +.RB ( read (2), +.BR write (2)). +Currently, +.\" As at glibc 2.4: +use of +.BR mmap (2) +is attempted only for a file opened for reading. +.TP +.B x +.\" Since glibc 2.0? +.\" FIXME . C11 specifies this flag +Open the file exclusively +(like the +.B O_EXCL +flag of +.BR open (2)). +If the file already exists, +.BR fopen () +fails, and sets +.I errno +to +.BR EEXIST . +This flag is ignored for +.BR fdopen (). +.P +In addition to the above characters, +.BR fopen () +and +.BR freopen () +support the following syntax +in +.IR mode : +.P +.BI " ,ccs=" string +.P +The given +.I string +is taken as the name of a coded character set and +the stream is marked as wide-oriented. +Thereafter, internal conversion functions convert I/O +to and from the character set +.IR string . +If the +.BI ,ccs= string +syntax is not specified, +then the wide-orientation of the stream is +determined by the first file operation. +If that operation is a wide-character operation, +the stream is marked wide-oriented, +and functions to convert to the coded character set are loaded. +.SH BUGS +When parsing for individual flag characters in +.I mode +(i.e., the characters preceding the "ccs" specification), +the glibc implementation of +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 +.BR fopen () +and +.BR freopen () +limits the number of characters examined in +.I mode +to 7 (or, before glibc 2.14, to 6, +which was not enough to include possible specifications such as "rb+cmxe"). +The current implementation of +.BR fdopen () +parses at most 5 characters in +.IR mode . +.SH SEE ALSO +.BR open (2), +.BR fclose (3), +.BR fileno (3), +.BR fmemopen (3), +.BR fopencookie (3), +.BR open_memstream (3) diff --git a/man/man3/fopencookie.3 b/man/man3/fopencookie.3 new file mode 100644 index 0000000..ac3c082 --- /dev/null +++ b/man/man3/fopencookie.3 @@ -0,0 +1,466 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fopencookie 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fopencookie \- open a custom stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 +.B #include <stdio.h> +.P +.BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode , +.BI " cookie_io_functions_t " io_funcs ); +.fi +.SH DESCRIPTION +The +.BR fopencookie () +function allows the programmer to create a custom implementation +for a standard I/O stream. +This implementation can store the stream's data at a location of +its own choosing; for example, +.BR fopencookie () +is used to implement +.BR fmemopen (3), +which provides a stream interface to data that is stored in a +buffer in memory. +.P +In order to create a custom stream the programmer must: +.IP \[bu] 3 +Implement four "hook" functions that are used internally by the +standard I/O library when performing I/O on the stream. +.IP \[bu] +Define a "cookie" data type, +a structure that provides bookkeeping information +(e.g., where to store data) used by the aforementioned hook functions. +The standard I/O package knows nothing about the contents of this cookie +(thus it is typed as +.I void\~* +when passed to +.BR fopencookie ()), +but automatically supplies the cookie +as the first argument when calling the hook functions. +.IP \[bu] +Call +.BR fopencookie () +to open a new stream and associate the cookie and hook functions +with that stream. +.P +The +.BR fopencookie () +function serves a purpose similar to +.BR fopen (3): +it opens a new stream and returns a pointer to a +.I FILE +object that is used to operate on that stream. +.P +The +.I cookie +argument is a pointer to the caller's cookie structure +that is to be associated with the new stream. +This pointer is supplied as the first argument when the standard I/O +library invokes any of the hook functions described below. +.P +The +.I mode +argument serves the same purpose as for +.BR fopen (3). +The following modes are supported: +.IR r , +.IR w , +.IR a , +.IR r+ , +.IR w+ , +and +.IR a+ . +See +.BR fopen (3) +for details. +.P +The +.I io_funcs +argument is a structure that contains four fields pointing to the +programmer-defined hook functions that are used to implement this stream. +The structure is defined as follows +.P +.in +4n +.EX +typedef struct { + cookie_read_function_t *read; + cookie_write_function_t *write; + cookie_seek_function_t *seek; + cookie_close_function_t *close; +} cookie_io_functions_t; +.EE +.in +.P +The four fields are as follows: +.TP +.I cookie_read_function_t *read +This function implements read operations for the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +ssize_t read(void *cookie, char *buf, size_t size); +.EE +.in +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer into which input data can be placed and the size of that buffer. +As its function result, the +.I read +function should return the number of bytes copied into +.IR buf , +0 on end of file, or \-1 on error. +The +.I read +function should update the stream offset appropriately. +.IP +If +.I *read +is a null pointer, +then reads from the custom stream always return end of file. +.TP +.I cookie_write_function_t *write +This function implements write operations for the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +ssize_t write(void *cookie, const char *buf, size_t size); +.EE +.in +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer of data to be output to the stream and the size of that buffer. +As its function result, the +.I write +function should return the number of bytes copied from +.IR buf , +or 0 on error. +(The function must not return a negative value.) +The +.I write +function should update the stream offset appropriately. +.IP +If +.I *write +is a null pointer, +then output to the stream is discarded. +.TP +.I cookie_seek_function_t *seek +This function implements seek operations on the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +int seek(void *cookie, off_t *offset, int whence); +.EE +.in +.IP +The +.I *offset +argument specifies the new file offset depending on which +of the following three values is supplied in +.IR whence : +.RS +.TP +.B SEEK_SET +The stream offset should be set +.I *offset +bytes from the start of the stream. +.TP +.B SEEK_CUR +.I *offset +should be added to the current stream offset. +.TP +.B SEEK_END +The stream offset should be set to the size of the stream plus +.IR *offset . +.RE +.IP +Before returning, the +.I seek +function should update +.I *offset +to indicate the new stream offset. +.IP +As its function result, the +.I seek +function should return 0 on success, and \-1 on error. +.IP +If +.I *seek +is a null pointer, +then it is not possible to perform seek operations on the stream. +.TP +.I cookie_close_function_t *close +This function closes the stream. +The hook function can do things such as freeing buffers allocated +for the stream. +When called, it receives one argument: +.IP +.in +4n +.EX +int close(void *cookie); +.EE +.in +.IP +The +.I cookie +argument is the cookie that the programmer supplied when calling +.BR fopencookie (). +.IP +As its function result, the +.I close +function should return 0 on success, and +.B EOF +on error. +.IP +If +.I *close +is NULL, then no special action is performed when the stream is closed. +.SH RETURN VALUE +On success +.BR fopencookie () +returns a pointer to the new stream. +On error, NULL is returned. +.\" .SH ERRORS +.\" It's not clear if errno ever gets set... +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fopencookie () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below implements a custom stream whose functionality +is similar (but not identical) to that available via +.BR fmemopen (3). +It implements a stream whose data is stored in a memory buffer. +The program writes its command-line arguments to the stream, +and then seeks through the stream reading two out of every +five characters and writing them to standard output. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]hello world\[aq]" +/he/ +/ w/ +/d/ +Reached end of file +.EE +.in +.P +Note that a more general version of the program below +could be improved to more robustly handle various error situations +(e.g., opening a stream with a cookie that already has an open stream; +closing a stream that has already been closed). +.SS Program source +\& +.\" SRC BEGIN (fopencookie.c) +.EX +#define _GNU_SOURCE +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/types.h> +#include <unistd.h> +\& +#define INIT_BUF_SIZE 4 +\& +struct memfile_cookie { + char *buf; /* Dynamically sized buffer for data */ + size_t allocated; /* Size of buf */ + size_t endpos; /* Number of characters in buf */ + off_t offset; /* Current file offset in buf */ +}; +\& +ssize_t +memfile_write(void *c, const char *buf, size_t size) +{ + char *new_buff; + struct memfile_cookie *cookie = c; +\& + /* Buffer too small? Keep doubling size until big enough. */ +\& + while (size + cookie\->offset > cookie\->allocated) { + new_buff = realloc(cookie\->buf, cookie\->allocated * 2); + if (new_buff == NULL) + return \-1; + cookie\->allocated *= 2; + cookie\->buf = new_buff; + } +\& + memcpy(cookie\->buf + cookie\->offset, buf, size); +\& + cookie\->offset += size; + if (cookie\->offset > cookie\->endpos) + cookie\->endpos = cookie\->offset; +\& + return size; +} +\& +ssize_t +memfile_read(void *c, char *buf, size_t size) +{ + ssize_t xbytes; + struct memfile_cookie *cookie = c; +\& + /* Fetch minimum of bytes requested and bytes available. */ +\& + xbytes = size; + if (cookie\->offset + size > cookie\->endpos) + xbytes = cookie\->endpos \- cookie\->offset; + if (xbytes < 0) /* offset may be past endpos */ + xbytes = 0; +\& + memcpy(buf, cookie\->buf + cookie\->offset, xbytes); +\& + cookie\->offset += xbytes; + return xbytes; +} +\& +int +memfile_seek(void *c, off_t *offset, int whence) +{ + off_t new_offset; + struct memfile_cookie *cookie = c; +\& + if (whence == SEEK_SET) + new_offset = *offset; + else if (whence == SEEK_END) + new_offset = cookie\->endpos + *offset; + else if (whence == SEEK_CUR) + new_offset = cookie\->offset + *offset; + else + return \-1; +\& + if (new_offset < 0) + return \-1; +\& + cookie\->offset = new_offset; + *offset = new_offset; + return 0; +} +\& +int +memfile_close(void *c) +{ + struct memfile_cookie *cookie = c; +\& + free(cookie\->buf); + cookie\->allocated = 0; + cookie\->buf = NULL; +\& + return 0; +} +\& +int +main(int argc, char *argv[]) +{ + cookie_io_functions_t memfile_func = { + .read = memfile_read, + .write = memfile_write, + .seek = memfile_seek, + .close = memfile_close + }; + FILE *stream; + struct memfile_cookie mycookie; + size_t nread; + char buf[1000]; +\& + /* Set up the cookie before calling fopencookie(). */ +\& + mycookie.buf = malloc(INIT_BUF_SIZE); + if (mycookie.buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + mycookie.allocated = INIT_BUF_SIZE; + mycookie.offset = 0; + mycookie.endpos = 0; +\& + stream = fopencookie(&mycookie, "w+", memfile_func); + if (stream == NULL) { + perror("fopencookie"); + exit(EXIT_FAILURE); + } +\& + /* Write command\-line arguments to our file. */ +\& + for (size_t j = 1; j < argc; j++) + if (fputs(argv[j], stream) == EOF) { + perror("fputs"); + exit(EXIT_FAILURE); + } +\& + /* Read two bytes out of every five, until EOF. */ +\& + for (long p = 0; ; p += 5) { + if (fseek(stream, p, SEEK_SET) == \-1) { + perror("fseek"); + exit(EXIT_FAILURE); + } + nread = fread(buf, 1, 2, stream); + if (nread == 0) { + if (ferror(stream) != 0) { + fprintf(stderr, "fread failed\en"); + exit(EXIT_FAILURE); + } + printf("Reached end of file\en"); + break; + } +\& + printf("/%.*s/\en", (int) nread, buf); + } +\& + free(mycookie.buf); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I seek +or that takes the address of +.BR fopencookie , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH SEE ALSO +.BR fclose (3), +.BR fmemopen (3), +.BR fopen (3), +.BR fseek (3) diff --git a/man/man3/forkpty.3 b/man/man3/forkpty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man/man3/forkpty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man/man3/fpathconf.3 b/man/man3/fpathconf.3 new file mode 100644 index 0000000..d879944 --- /dev/null +++ b/man/man3/fpathconf.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:26 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Probably all of the following should be documented: +.\" _PC_SYNC_IO, +.\" _PC_ASYNC_IO, +.\" _PC_PRIO_IO, +.\" _PC_SOCK_MAXBUF, +.\" _PC_FILESIZEBITS, +.\" _PC_REC_INCR_XFER_SIZE, +.\" _PC_REC_MAX_XFER_SIZE, +.\" _PC_REC_MIN_XFER_SIZE, +.\" _PC_REC_XFER_ALIGN, +.\" _PC_ALLOC_SIZE_MIN, +.\" _PC_SYMLINK_MAX, +.\" _PC_2_SYMLINKS +.\" +.TH fpathconf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpathconf, pathconf \- get configuration values for files +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "long fpathconf(int " fd ", int " name ); +.BI "long pathconf(const char *" path ", int " name ); +.fi +.SH DESCRIPTION +.BR fpathconf () +gets a value for the configuration option +.I name +for the open file descriptor +.IR fd . +.P +.BR pathconf () +gets a value for configuration option +.I name +for the filename +.IR path . +.P +The corresponding macros defined in +.I <unistd.h> +are minimum values; if an application wants to take advantage of values +which may change, a call to +.BR fpathconf () +or +.BR pathconf () +can be made, which may yield more liberal results. +.P +Setting +.I name +equal to one of the following constants returns the following +configuration options: +.TP +.B _PC_LINK_MAX +The maximum number of links to the file. +If +.I fd +or +.I path +refer to a directory, then the value applies to the whole directory. +The corresponding macro is +.BR _POSIX_LINK_MAX . +.TP +.B _PC_MAX_CANON +The maximum length of a formatted input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_CANON . +.TP +.B _PC_MAX_INPUT +The maximum length of an input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_INPUT . +.TP +.B _PC_NAME_MAX +The maximum length of a filename in the directory +.I path +or +.I fd +that the process is allowed to create. +The corresponding macro is +.BR _POSIX_NAME_MAX . +.TP +.B _PC_PATH_MAX +The maximum length of a relative pathname when +.I path +or +.I fd +is the current working directory. +The corresponding macro is +.BR _POSIX_PATH_MAX . +.TP +.B _PC_PIPE_BUF +The maximum number of bytes that can be written atomically to a pipe of FIFO. +For +.BR fpathconf (), +.I fd +should refer to a pipe or FIFO. +For +.BR fpathconf (), +.I path +should refer to a FIFO or a directory; in the latter case, +the returned value corresponds to FIFOs created in that directory. +The corresponding macro is +.BR _POSIX_PIPE_BUF . +.TP +.B _PC_CHOWN_RESTRICTED +This returns a positive value if the use of +.BR chown (2) +and +.BR fchown (2) +for changing a file's user ID is restricted to a process +with appropriate privileges, +and changing a file's group ID to a value other than the process's +effective group ID or one of its supplementary group IDs +is restricted to a process with appropriate privileges. +According to POSIX.1, +this variable shall always be defined with a value other than \-1. +The corresponding macro is +.BR _POSIX_CHOWN_RESTRICTED . +.IP +If +.I fd +or +.I path +refers to a directory, +then the return value applies to all files in that directory. +.TP +.B _PC_NO_TRUNC +This returns nonzero if accessing filenames longer than +.B _POSIX_NAME_MAX +generates an error. +The corresponding macro is +.BR _POSIX_NO_TRUNC . +.TP +.B _PC_VDISABLE +This returns nonzero if special character processing can be disabled, where +.I fd +or +.I path +must refer to a terminal. +.SH RETURN VALUE +The return value of these functions is one of the following: +.IP \[bu] 3 +On error, \-1 is returned and +.I errno +is set to indicate the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP \[bu] +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP \[bu] +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP \[bu] +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I <unistd.h> +or +.I <limits.h> +when the application was compiled. +.SH ERRORS +.TP +.B EACCES +.RB ( pathconf ()) +Search permission is denied for one of the directories in the path prefix of +.IR path . +.TP +.B EBADF +.RB ( fpathconf ()) +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I name +is invalid. +.TP +.B EINVAL +The implementation does not support an association of +.I name +with the specified file. +.TP +.B ELOOP +.RB ( pathconf ()) +Too many symbolic links were encountered while resolving +.IR path . +.TP +.B ENAMETOOLONG +.RB ( pathconf ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( pathconf ()) +A component of +.I path +does not exist, or +.I path +is an empty string. +.TP +.B ENOTDIR +.RB ( pathconf ()) +A component used as a directory in +.I path +is not in fact a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fpathconf (), +.BR pathconf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Files with name lengths longer than the value returned for +.I name +equal to +.B _PC_NAME_MAX +may exist in the given directory. +.P +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR getconf (1), +.BR open (2), +.BR statfs (2), +.BR confstr (3), +.BR sysconf (3) diff --git a/man/man3/fpclassify.3 b/man/man3/fpclassify.3 new file mode 100644 index 0000000..17a0fdd --- /dev/null +++ b/man/man3/fpclassify.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" This was done with the help of the glibc manual. +.\" +.\" 2004-10-31, aeb, corrected +.TH fpclassify 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpclassify, isfinite, isnormal, isnan, isinf \- floating-point +classification macros +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "int fpclassify(" x ); +.BI "int isfinite(" x ); +.BI "int isnormal(" x ); +.BI "int isnan(" x ); +.BI "int isinf(" x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.\" I haven't fully grokked the source to determine the FTM requirements; +.\" in part, the following has been tested by experiment. +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR isnan (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isinf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Floating point numbers can have special values, such as +infinite or NaN. +With the macro +.BI fpclassify( x ) +you can find out what type +.I x +is. +The macro takes any floating-point expression as argument. +The result is one of the following values: +.TP 14 +.B FP_NAN +.I x +is "Not a Number". +.TP +.B FP_INFINITE +.I x +is either positive infinity or negative infinity. +.TP +.B FP_ZERO +.I x +is zero. +.TP +.B FP_SUBNORMAL +.I x +is too small to be represented in normalized format. +.TP +.B FP_NORMAL +if nothing of the above is correct then it must be a +normal floating-point number. +.P +The other macros provide a short answer to some standard questions. +.TP 14 +.BI isfinite( x ) +returns a nonzero value if +.br +(fpclassify(x) != FP_NAN && fpclassify(x) != FP_INFINITE) +.TP +.BI isnormal( x ) +returns a nonzero value if +(fpclassify(x) == FP_NORMAL) +.TP +.BI isnan( x ) +returns a nonzero value if +(fpclassify(x) == FP_NAN) +.TP +.BI isinf( x ) +returns 1 if +.I x +is positive infinity, and \-1 if +.I x +is negative infinity. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (), +.BR isnan (), +.BR isinf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.P +In glibc 2.01 and earlier, +.BR isinf () +returns a nonzero value (actually: 1) if +.I x +is positive infinity or negative infinity. +(This is all that C99 requires.) +.SH NOTES +For +.BR isinf (), +the standards merely say that the return value is nonzero +if and only if the argument has an infinite value. +.SH SEE ALSO +.BR finite (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR signbit (3) diff --git a/man/man3/fprintf.3 b/man/man3/fprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/fprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/fpurge.3 b/man/man3/fpurge.3 new file mode 100644 index 0000000..4057c90 --- /dev/null +++ b/man/man3/fpurge.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fpurge 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpurge, __fpurge \- purge a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +/* unsupported */ +.B #include <stdio.h> +.P +.BI "int fpurge(FILE *" stream ); +.P +/* supported */ +.B #include <stdio.h> +.B #include <stdio_ext.h> +.P +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR fpurge () +clears the buffers of the given stream. +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.BR getc (3); +this includes any text pushed back via +.BR ungetc (3). +See also +.BR fflush (3). +.P +The function +.BR __fpurge () +does precisely the same, but without returning a value. +.SH RETURN VALUE +Upon successful completion +.BR fpurge () +returns 0. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __fpurge () +T} Thread safety MT-Safe race:stream +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR fpurge () +4.4BSD. +Not available under Linux. +.TP +.BR __fpurge () +Solaris, glibc 2.1.95. +.SH NOTES +Usually it is a mistake to want to discard input buffers. +.SH SEE ALSO +.\" .BR fclean (3), +.BR fflush (3), +.BR setbuf (3), +.BR stdio_ext (3) diff --git a/man/man3/fputc.3 b/man/man3/fputc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/fputc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/fputc_unlocked.3 b/man/man3/fputc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputs.3 b/man/man3/fputs.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/fputs.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/fputs_unlocked.3 b/man/man3/fputs_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputs_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputwc.3 b/man/man3/fputwc.3 new file mode 100644 index 0000000..cdac37d --- /dev/null +++ b/man/man3/fputwc.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fputwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputwc, putwc \- write a wide character to a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <wchar.h> +.P +.BI "wint_t fputwc(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc(wchar_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fputwc () +function is the wide-character +equivalent of the +.BR fputc (3) +function. +It writes the wide character \fIwc\fP to \fIstream\fP. +If +\fIferror(stream)\fP becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +Otherwise, it returns \fIwc\fP. +.P +The +.BR putwc () +function or macro functions identically to +.BR fputwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fputwc () +function returns +.IR wc . +Otherwise, +.B WEOF +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +Conversion of \fIwc\fP to the stream's encoding fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputwc (), +.BR putwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR fputwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputwc () +will actually write the multibyte +sequence corresponding to the wide character \fIwc\fP. +.SH SEE ALSO +.BR fgetwc (3), +.BR fputws (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fputwc_unlocked.3 b/man/man3/fputwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputws.3 b/man/man3/fputws.3 new file mode 100644 index 0000000..62b3425 --- /dev/null +++ b/man/man3/fputws.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fputws 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputws \- write a wide-character string to a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int fputws(const wchar_t *restrict " ws ", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR fputws () +function is the wide-character equivalent of +the +.BR fputs (3) +function. +It writes the wide-character string starting at \fIws\fP, +up to but not including the terminating null wide character (L\[aq]\e0\[aq]), +to \fIstream\fP. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fputws () +function returns a +nonnegative integer if the operation was +successful, or \-1 to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputws () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fputws () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputws () +will actually write the multibyte +string corresponding to the wide-character string \fIws\fP. +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fputws_unlocked.3 b/man/man3/fputws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fread.3 b/man/man3/fread.3 new file mode 100644 index 0000000..0deecd4 --- /dev/null +++ b/man/man3/fread.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (c) 2020 Arkadiusz Drabczyk <arkadiusz@drabczyk.org> +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fread.3 6.6 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu +.\" Sun Feb 19 21:26:54 1995 by faith, return values +.\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Modified Fri May 17 10:21:51 1996 by Martin Schulze <joey@infodrom.north.de> +.\" +.TH fread 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fread, fwrite \- binary stream input/output +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ], +.BI " size_t " size ", size_t " nmemb , +.BI " FILE *restrict " stream ); +.BI "size_t fwrite(const void " ptr "[restrict ." size " * ." nmemb ], +.BI " size_t " size ", size_t " nmemb , +.BI " FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The function +.BR fread () +reads +.I nmemb +items of data, each +.I size +bytes long, from the stream pointed to by +.IR stream , +storing them at the location given by +.IR ptr . +.P +The function +.BR fwrite () +writes +.I nmemb +items of data, each +.I size +bytes long, to the stream pointed to by +.IR stream , +obtaining them from the location given by +.IR ptr . +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fread () +and +.BR fwrite () +return the number of items read or written. +This number equals the number of bytes transferred only when +.I size +is 1. +If an error occurs, or the end of the file is reached, +the return value is a short item count (or zero). +.P +The file position indicator for the stream is advanced by the number +of bytes successfully read or written. +.P +.BR fread () +does not distinguish between end-of-file and error, and callers must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fread (), +.BR fwrite () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH EXAMPLES +The program below demonstrates the use of +.BR fread () +by parsing /bin/sh ELF executable in binary mode and printing its +magic and class: +.P +.in +4n +.EX +$ \fB./a.out\fP +ELF magic: 0x7f454c46 +Class: 0x02 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (fread.c) +.EX +#include <stdio.h> +#include <stdlib.h> +\& +#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) +\& +int +main(void) +{ + FILE *fp; + size_t ret; + unsigned char buffer[4]; +\& + fp = fopen("/bin/sh", "rb"); + if (!fp) { + perror("fopen"); + return EXIT_FAILURE; + } +\& + ret = fread(buffer, sizeof(*buffer), ARRAY_SIZE(buffer), fp); + if (ret != ARRAY_SIZE(buffer)) { + fprintf(stderr, "fread() failed: %zu\en", ret); + exit(EXIT_FAILURE); + } +\& + printf("ELF magic: %#04x%02x%02x%02x\en", buffer[0], buffer[1], + buffer[2], buffer[3]); +\& + ret = fread(buffer, 1, 1, fp); + if (ret != 1) { + fprintf(stderr, "fread() failed: %zu\en", ret); + exit(EXIT_FAILURE); + } +\& + printf("Class: %#04x\en", buffer[0]); +\& + fclose(fp); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR feof (3), +.BR ferror (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fread_unlocked.3 b/man/man3/fread_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fread_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/free.3 b/man/man3/free.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/free.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/freeaddrinfo.3 b/man/man3/freeaddrinfo.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man/man3/freeaddrinfo.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man/man3/freehostent.3 b/man/man3/freehostent.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man/man3/freehostent.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man/man3/freeifaddrs.3 b/man/man3/freeifaddrs.3 new file mode 100644 index 0000000..38f977d --- /dev/null +++ b/man/man3/freeifaddrs.3 @@ -0,0 +1 @@ +.so man3/getifaddrs.3 diff --git a/man/man3/freelocale.3 b/man/man3/freelocale.3 new file mode 100644 index 0000000..a4246c5 --- /dev/null +++ b/man/man3/freelocale.3 @@ -0,0 +1 @@ +.so man3/newlocale.3 diff --git a/man/man3/freopen.3 b/man/man3/freopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man/man3/freopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man/man3/frexp.3 b/man/man3/frexp.3 new file mode 100644 index 0000000..3d357c9 --- /dev/null +++ b/man/man3/frexp.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH frexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +frexp, frexpf, frexpl \- convert floating-point number to fractional +and integral components +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double frexp(double " x ", int *" exp ); +.BI "float frexpf(float " x ", int *" exp ); +.BI "long double frexpl(long double " x ", int *" exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR frexpf (), +.BR frexpl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions are used to split the number +.I x +into a +normalized fraction and an exponent which is stored in +.IR exp . +.SH RETURN VALUE +These functions return the normalized fraction. +If the argument +.I x +is not zero, +the normalized fraction is +.I x +times a power of two, +and its absolute value is always in the range 1/2 (inclusive) to +1 (exclusive), that is, [0.5,1). +.P +If +.I x +is zero, then the normalized fraction is +zero and zero is stored in +.IR exp . +.P +If +.I x +is a NaN, +a NaN is returned, and the value of +.I *exp +is unspecified. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned, and the value of +.I *exp +is unspecified. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR frexp (), +.BR frexpf (), +.BR frexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH EXAMPLES +The program below produces results such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 2560" +frexp(2560, &e) = 0.625: 0.625 * 2\[ha]12 = 2560 +.RB "$" " ./a.out \-4" +frexp(\-4, &e) = \-0.5: \-0.5 * 2\[ha]3 = \-4 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (frexp.c) +.EX +#include <float.h> +#include <math.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + double x, r; + int exp; +\& + x = strtod(argv[1], NULL); + r = frexp(x, &exp); +\& + printf("frexp(%g, &e) = %g: %g * %d\[ha]%d = %g\en", x, r, r, 2, exp, x); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldexp (3), +.BR modf (3) diff --git a/man/man3/frexpf.3 b/man/man3/frexpf.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man/man3/frexpf.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man/man3/frexpl.3 b/man/man3/frexpl.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man/man3/frexpl.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man/man3/fscanf.3 b/man/man3/fscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/fscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/fseek.3 b/man/man3/fseek.3 new file mode 100644 index 0000000..89948f0 --- /dev/null +++ b/man/man3/fseek.3 @@ -0,0 +1,177 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fseek.3 6.11 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.TH fseek 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fseek(FILE *" stream ", long " offset ", int " whence ); +.BI "long ftell(FILE *" stream ); +.P +.BI "void rewind(FILE *" stream ); +.P +.BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos ); +.BI "int fsetpos(FILE *" stream ", const fpos_t *" pos ); +.fi +.SH DESCRIPTION +The +.BR fseek () +function sets the file position indicator for the stream pointed to by +.IR stream . +The new position, measured in bytes, is obtained by adding +.I offset +bytes to the position specified by +.IR whence . +If +.I whence +is set to +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +the offset is relative to the start of the file, the current position +indicator, or end-of-file, respectively. +A successful call to the +.BR fseek () +function clears the end-of-file indicator for the stream and undoes +any effects of the +.BR ungetc (3) +function on the same stream. +.P +The +.BR ftell () +function obtains the current value of the file position indicator for the +stream pointed to by +.IR stream . +.P +The +.BR rewind () +function sets the file position indicator for the stream pointed to by +.I stream +to the beginning of the file. +It is equivalent to: +.P +.RS +(void) fseek(stream, 0L, SEEK_SET) +.RE +.P +except that the error indicator for the stream is also cleared (see +.BR clearerr (3)). +.P +The +.BR fgetpos () +and +.BR fsetpos () +functions are alternate interfaces equivalent to +.BR ftell () +and +.BR fseek () +(with +.I whence +set to +.BR SEEK_SET ), +setting and storing the current value of the file offset into or from the +object referenced by +.IR pos . +On some non-UNIX systems, an +.I fpos_t +object may be a complex object and these routines may be the only way to +portably reposition a text stream. +.P +If the stream refers to a regular file +and the resulting stream offset is beyond the size of the file, +subsequent writes will extend the file with a hole, up to the offset, +before committing any data. +See +.BR lseek (2) +for details on file seeking semantics. +.SH RETURN VALUE +The +.BR rewind () +function returns no value. +Upon successful completion, +.BR fgetpos (), +.BR fseek (), +.BR fsetpos () +return 0, +and +.BR ftell () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I whence +argument to +.BR fseek () +was not +.BR SEEK_SET , +.BR SEEK_END , +or +.BR SEEK_CUR . +Or: the resulting file offset would be negative. +.TP +.B ESPIPE +The file descriptor underlying +.I stream +is not seekable (e.g., it refers to a pipe, FIFO, or socket). +.P +The functions +.BR fgetpos (), +.BR fseek (), +.BR fsetpos (), +and +.BR ftell () +may also fail and set +.I errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR lseek (2), +and +.BR malloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fseek (), +.BR ftell (), +.BR rewind (), +.BR fgetpos (), +.BR fsetpos () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH SEE ALSO +.BR lseek (2), +.BR fseeko (3) diff --git a/man/man3/fseeko.3 b/man/man3/fseeko.3 new file mode 100644 index 0000000..e108ec7 --- /dev/null +++ b/man/man3/fseeko.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fseeko 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fseeko, ftello \- seek to or report file position +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); +.BI "off_t ftello(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fseeko (), +.BR ftello (): +.nf + _FILE_OFFSET_BITS == 64 || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR fseeko () +and +.BR ftello () +functions are identical to +.BR fseek (3) +and +.BR ftell (3) +(see +.BR fseek (3)), +respectively, except that the +.I offset +argument of +.BR fseeko () +and the return value of +.BR ftello () +is of type +.I off_t +instead of +.IR long . +.P +On some architectures, both +.I off_t +and +.I long +are 32-bit types, but defining +.B _FILE_OFFSET_BITS +with the value 64 (before including +.I any +header files) +will turn +.I off_t +into a 64-bit type. +.SH RETURN VALUE +On successful completion, +.BR fseeko () +returns 0, while +.BR ftello () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +See the ERRORS in +.BR fseek (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fseeko (), +.BR ftello () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001, SUSv2. +.SH NOTES +The declarations of these functions can also be obtained by defining +the obsolete +.B _LARGEFILE_SOURCE +feature test macro. +.SH SEE ALSO +.BR fseek (3) diff --git a/man/man3/fsetpos.3 b/man/man3/fsetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/fsetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/fstatvfs.3 b/man/man3/fstatvfs.3 new file mode 100644 index 0000000..adec9dd --- /dev/null +++ b/man/man3/fstatvfs.3 @@ -0,0 +1 @@ +.so man3/statvfs.3 diff --git a/man/man3/ftell.3 b/man/man3/ftell.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/ftell.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/ftello.3 b/man/man3/ftello.3 new file mode 100644 index 0000000..d5628f4 --- /dev/null +++ b/man/man3/ftello.3 @@ -0,0 +1 @@ +.so man3/fseeko.3 diff --git a/man/man3/ftime.3 b/man/man3/ftime.3 new file mode 100644 index 0000000..0c4a22e --- /dev/null +++ b/man/man3/ftime.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 14:23:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Oct 18 17:31:43 1998 by Andries Brouwer (aeb@cwi.nl) +.\" 2008-06-23, mtk, minor rewrites, added some details +.\" +.TH ftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftime \- return date and time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <sys/timeb.h>" +.P +.BI "int ftime(struct timeb *" tp ); +.fi +.SH DESCRIPTION +.BR NOTE : +This function is no longer provided by the GNU C library. +Use +.BR clock_gettime (2) +instead. +.P +This function returns the current time as seconds and milliseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +The time is returned in +.IR tp , +which is declared as follows: +.P +.in +4n +.EX +struct timeb { + time_t time; + unsigned short millitm; + short timezone; + short dstflag; +}; +.EE +.in +.P +Here \fItime\fP is the number of seconds since the Epoch, +and \fImillitm\fP is the number of milliseconds since \fItime\fP +seconds since the Epoch. +The \fItimezone\fP field is the local timezone measured in minutes +of time west of Greenwich (with a negative value indicating minutes +east of Greenwich). +The \fIdstflag\fP field +is a flag that, if nonzero, indicates that Daylight Saving time +applies locally during the appropriate part of the year. +.P +POSIX.1-2001 says that the contents of the \fItimezone\fP and \fIdstflag\fP +fields are unspecified; avoid relying on them. +.SH RETURN VALUE +This function always returns 0. +(POSIX.1-2001 specifies, and some systems document, a \-1 error return.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ftime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +Removed in glibc 2.33. +4.2BSD, POSIX.1-2001. +Removed in POSIX.1-2008. +.P +This function is obsolete. +Don't use it. +If the time in seconds +suffices, +.BR time (2) +can be used; +.BR gettimeofday (2) +gives microseconds; +.BR clock_gettime (2) +gives nanoseconds but is not as widely available. +.SH BUGS +Early glibc2 is buggy and returns 0 in the +.I millitm +field; +glibc 2.1.1 is correct again. +.\" .SH HISTORY +.\" The +.\" .BR ftime () +.\" function appeared in 4.2BSD. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (2) diff --git a/man/man3/ftok.3 b/man/man3/ftok.3 new file mode 100644 index 0000000..b8df38d --- /dev/null +++ b/man/man3/ftok.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2001-11-28, by Michael Kerrisk, <mtk.manpages@gmail.com> +.\" Changed data type of proj_id; minor fixes +.\" aeb: further fixes; added notes. +.\" +.TH ftok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftok \- convert a pathname and a project identifier to a System V IPC key +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/ipc.h> +.fi +.P +.BI "key_t ftok(const char *" pathname ", int " proj_id ); +.SH DESCRIPTION +The +.BR ftok () +function uses the identity of the file named by the given +.I pathname +(which must refer to an existing, accessible file) +and the least significant 8 bits of +.I proj_id +(which must be nonzero) to generate a +.I key_t +type System V IPC key, suitable for use with +.BR msgget (2), +.BR semget (2), +or +.BR shmget (2). +.P +The resulting value is the same for all pathnames that +name the same file, when the same value of +.I proj_id +is used. +The value returned should be different when the +(simultaneously existing) files or the project IDs differ. +.SH RETURN VALUE +On success, the generated +.I key_t +value is returned. +On failure \-1 is returned, with +.I errno +indicating the error as for the +.BR stat (2) +system call. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ftok () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +On some ancient systems, the prototype was: +.P +.in +4n +.EX +.BI "key_t ftok(char *" pathname ", char " proj_id ); +.EE +.in +.P +Today, +.I proj_id +is an +.IR int , +but still only 8 bits are used. +Typical usage has an ASCII character +.IR proj_id , +that is why the behavior is said to be undefined when +.I proj_id +is zero. +.P +Of course, no guarantee can be given that the resulting +.I key_t +is unique. +Typically, a best-effort attempt combines the given +.I proj_id +byte, the lower 16 bits of the inode number, and the +lower 8 bits of the device number into a 32-bit result. +Collisions may easily happen, for example between files on +.I /dev/hda1 +and files on +.IR /dev/sda1 . +.SH EXAMPLES +See +.BR semget (2). +.SH SEE ALSO +.BR msgget (2), +.BR semget (2), +.BR shmget (2), +.BR stat (2), +.BR sysvipc (7) diff --git a/man/man3/ftrylockfile.3 b/man/man3/ftrylockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man/man3/ftrylockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man/man3/fts.3 b/man/man3/fts.3 new file mode 100644 index 0000000..6a8b922 --- /dev/null +++ b/man/man3/fts.3 @@ -0,0 +1,826 @@ +'\" t +.\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH fts 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \ +traverse a file hierarchy +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.B #include <fts.h> +.P +.BI "FTS *fts_open(char *const *" path_argv ", int " options , +.BI " int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));" +.P +.BI "FTSENT *fts_read(FTS *" ftsp ); +.P +.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr ); +.P +.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr ); +.P +.BI "int fts_close(FTS *" ftsp ); +.fi +.SH DESCRIPTION +The +fts functions are provided for traversing +file hierarchies. +A simple overview is that the +.BR fts_open () +function returns a "handle" (of type +.IR "FTS\ *" ) +that refers to a file hierarchy "stream". +This handle is then supplied to the other +fts functions. +The function +.BR fts_read () +returns a pointer to a structure describing one of the files in the file +hierarchy. +The function +.BR fts_children () +returns a pointer to a linked list of structures, each of which describes +one of the files contained in a directory in the hierarchy. +.P +In general, directories are visited two distinguishable times; in preorder +(before any of their descendants are visited) and in postorder (after all +of their descendants have been visited). +Files are visited once. +It is possible to walk the hierarchy "logically" (visiting the files that +symbolic links point to) +or physically (visiting the symbolic links themselves), +order the walk of the hierarchy or +prune and/or revisit portions of the hierarchy. +.P +Two structures (and associated types) are defined in the include file +.IR <fts.h> . +The first type is +.IR FTS , +the structure that represents the file hierarchy itself. +The second type is +.IR FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.I FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, "file" and +"FTSENT structure" +are generally interchangeable. +.P +The +.I FTSENT +structure contains fields describing a file. +The structure contains at least the following fields +(there are additional fields that +should be considered private to the implementation): +.P +.in +4n +.EX +typedef struct _ftsent { + unsigned short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + short fts_pathlen; /* strlen(fts_path) + + strlen(fts_name) */ + char *fts_name; /* filename */ + short fts_namelen; /* strlen(fts_name) */ + short fts_level; /* depth (\-1 to N) */ + int fts_errno; /* file errno */ + long fts_number; /* local numeric value */ + void *fts_pointer; /* local address value */ + struct _ftsent *fts_parent; /* parent directory */ + struct _ftsent *fts_link; /* next file structure */ + struct _ftsent *fts_cycle; /* cycle structure */ + struct stat *fts_statp; /* [l]stat(2) information */ +.\" Also: +.\" ino_t fts_ino; /* inode (only for directories)*/ +.\" dev_t fts_dev; /* device (only for directories)*/ +.\" nlink_t fts_nlink; /* link count (only for directories)*/ +.\" u_short fts_flags; /* private flags for FTSENT structure */ +.\" u_short fts_instr; /* fts_set() instructions */ +} FTSENT; +.EE +.in +.P +These fields are defined as follows: +.\" .Bl -tag -width "fts_namelen" +.TP +.I fts_info +One of the following values describing the returned +.I FTSENT +structure and +the file it represents. +With the exception of directories without errors +.RB ( FTS_D ), +all of these +entries are terminal, that is, they will not be revisited, nor will any +of their descendants be visited. +.\" .Bl -tag -width FTS_DEFAULT +.RS +.TP +.B FTS_D +A directory being visited in preorder. +.TP +.B FTS_DC +A directory that causes a cycle in the tree. +(The +.I fts_cycle +field of the +.I FTSENT +structure will be filled in as well.) +.TP +.B FTS_DEFAULT +Any +.I FTSENT +structure that represents a file type not explicitly described +by one of the other +.I fts_info +values. +.TP +.B FTS_DNR +A directory which cannot be read. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_DOT +A file named +"." +or +".." +which was not specified as a filename to +.BR fts_open () +(see +.BR FTS_SEEDOT ). +.TP +.B FTS_DP +A directory being visited in postorder. +The contents of the +.I FTSENT +structure will be unchanged from when +it was returned in preorder, that is, with the +.I fts_info +field set to +.BR FTS_D . +.TP +.B FTS_ERR +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_F +A regular file. +.TP +.B FTS_NS +A file for which no +.RB [ l ]\c +.BR stat (2) +information was available. +The contents of the +.I fts_statp +field are undefined. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_NSOK +A file for which no +.RB [ l ]\c +.BR stat (2) +information was requested. +The contents of the +.I fts_statp +field are undefined. +.TP +.B FTS_SL +A symbolic link. +.TP +.B FTS_SLNONE +A symbolic link with a nonexistent target. +The contents of the +.I fts_statp +field reference the file characteristic information for the symbolic link +itself. +.\" .El +.RE +.TP +.I fts_accpath +A path for accessing the file from the current directory. +.TP +.I fts_path +The path for the file relative to the root of the traversal. +This path contains the path specified to +.BR fts_open () +as a prefix. +.TP +.I fts_pathlen +The sum of the lengths of the strings referenced by +.I fts_path +and +.IR fts_name . +.TP +.I fts_name +The name of the file. +.TP +.I fts_namelen +The length of the string referenced by +.IR fts_name . +.TP +.I fts_level +The depth of the traversal, numbered from \-1 to N, where this file +was found. +The +.I FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered \-1, and the +.I FTSENT +structure for the root +itself is numbered 0. +.TP +.I fts_errno +If +.BR fts_children () +or +.BR fts_read () +returns an +.I FTSENT +structure whose +.I fts_info +field is set to +.BR FTS_DNR , +.BR FTS_ERR , +or +.BR FTS_NS , +the +.I fts_errno +field contains the error number (i.e., the +.I errno +value) +specifying the cause of the error. +Otherwise, the contents of the +.I fts_errno +field are undefined. +.TP +.I fts_number +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to 0. +.TP +.I fts_pointer +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to +NULL. +.TP +.I fts_parent +A pointer to the +.I FTSENT +structure referencing the file in the hierarchy +immediately above the current file, that is, the directory of which this +file is a member. +A parent structure for the initial entry point is provided as well, +however, only the +.IR fts_level , +.IR fts_number , +and +.I fts_pointer +fields are guaranteed to be initialized. +.TP +.I fts_link +Upon return from the +.BR fts_children () +function, the +.I fts_link +field points to the next structure in the NULL-terminated linked list of +directory members. +Otherwise, the contents of the +.I fts_link +field are undefined. +.TP +.I fts_cycle +If a directory causes a cycle in the hierarchy (see +.BR FTS_DC ), +either because +of a hard link between two directories, or a symbolic link pointing to a +directory, the +.I fts_cycle +field of the structure will point to the +.I FTSENT +structure in the hierarchy that references the same file as the current +.I FTSENT +structure. +Otherwise, the contents of the +.I fts_cycle +field are undefined. +.TP +.I fts_statp +A pointer to +.RB [ l ]\c +.BR stat (2) +information for the file. +.\" .El +.P +A single buffer is used for all of the paths of all of the files in the +file hierarchy. +Therefore, the +.I fts_path +and +.I fts_accpath +fields are guaranteed to be +null-terminated +.I only +for the file most recently returned by +.BR fts_read (). +To use these fields to reference any files represented by other +.I FTSENT +structures will require that the path buffer be modified using the +information contained in that +.I FTSENT +structure's +.I fts_pathlen +field. +Any such modifications should be undone before further calls to +.BR fts_read () +are attempted. +The +.I fts_name +field is always +null-terminated. +.SS fts_open() +The +.BR fts_open () +function takes a pointer to an array of character pointers naming one +or more paths which make up a logical file hierarchy to be traversed. +The array must be terminated by a +null pointer. +.P +There are +a number of options, at least one of which (either +.B FTS_LOGICAL +or +.BR FTS_PHYSICAL ) +must be specified. +The options are selected by ORing +the following values: +.\" .Bl -tag -width "FTS_PHYSICAL" +.TP +.B FTS_LOGICAL +This option causes the +fts routines to return +.I FTSENT +structures for the targets of symbolic links +instead of the symbolic links themselves. +If this option is set, the only symbolic links for which +.I FTSENT +structures +are returned to the application are those referencing nonexistent files: +the +.I fts_statp +field is obtained via +.BR stat (2) +with a fallback to +.BR lstat (2). +.TP +.B FTS_PHYSICAL +This option causes the +fts routines to return +.I FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.I FTSENT +structures for all symbolic links in the +hierarchy are returned to the application: +the +.I fts_statp +field is obtained via +.BR lstat (2). +.TP +.B FTS_COMFOLLOW +This option causes any symbolic link specified as a root path to be +followed immediately, as if via +.BR FTS_LOGICAL , +regardless of the primary mode. +.TP +.B FTS_NOCHDIR +As a performance optimization, the +fts functions change directories as they walk the file hierarchy. +This has the side-effect that an application cannot rely on being +in any particular directory during the traversal. +This +option turns off this optimization, and the +fts functions will not change the current directory. +Note that applications should not themselves change their current directory +and try to access files unless +.B FTS_NOCHDIR +is specified and absolute +pathnames were provided as arguments to +.BR fts_open (). +.TP +.B FTS_NOSTAT +By default, returned +.I FTSENT +structures reference file characteristic information (the +.I fts_statp +field) for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the +fts functions to set the +.I fts_info +field to +.B FTS_NSOK +and leave the contents of the +.I fts_statp +field undefined. +.TP +.B FTS_SEEDOT +By default, unless they are specified as path arguments to +.BR fts_open (), +any files named +"." +or +".." +encountered in the file hierarchy are ignored. +This option causes the +fts routines to return +.I FTSENT +structures for them. +.TP +.B FTS_XDEV +This option prevents +fts from descending into directories that have a different device number +than the file from which the descent began. +.\" .El +.P +The argument +.BR compar () +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.I FTSENT +structures as arguments and +should return a negative value, zero, or a positive value to indicate +if the file referenced by its first argument comes before, in any order +with respect to, or after, the file referenced by its second argument. +The +.IR fts_accpath , +.IR fts_path , +and +.I fts_pathlen +fields of the +.I FTSENT +structures may +.I never +be used in this comparison. +If the +.I fts_info +field is set to +.B FTS_NS +or +.BR FTS_NSOK , +the +.I fts_statp +field may not either. +If the +.BR compar () +argument is +NULL, +the directory traversal order is in the order listed in +.I path_argv +for the root paths, and in the order listed in the directory for +everything else. +.SS fts_read() +The +.BR fts_read () +function returns a pointer to an +.I FTSENT +structure describing a file in +the hierarchy. +Directories (that are readable and do not cause cycles) are visited at +least twice, once in preorder and once in postorder. +All other files are visited at least once. +(Hard links between directories that do not cause cycles or symbolic +links to symbolic links may cause files to be visited more than once, +or directories more than twice.) +.P +If all the members of the hierarchy have been returned, +.BR fts_read () +returns NULL and sets +.I errno +to 0. +If an error unrelated to a file in the hierarchy occurs, +.BR fts_read () +returns +NULL +and sets +.I errno +to indicate the error. +If an error related to a returned file occurs, a pointer to an +.I FTSENT +structure is returned, and +.I errno +may or may not have been set (see +.IR fts_info ). +.P +The +.I FTSENT +structures returned by +.BR fts_read () +may be overwritten after a call to +.BR fts_close () +on the same file hierarchy stream, or, after a call to +.BR fts_read () +on the same file hierarchy stream unless they represent a file of type +directory, in which case they will not be overwritten until after a call to +.BR fts_read () +after the +.I FTSENT +structure has been returned by the function +.BR fts_read () +in postorder. +.SS fts_children() +The +.BR fts_children () +function returns a pointer to an +.I FTSENT +structure describing the first entry in a NULL-terminated linked list of +the files in the directory represented by the +.I FTSENT +structure most recently returned by +.BR fts_read (). +The list is linked through the +.I fts_link +field of the +.I FTSENT +structure, and is ordered by the user-specified comparison function, if any. +Repeated calls to +.BR fts_children () +will re-create this linked list. +.P +As a special case, if +.BR fts_read () +has not yet been called for a hierarchy, +.BR fts_children () +will return a pointer to the files in the logical directory specified to +.BR fts_open (), +that is, the arguments specified to +.BR fts_open (). +Otherwise, if the +.I FTSENT +structure most recently returned by +.BR fts_read () +is not a directory being visited in preorder, +or the directory does not contain any files, +.BR fts_children () +returns +NULL +and sets +.I errno +to zero. +If an error occurs, +.BR fts_children () +returns +NULL +and sets +.I errno +to indicate the error. +.P +The +.I FTSENT +structures returned by +.BR fts_children () +may be overwritten after a call to +.BR fts_children (), +.BR fts_close (), +or +.BR fts_read () +on the same file hierarchy stream. +.P +The +.I instr +argument is either zero or the following value: +.\" .Bl -tag -width FTS_NAMEONLY +.TP +.B FTS_NAMEONLY +Only the names of the files are needed. +The contents of all the fields in the returned linked list of structures +are undefined with the exception of the +.I fts_name +and +.I fts_namelen +fields. +.\" .El +.SS fts_set() +The function +.BR fts_set () +allows the user application to determine further processing for the +file +.I f +of the stream +.IR ftsp . +The +.BR fts_set () +function +returns 0 on success, and \-1 if an error occurs. +.P +The +.I instr +argument is either 0 (meaning "do nothing") or one of the following values: +.\" .Bl -tag -width FTS_PHYSICAL +.TP +.B FTS_AGAIN +Revisit the file; any file type may be revisited. +The next call to +.BR fts_read () +will return the referenced file. +The +.I fts_stat +and +.I fts_info +fields of the structure will be reinitialized at that time, +but no other fields will have been changed. +This option is meaningful only for the most recently returned +file from +.BR fts_read (). +Normal use is for postorder directory visits, where it causes the +directory to be revisited (in both preorder and postorder) as well as all +of its descendants. +.TP +.B FTS_FOLLOW +The referenced file must be a symbolic link. +If the referenced file is the one most recently returned by +.BR fts_read (), +the next call to +.BR fts_read () +returns the file with the +.I fts_info +and +.I fts_statp +fields reinitialized to reflect the target of the symbolic link instead +of the symbolic link itself. +If the file is one of those most recently returned by +.BR fts_children (), +the +.I fts_info +and +.I fts_statp +fields of the structure, when returned by +.BR fts_read (), +will reflect the target of the symbolic link instead of the symbolic link +itself. +In either case, if the target of the symbolic link does not exist, the +fields of the returned structure will be unchanged and the +.I fts_info +field will be set to +.BR FTS_SLNONE . +.IP +If the target of the link is a directory, the preorder return, followed +by the return of all of its descendants, followed by a postorder return, +is done. +.TP +.B FTS_SKIP +No descendants of this file are visited. +The file may be one of those most recently returned by either +.BR fts_children () +or +.BR fts_read (). +.\" .El +.SS fts_close() +The +.BR fts_close () +function closes the file hierarchy stream referred to by +.I ftsp +and restores the current directory to the directory from which +.BR fts_open () +was called to open +.IR ftsp . +The +.BR fts_close () +function +returns 0 on success, and \-1 if an error occurs. +.SH ERRORS +The function +.BR fts_open () +may fail and set +.I errno +for any of the errors specified for +.BR open (2) +and +.BR malloc (3). +.P +In addition, +.BR fts_open () +may fail and set +.I errno +as follows: +.TP +.B ENOENT +Any element of +.I path_argv +was an empty string. +.P +The function +.BR fts_close () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2) +and +.BR close (2). +.P +The functions +.BR fts_read () +and +.BR fts_children () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +and +.RB [ l ]\c +.BR stat (2). +.P +In addition, +.BR fts_children (), +.BR fts_open (), +and +.BR fts_set () +may fail and set +.I errno +as follows: +.TP +.B EINVAL +.I options +or +.I instr +was invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fts_open (), +.BR fts_set (), +.BR fts_close () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR fts_read (), +.BR fts_children () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2. +4.4BSD. +.SH BUGS +Before glibc 2.23, +.\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460 +all of the APIs described in this man page are not safe when compiling +a program using the LFS APIs (e.g., when compiling with +.IR \-D_FILE_OFFSET_BITS=64 ). +.\" +.\" The following statement is years old, and seems no closer to +.\" being true -- mtk +.\" The +.\" .I fts +.\" utility is expected to be included in a future +.\" POSIX.1 +.\" revision. +.SH SEE ALSO +.BR find (1), +.BR chdir (2), +.BR lstat (2), +.BR stat (2), +.BR ftw (3), +.BR qsort (3) diff --git a/man/man3/fts_children.3 b/man/man3/fts_children.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_children.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_close.3 b/man/man3/fts_close.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_close.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_open.3 b/man/man3/fts_open.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_open.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_read.3 b/man/man3/fts_read.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_read.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_set.3 b/man/man3/fts_set.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_set.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/ftw.3 b/man/man3/ftw.3 new file mode 100644 index 0000000..41fd4dc --- /dev/null +++ b/man/man3/ftw.3 @@ -0,0 +1,502 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net> +.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> +.\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; +.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and +.\" Michael Kerrisk <mtk.manpages@gmail.com> +.\" reorganized and rewrote much of the page +.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added an example program. +.\" +.TH ftw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftw, nftw \- file tree walk +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ftw.h> +.P +.BI "int nftw(const char *" dirpath , +.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ", struct FTW *" ftwbuf ), +.BI " int " nopenfd ", int " flags ); +.P +.B [[deprecated]] +.BI "int ftw(const char *" dirpath , +.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ), +.BI " int " nopenfd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nftw (): +.nf + _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +.BR nftw () +walks through the directory tree that is +located under the directory \fIdirpath\fP, +and calls \fIfn\fP() once for each entry in the tree. +By default, directories are handled before the files and +subdirectories they contain (preorder traversal). +.P +To avoid using up all of the calling process's file descriptors, +\fInopenfd\fP specifies the maximum number of directories that +.BR nftw () +will hold open simultaneously. +When +the search depth exceeds this, +.BR nftw () +will become slower because +directories have to be closed and reopened. +.BR nftw () +uses at most +one file descriptor for each level in the directory tree. +.P +For each entry found in the tree, +.BR nftw () +calls +\fIfn\fP() with four arguments: +.IR fpath , +.IR sb , +.IR typeflag , +and +.IR ftwbuf . +.I fpath +is the pathname of the entry, +and is expressed either as a pathname relative to the calling process's +current working directory at the time of the call to +.BR nftw (), +if +.I dirpath +was expressed as a relative pathname, +or as an absolute pathname, if +.I dirpath +was expressed as an absolute pathname. +.I sb +is a pointer to the +.I stat +structure returned by a call to +.BR stat (2) +for +.IR fpath . +.P +The +.I typeflag +argument passed to +.IR fn () +is an integer that has one of the following values: +.TP +.B FTW_F +.I fpath +is a regular file. +.TP +.B FTW_D +.I fpath +is a directory. +.TP +.B FTW_DNR +.I fpath +is a directory which can't be read. +.TP +.B FTW_DP +.I fpath +is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. +(If +.B FTW_DEPTH +was not specified in +.IR flags , +then directories will always be visited with +.I typeflag +set to +.BR FTW_D .) +All of the files +and subdirectories within \fIfpath\fP have been processed. +.TP +.B FTW_NS +The +.BR stat (2) +call failed on +.IR fpath , +which is not a symbolic link. +The probable cause for this is that the caller had read permission +on the parent directory, so that the filename +.I fpath +could be seen, +but did not have execute permission, +so that the file could not be reached for +.BR stat (2). +The contents of the buffer pointed to by +.I sb +are undefined. +.TP +.B FTW_SL +.I fpath +is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP. +.\" To obtain the definition of this constant from +.\" .IR <ftw.h> , +.\" either +.\" .B _BSD_SOURCE +.\" must be defined, or +.\" .BR _XOPEN_SOURCE +.\" must be defined with a value of 500 or more. +.TP +.B FTW_SLN +.I fpath +is a symbolic link pointing to a nonexistent file. +(This occurs only if \fBFTW_PHYS\fP is not set.) +In this case the +.I sb +argument passed to +.IR fn () +contains information returned by performing +.BR lstat (2) +on the "dangling" symbolic link. +(But see BUGS.) +.P +The fourth argument +.RI ( ftwbuf ) +that +.BR nftw () +supplies when calling +\fIfn\fP() +is a pointer to a structure of type \fIFTW\fP: +.P +.in +4n +.EX +struct FTW { + int base; + int level; +}; +.EE +.in +.P +.I base +is the offset of the filename (i.e., basename component) +in the pathname given in +.IR fpath . +.I level +is the depth of +.I fpath +in the directory tree, relative to the root of the tree +.RI ( dirpath , +which has depth 0). +.P +To stop the tree walk, \fIfn\fP() returns a nonzero value; this +value will become the return value of +.BR nftw (). +As long as \fIfn\fP() returns 0, +.BR nftw () +will continue either until it has traversed the entire tree, +in which case it will return zero, +or until it encounters an error (such as a +.BR malloc (3) +failure), in which case it will return \-1. +.P +Because +.BR nftw () +uses dynamic data structures, the only safe way to +exit out of a tree walk is to return a nonzero value from \fIfn\fP(). +To allow a signal to terminate the walk without causing a memory leak, +have the handler set a global flag that is checked by \fIfn\fP(). +\fIDon't\fP use +.BR longjmp (3) +unless the program is going to terminate. +.P +The \fIflags\fP argument of +.BR nftw () +is formed by ORing zero or more of the +following flags: +.TP +.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" +If this glibc-specific flag is set, then +.BR nftw () +handles the return value from +.IR fn () +differently. +.IR fn () +should return one of the following values: +.RS +.TP +.B FTW_CONTINUE +Instructs +.BR nftw () +to continue normally. +.TP +.B FTW_SKIP_SIBLINGS +If \fIfn\fP() returns this value, then +siblings of the current entry will be skipped, +and processing continues in the parent. +.\" If \fBFTW_DEPTH\fP +.\" is set, the entry's parent directory is processed next (with +.\" \fIflag\fP set to \fBFTW_DP\fP). +.TP +.B FTW_SKIP_SUBTREE +If \fIfn\fP() is called with an entry that is a directory +(\fItypeflag\fP is \fBFTW_D\fP), this return +value will prevent objects within that directory from being passed as +arguments to \fIfn\fP(). +.BR nftw () +continues processing with the next sibling of the directory. +.TP +.B FTW_STOP +Causes +.BR nftw () +to return immediately with the return value +\fBFTW_STOP\fP. +.P +Other return values could be associated with new actions in the future; +\fIfn\fP() should not return values other than those listed above. +.P +The feature test macro +.B _GNU_SOURCE +must be defined +(before including +.I any +header files) +in order to +obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP. +.RE +.TP +.B FTW_CHDIR +If set, do a +.BR chdir (2) +to each directory before handling its contents. +This is useful if the program needs to perform some action +in the directory in which \fIfpath\fP resides. +(Specifying this flag has no effect on the pathname that is passed in the +.I fpath +argument of +.IR fn .) +.TP +.B FTW_DEPTH +If set, do a post-order traversal, that is, call \fIfn\fP() for +the directory itself \fIafter\fP handling the contents of the directory +and its subdirectories. +(By default, each directory is handled \fIbefore\fP its contents.) +.TP +.B FTW_MOUNT +If set, stay within the same filesystem +(i.e., do not cross mount points). +.TP +.B FTW_PHYS +If set, do not follow symbolic links. +(This is what you want.) +If not set, symbolic links are followed, but no file is reported twice. +.IP +If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, +then the function +.IR fn () +is never called for a directory that would be a descendant of itself. +.SS ftw() +.BR ftw () +is an older function that offers a subset of the functionality of +.BR nftw (). +The notable differences are as follows: +.IP \[bu] 3 +.BR ftw () +has no +.I flags +argument. +It behaves the same as when +.BR nftw () +is called with +.I flags +specified as zero. +.IP \[bu] +The callback function, +.IR fn (), +is not supplied with a fourth argument. +.IP \[bu] +The range of values that is passed via the +.I typeflag +argument supplied to +.IR fn () +is smaller: just +.BR FTW_F , +.BR FTW_D , +.BR FTW_DNR , +.BR FTW_NS , +and (possibly) +.BR FTW_SL . +.SH RETURN VALUE +These functions return 0 on success, and \-1 if an error occurs. +.P +If \fIfn\fP() returns nonzero, +then the tree walk is terminated and the value returned by \fIfn\fP() +is returned as the result of +.BR ftw () +or +.BR nftw (). +.P +If +.BR nftw () +is called with the \fBFTW_ACTIONRETVAL\fP flag, +then the only nonzero value that should be used by \fIfn\fP() +to terminate the tree walk is \fBFTW_STOP\fP, +and that value is returned as the result of +.BR nftw (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nftw () +T} Thread safety MT-Safe cwd +T{ +.na +.nh +.BR ftw () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +In some implementations (e.g., glibc), +.BR ftw () +will never use \fBFTW_SL\fP; on other systems \fBFTW_SL\fP occurs only +for symbolic links that do not point to an existing file; +and again on other systems +.BR ftw () +will use \fBFTW_SL\fP for each symbolic link. +If +.I fpath +is a symbolic link and +.BR stat (2) +failed, POSIX.1-2008 states +that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP +is passed in +.IR typeflag . +For predictable results, use +.BR nftw (). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR ftw () +POSIX.1-2001, SVr4, SUSv1. +POSIX.1-2008 marks it as obsolete. +.TP +.BR nftw () +glibc 2.1. +POSIX.1-2001, SUSv1. +.TP +.B FTW_SL +POSIX.1-2001, SUSv1. +.SH NOTES +POSIX.1-2008 notes that the results are unspecified if +.I fn +does not preserve the current working directory. +.SH BUGS +According to POSIX.1-2008, when the +.I typeflag +argument passed to +.IR fn () +contains +.BR FTW_SLN , +the buffer pointed to by +.I sb +should contain information about the dangling symbolic link +(obtained by calling +.BR lstat (2) +on the link). +Early glibc versions correctly followed the POSIX specification on this point. +However, as a result of a regression introduced in glibc 2.4, +the contents of the buffer pointed to by +.I sb +were undefined when +.B FTW_SLN +is passed in +.IR typeflag . +(More precisely, the contents of the buffer were left unchanged in this case.) +This regression was eventually fixed in glibc 2.30, +.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 +.\" http://austingroupbugs.net/view.php?id=1121 +.\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 +so that the glibc implementation (once more) follows the POSIX specification. +.SH EXAMPLES +The following program traverses the directory tree under the path named +in its first command-line argument, or under the current directory +if no argument is supplied. +It displays various information about each file. +The second command-line argument can be used to specify characters that +control the value assigned to the \fIflags\fP +argument when calling +.BR nftw (). +.SS Program source +\& +.\" SRC BEGIN (ftw.c) +.EX +#define _XOPEN_SOURCE 500 +#include <ftw.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +static int +display_info(const char *fpath, const struct stat *sb, + int tflag, struct FTW *ftwbuf) +{ + printf("%\-3s %2d ", + (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : + (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : + (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : + (tflag == FTW_SLN) ? "sln" : "???", + ftwbuf\->level); +\& + if (tflag == FTW_NS) + printf("\-\-\-\-\-\-\-"); + else + printf("%7jd", (intmax_t) sb\->st_size); +\& + printf(" %\-40s %d %s\en", + fpath, ftwbuf\->base, fpath + ftwbuf\->base); +\& + return 0; /* To tell nftw() to continue */ +} +\& +int +main(int argc, char *argv[]) +{ + int flags = 0; +\& + if (argc > 2 && strchr(argv[2], \[aq]d\[aq]) != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], \[aq]p\[aq]) != NULL) + flags |= FTW_PHYS; +\& + if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) + == \-1) + { + perror("nftw"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR stat (2), +.BR fts (3), +.BR readdir (3) diff --git a/man/man3/funlockfile.3 b/man/man3/funlockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man/man3/funlockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man/man3/futimens.3 b/man/man3/futimens.3 new file mode 100644 index 0000000..a365c7b --- /dev/null +++ b/man/man3/futimens.3 @@ -0,0 +1 @@ +.so man2/utimensat.2 diff --git a/man/man3/futimes.3 b/man/man3/futimes.3 new file mode 100644 index 0000000..2ac7627 --- /dev/null +++ b/man/man3/futimes.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) 2006, 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH futimes 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +futimes, lutimes \- change file timestamps +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/time.h> +.P +.BI "int futimes(int " fd ", const struct timeval " tv [2]); +.BI "int lutimes(const char *" filename ", const struct timeval " tv [2]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR futimes (), +.BR lutimes (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR futimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that the file whose timestamps are to be changed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +.P +.BR lutimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that if +.I filename +refers to a symbolic link, then the link is not dereferenced: +instead, the timestamps of the symbolic link are changed. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR utimes (2), +with the following additions for +.BR futimes (): +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +The +.I /proc +filesystem could not be accessed. +.P +The following additional error may occur for +.BR lutimes (): +.TP +.B ENOSYS +The kernel does not support this call; Linux 2.6.22 or later is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR futimes (), +.BR lutimes () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +Linux, BSD. +.SH HISTORY +.TP +.BR futimes () +glibc 2.3. +.TP +.BR lutimes () +glibc 2.6. +.SH NOTES +.BR lutimes () +is implemented using the +.BR utimensat (2) +system call. +.SH SEE ALSO +.BR utime (2), +.BR utimensat (2), +.BR symlink (7) diff --git a/man/man3/fwide.3 b/man/man3/fwide.3 new file mode 100644 index 0000000..01f2081 --- /dev/null +++ b/man/man3/fwide.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fwide 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fwide \- set and determine the orientation of a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int fwide(FILE *" stream ", int " mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fwide (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +When \fImode\fP is zero, the +.BR fwide () +function determines the current +orientation of \fIstream\fP. +It returns a positive value if \fIstream\fP is +wide-character oriented, that is, if wide-character I/O is permitted but char +I/O is disallowed. +It returns a negative value if \fIstream\fP is byte oriented\[em]that is, +if char I/O is permitted but wide-character I/O is disallowed. +It +returns zero if \fIstream\fP has no orientation yet; in this case the next +I/O operation might change the orientation (to byte oriented if it is a char +I/O operation, or to wide-character oriented if it is a wide-character I/O +operation). +.P +Once a stream has an orientation, it cannot be changed and persists until +the stream is closed. +.P +When \fImode\fP is nonzero, the +.BR fwide () +function first attempts to set +\fIstream\fP's orientation (to wide-character oriented +if \fImode\fP is greater than 0, or +to byte oriented if \fImode\fP is less than 0). +It then returns a value denoting the +current orientation, as above. +.SH RETURN VALUE +The +.BR fwide () +function returns the stream's orientation, after possibly +changing it. +A positive return value means wide-character oriented. +A negative return value means byte oriented. +A return value of zero means undecided. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +Wide-character output to a byte oriented stream can be performed through the +.BR fprintf (3) +function with the +.B %lc +and +.B %ls +directives. +.P +Char oriented output to a wide-character oriented stream can be performed +through the +.BR fwprintf (3) +function with the +.B %c +and +.B %s +directives. +.SH SEE ALSO +.BR fprintf (3), +.BR fwprintf (3) diff --git a/man/man3/fwprintf.3 b/man/man3/fwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/fwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/fwrite.3 b/man/man3/fwrite.3 new file mode 100644 index 0000000..86906ed --- /dev/null +++ b/man/man3/fwrite.3 @@ -0,0 +1 @@ +.so man3/fread.3 diff --git a/man/man3/fwrite_unlocked.3 b/man/man3/fwrite_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fwrite_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/gai_cancel.3 b/man/man3/gai_cancel.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_cancel.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gai_error.3 b/man/man3/gai_error.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_error.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gai_strerror.3 b/man/man3/gai_strerror.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man/man3/gai_strerror.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man/man3/gai_suspend.3 b/man/man3/gai_suspend.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_suspend.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gamma.3 b/man/man3/gamma.3 new file mode 100644 index 0000000..082da41 --- /dev/null +++ b/man/man3/gamma.3 @@ -0,0 +1,121 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2003-11-18, aeb: historical remarks +.\" +.TH gamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gamma, gammaf, gammal \- (logarithm of the) gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "[[deprecated]] double gamma(double " x ");" +.BI "[[deprecated]] float gammaf(float " x ");" +.BI "[[deprecated]] long double gammal(long double " x ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gamma (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR gammaf (), +.BR gammal (): +.nf + _XOPEN_SOURCE >= 600 || (_XOPEN_SOURCE && _ISOC99_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions are deprecated: instead, use either the +.BR tgamma (3) +or the +.BR lgamma (3) +functions, as appropriate. +.P +For the definition of the Gamma function, see +.BR tgamma (3). +.SS *BSD version +The libm in 4.4BSD and some versions of FreeBSD had a +.BR gamma () +function that computes the Gamma function, as one would expect. +.SS glibc version +glibc has a +.BR gamma () +function that is equivalent to +.BR lgamma (3) +and computes the natural logarithm of the Gamma function. +.SH RETURN VALUE +See +.BR lgamma (3). +.SH ERRORS +See +.BR lgamma (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gamma (), +.BR gammaf (), +.BR gammal () +T} Thread safety MT-Unsafe race:signgam +.TE +.SH STANDARDS +None. +.SH HISTORY +SVID 2. +.P +Because of historical variations in behavior across systems, +this function is not specified in any recent standard. +.P +4.2BSD had a +.BR gamma () +that computed +.RI ln(|Gamma(| x |)|), +leaving the sign of +.RI Gamma(| x |) +in the external integer +.IR signgam . +In 4.3BSD the name was changed to +.BR lgamma (3), +and the man page promises +.P +.in +4n +"At some time in the future the name gamma will be rehabilitated +and used for the Gamma function" +.in +.P +This did indeed happen in 4.4BSD, where +.BR gamma () +computes the Gamma function (with no effect on +.IR signgam ). +However, this came too late, and we now have +.BR tgamma (3), +the "true gamma" function. +.\" The FreeBSD man page says about gamma() that it is like lgamma() +.\" except that is does not set signgam. +.\" Also, that 4.4BSD has a gamma() that computes the true gamma function. +.SH SEE ALSO +.BR lgamma (3), +.BR signgam (3), +.BR tgamma (3) diff --git a/man/man3/gammaf.3 b/man/man3/gammaf.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man/man3/gammaf.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man/man3/gammal.3 b/man/man3/gammal.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man/man3/gammal.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man/man3/gcvt.3 b/man/man3/gcvt.3 new file mode 100644 index 0000000..d563327 --- /dev/null +++ b/man/man3/gcvt.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu) +.TH gcvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "char *gcvt(double " number ", int " ndigit ", char *" buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gcvt (): +.nf + Since glibc 2.17 + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200809L)) + || /* glibc >= 2.20 */ _DEFAULT_SOURCE + || /* glibc <= 2.19 */ _SVID_SOURCE + glibc 2.12 to glibc 2.16: + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200112L)) + || _SVID_SOURCE + Before glibc 2.12: + _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR gcvt () +function converts \fInumber\fP to a minimal length null-terminated +ASCII string and stores the result in \fIbuf\fP. +It produces \fIndigit\fP significant digits in either +.BR printf (3) +F format or E format. +.SH RETURN VALUE +The +.BR gcvt () +function returns +\fIbuf\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gcvt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +Marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removed it, +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH SEE ALSO +.BR ecvt (3), +.BR fcvt (3), +.BR sprintf (3) diff --git a/man/man3/get_avphys_pages.3 b/man/man3/get_avphys_pages.3 new file mode 100644 index 0000000..cbd22cc --- /dev/null +++ b/man/man3/get_avphys_pages.3 @@ -0,0 +1 @@ +.so man3/get_phys_pages.3 diff --git a/man/man3/get_current_dir_name.3 b/man/man3/get_current_dir_name.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man/man3/get_current_dir_name.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man/man3/get_myaddress.3 b/man/man3/get_myaddress.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/get_myaddress.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/get_nprocs.3 b/man/man3/get_nprocs.3 new file mode 100644 index 0000000..96446a5 --- /dev/null +++ b/man/man3/get_nprocs.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (c) 2012, Petr Benas +.\" and Copyright (c) 2012, Michael Kerrisk <mtk.man-pages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH get_nprocs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_nprocs, get_nprocs_conf \- get number of processors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/sysinfo.h> +.P +.B int get_nprocs(void); +.B int get_nprocs_conf(void); +.fi +.SH DESCRIPTION +The function +.BR get_nprocs_conf () +returns the number of processors configured by the operating system. +.P +The function +.BR get_nprocs () +returns the number of processors currently available in the system. +This may be less than the number returned by +.BR get_nprocs_conf () +because processors may be offline (e.g., on hotpluggable systems). +.SH RETURN VALUE +As given in DESCRIPTION. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR get_nprocs (), +.BR get_nprocs_conf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +The current +.\" glibc 2.15 +implementation of these functions is rather expensive, +since they open and parse files in the +.I /sys +filesystem each time they are called. +.P +The following +.BR sysconf (3) +calls make use of the functions documented on this page +to return the same information. +.P +.in +4n +.EX +np = sysconf(_SC_NPROCESSORS_CONF); /* processors configured */ +np = sysconf(_SC_NPROCESSORS_ONLN); /* processors available */ +.EE +.in +.SH EXAMPLES +The following example shows how +.BR get_nprocs () +and +.BR get_nprocs_conf () +can be used. +.P +.\" SRC BEGIN (get_nprocs_conf.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <sys/sysinfo.h> +\& +int +main(void) +{ + printf("This system has %d processors configured and " + "%d processors available.\en", + get_nprocs_conf(), get_nprocs()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR nproc (1) diff --git a/man/man3/get_nprocs_conf.3 b/man/man3/get_nprocs_conf.3 new file mode 100644 index 0000000..7de3e2b --- /dev/null +++ b/man/man3/get_nprocs_conf.3 @@ -0,0 +1 @@ +.so man3/get_nprocs.3 diff --git a/man/man3/get_phys_pages.3 b/man/man3/get_phys_pages.3 new file mode 100644 index 0000000..6915d7f --- /dev/null +++ b/man/man3/get_phys_pages.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2015 William Woodruff (william@tuffbizz.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH get_phys_pages 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_phys_pages, get_avphys_pages \- get total and available physical +page counts +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <sys/sysinfo.h>" +.P +.B long get_phys_pages(void); +.B long get_avphys_pages(void); +.fi +.SH DESCRIPTION +The function +.BR get_phys_pages () +returns the total number of physical pages of memory available on the system. +.P +The function +.BR get_avphys_pages () +returns the number of currently available physical pages of memory on the +system. +.SH RETURN VALUE +On success, +these functions return a nonnegative value as given in DESCRIPTION. +On failure, they return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +The system could not provide the required information +(possibly because the +.I /proc +filesystem was not mounted). +.SH STANDARDS +GNU. +.SH HISTORY +Before glibc 2.23, +these functions obtained the required information by scanning the +.I MemTotal +and +.I MemFree +fields of +.IR /proc/meminfo . +Since glibc 2.23, +these functions obtain the required information by calling +.BR sysinfo (2). +.SH NOTES +The following +.BR sysconf (3) +calls provide a portable means of obtaining the same information as the +functions described on this page. +.P +.in +4n +.EX +total_pages = sysconf(_SC_PHYS_PAGES); /* total pages */ +avl_pages = sysconf(_SC_AVPHYS_PAGES); /* available pages */ +.EE +.in +.SH EXAMPLES +The following example shows how +.BR get_phys_pages () +and +.BR get_avphys_pages () +can be used. +.P +.\" SRC BEGIN (get_phys_pages.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <sys/sysinfo.h> +\& +int +main(void) +{ + printf("This system has %ld pages of physical memory and " + "%ld pages of physical memory available.\en", + get_phys_pages(), get_avphys_pages()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sysconf (3) diff --git a/man/man3/getaddrinfo.3 b/man/man3/getaddrinfo.3 new file mode 100644 index 0000000..d8be6f1 --- /dev/null +++ b/man/man3/getaddrinfo.3 @@ -0,0 +1,854 @@ +'\" t +.\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com> +.\" A few pieces of an earlier version remain: +.\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.\" +.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, +.\" and AI_NUMERICSERV. +.\" 2006-11-25, Ulrich Drepper <drepper@redhat.com> +.\" Add text describing Internationalized Domain Name extensions. +.\" 2007-06-08, mtk: added example programs +.\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other +.\" minor rewrites. +.\" 2008-06-18, mtk: many parts rewritten +.\" 2008-12-04, Petr Baudis <pasky@suse.cz> +.\" Describe results ordering and reference /etc/gai.conf. +.\" +.\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support +.\" and is SCTP support now also there? +.\" +.TH getaddrinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getaddrinfo, freeaddrinfo, gai_strerror \- network address and +service translation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/socket.h> +.B #include <netdb.h> +.P +.BI "int getaddrinfo(const char *restrict " node , +.BI " const char *restrict " service , +.BI " const struct addrinfo *restrict " hints , +.BI " struct addrinfo **restrict " res ); +.P +.BI "void freeaddrinfo(struct addrinfo *" res ); +.P +.BI "const char *gai_strerror(int " errcode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getaddrinfo (), +.BR freeaddrinfo (), +.BR gai_strerror (): +.nf + Since glibc 2.22: + _POSIX_C_SOURCE >= 200112L + glibc 2.21 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +Given +.I node +and +.IR service , +which identify an Internet host and a service, +.BR getaddrinfo () +returns one or more +.I addrinfo +structures, each of which contains an Internet address +that can be specified in a call to +.BR bind (2) +or +.BR connect (2). +The +.BR getaddrinfo () +function combines the functionality provided by the +.\" .BR getipnodebyname (3), +.\" .BR getipnodebyaddr (3), +.BR gethostbyname (3) +and +.BR getservbyname (3) +functions into a single interface, but unlike the latter functions, +.BR getaddrinfo () +is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. +.P +The +.I addrinfo +structure used by +.BR getaddrinfo () +contains the following fields: +.P +.in +4n +.EX +struct addrinfo { + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; + socklen_t ai_addrlen; + struct sockaddr *ai_addr; + char *ai_canonname; + struct addrinfo *ai_next; +}; +.EE +.in +.P +The +.I hints +argument points to an +.I addrinfo +structure that specifies criteria for selecting the socket address +structures returned in the list pointed to by +.IR res . +If +.I hints +is not NULL it points to an +.I addrinfo +structure whose +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +specify criteria that limit the set of socket addresses returned by +.BR getaddrinfo (), +as follows: +.TP +.I ai_family +This field specifies the desired address family for the returned addresses. +Valid values for this field include +.B AF_INET +and +.BR AF_INET6 . +The value +.B AF_UNSPEC +indicates that +.BR getaddrinfo () +should return socket addresses for any address family +(either IPv4 or IPv6, for example) that can be used with +.I node +and +.IR service . +.TP +.I ai_socktype +This field specifies the preferred socket type, for example +.B SOCK_STREAM +or +.BR SOCK_DGRAM . +Specifying 0 in this field indicates that socket addresses of any type +can be returned by +.BR getaddrinfo (). +.TP +.I ai_protocol +This field specifies the protocol for the returned socket addresses. +Specifying 0 in this field indicates that socket addresses with +any protocol can be returned by +.BR getaddrinfo (). +.TP +.I ai_flags +This field specifies additional options, described below. +Multiple flags are specified by bitwise OR-ing them together. +.P +All the other fields in the structure pointed to by +.I hints +must contain either 0 or a null pointer, as appropriate. +.P +Specifying +.I hints +as NULL is equivalent to setting +.I ai_socktype +and +.I ai_protocol +to 0; +.I ai_family +to +.BR AF_UNSPEC ; +and +.I ai_flags +to +.BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" . +(POSIX specifies different defaults for +.IR ai_flags ; +see NOTES.) +.I node +specifies either a numerical network address +(for IPv4, numbers-and-dots notation as supported by +.BR inet_aton (3); +for IPv6, hexadecimal string format as supported by +.BR inet_pton (3)), +or a network hostname, whose network addresses are looked up and resolved. +If +.I hints.ai_flags +contains the +.B AI_NUMERICHOST +flag, then +.I node +must be a numerical network address. +The +.B AI_NUMERICHOST +flag suppresses any potentially lengthy network host address lookups. +.P +If the +.B AI_PASSIVE +flag is specified in +.IR hints.ai_flags , +and +.I node +is NULL, +then the returned socket addresses will be suitable for +.BR bind (2)ing +a socket that will +.BR accept (2) +connections. +The returned socket address will contain the "wildcard address" +.RB ( INADDR_ANY +for IPv4 addresses, +.B IN6ADDR_ANY_INIT +for IPv6 address). +The wildcard address is used by applications (typically servers) +that intend to accept connections on any of the host's network addresses. +If +.I node +is not NULL, then the +.B AI_PASSIVE +flag is ignored. +.P +If the +.B AI_PASSIVE +flag is not set in +.IR hints.ai_flags , +then the returned socket addresses will be suitable for use with +.BR connect (2), +.BR sendto (2), +or +.BR sendmsg (2). +If +.I node +is NULL, +then the network address will be set to the loopback interface address +.RB ( INADDR_LOOPBACK +for IPv4 addresses, +.B IN6ADDR_LOOPBACK_INIT +for IPv6 address); +this is used by applications that intend to communicate +with peers running on the same host. +.P +.I service +sets the port in each returned address structure. +If this argument is a service name (see +.BR services (5)), +it is translated to the corresponding port number. +This argument can also be specified as a decimal number, +which is simply converted to binary. +If +.I service +is NULL, then the port number of the returned socket addresses +will be left uninitialized. +If +.B AI_NUMERICSERV +is specified in +.I hints.ai_flags +and +.I service +is not NULL, then +.I service +must point to a string containing a numeric port number. +This flag is used to inhibit the invocation of a name resolution service +in cases where it is known not to be required. +.P +Either +.I node +or +.IR service , +but not both, may be NULL. +.P +The +.BR getaddrinfo () +function allocates and initializes a linked list of +.I addrinfo +structures, one for each network address that matches +.I node +and +.IR service , +subject to any restrictions imposed by +.IR hints , +and returns a pointer to the start of the list in +.IR res . +The items in the linked list are linked by the +.I ai_next +field. +.P +There are several reasons why +the linked list may have more than one +.I addrinfo +structure, including: the network host is multihomed, accessible +over multiple protocols (e.g., both +.B AF_INET +and +.BR AF_INET6 ); +or the same service is available from multiple socket types (one +.B SOCK_STREAM +address and another +.B SOCK_DGRAM +address, for example). +Normally, the application should try +using the addresses in the order in which they are returned. +The sorting function used within +.BR getaddrinfo () +is defined in RFC\ 3484; the order can be tweaked for a particular +system by editing +.I /etc/gai.conf +(available since glibc 2.5). +.P +If +.I hints.ai_flags +includes the +.B AI_CANONNAME +flag, then the +.I ai_canonname +field of the first of the +.I addrinfo +structures in the returned list is set to point to the +official name of the host. +.\" Prior to glibc 2.3.4, the ai_canonname of each addrinfo +.\" structure was set pointing to the canonical name; that was +.\" more than POSIX.1-2001 specified, or other implementations provided. +.\" MTK, Aug 05 +.P +The remaining fields of each returned +.I addrinfo +structure are initialized as follows: +.IP \[bu] 3 +The +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +fields return the socket creation parameters (i.e., these fields have +the same meaning as the corresponding arguments of +.BR socket (2)). +For example, +.I ai_family +might return +.B AF_INET +or +.BR AF_INET6 ; +.I ai_socktype +might return +.B SOCK_DGRAM +or +.BR SOCK_STREAM ; +and +.I ai_protocol +returns the protocol for the socket. +.IP \[bu] +A pointer to the socket address is placed in the +.I ai_addr +field, and the length of the socket address, in bytes, +is placed in the +.I ai_addrlen +field. +.P +If +.I hints.ai_flags +includes the +.B AI_ADDRCONFIG +flag, then IPv4 addresses are returned in the list pointed to by +.I res +only if the local system has at least one +IPv4 address configured, and IPv6 addresses are returned +only if the local system has at least one IPv6 address configured. +The loopback address is not considered for this case as valid +as a configured address. +This flag is useful on, for example, +IPv4-only systems, to ensure that +.BR getaddrinfo () +does not return IPv6 socket addresses that would always fail in +.BR connect (2) +or +.BR bind (2). +.P +If +.I hints.ai_flags +specifies the +.B AI_V4MAPPED +flag, and +.I hints.ai_family +was specified as +.BR AF_INET6 , +and no matching IPv6 addresses could be found, +then return IPv4-mapped IPv6 addresses in the list pointed to by +.IR res . +If both +.B AI_V4MAPPED +and +.B AI_ALL +are specified in +.IR hints.ai_flags , +then return both IPv6 and IPv4-mapped IPv6 addresses +in the list pointed to by +.IR res . +.B AI_ALL +is ignored if +.B AI_V4MAPPED +is not also specified. +.P +The +.BR freeaddrinfo () +function frees the memory that was allocated +for the dynamically allocated linked list +.IR res . +.SS Extensions to getaddrinfo() for Internationalized Domain Names +Starting with glibc 2.3.4, +.BR getaddrinfo () +has been extended to selectively allow the incoming and outgoing +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Four new flags are defined: +.TP +.B AI_IDN +If this flag is specified, then the node name given in +.I node +is converted to IDN format if necessary. +The source encoding is that of the current locale. +.IP +If the input name contains non-ASCII characters, then the IDN encoding +is used. +Those parts of the node name (delimited by dots) that contain +non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) +before being passed to the name resolution functions. +.\" Implementation Detail: +.\" To minimize effects on system performance the implementation might +.\" want to check whether the input string contains any non-ASCII +.\" characters. If there are none the IDN step can be skipped completely. +.\" On systems which allow not-ASCII safe encodings for a locale this +.\" might be a problem. +.TP +.B AI_CANONIDN +After a successful name lookup, and if the +.B AI_CANONNAME +flag was specified, +.BR getaddrinfo () +will return the canonical name of the +node corresponding to the +.I addrinfo +structure value passed back. +The return value is an exact copy of the value returned by the name +resolution function. +.IP +If the name is encoded using ACE, then it will contain the +.I xn\-\- +prefix for one or more components of the name. +To convert these components into a readable form the +.B AI_CANONIDN +flag can be passed in addition to +.BR AI_CANONNAME . +The resulting string is encoded using the current locale's encoding. +.\" +.\"Implementation Detail: +.\"If no component of the returned name starts with xn\-\- the IDN +.\"step can be skipped, therefore avoiding unnecessary slowdowns. +.TP +.B AI_IDN_ALLOW_UNASSIGNED +.TQ +.B AI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getaddrinfo(); they need to +.\" be documented. +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +.BR getaddrinfo () +returns 0 if it succeeds, or one of the following nonzero error codes: +.TP +.B EAI_ADDRFAMILY +.\" Not in SUSv3 +The specified network host does not have any network addresses in the +requested address family. +.TP +.B EAI_AGAIN +The name server returned a temporary failure indication. +Try again later. +.TP +.B EAI_BADFLAGS +.I hints.ai_flags +contains invalid flags; or, +.I hints.ai_flags +included +.B AI_CANONNAME +and +.I node +was NULL. +.TP +.B EAI_FAIL +The name server returned a permanent failure indication. +.TP +.B EAI_FAMILY +The requested address family is not supported. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NODATA +.\" Not in SUSv3 +The specified network host exists, but does not have any +network addresses defined. +.TP +.B EAI_NONAME +The +.I node +or +.I service +is not known; or both +.I node +and +.I service +are NULL; or +.B AI_NUMERICSERV +was specified in +.I hints.ai_flags +and +.I service +was not a numeric port-number string. +.TP +.B EAI_SERVICE +The requested service is not available for the requested socket type. +It may be available through another socket type. +For example, this error could occur if +.I service +was "shell" (a service available only on stream sockets), and either +.I hints.ai_protocol +was +.BR IPPROTO_UDP , +or +.I hints.ai_socktype +was +.BR SOCK_DGRAM ; +or the error could occur if +.I service +was not NULL, and +.I hints.ai_socktype +was +.B SOCK_RAW +(a socket type that does not support the concept of services). +.TP +.B EAI_SOCKTYPE +The requested socket type is not supported. +This could occur, for example, if +.I hints.ai_socktype +and +.I hints.ai_protocol +are inconsistent (e.g., +.B SOCK_DGRAM +and +.BR IPPROTO_TCP , +respectively). +.TP +.B EAI_SYSTEM +Other system error; +.I errno +is set to indicate the error. +.P +The +.BR gai_strerror () +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/gai.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getaddrinfo () +T} Thread safety MT-Safe env locale +T{ +.na +.nh +.BR freeaddrinfo (), +.BR gai_strerror () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +According to POSIX.1, specifying +.\" POSIX.1-2001, POSIX.1-2008 +.I hints +as NULL should cause +.I ai_flags +to be assumed as 0. +The GNU C library instead assumes a value of +.B (AI_V4MAPPED\~|\~AI_ADDRCONFIG) +for this case, +since this value is considered an improvement on the specification. +.SH STANDARDS +POSIX.1-2008. +.TP +.BR getaddrinfo () +RFC\ 2553. +.SH HISTORY +POSIX.1-2001. +.TP +.B AI_ADDRCONFIG +.TQ +.B AI_ALL +.TQ +.B AI_V4MAPPED +glibc 2.3.3. +.TP +.B AI_NUMERICSERV +glibc 2.3.4. +.SH NOTES +.BR getaddrinfo () +supports the +.IB address % scope-id +notation for specifying the IPv6 scope-ID. +.SH EXAMPLES +.\" getnameinfo.3 refers to this example +.\" socket.2 refers to this example +.\" bind.2 refers to this example +.\" connect.2 refers to this example +.\" recvfrom.2 refers to this example +.\" sendto.2 refers to this example +The following programs demonstrate the use of +.BR getaddrinfo (), +.BR gai_strerror (), +.BR freeaddrinfo (), +and +.BR getnameinfo (3). +The programs are an echo server and client for UDP datagrams. +.SS Server program +\& +.\" SRC BEGIN (server.c) +.EX +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/socket.h> +#include <sys/types.h> +#include <unistd.h> +\& +#define BUF_SIZE 500 +\& +int +main(int argc, char *argv[]) +{ + int sfd, s; + char buf[BUF_SIZE]; + ssize_t nread; + socklen_t peer_addrlen; + struct addrinfo hints; + struct addrinfo *result, *rp; + struct sockaddr_storage peer_addr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s port\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + memset(&hints, 0, sizeof(hints)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */ + hints.ai_protocol = 0; /* Any protocol */ + hints.ai_canonname = NULL; + hints.ai_addr = NULL; + hints.ai_next = NULL; +\& + s = getaddrinfo(NULL, argv[1], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully bind(2). + If socket(2) (or bind(2)) fails, we (close the socket + and) try the next address. */ +\& + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; +\& + if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0) + break; /* Success */ +\& + close(sfd); + } +\& + freeaddrinfo(result); /* No longer needed */ +\& + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not bind\en"); + exit(EXIT_FAILURE); + } +\& + /* Read datagrams and echo them back to sender. */ +\& + for (;;) { + char host[NI_MAXHOST], service[NI_MAXSERV]; +\& + peer_addrlen = sizeof(peer_addr); + nread = recvfrom(sfd, buf, BUF_SIZE, 0, + (struct sockaddr *) &peer_addr, &peer_addrlen); + if (nread == \-1) + continue; /* Ignore failed request */ +\& + s = getnameinfo((struct sockaddr *) &peer_addr, + peer_addrlen, host, NI_MAXHOST, + service, NI_MAXSERV, NI_NUMERICSERV); + if (s == 0) + printf("Received %zd bytes from %s:%s\en", + nread, host, service); + else + fprintf(stderr, "getnameinfo: %s\en", gai_strerror(s)); +\& + if (sendto(sfd, buf, nread, 0, (struct sockaddr *) &peer_addr, + peer_addrlen) != nread) + { + fprintf(stderr, "Error sending response\en"); + } + } +} +.EE +.\" SRC END +.SS Client program +\& +.\" SRC BEGIN (client.c) +.EX +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/socket.h> +#include <sys/types.h> +#include <unistd.h> +\& +#define BUF_SIZE 500 +\& +int +main(int argc, char *argv[]) +{ + int sfd, s; + char buf[BUF_SIZE]; + size_t len; + ssize_t nread; + struct addrinfo hints; + struct addrinfo *result, *rp; +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s host port msg...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Obtain address(es) matching host/port. */ +\& + memset(&hints, 0, sizeof(hints)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = 0; + hints.ai_protocol = 0; /* Any protocol */ +\& + s = getaddrinfo(argv[1], argv[2], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully connect(2). + If socket(2) (or connect(2)) fails, we (close the socket + and) try the next address. */ +\& + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; +\& + if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1) + break; /* Success */ +\& + close(sfd); + } +\& + freeaddrinfo(result); /* No longer needed */ +\& + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not connect\en"); + exit(EXIT_FAILURE); + } +\& + /* Send remaining command\-line arguments as separate + datagrams, and read responses from server. */ +\& + for (size_t j = 3; j < argc; j++) { + len = strlen(argv[j]) + 1; + /* +1 for terminating null byte */ +\& + if (len > BUF_SIZE) { + fprintf(stderr, + "Ignoring long message in argument %zu\en", j); + continue; + } +\& + if (write(sfd, argv[j], len) != len) { + fprintf(stderr, "partial/failed write\en"); + exit(EXIT_FAILURE); + } +\& + nread = read(sfd, buf, BUF_SIZE); + if (nread == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + printf("Received %zd bytes: %s\en", nread, buf); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getaddrinfo_a (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR gai.conf (5), +.BR hostname (7), +.BR ip (7) diff --git a/man/man3/getaddrinfo_a.3 b/man/man3/getaddrinfo_a.3 new file mode 100644 index 0000000..373165a --- /dev/null +++ b/man/man3/getaddrinfo_a.3 @@ -0,0 +1,645 @@ +'\" t +.\" Copyright (c) 2009 Petr Baudis <pasky@suse.cz> +.\" and clean-ups and additions (C) Copyright 2010 Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: http://people.redhat.com/drepper/asynchnl.pdf, +.\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html +.\" +.TH getaddrinfo_a 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous +network address and service translation +.SH LIBRARY +Asynchronous name lookup library +.RI ( libanl ", " \-lanl ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <netdb.h> +.P +.BI "int getaddrinfo_a(int " mode ", struct gaicb *" list [restrict], +.BI " int " nitems ", struct sigevent *restrict " sevp ); +.BI "int gai_suspend(const struct gaicb *const " list "[], int " nitems , +.BI " const struct timespec *" timeout ); +.P +.BI "int gai_error(struct gaicb *" req ); +.BI "int gai_cancel(struct gaicb *" req ); +.fi +.SH DESCRIPTION +The +.BR getaddrinfo_a () +function performs the same task as +.BR getaddrinfo (3), +but allows multiple name look-ups to be performed asynchronously, +with optional notification on completion of look-up operations. +.P +The +.I mode +argument has one of the following values: +.TP +.B GAI_WAIT +Perform the look-ups synchronously. +The call blocks until the look-ups have completed. +.TP +.B GAI_NOWAIT +Perform the look-ups asynchronously. +The call returns immediately, +and the requests are resolved in the background. +See the discussion of the +.I sevp +argument below. +.P +The array +.I list +specifies the look-up requests to process. +The +.I nitems +argument specifies the number of elements in +.IR list . +The requested look-up operations are started in parallel. +NULL elements in +.I list +are ignored. +Each request is described by a +.I gaicb +structure, defined as follows: +.P +.in +4n +.EX +struct gaicb { + const char *ar_name; + const char *ar_service; + const struct addrinfo *ar_request; + struct addrinfo *ar_result; +}; +.EE +.in +.P +The elements of this structure correspond to the arguments of +.BR getaddrinfo (3). +Thus, +.I ar_name +corresponds to the +.I node +argument and +.I ar_service +to the +.I service +argument, identifying an Internet host and a service. +The +.I ar_request +element corresponds to the +.I hints +argument, specifying the criteria for selecting +the returned socket address structures. +Finally, +.I ar_result +corresponds to the +.I res +argument; you do not need to initialize this element, +it will be automatically set when the request +is resolved. +The +.I addrinfo +structure referenced by the last two elements is described in +.BR getaddrinfo (3). +.P +When +.I mode +is specified as +.BR GAI_NOWAIT , +notifications about resolved requests +can be obtained by employing the +.I sigevent +structure pointed to by the +.I sevp +argument. +For the definition and general details of this structure, see +.BR sigevent (3type). +The +.I sevp\->sigev_notify +field can have the following values: +.TP +.B SIGEV_NONE +Don't provide any notification. +.TP +.B SIGEV_SIGNAL +When a look-up completes, generate the signal +.I sigev_signo +for the process. +See +.BR sigevent (3type) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_ASYNCNL . +.\" si_pid and si_uid are also set, to the values of the calling process, +.\" which doesn't provide useful information, so we'll skip mentioning it. +.TP +.B SIGEV_THREAD +When a look-up completes, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (3type) +for details. +.P +For +.B SIGEV_SIGNAL +and +.BR SIGEV_THREAD , +it may be useful to point +.I sevp\->sigev_value.sival_ptr +to +.IR list . +.P +The +.BR gai_suspend () +function suspends execution of the calling thread, +waiting for the completion of one or more requests in the array +.IR list . +The +.I nitems +argument specifies the size of the array +.IR list . +The call blocks until one of the following occurs: +.IP \[bu] 3 +One or more of the operations in +.I list +completes. +.IP \[bu] +The call is interrupted by a signal that is caught. +.IP \[bu] +The time interval specified in +.I timeout +elapses. +This argument specifies a timeout in seconds plus nanoseconds (see +.BR nanosleep (2) +for details of the +.I timespec +structure). +If +.I timeout +is NULL, then the call blocks indefinitely +(until one of the events above occurs). +.P +No explicit indication of which request was completed is given; +you must determine which request(s) have completed by iterating with +.BR gai_error () +over the list of requests. +.P +The +.BR gai_error () +function returns the status of the request +.IR req : +either +.B EAI_INPROGRESS +if the request was not completed yet, +0 if it was handled successfully, +or an error code if the request could not be resolved. +.P +The +.BR gai_cancel () +function cancels the request +.IR req . +If the request has been canceled successfully, +the error status of the request will be set to +.B EAI_CANCELED +and normal asynchronous notification will be performed. +The request cannot be canceled if it is currently being processed; +in that case, it will be handled as if +.BR gai_cancel () +has never been called. +If +.I req +is NULL, an attempt is made to cancel all outstanding requests +that the process has made. +.SH RETURN VALUE +The +.BR getaddrinfo_a () +function returns 0 if all of the requests have been enqueued successfully, +or one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The resources necessary to enqueue the look-up requests were not available. +The application may check the error status of each +request to determine which ones failed. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_SYSTEM +.I mode +is invalid. +.P +The +.BR gai_suspend () +function returns 0 if at least one of the listed requests has been completed. +Otherwise, it returns one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The given timeout expired before any of the requests could be completed. +.TP +.B EAI_ALLDONE +There were no actual requests given to the function. +.TP +.B EAI_INTR +A signal has interrupted the function. +Note that this interruption might have been +caused by signal notification of some completed look-up request. +.P +The +.BR gai_error () +function can return +.B EAI_INPROGRESS +for an unfinished look-up request, +0 for a successfully completed look-up +(as described above), one of the error codes that could be returned by +.BR getaddrinfo (3), +or the error code +.B EAI_CANCELED +if the request has been canceled explicitly before it could be finished. +.P +The +.BR gai_cancel () +function can return one of these values: +.TP +.B EAI_CANCELED +The request has been canceled successfully. +.TP +.B EAI_NOTCANCELED +The request has not been canceled. +.TP +.B EAI_ALLDONE +The request has already completed. +.P +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getaddrinfo_a (), +.BR gai_suspend (), +.BR gai_error (), +.BR gai_cancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.2.3. +.P +The interface of +.BR getaddrinfo_a () +was modeled after the +.BR lio_listio (3) +interface. +.SH EXAMPLES +Two examples are provided: a simple example that resolves +several requests in parallel synchronously, and a complex example +showing some of the asynchronous capabilities. +.SS Synchronous example +The program below simply resolves several hostnames in parallel, +giving a speed-up compared to resolving the hostnames sequentially using +.BR getaddrinfo (3). +The program might be used like this: +.P +.in +4n +.EX +$ \fB./a.out mirrors.kernel.org enoent.linuxfoundation.org gnu.org\fP +mirrors.kernel.org: 139.178.88.99 +enoent.linuxfoundation.org: Name or service not known +gnu.org: 209.51.188.116 +.EE +.in +.P +Here is the program source code +.P +.\" SRC BEGIN (sync.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define MALLOC(n, type) ((type *) reallocarray(NULL, n, sizeof(type))) +\& +int +main(int argc, char *argv[]) +{ + int ret; + struct gaicb *reqs[argc \- 1]; + char host[NI_MAXHOST]; + struct addrinfo *res; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s HOST...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + for (size_t i = 0; i < argc \- 1; i++) { + reqs[i] = MALLOC(1, struct gaicb); + if (reqs[i] == NULL) + err(EXIT_FAILURE, "malloc"); +\& + memset(reqs[i], 0, sizeof(*reqs[0])); + reqs[i]\->ar_name = argv[i + 1]; + } +\& + ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL); + if (ret != 0) { + fprintf(stderr, "getaddrinfo_a() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } +\& + for (size_t i = 0; i < argc \- 1; i++) { + printf("%s: ", reqs[i]\->ar_name); + ret = gai_error(reqs[i]); + if (ret == 0) { + res = reqs[i]\->ar_result; +\& + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret != 0) { + fprintf(stderr, "getnameinfo() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); +\& + } else { + puts(gai_strerror(ret)); + } + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Asynchronous example +This example shows a simple interactive +.BR getaddrinfo_a () +front-end. +The notification facility is not demonstrated. +.P +An example session might look like this: +.P +.in +4n +.EX +$ \fB./a.out\fP +> a mirrors.kernel.org enoent.linuxfoundation.org gnu.org +> c 2 +[2] gnu.org: Request not canceled +> w 0 1 +[00] mirrors.kernel.org: Finished +> l +[00] mirrors.kernel.org: 139.178.88.99 +[01] enoent.linuxfoundation.org: Processing request in progress +[02] gnu.org: 209.51.188.116 +> l +[00] mirrors.kernel.org: 139.178.88.99 +[01] enoent.linuxfoundation.org: Name or service not known +[02] gnu.org: 209.51.188.116 +.EE +.in +.P +The program source is as follows: +.P +.\" SRC BEGIN (async.c) +.EX +#define _GNU_SOURCE +#include <assert.h> +#include <err.h> +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define CALLOC(n, type) ((type *) calloc(n, sizeof(type))) +\& +#define REALLOCF(ptr, n, type) \e +({ \e + static_assert(__builtin_types_compatible_p(typeof(ptr), type *)); \e + \e + (type *) reallocarrayf(ptr, n, sizeof(type)); \e +}) +\& +static struct gaicb **reqs = NULL; +static size_t nreqs = 0; +\& +static inline void * +reallocarrayf(void *p, size_t nmemb, size_t size) +{ + void *q; +\& + q = reallocarray(p, nmemb, size); + if (q == NULL && nmemb != 0 && size != 0) + free(p); + return q; +} +\& +static char * +getcmd(void) +{ + static char buf[256]; +\& + fputs("> ", stdout); fflush(stdout); + if (fgets(buf, sizeof(buf), stdin) == NULL) + return NULL; +\& + if (buf[strlen(buf) \- 1] == \[aq]\en\[aq]) + buf[strlen(buf) \- 1] = 0; +\& + return buf; +} +\& +/* Add requests for specified hostnames. */ +static void +add_requests(void) +{ + size_t nreqs_base = nreqs; + char *host; + int ret; +\& + while ((host = strtok(NULL, " "))) { + nreqs++; + reqs = REALLOCF(reqs, nreqs, struct gaicb *); + if (reqs == NULL) + err(EXIT_FAILURE, "reallocf"); +\& + reqs[nreqs \- 1] = CALLOC(1, struct gaicb); + if (reqs[nreqs \- 1] == NULL) + err(EXIT_FAILURE, "calloc"); +\& + reqs[nreqs \- 1]\->ar_name = strdup(host); + } +\& + /* Queue nreqs_base..nreqs requests. */ +\& + ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base], + nreqs \- nreqs_base, NULL); + if (ret) { + fprintf(stderr, "getaddrinfo_a() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } +} +\& +/* Wait until at least one of specified requests completes. */ +static void +wait_requests(void) +{ + char *id; + int ret; + size_t n; + struct gaicb const **wait_reqs; +\& + wait_reqs = CALLOC(nreqs, const struct gaicb *); + if (wait_reqs == NULL) + err(EXIT_FAILURE, "calloc"); +\& + /* NULL elements are ignored by gai_suspend(). */ +\& + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); +\& + if (n >= nreqs) { + printf("Bad request number: %s\en", id); + return; + } +\& + wait_reqs[n] = reqs[n]; + } +\& + ret = gai_suspend(wait_reqs, nreqs, NULL); + if (ret) { + printf("gai_suspend(): %s\en", gai_strerror(ret)); + return; + } +\& + for (size_t i = 0; i < nreqs; i++) { + if (wait_reqs[i] == NULL) + continue; +\& + ret = gai_error(reqs[i]); + if (ret == EAI_INPROGRESS) + continue; +\& + printf("[%02zu] %s: %s\en", i, reqs[i]\->ar_name, + ret == 0 ? "Finished" : gai_strerror(ret)); + } +} +\& +/* Cancel specified requests. */ +static void +cancel_requests(void) +{ + char *id; + int ret; + size_t n; +\& + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); +\& + if (n >= nreqs) { + printf("Bad request number: %s\en", id); + return; + } +\& + ret = gai_cancel(reqs[n]); + printf("[%s] %s: %s\en", id, reqs[atoi(id)]\->ar_name, + gai_strerror(ret)); + } +} +\& +/* List all requests. */ +static void +list_requests(void) +{ + int ret; + char host[NI_MAXHOST]; + struct addrinfo *res; +\& + for (size_t i = 0; i < nreqs; i++) { + printf("[%02zu] %s: ", i, reqs[i]\->ar_name); + ret = gai_error(reqs[i]); +\& + if (!ret) { + res = reqs[i]\->ar_result; +\& + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret) { + fprintf(stderr, "getnameinfo() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); + } else { + puts(gai_strerror(ret)); + } + } +} +\& +int +main(void) +{ + char *cmdline; + char *cmd; +\& + while ((cmdline = getcmd()) != NULL) { + cmd = strtok(cmdline, " "); +\& + if (cmd == NULL) { + list_requests(); + } else { + switch (cmd[0]) { + case \[aq]a\[aq]: + add_requests(); + break; + case \[aq]w\[aq]: + wait_requests(); + break; + case \[aq]c\[aq]: + cancel_requests(); + break; + case \[aq]l\[aq]: + list_requests(); + break; + default: + fprintf(stderr, "Bad command: %c\en", cmd[0]); + break; + } + } + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR lio_listio (3), +.BR hostname (7), +.BR ip (7), +.BR sigevent (3type) diff --git a/man/man3/getaliasbyname.3 b/man/man3/getaliasbyname.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasbyname.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasbyname_r.3 b/man/man3/getaliasbyname_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasbyname_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasent.3 b/man/man3/getaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasent_r.3 b/man/man3/getaliasent_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasent_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getauxval.3 b/man/man3/getauxval.3 new file mode 100644 index 0000000..8639916 --- /dev/null +++ b/man/man3/getauxval.3 @@ -0,0 +1,272 @@ +'\" t +.\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" See also https://lwn.net/Articles/519085/ +.\" +.TH getauxval 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getauxval \- retrieve a value from the auxiliary vector +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/auxv.h> +.P +.BI "unsigned long getauxval(unsigned long " type ); +.fi +.SH DESCRIPTION +The +.BR getauxval () +function retrieves values from the auxiliary vector, +a mechanism that the kernel's ELF binary loader +uses to pass certain information to +user space when a program is executed. +.P +Each entry in the auxiliary vector consists of a pair of values: +a type that identifies what this entry represents, +and a value for that type. +Given the argument +.IR type , +.BR getauxval () +returns the corresponding value. +.P +The value returned for each +.I type +is given in the following list. +Not all +.I type +values are present on all architectures. +.TP +.B AT_BASE +The base address of the program interpreter (usually, the dynamic linker). +.TP +.B AT_BASE_PLATFORM +A pointer to a string (PowerPC and MIPS only). +On PowerPC, this identifies the real platform; may differ from +.BR AT_PLATFORM "." +On MIPS, +.\" commit e585b768da111f2c2d413de6214e83bbdfee8f22 +this identifies the ISA level (since Linux 5.7). +.TP +.B AT_CLKTCK +The frequency with which +.BR times (2) +counts. +This value can also be obtained via +.IR sysconf(_SC_CLK_TCK) . +.TP +.B AT_DCACHEBSIZE +The data cache block size. +.TP +.B AT_EGID +The effective group ID of the thread. +.TP +.B AT_ENTRY +The entry address of the executable. +.TP +.B AT_EUID +The effective user ID of the thread. +.TP +.B AT_EXECFD +File descriptor of program. +.TP +.B AT_EXECFN +A pointer to a string containing the pathname used to execute the program. +.TP +.B AT_FLAGS +Flags (unused). +.TP +.B AT_FPUCW +Used FPU control word (SuperH architecture only). +This gives some information about the FPU initialization +performed by the kernel. +.TP +.B AT_GID +The real group ID of the thread. +.TP +.B AT_HWCAP +An architecture and ABI dependent bit-mask whose settings +indicate detailed processor capabilities. +The contents of the bit mask are hardware dependent +(for example, see the kernel source file +.I arch/x86/include/asm/cpufeature.h +for details relating to the Intel x86 architecture; the value +returned is the first 32-bit word of the array described there). +A human-readable version of the same information is available via +.IR /proc/cpuinfo . +.TP +.BR AT_HWCAP2 " (since glibc 2.18)" +Further machine-dependent hints about processor capabilities. +.TP +.B AT_ICACHEBSIZE +The instruction cache block size. +.\" .TP +.\" .BR AT_IGNORE +.\" .TP +.\" .BR AT_IGNOREPPC +.\" .TP +.\" .BR AT_NOTELF +.TP +.\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147 +.B AT_L1D_CACHEGEOMETRY +Geometry of the L1 data cache, encoded with the cache line size in bytes +in the bottom 16 bits and the cache associativity in the next 16 bits. +The associativity is such that if N is the 16-bit value, +the cache is N-way set associative. +.TP +.B AT_L1D_CACHESIZE +The L1 data cache size. +.TP +.B AT_L1I_CACHEGEOMETRY +Geometry of the L1 instruction cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L1I_CACHESIZE +The L1 instruction cache size. +.TP +.B AT_L2_CACHEGEOMETRY +Geometry of the L2 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L2_CACHESIZE +The L2 cache size. +.TP +.B AT_L3_CACHEGEOMETRY +Geometry of the L3 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L3_CACHESIZE +The L3 cache size. +.TP +.B AT_PAGESZ +The system page size (the same value returned by +.IR sysconf(_SC_PAGESIZE) ). +.TP +.B AT_PHDR +The address of the program headers of the executable. +.TP +.B AT_PHENT +The size of program header entry. +.TP +.B AT_PHNUM +The number of program headers. +.TP +.B AT_PLATFORM +A pointer to a string that identifies the hardware platform +that the program is running on. +The dynamic linker uses this in the interpretation of +.I rpath +values. +.TP +.B AT_RANDOM +The address of sixteen bytes containing a random value. +.TP +.B AT_SECURE +Has a nonzero value if this executable should be treated securely. +Most commonly, a nonzero value indicates that the process is +executing a set-user-ID or set-group-ID binary +(so that its real and effective UIDs or GIDs differ from one another), +or that it gained capabilities by executing +a binary file that has capabilities (see +.BR capabilities (7)). +Alternatively, +a nonzero value may be triggered by a Linux Security Module. +When this value is nonzero, +the dynamic linker disables the use of certain environment variables (see +.BR ld\-linux.so (8)) +and glibc changes other aspects of its behavior. +(See also +.BR secure_getenv (3).) +.TP +.B AT_SYSINFO +The entry point to the system call function in the vDSO. +Not present/needed on all architectures (e.g., absent on x86-64). +.TP +.B AT_SYSINFO_EHDR +The address of a page containing the virtual Dynamic Shared Object (vDSO) +that the kernel creates in order to provide fast implementations of +certain system calls. +.TP +.B AT_UCACHEBSIZE +The unified cache block size. +.TP +.B AT_UID +The real user ID of the thread. +.SH RETURN VALUE +On success, +.BR getauxval () +returns the value corresponding to +.IR type . +If +.I type +is not found, 0 is returned. +.SH ERRORS +.TP +.BR ENOENT " (since glibc 2.19)" +.\" commit b9ab448f980e296eac21ac65f53783967cc6037b +No entry corresponding to +.I type +could be found in the auxiliary vector. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getauxval () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.16. +.SH NOTES +The primary consumer of the information in the auxiliary vector +is the dynamic linker, +.BR ld\-linux.so (8). +The auxiliary vector is a convenient and efficient shortcut +that allows the kernel to communicate a certain set of standard +information that the dynamic linker usually or always needs. +In some cases, the same information could be obtained by system calls, +but using the auxiliary vector is cheaper. +.P +The auxiliary vector resides just above the argument list and +environment in the process address space. +The auxiliary vector supplied to a program can be viewed by setting the +.B LD_SHOW_AUXV +environment variable when running a program: +.P +.in +4n +.EX +$ LD_SHOW_AUXV=1 sleep 1 +.EE +.in +.P +The auxiliary vector of any process can (subject to file permissions) +be obtained via +.IR /proc/ pid /auxv ; +see +.BR proc (5) +for more information. +.SH BUGS +Before the addition of the +.B ENOENT +error in glibc 2.19, +there was no way to unambiguously distinguish the case where +.I type +could not be found from the case where the value corresponding to +.I type +was zero. +.SH SEE ALSO +.BR execve (2), +.BR secure_getenv (3), +.BR vdso (7), +.BR ld\-linux.so (8) diff --git a/man/man3/getc.3 b/man/man3/getc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/getc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/getc_unlocked.3 b/man/man3/getc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getchar.3 b/man/man3/getchar.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/getchar.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/getchar_unlocked.3 b/man/man3/getchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getcontext.3 b/man/man3/getcontext.3 new file mode 100644 index 0000000..879cfe8 --- /dev/null +++ b/man/man3/getcontext.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getcontext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getcontext, setcontext \- get or set the user context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ucontext.h> +.P +.BI "int getcontext(ucontext_t *" ucp ); +.BI "int setcontext(const ucontext_t *" ucp ); +.fi +.SH DESCRIPTION +In a System V-like environment, one has the two types +.I mcontext_t +and +.I ucontext_t +defined in +.I <ucontext.h> +and the four functions +.BR getcontext (), +.BR setcontext (), +.BR makecontext (3), +and +.BR swapcontext (3) +that allow user-level context switching between multiple +threads of control within a process. +.P +The +.I mcontext_t +type is machine-dependent and opaque. +The +.I ucontext_t +type is a structure that has at least +the following fields: +.P +.in +4n +.EX +typedef struct ucontext_t { + struct ucontext_t *uc_link; + sigset_t uc_sigmask; + stack_t uc_stack; + mcontext_t uc_mcontext; + ... +} ucontext_t; +.EE +.in +.P +with +.I sigset_t +and +.I stack_t +defined in +.IR <signal.h> . +Here +.I uc_link +points to the context that will be resumed +when the current context terminates (in case the current context +was created using +.BR makecontext (3)), +.I uc_sigmask +is the +set of signals blocked in this context (see +.BR sigprocmask (2)), +.I uc_stack +is the stack used by this context (see +.BR sigaltstack (2)), +and +.I uc_mcontext +is the +machine-specific representation of the saved context, +that includes the calling thread's machine registers. +.P +The function +.BR getcontext () +initializes the structure +pointed to by +.I ucp +to the currently active context. +.P +The function +.BR setcontext () +restores the user context +pointed to by +.IR ucp . +A successful call does not return. +The context should have been obtained by a call of +.BR getcontext (), +or +.BR makecontext (3), +or received as the third argument to a signal +handler (see the discussion of the +.B SA_SIGINFO +flag in +.BR sigaction (2)). +.P +If the context was obtained by a call of +.BR getcontext (), +program execution continues as if this call just returned. +.P +If the context was obtained by a call of +.BR makecontext (3), +program execution continues by a call to the function +.I func +specified as the second argument of that call to +.BR makecontext (3). +When the function +.I func +returns, we continue with the +.I uc_link +member of the structure +.I ucp +specified as the +first argument of that call to +.BR makecontext (3). +When this member is NULL, the thread exits. +.P +If the context was obtained by a call to a signal handler, +then old standard text says that "program execution continues with the +program instruction following the instruction interrupted +by the signal". +However, this sentence was removed in SUSv2, +and the present verdict is "the result is unspecified". +.SH RETURN VALUE +When successful, +.BR getcontext () +returns 0 and +.BR setcontext () +does not return. +On error, both return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +None defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getcontext (), +.BR setcontext () +T} Thread safety MT-Safe race:ucp +.TE +.SH STANDARDS +None. +.SH HISTORY +SUSv2, POSIX.1-2001. +.P +POSIX.1-2008 removes these functions, +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The earliest incarnation of this mechanism was the +.BR setjmp (3)/\c +.BR longjmp (3) +mechanism. +Since that does not define +the handling of the signal context, the next stage was the +.BR sigsetjmp (3)/\c +.BR siglongjmp (3) +pair. +The present mechanism gives much more control. +On the other hand, +there is no easy way to detect whether a return from +.BR getcontext () +is from the first call, or via a +.BR setcontext () +call. +The user has to invent their own bookkeeping device, and a register +variable won't do since registers are restored. +.P +When a signal occurs, the current user context is saved and +a new context is created by the kernel for the signal handler. +Do not leave the handler using +.BR longjmp (3): +it is undefined what would happen with contexts. +Use +.BR siglongjmp (3) +or +.BR setcontext () +instead. +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR longjmp (3), +.BR makecontext (3), +.BR sigsetjmp (3), +.BR signal (7) diff --git a/man/man3/getcwd.3 b/man/man3/getcwd.3 new file mode 100644 index 0000000..ea3c4cf --- /dev/null +++ b/man/man3/getcwd.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de): +.\" Corrected description of getwd(). +.\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj +.\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb +.\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi <rl@hellgate.ch> +.\" +.TH getcwd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getcwd, getwd, get_current_dir_name \- get current working directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "char *getcwd(char " buf [. size "], size_t " size ); +.B "char *get_current_dir_name(void);" +.P +.BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR get_current_dir_name (): +.nf + _GNU_SOURCE +.fi +.P +.BR getwd (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +These functions return a null-terminated string containing an +absolute pathname that is the current working directory of +the calling process. +The pathname is returned as the function result and via the argument +.IR buf , +if present. +.P +The +.BR getcwd () +function copies an absolute pathname of the current working directory +to the array pointed to by +.IR buf , +which is of length +.IR size . +.P +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.I size +bytes, NULL is returned, and +.I errno +is set to +.BR ERANGE ; +an application should check for this error, and allocate a larger +buffer if necessary. +.P +As an extension to the POSIX.1-2001 standard, glibc's +.BR getcwd () +allocates the buffer dynamically using +.BR malloc (3) +if +.I buf +is NULL. +In this case, the allocated buffer has the length +.I size +unless +.I size +is zero, when +.I buf +is allocated as big as necessary. +The caller should +.BR free (3) +the returned buffer. +.P +.BR get_current_dir_name () +will +.BR malloc (3) +an array big enough to hold the absolute pathname of +the current working directory. +If the environment +variable +.B PWD +is set, and its value is correct, then that value will be returned. +The caller should +.BR free (3) +the returned buffer. +.P +.BR getwd () +does not +.BR malloc (3) +any memory. +The +.I buf +argument should be a pointer to an array at least +.B PATH_MAX +bytes long. +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.B PATH_MAX +bytes, NULL is returned, and +.I errno +is set to +.BR ENAMETOOLONG . +(Note that on some systems, +.B PATH_MAX +may not be a compile-time constant; +furthermore, its value may depend on the filesystem, see +.BR pathconf (3).) +For portability and security reasons, use of +.BR getwd () +is deprecated. +.SH RETURN VALUE +On success, these functions return a pointer to a string containing +the pathname of the current working directory. +In the case of +.BR getcwd () +and +.BR getwd () +this is the same value as +.IR buf . +.P +On failure, these functions return NULL, and +.I errno +is set to indicate the error. +The contents of the array pointed to by +.I buf +are undefined on error. +.SH ERRORS +.TP +.B EACCES +Permission to read or search a component of the filename was denied. +.TP +.B EFAULT +.I buf +points to a bad address. +.TP +.B EINVAL +The +.I size +argument is zero and +.I buf +is not a null pointer. +.TP +.B EINVAL +.BR getwd (): +.I buf +is NULL. +.TP +.B ENAMETOOLONG +.BR getwd (): +The size of the null-terminated absolute pathname string exceeds +.B PATH_MAX +bytes. +.TP +.B ENOENT +The current working directory has been unlinked. +.TP +.B ENOMEM +Out of memory. +.TP +.B ERANGE +The +.I size +argument is less than the length of the absolute pathname of the +working directory, including the terminating null byte. +You need to allocate a bigger array and try again. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getcwd (), +.BR getwd () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR get_current_dir_name () +T} Thread safety MT-Safe env +.TE +.SH VERSIONS +POSIX.1-2001 leaves the behavior of +.BR getcwd () +unspecified if +.I buf +is NULL. +.P +POSIX.1-2001 +does not define any errors for +.BR getwd (). +.SH VERSIONS +.SS C library/kernel differences +On Linux, the kernel provides a +.BR getcwd () +system call, which the functions described in this page will use if possible. +The system call takes the same arguments as the library function +of the same name, but is limited to returning at most +.B PATH_MAX +bytes. +(Before Linux 3.12, +.\" commit 3272c544da48f8915a0e34189182aed029bd0f2b +the limit on the size of the returned pathname was the system page size. +On many architectures, +.B PATH_MAX +and the system page size are both 4096 bytes, +but a few architectures have a larger page size.) +If the length of the pathname of the current working directory +exceeds this limit, then the system call fails with the error +.BR ENAMETOOLONG . +In this case, the library functions fall back to +a (slower) alternative implementation that returns the full pathname. +.P +Following a change in Linux 2.6.36, +.\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74 +the pathname returned by the +.BR getcwd () +system call will be prefixed with the string "(unreachable)" +if the current directory is not below the root directory of the current +process (e.g., because the process set a new filesystem root using +.BR chroot (2) +without changing its current directory into the new root). +Such behavior can also be caused by an unprivileged user by changing +the current directory into another mount namespace. +When dealing with pathname from untrusted sources, callers of the +functions described in this page +should consider checking whether the returned pathname starts +with '/' or '(' to avoid misinterpreting an unreachable path +as a relative pathname. +.SH STANDARDS +.TP +.BR getcwd () +POSIX.1-2008. +.TP +.BR get_current_dir_name () +GNU. +.TP +.BR getwd () +None. +.SH HISTORY +.TP +.BR getcwd () +POSIX.1-2001. +.TP +.BR getwd () +POSIX.1-2001, but marked LEGACY. +Removed in POSIX.1-2008. +Use +.BR getcwd () +instead. +.P +Under Linux, these functions make use of the +.BR getcwd () +system call (available since Linux 2.1.92). +On older systems they would query +.IR /proc/self/cwd . +If both system call and proc filesystem are missing, a +generic implementation is called. +Only in that case can +these calls fail under Linux with +.BR EACCES . +.SH NOTES +These functions are often used to save the location of the current working +directory for the purpose of returning to it later. +Opening the current +directory (".") and calling +.BR fchdir (2) +to return is usually a faster and more reliable alternative when sufficiently +many file descriptors are available, especially on platforms other than Linux. +.SH BUGS +Since the Linux 2.6.36 change that added "(unreachable)" in the +circumstances described above, the glibc implementation of +.BR getcwd () +has failed to conform to POSIX and returned a relative pathname when the API +contract requires an absolute pathname. +With glibc 2.27 onwards this is corrected; +calling +.BR getcwd () +from such a pathname will now result in failure with +.BR ENOENT . +.SH SEE ALSO +.BR pwd (1), +.BR chdir (2), +.BR fchdir (2), +.BR open (2), +.BR unlink (2), +.BR free (3), +.BR malloc (3) diff --git a/man/man3/getdate.3 b/man/man3/getdate.3 new file mode 100644 index 0000000..f710356 --- /dev/null +++ b/man/man3/getdate.3 @@ -0,0 +1,322 @@ +'\" t +.\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 2001-12-26, aeb +.\" 2008-09-07, mtk, Various rewrites; added an example program. +.\" +.TH getdate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdate, getdate_r \- convert a date-plus-time string to broken-down time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <time.h>" +.P +.BI "struct tm *getdate(const char *" string ); +.P +.B "extern int getdate_err;" +.P +.BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.P +.BR getdate_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The function +.BR getdate () +converts a string representation of a date and time, +contained in the buffer pointed to by +.IR string , +into a broken-down time. +The broken-down time is stored in a +.I tm +structure, and a pointer to this +structure is returned as the function result. +This +.I tm +structure is allocated in static storage, +and consequently it will be overwritten by further calls to +.BR getdate (). +.P +In contrast to +.BR strptime (3), +(which has a +.I format +argument), +.BR getdate () +uses the formats found in the file +whose full pathname is given in the environment variable +.BR DATEMSK . +The first line in the file that matches the given input string +is used for the conversion. +.P +The matching is done case insensitively. +Superfluous whitespace, either in the pattern or in the string to +be converted, is ignored. +.P +The conversion specifications that a pattern can contain are those given for +.BR strptime (3). +One more conversion specification is specified in POSIX.1-2001: +.TP +.B %Z +Timezone name. +.\" FIXME Is it (still) true that %Z is not supported in glibc? +.\" Looking at the glibc 2.21 source code, where the implementation uses +.\" strptime(), suggests that it might be supported. +This is not implemented in glibc. +.P +When +.B %Z +is given, the structure containing the broken-down time +is initialized with values corresponding to the current +time in the given timezone. +Otherwise, the structure is initialized to the broken-down time +corresponding to the current local time (as by a call to +.BR localtime (3)). +.P +When only the day of the week is given, +the day is taken to be the first such day +on or after today. +.P +When only the month is given (and no year), the month is taken to +be the first such month equal to or after the current month. +If no day is given, it is the first day of the month. +.P +When no hour, minute, and second are given, the current +hour, minute, and second are taken. +.P +If no date is given, but we know the hour, then that hour is taken +to be the first such hour equal to or after the current hour. +.P +.BR getdate_r () +is a GNU extension that provides a reentrant version of +.BR getdate (). +Rather than using a global variable to report errors and a static buffer +to return the broken down time, +it returns errors via the function result value, +and returns the resulting broken-down time in the +caller-allocated buffer pointed to by the argument +.IR res . +.SH RETURN VALUE +When successful, +.BR getdate () +returns a pointer to a +.IR "struct tm" . +Otherwise, it returns NULL and sets the global variable +.I getdate_err +to one of the error numbers shown below. +Changes to +.I errno +are unspecified. +.P +On success +.BR getdate_r () +returns 0; +on error it returns one of the error numbers shown below. +.SH ERRORS +The following errors are returned via +.I getdate_err +(for +.BR getdate ()) +or as the function result (for +.BR getdate_r ()): +.TP 4n +.B 1 +The +.B DATEMSK +environment variable is not defined, or its value is an empty string. +.TP +.B 2 +The template file specified by +.B DATEMSK +cannot be opened for reading. +.TP +.B 3 +Failed to get file status information. +.\" stat() +.TP +.B 4 +The template file is not a regular file. +.TP +.B 5 +An error was encountered while reading the template file. +.TP +.B 6 +Memory allocation failed (not enough memory available). +.\" Error 6 doesn't seem to occur in glibc +.TP +.B 7 +There is no line in the file that matches the input. +.TP +.B 8 +Invalid input specification. +.SH ENVIRONMENT +.TP +.B DATEMSK +File containing format patterns. +.TP +.B TZ +.TQ +.B LC_TIME +Variables used by +.BR strptime (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdate () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getdate env locale +T} +T{ +.na +.nh +.BR getdate_r () +T} Thread safety T{ +.na +.nh +MT-Safe env locale +T} +.TE +.SH VERSIONS +The POSIX.1 specification for +.BR strptime (3) +contains conversion specifications using the +.B %E +or +.B %O +modifier, while such specifications are not given for +.BR getdate (). +In glibc, +.BR getdate () +is implemented using +.BR strptime (3), +so that precisely the same conversions are supported by both. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The program below calls +.BR getdate () +for each of its command-line arguments, +and for each call displays the values in the fields of the returned +.I tm +structure. +The following shell session demonstrates the operation of the program: +.P +.in +4n +.EX +.RB "$" " TFILE=$PWD/tfile" +.RB "$" " echo \[aq]%A\[aq] > $TFILE " " # Full name of the day of the week" +.RB "$" " echo \[aq]%T\[aq] >> $TFILE" " # Time (HH:MM:SS)" +.RB "$" " echo \[aq]%F\[aq] >> $TFILE" " # ISO date (YYYY\-MM\-DD)" +.RB "$" " date" +.RB "$" " export DATEMSK=$TFILE" +.RB "$" " ./a.out Tuesday \[aq]2009\-12\-28\[aq] \[aq]12:22:33\[aq]" +Sun Sep 7 06:03:36 CEST 2008 +Call 1 ("Tuesday") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 9 + tm_mon = 8 + tm_year = 108 + tm_wday = 2 + tm_yday = 252 + tm_isdst = 1 +Call 2 ("2009\-12\-28") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 28 + tm_mon = 11 + tm_year = 109 + tm_wday = 1 + tm_yday = 361 + tm_isdst = 0 +Call 3 ("12:22:33") succeeded: + tm_sec = 33 + tm_min = 22 + tm_hour = 12 + tm_mday = 7 + tm_mon = 8 + tm_year = 108 + tm_wday = 0 + tm_yday = 250 + tm_isdst = 1 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getdate.c) +.EX +#define _GNU_SOURCE +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +\& +int +main(int argc, char *argv[]) +{ + struct tm *tmp; +\& + for (size_t j = 1; j < argc; j++) { + tmp = getdate(argv[j]); +\& + if (tmp == NULL) { + printf("Call %zu failed; getdate_err = %d\en", + j, getdate_err); + continue; + } +\& + printf("Call %zu (\e"%s\e") succeeded:\en", j, argv[j]); + printf(" tm_sec = %d\en", tmp\->tm_sec); + printf(" tm_min = %d\en", tmp\->tm_min); + printf(" tm_hour = %d\en", tmp\->tm_hour); + printf(" tm_mday = %d\en", tmp\->tm_mday); + printf(" tm_mon = %d\en", tmp\->tm_mon); + printf(" tm_year = %d\en", tmp\->tm_year); + printf(" tm_wday = %d\en", tmp\->tm_wday); + printf(" tm_yday = %d\en", tmp\->tm_yday); + printf(" tm_isdst = %d\en", tmp\->tm_isdst); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3) diff --git a/man/man3/getdate_err.3 b/man/man3/getdate_err.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man/man3/getdate_err.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man/man3/getdate_r.3 b/man/man3/getdate_r.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man/man3/getdate_r.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man/man3/getdelim.3 b/man/man3/getdelim.3 new file mode 100644 index 0000000..caf4e48 --- /dev/null +++ b/man/man3/getdelim.3 @@ -0,0 +1 @@ +.so man3/getline.3 diff --git a/man/man3/getdirentries.3 b/man/man3/getdirentries.3 new file mode 100644 index 0000000..3eae3f0 --- /dev/null +++ b/man/man3/getdirentries.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/dirent.h are: +.\" Copyright 1991, 1992 Free Software Foundation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getdirentries 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdirentries \- get directory entries in a filesystem-independent format +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "ssize_t getdirentries(int " fd ", char " buf "[restrict ." nbytes "], \ +size_t " nbytes , +.BI " off_t *restrict " basep ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdirentries (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Read directory entries from the directory specified by +.I fd +into +.IR buf . +At most +.I nbytes +are read. +Reading starts at offset +.IR *basep , +and +.I *basep +is updated with the new position after reading. +.SH RETURN VALUE +.BR getdirentries () +returns the number of bytes read or zero when at the end of the directory. +If an error occurs, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See the Linux library source code for details. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdirentries () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH NOTES +Use +.BR opendir (3) +and +.BR readdir (3) +instead. +.SH SEE ALSO +.BR lseek (2), +.BR open (2) diff --git a/man/man3/getdtablesize.3 b/man/man3/getdtablesize.3 new file mode 100644 index 0000000..f9b24c0 --- /dev/null +++ b/man/man3/getdtablesize.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-04-15 by Roger Luethi <rl@hellgate.ch> and aeb +.\" +.TH getdtablesize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdtablesize \- get file descriptor table size +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B int getdtablesize(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdtablesize (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + glibc 2.12 to glibc 2.19: + _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.BR getdtablesize () +returns the maximum number of files a process can have open, +one more than the largest possible value for a file descriptor. +.SH RETURN VALUE +The current limit on the number of open files per process. +.SH ERRORS +On Linux, +.BR getdtablesize () +can return any of the errors described for +.BR getrlimit (2); +see NOTES below. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdtablesize () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc version of +.BR getdtablesize () +calls +.BR getrlimit (2) +and returns the current +.B RLIMIT_NOFILE +limit, or +.B OPEN_MAX +when that fails. +.\" The libc4 and libc5 versions return +.\" .B OPEN_MAX +.\" (set to 256 since Linux 0.98.4). +.P +Portable applications should employ +.I sysconf(_SC_OPEN_MAX) +instead of this call. +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.4BSD +(first appeared in 4.2BSD). +.SH SEE ALSO +.BR close (2), +.BR dup (2), +.BR getrlimit (2), +.BR open (2) diff --git a/man/man3/getentropy.3 b/man/man3/getentropy.3 new file mode 100644 index 0000000..4f5d3f8 --- /dev/null +++ b/man/man3/getentropy.3 @@ -0,0 +1,103 @@ +.\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getentropy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getentropy \- fill a buffer with random bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int getentropy(void " buffer [. length "], size_t " length ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getentropy (): +.nf + _DEFAULT_SOURCE +.fi +.SH DESCRIPTION +The +.BR getentropy () +function writes +.I length +bytes of high-quality random data to the buffer starting +at the location pointed to by +.IR buffer . +The maximum permitted value for the +.I length +argument is 256. +.P +A successful call to +.BR getentropy () +always provides the requested number of bytes of entropy. +.SH RETURN VALUE +On success, this function returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part or all of the buffer specified by +.I buffer +and +.I length +is not in valid addressable memory. +.TP +.B EIO +.I length +is greater than 256. +.TP +.B EIO +An unspecified error occurred while trying to overwrite +.I buffer +with random data. +.TP +.B ENOSYS +This kernel version does not implement the +.BR getrandom (2) +system call required to implement this function. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.25. +OpenBSD. +.SH NOTES +The +.BR getentropy () +function is implemented using +.BR getrandom (2). +.P +Whereas the glibc wrapper makes +.BR getrandom (2) +a cancelation point, +.BR getentropy () +is not a cancelation point. +.P +.BR getentropy () +is also declared in +.BR <sys/random.h> . +(No feature test macro need be defined to obtain the declaration from +that header file.) +.P +A call to +.BR getentropy () +may block if the system has just booted and the kernel has +not yet collected enough randomness to initialize the entropy pool. +In this case, +.BR getentropy () +will keep blocking even if a signal is handled, +and will return only once the entropy pool has been initialized. +.SH SEE ALSO +.BR getrandom (2), +.BR urandom (4), +.BR random (7) diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 new file mode 100644 index 0000000..c0105df --- /dev/null +++ b/man/man3/getenv.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2007, 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH getenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getenv, secure_getenv \- get an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "char *getenv(const char *" name ); +.BI "char *secure_getenv(const char *" name ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR secure_getenv (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR getenv () +function searches the environment list to find the +environment variable +.IR name , +and returns a pointer to the corresponding +.I value +string. +.P +The GNU-specific +.BR secure_getenv () +function is just like +.BR getenv () +except that it returns NULL in cases where "secure execution" is required. +Secure execution is required if one of the following conditions +was true when the program run by the calling process was loaded: +.IP \[bu] 3 +the process's effective user ID did not match its real user ID or +the process's effective group ID did not match its real group ID +(typically this is the result of executing a set-user-ID or +set-group-ID program); +.IP \[bu] +the effective capability bit was set on the executable file; or +.IP \[bu] +the process has a nonempty permitted capability set. +.P +Secure execution may also be required if triggered +by some Linux security modules. +.P +The +.BR secure_getenv () +function is intended for use in general-purpose libraries +to avoid vulnerabilities that could occur if +set-user-ID or set-group-ID programs accidentally +trusted the environment. +.SH RETURN VALUE +The +.BR getenv () +function returns a pointer to the value in the +environment, or NULL if there is no match. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getenv (), +.BR secure_getenv () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +.TP +.BR getenv () +C11, POSIX.1-2008. +.TP +.BR secure_getenv () +GNU. +.SH HISTORY +.TP +.BR getenv () +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.TP +.BR secure_getenv () +glibc 2.17. +.SH NOTES +The strings in the environment list are of the form \fIname=value\fP. +.P +As typically implemented, +.BR getenv () +returns a pointer to a string within the environment list. +The caller must take care not to modify this string, +since that would change the environment of the process. +.P +The implementation of +.BR getenv () +is not required to be reentrant. +The string pointed to by the return value of +.BR getenv () +may be statically allocated, +and can be modified by a subsequent call to +.BR getenv (), +.BR putenv (3), +.BR setenv (3), +or +.BR unsetenv (3). +.P +The "secure execution" mode of +.BR secure_getenv () +is controlled by the +.B AT_SECURE +flag contained in the auxiliary vector passed from the kernel to user space. +.SH SEE ALSO +.BR clearenv (3), +.BR getauxval (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR capabilities (7), +.BR environ (7) diff --git a/man/man3/getfsent.3 b/man/man3/getfsent.3 new file mode 100644 index 0000000..87f3d8a --- /dev/null +++ b/man/man3/getfsent.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page written by Walter Harms. +.\" +.TH getfsent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <fstab.h> +.P +.B "int setfsent(void);" +.B "struct fstab *getfsent(void);" +.B "void endfsent(void);" +.P +.BI "struct fstab *getfsfile(const char *" mount_point ); +.BI "struct fstab *getfsspec(const char *" special_file ); +.fi +.SH DESCRIPTION +These functions read from the file +.IR /etc/fstab . +The +.I struct fstab +is defined by: +.P +.in +4n +.EX +struct fstab { + char *fs_spec; /* block device name */ + char *fs_file; /* mount point */ + char *fs_vfstype; /* filesystem type */ + char *fs_mntops; /* mount options */ + const char *fs_type; /* rw/rq/ro/sw/xx option */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel dump */ +}; +.EE +.in +.P +Here the field +.I fs_type +contains (on a *BSD system) +one of the five strings "rw", "rq", "ro", "sw", "xx" +(read-write, read-write with quota, read-only, swap, ignore). +.P +The function +.BR setfsent () +opens the file when required and positions it at the first line. +.P +The function +.BR getfsent () +parses the next line from the file. +(After opening it when required.) +.P +The function +.BR endfsent () +closes the file when required. +.P +The function +.BR getfsspec () +searches the file from the start and returns the first entry found +for which the +.I fs_spec +field matches the +.I special_file +argument. +.P +The function +.BR getfsfile () +searches the file from the start and returns the first entry found +for which the +.I fs_file +field matches the +.I mount_point +argument. +.SH RETURN VALUE +Upon success, the functions +.BR getfsent (), +.BR getfsfile (), +and +.BR getfsspec () +return a pointer to a +.IR "struct fstab" , +while +.BR setfsent () +returns 1. +Upon failure or end-of-file, these functions return NULL and 0, respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR endfsent (), +.BR setfsent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fsent +T} +T{ +.na +.nh +.BR getfsent (), +.BR getfsspec (), +.BR getfsfile () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fsent locale +T} +.TE +.SH VERSIONS +Several operating systems have these functions, for example, +*BSD, SunOS, Digital UNIX, AIX (which also has a +.BR getfstype ()). +HP-UX has functions of the same names, +that however use a +.I struct checklist +instead of a +.IR "struct fstab" , +and calls these functions obsolete, superseded by +.BR getmntent (3). +.SH STANDARDS +None. +.SH HISTORY +The +.BR getfsent () +function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. +.SH NOTES +These functions are not thread-safe. +.P +Since Linux allows mounting a block special device in several places, +and since several devices can have the same mount point, where the +last device with a given mount point is the interesting one, +while +.BR getfsfile () +and +.BR getfsspec () +only return the first occurrence, these two functions are not suitable +for use under Linux. +.SH SEE ALSO +.BR getmntent (3), +.BR fstab (5) diff --git a/man/man3/getfsfile.3 b/man/man3/getfsfile.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/getfsfile.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/getfsspec.3 b/man/man3/getfsspec.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/getfsspec.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/getgrent.3 b/man/man3/getgrent.3 new file mode 100644 index 0000000..a9c937b --- /dev/null +++ b/man/man3/getgrent.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) +.TH getgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrent, setgrent, endgrent \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <grp.h> +.P +.B struct group *getgrent(void); +.P +.B void setgrent(void); +.B void endgrent(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setgrent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR getgrent (), +.BR endgrent (): +.nf + Since glibc 2.22: + _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + glibc 2.21 and earlier + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrent () +function returns a pointer to a structure containing +the broken-out fields of a record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP). +The first time +.BR getgrent () +is called, +it returns the first entry; thereafter, it returns successive entries. +.P +The +.BR setgrent () +function rewinds to the beginning +of the group database, to allow repeated scans. +.P +The +.BR endgrent () +function is used to close the group database +after all processing has been performed. +.P +The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.SH RETURN VALUE +The +.BR getgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +.P +Upon error, +.I errno +may be set. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (), +.BR getgrgid (3), +or +.BR getgrnam (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EAGAIN +The service was temporarily unavailable; try again later. +For NSS backends in glibc +this indicates a temporary error talking to the backend. +The error may correct itself, retrying later is suggested. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.\" not in POSIX +.B ENOENT +A necessary input file cannot be found. +For NSS backends in glibc +this indicates the backend is not correctly configured. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent +race:grentbuf locale +T} +T{ +.na +.nh +.BR setgrent (), +.BR endgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (), +.BR getgrent (), +or +.BR endgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent_r (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR getgrouplist (3), +.BR putgrent (3), +.BR group (5) diff --git a/man/man3/getgrent_r.3 b/man/man3/getgrent_r.3 new file mode 100644 index 0000000..23da51f --- /dev/null +++ b/man/man3/getgrent_r.3 @@ -0,0 +1,228 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getgrent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrent_r, fgetgrent_r \- get group file entry reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <grp.h> +.P +.BI "int getgrent_r(struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.BI "int fgetgrent_r(FILE *restrict " stream ", struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrent_r (): +.nf + _GNU_SOURCE +.fi +.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? +.P +.BR fgetgrent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR getgrent_r () +and +.BR fgetgrent_r () +are the reentrant versions of +.BR getgrent (3) +and +.BR fgetgrent (3). +The former reads the next group entry from the stream initialized by +.BR setgrent (3). +The latter reads the next group entry from +.IR stream . +.P +The \fIgroup\fP structure is defined in +.I <grp.h> +as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.P +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to group +name, password, and members. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I gbuf +that can hold a \fIstruct group\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct group\fP read from the stream, +is stored in the provided buffer +.IR *gbuf , +and a pointer to this \fIstruct group\fP is returned in +.IR *gbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *gbufp +is a pointer to the \fIstruct group\fP. +On error, these functions return an error value and +.I *gbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +T{ +.na +.nh +.BR fgetgrent_r () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (3), +.BR getgrent (3), +.BR endgrent (3), +or +.BR getgrent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Other systems use the prototype +.P +.in +4n +.EX +struct group *getgrent_r(struct group *grp, char *buf, + int buflen); +.EE +.in +.P +or, better, +.P +.in +4n +.EX +int getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.EE +.in +.SH STANDARDS +GNU. +.SH HISTORY +These functions are done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +.SH NOTES +The function +.BR getgrent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLES +.\" SRC BEGIN (getgrent_r.c) +.EX +#define _GNU_SOURCE +#include <grp.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#define BUFLEN 4096 +\& +int +main(void) +{ + struct group grp; + struct group *grpp; + char buf[BUFLEN]; + int i; +\& + setgrent(); + while (1) { + i = getgrent_r(&grp, buf, sizeof(buf), &grpp); + if (i) + break; + printf("%s (%jd):", grpp\->gr_name, (intmax_t) grpp\->gr_gid); + for (size_t j = 0; ; j++) { + if (grpp\->gr_mem[j] == NULL) + break; + printf(" %s", grpp\->gr_mem[j]); + } + printf("\en"); + } + endgrent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include <errno.h> +.\" #include <stdlib.h> +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getgrent_r: %s", strerror(i)); +.\" exit(EXIT_FAILURE); +.\" } +.\" SRC END +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR group (5) diff --git a/man/man3/getgrgid.3 b/man/man3/getgrgid.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrgid.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrgid_r.3 b/man/man3/getgrgid_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrgid_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrnam.3 b/man/man3/getgrnam.3 new file mode 100644 index 0000000..d19d414 --- /dev/null +++ b/man/man3/getgrnam.3 @@ -0,0 +1,260 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-11-15 by aeb +.\" +.TH getgrnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <grp.h> +.P +.BI "struct group *getgrnam(const char *" name ); +.BI "struct group *getgrgid(gid_t " gid ); +.P +.BI "int getgrnam_r(const char *restrict " name \ +", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.BI "int getgrgid_r(gid_t " gid ", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrnam_r (), +.BR getgrgid_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP) +that matches the group name +.IR name . +.P +The +.BR getgrgid () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +that matches the group ID +.IR gid . +.P +The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.P +The +.BR getgrnam_r () +and +.BR getgrgid_r () +functions obtain the same information as +.BR getgrnam () +and +.BR getgrgid (), +but store the retrieved +.I group +structure +in the space pointed to by +.IR grp . +The string fields pointed to by the members of the +.I group +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.P +The call +.P +.in +4n +.EX +sysconf(_SC_GETGR_R_SIZE_MAX) +.EE +.in +.P +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getgrnam () +and +.BR getgrgid () +functions return a pointer to a +.I group +structure, or NULL if the matching entry +is not found or an error occurs. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (3), +.BR getgrgid (), +or +.BR getgrnam (). +(Do not pass the returned pointer to +.BR free (3).) +.P +On success, +.BR getgrnam_r () +and +.BR getgrgid_r () +return zero, and set +.I *result +to +.IR grp . +If no matching group record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..." +The given +.I name +or +.I gid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.\" to allocate the group structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grnam locale +T} +T{ +.na +.nh +.BR getgrgid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grgid locale +T} +T{ +.na +.nh +.BR getgrnam_r (), +.BR getgrgid_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +The formulation given above under "RETURN VALUE" is from POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT +.\" since glibc 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent (3), +.BR getgrent (3), +.BR getpwnam (3), +.BR setgrent (3), +.BR group (5) diff --git a/man/man3/getgrnam_r.3 b/man/man3/getgrnam_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrnam_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrouplist.3 b/man/man3/getgrouplist.3 new file mode 100644 index 0000000..4a8f5fb --- /dev/null +++ b/man/man3/getgrouplist.3 @@ -0,0 +1,205 @@ +'\" t +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" A few pieces remain from an earlier version written in +.\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getgrouplist 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrouplist \- get list of groups to which a user belongs +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <grp.h> +.P +.BI "int getgrouplist(const char *" user ", gid_t " group , +.BI " gid_t *" groups ", int *" ngroups ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrouplist (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrouplist () +function scans the group database (see +.BR group (5)) +to obtain the list of groups that +.I user +belongs to. +Up to +.I *ngroups +of these groups are returned in the array +.IR groups . +.P +If it was not among the groups defined for +.I user +in the group database, then +.I group +is included in the list of groups returned by +.BR getgrouplist (); +typically this argument is specified as the group ID from +the password record for +.IR user . +.P +The +.I ngroups +argument is a value-result argument: +on return it always contains the number of groups found for +.IR user , +including +.IR group ; +this value may be greater than the number of groups stored in +.IR groups . +.SH RETURN VALUE +If the number of groups of which +.I user +is a member is less than or equal to +.IR *ngroups , +then the value +.I *ngroups +is returned. +.P +If the user is a member of more than +.I *ngroups +groups, then +.BR getgrouplist () +returns \-1. +In this case, the value returned in +.I *ngroups +can be used to resize the buffer passed to a further call to +.BR getgrouplist (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrouplist () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.2.4. +.SH BUGS +Before glibc 2.3.3, +the implementation of this function contains a buffer-overrun bug: +it returns the complete list of groups for +.I user +in the array +.IR groups , +even when the number of groups exceeds +.IR *ngroups . +.SH EXAMPLES +The program below displays the group list for the user named in its +first command-line argument. +The second command-line argument specifies the +.I ngroups +value to be supplied to +.BR getgrouplist (). +The following shell session shows examples of the use of this program: +.P +.in +4n +.EX +.RB "$" " ./a.out cecilia 0" +getgrouplist() returned \-1; ngroups = 3 +.RB "$" " ./a.out cecilia 3" +ngroups = 3 +16 (dialout) +33 (video) +100 (users) +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getgrouplist.c) +.EX +#include <errno.h> +#include <grp.h> +#include <pwd.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + int ngroups; + gid_t *groups; + struct group *gr; + struct passwd *pw; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + ngroups = atoi(argv[2]); +\& + groups = malloc(sizeof(*groups) * ngroups); + if (groups == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* Fetch passwd structure (contains first group ID for user). */ +\& + errno = 0; + pw = getpwnam(argv[1]); + if (pw == NULL) { + if (errno) + perror("getpwnam"); + else + fprintf(stderr, "no such user\en"); + exit(EXIT_FAILURE); + } +\& + /* Retrieve group list. */ +\& + if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) { + fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en", + ngroups); + exit(EXIT_FAILURE); + } +\& + /* Display list of retrieved groups, along with group names. */ +\& + fprintf(stderr, "ngroups = %d\en", ngroups); + for (int j = 0; j < ngroups; j++) { + printf("%d", groups[j]); + gr = getgrgid(groups[j]); + if (gr != NULL) + printf(" (%s)", gr\->gr_name); + printf("\en"); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR getgrent (3), +.BR group_member (3), +.BR group (5), +.BR passwd (5) diff --git a/man/man3/gethostbyaddr.3 b/man/man3/gethostbyaddr.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyaddr.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyaddr_r.3 b/man/man3/gethostbyaddr_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname.3 b/man/man3/gethostbyname.3 new file mode 100644 index 0000000..88ca5ac --- /dev/null +++ b/man/man3/gethostbyname.3 @@ -0,0 +1,553 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-05-22, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) +.\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2002-08-05, Michael Kerrisk +.\" Modified 2004-10-31, Andries Brouwer +.\" +.TH gethostbyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, +h_errno, +herror, hstrerror, +gethostbyaddr_r, +gethostbyname2, gethostbyname2_r, gethostbyname_r, +gethostent_r \- get network host entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "void sethostent(int " stayopen ); +.B void endhostent(void); +.P +.B [[deprecated]] extern int h_errno; +.P +.BI "[[deprecated]] struct hostent *gethostbyname(const char *" name ); +.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ], +.BI " socklen_t " len ", int " type ); +.P +.BI "[[deprecated]] void herror(const char *" s ); +.BI "[[deprecated]] const char *hstrerror(int " err ); +.P +/* System V/POSIX extension */ +.B struct hostent *gethostent(void); +.P +/* GNU extensions */ +.B [[deprecated]] +.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); +.P +.BI "int gethostent_r(struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.P +.B [[deprecated]] +.BI "int gethostbyaddr_r(const void " addr "[restrict ." len "], socklen_t " len , +.BI " int " type , +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.B [[deprecated]] +.BI "int gethostbyname_r(const char *restrict " name , +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.B [[deprecated]] +.BI "int gethostbyname2_r(const char *restrict " name ", int " af, +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostbyname2 (), +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc up to and including 2.19: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR herror (), +.BR hstrerror (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.8 to glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.8: + none +.fi +.P +.BR h_errno : +.nf + Since glibc 2.19 + _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L + glibc 2.12 to glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L + Before glibc 2.12: + none +.fi +.SH DESCRIPTION +The +.BR gethostbyname* (), +.BR gethostbyaddr* (), +.BR herror (), +and +.BR hstrerror () +functions are obsolete. +Applications should use +.BR getaddrinfo (3), +.BR getnameinfo (3), +and +.BR gai_strerror (3) +instead. +.P +The +.BR sethostent () +function specifies, if \fIstayopen\fP is true (1), +that a connected TCP socket should be used for the name server queries and +that the connection should remain open during successive queries. +Otherwise, name server queries will use UDP datagrams. +.P +The +.BR endhostent () +function ends the use of a TCP connection for name +server queries. +.P +The +.BR gethostbyname () +function returns a structure of type +.I hostent +for the given host +.IR name . +Here +.I name +is either a hostname or an IPv4 address in standard dot notation (as for +.BR inet_addr (3)). +If +.I name +is an IPv4 address, no lookup is performed and +.BR gethostbyname () +simply copies +.I name +into the +.I h_name +field and its +.I struct in_addr +equivalent into the +.I h_addr_list[0] +field of the returned +.I hostent +structure. +If +.I name +doesn't end in a dot and the environment variable +.B HOSTALIASES +is set, the alias file pointed to by +.B HOSTALIASES +will first be searched for +.I name +(see +.BR hostname (7) +for the file format). +The current domain and its parents are searched unless \fIname\fP +ends in a dot. +.P +The +.BR gethostbyaddr () +function returns a structure of type \fIhostent\fP +for the given host address \fIaddr\fP of length \fIlen\fP and address type +\fItype\fP. +Valid address types are +.B AF_INET +and +.B AF_INET6 +(defined in +.IR <sys/socket.h> ). +The host address argument is a pointer to a struct of a type depending +on the address type, for example a \fIstruct in_addr *\fP (probably +obtained via a call to +.BR inet_addr (3)) +for address type +.BR AF_INET . +.P +The (obsolete) +.BR herror () +function prints the error message associated +with the current value of \fIh_errno\fP on \fIstderr\fP. +.P +The (obsolete) +.BR hstrerror () +function takes an error number +(typically \fIh_errno\fP) and returns the corresponding message string. +.P +The domain name queries carried out by +.BR gethostbyname () +and +.BR gethostbyaddr () +rely on the Name Service Switch +.RB ( nsswitch.conf (5)) +configured sources or a local name server +.RB ( named (8)). +The default action is to query the Name Service Switch +.RB ( nsswitch.conf (5)) +configured sources, failing that, a local name server +.RB ( named (8)). +.\" +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.P +In glibc 2.4 and earlier, the +.I order +keyword was used to control the order of host lookups as defined in +.I /etc/host.conf +.RB ( host.conf (5)). +.P +The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows: +.P +.in +4n +.EX +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +} +#define h_addr h_addr_list[0] /* for backward compatibility */ +.EE +.in +.P +The members of the \fIhostent\fP structure are: +.TP +.I h_name +The official name of the host. +.TP +.I h_aliases +An array of alternative names for the host, terminated by a null pointer. +.TP +.I h_addrtype +The type of address; always +.B AF_INET +or +.B AF_INET6 +at present. +.TP +.I h_length +The length of the address in bytes. +.TP +.I h_addr_list +An array of pointers to network addresses for the host (in network byte +order), terminated by a null pointer. +.TP +.I h_addr +The first address in \fIh_addr_list\fP for backward compatibility. +.SH RETURN VALUE +The +.BR gethostbyname () +and +.BR gethostbyaddr () +functions return the +.I hostent +structure or a null pointer if an error occurs. +On error, the +.I h_errno +variable holds an error number. +When non-NULL, the return value may point at static data, see the notes below. +.SH ERRORS +The variable \fIh_errno\fP can have the following values: +.TP +.B HOST_NOT_FOUND +The specified host is unknown. +.TP +.B NO_DATA +The requested name is valid but does not have an IP address. +Another type of request to the name server for this domain +may return an answer. +The constant +.B NO_ADDRESS +is a synonym for +.BR NO_DATA . +.TP +.B NO_RECOVERY +A nonrecoverable name server error occurred. +.TP +.B TRY_AGAIN +A temporary error occurred on an authoritative name server. +Try again later. +.SH FILES +.TP +.I /etc/host.conf +resolver configuration file +.TP +.I /etc/hosts +host database file +.TP +.I /etc/nsswitch.conf +name service switch configuration +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gethostbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyname env +locale +T} +T{ +.na +.nh +.BR gethostbyaddr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyaddr env +locale +T} +T{ +.na +.nh +.BR sethostent (), +.BR endhostent (), +.BR gethostent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostent env +locale +T} +T{ +.na +.nh +.BR herror (), +.BR hstrerror () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR gethostent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostent +race:hostentbuf env locale +T} +T{ +.na +.nh +.BR gethostbyname2 () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyname2 +env locale +T} +T{ +.na +.nh +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r () +T} Thread safety MT-Safe env locale +.TE +.P +In the above table, +.I hostent +in +.I race:hostent +signifies that if any of the functions +.BR sethostent (), +.BR gethostent (), +.BR gethostent_r (), +or +.BR \%endhostent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +.TP +.BR sethostent () +.TQ +.BR endhostent () +.TQ +.BR gethostent () +POSIX.1-2008. +.TP +.BR gethostent_r () +GNU. +.TP +Others: +None. +.SH HISTORY +.TP +.BR sethostent () +.TQ +.BR endhostent () +.TQ +.BR gethostent () +POSIX.1-2001. +.TP +.BR gethostbyname () +.TQ +.BR gethostbyaddr () +.TQ +.I h_errno +Marked obsolescent in POSIX.1-2001. +Removed in POSIX.1-2008, +recommending the use of +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.SH NOTES +The functions +.BR gethostbyname () +and +.BR gethostbyaddr () +may return pointers to static data, which may be overwritten by +later calls. +Copying the +.I struct hostent +does not suffice, since it contains pointers; a deep copy is required. +.P +In the original BSD implementation the +.I len +argument +of +.BR gethostbyname () +was an +.IR int . +The SUSv2 standard is buggy and declares the +.I len +argument of +.BR gethostbyaddr () +to be of type +.IR size_t . +(That is wrong, because it has to be +.IR int , +and +.I size_t +is not. +POSIX.1-2001 makes it +.IR socklen_t , +which is OK.) +See also +.BR accept (2). +.P +The BSD prototype for +.BR gethostbyaddr () +uses +.I "const char\ *" +for the first argument. +.SS System V/POSIX extension +POSIX requires the +.BR gethostent () +call, which should return the next entry in the host data base. +When using DNS/BIND this does not make much sense, but it may +be reasonable if the host data base is a file that can be read +line by line. +On many systems, a routine of this name reads +from the file +.IR /etc/hosts . +.\" e.g., Linux, FreeBSD, UnixWare, HP-UX +It may be available only when the library was built without DNS support. +.\" e.g., FreeBSD, AIX +The glibc version will ignore ipv6 entries. +This function is not reentrant, +and glibc adds a reentrant version +.BR gethostent_r (). +.SS GNU extensions +glibc2 also has a +.BR gethostbyname2 () +that works like +.BR gethostbyname (), +but permits to specify the address family to which the address must belong. +.P +glibc2 also has reentrant versions +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +and +.BR gethostbyname2_r (). +The caller supplies a +.I hostent +structure +.I ret +which will be filled in on success, and a temporary work buffer +.I buf +of size +.IR buflen . +After the call, +.I result +will point to the result on success. +In case of an error +or if no entry is found +.I result +will be NULL. +The functions return 0 on success and a nonzero error number on failure. +In addition to the errors returned by the nonreentrant +versions of these functions, if +.I buf +is too small, the functions will return +.BR ERANGE , +and the call should be retried with a larger buffer. +The global variable +.I h_errno +is not modified, but the address of a variable in which to store error numbers +is passed in +.IR h_errnop . +.SH BUGS +.BR gethostbyname () +does not recognize components of a dotted IPv4 address string +that are expressed in hexadecimal. +.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 +.SH SEE ALSO +.BR getaddrinfo (3), +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR resolver (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.\" .BR resolv+ (8) diff --git a/man/man3/gethostbyname2.3 b/man/man3/gethostbyname2.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname2.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname2_r.3 b/man/man3/gethostbyname2_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname2_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname_r.3 b/man/man3/gethostbyname_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostent.3 b/man/man3/gethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostent_r.3 b/man/man3/gethostent_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostent_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostid.3 b/man/man3/gethostid.3 new file mode 100644 index 0000000..f4ee425 --- /dev/null +++ b/man/man3/gethostid.3 @@ -0,0 +1,149 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Updated with additions from Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk> +.\" Portions Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> +.TH gethostid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gethostid, sethostid \- get or set the unique identifier of the current host +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B long gethostid(void); +.BI "int sethostid(long " hostid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostid (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + Up to and including glibc 2.19: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.P +.BR sethostid (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +.BR gethostid () +and +.BR sethostid () +respectively get or set a unique 32-bit identifier for the current machine. +The 32-bit identifier was intended to be unique among all UNIX systems in +existence. +This normally resembles the Internet address for the local +machine, as returned by +.BR gethostbyname (3), +and thus usually never needs to be set. +.P +The +.BR sethostid () +call is restricted to the superuser. +.SH RETURN VALUE +.BR gethostid () +returns the 32-bit identifier for the current host as set by +.BR sethostid (). +.P +On success, +.BR sethostid () +returns 0; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR sethostid () +can fail with the following errors: +.TP +.B EACCES +The caller did not have permission to write to the file used +to store the host ID. +.TP +.B EPERM +The calling process's effective user or group ID is not the same +as its corresponding real ID. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gethostid () +T} Thread safety T{ +.na +.nh +MT-Safe hostid env locale +T} +T{ +.na +.nh +.BR sethostid () +T} Thread safety T{ +.na +.nh +MT-Unsafe const:hostid +T} +.TE +.SH VERSIONS +In the glibc implementation, the +.I hostid +is stored in the file +.IR /etc/hostid . +(Before glibc 2.2, the file +.I /var/adm/hostid +was used.) +.\" libc5 used /etc/hostid; libc4 didn't have these functions +.P +In the glibc implementation, if +.BR gethostid () +cannot open the file containing the host ID, +then it obtains the hostname using +.BR gethostname (2), +passes that hostname to +.BR gethostbyname_r (3) +in order to obtain the host's IPv4 address, +and returns a value obtained by bit-twiddling the IPv4 address. +(This value may not be unique.) +.SH STANDARDS +.TP +.BR gethostid () +POSIX.1-2008. +.TP +.BR sethostid () +None. +.SH HISTORY +4.2BSD; dropped in 4.4BSD. +SVr4 and POSIX.1-2001 include +.BR gethostid () +but not +.BR sethostid (). +.SH BUGS +It is impossible to ensure that the identifier is globally unique. +.SH SEE ALSO +.BR hostid (1), +.BR gethostbyname (3) diff --git a/man/man3/getifaddrs.3 b/man/man3/getifaddrs.3 new file mode 100644 index 0000000..825e38c --- /dev/null +++ b/man/man3/getifaddrs.3 @@ -0,0 +1,313 @@ +'\" t +.\" Copyright (c) 2008 Petr Baudis <pasky@suse.cz> +.\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 2008-12-08 Petr Baudis <pasky@suse.cz> +.\" Rewrite the BSD manpage in the Linux man pages style and account +.\" for glibc specificities, provide an example. +.\" 2009-01-14 mtk, many edits and changes, rewrote example program. +.\" +.TH getifaddrs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getifaddrs, freeifaddrs \- get interface addresses +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <ifaddrs.h> +.P +.BI "int getifaddrs(struct ifaddrs **" "ifap" ); +.BI "void freeifaddrs(struct ifaddrs *" "ifa" ); +.fi +.SH DESCRIPTION +The +.BR getifaddrs () +function creates a linked list of structures describing +the network interfaces of the local system, +and stores the address of the first item of the list in +.IR *ifap . +The list consists of +.I ifaddrs +structures, defined as follows: +.P +.in +4n +.EX +struct ifaddrs { + struct ifaddrs *ifa_next; /* Next item in list */ + char *ifa_name; /* Name of interface */ + unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */ + struct sockaddr *ifa_addr; /* Address of interface */ + struct sockaddr *ifa_netmask; /* Netmask of interface */ + union { + struct sockaddr *ifu_broadaddr; + /* Broadcast address of interface */ + struct sockaddr *ifu_dstaddr; + /* Point\-to\-point destination address */ + } ifa_ifu; +#define ifa_broadaddr ifa_ifu.ifu_broadaddr +#define ifa_dstaddr ifa_ifu.ifu_dstaddr + void *ifa_data; /* Address\-specific data */ +}; +.EE +.in +.P +The +.I ifa_next +field contains a pointer to the next structure on the list, +or NULL if this is the last item of the list. +.P +The +.I ifa_name +points to the null-terminated interface name. +.\" The constant +.\" .B IF NAMESIZE +.\" indicates the maximum length of this field. +.P +The +.I ifa_flags +field contains the interface flags, as returned by the +.B SIOCGIFFLAGS +.BR ioctl (2) +operation (see +.BR netdevice (7) +for a list of these flags). +.P +The +.I ifa_addr +field points to a structure containing the interface address. +(The +.I sa_family +subfield should be consulted to determine the format of the +address structure.) +This field may contain a null pointer. +.P +The +.I ifa_netmask +field points to a structure containing the netmask associated with +.IR ifa_addr , +if applicable for the address family. +This field may contain a null pointer. +.P +Depending on whether the bit +.B IFF_BROADCAST +or +.B IFF_POINTOPOINT +is set in +.I ifa_flags +(only one can be set at a time), +either +.I ifa_broadaddr +will contain the broadcast address associated with +.I ifa_addr +(if applicable for the address family) or +.I ifa_dstaddr +will contain the destination address of the point-to-point interface. +.P +The +.I ifa_data +field points to a buffer containing address-family-specific data; +this field may be NULL if there is no such data for this interface. +.P +The data returned by +.BR getifaddrs () +is dynamically allocated and should be freed using +.BR freeifaddrs () +when no longer needed. +.SH RETURN VALUE +On success, +.BR getifaddrs () +returns zero; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR getifaddrs () +may fail and set +.I errno +for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +.BR malloc (3), +or +.BR realloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getifaddrs (), +.BR freeifaddrs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +This function first appeared in BSDi and is +present on the BSD systems, but with slightly different +semantics documented\[em]returning one entry per interface, +not per address. +This means +.I ifa_addr +and other fields can actually be NULL if the interface has no address, +and no link-level address is returned if the interface has an IP address +assigned. +Also, the way of choosing either +.I ifa_broadaddr +or +.I ifa_dstaddr +differs on various systems. +.\" , but the BSD-derived documentation generally +.\" appears to be confused and obsolete on this point. +.\" i.e., commonly it still says one of them will be NULL, even if +.\" the ifa_ifu union is already present +.P +.BR getifaddrs () +first appeared in glibc 2.3, but before glibc 2.3.3, +the implementation supported only IPv4 addresses; +IPv6 support was added in glibc 2.3.3. +Support of address families other than IPv4 is available only +on kernels that support netlink. +.SH NOTES +The addresses returned on Linux will usually be the IPv4 and IPv6 addresses +assigned to the interface, but also one +.B AF_PACKET +address per interface containing lower-level details about the interface +and its physical layer. +In this case, the +.I ifa_data +field may contain a pointer to a +.IR "struct rtnl_link_stats" , +defined in +.I <linux/if_link.h> +(in Linux 2.4 and earlier, +.IR "struct net_device_stats" , +defined in +.IR <linux/netdevice.h> ), +which contains various interface attributes and statistics. +.SH EXAMPLES +The program below demonstrates the use of +.BR getifaddrs (), +.BR freeifaddrs (), +and +.BR getnameinfo (3). +Here is what we see when running this program on one system: +.P +.in +4n +.EX +$ \fB./a.out\fP +lo AF_PACKET (17) + tx_packets = 524; rx_packets = 524 + tx_bytes = 38788; rx_bytes = 38788 +wlp3s0 AF_PACKET (17) + tx_packets = 108391; rx_packets = 130245 + tx_bytes = 30420659; rx_bytes = 94230014 +em1 AF_PACKET (17) + tx_packets = 0; rx_packets = 0 + tx_bytes = 0; rx_bytes = 0 +lo AF_INET (2) + address: <127.0.0.1> +wlp3s0 AF_INET (2) + address: <192.168.235.137> +lo AF_INET6 (10) + address: <::1> +wlp3s0 AF_INET6 (10) + address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0> +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */ +#include <arpa/inet.h> +#include <sys/socket.h> +#include <netdb.h> +#include <ifaddrs.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <linux/if_link.h> +\& +int main(int argc, char *argv[]) +{ + struct ifaddrs *ifaddr; + int family, s; + char host[NI_MAXHOST]; +\& + if (getifaddrs(&ifaddr) == \-1) { + perror("getifaddrs"); + exit(EXIT_FAILURE); + } +\& + /* Walk through linked list, maintaining head pointer so we + can free list later. */ +\& + for (struct ifaddrs *ifa = ifaddr; ifa != NULL; + ifa = ifa\->ifa_next) { + if (ifa\->ifa_addr == NULL) + continue; +\& + family = ifa\->ifa_addr\->sa_family; +\& + /* Display interface name and family (including symbolic + form of the latter for the common families). */ +\& + printf("%\-8s %s (%d)\en", + ifa\->ifa_name, + (family == AF_PACKET) ? "AF_PACKET" : + (family == AF_INET) ? "AF_INET" : + (family == AF_INET6) ? "AF_INET6" : "???", + family); +\& + /* For an AF_INET* interface address, display the address. */ +\& + if (family == AF_INET || family == AF_INET6) { + s = getnameinfo(ifa\->ifa_addr, + (family == AF_INET) ? sizeof(struct sockaddr_in) : + sizeof(struct sockaddr_in6), + host, NI_MAXHOST, + NULL, 0, NI_NUMERICHOST); + if (s != 0) { + printf("getnameinfo() failed: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + printf("\et\etaddress: <%s>\en", host); +\& + } else if (family == AF_PACKET && ifa\->ifa_data != NULL) { + struct rtnl_link_stats *stats = ifa\->ifa_data; +\& + printf("\et\ettx_packets = %10u; rx_packets = %10u\en" + "\et\ettx_bytes = %10u; rx_bytes = %10u\en", + stats\->tx_packets, stats\->rx_packets, + stats\->tx_bytes, stats\->rx_bytes); + } + } +\& + freeifaddrs(ifaddr); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2), +.BR socket (2), +.BR packet (7), +.BR ifconfig (8) diff --git a/man/man3/getipnodebyaddr.3 b/man/man3/getipnodebyaddr.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man/man3/getipnodebyaddr.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man/man3/getipnodebyname.3 b/man/man3/getipnodebyname.3 new file mode 100644 index 0000000..c52dfa1 --- /dev/null +++ b/man/man3/getipnodebyname.3 @@ -0,0 +1,253 @@ +.\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH getipnodebyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getipnodebyname, getipnodebyaddr, freehostent \- get network +hostnames and addresses +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/socket.h> +.B #include <netdb.h> +.P +.BI "[[deprecated]] struct hostent *getipnodebyname(const char *" name ", int " af , +.BI " int " flags ", int *" error_num ); +.BI "[[deprecated]] struct hostent *getipnodebyaddr(const void " addr [. len ], +.BI " size_t " len ", int " af , +.BI " int *" "error_num" ); +.BI "[[deprecated]] void freehostent(struct hostent *" "ip" ); +.fi +.SH DESCRIPTION +These functions are deprecated (and unavailable in glibc). +Use +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.P +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions return the names and addresses of a network host. +These functions return a pointer to the +following structure: +.P +.in +4n +.EX +struct hostent { + char *h_name; + char **h_aliases; + int h_addrtype; + int h_length; + char **h_addr_list; +}; +.EE +.in +.P +These functions replace the +.BR gethostbyname (3) +and +.BR gethostbyaddr (3) +functions, which could access only the IPv4 network address family. +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions can access multiple network address families. +.P +Unlike the +.B gethostby +functions, +these functions return pointers to dynamically allocated memory. +The +.BR freehostent () +function is used to release the dynamically allocated memory +after the caller no longer needs the +.I hostent +structure. +.SS getipnodebyname() arguments +The +.BR getipnodebyname () +function +looks up network addresses for the host +specified by the +.I name +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I name +argument points to a dotted-quad IPv4 address or a name +of an IPv4 network host. +.TP +.B AF_INET6 +The +.I name +argument points to a hexadecimal IPv6 address or a name +of an IPv6 network host. +.P +The +.I flags +argument specifies additional options. +More than one option can be specified by bitwise OR-ing +them together. +.I flags +should be set to 0 +if no options are desired. +.TP +.B AI_V4MAPPED +This flag is used with +.B AF_INET6 +to request a query for IPv4 addresses instead of +IPv6 addresses; the IPv4 addresses will +be mapped to IPv6 addresses. +.TP +.B AI_ALL +This flag is used with +.B AI_V4MAPPED +to request a query for both IPv4 and IPv6 addresses. +Any IPv4 address found will be mapped to an IPv6 address. +.TP +.B AI_ADDRCONFIG +This flag is used with +.B AF_INET6 +to +further request that queries for IPv6 addresses should not be made unless +the system has at least one IPv6 address assigned to a network interface, +and that queries for IPv4 addresses should not be made unless the +system has at least one IPv4 address assigned to a network interface. +This flag may be used by itself or with the +.B AI_V4MAPPED +flag. +.TP +.B AI_DEFAULT +This flag is equivalent to +.BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . +.SS getipnodebyaddr() arguments +The +.BR getipnodebyaddr () +function +looks up the name of the host whose +network address is +specified by the +.I addr +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I addr +argument points to a +.I struct in_addr +and +.I len +must be set to +.IR "sizeof(struct in_addr)" . +.TP +.B AF_INET6 +The +.I addr +argument points to a +.I struct in6_addr +and +.I len +must be set to +.IR "sizeof(struct in6_addr)" . +.SH RETURN VALUE +NULL is returned if an error occurred, and +.I error_num +will contain an error code from the following list: +.TP +.B HOST_NOT_FOUND +The hostname or network address was not found. +.TP +.B NO_ADDRESS +The domain name server recognized the network address or name, +but no answer was returned. +This can happen if the network host has only IPv4 addresses and +a request has been made for IPv6 information only, or vice versa. +.TP +.B NO_RECOVERY +The domain name server returned a permanent failure response. +.TP +.B TRY_AGAIN +The domain name server returned a temporary failure response. +You might have better luck next time. +.P +A successful query returns a pointer to a +.I hostent +structure that contains the following fields: +.TP +.I h_name +This is the official name of this network host. +.TP +.I h_aliases +This is an array of pointers to unofficial aliases for the same host. +The array is terminated by a null pointer. +.TP +.I h_addrtype +This is a copy of the +.I af +argument to +.BR getipnodebyname () +or +.BR getipnodebyaddr (). +.I h_addrtype +will always be +.B AF_INET +if the +.I af +argument was +.BR AF_INET . +.I h_addrtype +will always be +.B AF_INET6 +if the +.I af +argument was +.BR AF_INET6 . +.TP +.I h_length +This field will be set to +.I sizeof(struct in_addr) +if +.I h_addrtype +is +.BR AF_INET , +and to +.I sizeof(struct in6_addr) +if +.I h_addrtype +is +.BR AF_INET6 . +.TP +.I h_addr_list +This is an array of one or more pointers to network address structures for the +network host. +The array is terminated by a null pointer. +.SH STANDARDS +None. +.SH HISTORY +.\" Not in POSIX.1-2001. +RFC\ 2553. +.P +Present in glibc 2.1.91-95, but removed again. +Several UNIX-like systems support them, but all +call them deprecated. +.SH SEE ALSO +.BR getaddrinfo (3), +.BR getnameinfo (3), +.BR inet_ntop (3), +.BR inet_pton (3) diff --git a/man/man3/getline.3 b/man/man3/getline.3 new file mode 100644 index 0000000..fc960f0 --- /dev/null +++ b/man/man3/getline.3 @@ -0,0 +1,182 @@ +'\" t +.\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk> +.\" Based in part on GNU libc documentation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getline 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getline, getdelim \- delimited string input +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n , +.BI " FILE *restrict " stream ); +.BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n , +.BI " int " delim ", FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getline (), +.BR getdelim (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR getline () +reads an entire line from \fIstream\fP, +storing the address of the buffer containing the text into +.IR *lineptr . +The buffer is null-terminated and includes the newline character, if +one was found. +.P +If +.I *lineptr +is set to NULL before the call, then +.BR getline () +will allocate a buffer for storing the line. +This buffer should be freed by the user program +even if +.BR getline () +failed. +.P +Alternatively, before calling +.BR getline (), +.I *lineptr +can contain a pointer to a +.BR malloc (3)\-allocated +buffer +.I *n +bytes in size. +If the buffer is not large enough to hold the line, +.BR getline () +resizes it with +.BR realloc (3), +updating +.I *lineptr +and +.I *n +as necessary. +.P +In either case, on a successful call, +.I *lineptr +and +.I *n +will be updated to reflect the buffer address and allocated size respectively. +.P +.BR getdelim () +works like +.BR getline (), +except that a line delimiter other than newline can be specified as the +.I delimiter +argument. +As with +.BR getline (), +a delimiter character is not added if one was not present +in the input before end of file was reached. +.SH RETURN VALUE +On success, +.BR getline () +and +.BR getdelim () +return the number of characters read, including the delimiter character, +but not including the terminating null byte (\[aq]\e0\[aq]). +This value can be used +to handle embedded null bytes in the line read. +.P +Both functions return \-1 on failure to read a line (including end-of-file +condition). +In the event of a failure, +.I errno +is set to indicate the error. +.P +If +.I *lineptr +was set to NULL before the call, then the buffer should be freed by the +user program even on failure. +.SH ERRORS +.TP +.B EINVAL +Bad arguments +.RI ( n +or +.I lineptr +is NULL, or +.I stream +is not valid). +.TP +.B ENOMEM +Allocation or reallocation of the line buffer failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getline (), +.BR getdelim () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +GNU, POSIX.1-2008. +.SH EXAMPLES +.\" SRC BEGIN (getline.c) +.EX +#define _GNU_SOURCE +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + FILE *stream; + char *line = NULL; + size_t len = 0; + ssize_t nread; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s <file>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + stream = fopen(argv[1], "r"); + if (stream == NULL) { + perror("fopen"); + exit(EXIT_FAILURE); + } +\& + while ((nread = getline(&line, &len, stream)) != \-1) { + printf("Retrieved line of length %zd:\en", nread); + fwrite(line, nread, 1, stdout); + } +\& + free(line); + fclose(stream); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR read (2), +.BR fgets (3), +.BR fopen (3), +.BR fread (3), +.BR scanf (3) diff --git a/man/man3/getloadavg.3 b/man/man3/getloadavg.3 new file mode 100644 index 0000000..7f45786 --- /dev/null +++ b/man/man3/getloadavg.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" @(#)getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH getloadavg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getloadavg \- get system load averages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int getloadavg(double " loadavg[] ", int " nelem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getloadavg (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR getloadavg () +function returns the number of processes in the system run queue +averaged over various periods of time. +Up to +.I nelem +samples are retrieved and assigned to successive elements of +.IR loadavg[] . +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +.SH RETURN VALUE +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getloadavg () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH HISTORY +4.3BSD-Reno, Solaris. +glibc 2.2. +.SH SEE ALSO +.BR uptime (1), +.BR proc (5) diff --git a/man/man3/getlogin.3 b/man/man3/getlogin.3 new file mode 100644 index 0000000..6ac36f8 --- /dev/null +++ b/man/man3/getlogin.3 @@ -0,0 +1,259 @@ +'\" t +.\" Copyright 1995 James R. Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3 +.\" added ref to /etc/utmp, added BUGS section, etc. +.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use +.TH getlogin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getlogin, getlogin_r, cuserid \- get username +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B "char *getlogin(void);" +.BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize ); +.P +.B #include <stdio.h> +.P +.BI "char *cuserid(char *" string ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getlogin_r (): +.nf +.\" Deprecated: _REENTRANT || + _POSIX_C_SOURCE >= 199506L +.fi +.P +.BR cuserid (): +.nf + Since glibc 2.24: + (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || _GNU_SOURCE + Up to and including glibc 2.23: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR getlogin () +returns a pointer to a string containing the name of +the user logged in on the controlling terminal of the process, or a +null pointer if this information cannot be determined. +The string is +statically allocated and might be overwritten on subsequent calls to +this function or to +.BR cuserid (). +.P +.BR getlogin_r () +returns this same username in the array +.I buf +of size +.IR bufsize . +.P +.BR cuserid () +returns a pointer to a string containing a username +associated with the effective user ID of the process. +If \fIstring\fP +is not a null pointer, it should be an array that can hold at least +\fBL_cuserid\fP characters; the string is returned in this array. +Otherwise, a pointer to a string in a static area is returned. +This +string is statically allocated and might be overwritten on subsequent +calls to this function or to +.BR getlogin (). +.P +The macro \fBL_cuserid\fP is an integer constant that indicates how +long an array you might need to store a username. +\fBL_cuserid\fP is declared in \fI<stdio.h>\fP. +.P +These functions let your program identify positively the user who is +running +.RB ( cuserid ()) +or the user who logged in this session +.RB ( getlogin ()). +(These can differ when set-user-ID programs are involved.) +.P +For most purposes, it is more useful to use the environment variable +\fBLOGNAME\fP to find out who the user is. +This is more flexible +precisely because the user can set \fBLOGNAME\fP arbitrarily. +.SH RETURN VALUE +.BR getlogin () +returns a pointer to the username when successful, +and NULL on failure, with +.I errno +set to indicate the error. +.BR getlogin_r () +returns 0 when successful, and nonzero on failure. +.SH ERRORS +POSIX specifies: +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENXIO +The calling process has no controlling terminal. +.TP +.B ERANGE +(getlogin_r) +The length of the username, including the terminating null byte (\[aq]\e0\[aq]), +is larger than +.IR bufsize . +.P +Linux/glibc also has: +.TP +.B ENOENT +There was no corresponding entry in the utmp-file. +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.TP +.B ENOTTY +Standard input didn't refer to a terminal. +(See BUGS.) +.SH FILES +.TP +\fI/etc/passwd\fP +password database file +.TP +\fI/var/run/utmp\fP +(traditionally \fI/etc/utmp\fP; +some libc versions used \fI/var/adm/utmp\fP) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getlogin () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getlogin race:utent +sig:ALRM timer locale +T} +T{ +.na +.nh +.BR getlogin_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent sig:ALRM timer +locale +T} +T{ +.na +.nh +.BR cuserid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:cuserid/!string locale +T} +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR getlogin () +and +.BR getlogin_r () +call those functions, +so we use race:utent to remind users. +.SH VERSIONS +OpenBSD has +.BR getlogin () +and +.BR setlogin (), +and a username +associated with a session, even if it has no controlling terminal. +.SH STANDARDS +.TP +.BR getlogin () +.TQ +.BR getlogin_r () +POSIX.1-2008. +.TP +.BR cuserid () +None. +.SH STANDARDS +.TP +.BR getlogin () +.TQ +.BR getlogin_r (): +POSIX.1-2001. +OpenBSD. +.TP +.BR cuserid () +System V, POSIX.1-1988. +Removed in POSIX.1-1990. +SUSv2. +Removed in POSIX.1-2001. +.IP +System V has a +.BR cuserid () +function which uses the real +user ID rather than the effective user ID. +.SH BUGS +Unfortunately, it is often rather easy to fool +.BR getlogin (). +Sometimes it does not work at all, because some program messed up +the utmp file. +Often, it gives only the first 8 characters of +the login name. +The user currently logged in on the controlling terminal +of our program need not be the user who started it. +Avoid +.BR getlogin () +for security-related purposes. +.P +Note that glibc does not follow the POSIX specification and uses +.I stdin +instead of +.IR /dev/tty . +A bug. +(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 +all return the login name also when +.I stdin +is redirected.) +.P +Nobody knows precisely what +.BR cuserid () +does; avoid it in portable programs. +Or avoid it altogether: use +.I getpwuid(geteuid()) +instead, if that is +what you meant. +.B Do not use +.BR cuserid (). +.SH SEE ALSO +.BR logname (1), +.BR geteuid (2), +.BR getuid (2), +.BR utmp (5) diff --git a/man/man3/getlogin_r.3 b/man/man3/getlogin_r.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man/man3/getlogin_r.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man/man3/getmntent.3 b/man/man3/getmntent.3 new file mode 100644 index 0000000..93d5100 --- /dev/null +++ b/man/man3/getmntent.3 @@ -0,0 +1,265 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961109, 031115, aeb +.\" +.TH getmntent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getmntent, setmntent, addmntent, endmntent, hasmntopt, +getmntent_r \- get filesystem descriptor file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <mntent.h> +.P +.BI "FILE *setmntent(const char *" filename ", const char *" type ); +.P +.BI "struct mntent *getmntent(FILE *" stream ); +.P +.BI "int addmntent(FILE *restrict " stream , +.BI " const struct mntent *restrict " mnt ); +.P +.BI "int endmntent(FILE *" streamp ); +.P +.BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt ); +.P +/* GNU extension */ +.B #include <mntent.h> +.P +.BI "struct mntent *getmntent_r(FILE *restrict " streamp , +.BI " struct mntent *restrict " mntbuf , +.BI " char " buf "[restrict ." buflen "], int " buflen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getmntent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These routines are used to access the filesystem description file +.I /etc/fstab +and the mounted filesystem description file +.IR /etc/mtab . +.P +The +.BR setmntent () +function opens the filesystem description file +.I filename +and returns a file pointer which can be used by +.BR getmntent (). +The argument +.I type +is the type of access +required and can take the same values as the +.I mode +argument of +.BR fopen (3). +The returned stream should be closed using +.BR endmntent () +rather than +.BR fclose (3). +.P +The +.BR getmntent () +function reads the next line of the filesystem +description file from +.I stream +and returns a pointer to a structure +containing the broken out fields from a line in the file. +The pointer +points to a static area of memory which is overwritten by subsequent +calls to +.BR getmntent (). +.P +The +.BR addmntent () +function adds the +.I mntent +structure +.I mnt +to +the end of the open +.IR stream . +.P +The +.BR endmntent () +function closes the +.I stream +associated with the filesystem description file. +.P +The +.BR hasmntopt () +function scans the +.I mnt_opts +field (see below) +of the +.I mntent +structure +.I mnt +for a substring that matches +.IR opt . +See +.I <mntent.h> +and +.BR mount (8) +for valid mount options. +.P +The reentrant +.BR getmntent_r () +function is similar to +.BR getmntent (), +but stores the +.I mntent +structure +in the provided +.IR *mntbuf , +and stores the strings pointed to by the entries in that structure +in the provided array +.I buf +of size +.IR buflen . +.P +The +.I mntent +structure is defined in +.I <mntent.h> +as follows: +.P +.in +4n +.EX +struct mntent { + char *mnt_fsname; /* name of mounted filesystem */ + char *mnt_dir; /* filesystem path prefix */ + char *mnt_type; /* mount type (see mntent.h) */ + char *mnt_opts; /* mount options (see mntent.h) */ + int mnt_freq; /* dump frequency in days */ + int mnt_passno; /* pass number on parallel fsck */ +}; +.EE +.in +.P +Since fields in the mtab and fstab files are separated by whitespace, +octal escapes are used to represent the characters space (\e040), +tab (\e011), newline (\e012), and backslash (\e\e) in those files +when they occur in one of the four strings in a +.I mntent +structure. +The routines +.BR addmntent () +and +.BR getmntent () +will convert +from string representation to escaped representation and back. +When converting from escaped representation, the sequence \e134 is +also converted to a backslash. +.SH RETURN VALUE +The +.BR getmntent () +and +.BR getmntent_r () +functions return +a pointer to the +.I mntent +structure or NULL on failure. +.P +The +.BR addmntent () +function returns 0 on success and 1 on failure. +.P +The +.BR endmntent () +function always returns 1. +.P +The +.BR hasmntopt () +function returns the address of the substring if +a match is found and NULL otherwise. +.SH FILES +.TP +.I /etc/fstab +filesystem description file +.TP +.I /etc/mtab +mounted filesystem description file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setmntent (), +.BR endmntent (), +.BR hasmntopt () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR getmntent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mntentbuf locale +T} +T{ +.na +.nh +.BR addmntent () +T} Thread safety T{ +.na +.nh +MT-Safe race:stream locale +T} +T{ +.na +.nh +.BR getmntent_r () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +The nonreentrant functions are from SunOS 4.1.3. +A routine +.BR getmntent_r () +was introduced in HP-UX 10, but it returns an +.IR int . +The prototype shown above is glibc-only. +.P +System V also has a +.BR getmntent () +function but the calling sequence +differs, and the returned structure is different. +Under System V +.I /etc/mnttab +is used. +4.4BSD and Digital UNIX have a routine +.BR \%getmntinfo (), +a wrapper around the system call +.BR getfsstat (). +.SH SEE ALSO +.BR fopen (3), +.BR fstab (5), +.BR mount (8) diff --git a/man/man3/getmntent_r.3 b/man/man3/getmntent_r.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/getmntent_r.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/getnameinfo.3 b/man/man3/getnameinfo.3 new file mode 100644 index 0000000..4fb632c --- /dev/null +++ b/man/man3/getnameinfo.3 @@ -0,0 +1,345 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. +.\" %%%LICENSE_END +.\" +.\" Almost all details are from RFC 2553. +.\" +.\" 2004-12-14, mtk, Added EAI_OVERFLOW error +.\" 2004-12-14 Fixed description of error return +.\" +.TH getnameinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnameinfo \- address-to-name translation in protocol-independent manner +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <netdb.h> +.P +.BI "int getnameinfo(const struct sockaddr *restrict " addr \ +", socklen_t " addrlen , +.BI " char " host "[_Nullable restrict ." hostlen ], +.BI " socklen_t " hostlen , +.BI " char " serv "[_Nullable restrict ." servlen ], +.BI " socklen_t " servlen , +.BI " int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getnameinfo (): +.nf + Since glibc 2.22: + _POSIX_C_SOURCE >= 200112L + glibc 2.21 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR getnameinfo () +function is the inverse of +.BR getaddrinfo (3): +it converts a socket address to a corresponding host and service, +in a protocol-independent manner. +It combines the functionality of +.BR gethostbyaddr (3) +and +.BR getservbyport (3), +but unlike those functions, +.BR getnameinfo () +is reentrant and allows programs to eliminate +IPv4-versus-IPv6 dependencies. +.P +The +.I addr +argument is a pointer to a generic socket address structure +(of type +.I sockaddr_in +or +.IR sockaddr_in6 ) +of size +.I addrlen +that holds the input IP address and port number. +The arguments +.I host +and +.I serv +are pointers to caller-allocated buffers (of size +.I hostlen +and +.I servlen +respectively) into which +.BR getnameinfo () +places null-terminated strings containing the host and +service names respectively. +.P +The caller can specify that no hostname (or no service name) +is required by providing a NULL +.I host +(or +.IR serv ) +argument or a zero +.I hostlen +(or +.IR servlen ) +argument. +However, at least one of hostname or service name +must be requested. +.P +The +.I flags +argument modifies the behavior of +.BR getnameinfo () +as follows: +.TP +.B NI_NAMEREQD +If set, then an error is returned if the hostname cannot be determined. +.TP +.B NI_DGRAM +If set, then the service is datagram (UDP) based rather than +stream (TCP) based. +This is required for the few ports (512\[en]514) +that have different services for UDP and TCP. +.TP +.B NI_NOFQDN +If set, return only the hostname part of the fully qualified domain name +for local hosts. +.TP +.B NI_NUMERICHOST +If set, then the numeric form of the hostname is returned. +.\" For example, by calling +.\" .BR inet_ntop () +.\" instead of +.\" .BR gethostbyaddr (). +(When not set, this will still happen in case the node's name +cannot be determined.) +.\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it. +.TP +.B NI_NUMERICSERV +If set, then the numeric form of the service address is returned. +(When not set, this will still happen in case the service's name +cannot be determined.) +.SS Extensions to getnameinfo() for Internationalized Domain Names +Starting with glibc 2.3.4, +.BR getnameinfo () +has been extended to selectively allow +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Three new flags are defined: +.TP +.B NI_IDN +If this flag is used, then the name found in the lookup process is +converted from IDN format to the locale's encoding if necessary. +ASCII-only names are not affected by the conversion, which +makes this flag usable in existing programs and environments. +.TP +.B NI_IDN_ALLOW_UNASSIGNED +.TQ +.B NI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getnameinfo(); they need to +.\" be documented. +.\" +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +On success, 0 is returned, and node and service names, if requested, +are filled with null-terminated strings, possibly truncated to fit +the specified buffer lengths. +On error, one of the following nonzero error codes is returned: +.TP +.B EAI_AGAIN +The name could not be resolved at this time. +Try again later. +.TP +.B EAI_BADFLAGS +The +.I flags +argument has an invalid value. +.TP +.B EAI_FAIL +A nonrecoverable error occurred. +.TP +.B EAI_FAMILY +The address family was not recognized, +or the address length was invalid for the specified family. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NONAME +The name does not resolve for the supplied arguments. +.B NI_NAMEREQD +is set and the host's name cannot be located, +or neither hostname nor service name were requested. +.TP +.B EAI_OVERFLOW +The buffer pointed to by +.I host +or +.I serv +was too small. +.TP +.B EAI_SYSTEM +A system error occurred. +The error code can be found in +.IR errno . +.P +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/hosts +.br +.I /etc/nsswitch.conf +.br +.I /etc/resolv.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnameinfo () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +RFC\ 2553. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +Before glibc 2.2, the +.I hostlen +and +.I servlen +arguments were typed as +.IR size_t . +.SH NOTES +In order to assist the programmer in choosing reasonable sizes +for the supplied buffers, +.I <netdb.h> +defines the constants +.P +.in +4n +.EX +#define NI_MAXHOST 1025 +#define NI_MAXSERV 32 +.EE +.in +.P +Since glibc 2.8, +these definitions are exposed only if suitable +feature test macros are defined, namely: +.BR _GNU_SOURCE , +.B _DEFAULT_SOURCE +(since glibc 2.19), +or (in glibc versions up to and including 2.19) +.B _BSD_SOURCE +or +.BR _SVID_SOURCE . +.P +The former is the constant +.B MAXDNAME +in recent versions of BIND's +.I <arpa/nameser.h> +header file. +The latter is a guess based on the services listed +in the current Assigned Numbers RFC. +.SH EXAMPLES +The following code tries to get the numeric hostname and service name, +for a given socket address. +Note that there is no hardcoded reference to +a particular address family. +.P +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; +\& +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) + printf("host=%s, serv=%s\en", hbuf, sbuf); +.EE +.in +.P +The following version checks if the socket address has a +reverse address mapping. +.P +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST]; +\& +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), + NULL, 0, NI_NAMEREQD)) + printf("could not resolve hostname"); +else + printf("host=%s\en", hbuf); +.EE +.in +.P +An example program using +.BR getnameinfo () +can be found in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR getpeername (2), +.BR getsockname (2), +.BR recvfrom (2), +.BR socket (2), +.BR getaddrinfo (3), +.BR gethostbyaddr (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR inet_ntop (3), +.BR hosts (5), +.BR services (5), +.BR hostname (7), +.BR named (8) +.P +R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens, +.IR "Basic Socket Interface Extensions for IPv6" , +RFC\ 2553, March 1999. +.P +Tatsuya Jinmei and Atsushi Onoe, +.IR "An Extension of Format for IPv6 Scoped Addresses" , +internet draft, work in progress +.UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt +.UE . +.P +Craig Metz, +.IR "Protocol Independence Using the Sockets API" , +Proceedings of the freenix track: +2000 USENIX annual technical conference, June 2000 +.ad l +.UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html +.UE . diff --git a/man/man3/getnetbyaddr.3 b/man/man3/getnetbyaddr.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/getnetbyaddr.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/getnetbyaddr_r.3 b/man/man3/getnetbyaddr_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man/man3/getnetbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man/man3/getnetbyname.3 b/man/man3/getnetbyname.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/getnetbyname.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/getnetbyname_r.3 b/man/man3/getnetbyname_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man/man3/getnetbyname_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man/man3/getnetent.3 b/man/man3/getnetent.3 new file mode 100644 index 0000000..80fc853 --- /dev/null +++ b/man/man3/getnetent.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH getnetent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- +get network entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.B struct netent *getnetent(void); +.P +.BI "struct netent *getnetbyname(const char *" name ); +.BI "struct netent *getnetbyaddr(uint32_t " net ", int " type ); +.P +.BI "void setnetent(int " stayopen ); +.B void endnetent(void); +.fi +.SH DESCRIPTION +The +.BR getnetent () +function reads the next entry from the networks database +and returns a +.I netent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getnetbyname () +function returns a +.I netent +structure +for the entry from the database +that matches the network +.IR name . +.P +The +.BR getnetbyaddr () +function returns a +.I netent +structure +for the entry from the database +that matches the network number +.I net +of type +.IR type . +The +.I net +argument must be in host byte order. +.P +The +.BR setnetent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getnet* () +functions. +.P +The +.BR endnetent () +function closes the connection to the database. +.P +The +.I netent +structure is defined in +.I <netdb.h> +as follows: +.P +.in +4n +.EX +struct netent { + char *n_name; /* official network name */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net address type */ + uint32_t n_net; /* network number */ +} +.EE +.in +.P +The members of the +.I netent +structure are: +.TP +.I n_name +The official name of the network. +.TP +.I n_aliases +A NULL-terminated list of alternative names for the network. +.TP +.I n_addrtype +The type of the network number; always +.BR AF_INET . +.TP +.I n_net +The network number in host byte order. +.SH RETURN VALUE +The +.BR getnetent (), +.BR getnetbyname (), +and +.BR getnetbyaddr () +functions return a pointer to a +statically allocated +.I netent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/networks +networks database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnetent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netent +race:netentbuf env locale +T} +T{ +.na +.nh +.BR getnetbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netbyname +env locale +T} +T{ +.na +.nh +.BR getnetbyaddr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netbyaddr +locale +T} +T{ +.na +.nh +.BR setnetent (), +.BR endnetent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netent env +locale +T} +.TE +.P +In the above table, +.I netent +in +.I race:netent +signifies that if any of the functions +.BR setnetent (), +.BR getnetent (), +or +.BR endnetent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Before glibc 2.2, the +.I net +argument of +.BR getnetbyaddr () +was of type +.IR long . +.SH SEE ALSO +.BR getnetent_r (3), +.BR getprotoent (3), +.BR getservent (3) +.\" .BR networks (5) +.br +RFC\ 1101 diff --git a/man/man3/getnetent_r.3 b/man/man3/getnetent_r.3 new file mode 100644 index 0000000..c7548c2 --- /dev/null +++ b/man/man3/getnetent_r.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getnetent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnetent_r, getnetbyname_r, getnetbyaddr_r \- get +network entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "int getnetent_r(struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.BI "int getnetbyname_r(const char *restrict " name , +.BI " struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.BI "int getnetbyaddr_r(uint32_t " net ", int " type , +.BI " struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getnetent_r (), +.BR getnetbyname_r (), +and +.BR getnetbyaddr_r () +functions are the reentrant equivalents of, respectively, +.BR getnetent (3), +.BR getnetbyname (3), +and +.BR getnetbynumber (3). +They differ in the way that the +.I netent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I netent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I netent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains a network record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.P +The buffer pointed to by +.I h_errnop +is used to return the value that would be stored in the global variable +.I h_errno +by the nonreentrant versions of these functions. +.\" getnetent.3 doesn't document any use of h_errno, but nevertheless +.\" the nonreentrant functions no seem to set h_errno. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getnetbyname_r (), +.BR getnetbyaddr_r ()), +or end of input +.RB ( getnetent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getnetent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getnetent (3), +.BR networks (5) diff --git a/man/man3/getnetgrent.3 b/man/man3/getnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/getnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/getnetgrent_r.3 b/man/man3/getnetgrent_r.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/getnetgrent_r.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/getopt.3 b/man/man3/getopt.3 new file mode 100644 index 0000000..828394a --- /dev/null +++ b/man/man3/getopt.3 @@ -0,0 +1,577 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2006-2008, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" longindex is a pointer, has_arg can take 3 values, using consistent +.\" names for optstring and longindex, "\n" in formats fixed. Documenting +.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily +.\" from the source code). +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX +.\" says; moreover, EOF is not defined in <unistd.h>. +.\" Modified 2002-02-16, joey: added information about nonexistent +.\" option character and colon as first option character +.\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added text to explain how to order both '[-+]' and ':' at +.\" the start of optstring +.\" Modified 2006-12-15, mtk, Added getopt() example program. +.\" +.TH getopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getopt, getopt_long, getopt_long_only, +optarg, optind, opterr, optopt \- Parse command-line options +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int getopt(int " argc ", char *" argv [], +.BI " const char *" optstring ); +.P +.BI "extern char *" optarg ; +.BI "extern int " optind ", " opterr ", " optopt ; +.P +.B #include <getopt.h> +.P +.BI "int getopt_long(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.BI "int getopt_long_only(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getopt (): +.nf + _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE +.fi +.P +.BR getopt_long (), +.BR getopt_long_only (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR getopt () +function parses the command-line arguments. +Its arguments +.I argc +and +.I argv +are the argument count and array as passed to the +.IR main () +function on program invocation. +An element of \fIargv\fP that starts with \[aq]\-\[aq] +(and is not exactly "\-" or "\-\-") +is an option element. +The characters of this element +(aside from the initial \[aq]\-\[aq]) are option characters. +If +.BR getopt () +is called repeatedly, it returns successively each of the option characters +from each of the option elements. +.P +The variable +.I optind +is the index of the next element to be processed in +.IR argv . +The system initializes this value to 1. +The caller can reset it to 1 to restart scanning of the same +.IR argv , +or when scanning a new argument vector. +.P +If +.BR getopt () +finds another option character, it returns that +character, updating the external variable \fIoptind\fP and a static +variable \fInextchar\fP so that the next call to +.BR getopt () +can +resume the scan with the following option character or +\fIargv\fP-element. +.P +If there are no more option characters, +.BR getopt () +returns \-1. +Then \fIoptind\fP is the index in \fIargv\fP of the first +\fIargv\fP-element that is not an option. +.P +.I optstring +is a string containing the legitimate option characters. +A legitimate option character is any visible one byte +.BR ascii (7) +character (for which +.BR isgraph (3) +would return nonzero) that is not \[aq]\-\[aq], \[aq]:\[aq], or \[aq];\[aq]. +If such a +character is followed by a colon, the option requires an argument, so +.BR getopt () +places a pointer to the following text in the same +\fIargv\fP-element, or the text of the following \fIargv\fP-element, in +.IR optarg . +Two colons mean an option takes +an optional arg; if there is text in the current \fIargv\fP-element +(i.e., in the same word as the option name itself, for example, "\-oarg"), +then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. +This is a GNU extension. +If +.I optstring +contains +.B W +followed by a semicolon, then +.B \-W foo +is treated as the long option +.BR \-\-foo . +(The +.B \-W +option is reserved by POSIX.2 for implementation extensions.) +This behavior is a GNU extension, not available with libraries before +glibc 2. +.P +By default, +.BR getopt () +permutes the contents of \fIargv\fP as it +scans, so that eventually all the nonoptions are at the end. +Two other scanning modes are also implemented. +If the first character of +\fIoptstring\fP is \[aq]+\[aq] or the environment variable +.B POSIXLY_CORRECT +is set, then option processing stops as soon as a nonoption argument is +encountered. +If \[aq]+\[aq] is not the first character of +.IR optstring , +it is treated as a normal option. +If +.B POSIXLY_CORRECT +behaviour is required in this case +.I optstring +will contain two \[aq]+\[aq] symbols. +If the first character of \fIoptstring\fP is \[aq]\-\[aq], then +each nonoption \fIargv\fP-element is handled as if it were the argument of +an option with character code 1. +(This is used by programs that were +written to expect options and other \fIargv\fP-elements in any order +and that care about the ordering of the two.) +The special argument "\-\-" forces an end of option-scanning regardless +of the scanning mode. +.P +While processing the option list, +.BR getopt () +can detect two kinds of errors: +(1) an option character that was not specified in +.I optstring +and (2) a missing option argument +(i.e., an option at the end of the command line without an expected argument). +Such errors are handled and reported as follows: +.IP \[bu] 3 +By default, +.BR getopt () +prints an error message on standard error, +places the erroneous option character in +.IR optopt , +and returns \[aq]?\[aq] as the function result. +.IP \[bu] +If the caller has set the global variable +.I opterr +to zero, then +.BR getopt () +does not print an error message. +The caller can determine that there was an error by testing whether +the function return value is \[aq]?\[aq]. +(By default, +.I opterr +has a nonzero value.) +.IP \[bu] +If the first character +(following any optional \[aq]+\[aq] or \[aq]\-\[aq] described above) +of \fIoptstring\fP +is a colon (\[aq]:\[aq]), then +.BR getopt () +likewise does not print an error message. +In addition, it returns \[aq]:\[aq] instead of \[aq]?\[aq] to +indicate a missing option argument. +This allows the caller to distinguish the two different types of errors. +.\" +.SS getopt_long() and getopt_long_only() +The +.BR getopt_long () +function works like +.BR getopt () +except that it also accepts long options, started with two dashes. +(If the program accepts only long options, then +.I optstring +should be specified as an empty string (""), not NULL.) +Long option names may be abbreviated if the abbreviation is +unique or is an exact match for some defined option. +A long option +may take a parameter, of the form +.B \-\-arg=param +or +.BR "\-\-arg param" . +.P +.I longopts +is a pointer to the first element of an array of +.I struct option +declared in +.I <getopt.h> +as +.P +.in +4n +.EX +struct option { + const char *name; + int has_arg; + int *flag; + int val; +}; +.EE +.in +.P +The meanings of the different fields are: +.TP +.I name +is the name of the long option. +.TP +.I has_arg +is: +\fBno_argument\fP (or 0) if the option does not take an argument; +\fBrequired_argument\fP (or 1) if the option requires an argument; or +\fBoptional_argument\fP (or 2) if the option takes an optional argument. +.TP +.I flag +specifies how results are returned for a long option. +If \fIflag\fP +is NULL, then +.BR getopt_long () +returns \fIval\fP. +(For example, the calling program may set \fIval\fP to the equivalent short +option character.) +Otherwise, +.BR getopt_long () +returns 0, and +\fIflag\fP points to a variable which is set to \fIval\fP if the +option is found, but left unchanged if the option is not found. +.TP +\fIval\fP +is the value to return, or to load into the variable pointed +to by \fIflag\fP. +.P +The last element of the array has to be filled with zeros. +.P +If \fIlongindex\fP is not NULL, it +points to a variable which is set to the index of the long option relative to +.IR longopts . +.P +.BR getopt_long_only () +is like +.BR getopt_long (), +but \[aq]\-\[aq] as well +as "\-\-" can indicate a long option. +If an option that starts with \[aq]\-\[aq] +(not "\-\-") doesn't match a long option, but does match a short option, +it is parsed as a short option instead. +.SH RETURN VALUE +If an option was successfully found, then +.BR getopt () +returns the option character. +If all command-line options have been parsed, then +.BR getopt () +returns \-1. +If +.BR getopt () +encounters an option character that was not in +.IR optstring , +then \[aq]?\[aq] is returned. +If +.BR getopt () +encounters an option with a missing argument, +then the return value depends on the first character in +.IR optstring : +if it is \[aq]:\[aq], then \[aq]:\[aq] is returned; +otherwise \[aq]?\[aq] is returned. +.P +.BR getopt_long () +and +.BR getopt_long_only () +also return the option +character when a short option is recognized. +For a long option, they +return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. +Error and \-1 returns are the same as for +.BR getopt (), +plus \[aq]?\[aq] for an +ambiguous match or an extraneous parameter. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If this is set, then option processing stops as soon as a nonoption +argument is encountered. +.TP +.B _<PID>_GNU_nonoption_argv_flags_ +This variable was used by +.BR bash (1) +2.0 to communicate to glibc which arguments are the results of +wildcard expansion and so should not be considered as options. +This behavior was removed in +.BR bash (1) +2.01, but the support remains in glibc. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getopt (), +.BR getopt_long (), +.BR getopt_long_only () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getopt env +T} +.TE +.SH VERSIONS +POSIX specifies that the +.I argv +array argument should be +.IR const , +but these functions permute its elements +unless the environment variable +.B POSIXLY_CORRECT +is set. +.I const +is used in the actual prototype to be compatible with other systems; +however, this page doesn't show the qualifier, +to avoid confusing readers. +.SH STANDARDS +.TP +.BR getopt () +POSIX.1-2008. +.TP +.BR getopt_long () +.TQ +.BR getopt_long_only () +GNU. +.IP +The use of \[aq]+\[aq] and \[aq]\-\[aq] in +.I optstring +is a GNU extension. +.SH HISTORY +.TP +.BR getopt () +POSIX.1-2001, and POSIX.2. +.P +On some older implementations, +.BR getopt () +was declared in +.IR <stdio.h> . +SUSv1 permitted the declaration to appear in either +.I <unistd.h> +or +.IR <stdio.h> . +POSIX.1-1996 marked the use of +.I <stdio.h> +for this purpose as LEGACY. +POSIX.1-2001 does not require the declaration to appear in +.IR <stdio.h> . +.SH NOTES +A program that scans multiple argument vectors, +or rescans the same vector more than once, +and wants to make use of GNU extensions such as \[aq]+\[aq] +and \[aq]\-\[aq] at the start of +.IR optstring , +or changes the value of +.B POSIXLY_CORRECT +between scans, +must reinitialize +.BR getopt () +by resetting +.I optind +to 0, rather than the traditional value of 1. +(Resetting to 0 forces the invocation of an internal initialization +routine that rechecks +.B POSIXLY_CORRECT +and checks for GNU extensions in +.IR optstring .) +.P +Command-line arguments are parsed in strict order +meaning that an option requiring an argument will consume the next argument, +regardless of whether that argument is the correctly specified option argument +or simply the next option +(in the scenario the user mis-specifies the command line). +For example, if +.I optstring +is specified as "1n:" +and the user specifies the command line arguments incorrectly as +.IR "prog\ \-n\ \-1" , +the +.I \-n +option will be given the +.B optarg +value "\-1", and the +.I \-1 +option will be considered to have not been specified. +.SH EXAMPLES +.SS getopt() +The following trivial example program uses +.BR getopt () +to handle two program options: +.IR \-n , +with no associated value; and +.IR "\-t val" , +which expects an associated value. +.P +.\" SRC BEGIN (getopt.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + int flags, opt; + int nsecs, tfnd; +\& + nsecs = 0; + tfnd = 0; + flags = 0; + while ((opt = getopt(argc, argv, "nt:")) != \-1) { + switch (opt) { + case \[aq]n\[aq]: + flags = 1; + break; + case \[aq]t\[aq]: + nsecs = atoi(optarg); + tfnd = 1; + break; + default: /* \[aq]?\[aq] */ + fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\en", + argv[0]); + exit(EXIT_FAILURE); + } + } +\& + printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\en", + flags, tfnd, nsecs, optind); +\& + if (optind >= argc) { + fprintf(stderr, "Expected argument after options\en"); + exit(EXIT_FAILURE); + } +\& + printf("name argument = %s\en", argv[optind]); +\& + /* Other code omitted */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS getopt_long() +The following example program illustrates the use of +.BR getopt_long () +with most of its features. +.P +.\" SRC BEGIN (getopt_long.c) +.EX +#include <getopt.h> +#include <stdio.h> /* for printf */ +#include <stdlib.h> /* for exit */ +\& +int +main(int argc, char *argv[]) +{ + int c; + int digit_optind = 0; +\& + while (1) { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = { + {"add", required_argument, 0, 0 }, + {"append", no_argument, 0, 0 }, + {"delete", required_argument, 0, 0 }, + {"verbose", no_argument, 0, 0 }, + {"create", required_argument, 0, \[aq]c\[aq]}, + {"file", required_argument, 0, 0 }, + {0, 0, 0, 0 } + }; +\& + c = getopt_long(argc, argv, "abc:d:012", + long_options, &option_index); + if (c == \-1) + break; +\& + switch (c) { + case 0: + printf("option %s", long_options[option_index].name); + if (optarg) + printf(" with arg %s", optarg); + printf("\en"); + break; +\& + case \[aq]0\[aq]: + case \[aq]1\[aq]: + case \[aq]2\[aq]: + if (digit_optind != 0 && digit_optind != this_option_optind) + printf("digits occur in two different argv\-elements.\en"); + digit_optind = this_option_optind; + printf("option %c\en", c); + break; +\& + case \[aq]a\[aq]: + printf("option a\en"); + break; +\& + case \[aq]b\[aq]: + printf("option b\en"); + break; +\& + case \[aq]c\[aq]: + printf("option c with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]d\[aq]: + printf("option d with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]?\[aq]: + break; +\& + default: + printf("?? getopt returned character code 0%o ??\en", c); + } + } +\& + if (optind < argc) { + printf("non\-option ARGV\-elements: "); + while (optind < argc) + printf("%s ", argv[optind++]); + printf("\en"); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getopt (1), +.BR getsubopt (3) diff --git a/man/man3/getopt_long.3 b/man/man3/getopt_long.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/getopt_long.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/getopt_long_only.3 b/man/man3/getopt_long_only.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/getopt_long_only.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/getpass.3 b/man/man3/getpass.3 new file mode 100644 index 0000000..6986a83 --- /dev/null +++ b/man/man3/getpass.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getpass 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpass \- get a password +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "[[deprecated]] char *getpass(const char *" prompt ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpass (): +.nf + Since glibc 2.2.2: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.2.2: + none +.fi +.SH DESCRIPTION +This function is obsolete. +Do not use it. +See NOTES. +If you want to read input without terminal echoing enabled, +see the description of the +.I ECHO +flag in +.BR termios (3). +.P +The +.BR getpass () +function opens +.I /dev/tty +(the controlling terminal of the process), outputs the string +.IR prompt , +turns off echoing, reads one line (the "password"), +restores the terminal state and closes +.I /dev/tty +again. +.SH RETURN VALUE +The function +.BR getpass () +returns a pointer to a static buffer containing (the first +.B PASS_MAX +bytes of) the password without the trailing +newline, terminated by a null byte (\[aq]\e0\[aq]). +This buffer may be overwritten by a following call. +On error, the terminal state is restored, +.I errno +is set to indicate the error, and NULL is returned. +.SH ERRORS +.TP +.B ENXIO +The process does not have a controlling terminal. +.SH FILES +.I /dev/tty +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpass () +T} Thread safety MT-Unsafe term +.TE +.SH STANDARDS +None. +.SH HISTORY +Version 7 AT&T UNIX. +Present in SUSv2, but marked LEGACY. +Removed in POSIX.1-2001. +.SH NOTES +.\" For libc4 and libc5, the prompt is not written to +.\" .I /dev/tty +.\" but to +.\" .IR stderr . +.\" Moreover, if +.\" .I /dev/tty +.\" cannot be opened, the password is read from +.\" .IR stdin . +.\" The static buffer has length 128 so that only the first 127 +.\" bytes of the password are returned. +.\" While reading the password, signal generation +.\" .RB ( SIGINT , +.\" .BR SIGQUIT , +.\" .BR SIGSTOP , +.\" .BR SIGTSTP ) +.\" is disabled and the corresponding characters +.\" (usually control-C, control-\e, control-Z and control-Y) +.\" are transmitted as part of the password. +.\" Since libc 5.4.19 also line editing is disabled, so that also +.\" backspace and the like will be seen as part of the password. +You should use instead +.BR readpassphrase (3bsd), +provided by +.IR libbsd . +.P +In the GNU C library implementation, if +.I /dev/tty +cannot be opened, the prompt is written to +.I stderr +and the password is read from +.IR stdin . +There is no limit on the length of the password. +Line editing is not disabled. +.P +According to SUSv2, the value of +.B PASS_MAX +must be defined in +.I <limits.h> +in case it is smaller than 8, and can in any case be obtained using +.IR sysconf(_SC_PASS_MAX) . +However, POSIX.2 withdraws the constants +.B PASS_MAX +and +.BR _SC_PASS_MAX , +and the function +.BR getpass (). +.\" Libc4 and libc5 have never supported +.\" .B PASS_MAX +.\" or +.\" .BR _SC_PASS_MAX . +The glibc version accepts +.B _SC_PASS_MAX +and returns +.B BUFSIZ +(e.g., 8192). +.SH BUGS +The calling process should zero the password as soon as possible to avoid +leaving the cleartext password visible in the process's address space. +.SH SEE ALSO +.BR crypt (3) diff --git a/man/man3/getprotobyname.3 b/man/man3/getprotobyname.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/getprotobyname.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/getprotobyname_r.3 b/man/man3/getprotobyname_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man/man3/getprotobyname_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man/man3/getprotobynumber.3 b/man/man3/getprotobynumber.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/getprotobynumber.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/getprotobynumber_r.3 b/man/man3/getprotobynumber_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man/man3/getprotobynumber_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man/man3/getprotoent.3 b/man/man3/getprotoent.3 new file mode 100644 index 0000000..1052299 --- /dev/null +++ b/man/man3/getprotoent.3 @@ -0,0 +1,192 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH getprotoent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getprotoent, getprotobyname, getprotobynumber, setprotoent, +endprotoent \- get protocol entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.B struct protoent *getprotoent(void); +.P +.BI "struct protoent *getprotobyname(const char *" name ); +.BI "struct protoent *getprotobynumber(int " proto ); +.P +.BI "void setprotoent(int " stayopen ); +.B void endprotoent(void); +.fi +.SH DESCRIPTION +The +.BR getprotoent () +function reads the next entry from the protocols database (see +.BR protocols (5)) +and returns a +.I protoent +structure +containing the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getprotobyname () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol name +.IR name . +A connection is opened to the database if necessary. +.P +The +.BR getprotobynumber () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol number +.IR number . +A connection is opened to the database if necessary. +.P +The +.BR setprotoent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getproto* () +functions. +.P +The +.BR endprotoent () +function closes the connection to the database. +.P +The +.I protoent +structure is defined in +.I <netdb.h> +as follows: +.P +.in +4n +.EX +struct protoent { + char *p_name; /* official protocol name */ + char **p_aliases; /* alias list */ + int p_proto; /* protocol number */ +} +.EE +.in +.P +The members of the +.I protoent +structure are: +.TP +.I p_name +The official name of the protocol. +.TP +.I p_aliases +A NULL-terminated list of alternative names for the protocol. +.TP +.I p_proto +The protocol number. +.SH RETURN VALUE +The +.BR getprotoent (), +.BR getprotobyname (), +and +.BR getprotobynumber () +functions return a pointer to a +statically allocated +.I protoent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.PD 0 +.TP +.I /etc/protocols +protocol database file +.PD +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getprotoent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protoent +race:protoentbuf locale +T} +T{ +.na +.nh +.BR getprotobyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protobyname +locale +T} +T{ +.na +.nh +.BR getprotobynumber () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protobynumber +locale +T} +T{ +.na +.nh +.BR setprotoent (), +.BR endprotoent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protoent +locale +T} +.TE +.P +In the above table, +.I protoent +in +.I race:protoent +signifies that if any of the functions +.BR setprotoent (), +.BR getprotoent (), +or +.BR endprotoent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent_r (3), +.BR getservent (3), +.BR protocols (5) diff --git a/man/man3/getprotoent_r.3 b/man/man3/getprotoent_r.3 new file mode 100644 index 0000000..ac2f160 --- /dev/null +++ b/man/man3/getprotoent_r.3 @@ -0,0 +1,243 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getprotoent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getprotoent_r, getprotobyname_r, getprotobynumber_r \- get +protocol entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "int getprotoent_r(struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.BI "int getprotobyname_r(const char *restrict " name , +.BI " struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.BI "int getprotobynumber_r(int " proto , +.BI " struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getprotoent_r (), +.BR getprotobyname_r (), +.BR getprotobynumber_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getprotoent_r (), +.BR getprotobyname_r (), +and +.BR getprotobynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getprotoent (3), +.BR getprotobyname (3), +and +.BR getprotobynumber (3). +They differ in the way that the +.I protoent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I protoent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I protoent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer. +.\" The 1024 byte value is also what the Solaris man page suggests. -- mtk +.P +If the function call successfully obtains a protocol record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getprotobyname_r (), +.BR getprotobynumber_r ()), +or end of input +.RB ( getprotoent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getprotoent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getprotoent_r (), +.BR getprotobyname_r (), +.BR getprotobynumber_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below uses +.BR getprotobyname_r () +to retrieve the protocol record for the protocol named +in its first command-line argument. +If a second (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getprotobyname_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.P +.in +4n +.EX +.RB "$" " ./a.out tcp 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=78) +p_name=tcp; p_proto=6; aliases=TCP +.RB "$" " ./a.out xxx 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=100) +Call failed/record not found +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getprotoent_r.c) +.EX +#define _GNU_SOURCE +#include <ctype.h> +#include <errno.h> +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define MAX_BUF 10000 +\& +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, s; + struct protoent result_buf; + struct protoent *result; + char buf[MAX_BUF]; +\& + if (argc < 2) { + printf("Usage: %s proto\-name [buflen]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + buflen = 1024; + if (argc > 2) + buflen = atoi(argv[2]); +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } +\& + erange_cnt = 0; + do { + s = getprotobyname_r(argv[1], &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\en"); + erange_cnt++; +\& + /* Increment a byte at a time so we can see exactly + what size buffer was required. */ +\& + buflen++; +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); +\& + printf("getprotobyname_r() returned: %s (buflen=%d)\en", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); +\& + if (s != 0 || result == NULL) { + printf("Call failed/record not found\en"); + exit(EXIT_FAILURE); + } +\& + printf("p_name=%s; p_proto=%d; aliases=", + result_buf.p_name, result_buf.p_proto); + for (char **p = result_buf.p_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getprotoent (3), +.BR protocols (5) diff --git a/man/man3/getpt.3 b/man/man3/getpt.3 new file mode 100644 index 0000000..8b2064f --- /dev/null +++ b/man/man3/getpt.3 @@ -0,0 +1,74 @@ +'\" t +.\" This man page was written by Jeremy Phelps <jphelps@notreached.net>. +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and modify at will. +.\" %%%LICENSE_END +.\" +.TH getpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpt \- open a new pseudoterminal master +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <stdlib.h> +.P +.B "int getpt(void);" +.fi +.SH DESCRIPTION +.BR getpt () +opens a new pseudoterminal device and returns a file descriptor +that refers to that device. +It is equivalent to opening the pseudoterminal multiplexor device +.P +.in +4n +.EX +open("/dev/ptmx", O_RDWR); +.EE +.in +.P +on Linux systems, though the pseudoterminal multiplexor device is located +elsewhere on some systems that use the GNU C library. +.SH RETURN VALUE +.BR getpt () +returns an open file descriptor upon successful completion. +Otherwise, it +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.BR getpt () +can fail with various errors described in +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpt () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use +.BR posix_openpt (3) +instead. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR ptmx (4), +.BR pty (7) diff --git a/man/man3/getpw.3 b/man/man3/getpw.3 new file mode 100644 index 0000000..39e8483 --- /dev/null +++ b/man/man3/getpw.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH getpw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpw \- reconstruct password line entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <sys/types.h> +.B #include <pwd.h> +.P +.BI "[[deprecated]] int getpw(uid_t " uid ", char *" buf ); +.fi +.SH DESCRIPTION +The +.BR getpw () +function reconstructs the password line entry for +the given user ID \fIuid\fP in the buffer \fIbuf\fP. +The returned buffer contains a line of format +.P +.in +4n +.EX +.B name:passwd:uid:gid:gecos:dir:shell +.EE +.in +.P +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpw () +function returns 0 on success; on error, it returns \-1, and +.I errno +is set to indicate the error. +.P +If +.I uid +is not found in the password database, +.BR getpw () +returns \-1, sets +.I errno +to 0, and leaves +.I buf +unchanged. +.SH ERRORS +.TP +.BR 0 " or " ENOENT +No user corresponding to +.IR uid . +.TP +.B EINVAL +.I buf +is NULL. +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpw () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr2. +.SH BUGS +The +.BR getpw () +function is dangerous as it may overflow the provided buffer +.IR buf . +It is obsoleted by +.BR getpwuid (3). +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwent.3 b/man/man3/getpwent.3 new file mode 100644 index 0000000..6b3ef03 --- /dev/null +++ b/man/man3/getpwent.3 @@ -0,0 +1,191 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH getpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwent, setpwent, endpwent \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <pwd.h> +.P +.B struct passwd *getpwent(void); +.B void setpwent(void); +.B void endpwent(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwent (), +.BR setpwent (), +.BR endpwent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getpwent () +function returns a pointer to a structure containing +the broken-out fields of a record from the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP). +The first time +.BR getpwent () +is called, it returns the first entry; thereafter, it returns successive +entries. +.P +The +.BR setpwent () +function rewinds to the beginning +of the password database. +.P +The +.BR endpwent () +function is used to close the password database +after all processing has been performed. +.P +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurred. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (), +.BR getpwnam (3), +or +.BR getpwuid (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" to allocate the passwd structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent +race:pwentbuf locale +T} +T{ +.na +.nh +.BR setpwent (), +.BR endpwent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent locale +T} +.TE +.P +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +or +.BR endpwent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent_r (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwent_r.3 b/man/man3/getpwent_r.3 new file mode 100644 index 0000000..60f1414 --- /dev/null +++ b/man/man3/getpwent_r.3 @@ -0,0 +1,227 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getpwent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwent_r, fgetpwent_r \- get passwd file entry reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <pwd.h> +.P +.BI "int getpwent_r(struct passwd *restrict " pwbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " pwbufp ); +.BI "int fgetpwent_r(FILE *restrict " stream \ +", struct passwd *restrict " pwbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " pwbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwent_r (), +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR fgetpwent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR getpwent_r () +and +.BR fgetpwent_r () +are the reentrant versions of +.BR getpwent (3) +and +.BR fgetpwent (3). +The former reads the next passwd entry from the stream initialized by +.BR setpwent (3). +The latter reads the next passwd entry from +.IR stream . +.P +The \fIpasswd\fP structure is defined in +.I <pwd.h> +as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.P +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to user +name, password, gecos field, home directory and shell. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I pwbuf +that can hold a \fIstruct passwd\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct passwd\fP read from the stream, +is stored in the provided buffer +.IR *pwbuf , +and a pointer to this \fIstruct passwd\fP is returned in +.IR *pwbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *pwbufp +is a pointer to the \fIstruct passwd\fP. +On error, these functions return an error value and +.I *pwbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent locale +T} +T{ +.na +.nh +.BR fgetpwent_r () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +.BR endpwent (), +or +.BR getpwent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Other systems use the prototype +.P +.in +4n +.EX +struct passwd * +getpwent_r(struct passwd *pwd, char *buf, int buflen); +.EE +.in +.P +or, better, +.P +.in +4n +.EX +int +getpwent_r(struct passwd *pwd, char *buf, int buflen, + FILE **pw_fp); +.EE +.in +.SH STANDARDS +None. +.SH HISTORY +These functions are done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +.SH NOTES +The function +.BR getpwent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLES +.\" SRC BEGIN (getpwent_r.c) +.EX +#define _GNU_SOURCE +#include <pwd.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define BUFLEN 4096 +\& +int +main(void) +{ + struct passwd pw; + struct passwd *pwp; + char buf[BUFLEN]; + int i; +\& + setpwent(); + while (1) { + i = getpwent_r(&pw, buf, sizeof(buf), &pwp); + if (i) + break; + printf("%s (%jd)\etHOME %s\etSHELL %s\en", pwp\->pw_name, + (intmax_t) pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell); + } + endpwent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include <errno.h> +.\" #include <stdlib.h> +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getpwent_r: %s", strerror(i)); +.\" exit(EXIT_SUCCESS); +.\" } +.\" SRC END +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwnam.3 b/man/man3/getpwnam.3 new file mode 100644 index 0000000..3547ca5 --- /dev/null +++ b/man/man3/getpwnam.3 @@ -0,0 +1,350 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-05-27 by Martin Schulze (joey@linux.de) +.\" Modified 2003-11-15 by aeb +.\" 2008-11-07, mtk, Added an example program for getpwnam_r(). +.\" +.TH getpwnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <pwd.h> +.P +.BI "struct passwd *getpwnam(const char *" name ); +.BI "struct passwd *getpwuid(uid_t " uid ); +.P +.BI "int getpwnam_r(const char *restrict " name ", \ +struct passwd *restrict " pwd , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " result ); +.BI "int getpwuid_r(uid_t " uid ", struct passwd *restrict " pwd , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwnam_r (), +.BR getpwuid_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getpwnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP) +that matches the username +.IR name . +.P +The +.BR getpwuid () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +that matches the user ID +.IR uid . +.P +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +See +.BR passwd (5) +for more information about these fields. +.P +The +.BR getpwnam_r () +and +.BR getpwuid_r () +functions obtain the same information as +.BR getpwnam () +and +.BR getpwuid (), +but store the retrieved +.I passwd +structure in the space pointed to by +.IR pwd . +The string fields pointed to by the members of the +.I passwd +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.P +The call +.P +.in +4n +.EX +sysconf(_SC_GETPW_R_SIZE_MAX) +.EE +.in +.P +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getpwnam () +and +.BR getpwuid () +functions return a pointer to a +.I passwd +structure, or NULL if the matching entry is not found or +an error occurs. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (3), +.BR getpwnam (), +or +.BR getpwuid (). +(Do not pass the returned pointer to +.BR free (3).) +.P +On success, +.BR getpwnam_r () +and +.BR getpwuid_r () +return zero, and set +.I *result +to +.IR pwd . +If no matching password record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..." +The given +.I name +or +.I uid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwnam locale +T} +T{ +.na +.nh +.BR getpwuid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwuid locale +T} +T{ +.na +.nh +.BR getpwnam_r (), +.BR getpwuid_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +.TE +.SH VERSIONS +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX.1-2001. +It does not call "not found" an error, and hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT +.\" since glibc 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.P +The +.I pw_dir +field contains the name of the initial working directory of the user. +Login programs use the value of this field to initialize the +.B HOME +environment variable for the login shell. +An application that wants to determine its user's home directory +should inspect the value of +.B HOME +(rather than the value +.IR getpwuid(getuid())\->pw_dir ) +since this allows the user to modify their notion of +"the home directory" during a login session. +To determine the (initial) home directory of another user, +it is necessary to use +.I getpwnam("username")\->pw_dir +or similar. +.SH EXAMPLES +The program below demonstrates the use of +.BR getpwnam_r () +to find the full username and user ID for the username +supplied as a command-line argument. +.P +.\" SRC BEGIN (getpwnam.c) +.EX +#include <errno.h> +#include <pwd.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + struct passwd pwd; + struct passwd *result; + char *buf; + long bufsize; + int s; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s username\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + bufsize = sysconf(_SC_GETPW_R_SIZE_MAX); + if (bufsize == \-1) /* Value was indeterminate */ + bufsize = 16384; /* Should be more than enough */ +\& + buf = malloc(bufsize); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result); + if (result == NULL) { + if (s == 0) + printf("Not found\en"); + else { + errno = s; + perror("getpwnam_r"); + } + exit(EXIT_FAILURE); + } +\& + printf("Name: %s; UID: %jd\en", pwd.pw_gecos, + (intmax_t) pwd.pw_uid); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getgrnam (3), +.BR getpw (3), +.BR getpwent (3), +.BR getspnam (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwnam_r.3 b/man/man3/getpwnam_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwnam_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getpwuid.3 b/man/man3/getpwuid.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwuid.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getpwuid_r.3 b/man/man3/getpwuid_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwuid_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getrpcbyname.3 b/man/man3/getrpcbyname.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/getrpcbyname.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/getrpcbyname_r.3 b/man/man3/getrpcbyname_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man/man3/getrpcbyname_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man/man3/getrpcbynumber.3 b/man/man3/getrpcbynumber.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/getrpcbynumber.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/getrpcbynumber_r.3 b/man/man3/getrpcbynumber_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man/man3/getrpcbynumber_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man/man3/getrpcent.3 b/man/man3/getrpcent.3 new file mode 100644 index 0000000..e1c2f9e --- /dev/null +++ b/man/man3/getrpcent.3 @@ -0,0 +1,136 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI +.TH getrpcent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcent, getrpcbyname, getrpcbynumber, setrpcent, endrpcent \- get +RPC entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.B struct rpcent *getrpcent(void); +.P +.BI "struct rpcent *getrpcbyname(const char *" name ); +.BI "struct rpcent *getrpcbynumber(int " number ); +.P +.BI "void setrpcent(int " stayopen ); +.B void endrpcent(void); +.fi +.SH DESCRIPTION +The +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +functions each return a pointer to an object with the +following structure containing the broken-out +fields of an entry in the RPC program number data base. +.P +.in +4n +.EX +struct rpcent { + char *r_name; /* name of server for this RPC program */ + char **r_aliases; /* alias list */ + long r_number; /* RPC program number */ +}; +.EE +.in +.P +The members of this structure are: +.TP +.I r_name +The name of the server for this RPC program. +.TP +.I r_aliases +A NULL-terminated list of alternate names for the RPC program. +.TP +.I r_number +The RPC program number for this service. +.P +The +.BR getrpcent () +function reads the next entry from the database. +A connection is opened to the database if necessary. +.P +The +.BR setrpcent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getrpc* () +functions. +.P +The +.BR endrpcent () +function closes the connection to the database. +.P +The +.BR getrpcbyname () +and +.BR getrpcbynumber () +functions sequentially search from the beginning +of the file until a matching RPC program name or +program number is found, or until end-of-file is encountered. +.SH RETURN VALUE +On success, +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +return a pointer to a statically allocated +.I rpcent +structure. +NULL is returned on EOF or error. +.SH FILES +.TP +.I /etc/rpc +RPC program number database. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcent (), +.BR getrpcbyname (), +.BR getrpcbynumber () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR setrpcent (), +.BR endrpcent () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +BSD, Solaris. +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. +.SH SEE ALSO +.BR getrpcent_r (3), +.BR rpc (5), +.BR rpcinfo (8), +.BR ypserv (8) diff --git a/man/man3/getrpcent_r.3 b/man/man3/getrpcent_r.3 new file mode 100644 index 0000000..aa20597 --- /dev/null +++ b/man/man3/getrpcent_r.3 @@ -0,0 +1,136 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getrpcent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcent_r, getrpcbyname_r, getrpcbynumber_r \- get +RPC entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "int getrpcent_r(struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.BI "int getrpcbyname_r(const char *" name , +.BI " struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.BI "int getrpcbynumber_r(int " number , +.BI " struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getrpcent_r (), +.BR getrpcbyname_r (), +and +.BR getrpcbynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getrpcent (3), +.BR getrpcbyname (3), +and +.BR getrpcbynumber (3). +They differ in the way that the +.I rpcent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I rpcent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I rpcent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains an RPC record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getrpcbyname_r (), +.BR getrpcbynumber_r ()), +or end of input +.RB ( getrpcent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getrpcent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getrpcent (3), +.BR rpc (5) diff --git a/man/man3/getrpcport.3 b/man/man3/getrpcport.3 new file mode 100644 index 0000000..23b1171 --- /dev/null +++ b/man/man3/getrpcport.3 @@ -0,0 +1,59 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI +.TH getrpcport 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcport \- get RPC port number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <rpc/rpc.h>" +.P +.BI "int getrpcport(const char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned int " proto ); +.fi +.SH DESCRIPTION +.BR getrpcport () +returns the port number for version +.I versnum +of the RPC program +.I prognum +running on +.I host +and using protocol +.IR proto . +It returns 0 if it cannot contact the portmapper, or if +.I prognum +is not registered. +If +.I prognum +is registered but not with version +.IR versnum , +it will still return a port number (for some version of the program) +indicating that the program is indeed registered. +The version mismatch will be detected upon the first call to the service. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcport () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +BSD, Solaris. diff --git a/man/man3/gets.3 b/man/man3/gets.3 new file mode 100644 index 0000000..371829b --- /dev/null +++ b/man/man3/gets.3 @@ -0,0 +1,107 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 2013-12-31, David Malcolm <dmalcolm@redhat.com> +.\" Split gets(3) into its own page; fgetc() et al. move to fgetc(3) +.TH gets 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gets \- get a string from standard input (DEPRECATED) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "[[deprecated]] char *gets(char *" "s" ); +.fi +.SH DESCRIPTION +.IR "Never use this function" . +.P +.BR gets () +reads a line from +.I stdin +into the buffer pointed to by +.I s +until either a terminating newline or +.BR EOF , +which it replaces with a null byte (\[aq]\e0\[aq]). +No check for buffer overrun is performed (see BUGS below). +.SH RETURN VALUE +.BR gets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +However, given the lack of buffer overrun checking, there can be no +guarantees that the function will even return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gets () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +LSB deprecates +.BR gets (). +POSIX.1-2008 marks +.BR gets () +obsolescent. +ISO C11 removes the specification of +.BR gets () +from the C language, and since glibc 2.16, +glibc header files don't expose the function declaration if the +.B _ISOC11_SOURCE +feature test macro is defined. +.SH BUGS +Never use +.BR gets (). +Because it is impossible to tell without knowing the data in advance how many +characters +.BR gets () +will read, and because +.BR gets () +will continue to store characters past the end of the buffer, +it is extremely dangerous to use. +It has been used to break computer security. +Use +.BR fgets () +instead. +.P +For more information, see CWE-242 (aka "Use of Inherently Dangerous +Function") at +http://cwe.mitre.org/data/definitions/242.html +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetc (3), +.BR fgets (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) diff --git a/man/man3/getservbyname.3 b/man/man3/getservbyname.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/getservbyname.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/getservbyname_r.3 b/man/man3/getservbyname_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man/man3/getservbyname_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man/man3/getservbyport.3 b/man/man3/getservbyport.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/getservbyport.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/getservbyport_r.3 b/man/man3/getservbyport_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man/man3/getservbyport_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man/man3/getservent.3 b/man/man3/getservent.3 new file mode 100644 index 0000000..b3c4b26 --- /dev/null +++ b/man/man3/getservent.3 @@ -0,0 +1,209 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze <joey@infodrom.north.de> +.\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze <joey@infodrom.north.de> +.\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton) +.\" +.TH getservent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getservent, getservbyname, getservbyport, setservent, endservent \- +get service entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.B struct servent *getservent(void); +.P +.BI "struct servent *getservbyname(const char *" name ", const char *" proto ); +.BI "struct servent *getservbyport(int " port ", const char *" proto ); +.P +.BI "void setservent(int " stayopen ); +.B void endservent(void); +.fi +.SH DESCRIPTION +The +.BR getservent () +function reads the next entry from the services database (see +.BR services (5)) +and returns a +.I servent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getservbyname () +function returns a +.I servent +structure +for the entry from the database +that matches the service +.I name +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.P +The +.BR getservbyport () +function returns a +.I servent +structure +for the entry from the database +that matches the port +.I port +(given in network byte order) +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.P +The +.BR setservent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getserv* () +functions. +.P +The +.BR endservent () +function closes the connection to the database. +.P +The +.I servent +structure is defined in +.I <netdb.h> +as follows: +.P +.in +4n +.EX +struct servent { + char *s_name; /* official service name */ + char **s_aliases; /* alias list */ + int s_port; /* port number */ + char *s_proto; /* protocol to use */ +} +.EE +.in +.P +The members of the +.I servent +structure are: +.TP +.I s_name +The official name of the service. +.TP +.I s_aliases +A NULL-terminated list of alternative names for the service. +.TP +.I s_port +The port number for the service given in network byte order. +.TP +.I s_proto +The name of the protocol to use with this service. +.SH RETURN VALUE +The +.BR getservent (), +.BR getservbyname (), +and +.BR getservbyport () +functions return a pointer to a +statically allocated +.I servent +structure, or NULL if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/services +services database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getservent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servent +race:serventbuf locale +T} +T{ +.na +.nh +.BR getservbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servbyname +locale +T} +T{ +.na +.nh +.BR getservbyport () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servbyport +locale +T} +T{ +.na +.nh +.BR setservent (), +.BR endservent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servent +locale +T} +.TE +.P +In the above table, +.I servent +in +.I race:servent +signifies that if any of the functions +.BR setservent (), +.BR getservent (), +or +.BR endservent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent (3), +.BR getservent_r (3), +.BR services (5) diff --git a/man/man3/getservent_r.3 b/man/man3/getservent_r.3 new file mode 100644 index 0000000..e2fe200 --- /dev/null +++ b/man/man3/getservent_r.3 @@ -0,0 +1,249 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getservent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getservent_r, getservbyname_r, getservbyport_r \- get +service entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "int getservent_r(struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.BI "int getservbyname_r(const char *restrict " name , +.BI " const char *restrict " proto , +.BI " struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.BI "int getservbyport_r(int " port , +.BI " const char *restrict " proto , +.BI " struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getservent_r (), +.BR getservbyname_r (), +and +.BR getservbyport_r () +functions are the reentrant equivalents of, respectively, +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +They differ in the way that the +.I servent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I servent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I servent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains a service record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in errors. +.P +On error, record not found +.RB ( getservbyname_r (), +.BR getservbyport_r ()), +or end of input +.RB ( getservent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getservent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below uses +.BR getservbyport_r () +to retrieve the service record for the port and protocol named +in its first command-line argument. +If a third (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getservbyport_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.P +.in +4n +.EX +.RB "$" " ./a.out 7 tcp 1" +ERANGE! Retrying with larger buffer +getservbyport_r() returned: 0 (success) (buflen=87) +s_name=echo; s_proto=tcp; s_port=7; aliases= +.RB "$" " ./a.out 77777 tcp" +getservbyport_r() returned: 0 (success) (buflen=1024) +Call failed/record not found +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getservent_r.c) +.EX +#define _GNU_SOURCE +#include <ctype.h> +#include <errno.h> +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define MAX_BUF 10000 +\& +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, port, s; + struct servent result_buf; + struct servent *result; + char buf[MAX_BUF]; + char *protop; +\& + if (argc < 3) { + printf("Usage: %s port\-num proto\-name [buflen]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + port = htons(atoi(argv[1])); + protop = (strcmp(argv[2], "null") == 0 || + strcmp(argv[2], "NULL") == 0) ? NULL : argv[2]; +\& + buflen = 1024; + if (argc > 3) + buflen = atoi(argv[3]); +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } +\& + erange_cnt = 0; + do { + s = getservbyport_r(port, protop, &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\en"); + erange_cnt++; +\& + /* Increment a byte at a time so we can see exactly + what size buffer was required. */ +\& + buflen++; +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); +\& + printf("getservbyport_r() returned: %s (buflen=%d)\en", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); +\& + if (s != 0 || result == NULL) { + printf("Call failed/record not found\en"); + exit(EXIT_FAILURE); + } +\& + printf("s_name=%s; s_proto=%s; s_port=%d; aliases=", + result_buf.s_name, result_buf.s_proto, + ntohs(result_buf.s_port)); + for (char **p = result_buf.s_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getservent (3), +.BR services (5) diff --git a/man/man3/getspent.3 b/man/man3/getspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getspent_r.3 b/man/man3/getspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getspnam.3 b/man/man3/getspnam.3 new file mode 100644 index 0000000..03fca91 --- /dev/null +++ b/man/man3/getspnam.3 @@ -0,0 +1,344 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and +.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH getspnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, +fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, +lckpwdf, ulckpwdf \- get shadow password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +/* General shadow password file API */ +.B #include <shadow.h> +.P +.BI "struct spwd *getspnam(const char *" name ); +.B struct spwd *getspent(void); +.P +.B void setspent(void); +.B void endspent(void); +.P +.BI "struct spwd *fgetspent(FILE *" stream ); +.BI "struct spwd *sgetspent(const char *" s ); +.P +.BI "int putspent(const struct spwd *" p ", FILE *" stream ); +.P +.B int lckpwdf(void); +.B int ulckpwdf(void); +.P +/* GNU extension */ +.B #include <shadow.h> +.P +.BI "int getspent_r(struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.P +.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getspent_r (), +.BR getspnam_r (), +.BR fgetspent_r (), +.BR sgetspent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Long ago it was considered safe to have encrypted passwords openly +visible in the password file. +When computers got faster and people +got more security-conscious, this was no longer acceptable. +Julianne Frances Haugh implemented the shadow password suite +that keeps the encrypted passwords in +the shadow password database +(e.g., the local shadow password file +.IR /etc/shadow , +NIS, and LDAP), +readable only by root. +.P +The functions described below resemble those for +the traditional password database +(e.g., see +.BR getpwnam (3) +and +.BR getpwent (3)). +.\" FIXME . I've commented out the following for the +.\" moment. The relationship between PAM and nsswitch.conf needs +.\" to be clearly documented in one place, which is pointed to by +.\" the pages for the user, group, and shadow password functions. +.\" (Jul 2005, mtk) +.\" +.\" This shadow password setup has been superseded by PAM +.\" (pluggable authentication modules), and the file +.\" .I /etc/nsswitch.conf +.\" now describes the sources to be used. +.P +The +.BR getspnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the shadow password database +that matches the username +.IR name . +.P +The +.BR getspent () +function returns a pointer to the next entry in the shadow password +database. +The position in the input stream is initialized by +.BR setspent (). +When done reading, the program may call +.BR endspent () +so that resources can be deallocated. +.\" some systems require a call of setspent() before the first getspent() +.\" glibc does not +.P +The +.BR fgetspent () +function is similar to +.BR getspent () +but uses the supplied stream instead of the one implicitly opened by +.BR setspent (). +.P +The +.BR sgetspent () +function parses the supplied string +.I s +into a struct +.IR spwd . +.P +The +.BR putspent () +function writes the contents of the supplied struct +.I spwd +.I *p +as a text line in the shadow password file format to +.IR stream . +String entries with value NULL and numerical entries with value \-1 +are written as an empty string. +.P +The +.BR lckpwdf () +function is intended to protect against multiple simultaneous accesses +of the shadow password database. +It tries to acquire a lock, and returns 0 on success, +or \-1 on failure (lock not obtained within 15 seconds). +The +.BR ulckpwdf () +function releases the lock again. +Note that there is no protection against direct access of the shadow +password file. +Only programs that use +.BR lckpwdf () +will notice the lock. +.P +These were the functions that formed the original shadow API. +They are widely available. +.\" Also in libc5 +.\" SUN doesn't have sgetspent() +.SS Reentrant versions +Analogous to the reentrant functions for the password database, glibc +also has reentrant functions for the shadow password database. +The +.BR getspnam_r () +function is like +.BR getspnam () +but stores the retrieved shadow password structure in the space pointed to by +.IR spbuf . +This shadow password structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *spbufp . +.P +The functions +.BR getspent_r (), +.BR fgetspent_r (), +and +.BR sgetspent_r () +are similarly analogous to their nonreentrant counterparts. +.P +Some non-glibc systems also have functions with these names, +often with different prototypes. +.\" SUN doesn't have sgetspent_r() +.SS Structure +The shadow password structure is defined in \fI<shadow.h>\fP as follows: +.P +.in +4n +.EX +struct spwd { + char *sp_namp; /* Login name */ + char *sp_pwdp; /* Encrypted password */ + long sp_lstchg; /* Date of last change + (measured in days since + 1970\-01\-01 00:00:00 +0000 (UTC)) */ + long sp_min; /* Min # of days between changes */ + long sp_max; /* Max # of days between changes */ + long sp_warn; /* # of days before password expires + to warn user to change it */ + long sp_inact; /* # of days after password expires + until account is disabled */ + long sp_expire; /* Date when account expires + (measured in days since + 1970\-01\-01 00:00:00 +0000 (UTC)) */ + unsigned long sp_flag; /* Reserved */ +}; +.EE +.in +.SH RETURN VALUE +The functions that return a pointer return NULL if no more entries +are available or if an error occurs during processing. +The functions which have \fIint\fP as the return value return 0 for +success and \-1 for failure, with +.I errno +set to indicate the error. +.P +For the nonreentrant functions, the return value may point to static area, +and may be overwritten by subsequent calls to these functions. +.P +The reentrant functions return zero on success. +In case of error, an error number is returned. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to access the shadow password file. +.TP +.B ERANGE +Supplied buffer is too small. +.SH FILES +.TP +.I /etc/shadow +local shadow password database file +.TP +.I /etc/.pwd.lock +lock file +.P +The include file +.I <paths.h> +defines the constant +.B _PATH_SHADOW +to the pathname of the shadow password file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getspnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspnam locale +T} +T{ +.na +.nh +.BR getspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspent +race:spentbuf locale +T} +T{ +.na +.nh +.BR setspent (), +.BR endspent (), +.BR getspent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspent locale +T} +T{ +.na +.nh +.BR fgetspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fgetspent +T} +T{ +.na +.nh +.BR sgetspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:sgetspent +T} +T{ +.na +.nh +.BR putspent (), +.BR getspnam_r (), +.BR sgetspent_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +T{ +.na +.nh +.BR lckpwdf (), +.BR ulckpwdf (), +.BR fgetspent_r () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.P +In the above table, +.I getspent +in +.I race:getspent +signifies that if any of the functions +.BR setspent (), +.BR getspent (), +.BR getspent_r (), +or +.BR endspent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Many other systems provide a similar API. +.SH STANDARDS +None. +.SH SEE ALSO +.BR getgrnam (3), +.BR getpwnam (3), +.BR getpwnam_r (3), +.BR shadow (5) diff --git a/man/man3/getspnam_r.3 b/man/man3/getspnam_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspnam_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getsubopt.3 b/man/man3/getsubopt.3 new file mode 100644 index 0000000..99bb4dd --- /dev/null +++ b/man/man3/getsubopt.3 @@ -0,0 +1,251 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (C) 2007 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH getsubopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int getsubopt(char **restrict " optionp ", char *const *restrict " tokens , +.BI " char **restrict " valuep ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getsubopt (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +.BR getsubopt () +parses the list of comma-separated suboptions provided in +.IR optionp . +(Such a suboption list is typically produced when +.BR getopt (3) +is used to parse a command line; +see for example the \fI\-o\fP option of +.BR mount (8).) +Each suboption may include an associated value, +which is separated from the suboption name by an equal sign. +The following is an example of the kind of string +that might be passed in +.IR optionp : +.P +.in +4n +.EX +.B ro,name=xyz +.EE +.in +.P +The +.I tokens +argument is a pointer to a NULL-terminated array of pointers to the tokens that +.BR getsubopt () +will look for in +.IR optionp . +The tokens should be distinct, null-terminated strings containing at +least one character, with no embedded equal signs or commas. +.P +Each call to +.BR getsubopt () +returns information about the next unprocessed suboption in +.IR optionp . +The first equal sign in a suboption (if any) is interpreted as a +separator between the name and the value of that suboption. +The value extends to the next comma, +or (for the last suboption) to the end of the string. +If the name of the suboption matches a known name from +.IR tokens , +and a value string was found, +.BR getsubopt () +sets +.I *valuep +to the address of that string. +The first comma in +.I optionp +is overwritten with a null byte, so +.I *valuep +is precisely the "value string" for that suboption. +.P +If the suboption is recognized, but no value string was found, +.I *valuep +is set to NULL. +.P +When +.BR getsubopt () +returns, +.I optionp +points to the next suboption, +or to the null byte (\[aq]\e0\[aq]) at the end of the +string if the last suboption was just processed. +.SH RETURN VALUE +If the first suboption in +.I optionp +is recognized, +.BR getsubopt () +returns the index of the matching suboption element in +.IR tokens . +Otherwise, \-1 is returned and +.I *valuep +is the entire +.IB name [= value ] +string. +.P +Since +.I *optionp +is changed, the first suboption before the call to +.BR getsubopt () +is not (necessarily) the same as the first suboption after +.BR getsubopt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getsubopt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Since +.BR getsubopt () +overwrites any commas it finds in the string +.IR *optionp , +that string must be writable; it cannot be a string constant. +.SH EXAMPLES +The following program expects suboptions following a "\-o" option. +.P +.\" SRC BEGIN (getsubopt.c) +.EX +#define _XOPEN_SOURCE 500 +#include <stdio.h> +#include <stdlib.h> +\& +#include <assert.h> +\& +int +main(int argc, char *argv[]) +{ + enum { + RO_OPT = 0, + RW_OPT, + NAME_OPT + }; + char *const token[] = { + [RO_OPT] = "ro", + [RW_OPT] = "rw", + [NAME_OPT] = "name", + NULL + }; + char *subopts; + char *value; + int opt; +\& + int readonly = 0; + int readwrite = 0; + char *name = NULL; + int errfnd = 0; +\& + while ((opt = getopt(argc, argv, "o:")) != \-1) { + switch (opt) { + case \[aq]o\[aq]: + subopts = optarg; + while (*subopts != \[aq]\e0\[aq] && !errfnd) { +\& + switch (getsubopt(&subopts, token, &value)) { + case RO_OPT: + readonly = 1; + break; +\& + case RW_OPT: + readwrite = 1; + break; +\& + case NAME_OPT: + if (value == NULL) { + fprintf(stderr, + "Missing value for suboption \[aq]%s\[aq]\en", + token[NAME_OPT]); + errfnd = 1; + continue; + } +\& + name = value; + break; +\& + default: + fprintf(stderr, + "No match found for token: /%s/\en", value); + errfnd = 1; + break; + } + } + if (readwrite && readonly) { + fprintf(stderr, + "Only one of \[aq]%s\[aq] and \[aq]%s\[aq] can be specified\en", + token[RO_OPT], token[RW_OPT]); + errfnd = 1; + } + break; +\& + default: + errfnd = 1; + } + } +\& + if (errfnd || argc == 1) { + fprintf(stderr, "\enUsage: %s \-o <suboptstring>\en", argv[0]); + fprintf(stderr, + "suboptions are \[aq]ro\[aq], \[aq]rw\[aq], and \[aq]name=<value>\[aq]\en"); + exit(EXIT_FAILURE); + } +\& + /* Remainder of program... */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getopt (3) diff --git a/man/man3/getttyent.3 b/man/man3/getttyent.3 new file mode 100644 index 0000000..b8869cb --- /dev/null +++ b/man/man3/getttyent.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH getttyent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getttyent, getttynam, setttyent, endttyent \- get ttys file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <ttyent.h>" +.P +.B "struct ttyent *getttyent(void);" +.BI "struct ttyent *getttynam(const char *" name ); +.P +.B "int setttyent(void);" +.B "int endttyent(void);" +.fi +.SH DESCRIPTION +These functions provide an interface to the file +.B _PATH_TTYS +(e.g., +.IR /etc/ttys ). +.P +The function +.BR setttyent () +opens the file or rewinds it if already open. +.P +The function +.BR endttyent () +closes the file. +.P +The function +.BR getttynam () +searches for a given terminal name in the file. +It returns a pointer to a +.I ttyent +structure (description below). +.P +The function +.BR getttyent () +opens the file +.B _PATH_TTYS +(if necessary) and returns the first entry. +If the file is already open, the next entry. +The +.I ttyent +structure has the form: +.P +.in +4n +.EX +struct ttyent { + char *ty_name; /* terminal device name */ + char *ty_getty; /* command to execute, usually getty */ + char *ty_type; /* terminal type for termcap */ + int ty_status; /* status flags */ + char *ty_window; /* command to start up window manager */ + char *ty_comment; /* comment field */ +}; +.EE +.in +.P +.I ty_status +can be: +.P +.in +4n +.EX +#define TTY_ON 0x01 /* enable logins (start ty_getty program) */ +#define TTY_SECURE 0x02 /* allow UID 0 to login */ +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getttyent (), +.BR setttyent (), +.BR endttyent (), +.BR getttynam () +T} Thread safety MT-Unsafe race:ttyent +.TE +.SH STANDARDS +BSD. +.SH NOTES +Under Linux, the file +.IR /etc/ttys , +and the functions described above, are not used. +.SH SEE ALSO +.BR ttyname (3), +.BR ttyslot (3) diff --git a/man/man3/getttynam.3 b/man/man3/getttynam.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/getttynam.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/getusershell.3 b/man/man3/getusershell.3 new file mode 100644 index 0000000..142b36e --- /dev/null +++ b/man/man3/getusershell.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:17:53 1993 by Rik Faith (faith@cs.unc.edu) +.TH getusershell 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getusershell, setusershell, endusershell \- get permitted user shells +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B char *getusershell(void); +.B void setusershell(void); +.B void endusershell(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getusershell (), +.BR setusershell (), +.BR endusershell (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The +.BR getusershell () +function returns the next line from the file +.IR /etc/shells , +opening the file if necessary. +The line should contain +the pathname of a valid user shell. +If +.I /etc/shells +does not exist or +is unreadable, +.BR getusershell () +behaves as if +.I /bin/sh +and +.I /bin/csh +were listed in the file. +.P +The +.BR setusershell () +function rewinds +.IR /etc/shells . +.P +The +.BR endusershell () +function closes +.IR /etc/shells . +.SH RETURN VALUE +The +.BR getusershell () +function returns NULL on end-of-file. +.SH FILES +.I /etc/shells +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getusershell (), +.BR setusershell (), +.BR endusershell () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.SH SEE ALSO +.BR shells (5) diff --git a/man/man3/getutent.3 b/man/man3/getutent.3 new file mode 100644 index 0000000..88ba149 --- /dev/null +++ b/man/man3/getutent.3 @@ -0,0 +1,355 @@ +'\" t +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" Linux libc source code +.\" Solaris manpages +.\" +.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt +.\" <michael@cantor.informatik.rwth-aachen.de> +.\" +.TH getutent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, +utmpname \- access utmp file entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <utmp.h> +.P +.B struct utmp *getutent(void); +.BI "struct utmp *getutid(const struct utmp *" ut ); +.BI "struct utmp *getutline(const struct utmp *" ut ); +.P +.BI "struct utmp *pututline(const struct utmp *" ut ); +.P +.B void setutent(void); +.B void endutent(void); +.P +.BI "int utmpname(const char *" file ); +.fi +.SH DESCRIPTION +New applications should use the POSIX.1-specified "utmpx" versions of +these functions; see STANDARDS. +.P +.BR utmpname () +sets the name of the utmp-format file for the other utmp +functions to access. +If +.BR utmpname () +is not used to set the filename +before the other functions are used, they assume \fB_PATH_UTMP\fP, as +defined in \fI<paths.h>\fP. +.P +.BR setutent () +rewinds the file pointer to the beginning of the utmp file. +It is generally a good idea to call it before any of the other +functions. +.P +.BR endutent () +closes the utmp file. +It should be called when the user +code is done accessing the file with the other functions. +.P +.BR getutent () +reads a line from the current file position in the utmp file. +It returns a pointer to a structure containing the fields of +the line. +The definition of this structure is shown in +.BR utmp (5). +.P +.BR getutid () +searches forward from the current file position in the utmp +file based upon \fIut\fP. +If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP, +\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, +.BR getutid () +will +find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP. +If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, +\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, +.BR getutid () +will find the +first entry whose +.I ut_id +field matches \fIut\->ut_id\fP. +.P +.BR getutline () +searches forward from the current file position in the utmp file. +It scans entries whose +.I ut_type +is \fBUSER_PROCESS\fP +or \fBLOGIN_PROCESS\fP and returns the first one whose +.I ut_line +field +matches \fIut\->ut_line\fP. +.P +.BR pututline () +writes the +.I utmp +structure \fIut\fP into the utmp file. +It uses +.BR getutid () +to search for the proper place in the file to insert +the new entry. +If it cannot find an appropriate slot for \fIut\fP, +.BR pututline () +will append the new entry to the end of the file. +.SH RETURN VALUE +.BR getutent (), +.BR getutid (), +and +.BR getutline () +return a pointer to a \fIstruct utmp\fP on success, +and NULL on failure (which includes the "record not found" case). +This \fIstruct utmp\fP is allocated in static storage, and may be +overwritten by subsequent calls. +.P +On success +.BR pututline () +returns +.IR ut ; +on failure, it returns NULL. +.P +.BR utmpname () +returns 0 if the new name was successfully stored, or \-1 on failure. +.P +On failure, these functions +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Out of memory. +.TP +.B ESRCH +Record not found. +.P +.BR setutent (), +.BR pututline (), +and the +.BR getut* () +functions can also fail for the reasons described in +.BR open (2). +.SH FILES +.TP +.I /var/run/utmp +database of currently logged-in users +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getutent () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +race:utentbuf sig:ALRM timer +T} +T{ +.na +.nh +.BR getutid (), +.BR getutline () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR pututline () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR setutent (), +.BR endutent (), +.BR utmpname () +T} Thread safety MT-Unsafe race:utent +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (), +.BR getutent (), +.BR getutid (), +.BR getutline (), +.BR pututline (), +.BR utmpname (), +or +.BR endutent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +None. +.SH HISTORY +XPG2, SVr4. +.P +In XPG2 and SVID 2 the function +.BR pututline () +is documented to return void, and that is what it does on many systems +(AIX, HP-UX). +HP-UX introduces a new function +.BR _pututline () +with the prototype given above for +.BR pututline (). +.P +All these functions are obsolete now on non-Linux systems. +POSIX.1-2001 and POSIX.1-2008, following SUSv1, +does not have any of these functions, but instead uses +.P +.RS 4 +.EX +.B #include <utmpx.h> +.P +.B struct utmpx *getutxent(void); +.B struct utmpx *getutxid(const struct utmpx *); +.B struct utmpx *getutxline(const struct utmpx *); +.B struct utmpx *pututxline(const struct utmpx *); +.B void setutxent(void); +.B void endutxent(void); +.EE +.RE +.P +These functions are provided by glibc, +and perform the same task as their equivalents without the "x", but use +.IR "struct utmpx" , +defined on Linux to be the same as +.IR "struct utmp" . +For completeness, glibc also provides +.BR utmpxname (), +although this function is not specified by POSIX.1. +.P +On some other systems, +the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, +with additional fields, and larger versions of the existing fields, +and parallel files are maintained, often +.I /var/*/utmpx +and +.IR /var/*/wtmpx . +.P +Linux glibc on the other hand does not use a parallel \fIutmpx\fP file +since its \fIutmp\fP structure is already large enough. +The "x" functions listed above are just aliases for +their counterparts without the "x" (e.g., +.BR getutxent () +is an alias for +.BR getutent ()). +.SH NOTES +.SS glibc notes +The above functions are not thread-safe. +glibc adds reentrant versions +.P +.nf +.B #include <utmp.h> +.P +.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); +.BI "int getutid_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.BI "int getutline_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.fi +.P +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.P +.BR getutent_r (), +.BR getutid_r (), +.BR getutline_r (): +.nf + _GNU_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +These functions are GNU extensions, analogs of the functions of the +same name without the _r suffix. +The +.I ubuf +argument gives these functions a place to store their result. +On success, they return 0, and a pointer to the result is written in +.IR *ubufp . +On error, these functions return \-1. +There are no utmpx equivalents of the above functions. +(POSIX.1 does not specify such functions.) +.SH EXAMPLES +The following example adds and removes a utmp record, assuming it is run +from within a pseudo terminal. +For usage in a real application, you +should check the return values of +.BR getpwuid (3) +and +.BR ttyname (3). +.P +.\" SRC BEGIN (getutent.c) +.EX +#include <pwd.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> +#include <unistd.h> +#include <utmp.h> +\& +int +main(void) +{ + struct utmp entry; +\& + system("echo before adding entry:;who"); +\& + entry.ut_type = USER_PROCESS; + entry.ut_pid = getpid(); + strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); + /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ + strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); + entry.ut_time = time(NULL); + strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); + memset(entry.ut_host, 0, UT_HOSTSIZE); + entry.ut_addr = 0; + setutent(); + pututline(&entry); +\& + system("echo after adding entry:;who"); +\& + entry.ut_type = DEAD_PROCESS; + memset(entry.ut_line, 0, UT_LINESIZE); + entry.ut_time = 0; + memset(entry.ut_user, 0, UT_NAMESIZE); + setutent(); + pututline(&entry); +\& + system("echo after removing entry:;who"); +\& + endutent(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getutmp (3), +.BR utmp (5) diff --git a/man/man3/getutent_r.3 b/man/man3/getutent_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutent_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutid.3 b/man/man3/getutid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutid_r.3 b/man/man3/getutid_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutid_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutline.3 b/man/man3/getutline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutline_r.3 b/man/man3/getutline_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutline_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutmp.3 b/man/man3/getutmp.3 new file mode 100644 index 0000000..1d857fe --- /dev/null +++ b/man/man3/getutmp.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getutmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getutmp, getutmpx \- copy utmp structure to utmpx, and vice versa +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <utmpx.h> +.P +.BI "void getutmp(const struct utmpx *" ux ", struct utmp *" u ); +.BI "void getutmpx(const struct utmp *" u ", struct utmpx *" ux ); +.fi +.SH DESCRIPTION +The +.BR getutmp () +function copies the fields of the +.I utmpx +structure pointed to by +.I ux +to the corresponding fields of the +.I utmp +structure pointed to by +.IR u . +The +.BR getutmpx () +function performs the converse operation. +.SH RETURN VALUE +These functions do not return a value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getutmp (), +.BR getutmpx () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1.1. +Solaris, NetBSD. +.SH NOTES +These functions exist primarily for compatibility with other +systems where the +.I utmp +and +.I utmpx +structures contain different fields, +or the size of corresponding fields differs. +.\" e.g., on Solaris, the utmpx structure is rather larger than utmp. +On Linux, the two structures contain the same fields, +and the fields have the same sizes. +.SH SEE ALSO +.BR utmpdump (1), +.BR getutent (3), +.BR utmp (5) diff --git a/man/man3/getutmpx.3 b/man/man3/getutmpx.3 new file mode 100644 index 0000000..668ecb5 --- /dev/null +++ b/man/man3/getutmpx.3 @@ -0,0 +1 @@ +.so man3/getutmp.3 diff --git a/man/man3/getutxent.3 b/man/man3/getutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutxid.3 b/man/man3/getutxid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutxline.3 b/man/man3/getutxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getw.3 b/man/man3/getw.3 new file mode 100644 index 0000000..843d280 --- /dev/null +++ b/man/man3/getw.3 @@ -0,0 +1,84 @@ +'\" t +.\" Copyright (c) 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getw, putw \- input and output of words (ints) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int getw(FILE *" stream ); +.BI "int putw(int " w ", FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getw (), +.BR putw (): +.nf + Since glibc 2.3.3: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.3.3: + _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR getw () +reads a word (that is, an \fIint\fP) from \fIstream\fP. +It's provided for compatibility with SVr4. +We recommend you use +.BR fread (3) +instead. +.P +.BR putw () +writes the word \fIw\fP (that is, +an \fIint\fP) to \fIstream\fP. +It is provided for compatibility with SVr4, but we recommend you use +.BR fwrite (3) +instead. +.SH RETURN VALUE +Normally, +.BR getw () +returns the word read, and +.BR putw () +returns 0. +On error, they return \fBEOF\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getw (), +.BR putw () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, SUSv2. +.SH BUGS +The value returned on error is also a legitimate data value. +.BR ferror (3) +can be used to distinguish between the two cases. +.SH SEE ALSO +.BR ferror (3), +.BR fread (3), +.BR fwrite (3), +.BR getc (3), +.BR putc (3) diff --git a/man/man3/getwc.3 b/man/man3/getwc.3 new file mode 100644 index 0000000..358c2d2 --- /dev/null +++ b/man/man3/getwc.3 @@ -0,0 +1 @@ +.so man3/fgetwc.3 diff --git a/man/man3/getwc_unlocked.3 b/man/man3/getwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getwchar.3 b/man/man3/getwchar.3 new file mode 100644 index 0000000..47a53ca --- /dev/null +++ b/man/man3/getwchar.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH getwchar 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getwchar \- read a wide character from standard input +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.B "wint_t getwchar(void);" +.fi +.SH DESCRIPTION +The +.BR getwchar () +function is the wide-character equivalent of the +.BR getchar (3) +function. +It reads a wide character from +.I stdin +and returns +it. +If the end of stream is reached, or if +.I ferror(stdin) +becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR getwchar () +function returns the next wide-character from +standard input, or +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getwchar () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR getwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +It is reasonable to expect that +.BR getwchar () +will actually +read a multibyte sequence from standard input and then +convert it to a wide character. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/getwchar_unlocked.3 b/man/man3/getwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man/man3/getwd.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man/man3/glob.3 b/man/man3/glob.3 new file mode 100644 index 0000000..98ea94f --- /dev/null +++ b/man/man3/glob.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990912 by aeb +.\" 2007-10-10 mtk +.\" Added description of GLOB_TILDE_NOMATCH +.\" Expanded the description of various flags +.\" Various wording fixes. +.\" +.TH glob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +glob, globfree \- find pathnames matching a pattern, free memory from glob() +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <glob.h> +.P +.BI "int glob(const char *restrict " pattern ", int " flags , +.BI " int (*" errfunc ")(const char *" epath ", int " eerrno ), +.BI " glob_t *restrict " pglob ); +.BI "void globfree(glob_t *" pglob ); +.fi +.SH DESCRIPTION +The +.BR glob () +function searches for all the pathnames matching +.I pattern +according to the rules used by the shell (see +.BR glob (7)). +No tilde expansion or parameter substitution is done; if you want +these, use +.BR wordexp (3). +.P +The +.BR globfree () +function frees the dynamically allocated storage from an earlier call +to +.BR glob (). +.P +The results of a +.BR glob () +call are stored in the structure pointed to by +.IR pglob . +This structure is of type +.I glob_t +(declared in +.IR <glob.h> ) +and includes the following elements defined by POSIX.2 (more may be +present as an extension): +.P +.in +4n +.EX +typedef struct { + size_t gl_pathc; /* Count of paths matched so far */ + char **gl_pathv; /* List of matched pathnames. */ + size_t gl_offs; /* Slots to reserve in \fIgl_pathv\fP. */ +} glob_t; +.EE +.in +.P +Results are stored in dynamically allocated storage. +.P +The argument +.I flags +is made up of the bitwise OR of zero or more the following symbolic +constants, which modify the behavior of +.BR glob (): +.TP +.B GLOB_ERR +Return upon a read error (because a directory does not +have read permission, for example). +By default, +.BR glob () +attempts carry on despite errors, +reading all of the directories that it can. +.TP +.B GLOB_MARK +Append a slash to each path which corresponds to a directory. +.TP +.B GLOB_NOSORT +Don't sort the returned pathnames. +The only reason to do this is to save processing time. +By default, the returned pathnames are sorted. +.TP +.B GLOB_DOOFFS +Reserve +.I pglob\->gl_offs +slots at the beginning of the list of strings in +.IR pglob\->pathv . +The reserved slots contain null pointers. +.TP +.B GLOB_NOCHECK +If no pattern matches, return the original pattern. +By default, +.BR glob () +returns +.B GLOB_NOMATCH +if there are no matches. +.TP +.B GLOB_APPEND +Append the results of this call to the vector of results +returned by a previous call to +.BR glob (). +Do not set this flag on the first invocation of +.BR glob (). +.TP +.B GLOB_NOESCAPE +Don't allow backslash (\[aq]\e\[aq]) to be used as an escape +character. +Normally, a backslash can be used to quote the following character, +providing a mechanism to turn off the special meaning +metacharacters. +.P +.I flags +may also include any of the following, which are GNU +extensions and not defined by POSIX.2: +.TP +.B GLOB_PERIOD +Allow a leading period to be matched by metacharacters. +By default, metacharacters can't match a leading period. +.TP +.B GLOB_ALTDIRFUNC +Use alternative functions +.IR pglob\->gl_closedir , +.IR pglob\->gl_readdir , +.IR pglob\->gl_opendir , +.IR pglob\->gl_lstat , +and +.I pglob\->gl_stat +for filesystem access instead of the normal library +functions. +.TP +.B GLOB_BRACE +Expand +.BR csh (1) +style brace expressions of the form +.BR {a,b} . +Brace expressions can be nested. +Thus, for example, specifying the pattern +"{foo/{,cat,dog},bar}" would return the same results as four separate +.BR glob () +calls using the strings: +"foo/", +"foo/cat", +"foo/dog", +and +"bar". +.TP +.B GLOB_NOMAGIC +If the pattern contains no metacharacters, +then it should be returned as the sole matching word, +even if there is no file with that name. +.TP +.B GLOB_TILDE +Carry out tilde expansion. +If a tilde (\[aq]\[ti]\[aq]) is the only character in the pattern, +or an initial tilde is followed immediately by a slash (\[aq]/\[aq]), +then the home directory of the caller is substituted for +the tilde. +If an initial tilde is followed by a username (e.g., "\[ti]andrea/bin"), +then the tilde and username are substituted by the home directory +of that user. +If the username is invalid, or the home directory cannot be +determined, then no substitution is performed. +.TP +.B GLOB_TILDE_CHECK +This provides behavior similar to that of +.BR GLOB_TILDE . +The difference is that if the username is invalid, or the +home directory cannot be determined, then +instead of using the pattern itself as the name, +.BR glob () +returns +.B GLOB_NOMATCH +to indicate an error. +.TP +.B GLOB_ONLYDIR +This is a +.I hint +to +.BR glob () +that the caller is interested only in directories that match the pattern. +If the implementation can easily determine file-type information, +then nondirectory files are not returned to the caller. +However, the caller must still check that returned files +are directories. +(The purpose of this flag is merely to optimize performance when +the caller is interested only in directories.) +.P +If +.I errfunc +is not NULL, +it will be called in case of an error with the arguments +.IR epath , +a pointer to the path which failed, and +.IR eerrno , +the value of +.I errno +as returned from one of the calls to +.BR opendir (3), +.BR readdir (3), +or +.BR stat (2). +If +.I errfunc +returns nonzero, or if +.B GLOB_ERR +is set, +.BR glob () +will terminate after the call to +.IR errfunc . +.P +Upon successful return, +.I pglob\->gl_pathc +contains the number of matched pathnames and +.I pglob\->gl_pathv +contains a pointer to the list of pointers to matched pathnames. +The list of pointers is terminated by a null pointer. +.P +It is possible to call +.BR glob () +several times. +In that case, the +.B GLOB_APPEND +flag has to be set in +.I flags +on the second and later invocations. +.P +As a GNU extension, +.I pglob\->gl_flags +is set to the flags specified, +.BR or ed +with +.B GLOB_MAGCHAR +if any metacharacters were found. +.SH RETURN VALUE +On successful completion, +.BR glob () +returns zero. +Other possible returns are: +.TP +.B GLOB_NOSPACE +for running out of memory, +.TP +.B GLOB_ABORTED +for a read error, and +.TP +.B GLOB_NOMATCH +for no found matches. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR glob () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent env +sig:ALRM timer locale +T} +T{ +.na +.nh +.BR globfree () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR glob () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, POSIX.2. +.SH NOTES +The structure elements +.I gl_pathc +and +.I gl_offs +are declared as +.I size_t +in glibc 2.1, as they should be according to POSIX.2, +but are declared as +.I int +in glibc 2.0. +.SH BUGS +The +.BR glob () +function may fail due to failure of underlying function calls, such as +.BR malloc (3) +or +.BR opendir (3). +These will store their error code in +.IR errno . +.SH EXAMPLES +One example of use is the following code, which simulates typing +.P +.in +4n +.EX +ls \-l *.c ../*.c +.EE +.in +.P +in the shell: +.P +.in +4n +.EX +glob_t globbuf; +\& +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "\-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.EE +.in +.SH SEE ALSO +.BR ls (1), +.BR sh (1), +.BR stat (2), +.BR exec (3), +.BR fnmatch (3), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +.BR wordexp (3), +.BR glob (7) diff --git a/man/man3/globfree.3 b/man/man3/globfree.3 new file mode 100644 index 0000000..20056c6 --- /dev/null +++ b/man/man3/globfree.3 @@ -0,0 +1 @@ +.so man3/glob.3 diff --git a/man/man3/gmtime.3 b/man/man3/gmtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/gmtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/gmtime_r.3 b/man/man3/gmtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/gmtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/gnu_dev_major.3 b/man/man3/gnu_dev_major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_dev_makedev.3 b/man/man3/gnu_dev_makedev.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_makedev.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_dev_minor.3 b/man/man3/gnu_dev_minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_get_libc_release.3 b/man/man3/gnu_get_libc_release.3 new file mode 100644 index 0000000..7f84005 --- /dev/null +++ b/man/man3/gnu_get_libc_release.3 @@ -0,0 +1 @@ +.so man3/gnu_get_libc_version.3 diff --git a/man/man3/gnu_get_libc_version.3 b/man/man3/gnu_get_libc_version.3 new file mode 100644 index 0000000..20fc521 --- /dev/null +++ b/man/man3/gnu_get_libc_version.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH gnu_get_libc_version 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gnu_get_libc_version, gnu_get_libc_release \- get glibc version and release +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <gnu/libc\-version.h> +.P +.B const char *gnu_get_libc_version(void); +.B const char *gnu_get_libc_release(void); +.fi +.SH DESCRIPTION +The function +.BR gnu_get_libc_version () +returns a string that identifies the glibc version available on the system. +.P +The function +.BR gnu_get_libc_release () +returns a string indicates the release status of the glibc version +available on the system. +This will be a string such as +.IR "stable" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gnu_get_libc_version (), +.BR gnu_get_libc_release () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH EXAMPLES +When run, the program below will produce output such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out" +GNU libc version: 2.8 +GNU libc release: stable +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (gnu_get_libc_version.c) +.EX +#include <stdio.h> +#include <stdlib.h> +\& +#include <gnu/libc\-version.h> +\& +int +main(void) +{ + printf("GNU libc version: %s\en", gnu_get_libc_version()); + printf("GNU libc release: %s\en", gnu_get_libc_release()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR confstr (3) diff --git a/man/man3/grantpt.3 b/man/man3/grantpt.3 new file mode 100644 index 0000000..8ac498e --- /dev/null +++ b/man/man3/grantpt.3 @@ -0,0 +1,107 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH grantpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +grantpt \- grant access to the slave pseudoterminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int grantpt(int " fd ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR grantpt (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR grantpt () +function changes the mode and owner of the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by the file descriptor +.IR fd . +The user ID of the slave is set to the real UID of the calling process. +The group ID is set to an unspecified value (e.g., +.IR tty ). +The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-). +.P +The behavior of +.BR grantpt () +is unspecified if a signal handler is installed to catch +.B SIGCHLD +signals. +.SH RETURN VALUE +When successful, +.BR grantpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +The corresponding slave pseudoterminal could not be accessed. +.TP +.B EBADF +The +.I fd +argument is not a valid open file descriptor. +.TP +.B EINVAL +The +.I fd +argument is valid but not associated with a master pseudoterminal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR grantpt () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +This is part of the UNIX 98 pseudoterminal support, see +.BR pts (4). +.P +Historical systems implemented this function via a set-user-ID helper binary +called "pt_chown". +glibc on Linux before glibc 2.33 could do so as well, +in order to support configurations with only BSD pseudoterminals; +this support has been removed. +On modern systems this is either a no-op +\[em]with permissions configured on pty allocation, as is the case on Linux\[em] +or an +.BR ioctl (2). +.SH SEE ALSO +.BR open (2), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/group_member.3 b/man/man3/group_member.3 new file mode 100644 index 0000000..32f00cc --- /dev/null +++ b/man/man3/group_member.3 @@ -0,0 +1,48 @@ +.\" Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH group_member 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +group_member \- test whether a process is in a group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int group_member(gid_t " gid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR group_member (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR group_member () +function tests whether any of the caller's supplementary group IDs +(as returned by +.BR getgroups (2)) +matches +.IR gid . +.SH RETURN VALUE +The +.BR group_member () +function returns nonzero if any of the caller's +supplementary group IDs matches +.IR gid , +and zero otherwise. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getgid (2), +.BR getgroups (2), +.BR getgrouplist (3), +.BR group (5) diff --git a/man/man3/gsignal.3 b/man/man3/gsignal.3 new file mode 100644 index 0000000..748d320 --- /dev/null +++ b/man/man3/gsignal.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de>. +.TH gsignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gsignal, ssignal \- software signal facility +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "[[deprecated]] int gsignal(int " signum ); +.P +.BI "[[deprecated]] sighandler_t ssignal(int " signum ", sighandler_t " action ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gsignal (), +.BR ssignal (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +Don't use these functions under Linux. +Due to a historical mistake, under Linux these functions are +aliases for +.BR raise (3) +and +.BR signal (2), +respectively. +.P +Elsewhere, on System V-like systems, these functions implement +software signaling, entirely independent of the classical +.BR signal (2) +and +.BR kill (2) +functions. +The function +.BR ssignal () +defines the action to take when the software signal with +number +.I signum +is raised using the function +.BR gsignal (), +and returns the previous such action or +.BR SIG_DFL . +The function +.BR gsignal () +does the following: if no action (or the action +.BR SIG_DFL ) +was +specified for +.IR signum , +then it does nothing and returns 0. +If the action +.B SIG_IGN +was specified for +.IR signum , +then it does nothing and returns 1. +Otherwise, it resets the action to +.B SIG_DFL +and calls +the action function with argument +.IR signum , +and returns the value returned by that function. +The range of possible values +.I signum +varies (often 1\[en]15 or 1\[en]17). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gsignal () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR ssignal () +T} Thread safety MT-Safe sigintr +.TE +.SH STANDARDS +None. +.SH HISTORY +AIX, DG/UX, HP-UX, SCO, Solaris, Tru64. +They are called obsolete under most of these systems, and are +broken under +.\" Linux libc and +glibc. +Some systems also have +.BR gsignal_r () +and +.BR ssignal_r (). +.SH SEE ALSO +.BR kill (2), +.BR signal (2), +.BR raise (3) diff --git a/man/man3/h_errno.3 b/man/man3/h_errno.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/h_errno.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/hash.3 b/man/man3/hash.3 new file mode 100644 index 0000000..4ccbaca --- /dev/null +++ b/man/man3/hash.3 @@ -0,0 +1,145 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" +.TH hash 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +hash \- hash database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include <sys/types.h> +#include <db.h> +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is hash files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the hash-specific information. +.P +The hash data structure is an extensible, dynamic hashing scheme. +.P +The access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I <db.h> +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned int bsize; + unsigned int ffactor; + unsigned int nelem; + unsigned int cachesize; + uint32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.EE +.in +.P +The elements of this structure are as follows: +.TP 10 +.I bsize +defines the hash table bucket size, and is, by default, 256 bytes. +It may be preferable to increase the page size for disk-resident tables +and tables with large data items. +.TP +.I ffactor +indicates a desired density within the hash table. +It is an approximation of the number of keys allowed to accumulate in any +one bucket, determining when the hash table grows or shrinks. +The default value is 8. +.TP +.I nelem +is an estimate of the final size of the hash table. +If not set or set too low, hash tables will expand gracefully as keys +are entered, although a slight performance degradation may be noticed. +The default value is 1. +.TP +.I cachesize +is the suggested maximum size, in bytes, of the memory cache. +This value is +.IR "only advisory" , +and the access method will allocate more memory rather than fail. +.TP +.I hash +is a user-defined hash function. +Since no hash function performs equally well on all possible data, the +user may find that the built-in hash function does poorly on a particular +data set. +A user-specified hash functions must take two arguments (a pointer to a byte +string and a length) and return a 32-bit quantity to be used as the hash +value. +.TP +.I lorder +is the byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.P +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for +.IR bsize , +.IR ffactor , +.IR lorder , +and +.I nelem +are +ignored and the values specified when the tree was created are used. +.P +If a hash function is specified, +.I hash_open +attempts to determine if the hash function specified is the same as +the one with which the database was created, and fails if it is not. +.P +Backward-compatible interfaces to the routines described in +.BR dbm (3), +and +.BR ndbm (3) +are provided, however these interfaces are not compatible with +previous file formats. +.SH ERRORS +The +.I hash +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order are supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "Dynamic Hash Tables" , +Per-Ake Larson, Communications of the ACM, April 1988. +.P +.IR "A New Hash Package for UNIX" , +Margo Seltzer, USENIX Proceedings, Winter 1991. diff --git a/man/man3/hasmntopt.3 b/man/man3/hasmntopt.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/hasmntopt.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/hcreate.3 b/man/man3/hcreate.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hcreate.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hcreate_r.3 b/man/man3/hcreate_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hcreate_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hdestroy.3 b/man/man3/hdestroy.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hdestroy.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hdestroy_r.3 b/man/man3/hdestroy_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hdestroy_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/herror.3 b/man/man3/herror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/herror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/hsearch.3 b/man/man3/hsearch.3 new file mode 100644 index 0000000..7dc38ee --- /dev/null +++ b/man/man3/hsearch.3 @@ -0,0 +1,355 @@ +'\" t +.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" SunOS 4.1.1 man pages +.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 +.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb +.\" 2008-09-02, mtk: various additions and rewrites +.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from +.\" Timothy S. Nelson <wayland@wayland.id.au> +.\" +.TH hsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, +hsearch_r \- hash table management +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <search.h> +.P +.BI "int hcreate(size_t " nel ); +.B "void hdestroy(void);" +.P +.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <search.h> +.P +.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab ); +.BI "void hdestroy_r(struct hsearch_data *" htab ); +.P +.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval , +.BI " struct hsearch_data *" htab ); +.fi +.SH DESCRIPTION +The three functions +.BR hcreate (), +.BR hsearch (), +and +.BR hdestroy () +allow the caller to create and manage a hash search table +containing entries consisting of a key (a string) and associated data. +Using these functions, only one hash table can be used at a time. +.P +The three functions +.BR hcreate_r (), +.BR hsearch_r (), +.BR hdestroy_r () +are reentrant versions that allow a program to use +more than one hash search table at the same time. +The last argument, +.IR htab , +points to a structure that describes the table +on which the function is to operate. +The programmer should treat this structure as opaque +(i.e., do not attempt to directly access or modify +the fields in this structure). +.P +First a hash table must be created using +.BR hcreate (). +The argument \fInel\fP specifies the maximum number of entries +in the table. +(This maximum cannot be changed later, so choose it wisely.) +The implementation may adjust this value upward to improve the +performance of the resulting hash table. +.\" e.g., in glibc it is raised to the next higher prime number +.P +The +.BR hcreate_r () +function performs the same task as +.BR hcreate (), +but for the table described by the structure +.IR *htab . +The structure pointed to by +.I htab +must be zeroed before the first call to +.BR hcreate_r (). +.P +The function +.BR hdestroy () +frees the memory occupied by the hash table that was created by +.BR hcreate (). +After calling +.BR hdestroy (), +a new hash table can be created using +.BR hcreate (). +The +.BR hdestroy_r () +function performs the analogous task for a hash table described by +.IR *htab , +which was previously created using +.BR hcreate_r (). +.P +The +.BR hsearch () +function searches the hash table for an +item with the same key as \fIitem\fP (where "the same" is determined using +.BR strcmp (3)), +and if successful returns a pointer to it. +.P +The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in +\fI<search.h>\fP as follows: +.P +.in +4n +.EX +typedef struct entry { + char *key; + void *data; +} ENTRY; +.EE +.in +.P +The field \fIkey\fP points to a null-terminated string which is the +search key. +The field \fIdata\fP points to data that is associated with that key. +.P +The argument \fIaction\fP determines what +.BR hsearch () +does after an unsuccessful search. +This argument must either have the value +.BR ENTER , +meaning insert a copy of +.I item +(and return a pointer to the new hash table entry as the function result), +or the value +.BR FIND , +meaning that NULL should be returned. +(If +.I action +is +.BR FIND , +then +.I data +is ignored.) +.P +The +.BR hsearch_r () +function is like +.BR hsearch () +but operates on the hash table described by +.IR *htab . +The +.BR hsearch_r () +function differs from +.BR hsearch () +in that a pointer to the found item is returned in +.IR *retval , +rather than as the function result. +.SH RETURN VALUE +.BR hcreate () +and +.BR hcreate_r () +return nonzero on success. +They return 0 on error, with +.I errno +set to indicate the error. +.P +On success, +.BR hsearch () +returns a pointer to an entry in the hash table. +.BR hsearch () +returns NULL on error, that is, +if \fIaction\fP is \fBENTER\fP and +the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP +cannot be found in the hash table. +.BR hsearch_r () +returns nonzero on success, and 0 on error. +In the event of an error, these two functions set +.I errno +to indicate the error. +.SH ERRORS +.BR hcreate_r () +and +.BR hdestroy_r () +can fail for the following reasons: +.TP +.B EINVAL +.I htab +is NULL. +.P +.BR hsearch () +and +.BR hsearch_r () +can fail for the following reasons: +.TP +.B ENOMEM +.I action +was +.BR ENTER , +.I key +was not found in the table, +and there was no room in the table to add a new entry. +.TP +.B ESRCH +.I action +was +.BR FIND , +and +.I key +was not found in the table. +.P +POSIX.1 specifies only the +.\" PROX.1-2001, POSIX.1-2008 +.B ENOMEM +error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR hcreate (), +.BR hsearch (), +.BR hdestroy () +T} Thread safety MT-Unsafe race:hsearch +T{ +.na +.nh +.BR hcreate_r (), +.BR hsearch_r (), +.BR hdestroy_r () +T} Thread safety MT-Safe race:htab +.TE +.SH STANDARDS +.TP +.BR hcreate () +.TQ +.BR hsearch () +.TQ +.BR hdestroy () +POSIX.1-2008. +.TP +.BR hcreate_r () +.TQ +.BR hsearch_r () +.TQ +.BR hdestroy_r () +GNU. +.SH HISTORY +.TP +.BR hcreate () +.TQ +.BR hsearch () +.TQ +.BR hdestroy () +SVr4, POSIX.1-2001. +.TP +.BR hcreate_r () +.TQ +.BR hsearch_r () +.TQ +.BR hdestroy_r () +GNU. +.SH NOTES +Hash table implementations are usually more efficient when the +table contains enough free space to minimize collisions. +Typically, this means that +.I nel +should be at least 25% larger than the maximum number of elements +that the caller expects to store in the table. +.P +The +.BR hdestroy () +and +.BR hdestroy_r () +functions do not free the buffers pointed to by the +.I key +and +.I data +elements of the hash table entries. +(It can't do this because it doesn't know +whether these buffers were allocated dynamically.) +If these buffers need to be freed (perhaps because the program +is repeatedly creating and destroying hash tables, +rather than creating a single table whose lifetime +matches that of the program), +then the program must maintain bookkeeping data structures that +allow it to free them. +.SH BUGS +SVr4 and POSIX.1-2001 specify that \fIaction\fP +is significant only for unsuccessful searches, so that an \fBENTER\fP +should not do anything for a successful search. +In libc and glibc (before glibc 2.3), the +implementation violates the specification, +updating the \fIdata\fP for the given \fIkey\fP in this case. +.P +Individual hash table entries can be added, but not deleted. +.SH EXAMPLES +The following program inserts 24 items into a hash table, then prints +some of them. +.P +.\" SRC BEGIN (hsearch.c) +.EX +#include <search.h> +#include <stdio.h> +#include <stdlib.h> +\& +static char *data[] = { "alpha", "bravo", "charlie", "delta", + "echo", "foxtrot", "golf", "hotel", "india", "juliet", + "kilo", "lima", "mike", "november", "oscar", "papa", + "quebec", "romeo", "sierra", "tango", "uniform", + "victor", "whisky", "x\-ray", "yankee", "zulu" +}; +\& +int +main(void) +{ + ENTRY e; + ENTRY *ep; +\& + hcreate(30); +\& + for (size_t i = 0; i < 24; i++) { + e.key = data[i]; + /* data is just an integer, instead of a + pointer to something */ + e.data = (void *) i; + ep = hsearch(e, ENTER); + /* there should be no failures */ + if (ep == NULL) { + fprintf(stderr, "entry failed\en"); + exit(EXIT_FAILURE); + } + } +\& + for (size_t i = 22; i < 26; i++) { + /* print two entries from the table, and + show that two are not in the table */ + e.key = data[i]; + ep = hsearch(e, FIND); + printf("%9.9s \-> %9.9s:%d\en", e.key, + ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); + } + hdestroy(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bsearch (3), +.BR lsearch (3), +.BR malloc (3), +.BR tsearch (3) diff --git a/man/man3/hsearch_r.3 b/man/man3/hsearch_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hsearch_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hstrerror.3 b/man/man3/hstrerror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/hstrerror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/htobe16.3 b/man/man3/htobe16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htobe32.3 b/man/man3/htobe32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htobe64.3 b/man/man3/htobe64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole16.3 b/man/man3/htole16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole32.3 b/man/man3/htole32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole64.3 b/man/man3/htole64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htonl.3 b/man/man3/htonl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/htonl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/htons.3 b/man/man3/htons.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/htons.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/hypot.3 b/man/man3/hypot.3 new file mode 100644 index 0000000..19f028c --- /dev/null +++ b/man/man3/hypot.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH hypot 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hypot, hypotf, hypotl \- Euclidean distance function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double hypot(double " x ", double " y ); +.BI "float hypotf(float " x ", float " y ); +.BI "long double hypotl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR hypot (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR hypotf (), +.BR hypotl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return +.RI sqrt( x * x + y * y ). +This is the length of the hypotenuse of a right-angled triangle +with sides of length +.I x +and +.IR y , +or the distance of the point +.RI ( x , y ) +from the origin. +.P +The calculation is performed without undue overflow or underflow +during the intermediate steps of the calculation. +.\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say +.\" hypot(DBL_MAX/2.0, DBL_MAX/2.0). +.SH RETURN VALUE +On success, these functions return the length of the hypotenuse of +a right-angled triangle +with sides of length +.I x +and +.IR y . +.P +If +.I x +or +.I y +is an infinity, +positive infinity is returned. +.P +If +.I x +or +.I y +is a NaN, +and the other argument is not an infinity, +a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.P +If both arguments are subnormal, and the result is subnormal, +.\" Actually, could the result not be subnormal if both arguments +.\" are subnormal? I think not -- mtk, Jul 2008 +a range error occurs, +and the correct result is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.IP +These functions do not set +.I errno +for this case. +.\" This is intentional; see +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6795 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR hypot (), +.BR hypotf (), +.BR hypotl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cabs (3), +.BR sqrt (3) diff --git a/man/man3/hypotf.3 b/man/man3/hypotf.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man/man3/hypotf.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man/man3/hypotl.3 b/man/man3/hypotl.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man/man3/hypotl.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man/man3/iconv.3 b/man/man3/iconv.3 new file mode 100644 index 0000000..120fbbc --- /dev/null +++ b/man/man3/iconv.3 @@ -0,0 +1,233 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp> +.\" 2000-11-15 aeb, fixed prototype +.\" +.TH iconv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv \- perform character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <iconv.h> +.P +.BI "size_t iconv(iconv_t " cd , +.BI " char **restrict " inbuf ", size_t *restrict " inbytesleft , +.BI " char **restrict " outbuf ", size_t *restrict " outbytesleft ); +.fi +.SH DESCRIPTION +The +.BR iconv () +function converts a sequence of characters in one character encoding +to a sequence of characters in another character encoding. +The +.I cd +argument is a conversion descriptor, +previously created by a call to +.BR iconv_open (3); +the conversion descriptor defines the character encodings that +.BR iconv () +uses for the conversion. +The +.I inbuf +argument is the address of a variable that points to +the first character of the input sequence; +.I inbytesleft +indicates the number of bytes in that buffer. +The +.I outbuf +argument is the address of a variable that points to +the first byte available in the output buffer; +.I outbytesleft +indicates the number of bytes available in the output buffer. +.P +The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. +In this case, the +.BR iconv () +function converts the multibyte sequence +starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. +At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +.P +The +.BR iconv () +function converts one multibyte character at a time, and for +each character conversion it increments \fI*inbuf\fP and decrements +\fI*inbytesleft\fP by the number of converted input bytes, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted +output bytes, and it updates the conversion state contained in \fIcd\fP. +If the character encoding of the input is stateful, the +.BR iconv () +function can also convert a sequence of input bytes +to an update to the conversion state without producing any output bytes; +such input is called a \fIshift sequence\fP. +The conversion can stop for five reasons: +.IP \[bu] 3 +An invalid multibyte sequence is encountered in the input. +In this case, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP +is left pointing to the beginning of the invalid multibyte sequence. +.IP \[bu] +A multibyte sequence is encountered that is valid but that +cannot be translated to the character encoding of the output. +This condition depends on the implementation and on the conversion descriptor. +In the GNU C library and GNU libiconv, if +.I cd +was created without the suffix +.B //TRANSLIT +or +.BR //IGNORE , +the conversion is strict: +lossy conversions produce this condition. +If the suffix +.B //TRANSLIT +was specified, +transliteration can avoid this condition in some cases. +In the musl C library, +this condition cannot occur because a conversion to +.B \[aq]*\[aq] +is used as a fallback. +In the FreeBSD, NetBSD, and Solaris implementations of +.BR iconv (), +this condition cannot occur either, +because a conversion to +.B \[aq]?\[aq] +is used as a fallback. +When this condition is met, +.BR iconv () +sets +.I errno +to +.B EILSEQ +and returns +.IR (size_t)\ \-1 . +.I *inbuf +is left pointing to the beginning of the unconvertible multibyte sequence. +.IP \[bu] +The input byte sequence has been entirely converted, +that is, \fI*inbytesleft\fP has gone down to 0. +In this case, +.BR iconv () +returns the number of +nonreversible conversions performed during this call. +.IP \[bu] +An incomplete multibyte sequence is encountered in the input, and the +input byte sequence terminates after it. +In this case, it sets \fIerrno\fP to +\fBEINVAL\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP is left pointing to the +beginning of the incomplete multibyte sequence. +.IP \[bu] +The output buffer has no more room for the next converted character. +In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +.P +A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but +\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. +In this case, the +.BR iconv () +function attempts to set \fIcd\fP's conversion state to the +initial state and store a corresponding shift sequence at \fI*outbuf\fP. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +If the output buffer has no more room for this reset sequence, it sets +\fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +Otherwise, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes +written. +.P +A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and +\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. +In this case, the +.BR iconv () +function sets \fIcd\fP's conversion state to the initial state. +.SH RETURN VALUE +The +.BR iconv () +function returns the number of characters converted in a +nonreversible way during this call; reversible conversions are not counted. +In case of error, +.BR iconv () +returns +.I (size_t)\ \-1 +and sets +.I errno +to indicate the error. +.SH ERRORS +The following errors can occur, among others: +.TP +.B E2BIG +There is not sufficient room at \fI*outbuf\fP. +.TP +.B EILSEQ +An invalid multibyte sequence has been encountered in the input. +.TP +.B EINVAL +An incomplete multibyte sequence has been encountered in the input. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv () +T} Thread safety MT-Safe race:cd +.TE +.P +The +.BR iconv () +function is MT-Safe, as long as callers arrange for +mutual exclusion on the +.I cd +argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +In each series of calls to +.BR iconv (), +the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL, +in order to flush out any partially converted input. +.P +Although +.I inbuf +and +.I outbuf +are typed as +.IR "char\ **" , +this does not mean that the objects they point can be interpreted +as C strings or as arrays of characters: +the interpretation of character byte sequences is +handled internally by the conversion functions. +In some encodings, a zero byte may be a valid part of a multibyte character. +.P +The caller of +.BR iconv () +must ensure that the pointers passed to the function are suitable +for accessing characters in the appropriate character set. +This includes ensuring correct alignment on platforms that have +tight restrictions on alignment. +.SH SEE ALSO +.BR iconv_close (3), +.BR iconv_open (3), +.BR iconvconfig (8) diff --git a/man/man3/iconv_close.3 b/man/man3/iconv_close.3 new file mode 100644 index 0000000..f5014e3 --- /dev/null +++ b/man/man3/iconv_close.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH iconv_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv_close \- deallocate descriptor for character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <iconv.h> +.P +.BI "int iconv_close(iconv_t " cd ); +.fi +.SH DESCRIPTION +The +.BR iconv_close () +function deallocates a conversion descriptor +.I cd +previously allocated using +.BR iconv_open (3). +.SH RETURN VALUE +On success, +.BR iconv_close () +returns 0; otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR iconv (3), +.BR iconv_open (3) diff --git a/man/man3/iconv_open.3 b/man/man3/iconv_open.3 new file mode 100644 index 0000000..86333f9 --- /dev/null +++ b/man/man3/iconv_open.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT +.\" and //IGNORE extensions for 'tocode'. +.\" +.TH iconv_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv_open \- allocate descriptor for character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <iconv.h> +.P +.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); +.fi +.SH DESCRIPTION +The +.BR iconv_open () +function allocates a conversion descriptor suitable +for converting byte sequences from character encoding +.I fromcode +to +character encoding +.IR tocode . +.P +The values permitted for +.I fromcode +and +.I tocode +and the supported +combinations are system-dependent. +For the GNU C library, the permitted +values are listed by the +.I "iconv \-\-list" +command, and all combinations +of the listed values are supported. +Furthermore the GNU C library and the +GNU libiconv library support the following two suffixes: +.TP +//TRANSLIT +When the string "//TRANSLIT" is appended to +.IR tocode , +transliteration +is activated. +This means that when a character cannot be represented in the +target character set, it can be approximated through one or several +similarly looking characters. +.TP +//IGNORE +When the string "//IGNORE" is appended to +.IR tocode , +characters that +cannot be represented in the target character set will be silently discarded. +.P +The resulting conversion descriptor can be used with +.BR iconv (3) +any number of times. +It remains valid until deallocated using +.BR iconv_close (3). +.P +A conversion descriptor contains a conversion state. +After creation using +.BR iconv_open (), +the state is in the initial state. +Using +.BR iconv (3) +modifies the descriptor's conversion state. +To bring the state back to the initial state, use +.BR iconv (3) +with NULL as +.I inbuf +argument. +.SH RETURN VALUE +On success, +.BR iconv_open () +returns a freshly allocated conversion +descriptor. +On failure, it returns +.I (iconv_t)\ \-1 +and sets +.I errno +to indicate the error. +.SH ERRORS +The following error can occur, among others: +.TP +.B EINVAL +The conversion from +.I fromcode +to +.I tocode +is not supported by the +implementation. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv_open () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001, SUSv2. +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3), +.BR iconv_close (3) diff --git a/man/man3/if_freenameindex.3 b/man/man3/if_freenameindex.3 new file mode 100644 index 0000000..d8aac84 --- /dev/null +++ b/man/man3/if_freenameindex.3 @@ -0,0 +1 @@ +.so man3/if_nameindex.3 diff --git a/man/man3/if_indextoname.3 b/man/man3/if_indextoname.3 new file mode 100644 index 0000000..4379659 --- /dev/null +++ b/man/man3/if_indextoname.3 @@ -0,0 +1 @@ +.so man3/if_nametoindex.3 diff --git a/man/man3/if_nameindex.3 b/man/man3/if_nameindex.3 new file mode 100644 index 0000000..42b325b --- /dev/null +++ b/man/man3/if_nameindex.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 2012 YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> +.\" and Copyright (c) 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH if_nameindex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +if_nameindex, if_freenameindex \- get network interface names and indexes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <net/if.h> +.P +.BI "struct if_nameindex *if_nameindex(" void ); +.BI "void if_freenameindex(struct if_nameindex *" "ptr" ); +.fi +.SH DESCRIPTION +The +.BR if_nameindex () +function returns an array of +.I if_nameindex +structures, each containing information +about one of the network interfaces on the local system. +The +.I if_nameindex +structure contains at least the following entries: +.P +.in +4n +.EX +unsigned int if_index; /* Index of interface (1, 2, ...) */ +char *if_name; /* Null\-terminated name ("eth0", etc.) */ +.EE +.in +.P +The +.I if_index +field contains the interface index. +The +.I if_name +field points to the null-terminated interface name. +The end of the array is indicated by entry with +.I if_index +set to zero and +.I if_name +set to NULL. +.P +The data structure returned by +.BR if_nameindex () +is dynamically allocated and should be freed using +.BR if_freenameindex () +when no longer needed. +.SH RETURN VALUE +On success, +.BR if_nameindex () +returns pointer to the array; +on error, NULL is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR if_nameindex () +may fail and set +.I errno +if: +.TP +.B ENOBUFS +Insufficient resources available. +.P +.BR if_nameindex () +may also fail for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR ioctl (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +or +.BR malloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR if_nameindex (), +.BR if_freenameindex () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008, RFC\ 3493. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +BSDi. +.P +Before glibc 2.3.4, +the implementation supported only interfaces with IPv4 addresses. +Support of interfaces that don't have IPv4 addresses is available only +on kernels that support netlink. +.SH EXAMPLES +The program below demonstrates the use of the functions described +on this page. +An example of the output this program might produce is the following: +.P +.in +4n +.EX +$ \fB./a.out\fI +1: lo +2: wlan0 +3: em1 +.EE +.in +.SS Program source +.\" SRC BEGIN (if_nameindex.c) +.EX +#include <net/if.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(void) +{ + struct if_nameindex *if_ni, *i; +\& + if_ni = if_nameindex(); + if (if_ni == NULL) { + perror("if_nameindex"); + exit(EXIT_FAILURE); + } +\& + for (i = if_ni; !(i\->if_index == 0 && i\->if_name == NULL); i++) + printf("%u: %s\en", i\->if_index, i\->if_name); +\& + if_freenameindex(if_ni); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getsockopt (2), +.BR setsockopt (2), +.BR getifaddrs (3), +.BR if_indextoname (3), +.BR if_nametoindex (3), +.BR ifconfig (8) diff --git a/man/man3/if_nametoindex.3 b/man/man3/if_nametoindex.3 new file mode 100644 index 0000000..1a1272a --- /dev/null +++ b/man/man3/if_nametoindex.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (c) 2012 YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH if_nametoindex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +if_nametoindex, if_indextoname \- mappings between network interface +names and indexes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <net/if.h> +.P +.BI "unsigned int if_nametoindex(const char *" "ifname" ); +.BI "char *if_indextoname(unsigned int ifindex, char *" ifname ); +.fi +.SH DESCRIPTION +The +.BR if_nametoindex () +function returns the index of the network interface +corresponding to the name +.IR ifname . +.P +The +.BR if_indextoname () +function returns the name of the network interface +corresponding to the interface index +.IR ifindex . +The name is placed in the buffer pointed to by +.IR ifname . +The buffer must allow for the storage of at least +.B IF_NAMESIZE +bytes. +.SH RETURN VALUE +On success, +.BR if_nametoindex () +returns the index number of the network interface; +on error, 0 is returned and +.I errno +is set to indicate the error. +.P +On success, +.BR if_indextoname () +returns +.IR ifname ; +on error, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR if_nametoindex () +may fail and set +.I errno +if: +.TP +.B ENODEV +No interface found with given name. +.P +.BR if_indextoname () +may fail and set +.I errno +if: +.TP +.B ENXIO +No interface found for the index. +.P +.BR if_nametoindex () +and +.BR if_indextoname () +may also fail for any of the errors specified for +.BR socket (2) +or +.BR ioctl (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR if_nametoindex (), +.BR if_indextoname () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008, RFC\ 3493. +.SH HISTORY +POSIX.1-2001. +BSDi. +.SH SEE ALSO +.BR getifaddrs (3), +.BR if_nameindex (3), +.BR ifconfig (8) diff --git a/man/man3/ilogb.3 b/man/man3/ilogb.3 new file mode 100644 index 0000000..07ce896 --- /dev/null +++ b/man/man3/ilogb.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH ilogb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ilogb, ilogbf, ilogbl \- get integer exponent of a floating-point value +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "int ilogb(double " x ); +.BI "int ilogbf(float " x ); +.BI "int ilogbl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ilogb (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR ilogbf (), +.BR ilogbl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the exponent part of their argument +as a signed integer. +When no error occurs, these functions +are equivalent to the corresponding +.BR logb (3) +functions, cast to +.IR int . +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x , +as a signed integer. +.P +If +.I x +is zero, then a domain error occurs, and the functions return +.\" the POSIX.1 spec for logb() says logb() gives pole error for this +.\" case, but for ilogb() it says domain error. +.BR FP_ILOGB0 . +.\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'. +.P +If +.I x +is a NaN, then a domain error occurs, and the functions return +.BR FP_ILOGBNAN . +.\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'. +.\" On i386, FP_ILOGB0 and FP_ILOGBNAN have the same value. +.P +If +.I x +is negative infinity or positive infinity, then +a domain error occurs, and the functions return +.BR INT_MAX . +.\" +.\" POSIX.1-2001 also says: +.\" If the correct value is greater than {INT_MAX}, {INT_MAX} +.\" shall be returned and a domain error shall occur. +.\" +.\" If the correct value is less than {INT_MIN}, {INT_MIN} +.\" shall be returned and a domain error shall occur. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is 0 or a NaN +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.B EDOM +(but see BUGS). +.TP +Domain error: \fIx\fP is an infinity +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.B EDOM +(but see BUGS). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ilogb (), +.BR ilogbf (), +.BR ilogbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH BUGS +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6794 +Before glibc 2.16, the following bugs existed in the +glibc implementation of these functions: +.IP \[bu] 3 +The domain error case where +.I x +is 0 or a NaN did not cause +.I errno +to be set or (on some architectures) raise a floating-point exception. +.IP \[bu] +The domain error case where +.I x +is an infinity did not cause +.I errno +to be set or raise a floating-point exception. +.SH SEE ALSO +.BR log (3), +.BR logb (3), +.BR significand (3) diff --git a/man/man3/ilogbf.3 b/man/man3/ilogbf.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man/man3/ilogbf.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man/man3/ilogbl.3 b/man/man3/ilogbl.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man/man3/ilogbl.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man/man3/imaxabs.3 b/man/man3/imaxabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/imaxabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/imaxdiv.3 b/man/man3/imaxdiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/imaxdiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/index.3 b/man/man3/index.3 new file mode 100644 index 0000000..77f2b5a --- /dev/null +++ b/man/man3/index.3 @@ -0,0 +1,44 @@ +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH index 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +index, rindex \- locate character in string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "[[deprecated]] char *index(const char *" s ", int " c ); +.BI "[[deprecated]] char *rindex(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +.BR index () +is identical to +.BR strchr (3). +.P +.BR rindex () +is identical to +.BR strrchr (3). +.P +Use +.BR strchr (3) +and +.BR strrchr (3) +instead of these functions. +.SH STANDARDS +None. +.SH HISTORY +4.3BSD; marked as LEGACY in POSIX.1-2001. +Removed in POSIX.1-2008, +recommending +.BR strchr (3) +and +.BR strrchr (3) +instead. +.SH SEE ALSO +.BR strchr (3), +.BR strrchr (3) diff --git a/man/man3/inet.3 b/man/man3/inet.3 new file mode 100644 index 0000000..04cfdb7 --- /dev/null +++ b/man/man3/inet.3 @@ -0,0 +1,336 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" libc.info (from glibc distribution) +.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Changed network into host byte order (for inet_network), +.\" Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130. +.\" 2008-06-19, mtk +.\" Describe the various address forms supported by inet_aton(). +.\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). +.\" Add discussion of Classful Addressing, noting that it is obsolete. +.\" Added an EXAMPLE program. +.\" +.TH inet 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_netof \- Internet address manipulation routines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <netinet/in.h> +.B #include <arpa/inet.h> +.P +.BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); +.P +.BI "in_addr_t inet_addr(const char *" cp ); +.BI "in_addr_t inet_network(const char *" cp ); +.P +.BI "[[deprecated]] char *inet_ntoa(struct in_addr " in ); +.P +.BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net , +.BI " in_addr_t " host ); +.P +.BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in ); +.BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR inet_aton (), +.BR inet_ntoa (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR inet_aton () +converts the Internet host address \fIcp\fP from the +IPv4 numbers-and-dots notation into binary form (in network byte order) +and stores it in the structure that \fIinp\fP points to. +.BR inet_aton () +returns nonzero if the address is valid, zero if not. +The address supplied in +.I cp +can have one of the following forms: +.TP 10 +.I a.b.c.d +Each of the four numeric parts specifies a byte of the address; +the bytes are assigned in left-to-right order to produce the binary address. +.TP +.I a.b.c +Parts +.I a +and +.I b +specify the first two bytes of the binary address. +Part +.I c +is interpreted as a 16-bit value that defines the rightmost two bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class B +network addresses. +.TP +.I a.b +Part +.I a +specifies the first byte of the binary address. +Part +.I b +is interpreted as a 24-bit value that defines the rightmost three bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class A +network addresses. +.TP +.I a +The value +.I a +is interpreted as a 32-bit value that is stored directly +into the binary address without any byte rearrangement. +.P +In all of the above forms, +components of the dotted address can be specified in decimal, +octal (with a leading +.IR 0 ), +or hexadecimal, with a leading +.IR 0X ). +Addresses in any of these forms are collectively termed +.IR "IPV4 numbers-and-dots notation" . +The form that uses exactly four decimal numbers is referred to as +.I IPv4 dotted-decimal notation +(or sometimes: +.IR "IPv4 dotted-quad notation" ). +.P +.BR inet_aton () +returns 1 if the supplied string was successfully interpreted, +or 0 if the string is invalid +.RB ( errno +is +.I not +set on error). +.P +The +.BR inet_addr () +function converts the Internet host address +\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network +byte order. +If the input is invalid, +.B INADDR_NONE +(usually \-1) is returned. +Use of this function is problematic because \-1 is a valid address +(255.255.255.255). +Avoid its use in favor of +.BR inet_aton (), +.BR inet_pton (3), +or +.BR getaddrinfo (3), +which provide a cleaner way to indicate error return. +.P +The +.BR inet_network () +function converts +.IR cp , +a string in IPv4 numbers-and-dots notation, +into a number in host byte order suitable for use as an +Internet network address. +On success, the converted address is returned. +If the input is invalid, \-1 is returned. +.P +The +.BR inet_ntoa () +function converts the Internet host address +\fIin\fP, given in network byte order, to a string in IPv4 +dotted-decimal notation. +The string is returned in a statically +allocated buffer, which subsequent calls will overwrite. +.P +The +.BR inet_lnaof () +function returns the local network address part +of the Internet address \fIin\fP. +The returned value is in host byte order. +.P +The +.BR inet_netof () +function returns the network number part of +the Internet address \fIin\fP. +The returned value is in host byte order. +.P +The +.BR inet_makeaddr () +function is the converse of +.BR inet_netof () +and +.BR inet_lnaof (). +It returns an Internet host address in network byte order, +created by combining the network number \fInet\fP +with the local address \fIhost\fP, both in +host byte order. +.P +The structure \fIin_addr\fP as used in +.BR inet_ntoa (), +.BR inet_makeaddr (), +.BR inet_lnaof (), +and +.BR inet_netof () +is defined in +.I <netinet/in.h> +as: +.P +.in +4n +.EX +typedef uint32_t in_addr_t; +\& +struct in_addr { + in_addr_t s_addr; +}; +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_aton (), +.BR inet_addr (), +.BR inet_network (), +.BR inet_ntoa () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR inet_makeaddr (), +.BR inet_lnaof (), +.BR inet_netof () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2008. +.TP +.BR inet_aton () +None. +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2001, 4.3BSD. +.P +.BR inet_lnaof (), +.BR inet_netof (), +and +.BR inet_makeaddr () +are legacy functions that assume they are dealing with +.IR "classful network addresses" . +Classful networking divides IPv4 network addresses into host and network +components at byte boundaries, as follows: +.TP 10 +Class A +This address type is indicated by the value 0 in the +most significant bit of the (network byte ordered) address. +The network address is contained in the most significant byte, +and the host address occupies the remaining three bytes. +.TP +Class B +This address type is indicated by the binary value 10 in the +most significant two bits of the address. +The network address is contained in the two most significant bytes, +and the host address occupies the remaining two bytes. +.TP +Class C +This address type is indicated by the binary value 110 in the +most significant three bits of the address. +The network address is contained in the three most significant bytes, +and the host address occupies the remaining byte. +.P +Classful network addresses are now obsolete, +having been superseded by Classless Inter-Domain Routing (CIDR), +which divides addresses into network and host components at +arbitrary bit (rather than byte) boundaries. +.SH NOTES +On x86 architectures, the host byte order is Least Significant Byte +first (little endian), whereas the network byte order, as used on the +Internet, is Most Significant Byte first (big endian). +.SH EXAMPLES +An example of the use of +.BR inet_aton () +and +.BR inet_ntoa () +is shown below. +Here are some example runs: +.P +.in +4n +.EX +.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" +226.0.0.31 +.RB "$" " ./a.out 0x7f.1 " " # First byte is in hex" +127.0.0.1 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (inet.c) +.EX +#define _DEFAULT_SOURCE +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + struct in_addr addr; +\& + if (argc != 2) { + fprintf(stderr, "%s <dotted\-address>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (inet_aton(argv[1], &addr) == 0) { + fprintf(stderr, "Invalid address\en"); + exit(EXIT_FAILURE); + } +\& + printf("%s\en", inet_ntoa(addr)); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR byteorder (3), +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR getnetent (3), +.BR inet_net_pton (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR hosts (5), +.BR networks (5) diff --git a/man/man3/inet_addr.3 b/man/man3/inet_addr.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_addr.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_aton.3 b/man/man3/inet_aton.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_aton.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_lnaof.3 b/man/man3/inet_lnaof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_lnaof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_makeaddr.3 b/man/man3/inet_makeaddr.3 new file mode 100644 index 0000000..4a9e0fd --- /dev/null +++ b/man/man3/inet_makeaddr.3 @@ -0,0 +1 @@ +.so man3/inet_addr.3 diff --git a/man/man3/inet_net_ntop.3 b/man/man3/inet_net_ntop.3 new file mode 100644 index 0000000..10b8d44 --- /dev/null +++ b/man/man3/inet_net_ntop.3 @@ -0,0 +1 @@ +.so man3/inet_net_pton.3 diff --git a/man/man3/inet_net_pton.3 b/man/man3/inet_net_pton.3 new file mode 100644 index 0000000..09bff61 --- /dev/null +++ b/man/man3/inet_net_pton.3 @@ -0,0 +1,369 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH inet_net_pton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_net_pton, inet_net_ntop \- Internet network number conversion +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include <arpa/inet.h> +.P +.BI "int inet_net_pton(int " af ", const char *" pres , +.BI " void " netp [. nsize "], size_t " nsize ); +.BI "char *inet_net_ntop(int " af , +.BI " const void " netp [(. bits " - CHAR_BIT + 1) / CHAR_BIT]," +.BI " int " bits , +.BI " char " pres [. psize "], size_t " psize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR inet_net_pton (), +.BR inet_net_ntop (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE + Before glibc 2.20: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions convert network numbers between +presentation (i.e., printable) format and network (i.e., binary) format. +.P +For both functions, +.I af +specifies the address family for the conversion; +the only supported value is +.BR AF_INET . +.SS inet_net_pton() +The +.BR inet_net_pton () +function converts +.IR pres , +a null-terminated string containing an Internet network number in +presentation format to network format. +The result of the conversion, which is in network byte order, +is placed in the buffer pointed to by +.IR netp . +(The +.I netp +argument typically points to an +.I in_addr +structure.) +The +.I nsize +argument specifies the number of bytes available in +.IR netp . +.P +On success, +.BR inet_net_pton () +returns the number of bits in the network number field +of the result placed in +.IR netp . +For a discussion of the input presentation format and the return value, +see NOTES. +.P +.IR Note : +the buffer pointed to by +.I netp +should be zeroed out before calling +.BR inet_net_pton (), +since the call writes only as many bytes as are required +for the network number (or as are explicitly specified by +.IR pres ), +which may be less than the number of bytes in a complete network address. +.SS inet_net_ntop() +The +.BR inet_net_ntop () +function converts the network number in the buffer pointed to by +.I netp +to presentation format; +.I *netp +is interpreted as a value in network byte order. +The +.I bits +argument specifies the number of bits in the network number in +.IR *netp . +.P +The null-terminated presentation-format string +is placed in the buffer pointed to by +.IR pres . +The +.I psize +argument specifies the number of bytes available in +.IR pres . +The presentation string is in CIDR format: +a dotted-decimal number representing the network address, +followed by a slash, and the size of the network number in bits. +.SH RETURN VALUE +On success, +.BR inet_net_pton () +returns the number of bits in the network number. +On error, it returns \-1, and +.I errno +is set to indicate the error. +.P +On success, +.BR inet_net_ntop () +returns +.IR pres . +On error, it returns NULL, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +specified a value other than +.BR AF_INET . +.TP +.B EMSGSIZE +The size of the output buffer was insufficient. +.TP +.B ENOENT +.RB ( inet_net_pton ()) +.I pres +was not in correct presentation format. +.SH STANDARDS +None. +.SH NOTES +.SS Input presentation format for inet_net_pton() +The network number may be specified either +as a hexadecimal value +or in dotted-decimal notation. +.P +Hexadecimal values are indicated by an initial "0x" or "0X". +The hexadecimal digits populate the nibbles (half octets) of the +network number from left to right in network byte order. +.\" If the hexadecimal string is short, the remaining nibbles are zeroed. +.P +In dotted-decimal notation, up to four octets are specified, +as decimal numbers separated by dots. +Thus, any of the following forms are accepted: +.P +.in +4n +.EX +a.b.c.d +a.b.c +a.b +a +.EE +.in +.P +Each part is a number in the range 0 to 255 that +populates one byte of the resulting network number, +going from left to right, in network-byte (big endian) order. +Where a part is omitted, the resulting byte in the network number is zero. +.\" Reading other man pages, some other implementations treat +.\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes +.\" 'b' in a.b as a 24-bit number that populates right-most three bytes +.P +For either hexadecimal or dotted-decimal format, +the network number can optionally be followed by a slash +and a number in the range 0 to 32, +which specifies the size of the network number in bits. +.SS Return value of inet_net_pton() +The return value of +.BR inet_net_pton () +is the number of bits in the network number field. +If the input presentation string terminates with a slash and +an explicit size value, then that size becomes the return value of +.BR inet_net_pton (). +Otherwise, the return value, +.IR bits , +is inferred as follows: +.IP \[bu] 3 +If the most significant byte of the network number is +greater than or equal to 240, +then +.I bits +is 32. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 224, +then +.I bits +is 4. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 192, +then +.I bits +is 24. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 128, +then +.I bits +is 16. +.IP \[bu] +Otherwise, +.I bits +is 8. +.P +If the resulting +.I bits +value from the above steps is greater than or equal to 8, +but the number of octets specified in the network number exceed +.IR "bits/8" , +then +.I bits +is set to 8 times the number of octets actually specified. +.SH EXAMPLES +The program below demonstrates the use of +.BR inet_net_pton () +and +.BR inet_net_ntop (). +It uses +.BR inet_net_pton () +to convert the presentation format network address provided in +its first command-line argument to binary form, displays the return value from +.BR inet_net_pton (). +It then uses +.BR inet_net_ntop () +to convert the binary form back to presentation format, +and displays the resulting string. +.P +In order to demonstrate that +.BR inet_net_pton () +may not write to all bytes of its +.I netp +argument, the program allows an optional second command-line argument, +a number used to initialize the buffer before +.BR inet_net_pton () +is called. +As its final line of output, +the program displays all of the bytes of the buffer returned by +.BR inet_net_pton () +allowing the user to see which bytes have not been touched by +.BR inet_net_pton (). +.P +An example run, showing that +.BR inet_net_pton () +infers the number of bits in the network number: +.P +.in +4n +.EX +$ \fB./a.out 193.168\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a80000 +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +does not zero out unused bytes in its result buffer: +.P +.in +4n +.EX +$ \fB./a.out 193.168 0xffffffff\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a800ff +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +will widen the inferred size of the network number, +if the supplied number of bytes in the presentation +string exceeds the inferred value: +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128\fP +inet_net_pton() returned: 32 +inet_net_ntop() yielded: 193.168.1.128/32 +Raw address: c1a80180 +.EE +.in +.P +Explicitly specifying the size of the network number overrides any +inference about its size +(but any extra bytes that are explicitly specified will still be used by +.BR inet_net_pton (): +to populate the result buffer): +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128/24\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.1/24 +Raw address: c1a80180 +.EE +.in +.SS Program source +.\" SRC BEGIN (inet_net_pton.c) +.EX +/* Link with "\-lresolv" */ +\& +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + char buf[100]; + struct in_addr addr; + int bits; +\& + if (argc < 2) { + fprintf(stderr, + "Usage: %s presentation\-form [addr\-init\-value]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + /* If argv[2] is supplied (a numeric value), use it to initialize + the output buffer given to inet_net_pton(), so that we can see + that inet_net_pton() initializes only those bytes needed for + the network number. If argv[2] is not supplied, then initialize + the buffer to zero (as is recommended practice). */ +\& + addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0; +\& + /* Convert presentation network number in argv[1] to binary. */ +\& + bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr)); + if (bits == \-1) + errExit("inet_net_ntop"); +\& + printf("inet_net_pton() returned: %d\en", bits); +\& + /* Convert binary format back to presentation, using \[aq]bits\[aq] + returned by inet_net_pton(). */ +\& + if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL) + errExit("inet_net_ntop"); +\& + printf("inet_net_ntop() yielded: %s\en", buf); +\& + /* Display \[aq]addr\[aq] in raw form (in network byte order), so we can + see bytes not displayed by inet_net_ntop(); some of those bytes + may not have been touched by inet_net_ntop(), and so will still + have any initial value that was specified in argv[2]. */ +\& + printf("Raw address: %x\en", htonl(addr.s_addr)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR inet (3), +.BR networks (5) diff --git a/man/man3/inet_netof.3 b/man/man3/inet_netof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_netof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_network.3 b/man/man3/inet_network.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_network.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_ntoa.3 b/man/man3/inet_ntoa.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_ntoa.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_ntop.3 b/man/man3/inet_ntop.3 new file mode 100644 index 0000000..6f2ce5d --- /dev/null +++ b/man/man3/inet_ntop.3 @@ -0,0 +1,122 @@ +'\" t +.\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH inet_ntop 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_ntop \- convert IPv4 and IPv6 addresses from binary to text form +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <arpa/inet.h> +.P +.BI "const char *inet_ntop(int " af ", const void *restrict " src , +.BI " char " dst "[restrict ." size "], socklen_t " size ); +.fi +.SH DESCRIPTION +This function converts the network address structure +.I src +in the +.I af +address family into a character string. +The resulting string is copied to the buffer pointed to by +.IR dst , +which must be a non-null pointer. +The caller specifies the number of bytes available in this buffer in +the argument +.IR size . +.P +.BR inet_ntop () +extends the +.BR inet_ntoa (3) +function to support multiple address families, +.BR inet_ntoa (3) +is now considered to be deprecated in favor of +.BR inet_ntop (). +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a +.I struct in_addr +(in network byte order) +which is converted to an IPv4 network address in +the dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP". +The buffer +.I dst +must be at least +.B INET_ADDRSTRLEN +bytes long. +.TP +.B AF_INET6 +.I src +points to a +.I struct in6_addr +(in network byte order) +which is converted to a representation of this address in the +most appropriate IPv6 network address format for this address. +The buffer +.I dst +must be at least +.B INET6_ADDRSTRLEN +bytes long. +.SH RETURN VALUE +On success, +.BR inet_ntop () +returns a non-null pointer to +.IR dst . +NULL is returned if there was an error, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +was not a valid address family. +.TP +.B ENOSPC +The converted address string would exceed the size given by +.IR size . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_ntop () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Note that RFC\ 2553 defines a prototype where the last argument +.I size +is of type +.IR size_t . +Many systems follow RFC\ 2553. +glibc 2.0 and 2.1 have +.IR size_t , +but 2.2 and later have +.IR socklen_t . +.\" 2.1.3: size_t, 2.1.91: socklen_t +.SH BUGS +.B AF_INET6 +converts IPv4-mapped IPv6 addresses into an IPv6 format. +.SH EXAMPLES +See +.BR inet_pton (3). +.SH SEE ALSO +.BR getnameinfo (3), +.BR inet (3), +.BR inet_pton (3) diff --git a/man/man3/inet_pton.3 b/man/man3/inet_pton.3 new file mode 100644 index 0000000..89b10c3 --- /dev/null +++ b/man/man3/inet_pton.3 @@ -0,0 +1,223 @@ +'\" t +.\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> +.\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH inet_pton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_pton \- convert IPv4 and IPv6 addresses from text to binary form +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <arpa/inet.h> +.P +.BI "int inet_pton(int " af ", const char *restrict " src \ +", void *restrict " dst ); +.fi +.SH DESCRIPTION +This function converts the character string +.I src +into a network address structure in the +.I af +address family, then +copies +the network address structure to +.IR dst . +The +.I af +argument must be either +.B AF_INET +or +.BR AF_INET6 . +.I dst +is written in network byte order. +.P +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a character string containing an IPv4 network address in +dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where +.I ddd +is a decimal number of up to three digits in the range 0 to 255. +The address is converted to a +.I struct in_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in_addr) +(4) bytes (32 bits) long. +.TP +.B AF_INET6 +.I src +points to a character string containing an IPv6 network address. +The address is converted to a +.I struct in6_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in6_addr) +(16) bytes (128 bits) long. +The allowed formats for IPv6 addresses follow these rules: +.RS +.IP \[bu] 3 +The preferred format is +.IR x:x:x:x:x:x:x:x . +This form consists of eight hexadecimal numbers, +each of which expresses a 16-bit value (i.e., each +.I x +can be up to 4 hex digits). +.IP \[bu] +A series of contiguous zero values in the preferred format +can be abbreviated to +.IR :: . +Only one instance of +.I :: +can occur in an address. +For example, the loopback address +.I 0:0:0:0:0:0:0:1 +can be abbreviated as +.IR ::1 . +The wildcard address, consisting of all zeros, can be written as +.IR :: . +.IP \[bu] +An alternate format is useful for expressing IPv4-mapped IPv6 addresses. +This form is written as +.IR x:x:x:x:x:x:d.d.d.d , +where the six leading +.IR x s +are hexadecimal values that define the six most-significant +16-bit pieces of the address (i.e., 96 bits), and the +.IR d s +express a value in dotted-decimal notation that +defines the least significant 32 bits of the address. +An example of such an address is +.IR ::FFFF:204.152.189.116 . +.RE +.IP +See RFC 2373 for further details on the representation of IPv6 addresses. +.SH RETURN VALUE +.BR inet_pton () +returns 1 on success (network address was successfully converted). +0 is returned if +.I src +does not contain a character string representing a valid network +address in the specified address family. +If +.I af +does not contain a valid address family, \-1 is returned and +.I errno +is set to +.BR EAFNOSUPPORT . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_pton () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Unlike +.BR inet_aton (3) +and +.BR inet_addr (3), +.BR inet_pton () +supports IPv6 addresses. +On the other hand, +.BR inet_pton () +accepts only IPv4 addresses in dotted-decimal notation, whereas +.BR inet_aton (3) +and +.BR inet_addr (3) +allow the more general numbers-and-dots notation (hexadecimal +and octal number formats, and formats that don't require all +four bytes to be explicitly written). +For an interface that handles both IPv6 addresses, and IPv4 +addresses in numbers-and-dots notation, see +.BR getaddrinfo (3). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +.B AF_INET6 +does not recognize IPv4 addresses. +An explicit IPv4-mapped IPv6 address must be supplied in +.I src +instead. +.SH EXAMPLES +The program below demonstrates the use of +.BR inet_pton () +and +.BR inet_ntop (3). +Here are some example runs: +.P +.in +4n +.EX +.RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" +:: +.RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" +1::8 +.RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" +::ffff:204.152.189.116 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (inet_pton.c) +.EX +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + unsigned char buf[sizeof(struct in6_addr)]; + int domain, s; + char str[INET6_ADDRSTRLEN]; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s {i4|i6|<num>} string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : + (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); +\& + s = inet_pton(domain, argv[2], buf); + if (s <= 0) { + if (s == 0) + fprintf(stderr, "Not in presentation format"); + else + perror("inet_pton"); + exit(EXIT_FAILURE); + } +\& + if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { + perror("inet_ntop"); + exit(EXIT_FAILURE); + } +\& + printf("%s\en", str); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR inet_ntop (3) diff --git a/man/man3/initgroups.3 b/man/man3/initgroups.3 new file mode 100644 index 0000000..ea68719 --- /dev/null +++ b/man/man3/initgroups.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> +.\" Modified 2004-10-10 by aeb +.\" +.TH initgroups 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +initgroups \- initialize the supplementary group access list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <grp.h> +.P +.BI "int initgroups(const char *" user ", gid_t " group ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR initgroups (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR initgroups () +function initializes the group access list by +reading the group database +.I /etc/group +and using all groups of +which +.I user +is a member. +The additional group +.I group +is +also added to the list. +.P +The +.I user +argument must be non-NULL. +.SH RETURN VALUE +The +.BR initgroups () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate group information structure. +.TP +.B EPERM +The calling process has insufficient privilege. +See the underlying system call +.BR setgroups (2). +.SH FILES +.TP +.I /etc/group +group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR initgroups () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.3BSD. +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR credentials (7) diff --git a/man/man3/initstate.3 b/man/man3/initstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/initstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/initstate_r.3 b/man/man3/initstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/initstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/innetgr.3 b/man/man3/innetgr.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/innetgr.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/insque.3 b/man/man3/insque.3 new file mode 100644 index 0000000..905d803 --- /dev/null +++ b/man/man3/insque.3 @@ -0,0 +1,248 @@ +'\" t +.\" peter memishian -- meem@gnu.ai.mit.edu +.\" $Id: insque.3,v 1.2 1996/10/30 21:03:39 meem Exp meem $ +.\" and Copyright (c) 2010, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code (5.4.7) +.\" Solaris 2.x, OSF/1, and HP-UX manpages +.\" Curry's "UNIX Systems Programming for SVR4" (O'Reilly & Associates 1996) +.\" +.\" Changed to POSIX, 2003-08-11, aeb+wh +.\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular +.\" lists, added example program +.\" +.TH insque 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +insque, remque \- insert/remove an item from a queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <search.h> +.P +.BI "void insque(void *" elem ", void *" prev ); +.BI "void remque(void *" elem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR insque (), +.BR remque (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR insque () +and +.BR remque () +functions manipulate doubly linked lists. +Each element in the list is a structure of +which the first two elements are a forward and a +backward pointer. +The linked list may be linear (i.e., NULL forward pointer at +the end of the list and NULL backward pointer at the start of the list) +or circular. +.P +The +.BR insque () +function inserts the element pointed to by \fIelem\fP +immediately after the element pointed to by \fIprev\fP. +.P +If the list is linear, then the call +.I "insque(elem, NULL)" +can be used to insert the initial list element, +and the call sets the forward and backward pointers of +.I elem +to NULL. +.P +If the list is circular, +the caller should ensure that the forward and backward pointers of the +first element are initialized to point to that element, +and the +.I prev +argument of the +.BR insque () +call should also point to the element. +.P +The +.BR remque () +function removes the element pointed to by \fIelem\fP from the +doubly linked list. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR insque (), +.BR remque () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On ancient systems, +.\" e.g., SunOS, Linux libc4 and libc5 +the arguments of these functions were of type \fIstruct qelem *\fP, +defined as: +.P +.in +4n +.EX +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[1]; +}; +.EE +.in +.P +This is still what you will get if +.B _GNU_SOURCE +is defined before +including \fI<search.h>\fP. +.P +The location of the prototypes for these functions differs among several +versions of UNIX. +The above is the POSIX version. +Some systems place them in \fI<string.h>\fP. +.\" Linux libc4 and libc 5 placed them +.\" in \fI<stdlib.h>\fP. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +In glibc 2.4 and earlier, it was not possible to specify +.I prev +as NULL. +Consequently, to build a linear list, the caller had to build a list +using an initial call that contained the first two elements of the list, +with the forward and backward pointers in each element suitably initialized. +.SH EXAMPLES +The program below demonstrates the use of +.BR insque (). +Here is an example run of the program: +.P +.in +4n +.EX +.RB "$ " "./a.out \-c a b c" +Traversing completed list: + a + b + c +That was a circular list +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (insque.c) +.EX +#include <search.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +struct element { + struct element *forward; + struct element *backward; + char *name; +}; +\& +static struct element * +new_element(void) +{ + struct element *e; +\& + e = malloc(sizeof(*e)); + if (e == NULL) { + fprintf(stderr, "malloc() failed\en"); + exit(EXIT_FAILURE); + } +\& + return e; +} +\& +int +main(int argc, char *argv[]) +{ + struct element *first, *elem, *prev; + int circular, opt, errfnd; +\& + /* The "\-c" command\-line option can be used to specify that the + list is circular. */ +\& + errfnd = 0; + circular = 0; + while ((opt = getopt(argc, argv, "c")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: + circular = 1; + break; + default: + errfnd = 1; + break; + } + } +\& + if (errfnd || optind >= argc) { + fprintf(stderr, "Usage: %s [\-c] string...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Create first element and place it in the linked list. */ +\& + elem = new_element(); + first = elem; +\& + elem\->name = argv[optind]; +\& + if (circular) { + elem\->forward = elem; + elem\->backward = elem; + insque(elem, elem); + } else { + insque(elem, NULL); + } +\& + /* Add remaining command\-line arguments as list elements. */ +\& + while (++optind < argc) { + prev = elem; +\& + elem = new_element(); + elem\->name = argv[optind]; + insque(elem, prev); + } +\& + /* Traverse the list from the start, printing element names. */ +\& + printf("Traversing completed list:\en"); + elem = first; + do { + printf(" %s\en", elem\->name); + elem = elem\->forward; + } while (elem != NULL && elem != first); +\& + if (elem == first) + printf("That was a circular list\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR queue (7) diff --git a/man/man3/intro.3 b/man/man3/intro.3 new file mode 100644 index 0000000..fbf9f65 --- /dev/null +++ b/man/man3/intro.3 @@ -0,0 +1,135 @@ +.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-10-23 mtk, Nearly a complete rewrite of the earlier page. +.TH intro 3 2024-05-02 "Linux man-pages (unreleased)" +.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. +.P +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 +and +.IR \-lrt , +respectively, +for the aforementioned libraries). +.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 +.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). +.\" +.\" 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 +Section 3 of this manual is organized 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 +.P +This difficult history frequently makes it a poor example to follow +in design, +implementation, +and presentation. +.P +Ideally, +a library for the C language +is designed such that each header file +presents the interface to a coherent software module. +It provides a small number of function declarations +and exposes only data types and constants that +are required for use of those functions. +Together, +these are termed an API or +.IR "application program interface" . +Types and constants to be shared among multiple APIs +should be placed in header files that declare no functions. +This organization permits a C library module +to be documented concisely with one header file per manual page. +Such an approach +improves the readability and accessibility of library documentation, +and thereby the usability of the software. +.SH STANDARDS +Certain terms and abbreviations are used to indicate UNIX variants +and standards to which calls in this section conform. +See +.BR standards (7). +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source +for the author(s) and copyright conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR intro (2), +.BR errno (3), +.BR capabilities (7), +.BR credentials (7), +.BR environ (7), +.BR feature_test_macros (7), +.BR libc (7), +.BR math_error (7), +.BR path_resolution (7), +.BR pthreads (7), +.BR signal (7), +.BR standards (7), +.BR system_data_types (7) diff --git a/man/man3/iruserok.3 b/man/man3/iruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/iruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/iruserok_af.3 b/man/man3/iruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/iruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/isalnum.3 b/man/man3/isalnum.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalnum.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isalnum_l.3 b/man/man3/isalnum_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalnum_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isalpha.3 b/man/man3/isalpha.3 new file mode 100644 index 0000000..3625685 --- /dev/null +++ b/man/man3/isalpha.3 @@ -0,0 +1,405 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:10:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 17:51:50 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Sep 2 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de) +.\" +.TH isalpha 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, +isprint, ispunct, isspace, isupper, isxdigit, +isalnum_l, isalpha_l, isascii_l, isblank_l, iscntrl_l, +isdigit_l, isgraph_l, islower_l, +isprint_l, ispunct_l, isspace_l, isupper_l, isxdigit_l +\- character classification functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ctype.h> +.P +.BI "int isalnum(int " c ); +.BI "int isalpha(int " c ); +.BI "int iscntrl(int " c ); +.BI "int isdigit(int " c ); +.BI "int isgraph(int " c ); +.BI "int islower(int " c ); +.BI "int isprint(int " c ); +.BI "int ispunct(int " c ); +.BI "int isspace(int " c ); +.BI "int isupper(int " c ); +.BI "int isxdigit(int " c ); +.P +.BI "int isascii(int " c ); +.BI "int isblank(int " c ); +.P +.BI "int isalnum_l(int " c ", locale_t " locale ); +.BI "int isalpha_l(int " c ", locale_t " locale ); +.BI "int isblank_l(int " c ", locale_t " locale ); +.BI "int iscntrl_l(int " c ", locale_t " locale ); +.BI "int isdigit_l(int " c ", locale_t " locale ); +.BI "int isgraph_l(int " c ", locale_t " locale ); +.BI "int islower_l(int " c ", locale_t " locale ); +.BI "int isprint_l(int " c ", locale_t " locale ); +.BI "int ispunct_l(int " c ", locale_t " locale ); +.BI "int isspace_l(int " c ", locale_t " locale ); +.BI "int isupper_l(int " c ", locale_t " locale ); +.BI "int isxdigit_l(int " c ", locale_t " locale ); +.P +.BI "int isascii_l(int " c ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR isascii (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.P +.BR isblank (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR \%salnum_l (), +.BR \%salpha_l (), +.BR \%sblank_l (), +.BR \%scntrl_l (), +.BR \%sdigit_l (), +.BR \%sgraph_l (), +.BR \%slower_l (), +.BR \%sprint_l (), +.BR \%spunct_l (), +.BR \%sspace_l (), +.BR \%supper_l (), +.BR \%sxdigit_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.BR isascii_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 && (_SVID_SOURCE || _BSD_SOURCE) + Before glibc 2.10: + _GNU_SOURCE +.fi +.ad +.SH DESCRIPTION +These functions check whether +.IR c , +which must have the value of an +.I unsigned char +or +.BR EOF , +falls into a certain character class according to the specified locale. +The functions without the +"_l" suffix perform the check based on the current locale. +.P +The functions with the "_l" suffix perform the check +based on the locale specified by the locale object +.IR locale . +The behavior of these functions is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The list below explains the operation of the functions without +the "_l" suffix; +the functions with the "_l" suffix differ only in using the locale object +.I locale +instead of the current locale. +.TP +.BR isalnum () +checks for an alphanumeric character; it is equivalent to +.BI "(isalpha(" c ") || isdigit(" c "))" \fR. +.TP +.BR isalpha () +checks for an alphabetic character; in the standard \fB"C"\fP +locale, it is equivalent to +.BI "(isupper(" c ") || islower(" c "))" \fR. +In some locales, there may be additional characters for which +.BR isalpha () +is true\[em]letters which are neither uppercase nor lowercase. +.TP +.BR isascii () +checks whether \fIc\fP is a 7-bit +.I unsigned char +value that fits into +the ASCII character set. +.TP +.BR isblank () +checks for a blank character; that is, a space or a tab. +.TP +.BR iscntrl () +checks for a control character. +.TP +.BR isdigit () +checks for a digit (0 through 9). +.TP +.BR isgraph () +checks for any printable character except space. +.TP +.BR islower () +checks for a lowercase character. +.TP +.BR isprint () +checks for any printable character including space. +.TP +.BR ispunct () +checks for any printable character which is not a space or an +alphanumeric character. +.TP +.BR isspace () +checks for white-space characters. +In the +.B \[dq]C\[dq] +and +.B \[dq]POSIX\[dq] +locales, these are: space, form-feed +.RB ( \[aq]\ef\[aq] ), +newline +.RB ( \[aq]\en\[aq] ), +carriage return +.RB ( \[aq]\er\[aq] ), +horizontal tab +.RB ( \[aq]\et\[aq] ), +and vertical tab +.RB ( \[aq]\ev\[aq] ). +.TP +.BR isupper () +checks for an uppercase letter. +.TP +.BR isxdigit () +checks for hexadecimal digits, that is, one of +.br +.BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" . +.SH RETURN VALUE +The values returned are nonzero if the character +.I c +falls into the tested class, and zero if not. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isalnum (), +.BR isalpha (), +.BR isascii (), +.BR isblank (), +.BR iscntrl (), +.BR isdigit (), +.BR isgraph (), +.BR islower (), +.BR isprint (), +.BR ispunct (), +.BR isspace (), +.BR isupper (), +.BR isxdigit () +T} Thread safety MT-Safe +.TE +.\" FIXME: need a thread-safety statement about the *_l functions +.SH STANDARDS +.TP +.BR isalnum () +.TQ +.BR isalpha () +.TQ +.BR iscntrl () +.TQ +.BR isdigit () +.TQ +.BR isgraph () +.TQ +.BR islower () +.TQ +.BR isprint () +.TQ +.BR ispunct () +.TQ +.BR isspace () +.TQ +.BR isupper () +.TQ +.BR isxdigit () +.TQ +.BR isblank () +C11, POSIX.1-2008. +.TP +.BR isascii () +.TQ +.BR isalnum_l () +.TQ +.BR isalpha_l () +.TQ +.BR isblank_l () +.TQ +.BR iscntrl_l () +.TQ +.BR isdigit_l () +.TQ +.BR isgraph_l () +.TQ +.BR islower_l () +.TQ +.BR isprint_l () +.TQ +.BR ispunct_l () +.TQ +.BR isspace_l () +.TQ +.BR isupper_l () +.TQ +.BR isxdigit_l () +POSIX.1-2008. +.TP +.BR isascii_l () +GNU. +.SH HISTORY +.TP +.BR isalnum () +.TQ +.BR isalpha () +.TQ +.BR iscntrl () +.TQ +.BR isdigit () +.TQ +.BR isgraph () +.TQ +.BR islower () +.TQ +.BR isprint () +.TQ +.BR ispunct () +.TQ +.BR isspace () +.TQ +.BR isupper () +.TQ +.BR isxdigit () +C89, POSIX.1-2001. +.TP +.BR isblank () +C99, POSIX.1-2001. +.TP +.BR isascii () +POSIX.1-2001 (XSI). +.IP +POSIX.1-2008 marks it as obsolete, +noting that it cannot be used portably in a localized application. +.TP +.BR isalnum_l () +.TQ +.BR isalpha_l () +.TQ +.BR isblank_l () +.TQ +.BR iscntrl_l () +.TQ +.BR isdigit_l () +.TQ +.BR isgraph_l () +.TQ +.BR islower_l () +.TQ +.BR isprint_l () +.TQ +.BR ispunct_l () +.TQ +.BR isspace_l () +.TQ +.BR isupper_l () +.TQ +.BR isxdigit_l () +glibc 2.3. +POSIX.1-2008. +.TP +.BR isascii_l () +glibc 2.3. +.SH CAVEATS +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" ; +otherwise, +the behavior is undefined. +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.P +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.P +This is necessary because +.I char +may be the equivalent of +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.P +The details of what characters belong to which class depend on the +locale. +For example, +.BR isupper () +will not recognize an A-umlaut (\(:A) as an uppercase letter in the default +.B "C" +locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR newlocale (3), +.BR setlocale (3), +.BR toascii (3), +.BR tolower (3), +.BR toupper (3), +.BR uselocale (3), +.BR ascii (7), +.BR locale (7) diff --git a/man/man3/isalpha_l.3 b/man/man3/isalpha_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalpha_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isascii.3 b/man/man3/isascii.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isascii.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isascii_l.3 b/man/man3/isascii_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isascii_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isatty.3 b/man/man3/isatty.3 new file mode 100644 index 0000000..99cb872 --- /dev/null +++ b/man/man3/isatty.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH isatty 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isatty \- test whether a file descriptor refers to a terminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int isatty(int " fd ); +.fi +.SH DESCRIPTION +The +.BR isatty () +function tests whether +.I fd +is an open file descriptor referring to a terminal. +.SH RETURN VALUE +.BR isatty () +returns 1 if +.I fd +is an open file descriptor referring to a terminal; +otherwise 0 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +.I fd +refers to a file other than a terminal. +On some older kernels, some types of files +.\" e.g., FIFOs and pipes on 2.6.32 +resulted in the error +.B EINVAL +in this case (which is a violation of POSIX, which specifies the error +.BR ENOTTY ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isatty () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fstat (2), +.BR ttyname (3) diff --git a/man/man3/isblank.3 b/man/man3/isblank.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isblank.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isblank_l.3 b/man/man3/isblank_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isblank_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iscntrl.3 b/man/man3/iscntrl.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/iscntrl.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iscntrl_l.3 b/man/man3/iscntrl_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/iscntrl_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isdigit.3 b/man/man3/isdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isdigit_l.3 b/man/man3/isdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isfdtype.3 b/man/man3/isfdtype.3 new file mode 100644 index 0000000..74ecf93 --- /dev/null +++ b/man/man3/isfdtype.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH isfdtype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isfdtype \- test file type of a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/stat.h> +.B #include <sys/socket.h> +.P +.BI "int isfdtype(int " fd ", int " fdtype ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR isfdtype (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE + Before glibc 2.20: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR isfdtype () +function tests whether the file descriptor +.I fd +refers to a file of type +.IR fdtype . +The +.I fdtype +argument specifies one of the +.B S_IF* +constants defined in +.I <sys/stat.h> +and documented in +.BR stat (2) +(e.g., +.BR S_IFREG ). +.SH RETURN VALUE +The +.BR isfdtype () +function returns 1 if the file descriptor +.I fd +is of type +.I fdtype +and 0 if it is not. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +The +.BR isfdtype () +function can fail with any of the same errors as +.BR fstat (2). +.SH VERSIONS +Portable applications should use +.BR fstat (2) +instead. +.SH STANDARDS +None. +.SH HISTORY +It appeared in the draft POSIX.1g standard. +It is present on OpenBSD and Tru64 UNIX +(where the required header file in both cases is just +.IR <sys/stat.h> , +as shown in the POSIX.1g draft). +.SH SEE ALSO +.BR fstat (2) diff --git a/man/man3/isfinite.3 b/man/man3/isfinite.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isfinite.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isgraph.3 b/man/man3/isgraph.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isgraph.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isgraph_l.3 b/man/man3/isgraph_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isgraph_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isgreater.3 b/man/man3/isgreater.3 new file mode 100644 index 0000000..9252b63 --- /dev/null +++ b/man/man3/isgreater.3 @@ -0,0 +1,144 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2002-07-27 Walter Harms +.\" this was done with the help of the glibc manual +.\" +.TH isgreater 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isgreater, isgreaterequal, isless, islessequal, islessgreater, +isunordered \- floating-point relational tests without exception for NaN +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "int isgreater(" x ", " y ); +.BI "int isgreaterequal(" x ", " y ); +.BI "int isless(" x ", " y ); +.BI "int islessequal(" x ", " y ); +.BI "int islessgreater(" x ", " y ); +.BI "int isunordered(" x ", " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf + All functions described here: + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The normal relational operations (like +.BR < , +"less than") +fail if one of the operands is NaN. +This will cause an exception. +To avoid this, C99 defines the macros listed below. +.P +These macros are guaranteed to evaluate their arguments only once. +The arguments must be of real floating-point type (note: do not pass +integer values as arguments to these macros, since the arguments will +.I not +be promoted to real-floating types). +.TP +.BR isgreater () +determines \fI(x)\ >\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR isgreaterequal () +determines \fI(x)\ >=\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR isless () +determines \fI(x)\ <\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR islessequal () +determines \fI(x)\ <=\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR islessgreater () +determines \fI(x)\ < (y) || (x) >\ (y)\fP +without an exception if +.I x +or +.I y +is NaN. +This macro is not equivalent to \fIx\ !=\ y\fP because that expression is +true if +.I x +or +.I y +is NaN. +.TP +.BR isunordered () +determines whether its arguments are unordered, that is, whether +at least one of the arguments is a NaN. +.SH RETURN VALUE +The macros other than +.BR isunordered () +return the result of the relational comparison; +these macros return 0 if either argument is a NaN. +.P +.BR isunordered () +returns 1 if +.I x +or +.I y +is NaN and 0 otherwise. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isgreater (), +.BR isgreaterequal (), +.BR isless (), +.BR islessequal (), +.BR islessgreater (), +.BR isunordered () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Not all hardware supports these functions, +and where hardware support isn't provided, they will be emulated by macros. +This will result in a performance penalty. +Don't use these functions if NaN is of no concern for you. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR fpclassify (3), +.BR isnan (3) diff --git a/man/man3/isgreaterequal.3 b/man/man3/isgreaterequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isgreaterequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/isinf.3 b/man/man3/isinf.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isinf.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isinff.3 b/man/man3/isinff.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isinff.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isinfl.3 b/man/man3/isinfl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isinfl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isless.3 b/man/man3/isless.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isless.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islessequal.3 b/man/man3/islessequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/islessequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islessgreater.3 b/man/man3/islessgreater.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/islessgreater.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islower.3 b/man/man3/islower.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/islower.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/islower_l.3 b/man/man3/islower_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/islower_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isnan.3 b/man/man3/isnan.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isnan.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isnanf.3 b/man/man3/isnanf.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isnanf.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isnanl.3 b/man/man3/isnanl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isnanl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isnormal.3 b/man/man3/isnormal.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isnormal.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isprint.3 b/man/man3/isprint.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isprint.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isprint_l.3 b/man/man3/isprint_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isprint_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/ispunct.3 b/man/man3/ispunct.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/ispunct.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/ispunct_l.3 b/man/man3/ispunct_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/ispunct_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isspace.3 b/man/man3/isspace.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isspace.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isspace_l.3 b/man/man3/isspace_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isspace_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isunordered.3 b/man/man3/isunordered.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isunordered.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/isupper.3 b/man/man3/isupper.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isupper.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isupper_l.3 b/man/man3/isupper_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isupper_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iswalnum.3 b/man/man3/iswalnum.3 new file mode 100644 index 0000000..2d05ee1 --- /dev/null +++ b/man/man3/iswalnum.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswalnum 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswalnum \- test for alphanumeric wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswalnum(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalnum () +function is the wide-character equivalent of the +.BR isalnum (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alnum". +.P +The wide-character class "alnum" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"alnum" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "alnum" is disjoint from +the wide-character class "space" and its subclass "blank". +.P +The wide-character class "alnum" is disjoint from the wide-character class +"punct". +.P +The wide-character class "alnum" is the union of the wide-character classes +"alpha" and "digit". +As such, it also contains the wide-character class +"xdigit". +.P +The wide-character class "alnum" +always contains at least the letters +\[aq]A\[aq] to \[aq]Z\[aq], +\[aq]a\[aq] to \[aq]z\[aq], +and the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswalnum () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alnum". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswalnum () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswalnum () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalnum (3), +.BR iswctype (3) diff --git a/man/man3/iswalpha.3 b/man/man3/iswalpha.3 new file mode 100644 index 0000000..0f309a5 --- /dev/null +++ b/man/man3/iswalpha.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswalpha 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswalpha \- test for alphabetic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswalpha(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalpha () +function is the wide-character equivalent of the +.BR isalpha (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alpha". +.P +The wide-character class "alpha" is a subclass of the +wide-character class "alnum", +and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"alpha" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "alpha" is disjoint from +the wide-character class "space" and its subclass "blank". +.P +Being a subclass of the wide-character class "alnum", +the wide-character class "alpha" is disjoint from the +wide-character class "punct". +.P +The wide-character class "alpha" is disjoint from the wide-character class +"digit". +.P +The wide-character class "alpha" contains the wide-character classes "upper" +and "lower". +.P +The wide-character class "alpha" always contains at least the +letters \[aq]A\[aq] to \[aq]Z\[aq] and \[aq]a\[aq] to \[aq]z\[aq]. +.SH RETURN VALUE +The +.BR iswalpha () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alpha". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswalpha () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswalpha () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalpha (3), +.BR iswctype (3) diff --git a/man/man3/iswblank.3 b/man/man3/iswblank.3 new file mode 100644 index 0000000..81e3953 --- /dev/null +++ b/man/man3/iswblank.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswblank 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswblank \- test for whitespace wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswblank(wint_t " wc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR iswblank (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR iswblank () +function is the wide-character equivalent of the +.BR isblank (3) +function. +It tests whether \fIwc\fP is a wide character +belonging to the wide-character class "blank". +.P +The wide-character class "blank" is a subclass of the wide-character class +"space". +.P +Being a subclass of the wide-character class "space", +the wide-character class "blank" is disjoint from the +wide-character class "graph" and therefore also disjoint +from its subclasses "alnum", "alpha", "upper", "lower", "digit", +"xdigit", "punct". +.P +The wide-character class "blank" always contains +at least the space character +and the control character \[aq]\et\[aq]. +.SH RETURN VALUE +The +.BR iswblank () +function returns nonzero +if \fIwc\fP is a wide character +belonging to the wide-character class "blank". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswblank () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The behavior of +.BR iswblank () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isblank (3), +.BR iswctype (3) diff --git a/man/man3/iswcntrl.3 b/man/man3/iswcntrl.3 new file mode 100644 index 0000000..424fb9d --- /dev/null +++ b/man/man3/iswcntrl.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswcntrl 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswcntrl \- test for control wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswcntrl(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswcntrl () +function is the wide-character equivalent of the +.BR iscntrl (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "cntrl". +.P +The wide-character class "cntrl" is disjoint from the wide-character class +"print" and therefore also disjoint from its subclasses "graph", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.P +For an unsigned char +.IR c , +.I iscntrl(c) +implies +.IR iswcntrl(btowc(c)) , +but not vice versa. +.SH RETURN VALUE +The +.BR iswcntrl () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "cntrl". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswcntrl () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswcntrl () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iscntrl (3), +.BR iswctype (3) diff --git a/man/man3/iswctype.3 b/man/man3/iswctype.3 new file mode 100644 index 0000000..f49aff2 --- /dev/null +++ b/man/man3/iswctype.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswctype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswctype \- wide-character classification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswctype(wint_t " wc ", wctype_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character having the character property designated by +.I desc +(or in other words: belongs to the character class designated by +.IR desc ), +then the +.BR iswctype () +function returns nonzero. +Otherwise, it +returns zero. +If +.I wc +is +.BR WEOF , +zero is returned. +.P +.I desc +must be a character property descriptor +returned by the +.BR wctype (3) +function. +.SH RETURN VALUE +The +.BR iswctype () +function returns nonzero if +the +.I wc +has the designated +property. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswctype () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR wctype (3) diff --git a/man/man3/iswdigit.3 b/man/man3/iswdigit.3 new file mode 100644 index 0000000..d6caa4f --- /dev/null +++ b/man/man3/iswdigit.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswdigit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswdigit \- test for decimal digit wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswdigit () +function is the wide-character equivalent of the +.BR isdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "digit". +.P +The wide-character class "digit" is a subclass of the wide-character class +"xdigit", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide character +class "print", the wide-character class +"digit" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class +"digit" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character +class "alnum", the wide-character class +"digit" is disjoint from the wide-character class "punct". +.P +The wide-character class "digit" is +disjoint from the wide-character class +"alpha" and therefore also disjoint from its subclasses "lower", "upper". +.P +The wide-character class "digit" always +contains exactly the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswdigit () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "digit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswdigit () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isdigit (3), +.BR iswctype (3) diff --git a/man/man3/iswgraph.3 b/man/man3/iswgraph.3 new file mode 100644 index 0000000..cedc72f --- /dev/null +++ b/man/man3/iswgraph.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswgraph 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswgraph \- test for graphic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswgraph(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswgraph () +function is the wide-character equivalent of the +.BR isgraph (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "graph". +.P +The wide-character class "graph" is a subclass of the wide-character class +"print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"graph" is disjoint from the wide-character class "cntrl". +.P +The wide-character class "graph" is disjoint from the wide-character class +"space" and therefore also disjoint from its subclass "blank". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.P +The wide-character class "graph" contains all the wide characters from the +wide-character class "print" except the space character. +It therefore contains +the wide-character classes "alnum" and "punct". +.SH RETURN VALUE +The +.BR iswgraph () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "graph". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswgraph () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswgraph () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isgraph (3), +.BR iswctype (3) diff --git a/man/man3/iswlower.3 b/man/man3/iswlower.3 new file mode 100644 index 0000000..41051b9 --- /dev/null +++ b/man/man3/iswlower.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswlower 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswlower \- test for lowercase wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswlower(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswlower () +function is the wide-character equivalent of the +.BR islower (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "lower". +.P +The wide-character class "lower" is a subclass of the wide-character class +"alpha", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"lower" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "lower" is disjoint from the +wide-character class "space" and its subclass "blank". +.P +Being a subclass of the wide-character class "alnum", +the wide-character class +"lower" is disjoint from the wide-character class "punct". +.P +Being a subclass of the wide-character class "alpha", +the wide-character class +"lower" is disjoint from the wide-character class "digit". +.P +The wide-character class "lower" contains at least +those characters +.I wc +which are equal to +.I towlower(wc) +and different from +.IR towupper(wc) . +.P +The wide-character class "lower" always contains +at least the letters \[aq]a\[aq] to \[aq]z\[aq]. +.SH RETURN VALUE +The +.BR iswlower () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "lower". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswlower () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswlower () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR islower (3), +.BR iswctype (3), +.BR towlower (3) diff --git a/man/man3/iswprint.3 b/man/man3/iswprint.3 new file mode 100644 index 0000000..e570b0b --- /dev/null +++ b/man/man3/iswprint.3 @@ -0,0 +1,74 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswprint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswprint \- test for printing wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswprint(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswprint () +function is the wide-character equivalent of the +.BR isprint (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "print". +.P +The wide-character class "print" is disjoint from the wide-character class +"cntrl". +.P +The wide-character class "print" contains the wide-character class "graph". +.SH RETURN VALUE +The +.BR iswprint () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "print". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswprint () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswprint () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isprint (3), +.BR iswctype (3) diff --git a/man/man3/iswpunct.3 b/man/man3/iswpunct.3 new file mode 100644 index 0000000..426bd2d --- /dev/null +++ b/man/man3/iswpunct.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswpunct 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswpunct \- test for punctuation or symbolic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswpunct(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswpunct () +function is the wide-character equivalent of the +.BR ispunct (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "punct". +.P +The wide-character class "punct" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.P +The wide-character class "punct" is disjoint from the wide-character class +"alnum" and therefore also disjoint from its subclasses "alpha", "upper", +"lower", "digit", "xdigit". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"punct" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class +"punct" is disjoint from the wide-character class "space" and its subclass +"blank". +.SH RETURN VALUE +The +.BR iswpunct () +function returns nonzero +if +.I wc +is a wide-character +belonging to the wide-character class "punct". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswpunct () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswpunct () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function's name is a misnomer when dealing with Unicode characters, +because the wide-character class "punct" contains both punctuation characters +and symbol (math, currency, etc.) characters. +.SH SEE ALSO +.BR ispunct (3), +.BR iswctype (3) diff --git a/man/man3/iswspace.3 b/man/man3/iswspace.3 new file mode 100644 index 0000000..fdddacb --- /dev/null +++ b/man/man3/iswspace.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswspace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswspace \- test for whitespace wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswspace(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswspace () +function is the wide-character equivalent of the +.BR isspace (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "space". +.P +The wide-character class "space" is disjoint from the wide-character class +"graph" and therefore also disjoint from its subclasses "alnum", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.P +The wide-character class "space" contains the wide-character class "blank". +.P +The wide-character class "space" +always contains at least the space character +and the control characters +\[aq]\ef\[aq], \[aq]\en\[aq], \[aq]\er\[aq], \[aq]\et\[aq], and \[aq]\ev\[aq]. +.SH RETURN VALUE +The +.BR iswspace () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "space". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswspace () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswspace () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isspace (3), +.BR iswctype (3) diff --git a/man/man3/iswupper.3 b/man/man3/iswupper.3 new file mode 100644 index 0000000..27371e9 --- /dev/null +++ b/man/man3/iswupper.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswupper \- test for uppercase wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswupper(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswupper () +function is the wide-character equivalent of the +.BR isupper (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "upper". +.P +The wide-character class "upper" is a subclass of the wide-character class +"alpha", and therefore also a subclass of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", the wide-character class +"upper" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", the wide-character class +"upper" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character class "alnum", the wide-character class +"upper" is disjoint from the wide-character class "punct". +.P +Being a subclass of the wide-character class "alpha", the wide-character class +"upper" is disjoint from the wide-character class "digit". +.P +The wide-character class "upper" contains at least those characters +.I wc +which are equal to +.I towupper(wc) +and different from +.IR towlower(wc) . +.P +The wide-character class "upper" always contains at least the +letters \[aq]A\[aq] to \[aq]Z\[aq]. +.SH RETURN VALUE +The +.BR iswupper () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "upper". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswupper () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswupper () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR isupper (3), +.BR iswctype (3), +.BR towupper (3) diff --git a/man/man3/iswxdigit.3 b/man/man3/iswxdigit.3 new file mode 100644 index 0000000..063743b --- /dev/null +++ b/man/man3/iswxdigit.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswxdigit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswxdigit \- test for hexadecimal digit wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "int iswxdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswxdigit () +function is the wide-character equivalent of the +.BR isxdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "xdigit". +.P +The wide-character class "xdigit" is a subclass of the wide-character class +"alnum", and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", the wide-character class +"xdigit" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", the wide-character class +"xdigit" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character class "alnum", the wide-character class +"xdigit" is disjoint from the wide-character class "punct". +.P +The wide-character class "xdigit" always contains at least the +letters \[aq]A\[aq] to \[aq]F\[aq], \[aq]a\[aq] to \[aq]f\[aq] +and the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswxdigit () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "xdigit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswxdigit () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswxdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3), +.BR isxdigit (3) diff --git a/man/man3/isxdigit.3 b/man/man3/isxdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isxdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isxdigit_l.3 b/man/man3/isxdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isxdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/j0.3 b/man/man3/j0.3 new file mode 100644 index 0000000..4a97b3f --- /dev/null +++ b/man/man3/j0.3 @@ -0,0 +1,195 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, moved yxx() material into separate y0.3 page +.\" +.TH j0 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl \- +Bessel functions of the first kind +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double j0(double " x ); +.BI "double j1(double " x ); +.BI "double jn(int " n ", double " x ); +.P +.BI "float j0f(float " x ); +.BI "float j1f(float " x ); +.BI "float jnf(int " n ", float " x ); +.P +.BI "long double j0l(long double " x ); +.BI "long double j1l(long double " x ); +.BI "long double jnl(int " n ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR j0 (), +.BR j1 (), +.BR jn (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR j0f (), +.BR j0l (), +.BR j1f (), +.BR j1l (), +.BR jnf (), +.BR jnl (): +.nf + _XOPEN_SOURCE >= 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR j0 () +and +.BR j1 () +functions return Bessel functions of +.I x +of the first kind of orders 0 and 1, respectively. +The +.BR jn () +function +returns the Bessel function of +.I x +of the first kind of order +.IR n . +.P +The +.BR j0f (), +.BR j1f (), +and +.BR jnf (), +functions are versions that take and return +.I float +values. +The +.BR j0l (), +.BR j1l (), +and +.BR jnl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the first kind for +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is too large in magnitude, +or the result underflows, +a range error occurs, +and the return value is 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow, or \fIx\fP is too large in magnitude +.I errno +is set to +.BR ERANGE . +.P +These functions do not raise exceptions for +.BR fetestexcept (3). +.\" e.g., j0(1.5e16) +.\" This is intentional. +.\" See https://www.sourceware.org/bugzilla/show_bug.cgi?id=6805 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR j0 (), +.BR j0f (), +.BR j0l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR j1 (), +.BR j1f (), +.BR j1l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR jn (), +.BR jnf (), +.BR jnl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR j0 () +.TQ +.BR j1 () +.TQ +.BR jn () +POSIX.1-2008. +.TP +Others: +BSD. +.SH HISTORY +.TP +.BR j0 () +.TQ +.BR j1 () +.TQ +.BR jn () +SVr4, 4.3BSD, +POSIX.1-2001, POSIX.1-2008. +.TP +Others: +BSD. +.SH BUGS +There are errors of up to 2e\-16 in the values returned by +.BR j0 (), +.BR j1 (), +and +.BR jn () +for values of +.I x +between \-8 and 8. +.SH SEE ALSO +.BR y0 (3) diff --git a/man/man3/j0f.3 b/man/man3/j0f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j0f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j0l.3 b/man/man3/j0l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j0l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1.3 b/man/man3/j1.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1f.3 b/man/man3/j1f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1l.3 b/man/man3/j1l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jn.3 b/man/man3/jn.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jn.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jnf.3 b/man/man3/jnf.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jnf.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jnl.3 b/man/man3/jnl.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jnl.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jrand48.3 b/man/man3/jrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/jrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/jrand48_r.3 b/man/man3/jrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/jrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/key_decryptsession.3 b/man/man3/key_decryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_decryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_encryptsession.3 b/man/man3/key_encryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_encryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_gendes.3 b/man/man3/key_gendes.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_gendes.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_secretkey_is_set.3 b/man/man3/key_secretkey_is_set.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_secretkey_is_set.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_setsecret.3 b/man/man3/key_setsecret.3 new file mode 100644 index 0000000..5ea22c9 --- /dev/null +++ b/man/man3/key_setsecret.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" I had no way the check the functions out +.\" be careful +.TH key_setsecret 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +key_decryptsession, key_encryptsession, key_setsecret, key_gendes, +key_secretkey_is_set \- interfaces to rpc keyserver daemon +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <rpc/rpc.h> +.P +.BI "int key_decryptsession(char *" remotename ", des_block *" deskey ); +.BI "int key_encryptsession(char *" remotename ", des_block *" deskey ); +.P +.BI "int key_gendes(des_block *" deskey ); +.P +.BI "int key_setsecret(char *" key ); +.B int key_secretkey_is_set(void); +.fi +.SH DESCRIPTION +The functions here are used within the RPC's secure authentication +mechanism (AUTH_DES). +There should be no need for user programs to +use this functions. +.P +The function +.BR key_decryptsession () +uses the (remote) server netname and takes the DES key +for decrypting. +It uses the public key of the server and the +secret key associated with the effective UID of the calling process. +.P +The function +.BR key_encryptsession () +is the inverse of +.BR key_decryptsession (). +It encrypts the DES keys with the public key of the server and +the secret key associated with the effective UID of the calling process. +.P +The function +.BR key_gendes () +is used to ask the keyserver for a secure conversation key. +.P +The function +.BR key_setsecret () +is used to set the key for the effective UID of the calling process. +.P +The function +.BR key_secretkey_is_set () +can be used to determine whether a key has been +set for the effective UID of the calling process. +.SH RETURN VALUE +These functions return 1 on success and 0 on failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR key_decryptsession (), +.BR key_encryptsession (), +.BR key_gendes (), +.BR key_setsecret (), +.BR key_secretkey_is_set () +T} Thread safety MT-Safe +.TE +.SH NOTES +Note that we talk about two types of encryption here. +One is asymmetric using a public and secret key. +The other is symmetric, the +64-bit DES. +.P +These routines were part of the Linux/Doors-project, abandoned by now. +.SH SEE ALSO +.BR crypt (3) diff --git a/man/man3/killpg.3 b/man/man3/killpg.3 new file mode 100644 index 0000000..35edc0e --- /dev/null +++ b/man/man3/killpg.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)killpg.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Fri Jul 23 21:55:01 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2004-06-16 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on CAP_KILL +.\" Modified 2004-06-21 by aeb +.\" +.TH killpg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +killpg \- send signal to a process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int killpg(int " pgrp ", int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR killpg (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR killpg () +sends the signal +.I sig +to the process group +.IR pgrp . +See +.BR signal (7) +for a list of signals. +.P +If +.I pgrp +is 0, +.BR killpg () +sends the signal to the calling process's process group. +(POSIX says: if +.I pgrp +is less than or equal to 1, the behavior is undefined.) +.P +For the permissions required to send a signal to another process, see +.BR kill (2). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sig +is not a valid signal number. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process can be found in the process group specified by +.IR pgrp . +.TP +.B ESRCH +The process group was given as 0 but the sending process does not +have a process group. +.SH VERSIONS +There are various differences between the permission checking +in BSD-type systems and System\ V-type systems. +See the POSIX rationale for +.BR kill (3p). +A difference not mentioned by POSIX concerns the return +value +.BR EPERM : +BSD documents that no signal is sent and +.B EPERM +returned when the permission check failed for at least one target process, +while POSIX documents +.B EPERM +only when the permission check failed for all target processes. +.SS C library/kernel differences +On Linux, +.BR killpg () +is implemented as a library function that makes the call +.IR "kill(\-pgrp,\ sig)" . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4BSD). +.SH SEE ALSO +.BR getpgrp (2), +.BR kill (2), +.BR signal (2), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man3/klogctl.3 b/man/man3/klogctl.3 new file mode 100644 index 0000000..bbe6ab2 --- /dev/null +++ b/man/man3/klogctl.3 @@ -0,0 +1 @@ +.so man2/syslog.2 diff --git a/man/man3/l64a.3 b/man/man3/l64a.3 new file mode 100644 index 0000000..e54ce27 --- /dev/null +++ b/man/man3/l64a.3 @@ -0,0 +1 @@ +.so man3/a64l.3 diff --git a/man/man3/labs.3 b/man/man3/labs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/labs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/lckpwdf.3 b/man/man3/lckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/lckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/lcong48.3 b/man/man3/lcong48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/lcong48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/lcong48_r.3 b/man/man3/lcong48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/lcong48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/ldexp.3 b/man/man3/ldexp.3 new file mode 100644 index 0000000..5e00270 --- /dev/null +++ b/man/man3/ldexp.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH ldexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2 +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double ldexp(double " x ", int " exp ); +.BI "float ldexpf(float " x ", int " exp ); +.BI "long double ldexpl(long double " x ", int " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ldexpf (), +.BR ldexpl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the result of multiplying the floating-point number +.I x +by 2 raised to the power +.IR exp . +.SH RETURN VALUE +On success, these functions return +.IR "x * (2\[ha]exp)" . +.P +If +.I exp +is zero, then +.I x +is returned. +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If the result underflows, +a range error occurs, +and zero is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ldexp (), +.BR ldexpf (), +.BR ldexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR modf (3), +.BR scalbln (3) diff --git a/man/man3/ldexpf.3 b/man/man3/ldexpf.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man/man3/ldexpf.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man/man3/ldexpl.3 b/man/man3/ldexpl.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man/man3/ldexpl.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man/man3/ldiv.3 b/man/man3/ldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/ldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/le16toh.3 b/man/man3/le16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/le32toh.3 b/man/man3/le32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/le64toh.3 b/man/man3/le64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/lfind.3 b/man/man3/lfind.3 new file mode 100644 index 0000000..24179b4 --- /dev/null +++ b/man/man3/lfind.3 @@ -0,0 +1 @@ +.so man3/lsearch.3 diff --git a/man/man3/lgamma.3 b/man/man3/lgamma.3 new file mode 100644 index 0000000..8b1381b --- /dev/null +++ b/man/man3/lgamma.3 @@ -0,0 +1,202 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" +.TH lgamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \- +log gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double lgamma(double " x ); +.BI "float lgammaf(float " x ); +.BI "long double lgammal(long double " x ); +.P +.BI "double lgamma_r(double " x ", int *" signp ); +.BI "float lgammaf_r(float " x ", int *" signp ); +.BI "long double lgammal_r(long double " x ", int *" signp ); +.P +.BI "extern int " signgam ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR lgamma (): + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR lgammaf (), +.BR lgammal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR lgamma_r (), +.BR lgammaf_r (), +.BR lgammal_r (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.IR signgam : +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +For the definition of the Gamma function, see +.BR tgamma (3). +.P +The +.BR lgamma (), +.BR lgammaf (), +and +.BR lgammal () +functions return the natural logarithm of +the absolute value of the Gamma function. +The sign of the Gamma function is returned in the +external integer +.I signgam +declared in +.IR <math.h> . +It is 1 when the Gamma function is positive or zero, \-1 +when it is negative. +.P +Since using a constant location +.I signgam +is not thread-safe, the functions +.BR lgamma_r (), +.BR lgammaf_r (), +and +.BR lgammal_r () +have been introduced; they return the sign via the argument +.IR signp . +.SH RETURN VALUE +On success, these functions return the natural logarithm of Gamma(x). +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is 1 or 2, +0 is returned. +.P +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.P +If +.I x +is a nonpositive integer, +a pole error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.P +If the result overflows, +a range error occurs, +.\" e.g., lgamma(DBL_MAX) +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Pole error: \fIx\fP is a nonpositive integer +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH STANDARDS +.TP +.BR lgamma () +.TQ +.BR lgammaf () +.TQ +.BR lgammal () +C11, POSIX.1-2008. +.TP +.I signgam +POSIX.1-2008. +.TP +.BR lgamma_r () +.TQ +.BR lgammaf_r () +.TQ +.BR lgammal_r () +None. +.SH HISTORY +.TP +.BR lgamma () +.TQ +.BR lgammaf () +.TQ +.BR lgammal () +C99, POSIX.1-2001. +.TP +.I signgam +POSIX.1-2001. +.TP +.BR lgamma_r () +.TQ +.BR lgammaf_r () +.TQ +.BR lgammal_r () +None. +.SH BUGS +In glibc 2.9 and earlier, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6777 +when a pole error occurs, +.I errno +is set to +.BR EDOM ; +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, glibc does the right thing. +.SH SEE ALSO +.BR tgamma (3) diff --git a/man/man3/lgamma_r.3 b/man/man3/lgamma_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgamma_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammaf.3 b/man/man3/lgammaf.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammaf.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammaf_r.3 b/man/man3/lgammaf_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammaf_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammal.3 b/man/man3/lgammal.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammal.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammal_r.3 b/man/man3/lgammal_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammal_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lio_listio.3 b/man/man3/lio_listio.3 new file mode 100644 index 0000000..2e38492 --- /dev/null +++ b/man/man3/lio_listio.3 @@ -0,0 +1,224 @@ +'\" t +.\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH lio_listio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lio_listio \- initiate a list of I/O requests +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include <aio.h>" +.P +.BI "int lio_listio(int " mode , +.BI " struct aiocb *restrict const " aiocb_list [restrict], +.BI " int " nitems ", struct sigevent *restrict " sevp ); +.fi +.SH DESCRIPTION +The +.BR lio_listio () +function initiates the list of I/O operations described by the array +.IR aiocb_list . +.P +The +.I mode +operation has one of the following values: +.TP +.B LIO_WAIT +The call blocks until all operations are complete. +The +.I sevp +argument is ignored. +.TP +.B LIO_NOWAIT +The I/O operations are queued for processing and the call returns immediately. +When all of the I/O operations complete, asynchronous notification occurs, +as specified by the +.I sevp +argument; see +.BR sigevent (3type) +for details. +If +.I sevp +is NULL, no asynchronous notification occurs. +.P +The +.I aiocb_list +argument is an array of pointers to +.I aiocb +structures that describe I/O operations. +These operations are executed in an unspecified order. +The +.I nitems +argument specifies the size of the array +.IR aiocb_list . +Null pointers in +.I aiocb_list +are ignored. +.P +In each control block in +.IR aiocb_list , +the +.I aio_lio_opcode +field specifies the I/O operation to be initiated, as follows: +.TP +.B LIO_READ +Initiate a read operation. +The operation is queued as for a call to +.BR aio_read (3) +specifying this control block. +.TP +.B LIO_WRITE +Initiate a write operation. +The operation is queued as for a call to +.BR aio_write (3) +specifying this control block. +.TP +.B LIO_NOP +Ignore this control block. +.P +The remaining fields in each control block have the same meanings as for +.BR aio_read (3) +and +.BR aio_write (3). +The +.I aio_sigevent +fields of each control block can be used to specify notifications +for the individual I/O operations (see +.BR sigevent (7)). +.SH RETURN VALUE +If +.I mode +is +.BR LIO_NOWAIT , +.BR lio_listio () +returns 0 if all I/O operations are successfully queued. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.P +If +.I mode +is +.BR LIO_WAIT , +.BR lio_listio () +returns 0 when all of the I/O operations have completed successfully. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.P +The return status from +.BR lio_listio () +provides information only about the call itself, +not about the individual I/O operations. +One or more of the I/O operations may fail, +but this does not prevent other operations completing. +The status of individual I/O operations in +.I aiocb_list +can be determined using +.BR aio_error (3). +When an operation has completed, +its return status can be obtained using +.BR aio_return (3). +Individual I/O operations can fail for the reasons described in +.BR aio_read (3) +and +.BR aio_write (3). +.SH ERRORS +The +.BR lio_listio () +function may fail for the following reasons: +.TP +.B EAGAIN +Out of resources. +.TP +.B EAGAIN +.\" Doesn't happen in glibc(?) +The number of I/O operations specified by +.I nitems +would cause the limit +.B AIO_MAX +to be exceeded. +.TP +.B EINTR +.I mode +was +.B LIO_WAIT +and a signal +was caught before all I/O operations completed; see +.BR signal (7). +(This may even be one of the signals used for +asynchronous I/O completion notification.) +.TP +.B EINVAL +.I mode +is invalid, or +.\" Doesn't happen in glibc(?) +.I nitems +exceeds the limit +.BR AIO_LISTIO_MAX . +.TP +.B EIO +One of more of the operations specified by +.I aiocb_list +failed. +.\" e.g., ioa_reqprio or aio_lio_opcode was invalid +The application can check the status of each operation using +.BR aio_return (3). +.P +If +.BR lio_listio () +fails with the error +.BR EAGAIN , +.BR EINTR , +or +.BR EIO , +then some of the operations in +.I aiocb_list +may have been initiated. +If +.BR lio_listio () +fails for any other reason, +then none of the I/O operations has been initiated. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lio_listio () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control blocks before use. +The control blocks must not be changed while the I/O operations +are in progress. +The buffer areas being read into or written from +.\" or the control block of the operation +must not be accessed during the operations or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR aio (7) diff --git a/man/man3/list.3 b/man/man3/list.3 new file mode 100644 index 0000000..bab95a0 --- /dev/null +++ b/man/man3/list.3 @@ -0,0 +1,308 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH LIST 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +LIST_EMPTY, +LIST_ENTRY, +LIST_FIRST, +LIST_FOREACH, +.\"LIST_FOREACH_FROM, +.\"LIST_FOREACH_SAFE, +.\"LIST_FOREACH_FROM_SAFE, +LIST_HEAD, +LIST_HEAD_INITIALIZER, +LIST_INIT, +LIST_INSERT_AFTER, +LIST_INSERT_BEFORE, +LIST_INSERT_HEAD, +LIST_NEXT, +.\"LIST_PREV, +LIST_REMOVE +.\"LIST_SWAP +\- implementation of a doubly linked list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/queue.h> +.P +.B LIST_ENTRY(TYPE); +.P +.B LIST_HEAD(HEADNAME, TYPE); +.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ); +.BI "void LIST_INIT(LIST_HEAD *" head ); +.P +.BI "int LIST_EMPTY(LIST_HEAD *" head ); +.P +.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.P +.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head ); +.\" .BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head , +.\" .BI " struct TYPE, LIST_ENTRY " NAME ); +.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME ); +.P +.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); +.\" .BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); +.\" .P +.\" .BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head , +.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head , +.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME ); +.\" .P +.\" .BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 , +.\" .BI " struct TYPE, LIST_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked lists. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR LIST_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR LIST_HEAD (). +.SS Creation +A list is headed by a structure defined by the +.BR LIST_HEAD () +macro. +This structure contains a single pointer to the first element on the list. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the list. +New elements can be added to the list +after an existing element, +before an existing element, +or at the head of the list. +A +.I LIST_HEAD +structure is declared as follows: +.P +.in +4 +.EX +LIST_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR LIST_ENTRY () +declares a structure that connects the elements in the list. +.P +.BR LIST_HEAD_INITIALIZER () +evaluates to an initializer for the list +.IR head . +.P +.BR LIST_INIT () +initializes the list referenced by +.IR head . +.P +.BR LIST_EMPTY () +evaluates to true if there are no elements in the list. +.SS Insertion +.BR LIST_INSERT_HEAD () +inserts the new element +.I elm +at the head of the list. +.P +.BR LIST_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR LIST_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR LIST_FIRST () +returns the first element in the list, or NULL if the list is empty. +.\" .P +.\" .BR LIST_PREV () +.\" returns the previous element in the list, or NULL if this is the first. +.\" List +.\" .I head +.\" must contain element +.\" .IR elm . +.P +.BR LIST_NEXT () +returns the next element in the list, or NULL if this is the last. +.P +.BR LIST_FOREACH () +traverses the list referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR LIST_FOREACH_FROM () +.\" behaves identically to +.\" .BR LIST_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found LIST element and begins the loop at +.\" .I var +.\" instead of the first element in the LIST referenced by +.\" .IR head . +.\" .P +.\" .BR LIST_FOREACH_SAFE () +.\" traverses the list referenced by +.\" .I head +.\" in the forward direction, assigning each element in turn to +.\" .IR var . +.\" However, unlike +.\" .BR LIST_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR LIST_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR LIST_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found LIST element and begins the loop at +.\" .I var +.\" instead of the first element in the LIST referenced by +.\" .IR head . +.SS Removal +.BR LIST_REMOVE () +removes the element +.I elm +from the list. +.\" .SS Other features +.\" .BR LIST_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR LIST_EMPTY () +returns nonzero if the list is empty, +and zero if the list contains at least one entry. +.P +.BR LIST_FIRST (), +and +.BR LIST_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR LIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH BUGS +.BR LIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR LIST_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (list.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> +\& +struct entry { + int data; + LIST_ENTRY(entry) entries; /* List */ +}; +\& +LIST_HEAD(listhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct listhead head; /* List head */ + int i; +\& + LIST_INIT(&head); /* Initialize the list */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + LIST_INSERT_HEAD(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + LIST_INSERT_AFTER(n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + LIST_INSERT_BEFORE(n2, n3, entries); +\& + i = 0; /* Forward traversal */ + LIST_FOREACH(np, &head, entries) + np\->data = i++; +\& + LIST_REMOVE(n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + LIST_FOREACH(np, &head, entries) + printf("%i\en", np\->data); + /* List deletion */ + n1 = LIST_FIRST(&head); + while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; + } + LIST_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/llabs.3 b/man/man3/llabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/llabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/lldiv.3 b/man/man3/lldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/lldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/llrint.3 b/man/man3/llrint.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrint.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llrintf.3 b/man/man3/llrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llrintl.3 b/man/man3/llrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llround.3 b/man/man3/llround.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llround.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/llroundf.3 b/man/man3/llroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/llroundl.3 b/man/man3/llroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/localeconv.3 b/man/man3/localeconv.3 new file mode 100644 index 0000000..0077714 --- /dev/null +++ b/man/man3/localeconv.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:01:20 1993 by Rik Faith (faith@cs.unc.edu) +.TH localeconv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +localeconv \- get numeric formatting information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.B struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The +.BR localeconv () +function returns a pointer to a +.I struct lconv +for the current locale. +This structure is shown in +.BR locale (7), +and contains all values associated with the locale categories +.B LC_NUMERIC +and +.BR LC_MONETARY . +Programs may also use the functions +.BR printf (3) +and +.BR strfmon (3), +which behave according to the actual locale in use. +.SH RETURN VALUE +The +.BR localeconv () +function returns a pointer to a filled in +.IR "struct lconv" . +This structure may be (in glibc, +.IR is ) +statically allocated, and may be overwritten by subsequent calls. +According to POSIX, +the caller should not modify the contents of this structure. +The +.BR localeconv () +function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR localeconv () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:localeconv locale +T} +.TE +.SH STANDARDS +C11. +.SH HISTORY +C89. +.SH BUGS +The +.BR printf (3) +family of functions may or may not honor the current locale. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strftime (3), +.BR locale (7) diff --git a/man/man3/localtime.3 b/man/man3/localtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/localtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/localtime_r.3 b/man/man3/localtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/localtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/lockf.3 b/man/man3/lockf.3 new file mode 100644 index 0000000..c86895a --- /dev/null +++ b/man/man3/lockf.3 @@ -0,0 +1,179 @@ +'\" t +.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org> +.\" Created Thu Aug 7 00:44:00 ART 1997 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Added section stuff, aeb, 2002-04-22. +.\" Corrected include file, drepper, 2003-06-15. +.\" +.TH lockf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lockf \- apply, test or remove a POSIX lock on an open file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int lockf(int " fd ", int " op ", off_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR lockf (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Apply, test, or remove a POSIX lock on a section of an open file. +The file is specified by +.IR fd , +a file descriptor open for writing, the action by +.IR op , +and the section consists of byte positions +.IR pos .. pos + len \-1 +if +.I len +is positive, and +.IR pos \- len .. pos \-1 +if +.I len +is negative, where +.I pos +is the current file position, and if +.I len +is zero, the section extends from the current file position to +infinity, encompassing the present and future end-of-file positions. +In all cases, the section may extend past current end-of-file. +.P +On Linux, +.BR lockf () +is just an interface on top of +.BR fcntl (2) +locking. +Many other systems implement +.BR lockf () +in this way, but note that POSIX.1 leaves the relationship between +.BR lockf () +and +.BR fcntl (2) +locks unspecified. +A portable application should probably avoid mixing calls +to these interfaces. +.P +Valid operations are given below: +.TP +.B F_LOCK +Set an exclusive lock on the specified section of the file. +If (part of) this section is already locked, the call +blocks until the previous lock is released. +If this section overlaps an earlier locked section, +both are merged. +File locks are released as soon as the process holding the locks +closes some file descriptor for the file. +A child process does not inherit these locks. +.TP +.B F_TLOCK +Same as +.B F_LOCK +but the call never blocks and returns an error instead if the file is +already locked. +.TP +.B F_ULOCK +Unlock the indicated section of the file. +This may cause a locked section to be split into two locked sections. +.TP +.B F_TEST +Test the lock: return 0 if the specified section +is unlocked or locked by this process; return \-1, set +.I errno +to +.B EAGAIN +.RB ( EACCES +on some other systems), +if another process holds a lock. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +The file is locked and +.B F_TLOCK +or +.B F_TEST +was specified, or the operation is prohibited because the file has +been memory-mapped by another process. +.TP +.B EBADF +.I fd +is not an open file descriptor; or +.I op +is +.B F_LOCK +or +.B F_TLOCK +and +.I fd +is not a writable file descriptor. +.TP +.B EDEADLK +.I op +was +.B F_LOCK +and this lock operation would cause a deadlock. +.TP +.B EINTR +While waiting to acquire a lock, the call was interrupted by +delivery of a signal caught by a handler; see +.BR signal (7). +.TP +.B EINVAL +An invalid operation was specified in +.IR op . +.TP +.B ENOLCK +Too many segment locks open, lock table is full. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lockf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SH SEE ALSO +.BR fcntl (2), +.BR flock (2) +.P +.I locks.txt +and +.I mandatory\-locking.txt +in the Linux kernel source directory +.I Documentation/filesystems +(on older kernels, these files are directly under the +.I Documentation +directory, and +.I mandatory\-locking.txt +is called +.IR mandatory.txt ) diff --git a/man/man3/log.3 b/man/man3/log.3 new file mode 100644 index 0000000..29ec350 --- /dev/null +++ b/man/man3/log.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log, logf, logl \- natural logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double log(double " x ); +.BI "float logf(float " x ); +.BI "long double logl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR logf (), +.BR logl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the natural logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is 1, the result is +0. +.P +If +.I x +is positive infinity, +positive infinity is returned. +.P +If +.I x +is zero, +then a pole error occurs, and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is negative (including negative infinity), then +a domain error occurs, and a NaN (not a number) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log (), +.BR logf (), +.BR logl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +In glibc 2.5 and earlier, +taking the +.BR log () +of a NaN produces a bogus invalid floating-point +.RB ( FE_INVALID ) +exception. +.SH SEE ALSO +.BR cbrt (3), +.BR clog (3), +.BR log10 (3), +.BR log1p (3), +.BR log2 (3), +.BR sqrt (3) diff --git a/man/man3/log10.3 b/man/man3/log10.3 new file mode 100644 index 0000000..33bdaf0 --- /dev/null +++ b/man/man3/log10.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log10, log10f, log10l \- base-10 logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double log10(double " x ); +.BI "float log10f(float " x ); +.BI "long double log10l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR log10f (), +.BR log10l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the base-10 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-10 logarithm of +.IR x . +.P +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log10 (), +.BR log10f (), +.BR log10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR clog10 (3), +.BR exp10 (3), +.BR log (3), +.BR log2 (3), +.BR sqrt (3) diff --git a/man/man3/log10f.3 b/man/man3/log10f.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man/man3/log10f.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man/man3/log10l.3 b/man/man3/log10l.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man/man3/log10l.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man/man3/log1p.3 b/man/man3/log1p.3 new file mode 100644 index 0000000..0eadb1f --- /dev/null +++ b/man/man3/log1p.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com> +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH log1p 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log1p, log1pf, log1pl \- logarithm of 1 plus argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double log1p(double " x ); +.BI "float log1pf(float " x ); +.BI "long double log1pl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR log1p (): + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR log1pf (), +.BR log1pl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value equivalent to +.P +.nf + log (1 + \fIx\fP) +.fi +.P +The result is computed in a way +that is accurate even if the value of +.I x +is near zero. +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR "(1\ +\ x)" . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is \-1, a pole error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is less than \-1 (including negative infinity), +a domain error occurs, +and a NaN (not a number) is returned. +.\" POSIX.1 specifies a possible range error if x is subnormal +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is less than \-1 +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is \-1 +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log1p (), +.BR log1pf (), +.BR log1pl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.\" BSD +.SH BUGS +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B EDOM +when a domain error occurred. +.P +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR expm1 (3), +.BR log (3) diff --git a/man/man3/log1pf.3 b/man/man3/log1pf.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man/man3/log1pf.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man/man3/log1pl.3 b/man/man3/log1pl.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man/man3/log1pl.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man/man3/log2.3 b/man/man3/log2.3 new file mode 100644 index 0000000..64ea6d3 --- /dev/null +++ b/man/man3/log2.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log2, log2f, log2l \- base-2 logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double log2(double " x ); +.BI "float log2f(float " x ); +.BI "long double log2l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR log2 (), +.BR log2f (), +.BR log2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the base-2 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-2 logarithm of +.IR x . +.P +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log2 (), +.BR log2f (), +.BR log2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR clog2 (3), +.BR log (3), +.BR log10 (3), +.BR sqrt (3) diff --git a/man/man3/log2f.3 b/man/man3/log2f.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man/man3/log2f.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man/man3/log2l.3 b/man/man3/log2l.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man/man3/log2l.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man/man3/logb.3 b/man/man3/logb.3 new file mode 100644 index 0000000..9205905 --- /dev/null +++ b/man/man3/logb.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH logb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +logb, logbf, logbl \- get exponent of a floating-point value +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double logb(double " x ); +.BI "float logbf(float " x ); +.BI "long double logbl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR logb (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR logbf (), +.BR logbl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions extract the exponent from the +internal floating-point representation of +.I x +and return it as a floating-point value. +The integer constant +.BR FLT_RADIX , +defined in +.IR <float.h> , +indicates the radix used for the system's floating-point representation. +If +.B FLT_RADIX +is 2, +.BI logb( x ) +is similar to +.BI floor(log2(fabs( x )))\f[R],\f[] +except that the latter may give an incorrect integer +due to intermediate rounding. +.P +If +.I x +is subnormal, +.BR logb () +returns the exponent +.I x +would have if it were normalized. +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is zero, then a pole error occurs, and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is negative infinity or positive infinity, then +positive infinity is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Pole error: \fIx\fP is 0 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" log(), log2(), log10() do set errno +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6793 +.\" +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR logb (), +.BR logbf (), +.BR logbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.TP +.BR logb () +4.3BSD +(see IEEE.3 in the 4.3BSD manual). +.SH SEE ALSO +.BR ilogb (3), +.BR log (3) diff --git a/man/man3/logbf.3 b/man/man3/logbf.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man/man3/logbf.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man/man3/logbl.3 b/man/man3/logbl.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man/man3/logbl.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man/man3/logf.3 b/man/man3/logf.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man/man3/logf.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man/man3/login.3 b/man/man3/login.3 new file mode 100644 index 0000000..b0df3ad --- /dev/null +++ b/man/man3/login.3 @@ -0,0 +1,151 @@ +'\" t +.\" Derived from text written by Martin Schulze (or taken from glibc.info) +.\" and text written by Paul Thompson - both copyright 2002. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH login 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +login, logout \- write utmp and wtmp entries +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include <utmp.h> +.P +.BI "void login(const struct utmp *" ut ); +.BI "int logout(const char *" ut_line ); +.fi +.SH DESCRIPTION +The utmp file records who is currently using the system. +The wtmp file records all logins and logouts. +See +.BR utmp (5). +.P +The function +.BR login () +takes the supplied +.IR "struct utmp" , +.IR ut , +and writes it to both the utmp and the wtmp file. +.P +The function +.BR logout () +clears the entry in the utmp file again. +.SS GNU details +More precisely, +.BR login () +takes the argument +.I ut +struct, fills the field +.I ut\->ut_type +(if there is such a field) with the value +.BR USER_PROCESS , +and fills the field +.I ut\->ut_pid +(if there is such a field) with the process ID of the calling process. +Then it tries to fill the field +.IR ut\->ut_line . +It takes the first of +.IR stdin , +.IR stdout , +.I stderr +that is a terminal, and +stores the corresponding pathname minus a possible leading +.I /dev/ +into this field, and then writes the struct to the utmp file. +On the other hand, +if no terminal name was found, this field is filled with "???" +and the struct is not written to the utmp file. +After this, the struct is written to the wtmp file. +.P +The +.BR logout () +function searches the utmp file for an entry matching the +.I ut_line +argument. +If a record is found, it is updated by zeroing out the +.I ut_name +and +.I ut_host +fields, updating the +.I ut_tv +timestamp field and setting +.I ut_type +(if there is such a field) to +.BR DEAD_PROCESS . +.SH RETURN VALUE +The +.BR logout () +function returns 1 if the entry was successfully written to the +database, or 0 if an error occurred. +.SH FILES +.TP +.I /var/run/utmp +user accounting database, configured through +.B _PATH_UTMP +in +.I <paths.h> +.TP +.I /var/log/wtmp +user accounting log file, configured through +.B _PATH_WTMP +in +.I <paths.h> +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR login (), +.BR logout () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent +sig:ALRM timer +T} +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR login () +and +.BR logout () +calls those functions, +so we use race:utent to remind users. +.SH VERSIONS +The member +.I ut_user +of +.I struct utmp +is called +.I ut_name +in BSD. +Therefore, +.I ut_name +is defined as an alias for +.I ut_user +in +.IR <utmp.h> . +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR getutent (3), +.BR utmp (5) diff --git a/man/man3/login_tty.3 b/man/man3/login_tty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man/man3/login_tty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man/man3/logl.3 b/man/man3/logl.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man/man3/logl.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man/man3/logout.3 b/man/man3/logout.3 new file mode 100644 index 0000000..a1ee672 --- /dev/null +++ b/man/man3/logout.3 @@ -0,0 +1 @@ +.so man3/login.3 diff --git a/man/man3/logwtmp.3 b/man/man3/logwtmp.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man/man3/logwtmp.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man/man3/longjmp.3 b/man/man3/longjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/longjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/lrand48.3 b/man/man3/lrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/lrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/lrand48_r.3 b/man/man3/lrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/lrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/lrint.3 b/man/man3/lrint.3 new file mode 100644 index 0000000..990b8d1 --- /dev/null +++ b/man/man3/lrint.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lrint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "long lrint(double " x ); +.BI "long lrintf(float " x ); +.BI "long lrintl(long double " x ); +.P +.BI "long long llrint(double " x ); +.BI "long long llrintf(float " x ); +.BI "long long llrintl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +using the current rounding direction (see +.BR fesetround (3)). +.P +Note that unlike the +.BR rint (3) +family of functions, +the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6798 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lrint (), +.BR lrintf (), +.BR lrintl (), +.BR llrint (), +.BR llrintf (), +.BR llrintl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/lrintf.3 b/man/man3/lrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/lrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/lrintl.3 b/man/man3/lrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/lrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/lround.3 b/man/man3/lround.3 new file mode 100644 index 0000000..24533f7 --- /dev/null +++ b/man/man3/lround.3 @@ -0,0 +1,113 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lround 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lround, lroundf, lroundl, llround, llroundf, llroundl \- round to +nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "long lround(double " x ); +.BI "long lroundf(float " x ); +.BI "long lroundl(long double " x ); +.P +.BI "long long llround(double " x ); +.BI "long long llroundf(float " x ); +.BI "long long llroundl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +rounding halfway cases away from zero, +regardless of the current rounding direction (see +.BR fenv (3)). +.P +Note that unlike the +.BR round (3) +and +.BR ceil (3), +functions, the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6797 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lround (), +.BR lroundf (), +.BR lroundl (), +.BR llround (), +.BR llroundf (), +.BR llroundl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/lroundf.3 b/man/man3/lroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/lroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/lroundl.3 b/man/man3/lroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/lroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/lsearch.3 b/man/man3/lsearch.3 new file mode 100644 index 0000000..ea25d5f --- /dev/null +++ b/man/man3/lsearch.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Corrected prototype and include, aeb, 990927 +.TH lsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lfind, lsearch \- linear search of an array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <search.h> +.P +.BI "void *lfind(const void " key [. size "], \ +const void " base [. size " * ." nmemb ], +.BI " size_t *" nmemb ", size_t " size , +.BI " int(*" compar ")(const void [." size "], \ +const void [." size ])); +.BI "void *lsearch(const void " key [. size "], \ +void " base [. size " * ." nmemb ], +.BI " size_t *" nmemb ", size_t " size , +.BI " int(*" compar ")(const void [." size "], \ +const void [." size ])); +.fi +.SH DESCRIPTION +.BR lfind () +and +.BR lsearch () +perform a linear search for +.I key +in the array +.I base +which has +.I *nmemb +elements of +.I size +bytes each. +The comparison function referenced by +.I compar +is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and which +returns zero if the +.I key +object matches the array member, and +nonzero otherwise. +.P +If +.BR lsearch () +does not find a matching element, then the +.I key +object is inserted at the end of the table, and +.I *nmemb +is +incremented. +In particular, one should know that a matching element +exists, or that more room is available. +.SH RETURN VALUE +.BR lfind () +returns a pointer to a matching member of the array, or +NULL if no match is found. +.BR lsearch () +returns a pointer to +a matching member of the array, or to the newly added member if no +match is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lfind (), +.BR lsearch () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +libc-4.6.27. +.SH BUGS +The naming is unfortunate. +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR tsearch (3) diff --git a/man/man3/lseek64.3 b/man/man3/lseek64.3 new file mode 100644 index 0000000..2e1d7ec --- /dev/null +++ b/man/man3/lseek64.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lseek64 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lseek64 \- reposition 64-bit read/write file offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */" +.B #include <sys/types.h> +.B #include <unistd.h> +.P +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.fi +.SH DESCRIPTION +The +.BR lseek () +family of functions reposition the offset of the open file associated +with the file descriptor +.I fd +to +.I offset +bytes relative to the start, current position, or end of the file, +when +.I whence +has the value +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +.P +For more details, return value, and errors, see +.BR lseek (2). +.P +Four interfaces are available: +.BR lseek (), +.BR lseek64 (), +.BR llseek (), +and +.BR _llseek (). +.\" +.\" For some background details, see: +.\" https://lore.kernel.org/linux-man/CAKgNAkhNSWR3uYhYYaxx74fZfJ3JrpfAAPVrK0AFk_cAOUsbDg@mail.gmail.com/ +.\" +.SS lseek() +Prototype: +.P +.in +4n +.EX +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.EE +.in +.P +The C library's +.BR lseek () +wrapper function uses the type +.IR off_t . +This is a 32-bit signed type on 32-bit architectures, unless one +compiles with +.P +.in +4n +.EX +#define _FILE_OFFSET_BITS 64 +.EE +.in +.P +in which case it is a 64-bit signed type. +.SS lseek64() +Prototype: +.P +.in +4n +.EX +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.EE +.in +.P +The +.BR lseek64 () +library function uses a 64-bit type even when +.I off_t +is a 32-bit type. +Its prototype (and the type +.IR off64_t ) +is available only when one compiles with +.P +.in +4n +.EX +#define _LARGEFILE64_SOURCE +.EE +.in +.P +The function +.BR lseek64 () +.\" in glibc 2.0.94, not in glibc 2.0.6 +is available since glibc 2.1. +.\" +.SS llseek() +Prototype: +.P +.in +4n +.EX +.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence ); +.EE +.in +.P +The type +.I loff_t +is a 64-bit signed type. +The +.BR llseek () +library function is available in glibc and works without special defines. +However, the glibc headers do not provide a prototype. +Users should add +the above prototype, or something equivalent, to their own source. +When users complained about data loss caused by a miscompilation of +.BR e2fsck (8), +glibc 2.1.3 added the link-time warning +.P +.in +4n +"the \`llseek\' function may be dangerous; use \`lseek64\' instead." +.in +.P +This makes this function unusable if one desires a warning-free +compilation. +.P +Since glibc 2.28, +.\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef +this function symbol is no longer available to newly linked applications. +.\" +.SS _llseek() +On 32-bit architectures, +this is the system call that is used (by the C library wrapper functions) +to implement all of the above functions. +The prototype is: +.P +.in +4n +.EX +.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo , +.BI " loff_t *" result ", int " whence ); +.EE +.in +.P +For more details, see +.BR llseek (2). +.P +64-bit systems don't need an +.BR _llseek () +system call. +Instead, they have an +.BR lseek (2) +system call that supports 64-bit file offsets. +.\" In arch/x86/entry/syscalls/syscall_32.tbl, +.\" we see the following line: +.\" +.\" 140 i386 _llseek sys_llseek +.\" +.\" This is essentially telling us that 'sys_llseek' (the name generated +.\" by SYSCALL_DEFINE5(llseek...)) is exposed to user-space as system call +.\" number 140, and that system call number will (IIUC) be exposed in +.\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek"). +.\" The "i386" is telling us that this happens in i386 (32-bit Intel). +.\" There is nothing equivalent on x86-64, because 64 bit systems don't +.\" need an _llseek system call. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lseek64 () +T} Thread safety MT-Safe +.TE +.SH NOTES +.BR lseek64 () +is one of the functions that was specified in the Large File Summit (LFS) +specification that was completed in 1996. +The purpose of the specification was to provide transitional support +that allowed applications on 32-bit systems to access +files whose size exceeds that which can be represented with a 32-bit +.I off_t +type. +As noted above, this symbol is exposed by header files if the +.B _LARGEFILE64_SOURCE +feature test macro is defined. +ALternatively, on a 32-bit system, the symbol +.I lseek +is aliased to +.I lseek64 +if the macro +.B _FILE_OFFSET_BITS +is defined with the value 64. +.SH SEE ALSO +.BR llseek (2), +.BR lseek (2) diff --git a/man/man3/lutimes.3 b/man/man3/lutimes.3 new file mode 100644 index 0000000..3145980 --- /dev/null +++ b/man/man3/lutimes.3 @@ -0,0 +1 @@ +.so man3/futimes.3 diff --git a/man/man3/major.3 b/man/man3/major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/makecontext.3 b/man/man3/makecontext.3 new file mode 100644 index 0000000..a478fd9 --- /dev/null +++ b/man/man3/makecontext.3 @@ -0,0 +1,236 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2006-08-02, mtk, Added example program +.\" +.TH makecontext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +makecontext, swapcontext \- manipulate user context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ucontext.h> +.P +.BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \ +", ...);" +.BI "int swapcontext(ucontext_t *restrict " oucp , +.BI " const ucontext_t *restrict " ucp ); +.fi +.SH DESCRIPTION +In a System V-like environment, one has the type +.I ucontext_t +(defined in +.I <ucontext.h> +and described in +.BR getcontext (3)) +and the four functions +.BR getcontext (3), +.BR setcontext (3), +.BR makecontext (), +and +.BR swapcontext () +that allow user-level context switching +between multiple threads of control within a process. +.P +The +.BR makecontext () +function modifies the context pointed to +by \fIucp\fP (which was obtained from a call to +.BR getcontext (3)). +Before invoking +.BR makecontext (), +the caller must allocate a new stack +for this context and assign its address to \fIucp\->uc_stack\fP, +and define a successor context and +assign its address to \fIucp\->uc_link\fP. +.P +When this context is later activated (using +.BR setcontext (3) +or +.BR swapcontext ()) +the function \fIfunc\fP is called, +and passed the series of integer +.RI ( int ) +arguments that follow +.IR argc ; +the caller must specify the number of these arguments in +.IR argc . +When this function returns, the successor context is activated. +If the successor context pointer is NULL, the thread exits. +.P +The +.BR swapcontext () +function saves the current context in +the structure pointed to by \fIoucp\fP, and then activates the +context pointed to by \fIucp\fP. +.SH RETURN VALUE +When successful, +.BR swapcontext () +does not return. +(But we may return later, in case \fIoucp\fP is +activated, in which case it looks like +.BR swapcontext () +returns 0.) +On error, +.BR swapcontext () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient stack space left. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR makecontext () +T} Thread safety T{ +.na +.nh +MT-Safe race:ucp +T} +T{ +.na +.nh +.BR swapcontext () +T} Thread safety T{ +.na +.nh +MT-Safe race:oucp race:ucp +T} +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1. +SUSv2, POSIX.1-2001. +Removed in POSIX.1-2008, +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The interpretation of \fIucp\->uc_stack\fP is just as in +.BR sigaltstack (2), +namely, this struct contains the start and length of a memory area +to be used as the stack, regardless of the direction of growth of +the stack. +Thus, it is not necessary for the user program to +worry about this direction. +.P +On architectures where +.I int +and pointer types are the same size +(e.g., x86-32, where both types are 32 bits), +you may be able to get away with passing pointers as arguments to +.BR makecontext () +following +.IR argc . +However, doing this is not guaranteed to be portable, +is undefined according to the standards, +and won't work on architectures where pointers are larger than +.IR int s. +Nevertheless, starting with glibc 2.8, glibc makes some changes to +.BR makecontext (), +to permit this on some 64-bit architectures (e.g., x86-64). +.SH EXAMPLES +The example program below demonstrates the use of +.BR getcontext (3), +.BR makecontext (), +and +.BR swapcontext (). +Running the program produces the following output: +.P +.in +4n +.EX +.RB "$" " ./a.out" +main: swapcontext(&uctx_main, &uctx_func2) +func2: started +func2: swapcontext(&uctx_func2, &uctx_func1) +func1: started +func1: swapcontext(&uctx_func1, &uctx_func2) +func2: returning +func1: returning +main: exiting +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (makecontext.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <ucontext.h> +\& +static ucontext_t uctx_main, uctx_func1, uctx_func2; +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void +func1(void) +{ + printf("%s: started\en", __func__); + printf("%s: swapcontext(&uctx_func1, &uctx_func2)\en", __func__); + if (swapcontext(&uctx_func1, &uctx_func2) == \-1) + handle_error("swapcontext"); + printf("%s: returning\en", __func__); +} +\& +static void +func2(void) +{ + printf("%s: started\en", __func__); + printf("%s: swapcontext(&uctx_func2, &uctx_func1)\en", __func__); + if (swapcontext(&uctx_func2, &uctx_func1) == \-1) + handle_error("swapcontext"); + printf("%s: returning\en", __func__); +} +\& +int +main(int argc, char *argv[]) +{ + char func1_stack[16384]; + char func2_stack[16384]; +\& + if (getcontext(&uctx_func1) == \-1) + handle_error("getcontext"); + uctx_func1.uc_stack.ss_sp = func1_stack; + uctx_func1.uc_stack.ss_size = sizeof(func1_stack); + uctx_func1.uc_link = &uctx_main; + makecontext(&uctx_func1, func1, 0); +\& + if (getcontext(&uctx_func2) == \-1) + handle_error("getcontext"); + uctx_func2.uc_stack.ss_sp = func2_stack; + uctx_func2.uc_stack.ss_size = sizeof(func2_stack); + /* Successor context is f1(), unless argc > 1 */ + uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1; + makecontext(&uctx_func2, func2, 0); +\& + printf("%s: swapcontext(&uctx_main, &uctx_func2)\en", __func__); + if (swapcontext(&uctx_main, &uctx_func2) == \-1) + handle_error("swapcontext"); +\& + printf("%s: exiting\en", __func__); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR getcontext (3), +.BR sigsetjmp (3) diff --git a/man/man3/makedev.3 b/man/man3/makedev.3 new file mode 100644 index 0000000..019ac09 --- /dev/null +++ b/man/man3/makedev.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH makedev 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +makedev, major, minor \- manage a device number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/sysmacros.h> +.P +.BI "dev_t makedev(unsigned int " maj ", unsigned int " min ); +.P +.BI "unsigned int major(dev_t " dev ); +.BI "unsigned int minor(dev_t " dev ); +.fi +.SH DESCRIPTION +A device ID consists of two parts: +a major ID, identifying the class of the device, +and a minor ID, identifying a specific instance of a device in that class. +A device ID is represented using the type +.IR dev_t . +.P +Given major and minor device IDs, +.BR makedev () +combines these to produce a device ID, returned as the function result. +This device ID can be given to +.BR mknod (2), +for example. +.P +The +.BR major () +and +.BR minor () +functions perform the converse task: given a device ID, +they return, respectively, the major and minor components. +These macros can be useful to, for example, +decompose the device IDs in the structure returned by +.BR stat (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR makedev (), +.BR major (), +.BR minor () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The BSDs expose the definitions for these macros via +.IR <sys/types.h> . +.SH STANDARDS +None. +.SH HISTORY +BSD, HP-UX, Solaris, AIX, Irix. +.\" The header location is inconsistent: +.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h. +.P +These interfaces are defined as macros. +Since glibc 2.3.3, +they have been aliases for three GNU-specific functions: +.BR gnu_dev_makedev (), +.BR gnu_dev_major (), +and +.BR gnu_dev_minor (). +The latter names are exported, but the traditional names are more portable. +.P +Depending on the version, +glibc also exposes definitions for these macros from +.I <sys/types.h> +if suitable feature test macros are defined. +However, this behavior was deprecated in glibc 2.25, +.\" glibc commit dbab6577c6684c62bd2521c1c29dc25c3cac966f +and since glibc 2.28, +.\" glibc commit e16deca62e16f645213dffd4ecd1153c37765f17 +.I <sys/types.h> +no longer provides these definitions. +.SH SEE ALSO +.BR mknod (2), +.BR stat (2) diff --git a/man/man3/mallinfo.3 b/man/man3/mallinfo.3 new file mode 100644 index 0000000..aa4b2cc --- /dev/null +++ b/man/man3/mallinfo.3 @@ -0,0 +1,338 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mallinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mallinfo, mallinfo2 \- obtain memory allocation information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.B struct mallinfo mallinfo(void); +.B struct mallinfo2 mallinfo2(void); +.fi +.SH DESCRIPTION +These functions return a copy of a structure containing information about +memory allocations performed by +.BR malloc (3) +and related functions. +The structure returned by each function contains the same fields. +However, the older function, +.BR mallinfo (), +is deprecated since the type used for the fields is too small (see BUGS). +.P +Note that not all allocations are visible to these functions; +see BUGS and consider using +.BR malloc_info (3) +instead. +.P +The +.I mallinfo2 +structure returned by +.BR mallinfo2 () +is defined as follows: +.P +.in +4n +.EX +struct mallinfo2 { + size_t arena; /* Non\-mmapped space allocated (bytes) */ + size_t ordblks; /* Number of free chunks */ + size_t smblks; /* Number of free fastbin blocks */ + size_t hblks; /* Number of mmapped regions */ + size_t hblkhd; /* Space allocated in mmapped regions + (bytes) */ + size_t usmblks; /* See below */ + size_t fsmblks; /* Space in freed fastbin blocks (bytes) */ + size_t uordblks; /* Total allocated space (bytes) */ + size_t fordblks; /* Total free space (bytes) */ + size_t keepcost; /* Top\-most, releasable space (bytes) */ +}; +.EE +.in +.P +The +.I mallinfo +structure returned by the deprecated +.BR mallinfo () +function is exactly the same, except that the fields are typed as +.IR int . +.P +The structure fields contain the following information: +.TP 10 +.I arena +The total amount of memory allocated by means other than +.BR mmap (2) +(i.e., memory allocated on the heap). +This figure includes both in-use blocks and blocks on the free list. +.TP +.I ordblks +The number of ordinary (i.e., non-fastbin) free blocks. +.TP +.I smblks +.\" the glibc info page wrongly says this field is unused +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 +The number of fastbin free blocks (see +.BR mallopt (3)). +.TP +.I hblks +The number of blocks currently allocated using +.BR mmap (2). +(See the discussion of +.B M_MMAP_THRESHOLD +in +.BR mallopt (3).) +.TP +.I hblkhd +The number of bytes in blocks currently allocated using +.BR mmap (2). +.TP +.I usmblks +This field is unused, and is always 0. +.\" It seems to have been zero since at least as far back as glibc 2.15 +Historically, it was the "highwater mark" for allocated space\[em]that is, +the maximum amount of space that was ever allocated (in bytes); +this field was maintained only in nonthreading environments. +.TP +.I fsmblks +.\" the glibc info page wrongly says this field is unused +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 +The total number of bytes in fastbin free blocks. +.TP +.I uordblks +The total number of bytes used by in-use allocations. +.TP +.I fordblks +The total number of bytes in free blocks. +.TP +.I keepcost +The total amount of releasable free space at the top +of the heap. +This is the maximum number of bytes that could ideally +(i.e., ignoring page alignment restrictions, and so on) be released by +.BR malloc_trim (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mallinfo (), +.BR mallinfo2 () +T} Thread safety T{ +.na +.nh +MT-Unsafe init const:mallopt +T} +.TE +.P +.BR mallinfo ()/ +.BR mallinfo2 () +would access some global internal objects. +If modify them with non-atomically, +may get inconsistent results. +The identifier +.I mallopt +in +.I const:mallopt +mean that +.BR mallopt () +would modify the global internal objects with atomics, that make sure +.BR mallinfo ()/ +.BR mallinfo2 () +is safe enough, others modify with non-atomically maybe not. +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR mallinfo () +glibc 2.0. +SVID. +.TP +.BR mallinfo2 () +.\" commit e3960d1c57e57f33e0e846d615788f4ede73b945 +glibc 2.33. +.SH BUGS +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208 +.\" See the 24 Aug 2011 mail by Paul Pluzhnikov: +.\" "[patch] Fix mallinfo() to accumulate results for all arenas" +.\" on libc-alpha@sourceware.org +.B Information is returned for only the main memory allocation area. +Allocations in other arenas are excluded. +See +.BR malloc_stats (3) +and +.BR malloc_info (3) +for alternatives that include information about other arenas. +.P +The fields of the +.I mallinfo +structure that is returned by the older +.BR mallinfo () +function are typed as +.IR int . +However, because some internal bookkeeping values may be of type +.IR long , +the reported values may wrap around zero and thus be inaccurate. +.SH EXAMPLES +The program below employs +.BR mallinfo2 () +to retrieve memory allocation statistics before and after +allocating and freeing some blocks of memory. +The statistics are displayed on standard output. +.P +The first two command-line arguments specify the number and size of +blocks to be allocated with +.BR malloc (3). +.P +The remaining three arguments specify which of the allocated blocks +should be freed with +.BR free (3). +These three arguments are optional, and specify (in order): +the step size to be used in the loop that frees blocks +(the default is 1, meaning free all blocks in the range); +the ordinal position of the first block to be freed +(default 0, meaning the first allocated block); +and a number one greater than the ordinal position +of the last block to be freed +(default is one greater than the maximum block number). +If these three arguments are omitted, +then the defaults cause all allocated blocks to be freed. +.P +In the following example run of the program, +1000 allocations of 100 bytes are performed, +and then every second allocated block is freed: +.P +.in +4n +.EX +$ \fB./a.out 1000 100 2\fP +============== Before allocating blocks ============== +Total non\-mmapped bytes (arena): 0 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 0 +Total free space (fordblks): 0 +Topmost releasable block (keepcost): 0 +\& +============== After allocating blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 104000 +Total free space (fordblks): 31168 +Topmost releasable block (keepcost): 31168 +\& +============== After freeing blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 501 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 52000 +Total free space (fordblks): 83168 +Topmost releasable block (keepcost): 31168 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mallinfo.c) +.EX +#include <malloc.h> +#include <stdlib.h> +#include <string.h> +\& +static void +display_mallinfo2(void) +{ + struct mallinfo2 mi; +\& + mi = mallinfo2(); +\& + printf("Total non\-mmapped bytes (arena): %zu\en", mi.arena); + printf("# of free chunks (ordblks): %zu\en", mi.ordblks); + printf("# of free fastbin blocks (smblks): %zu\en", mi.smblks); + printf("# of mapped regions (hblks): %zu\en", mi.hblks); + printf("Bytes in mapped regions (hblkhd): %zu\en", mi.hblkhd); + printf("Max. total allocated space (usmblks): %zu\en", mi.usmblks); + printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks); + printf("Total allocated space (uordblks): %zu\en", mi.uordblks); + printf("Total free space (fordblks): %zu\en", mi.fordblks); + printf("Topmost releasable block (keepcost): %zu\en", mi.keepcost); +} +\& +int +main(int argc, char *argv[]) +{ +#define MAX_ALLOCS 2000000 + char *alloc[MAX_ALLOCS]; + size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep; +\& + if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s num\-blocks block\-size [free\-step " + "[start\-free [end\-free]]]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + numBlocks = atoi(argv[1]); + blockSize = atoi(argv[2]); + freeStep = (argc > 3) ? atoi(argv[3]) : 1; + freeBegin = (argc > 4) ? atoi(argv[4]) : 0; + freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks; +\& + printf("============== Before allocating blocks ==============\en"); + display_mallinfo2(); +\& + for (size_t j = 0; j < numBlocks; j++) { + if (numBlocks >= MAX_ALLOCS) { + fprintf(stderr, "Too many allocations\en"); + exit(EXIT_FAILURE); + } +\& + alloc[j] = malloc(blockSize); + if (alloc[j] == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + } +\& + printf("\en============== After allocating blocks ==============\en"); + display_mallinfo2(); +\& + for (size_t j = freeBegin; j < freeEnd; j += freeStep) + free(alloc[j]); +\& + printf("\en============== After freeing blocks ==============\en"); + display_mallinfo2(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR malloc (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mallopt (3) diff --git a/man/man3/mallinfo2.3 b/man/man3/mallinfo2.3 new file mode 100644 index 0000000..25caee7 --- /dev/null +++ b/man/man3/mallinfo2.3 @@ -0,0 +1 @@ +.so man3/mallinfo.3 diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 0000000..5edae40 --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,460 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) +.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 +.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) +.\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). +.\" +.\" FIXME . Review http://austingroupbugs.net/view.php?id=374 +.\" to see what changes are required on this page. +.\" +.TH malloc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "void *malloc(size_t " size ); +.BI "void free(void *_Nullable " ptr ); +.BI "void *calloc(size_t " nmemb ", size_t " size ); +.BI "void *realloc(void *_Nullable " ptr ", size_t " size ); +.BI "void *reallocarray(void *_Nullable " ptr ", size_t " nmemb ", size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR reallocarray (): +.nf + Since glibc 2.29: + _DEFAULT_SOURCE + glibc 2.28 and earlier: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.SS malloc() +The +.BR malloc () +function allocates +.I size +bytes and returns a pointer to the allocated memory. +.IR "The memory is not initialized" . +If +.I size +is 0, then +.BR malloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +(See "Nonportable behavior" for portability issues.) +.SS free() +The +.BR free () +function frees the memory space pointed to by +.IR ptr , +which must have been returned by a previous call to +.BR malloc () +or related functions. +Otherwise, or if +.I ptr +has already been freed, undefined behavior occurs. +If +.I ptr +is NULL, no operation is performed. +.SS calloc() +The +.BR calloc () +function allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +If +.I nmemb +or +.I size +is 0, then +.BR calloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +.P +If the multiplication of +.I nmemb +and +.I size +would result in integer overflow, then +.BR calloc () +returns an error. +By contrast, +an integer overflow would not be detected in the following call to +.BR malloc (), +with the result that an incorrectly sized block of memory would be allocated: +.P +.in +4n +.EX +malloc(nmemb * size); +.EE +.in +.SS realloc() +The +.BR realloc () +function changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents of the memory +will be unchanged in the range from the start of the region +up to the minimum of the old and new sizes. +If the new size is larger than the old size, the added memory will +.I not +be initialized. +.P +If +.I ptr +is NULL, then the call is equivalent to +.IR malloc(size) , +for all values of +.IR size . +.P +If +.I size +is equal to zero, +and +.I ptr +is not NULL, then the call is equivalent to +.I free(ptr) +(but see "Nonportable behavior" for portability issues). +.P +Unless +.I ptr +is NULL, it must have been returned by an earlier call to +.B malloc +or related functions. +If the area pointed to was moved, a +.I free(ptr) +is done. +.SS reallocarray() +The +.BR reallocarray () +function changes the size of (and possibly moves) +the memory block pointed to by +.I ptr +to be large enough for an array of +.I nmemb +elements, each of which is +.I size +bytes. +It is equivalent to the call +.P +.in +4n +.EX +realloc(ptr, nmemb * size); +.EE +.in +.P +However, unlike that +.BR realloc () +call, +.BR reallocarray () +fails safely in the case where the multiplication would overflow. +If such an overflow occurs, +.BR reallocarray () +returns an error. +.SH RETURN VALUE +The +.BR malloc (), +.BR calloc (), +.BR realloc (), +and +.BR reallocarray () +functions return a pointer to the allocated memory, +which is suitably aligned for any type that fits into +the requested size or less. +On error, these functions return NULL and set +.IR errno . +Attempting to allocate more than +.B PTRDIFF_MAX +bytes is considered an error, as an object that large +could cause later pointer subtraction to overflow. +.P +The +.BR free () +function returns no value, and preserves +.IR errno . +.P +The +.BR realloc () +and +.BR reallocarray () +functions return NULL if +.I ptr +is not NULL and the requested size is zero; +this is not considered an error. +(See "Nonportable behavior" for portability issues.) +Otherwise, the returned pointer may be the same as +.I ptr +if the allocation was not moved +(e.g., there was room to expand the allocation in-place), or different from +.I ptr +if the allocation was moved to a new address. +If these functions fail, +the original block is left untouched; it is not freed or moved. +.SH ERRORS +.BR calloc (), +.BR malloc (), +.BR realloc (), +and +.BR reallocarray () +can fail with the following error: +.TP +.B ENOMEM +Out of memory. +Possibly, the application hit the +.B RLIMIT_AS +or +.B RLIMIT_DATA +limit described in +.BR getrlimit (2). +Another reason could be that +the number of mappings created by the caller process +exceeded the limit specified by +.IR /proc/sys/vm/max_map_count . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc (), +.BR free (), +.BR calloc (), +.BR realloc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +C11, POSIX.1-2008. +.TP +.BR reallocarray () +None. +.SH HISTORY +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +POSIX.1-2001, C89. +.TP +.BR reallocarray () +glibc 2.26. +OpenBSD 5.6, FreeBSD 11.0. +.P +.BR malloc () +and related functions rejected sizes greater than +.B PTRDIFF_MAX +starting in glibc 2.30. +.P +.BR free () +preserved +.I errno +starting in glibc 2.33. +.SH NOTES +By default, Linux follows an optimistic memory allocation strategy. +This means that when +.BR malloc () +returns non-NULL there is no guarantee that the memory really +is available. +In case it turns out that the system is out of memory, +one or more processes will be killed by the OOM killer. +For more information, see the description of +.I /proc/sys/vm/overcommit_memory +and +.I /proc/sys/vm/oom_adj +in +.BR proc (5), +and the Linux kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.P +Normally, +.BR malloc () +allocates memory from the heap, and adjusts the size of the heap +as required, using +.BR sbrk (2). +When allocating blocks of memory larger than +.B MMAP_THRESHOLD +bytes, the glibc +.BR malloc () +implementation allocates the memory as a private anonymous mapping using +.BR mmap (2). +.B MMAP_THRESHOLD +is 128\ kB by default, but is adjustable using +.BR mallopt (3). +Prior to Linux 4.7 +allocations performed using +.BR mmap (2) +were unaffected by the +.B RLIMIT_DATA +resource limit; +since Linux 4.7, this limit is also enforced for allocations performed using +.BR mmap (2). +.P +To avoid corruption in multithreaded applications, +mutexes are used internally to protect the memory-management +data structures employed by these functions. +In a multithreaded application in which threads simultaneously +allocate and free memory, +there could be contention for these mutexes. +To scalably handle memory allocation in multithreaded applications, +glibc creates additional +.I memory allocation arenas +if mutex contention is detected. +Each arena is a large region of memory that is internally allocated +by the system +(using +.BR brk (2) +or +.BR mmap (2)), +and managed with its own mutexes. +.P +If your program uses a private memory allocator, +it should do so by replacing +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +The replacement functions must implement the documented glibc behaviors, +including +.I errno +handling, size-zero allocations, and overflow checking; +otherwise, other library routines may crash or operate incorrectly. +For example, if the replacement +.IR free () +does not preserve +.IR errno , +then seemingly unrelated library routines may +fail without having a valid reason in +.IR errno . +Private memory allocators may also need to replace other glibc functions; +see "Replacing malloc" in the glibc manual for details. +.P +Crashes in memory allocators +are almost always related to heap corruption, such as overflowing +an allocated chunk or freeing the same pointer twice. +.P +The +.BR malloc () +implementation is tunable via environment variables; see +.BR mallopt (3) +for details. +.SS Nonportable behavior +The behavior of +these functions when the requested size is zero +is glibc specific; +other implementations may return NULL without setting +.IR errno , +and portable POSIX programs should tolerate such behavior. +See +.BR realloc (3p). +.P +POSIX requires memory allocators +to set +.I errno +upon failure. +However, the C standard does not require this, and applications +portable to non-POSIX platforms should not assume this. +.P +Portable programs should not use private memory allocators, +as POSIX and the C standard do not allow replacement of +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +.SH EXAMPLES +.EX +#include <err.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type))) +#define MALLOC(type) MALLOCARRAY(1, type) +\& +static inline void *my_mallocarray(size_t nmemb, size_t size); +\& +int +main(void) +{ + char *p; +\& + p = MALLOCARRAY(32, char); + if (p == NULL) + err(EXIT_FAILURE, "malloc"); +\& + strlcpy(p, "foo", 32); + puts(p); +} +\& +static inline void * +my_mallocarray(size_t nmemb, size_t size) +{ + return reallocarray(NULL, nmemb, size); +} +.EE +.SH SEE ALSO +.\" http://g.oswego.edu/dl/html/malloc.html +.\" A Memory Allocator - by Doug Lea +.\" +.\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html +.\" Linux Heap, Contention in free() - David Boreham +.\" +.\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html +.\" malloc() Performance in a Multithreaded Linux Environment - +.\" Check Lever, David Boreham +.\" +.ad l +.nh +.BR valgrind (1), +.BR brk (2), +.BR mmap (2), +.BR alloca (3), +.BR malloc_get_state (3), +.BR malloc_info (3), +.BR malloc_trim (3), +.BR malloc_usable_size (3), +.BR mallopt (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) +.P +For details of the GNU C library implementation, see +.UR https://sourceware.org/glibc/wiki/MallocInternals +.UE . diff --git a/man/man3/malloc_get_state.3 b/man/man3/malloc_get_state.3 new file mode 100644 index 0000000..8a24f85 --- /dev/null +++ b/man/man3/malloc_get_state.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_get_state 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_get_state, malloc_set_state \- +record and restore state of malloc implementation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.B void *malloc_get_state(void); +.BI "int malloc_set_state(void *" state ); +.fi +.SH DESCRIPTION +.IR Note : +these functions are removed in glibc 2.25. +.P +The +.BR malloc_get_state () +function records the current state of all +.BR malloc (3) +internal bookkeeping variables +(but not the actual contents of the heap +or the state of +.BR malloc_hook (3) +functions pointers). +The state is recorded in a system-dependent opaque data structure +dynamically allocated via +.BR malloc (3), +and a pointer to that data structure is returned as the function result. +(It is the caller's responsibility to +.BR free (3) +this memory.) +.P +The +.BR malloc_set_state () +function restores the state of all +.BR malloc (3) +internal bookkeeping variables to the values recorded in +the opaque data structure pointed to by +.IR state . +.SH RETURN VALUE +On success, +.BR malloc_get_state () +returns a pointer to a newly allocated opaque data structure. +On error (for example, memory could not be allocated for the data structure), +.BR malloc_get_state () +returns NULL. +.P +On success, +.BR malloc_set_state () +returns 0. +If the implementation detects that +.I state +does not point to a correctly formed data structure, +.\" if(ms->magic != MALLOC_STATE_MAGIC) return -1; +.BR malloc_set_state () +returns \-1. +If the implementation detects that +the version of the data structure referred to by +.I state +is a more recent version than this implementation knows about, +.\" /* Must fail if the major version is too high. */ +.\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2; +.BR malloc_set_state () +returns \-2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_get_state (), +.BR malloc_set_state () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +These functions are useful when using this +.BR malloc (3) +implementation as part of a shared library, +and the heap contents are saved/restored via some other method. +This technique is used by GNU Emacs to implement its "dumping" function. +.P +Hook function pointers are never saved or restored by these +functions, with two exceptions: +if malloc checking (see +.BR mallopt (3)) +was in use when +.BR malloc_get_state () +was called, then +.BR malloc_set_state () +resets malloc checking hooks +.\" i.e., calls __malloc_check_init() +if possible; +.\" i.e., malloc checking is not already in use +.\" and the caller requested malloc checking +if malloc checking was not in use in the recorded state, +but the caller has requested malloc checking, +then the hooks are reset to 0. +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3) diff --git a/man/man3/malloc_hook.3 b/man/man3/malloc_hook.3 new file mode 100644 index 0000000..5b10cfd --- /dev/null +++ b/man/man3/malloc_hook.3 @@ -0,0 +1,154 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Heavily based on glibc documentation +.\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb +.\" +.TH __malloc_hook 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__malloc_hook, __malloc_initialize_hook, +__memalign_hook, __free_hook, __realloc_hook, +__after_morecore_hook \- malloc debugging variables (DEPRECATED) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <malloc.h>" +.P +.BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller ); +.P +.BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size , +.BI " const void *" caller ); +.P +.BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size , +.BI " const void *" caller ); +.P +.BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller ); +.P +.B "void (*__malloc_initialize_hook)(void);" +.P +.B "void (*volatile __after_morecore_hook)(void);" +.fi +.SH DESCRIPTION +The GNU C library lets you modify the behavior of +.BR malloc (3), +.BR realloc (3), +and +.BR free (3) +by specifying appropriate hook functions. +You can use these hooks +to help you debug programs that use dynamic memory allocation, +for example. +.P +The variable +.B __malloc_initialize_hook +points at a function that is called once when the malloc implementation +is initialized. +This is a weak variable, so it can be overridden in +the application with a definition like the following: +.P +.in +4n +.EX +void (*__malloc_initialize_hook)(void) = my_init_hook; +.EE +.in +.P +Now the function +.IR my_init_hook () +can do the initialization of all hooks. +.P +The four functions pointed to by +.BR __malloc_hook , +.BR __realloc_hook , +.BR __memalign_hook , +.B __free_hook +have a prototype like the functions +.BR malloc (3), +.BR realloc (3), +.BR memalign (3), +.BR free (3), +respectively, except that they have a final argument +.I caller +that gives the address of the caller of +.BR malloc (3), +etc. +.P +The variable +.B __after_morecore_hook +points at a function that is called each time after +.BR sbrk (2) +was asked for more memory. +.SH STANDARDS +GNU. +.SH NOTES +The use of these hook functions is not safe in multithreaded programs, +and they are now deprecated. +From glibc 2.24 onwards, the +.B __malloc_initialize_hook +variable has been removed from the API, +and from glibc 2.34 onwards, all +the hook variables have been removed from the API. +.\" https://bugzilla.redhat.com/show_bug.cgi?id=450187 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957 +Programmers should instead preempt calls to the relevant functions +by defining and exporting +.BR malloc (), +.BR free (), +.BR realloc (), +and +.BR calloc (). +.SH EXAMPLES +Here is a short example of how to use these variables. +.P +.EX +#include <stdio.h> +#include <malloc.h> +\& +/* Prototypes for our hooks */ +static void my_init_hook(void); +static void *my_malloc_hook(size_t, const void *); +\& +/* Variables to save original hooks */ +static void *(*old_malloc_hook)(size_t, const void *); +\& +/* Override initializing hook from the C library */ +void (*__malloc_initialize_hook)(void) = my_init_hook; +\& +static void +my_init_hook(void) +{ + old_malloc_hook = __malloc_hook; + __malloc_hook = my_malloc_hook; +} +\& +static void * +my_malloc_hook(size_t size, const void *caller) +{ + void *result; +\& + /* Restore all old hooks */ + __malloc_hook = old_malloc_hook; +\& + /* Call recursively */ + result = malloc(size); +\& + /* Save underlying hooks */ + old_malloc_hook = __malloc_hook; +\& + /* printf() might call malloc(), so protect it too */ + printf("malloc(%zu) called from %p returns %p\en", + size, caller, result); +\& + /* Restore our own hooks */ + __malloc_hook = my_malloc_hook; +\& + return result; +} +.EE +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR mcheck (3), +.BR mtrace (3) diff --git a/man/man3/malloc_info.3 b/man/man3/malloc_info.3 new file mode 100644 index 0000000..086b3b2 --- /dev/null +++ b/man/man3/malloc_info.3 @@ -0,0 +1,257 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_info 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_info \- export malloc state to a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.BI "int malloc_info(int " options ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR malloc_info () +function exports an XML string that describes the current state +of the memory-allocation +implementation in the caller. +The string is printed on the file stream +.IR stream . +The exported string includes information about all arenas (see +.BR malloc (3)). +.P +As currently implemented, +.I options +must be zero. +.SH RETURN VALUE +On success, +.BR malloc_info () +returns 0. +On failure, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I options +was nonzero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_info () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.10. +.SH NOTES +The memory-allocation information is provided as an XML string +(rather than a C structure) +because the information may change over time +(according to changes in the underlying implementation). +The output XML string includes a version field. +.P +The +.BR open_memstream (3) +function can be used to send the output of +.BR malloc_info () +directly into a buffer in memory, rather than to a file. +.P +The +.BR malloc_info () +function is designed to address deficiencies in +.BR malloc_stats (3) +and +.BR mallinfo (3). +.SH EXAMPLES +The program below takes up to four command-line arguments, +of which the first three are mandatory. +The first argument specifies the number of threads that +the program should create. +All of the threads, including the main thread, +allocate the number of blocks of memory specified by the second argument. +The third argument controls the size of the blocks to be allocated. +The main thread creates blocks of this size, +the second thread created by the program allocates blocks of twice this size, +the third thread allocates blocks of three times this size, and so on. +.P +The program calls +.BR malloc_info () +twice to display the memory-allocation state. +The first call takes place before any threads +are created or memory allocated. +The second call is performed after all threads have allocated memory. +.P +In the following example, +the command-line arguments specify the creation of one additional thread, +and both the main thread and the additional thread +allocate 10000 blocks of memory. +After the blocks of memory have been allocated, +.BR malloc_info () +shows the state of two allocation arenas. +.P +.in +4n +.EX +.RB "$ " "getconf GNU_LIBC_VERSION" +glibc 2.13 +.RB "$ " "./a.out 1 10000 100" +============ Before allocating blocks ============ +<malloc version="1"> +<heap nr="0"> +<sizes> +</sizes> +<total type="fast" count="0" size="0"/> +<total type="rest" count="0" size="0"/> +<system type="current" size="135168"/> +<system type="max" size="135168"/> +<aspace type="total" size="135168"/> +<aspace type="mprotect" size="135168"/> +</heap> +<total type="fast" count="0" size="0"/> +<total type="rest" count="0" size="0"/> +<system type="current" size="135168"/> +<system type="max" size="135168"/> +<aspace type="total" size="135168"/> +<aspace type="mprotect" size="135168"/> +</malloc> +\& +============ After allocating blocks ============ +<malloc version="1"> +<heap nr="0"> +<sizes> +</sizes> +<total type="fast" count="0" size="0"/> +<total type="rest" count="0" size="0"/> +<system type="current" size="1081344"/> +<system type="max" size="1081344"/> +<aspace type="total" size="1081344"/> +<aspace type="mprotect" size="1081344"/> +</heap> +<heap nr="1"> +<sizes> +</sizes> +<total type="fast" count="0" size="0"/> +<total type="rest" count="0" size="0"/> +<system type="current" size="1032192"/> +<system type="max" size="1032192"/> +<aspace type="total" size="1032192"/> +<aspace type="mprotect" size="1032192"/> +</heap> +<total type="fast" count="0" size="0"/> +<total type="rest" count="0" size="0"/> +<system type="current" size="2113536"/> +<system type="max" size="2113536"/> +<aspace type="total" size="2113536"/> +<aspace type="mprotect" size="2113536"/> +</malloc> +.EE +.in +.SS Program source +.\" SRC BEGIN (malloc_info.c) +.EX +#include <err.h> +#include <errno.h> +#include <malloc.h> +#include <pthread.h> +#include <stdlib.h> +#include <unistd.h> +\& +static size_t blockSize; +static size_t numThreads; +static unsigned int numBlocks; +\& +static void * +thread_func(void *arg) +{ + int tn = (int) arg; +\& + /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including + the main thread) allocates a different amount of memory. */ +\& + for (unsigned int j = 0; j < numBlocks; j++) + if (malloc(blockSize * (2 + tn)) == NULL) + err(EXIT_FAILURE, "malloc\-thread"); +\& + sleep(100); /* Sleep until main thread terminates. */ + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + int sleepTime; + pthread_t *thr; +\& + if (argc < 4) { + fprintf(stderr, + "%s num\-threads num\-blocks block\-size [sleep\-time]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + numThreads = atoi(argv[1]); + numBlocks = atoi(argv[2]); + blockSize = atoi(argv[3]); + sleepTime = (argc > 4) ? atoi(argv[4]) : 0; +\& + thr = calloc(numThreads, sizeof(*thr)); + if (thr == NULL) + err(EXIT_FAILURE, "calloc"); +\& + printf("============ Before allocating blocks ============\en"); + malloc_info(0, stdout); +\& + /* Create threads that allocate different amounts of memory. */ +\& + for (size_t tn = 0; tn < numThreads; tn++) { + errno = pthread_create(&thr[tn], NULL, thread_func, + (void *) tn); + if (errno != 0) + err(EXIT_FAILURE, "pthread_create"); +\& + /* If we add a sleep interval after the start\-up of each + thread, the threads likely won\[aq]t contend for malloc + mutexes, and therefore additional arenas won\[aq]t be + allocated (see malloc(3)). */ +\& + if (sleepTime > 0) + sleep(sleepTime); + } +\& + /* The main thread also allocates some memory. */ +\& + for (unsigned int j = 0; j < numBlocks; j++) + if (malloc(blockSize) == NULL) + err(EXIT_FAILURE, "malloc"); +\& + sleep(2); /* Give all threads a chance to + complete allocations. */ +\& + printf("\en============ After allocating blocks ============\en"); + malloc_info(0, stdout); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_stats (3), +.BR mallopt (3), +.BR open_memstream (3) diff --git a/man/man3/malloc_set_state.3 b/man/man3/malloc_set_state.3 new file mode 100644 index 0000000..ff16dd7 --- /dev/null +++ b/man/man3/malloc_set_state.3 @@ -0,0 +1 @@ +.so man3/malloc_get_state.3 diff --git a/man/man3/malloc_stats.3 b/man/man3/malloc_stats.3 new file mode 100644 index 0000000..30df458 --- /dev/null +++ b/man/man3/malloc_stats.3 @@ -0,0 +1,65 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_stats 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_stats \- print memory allocation statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.B void malloc_stats(void); +.fi +.SH DESCRIPTION +The +.BR malloc_stats () +function prints (on standard error) statistics about memory allocated by +.BR malloc (3) +and related functions. +For each arena (allocation area), this function prints +the total amount of memory allocated +and the total number of bytes consumed by in-use allocations. +(These two values correspond to the +.I arena +and +.I uordblks +fields retrieved by +.BR mallinfo (3).) +In addition, +the function prints the sum of these two statistics for all arenas, +and the maximum number of blocks and bytes that were ever simultaneously +allocated using +.BR mmap (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_stats () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.0. +.SH NOTES +More detailed information about memory allocations in the main arena +can be obtained using +.BR mallinfo (3). +.SH SEE ALSO +.BR mmap (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_info (3), +.BR mallopt (3) diff --git a/man/man3/malloc_trim.3 b/man/man3/malloc_trim.3 new file mode 100644 index 0000000..4049b24 --- /dev/null +++ b/man/man3/malloc_trim.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_trim 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_trim \- release free memory from the heap +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.BI "int malloc_trim(size_t " pad ); +.fi +.SH DESCRIPTION +The +.BR malloc_trim () +function attempts to release free memory from the heap +(by calling +.BR sbrk (2) +or +.BR madvise (2) +with suitable arguments). +.P +The +.I pad +argument specifies the amount of free space to leave untrimmed +at the top of the heap. +If this argument is 0, only the minimum amount of memory is maintained +at the top of the heap (i.e., one page or less). +A nonzero argument can be used to maintain some trailing space +at the top of the heap in order to allow future allocations +to be made without having to extend the heap with +.BR sbrk (2). +.SH RETURN VALUE +The +.BR malloc_trim () +function returns 1 if memory was actually released back to the system, +or 0 if it was not possible to release any memory. +.SH ERRORS +No errors are defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_trim () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH VERSIONS +glibc 2.0. +.SH NOTES +Only the main heap (using +.BR sbrk (2)) +honors the +.I pad +argument; thread heaps do not. +.P +Since glibc 2.8 this function frees memory in all arenas and in all +chunks with whole free pages. +.\" See commit 68631c8eb92ff38d9da1ae34f6aa048539b199cc +.\" (dated 2007-12-16) which adds iteration over all +.\" arenas and frees all pages in chunks which are free. +.P +Before glibc 2.8 this function only freed memory at the +top of the heap in the main arena. +.SH SEE ALSO +.BR sbrk (2), +.BR malloc (3), +.BR mallopt (3) diff --git a/man/man3/malloc_usable_size.3 b/man/man3/malloc_usable_size.3 new file mode 100644 index 0000000..c0aa6b8 --- /dev/null +++ b/man/man3/malloc_usable_size.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_usable_size 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_usable_size \- obtain size of block of memory allocated from heap +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.BI "size_t malloc_usable_size(void *_Nullable " ptr ); +.fi +.SH DESCRIPTION +This function can be used for +diagnostics or statistics about allocations from +.BR malloc (3) +or a related function. +.SH RETURN VALUE +.BR malloc_usable_size () +returns a value no less than +the size of the block of allocated memory pointed to by +.IR ptr . +If +.I ptr +is NULL, 0 is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_usable_size () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH CAVEATS +The value returned by +.BR malloc_usable_size () +may be greater than the requested size of the allocation +because of various internal implementation details, +none of which the programmer should rely on. +This function is intended to only be used +for diagnostics and statistics; +writing to the excess memory without first calling +.BR realloc (3) +to resize the allocation is not supported. +The returned value is only valid at the time of the call. +.SH SEE ALSO +.BR malloc (3) diff --git a/man/man3/mallopt.3 b/man/man3/mallopt.3 new file mode 100644 index 0000000..d684eb1 --- /dev/null +++ b/man/man3/mallopt.3 @@ -0,0 +1,619 @@ +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mallopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mallopt \- set memory allocation parameters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <malloc.h> +.P +.BI "int mallopt(int " param ", int " value ); +.fi +.SH DESCRIPTION +The +.BR mallopt () +function adjusts parameters that control the behavior of the +memory-allocation functions (see +.BR malloc (3)). +The +.I param +argument specifies the parameter to be modified, and +.I value +specifies the new value for that parameter. +.P +The following values can be specified for +.IR param : +.TP +.B M_ARENA_MAX +If this parameter has a nonzero value, +it defines a hard limit on the maximum number of arenas that can be created. +An arena represents a pool of memory that can be used by +.BR malloc (3) +(and similar) calls to service allocation requests. +Arenas are thread safe and +therefore may have multiple concurrent memory requests. +The trade-off is between the number of threads and the number of arenas. +The more arenas you have, the lower the per-thread contention, +but the higher the memory usage. +.IP +The default value of this parameter is 0, +meaning that the limit on the number of arenas is determined +according to the setting of +.BR M_ARENA_TEST . +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +In some versions of the allocator there was no limit on the number +of created arenas (e.g., CentOS 5, RHEL 5). +.IP +When employing newer glibc versions, applications may in +some cases exhibit high contention when accessing arenas. +In these cases, it may be beneficial to increase +.B M_ARENA_MAX +to match the number of threads. +This is similar in behavior to strategies taken by tcmalloc and jemalloc +(e.g., per-thread allocation pools). +.TP +.B M_ARENA_TEST +This parameter specifies a value, in number of arenas created, +at which point the system configuration will be examined +to determine a hard limit on the number of created arenas. +(See +.B M_ARENA_MAX +for the definition of an arena.) +.IP +The computation of the arena hard limit is implementation-defined +and is usually calculated as a multiple of the number of available CPUs. +Once the hard limit is computed, the result is final and constrains +the total number of arenas. +.IP +The default value for the +.B M_ARENA_TEST +parameter is 2 on systems where +.I sizeof(long) +is 4; otherwise the default value is 8. +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +.IP +The value of +.B M_ARENA_TEST +is not used when +.B M_ARENA_MAX +has a nonzero value. +.TP +.B M_CHECK_ACTION +Setting this parameter controls how glibc responds when various kinds +of programming errors are detected (e.g., freeing the same pointer twice). +The 3 least significant bits (2, 1, and 0) of the value assigned +to this parameter determine the glibc behavior, as follows: +.RS +.TP +Bit 0 +If this bit is set, then print a one-line message on +.I stderr +that provides details about the error. +The message starts with the string "***\ glibc detected\ ***", +followed by the program name, +the name of the memory-allocation function in which the error was detected, +a brief description of the error, +and the memory address where the error was detected. +.TP +Bit 1 +If this bit is set, then, +after printing any error message specified by bit 0, +the program is terminated by calling +.BR abort (3). +Since glibc 2.4, +if bit 0 is also set, +then, between printing the error message and aborting, +the program also prints a stack trace in the manner of +.BR backtrace (3), +and prints the process's memory mapping in the style of +.IR /proc/ pid /maps +(see +.BR proc (5)). +.TP +Bit 2 (since glibc 2.4) +This bit has an effect only if bit 0 is also set. +If this bit is set, +then the one-line message describing the error is simplified +to contain just the name of the function where the error +was detected and the brief description of the error. +.RE +.IP +The remaining bits in +.I value +are ignored. +.IP +Combining the above details, +the following numeric values are meaningful for +.BR M_CHECK_ACTION : +.RS 12 +.TP +.B 0 +Ignore error conditions; continue execution (with undefined results). +.TP +.B 1 +Print a detailed error message and continue execution. +.TP +.B 2 +Abort the program. +.TP +.B 3 +Print detailed error message, stack trace, and memory mappings, +and abort the program. +.TP +.B 5 +Print a simple error message and continue execution. +.TP +.B 7 +Print simple error message, stack trace, and memory mappings, +and abort the program. +.RE +.IP +Since glibc 2.3.4, the default value for the +.B M_CHECK_ACTION +parameter is 3. +In glibc 2.3.3 and earlier, the default value is 1. +.IP +Using a nonzero +.B M_CHECK_ACTION +value can be useful because otherwise a crash may happen much later, +and the true cause of the problem is then very hard to track down. +.TP +.B M_MMAP_MAX +.\" The following text adapted from comments in the glibc source: +This parameter specifies the maximum number of allocation requests that +may be simultaneously serviced using +.BR mmap (2). +This parameter exists because some systems have a limited number +of internal tables for use by +.BR mmap (2), +and using more than a few of them may degrade performance. +.IP +The default value is 65,536, +a value which has no special significance and +which serves only as a safeguard. +Setting this parameter to 0 disables the use of +.BR mmap (2) +for servicing large allocation requests. +.TP +.B M_MMAP_THRESHOLD +For allocations greater than or equal to the limit specified (in bytes) by +.B M_MMAP_THRESHOLD +that can't be satisfied from the free list, +the memory-allocation functions employ +.BR mmap (2) +instead of increasing the program break using +.BR sbrk (2). +.IP +Allocating memory using +.BR mmap (2) +has the significant advantage that the allocated memory blocks +can always be independently released back to the system. +(By contrast, +the heap can be trimmed only if memory is freed at the top end.) +On the other hand, there are some disadvantages to the use of +.BR mmap (2): +deallocated space is not placed on the free list +for reuse by later allocations; +memory may be wasted because +.BR mmap (2) +allocations must be page-aligned; +and the kernel must perform the expensive task of zeroing out +memory allocated via +.BR mmap (2). +Balancing these factors leads to a default setting of 128*1024 for the +.B M_MMAP_THRESHOLD +parameter. +.IP +The lower limit for this parameter is 0. +The upper limit is +.BR DEFAULT_MMAP_THRESHOLD_MAX : +512*1024 on 32-bit systems or +.I 4*1024*1024*sizeof(long) +on 64-bit systems. +.IP +.IR Note : +Nowadays, glibc uses a dynamic mmap threshold by default. +The initial value of the threshold is 128*1024, +but when blocks larger than the current threshold and less than or equal to +.B DEFAULT_MMAP_THRESHOLD_MAX +are freed, +the threshold is adjusted upward to the size of the freed block. +When dynamic mmap thresholding is in effect, +the threshold for trimming the heap is also dynamically adjusted +to be twice the dynamic mmap threshold. +Dynamic adjustment of the mmap threshold is disabled if any of the +.BR M_TRIM_THRESHOLD , +.BR M_TOP_PAD , +.BR M_MMAP_THRESHOLD , +or +.B M_MMAP_MAX +parameters is set. +.TP +.BR M_MXFAST " (since glibc 2.3)" +.\" The following text adapted from comments in the glibc sources: +Set the upper limit for memory allocation requests that are satisfied +using "fastbins". +(The measurement unit for this parameter is bytes.) +Fastbins are storage areas that hold deallocated blocks of memory +of the same size without merging adjacent free blocks. +Subsequent reallocation of blocks of the same size can be handled +very quickly by allocating from the fastbin, +although memory fragmentation and the overall memory footprint +of the program can increase. +.IP +The default value for this parameter is +.I 64*sizeof(size_t)/4 +(i.e., 64 on 32-bit architectures). +The range for this parameter is 0 to +.IR 80*sizeof(size_t)/4 . +Setting +.B M_MXFAST +to 0 disables the use of fastbins. +.TP +.BR M_PERTURB " (since glibc 2.4)" +If this parameter is set to a nonzero value, +then bytes of allocated memory (other than allocations via +.BR calloc (3)) +are initialized to the complement of the value +in the least significant byte of +.IR value , +and when allocated memory is released using +.BR free (3), +the freed bytes are set to the least significant byte of +.IR value . +This can be useful for detecting errors where programs +incorrectly rely on allocated memory being initialized to zero, +or reuse values in memory that has already been freed. +.IP +The default value for this parameter is 0. +.TP +.B M_TOP_PAD +This parameter defines the amount of padding to employ when calling +.BR sbrk (2) +to modify the program break. +(The measurement unit for this parameter is bytes.) +This parameter has an effect in the following circumstances: +.RS +.IP \[bu] 3 +When the program break is increased, then +.B M_TOP_PAD +bytes are added to the +.BR sbrk (2) +request. +.IP \[bu] +When the heap is trimmed as a consequence of calling +.BR free (3) +(see the discussion of +.BR M_TRIM_THRESHOLD ) +this much free space is preserved at the top of the heap. +.RE +.IP +In either case, +the amount of padding is always rounded to a system page boundary. +.IP +Modifying +.B M_TOP_PAD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.IP +The default value for this parameter is 128*1024. +.\" DEFAULT_TOP_PAD in glibc source +.TP +.B M_TRIM_THRESHOLD +When the amount of contiguous free memory at the top of the heap +grows sufficiently large, +.BR free (3) +employs +.BR sbrk (2) +to release this memory back to the system. +(This can be useful in programs that continue to execute for +a long period after freeing a significant amount of memory.) +The +.B M_TRIM_THRESHOLD +parameter specifies the minimum size (in bytes) that +this block of memory must reach before +.BR sbrk (2) +is used to trim the heap. +.IP +The default value for this parameter is 128*1024. +Setting +.B M_TRIM_THRESHOLD +to \-1 disables trimming completely. +.IP +Modifying +.B M_TRIM_THRESHOLD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.\" +.SS Environment variables +A number of environment variables can be defined +to modify some of the same parameters as are controlled by +.BR mallopt (). +Using these variables has the advantage that the source code +of the program need not be changed. +To be effective, these variables must be defined before the +first call to a memory-allocation function. +(If the same parameters are adjusted via +.BR mallopt (), +then the +.BR mallopt () +settings take precedence.) +For security reasons, +these variables are ignored in set-user-ID and set-group-ID programs. +.P +The environment variables are as follows +(note the trailing underscore at the end of the name of some variables): +.TP +.B MALLOC_ARENA_MAX +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_MAX . +.TP +.B MALLOC_ARENA_TEST +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_TEST . +.TP +.B MALLOC_CHECK_ +This environment variable controls the same parameter as +.BR mallopt () +.BR M_CHECK_ACTION . +If this variable is set to a nonzero value, +then a special implementation of the memory-allocation functions is used. +(This is accomplished using the +.BR malloc_hook (3) +feature.) +This implementation performs additional error checking, +but is slower +.\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower +.\" when MALLOC_CHECK_ was set. +than the standard set of memory-allocation functions. +(This implementation does not detect all possible errors; +memory leaks can still occur.) +.IP +The value assigned to this environment variable should be a single digit, +whose meaning is as described for +.BR M_CHECK_ACTION . +Any characters beyond the initial digit are ignored. +.IP +For security reasons, the effect of +.B MALLOC_CHECK_ +is disabled by default for set-user-ID and set-group-ID programs. +However, if the file +.I /etc/suid\-debug +exists (the content of the file is irrelevant), then +.B MALLOC_CHECK_ +also has an effect for set-user-ID and set-group-ID programs. +.TP +.B MALLOC_MMAP_MAX_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_MAX . +.TP +.B MALLOC_MMAP_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_THRESHOLD . +.TP +.B MALLOC_PERTURB_ +Controls the same parameter as +.BR mallopt () +.BR M_PERTURB . +.TP +.B MALLOC_TRIM_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_TRIM_THRESHOLD . +.TP +.B MALLOC_TOP_PAD_ +Controls the same parameter as +.BR mallopt () +.BR M_TOP_PAD . +.SH RETURN VALUE +On success, +.BR mallopt () +returns 1. +On error, it returns 0. +.SH ERRORS +On error, +.I errno +is +.I not +set. +.SH VERSIONS +A similar function exists on many System V derivatives, +but the range of values for +.I param +varies across systems. +The SVID defined options +.BR M_MXFAST , +.BR M_NLBLKS , +.BR M_GRAIN , +and +.BR M_KEEP , +but only the first of these is implemented in glibc. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.0. +.SH BUGS +Specifying an invalid value for +.I param +does not generate an error. +.P +A calculation error within the glibc implementation means that +a call of the form: +.\" FIXME . This looks buggy: +.\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK) +.\" malloc requests are rounded up: +.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129 +.P +.in +4n +.EX +mallopt(M_MXFAST, n) +.EE +.in +.P +does not result in fastbins being employed for all allocations of size up to +.IR n . +To ensure desired results, +.I n +should be rounded up to the next multiple greater than or equal to +.IR (2k+1)*sizeof(size_t) , +where +.I k +is an integer. +.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t) +.P +If +.BR mallopt () +is used to set +.BR M_PERTURB , +then, as expected, the bytes of allocated memory are initialized +to the complement of the byte in +.IR value , +and when that memory is freed, +the bytes of the region are initialized to the byte specified in +.IR value . +However, there is an +.RI off-by- sizeof(size_t) +error in the implementation: +.\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12140 +instead of initializing precisely the block of memory +being freed by the call +.IR free(p) , +the block starting at +.I p+sizeof(size_t) +is initialized. +.SH EXAMPLES +The program below demonstrates the use of +.BR M_CHECK_ACTION . +If the program is supplied with an (integer) command-line argument, +then that argument is used to set the +.B M_CHECK_ACTION +parameter. +The program then allocates a block of memory, +and frees it twice (an error). +.P +The following shell session shows what happens when we run this program +under glibc, with the default value for +.BR M_CHECK_ACTION : +.P +.in +4n +.EX +$ \fB./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 *** +======= Backtrace: ========= +/lib/libc.so.6(+0x6c501)[0x523501] +/lib/libc.so.6(+0x6dd70)[0x524d70] +/lib/libc.so.6(cfree+0x6d)[0x527e5d] +\&./a.out[0x80485db] +/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7] +\&./a.out[0x8048471] +======= Memory map: ======== +001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1 +001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1 +[some lines omitted] +b7814000\-b7817000 rw\-p 00000000 00:00 0 +bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack] +Aborted (core dumped) +.EE +.in +.P +The following runs show the results when employing other values for +.BR M_CHECK_ACTION : +.P +.in +4n +.EX +$ \fB./a.out 1\fP # Diagnose error and continue +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 *** +main(): returned from second free() call +$ \fB./a.out 2\fP # Abort without error message +main(): returned from first free() call +Aborted (core dumped) +$ \fB./a.out 0\fP # Ignore error and continue +main(): returned from first free() call +main(): returned from second free() call +.EE +.in +.P +The next run shows how to set the same parameter using the +.B MALLOC_CHECK_ +environment variable: +.P +.in +4n +.EX +$ \fBMALLOC_CHECK_=1 ./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 *** +main(): returned from second free() call +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mallopt.c) +.EX +#include <malloc.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + char *p; +\& + if (argc > 1) { + if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) { + fprintf(stderr, "mallopt() failed"); + exit(EXIT_FAILURE); + } + } +\& + p = malloc(1000); + if (p == NULL) { + fprintf(stderr, "malloc() failed"); + exit(EXIT_FAILURE); + } +\& + free(p); + printf("%s(): returned from first free() call\en", __func__); +\& + free(p); + printf("%s(): returned from second free() call\en", __func__); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR sbrk (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_hook (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) diff --git a/man/man3/matherr.3 b/man/man3/matherr.3 new file mode 100644 index 0000000..4536e01 --- /dev/null +++ b/man/man3/matherr.3 @@ -0,0 +1,428 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH matherr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +matherr \- SVID math library exception handling +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "[[deprecated]] int matherr(struct exception *" exc ); +.P +.B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION; +.fi +.SH DESCRIPTION +.IR Note : +the mechanism described in this page is no longer supported by glibc. +Before glibc 2.27, it had been marked as obsolete. +Since glibc 2.27, +.\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa +the mechanism has been removed altogether. +New applications should use the techniques described in +.BR math_error (7) +and +.BR fenv (3). +This page documents the +.BR matherr () +mechanism as an aid for maintaining and porting older applications. +.P +The System V Interface Definition (SVID) specifies that various +math functions should invoke a function called +.BR matherr () +if a math exception is detected. +This function is called before the math function returns; +after +.BR matherr () +returns, the system then returns to the math function, +which in turn returns to the caller. +.P +To employ +.BR matherr (), +the programmer must define the +.B _SVID_SOURCE +feature test macro +(before including +.I any +header files), +and assign the value +.B _SVID_ +to the external variable +.BR _LIB_VERSION . +.P +The system provides a default version of +.BR matherr (). +This version does nothing, and returns zero +(see below for the significance of this). +The default +.BR matherr () +can be overridden by a programmer-defined +version, which will be invoked when an exception occurs. +The function is invoked with one argument, a pointer to an +.I exception +structure, defined as follows: +.P +.in +4n +.EX +struct exception { + int type; /* Exception type */ + char *name; /* Name of function causing exception */ + double arg1; /* 1st argument to function */ + double arg2; /* 2nd argument to function */ + double retval; /* Function return value */ +} +.EE +.in +.P +The +.I type +field has one of the following values: +.TP 12 +.B DOMAIN +A domain error occurred (the function argument was outside the range +for which the function is defined). +The return value depends on the function; +.I errno +is set to +.BR EDOM . +.TP +.B SING +A pole error occurred (the function result is an infinity). +The return value in most cases is +.B HUGE +(the largest single precision floating-point number), +appropriately signed. +In most cases, +.I errno +is set to +.BR EDOM . +.TP +.B OVERFLOW +An overflow occurred. +In most cases, the value +.B HUGE +is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B UNDERFLOW +An underflow occurred. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B TLOSS +Total loss of significance. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B PLOSS +Partial loss of significance. +This value is unused on glibc +(and many other systems). +.P +The +.I arg1 +and +.I arg2 +fields are the arguments supplied to the function +.RI ( arg2 +is undefined for functions that take only one argument). +.P +The +.I retval +field specifies the return value that the math +function will return to its caller. +The programmer-defined +.BR matherr () +can modify this field to change the return value of the math function. +.P +If the +.BR matherr () +function returns zero, then the system sets +.I errno +as described above, and may print an error message on standard error +(see below). +.P +If the +.BR matherr () +function returns a nonzero value, then the system does not set +.IR errno , +and doesn't print an error message. +.SS Math functions that employ matherr() +The table below lists the functions and circumstances in which +.BR matherr () +is called. +The "Type" column indicates the value assigned to +.I exc\->type +when calling +.BR matherr (). +The "Result" column is the default return value assigned to +.IR exc\->retval . +.P +The "Msg?" and "errno" columns describe the default behavior if +.BR matherr () +returns zero. +If the "Msg?" columns contains "y", +then the system prints an error message on standard error. +.P +The table uses the following notations and abbreviations: +.P +.RS +.TS +l l. +x first argument to function +y second argument to function +fin finite value for argument +neg negative value for argument +int integral value for argument +o/f result overflowed +u/f result underflowed +|x| absolute value of x +X_TLOSS is a constant defined in \fI<math.h>\fP +.TE +.RE +.\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c +.\" A subset of cases were test by experimental programs. +.TS +lB lB lB cB lB +l l l c l. +Function Type Result Msg? errno +acos(|x|>1) DOMAIN HUGE y EDOM +asin(|x|>1) DOMAIN HUGE y EDOM +atan2(0,0) DOMAIN HUGE y EDOM +acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0 +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +cosh(fin) o/f OVERFLOW HUGE n ERANGE +sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE : \-HUGE +sqrt(x<0) DOMAIN 0.0 y EDOM +hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) u/f UNDERFLOW 0.0 n ERANGE +exp2(fin) o/f OVERFLOW HUGE n ERANGE +exp2(fin) u/f UNDERFLOW 0.0 n ERANGE +exp10(fin) o/f OVERFLOW HUGE n ERANGE +exp10(fin) u/f UNDERFLOW 0.0 n ERANGE +j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +y0(x>X_TLOSS) TLOSS 0.0 y ERANGE +y1(x>X_TLOSS) TLOSS 0.0 y ERANGE +yn(x>X_TLOSS) TLOSS 0.0 y ERANGE +y0(0) DOMAIN \-HUGE y EDOM +y0(x<0) DOMAIN \-HUGE y EDOM +y1(0) DOMAIN \-HUGE y EDOM +y1(x<0) DOMAIN \-HUGE y EDOM +yn(n,0) DOMAIN \-HUGE y EDOM +yn(x<0) DOMAIN \-HUGE y EDOM +lgamma(fin) o/f OVERFLOW HUGE n ERANGE +lgamma(\-int) or SING HUGE y EDOM +\ \ lgamma(0) +tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE +tgamma(\-int) SING NAN y EDOM +tgamma(0) SING copysign( y ERANGE +\ \ HUGE_VAL,x) +log(0) SING \-HUGE y EDOM +log(x<0) DOMAIN \-HUGE y EDOM +log2(0) SING \-HUGE n EDOM \" different from log() +log2(x<0) DOMAIN \-HUGE n EDOM \" different from log() +log10(0) SING \-HUGE y EDOM +log10(x<0) DOMAIN \-HUGE y EDOM +pow(0.0,0.0) DOMAIN 0.0 y EDOM +pow(x,y) o/f OVERFLOW HUGE n ERANGE +pow(x,y) u/f UNDERFLOW 0.0 n ERANGE +pow(NaN,0.0) DOMAIN x n EDOM +0**neg DOMAIN 0.0 y EDOM \" +0 and -0 +neg**non-int DOMAIN 0.0 y EDOM +scalb() o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +scalb() u/f UNDERFLOW copysign( n ERANGE +\ \ \ \ 0.0,x) +fmod(x,0) DOMAIN x y EDOM +remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +.TE +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR matherr () +T} Thread safety MT-Safe +.TE +.SH EXAMPLES +The example program demonstrates the use of +.BR matherr () +when calling +.BR log (3). +The program takes up to three command-line arguments. +The first argument is the floating-point number to be given to +.BR log (3). +If the optional second argument is provided, then +.B _LIB_VERSION +is set to +.B _SVID_ +so that +.BR matherr () +is called, and the integer supplied in the +command-line argument is used as the return value from +.BR matherr (). +If the optional third command-line argument is supplied, +then it specifies an alternative return value that +.BR matherr () +should assign as the return value of the math function. +.P +The following example run, where +.BR log (3) +is given an argument of 0.0, does not use +.BR matherr (): +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0" +errno: Numerical result out of range +x=\-inf +.EE +.in +.P +In the following run, +.BR matherr () +is called, and returns 0: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +log: SING error +errno: Numerical argument out of domain +x=\-340282346638528859811704183484516925440.000000 +.EE +.in +.P +The message "log: SING error" was printed by the C library. +.P +In the following run, +.BR matherr () +is called, and returns a nonzero value: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 1" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=\-340282346638528859811704183484516925440.000000 +.EE +.in +.P +In this case, the C library did not print a message, and +.I errno +was not set. +.P +In the following run, +.BR matherr () +is called, changes the return value of the math function, +and returns a nonzero value: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 1 12345.0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=12345.000000 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (matherr.c) +.EX +#define _SVID_SOURCE +#include <errno.h> +#include <math.h> +#include <stdio.h> +#include <stdlib.h> +\& +static int matherr_ret = 0; /* Value that matherr() + should return */ +static int change_retval = 0; /* Should matherr() change + function\[aq]s return value? */ +static double new_retval; /* New function return value */ +\& +int +matherr(struct exception *exc) +{ + fprintf(stderr, "matherr %s exception in %s() function\en", + (exc\->type == DOMAIN) ? "DOMAIN" : + (exc\->type == OVERFLOW) ? "OVERFLOW" : + (exc\->type == UNDERFLOW) ? "UNDERFLOW" : + (exc\->type == SING) ? "SING" : + (exc\->type == TLOSS) ? "TLOSS" : + (exc\->type == PLOSS) ? "PLOSS" : "???", + exc\->name); + fprintf(stderr, " args: %f, %f\en", + exc\->arg1, exc\->arg2); + fprintf(stderr, " retval: %f\en", exc\->retval); +\& + if (change_retval) + exc\->retval = new_retval; +\& + return matherr_ret; +} +\& +int +main(int argc, char *argv[]) +{ + double x; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s <argval>" + " [<matherr\-ret> [<new\-func\-retval>]]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (argc > 2) { + _LIB_VERSION = _SVID_; + matherr_ret = atoi(argv[2]); + } +\& + if (argc > 3) { + change_retval = 1; + new_retval = atof(argv[3]); + } +\& + x = log(atof(argv[1])); + if (errno != 0) + perror("errno"); +\& + printf("x=%f\en", x); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fenv (3), +.BR math_error (7), +.BR standards (7) diff --git a/man/man3/mblen.3 b/man/man3/mblen.3 new file mode 100644 index 0000000..f253965 --- /dev/null +++ b/man/man3/mblen.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mblen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mblen \- determine number of bytes in next multibyte character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int mblen(const char " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, the +.BR mblen () +function inspects at most +.I n +bytes of the multibyte string starting at +.I s +and extracts the +next complete multibyte character. +It uses a static anonymous shift state known only to the +.BR mblen () +function. +If the multibyte character is not the null wide +character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mblen () +returns \-1. +This can happen even if +.I n +is greater than or equal to +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mblen () +also returns \-1. +.P +If +.I s +is NULL, the +.BR mblen () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known to only this function, to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +The +.BR mblen () +function returns the number of +bytes parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns \-1, if an +invalid multibyte sequence was encountered or if it couldn't parse a complete +multibyte character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mblen () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +The function +.BR mbrlen (3) +provides a better interface to the same +functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mblen () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrlen (3) diff --git a/man/man3/mbrlen.3 b/man/man3/mbrlen.3 new file mode 100644 index 0000000..83d9d36 --- /dev/null +++ b/man/man3/mbrlen.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbrlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbrlen \- determine number of bytes in next multibyte character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t mbrlen(const char " s "[restrict ." n "], size_t " n , +.BI " mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The +.BR mbrlen () +function inspects at most +.I n +bytes of the multibyte +string starting at +.I s +and extracts the next complete multibyte character. +It updates the shift state +.IR *ps . +If the multibyte character is not the +null wide character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it resets the +shift state +.I *ps +to the initial state and returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrlen () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrlen () +returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.P +If +.I ps +is NULL, a static anonymous state known only to the +.BR mbrlen () +function is used instead. +.SH RETURN VALUE +The +.BR mbrlen () +function returns the number of bytes +parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns +.I "(size_t)\ \-1" +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.I (size_t)\ \-2 +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbrlen () +T} Thread safety MT-Unsafe race:mbrlen/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbrlen () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrtowc (3) diff --git a/man/man3/mbrtowc.3 b/man/man3/mbrtowc.3 new file mode 100644 index 0000000..e0cc56e --- /dev/null +++ b/man/man3/mbrtowc.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbrtowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbrtowc \- convert a multibyte sequence to a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t mbrtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n ], +.BI " size_t " n ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbrtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates the shift state +.IR *ps . +If the converted wide +character is not L\[aq]\e0\[aq] (the null wide character), +it returns the number of bytes that were consumed +from +.IR s . +If the converted wide character is L\[aq]\e0\[aq], it resets the shift +state +.I *ps +to the initial state and returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrtowc () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrtowc () +returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.P +A different case is when +.I s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbrtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.P +A third case is when +.I s +is NULL. +In this case, +.I pwc +and +.I n +are +ignored. +If the conversion state represented by +.I *ps +denotes an +incomplete multibyte character conversion, the +.BR mbrtowc () +function +returns +.IR "(size_t)\ \-1" , +sets +.I errno +to +.BR EILSEQ , +and +leaves +.I *ps +in an undefined state. +Otherwise, the +.BR mbrtowc () +function +puts +.I *ps +in the initial state and returns 0. +.P +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbrtowc () +function is used instead. +Otherwise, +.I *ps +must be a valid +.I mbstate_t +object. +An +.I mbstate_t +object +.I a +can be initialized to the initial state +by zeroing it, for example using +.P +.in +4n +.EX +memset(&a, 0, sizeof(a)); +.EE +.in +.SH RETURN VALUE +The +.BR mbrtowc () +function returns the number of bytes parsed from the +multibyte sequence starting at +.IR s , +if a non-L\[aq]\e0\[aq] wide character +was recognized. +It returns 0, if a L\[aq]\e0\[aq] wide character was recognized. +It returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.I "(size_t)\ \-2" +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbrtowc () +T} Thread safety MT-Unsafe race:mbrtowc/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbrtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbsinit (3), +.BR mbsrtowcs (3) diff --git a/man/man3/mbsinit.3 b/man/man3/mbsinit.3 new file mode 100644 index 0000000..00049c5 --- /dev/null +++ b/man/man3/mbsinit.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright, Bruno Haible <haible@clisp.cons.org> +.\" Copyright 2024, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbsinit 3 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +mbsinit +\- +test for initial shift state +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int mbsinit(const mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The function +.BR mbsinit () +tests whether +.I *ps +corresponds to an +initial state. +.SH RETURN VALUE +.BR mbsinit () +returns nonzero if +.I *ps +is an initial state, or if +.I ps +is NULL. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsinit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbsinit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbstate_t (3type), +.BR mbrlen (3), +.BR mbrtowc (3), +.BR mbsrtowcs (3), +.BR wcrtomb (3), +.BR wcsrtombs (3) diff --git a/man/man3/mbsnrtowcs.3 b/man/man3/mbsnrtowcs.3 new file mode 100644 index 0000000..5b03f7c --- /dev/null +++ b/man/man3/mbsnrtowcs.3 @@ -0,0 +1,199 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH mbsnrtowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbsnrtowcs \- convert a multibyte string to a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src , +.BI " size_t " nms ", size_t " len \ +", mbstate_t *restrict " ps ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mbsnrtowcs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR mbsnrtowcs () +function is like the +.BR mbsrtowcs (3) +function, except that +the number of bytes to be converted, starting at +.IR *src , +is limited to at most +.I nms +bytes. +.P +If +.I dest +is not NULL, the +.BR mbsnrtowcs () +function converts at +most +.I nms +bytes from the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I len +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The +conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +The +.I nms +limit forces a stop, +or +.I len +non-L\[aq]\e0\[aq] wide characters +have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the +next multibyte sequence to be converted, and the number of wide characters +written to +.I dest +is returned. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null wide character (\[aq]\e0\[aq]) +(which has the side effect of bringing back +.I *ps +to the +initial state). +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, +is returned. +.P +According to POSIX.1, +if the input buffer ends with an incomplete character, +it is unspecified whether conversion stops at the end of +the previous character (if any), or at the end of the input buffer. +The glibc implementation adopts the former behavior. +.P +If +.I dest +is NULL, +.I len +is ignored, and the conversion proceeds as +above, except that the converted wide characters +are not written out to memory, +and that no destination length limit exists. +.P +In both of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsnrtowcs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +wide +characters at +.IR dest . +.SH RETURN VALUE +The +.BR mbsnrtowcs () +function returns the number of wide characters +that make up the converted part of the wide-character string, +not including the terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsnrtowcs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mbsnrtowcs/!ps +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR mbsnrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsrtowcs (3) diff --git a/man/man3/mbsrtowcs.3 b/man/man3/mbsrtowcs.3 new file mode 100644 index 0000000..bf70295 --- /dev/null +++ b/man/man3/mbsrtowcs.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbsrtowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbsrtowcs \- convert a multibyte string to a wide-character string (restartable) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." dsize ], +.BI " const char **restrict " src , +.BI " size_t " dsize ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +convert the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I dsize +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +.I dsize +non-L\[aq]\e0\[aq] wide characters have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the next +multibyte sequence to be converted, +and the number of wide characters written to +.I dest +is returned. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null wide character (\[aq]\e0\[aq]), which has the side +effect of bringing back +.I *ps +to the +initial state. +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.P +If +.I dest +is NULL, +.I dsize +is ignored, +and the conversion proceeds as above, +except that the converted wide characters are not written out to memory, +and that no length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsrtowcs () +function is used instead. +.P +In order to avoid the case 2 above, the programmer should make sure +.I dsize +is +greater than or equal to +.IR "mbsrtowcs(NULL,src,0,ps)+1" . +.P +The programmer must ensure that there is room for at least +.I dsize +wide +characters at +.IR dest . +.P +This function is a restartable version of +.BR mbstowcs (3). +.SH RETURN VALUE +The number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsrtowcs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mbsrtowcs/!ps +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbsrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsnrtowcs (3), +.BR mbstowcs (3) diff --git a/man/man3/mbstowcs.3 b/man/man3/mbstowcs.3 new file mode 100644 index 0000000..f1c4ea5 --- /dev/null +++ b/man/man3/mbstowcs.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbstowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbstowcs \- convert a multibyte string to a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "size_t mbstowcs(wchar_t " dest "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +convert the +multibyte string +.I src +to a wide-character string starting at +.IR dest . +At most +.I dsize +wide characters are written to +.IR dest . +The sequence of characters in the string +.I src +shall begin in the initial shift state. +The conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I (size_t)\ \-1 +is returned. +.IP \[bu] +.I dsize +non-L\[aq]\e0\[aq] wide characters have been stored at +.IR dest . +In this case, the number of wide characters written to +.I dest +is returned, but the +shift state at this point is lost. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null character (\[aq]\e0\[aq]). +In this case, the number of wide characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.P +If +.I dest +is NULL, +.I dsize +is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no length limit exists. +.P +In order to avoid the case 2 above, the programmer should make sure +.I dsize +is +greater than or equal to +.IR "mbstowcs(NULL,src,0)+1" . +.P +The programmer must ensure that there is room for at least +.I dsize +wide +characters at +.IR dest . +.SH RETURN VALUE +The number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbstowcs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The function +.BR mbsrtowcs (3) +provides a better interface to the same +functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbstowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH EXAMPLES +The program below illustrates the use of +.BR mbstowcs (), +as well as some of the wide character classification functions. +An example run is the following: +.P +.in +4n +.EX +$ ./t_mbstowcs de_DE.UTF\-8 Grüße! +Length of source string (excluding terminator): + 8 bytes + 6 multibyte characters +\& +Wide character string is: Grüße! (6 characters) + G alpha upper + r alpha lower + ü alpha lower + ß alpha lower + e alpha lower + ! !alpha +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mbstowcs.c) +.EX +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <wchar.h> +#include <wctype.h> +\& +int +main(int argc, char *argv[]) +{ + size_t mbslen; /* Number of multibyte characters in source */ + wchar_t *wcs; /* Pointer to converted wide character string */ +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Apply the specified locale. */ +\& + if (setlocale(LC_ALL, argv[1]) == NULL) { + perror("setlocale"); + exit(EXIT_FAILURE); + } +\& + /* Calculate the length required to hold argv[2] converted to + a wide character string. */ +\& + mbslen = mbstowcs(NULL, argv[2], 0); + if (mbslen == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } +\& + /* Describe the source string to the user. */ +\& + printf("Length of source string (excluding terminator):\en"); + printf(" %zu bytes\en", strlen(argv[2])); + printf(" %zu multibyte characters\en\en", mbslen); +\& + /* Allocate wide character string of the desired size. Add 1 + to allow for terminating null wide character (L\[aq]\e0\[aq]). */ +\& + wcs = calloc(mbslen + 1, sizeof(*wcs)); + if (wcs == NULL) { + perror("calloc"); + exit(EXIT_FAILURE); + } +\& + /* Convert the multibyte character string in argv[2] to a + wide character string. */ +\& + if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } +\& + printf("Wide character string is: %ls (%zu characters)\en", + wcs, mbslen); +\& + /* Now do some inspection of the classes of the characters in + the wide character string. */ +\& + for (wchar_t *wp = wcs; *wp != 0; wp++) { + printf(" %lc ", (wint_t) *wp); +\& + if (!iswalpha(*wp)) + printf("!"); + printf("alpha "); +\& + if (iswalpha(*wp)) { + if (iswupper(*wp)) + printf("upper "); +\& + if (iswlower(*wp)) + printf("lower "); + } +\& + putchar(\[aq]\en\[aq]); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mblen (3), +.BR mbsrtowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/mbtowc.3 b/man/man3/mbtowc.3 new file mode 100644 index 0000000..4057959 --- /dev/null +++ b/man/man3/mbtowc.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbtowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbtowc \- convert a multibyte sequence to a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int mbtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates an internal shift state known only to the +.BR mbtowc () +function. +If +.I s +does not point to a null byte (\[aq]\e0\[aq]), it returns the number +of bytes that were consumed from +.IR s , +otherwise it returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, or if they contain an invalid multibyte sequence, +.BR mbtowc () +returns \-1. +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.P +A different case is when +.I s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.P +A third case is when +.I s +is NULL. +In this case, +.I pwc +and +.I n +are +ignored. +The +.BR mbtowc () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR mbtowc () +function returns the number of +consumed bytes starting at +.IR s , +or 0 if +.I s +points to a null byte, +or \-1 upon failure. +.P +If +.I s +is NULL, the +.BR mbtowc () +function +returns nonzero if the encoding +has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbtowc () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +This function is not multithread safe. +The function +.BR mbrtowc (3) +provides +a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbrtowc (3), +.BR mbstowcs (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/mcheck.3 b/man/man3/mcheck.3 new file mode 100644 index 0000000..0d3a7da --- /dev/null +++ b/man/man3/mcheck.3 @@ -0,0 +1,213 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mcheck 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <mcheck.h> +.P +.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.B void mcheck_check_all(void); +.P +.BI "enum mcheck_status mprobe(void *" ptr ); +.fi +.SH DESCRIPTION +The +.BR mcheck () +function installs a set of debugging hooks for the +.BR malloc (3) +family of memory-allocation functions. +These hooks cause certain consistency checks to be performed +on the state of the heap. +The checks can detect application errors such as freeing a block of memory +more than once or corrupting the bookkeeping data structures +that immediately precede a block of allocated memory. +.P +To be effective, the +.BR mcheck () +function must be called before the first call to +.BR malloc (3) +or a related function. +In cases where this is difficult to ensure, linking the program with +.I \-lmcheck +inserts an implicit call to +.BR mcheck () +(with a NULL argument) +before the first call to a memory-allocation function. +.P +The +.BR mcheck_pedantic () +function is similar to +.BR mcheck (), +but performs checks on all allocated blocks whenever +one of the memory-allocation functions is called. +This can be very slow! +.P +The +.BR mcheck_check_all () +function causes an immediate check on all allocated blocks. +This call is effective only if +.BR mcheck () +is called beforehand. +.P +If the system detects an inconsistency in the heap, +the caller-supplied function pointed to by +.I abortfunc +is invoked with a single argument, +.IR mstatus , +that indicates what type of inconsistency was detected. +If +.I abortfunc +is NULL, a default function prints an error message on +.I stderr +and calls +.BR abort (3). +.P +The +.BR mprobe () +function performs a consistency check on +the block of allocated memory pointed to by +.IR ptr . +The +.BR mcheck () +function should be called beforehand (otherwise +.BR mprobe () +returns +.BR MCHECK_DISABLED ). +.P +The following list describes the values returned by +.BR mprobe () +or passed as the +.I mstatus +argument when +.I abortfunc +is invoked: +.TP +.BR MCHECK_DISABLED " (" mprobe "() only)" +.BR mcheck () +was not called before the first memory allocation function was called. +Consistency checking is not possible. +.TP +.BR MCHECK_OK " (" mprobe "() only)" +No inconsistency detected. +.TP +.B MCHECK_HEAD +Memory preceding an allocated block was clobbered. +.TP +.B MCHECK_TAIL +Memory following an allocated block was clobbered. +.TP +.B +MCHECK_FREE +A block of memory was freed twice. +.SH RETURN VALUE +.BR mcheck () +and +.BR mcheck_pedantic () +return 0 on success, or \-1 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mcheck (), +.BR mcheck_pedantic (), +.BR mcheck_check_all (), +.BR mprobe () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mcheck +const:malloc_hooks +T} +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR mcheck_pedantic () +.TQ +.BR mcheck_check_all () +glibc 2.2. +.TP +.BR mcheck () +.TQ +.BR mprobe () +glibc 2.0. +.SH NOTES +Linking a program with +.I \-lmcheck +and using the +.B MALLOC_CHECK_ +environment variable (described in +.BR mallopt (3)) +cause the same kinds of errors to be detected. +But, using +.B MALLOC_CHECK_ +does not require the application to be relinked. +.\" But is MALLOC_CHECK_ slower? +.SH EXAMPLES +The program below calls +.BR mcheck () +with a NULL argument and then frees the same block of memory twice. +The following shell session demonstrates what happens +when running the program: +.P +.in +4n +.EX +.RB "$" " ./a.out" +About to free +\& +About to free a second time +block freed twice +Aborted (core dumped) +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mcheck.c) +.EX +#include <mcheck.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + char *p; +\& + if (mcheck(NULL) != 0) { + fprintf(stderr, "mcheck() failed\en"); +\& + exit(EXIT_FAILURE); + } +\& + p = malloc(1000); +\& + fprintf(stderr, "About to free\en"); + free(p); + fprintf(stderr, "\enAbout to free a second time\en"); + free(p); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3), +.BR mtrace (3) diff --git a/man/man3/mcheck_check_all.3 b/man/man3/mcheck_check_all.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mcheck_check_all.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/mcheck_pedantic.3 b/man/man3/mcheck_pedantic.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mcheck_pedantic.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/memalign.3 b/man/man3/memalign.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/memalign.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/memccpy.3 b/man/man3/memccpy.3 new file mode 100644 index 0000000..da4acf9 --- /dev/null +++ b/man/man3/memccpy.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:57:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH memccpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memccpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "void *memccpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memccpy () +function copies no more than +.I n +bytes from +memory area +.I src +to memory area +.IR dest , +stopping when the +character +.I c +is found. +.P +If the memory areas overlap, the results are undefined. +.SH RETURN VALUE +The +.BR memccpy () +function returns a pointer to the next character +in +.I dest +after +.IR c , +or NULL if +.I c +was not found in the +first +.I n +characters of +.IR src . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memccpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man/man3/memchr.3 b/man/man3/memchr.3 new file mode 100644 index 0000000..f831625 --- /dev/null +++ b/man/man3/memchr.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Mon Apr 12 12:49:57 1993, David Metcalfe +.\" Modified Sat Jul 24 18:56:22 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com) +.\" 2008-07-09, mtk, add rawmemchr() +.\" +.TH memchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memchr, memrchr, rawmemchr \- scan memory for a character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); +.BI "void *memrchr(const void " s [. n "], int " c ", size_t " n ); +.P +.BI "[[deprecated]] void *rawmemchr(const void *" s ", int " c ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR memrchr (), +.BR rawmemchr (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR memchr () +function scans the initial +.I n +bytes of the memory +area pointed to by +.I s +for the first instance of +.IR c . +Both +.I c +and the bytes of the memory area pointed to by +.I s +are interpreted as +.IR "unsigned char" . +.P +The +.BR memrchr () +function is like the +.BR memchr () +function, +except that it searches backward from the end of the +.I n +bytes pointed to by +.I s +instead of forward from the beginning. +.P +The +.BR rawmemchr () +function is similar to +.BR memchr (), +but it assumes +(i.e., the programmer knows for certain) +that an instance of +.I c +lies somewhere in the memory area starting at the location pointed to by +.IR s . +If an instance of +.I c +is not found, the behavior is undefined. +Use either +.BR strlen (3) +or +.BR memchr (3) +instead. +.SH RETURN VALUE +The +.BR memchr () +and +.BR memrchr () +functions return a pointer +to the matching byte or NULL if the character does not occur in +the given memory area. +.P +The +.BR rawmemchr () +function returns a pointer to the matching byte. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memchr (), +.BR memrchr (), +.BR rawmemchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR memchr () +C11, POSIX.1-2008. +.TP +.BR memrchr () +.TQ +.BR rawmemchr () +GNU. +.SH HISTORY +.TP +.BR memchr () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR memrchr () +glibc 2.2. +.TP +.BR rawmemchr () +glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR ffs (3), +.BR memmem (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wmemchr (3) diff --git a/man/man3/memcmp.3 b/man/man3/memcmp.3 new file mode 100644 index 0000000..efd362a --- /dev/null +++ b/man/man3/memcmp.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH memcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memcmp \- compare memory areas +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcmp () +function compares the first \fIn\fP bytes (each interpreted as +.IR "unsigned char" ) +of the memory areas \fIs1\fP and \fIs2\fP. +.SH RETURN VALUE +The +.BR memcmp () +function returns an integer less than, equal to, or +greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, +respectively, to be less than, to match, or be greater than the first +\fIn\fP bytes of \fIs2\fP. +.P +For a nonzero return value, the sign is determined by the sign of +the difference between the first pair of bytes (interpreted as +.IR "unsigned char" ) +that differ in +.I s1 +and +.IR s2 . +.P +If +.I n +is zero, the return value is zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memcmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +Do not use +.BR memcmp () +to compare confidential data, +such as cryptographic secrets, +because the CPU time required for the comparison +depends on the contents of the addresses compared, +this function is subject to timing-based side-channel attacks. +In such cases, +a function that performs comparisons in deterministic time, +depending only on +.I n +(the quantity of bytes compared) +is required. +Some operating systems provide such a function (e.g., NetBSD's +.BR consttime_memequal ()), +but no such function is specified in POSIX. +On Linux, you may need to implement such a function yourself. +.SH SEE ALSO +.BR bstring (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3), +.BR wmemcmp (3) diff --git a/man/man3/memcpy.3 b/man/man3/memcpy.3 new file mode 100644 index 0000000..0c1d801 --- /dev/null +++ b/man/man3/memcpy.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu) +.TH memcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memcpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "void *memcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcpy () +function copies \fIn\fP bytes from memory area +\fIsrc\fP to memory area \fIdest\fP. +The memory areas must not overlap. +Use +.BR memmove (3) +if the memory areas do overlap. +.SH RETURN VALUE +The +.BR memcpy () +function returns a pointer to \fIdest\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +Failure to observe the requirement that the memory areas +do not overlap has been the source of significant bugs. +(POSIX and the C standards are explicit that employing +.BR memcpy () +with overlapping areas produces undefined behavior.) +Most notably, in glibc 2.13 +.\" glibc commit 6fb8cbcb58a29fff73eb2101b34caa19a7f88eba +a performance optimization of +.BR memcpy () +on some platforms (including x86-64) included changing the order +.\" From forward copying to backward copying +in which bytes were copied from +.I src +to +.IR dest . +.P +This change revealed breakages in a number of applications that performed +copying with overlapping areas. +.\" Adobe Flash player was the highest profile example: +.\" https://bugzilla.redhat.com/show_bug.cgi?id=638477 +.\" Reported: 2010-09-29 02:35 EDT by JCHuynh +.\" Bug 638477 - Strange sound on mp3 flash website +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=12518 +.\" Bug 12518 - memcpy acts randomly (and differently) with overlapping areas +.\" Reported: 2011-02-25 02:26 UTC by Linus Torvalds +.\" +Under the previous implementation, +the order in which the bytes were copied had fortuitously hidden the bug, +which was revealed when the copying order was reversed. +In glibc 2.14, +.\" glibc commit 0354e355014b7bfda32622e0255399d859862fcd +a versioned symbol was added so that old binaries +(i.e., those linked against glibc versions earlier than 2.14) +employed a +.BR memcpy () +implementation that safely handles the overlapping buffers case +(by providing an "older" +.BR memcpy () +implementation that was aliased to +.BR memmove (3)). +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memmove (3), +.BR mempcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemcpy (3) diff --git a/man/man3/memfrob.3 b/man/man3/memfrob.3 new file mode 100644 index 0000000..c6178e5 --- /dev/null +++ b/man/man3/memfrob.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:54:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH memfrob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memfrob \- frobnicate (obfuscate) a memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "void *memfrob(void " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memfrob () +function obfuscates the first \fIn\fP bytes of the +memory area \fIs\fP by exclusive-ORing each character with the number +42. +The effect can be reversed by using +.BR memfrob () +on the +obfuscated memory area. +.P +Note that this function is not a proper encryption routine as the XOR +constant is fixed, and is suitable only for hiding strings. +.SH RETURN VALUE +The +.BR memfrob () +function returns a pointer to the obfuscated memory +area. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memfrob () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR bstring (3), +.BR strfry (3) diff --git a/man/man3/memmem.3 b/man/man3/memmem.3 new file mode 100644 index 0000000..825a0d4 --- /dev/null +++ b/man/man3/memmem.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:50:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Interchanged 'needle' and 'haystack'; added history, aeb, 980113. +.TH memmem 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memmem \- locate a substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , +.BI " const void " needle [. needlelen "], size_t " needlelen ); +.fi +.SH DESCRIPTION +The +.BR memmem () +function finds the start of the first occurrence +of the substring +.I needle +of length +.I needlelen +in the memory +area +.I haystack +of length +.IR haystacklen . +.SH RETURN VALUE +The +.BR memmem () +function returns a pointer to the beginning of the +substring, or NULL if the substring is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memmem () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +musl libc 0.9.7; +FreeBSD 6.0, OpenBSD 5.4, NetBSD, Illumos. +.SH BUGS +.\" This function was broken in Linux libraries up to and including libc 5.0.9; +.\" there the +.\" .IR needle +.\" and +.\" .I haystack +.\" arguments were interchanged, +.\" and a pointer to the end of the first occurrence of +.\" .I needle +.\" was returned. +.\" +.\" Both old and new libc's have the bug that if +.\" .I needle +.\" is empty, +.\" .I haystack\-1 +.\" (instead of +.\" .IR haystack ) +.\" is returned. +In glibc 2.0, if +.I needle +is empty, +.BR memmem () +returns a pointer to the last byte of +.IR haystack . +This is fixed in glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR strstr (3) diff --git a/man/man3/memmove.3 b/man/man3/memmove.3 new file mode 100644 index 0000000..598fec7 --- /dev/null +++ b/man/man3/memmove.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH memmove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memmove \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memmove () +function copies +.I n +bytes from memory area +.I src +to memory area +.IR dest . +The memory areas may overlap: copying takes place as though +the bytes in +.I src +are first copied into a temporary array that does not overlap +.I src +or +.IR dest , +and the bytes are then copied from the temporary array to +.IR dest . +.SH RETURN VALUE +The +.BR memmove () +function returns a pointer to +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memmove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemmove (3) diff --git a/man/man3/mempcpy.3 b/man/man3/mempcpy.3 new file mode 100644 index 0000000..f685a74 --- /dev/null +++ b/man/man3/mempcpy.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Heavily based on glibc infopages, copyright Free Software Foundation +.\" +.\" aeb, 2003, polished a little +.TH mempcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mempcpy, wmempcpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "void *mempcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " size_t " n ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <wchar.h> +.P +.BI "wchar_t *wmempcpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR mempcpy () +function is nearly identical to the +.BR memcpy (3) +function. +It copies +.I n +bytes from the object beginning at +.I src +into the object pointed to by +.IR dest . +But instead of returning the value of +.I dest +it returns a pointer to the byte following the last written byte. +.P +This function is useful in situations where a number of objects +shall be copied to consecutive memory positions. +.P +The +.BR wmempcpy () +function is identical but takes +.I wchar_t +type arguments and copies +.I n +wide characters. +.SH RETURN VALUE +.I dest ++ +.IR n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mempcpy (), +.BR wmempcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH EXAMPLES +.EX +void * +combine(void *o1, size_t s1, void *o2, size_t s2) +{ + void *result = malloc(s1 + s2); + if (result != NULL) + mempcpy(mempcpy(result, o1, s1), o2, s2); + return result; +} +.EE +.SH SEE ALSO +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man/man3/memrchr.3 b/man/man3/memrchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man/man3/memrchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man/man3/memset.3 b/man/man3/memset.3 new file mode 100644 index 0000000..cb3c143 --- /dev/null +++ b/man/man3/memset.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:23 1993 by Rik Faith (faith@cs.unc.edu) +.TH memset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memset \- fill memory with a constant byte +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "void *memset(void " s [. n "], int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memset () +function fills the first +.I n +bytes of the +memory area pointed to by +.I s +with the constant byte +.IR c . +.SH RETURN VALUE +The +.BR memset () +function returns a pointer to the memory area +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memset () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3), +.BR bzero (3), +.BR swab (3), +.BR wmemset (3) diff --git a/man/man3/minor.3 b/man/man3/minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/mkdtemp.3 b/man/man3/mkdtemp.3 new file mode 100644 index 0000000..5a2332a --- /dev/null +++ b/man/man3/mkdtemp.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2001 John Levon <moz@compsoc.man.ac.uk> +.\" Based on mkstemp(3), Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and GNU libc documentation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH mkdtemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkdtemp \- create a unique temporary directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "char *mkdtemp(char *" template ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkdtemp (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc 2.19 and earlier: */ _BSD_SOURCE + || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR mkdtemp () +function generates a uniquely named temporary +directory from \fItemplate\fP. +The last six characters of \fItemplate\fP +must be XXXXXX and these are replaced with a string that makes the +directory name unique. +The directory is then created with +permissions 0700. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mkdtemp () +function returns a pointer to the modified template +string on success, and NULL on failure, in which case +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +Now \fItemplate\fP is unchanged. +.P +Also see +.BR mkdir (2) +for other possible values for \fIerrno\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkdtemp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1.91. +NetBSD 1.4. +POSIX.1-2008. +.SH SEE ALSO +.BR mktemp (1), +.BR mkdir (2), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mkfifo.3 b/man/man3/mkfifo.3 new file mode 100644 index 0000000..46e1c14 --- /dev/null +++ b/man/man3/mkfifo.3 @@ -0,0 +1,201 @@ +'\" t +.\" This manpage is Copyright (C) 1995 James R. Van Zandt <jrv@vanzandt.mv.com> +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" changed section from 2 to 3, aeb, 950919 +.\" +.TH mkfifo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkfifo, mkfifoat \- make a FIFO special file (a named pipe) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.P +.BI "int mkfifo(const char *" pathname ", mode_t " mode ); +.P +.BR "#include <fcntl.h> " "/* Definition of AT_* constants */" +.B #include <sys/stat.h> +.P +.BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkfifoat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR mkfifo () +makes a FIFO special file with name \fIpathname\fP. +\fImode\fP specifies the FIFO's permissions. +It is modified by the +process's \fBumask\fP in the usual way: the permissions of the created +file are \fB(\fP\fImode\fP\fB & \[ti]umask)\fP. +.P +A FIFO special file is similar to a pipe, except that it is created +in a different way. +Instead of being an anonymous communications +channel, a FIFO special file is entered into the filesystem by +calling +.BR mkfifo (). +.P +Once you have created a FIFO special file in this way, any process can +open it for reading or writing, in the same way as an ordinary file. +However, it has to be open at both ends simultaneously before you can +proceed to do any input or output operations on it. +Opening a FIFO for reading normally blocks until some +other process opens the same FIFO for writing, and vice versa. +See +.BR fifo (7) +for nonblocking handling of FIFO special files. +.SS mkfifoat() +The +.BR mkfifoat () +function operates in exactly the same way as +.BR mkfifo (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mkfifo () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mkfifo ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR mkfifoat (). +.SH RETURN VALUE +On success +.BR mkfifo () +and +.BR mkfifoat () +return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +One of the directories in \fIpathname\fP did not allow search +(execute) permission. +.TP +.B EBADF +.RB ( mkfifoat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +\fIpathname\fP already exists. +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B ENAMETOOLONG +Either the total length of \fIpathname\fP is greater than +\fBPATH_MAX\fP, or an individual filename component has a length +greater than \fBNAME_MAX\fP. +In the GNU system, there is no imposed +limit on overall filename length, but some filesystems may place +limits on the length of a component. +.TP +.B ENOENT +A directory component in \fIpathname\fP does not exist or is a +dangling symbolic link. +.TP +.B ENOSPC +The directory or filesystem has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in \fIpathname\fP is not, in fact, a +directory. +.TP +.B ENOTDIR +.RB ( mkfifoat ()) +.I pathname +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EROFS +\fIpathname\fP refers to a read-only filesystem. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkfifo (), +.BR mkfifoat () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +It is implemented using +.BR mknodat (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mkfifo () +POSIX.1-2001. +.TP +.BR mkfifoat () +glibc 2.4. +POSIX.1-2008. +.SH SEE ALSO +.BR mkfifo (1), +.BR close (2), +.BR open (2), +.BR read (2), +.BR stat (2), +.BR umask (2), +.BR write (2), +.BR fifo (7) diff --git a/man/man3/mkfifoat.3 b/man/man3/mkfifoat.3 new file mode 100644 index 0000000..25f4896 --- /dev/null +++ b/man/man3/mkfifoat.3 @@ -0,0 +1 @@ +.so man3/mkfifo.3 diff --git a/man/man3/mkostemp.3 b/man/man3/mkostemp.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkostemp.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mkostemps.3 b/man/man3/mkostemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkostemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mkstemp.3 b/man/man3/mkstemp.3 new file mode 100644 index 0000000..8461aae --- /dev/null +++ b/man/man3/mkstemp.3 @@ -0,0 +1,247 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 980310, aeb +.\" Modified 990328, aeb +.\" 2008-06-19, mtk, Added mkostemp(); various other changes +.\" +.TH mkstemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkstemp, mkostemp, mkstemps, mkostemps \- create a unique temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int mkstemp(char *" template ); +.BI "int mkostemp(char *" template ", int " flags ); +.BI "int mkstemps(char *" template ", int " suffixlen ); +.BI "int mkostemps(char *" template ", int " suffixlen ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkstemp (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR mkostemp (): +.nf + _GNU_SOURCE +.fi +.P +.BR mkstemps (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR mkostemps (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR mkstemp () +function generates a unique temporary filename from +.IR template , +creates and opens the file, +and returns an open file descriptor for the file. +.P +The last six characters of +.I template +must be "XXXXXX" and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.P +The file is created with +permissions 0600, that is, read plus write for owner only. +The returned file descriptor provides both read and write access to the file. +The file is opened with the +.BR open (2) +.B O_EXCL +flag, guaranteeing that the caller is the process that creates the file. +.P +The +.BR mkostemp () +function is like +.BR mkstemp (), +with the difference that the following bits\[em]with the same meaning as for +.BR open (2)\[em]may +be specified in +.IR flags : +.BR O_APPEND , +.BR O_CLOEXEC , +and +.BR O_SYNC . +Note that when creating the file, +.BR mkostemp () +includes the values +.BR O_RDWR , +.BR O_CREAT , +and +.B O_EXCL +in the +.I flags +argument given to +.BR open (2); +including these values in the +.I flags +argument given to +.BR mkostemp () +is unnecessary, and produces errors on some +.\" Reportedly, FreeBSD +systems. +.P +The +.BR mkstemps () +function is like +.BR mkstemp (), +except that the string in +.I template +contains a suffix of +.I suffixlen +characters. +Thus, +.I template +is of the form +.IR "prefixXXXXXXsuffix" , +and the string XXXXXX is modified as for +.BR mkstemp (). +.P +The +.BR mkostemps () +function is to +.BR mkstemps () +as +.BR mkostemp () +is to +.BR mkstemp (). +.SH RETURN VALUE +On success, these functions return the file descriptor +of the temporary file. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EEXIST +Could not create a unique temporary filename. +Now the contents of \fItemplate\fP are undefined. +.TP +.B EINVAL +For +.BR mkstemp () +and +.BR mkostemp (): +The last six characters of \fItemplate\fP were not XXXXXX; +now \fItemplate\fP is unchanged. +.IP +For +.BR mkstemps () +and +.BR mkostemps (): +.I template +is less than +.I "(6 + suffixlen)" +characters long, or the last 6 characters before the suffix in +.I template +were not XXXXXX. +.P +These functions may also fail with any of the errors described for +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkstemp (), +.BR mkostemp (), +.BR mkstemps (), +.BR mkostemps () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR mkstemp () +POSIX.1-2001. +.TP +.BR mkstemps () +BSD. +.\" mkstemps() appears to be at least on the BSDs, Mac OS X, Solaris, +.\" and Tru64. +.TP +.BR mkostemp () +.TQ +.BR mkostemps () +GNU. +.SH HISTORY +.TP +.BR mkstemp () +4.3BSD, POSIX.1-2001. +.TP +.BR mkstemps () +glibc 2.11. +BSD, Mac OS X, Solaris, Tru64. +.TP +.BR mkostemp () +glibc 2.7. +.TP +.BR mkostemps () +glibc 2.11. +.P +In glibc versions 2.06 and earlier, the file is created with permissions 0666, +that is, read and write for all users. +This old behavior may be +a security risk, especially since other UNIX flavors use 0600, +and somebody might overlook this detail when porting programs. +POSIX.1-2008 adds a requirement that the file be created with mode 0600. +.P +More generally, the POSIX specification of +.BR mkstemp () +does not say anything +about file modes, so the application should make sure its +file mode creation mask (see +.BR umask (2)) +is set appropriately before calling +.BR mkstemp () +(and +.BR mkostemp ()). +.\" +.\" The prototype for +.\" .BR mkstemp () +.\" is in +.\" .I <unistd.h> +.\" for libc4, libc5, glibc1; glibc2 follows POSIX.1 and has the prototype in +.\" .IR <stdlib.h> . +.SH SEE ALSO +.BR mkdtemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mkstemps.3 b/man/man3/mkstemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkstemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mktemp.3 b/man/man3/mktemp.3 new file mode 100644 index 0000000..54e5b1f --- /dev/null +++ b/man/man3/mktemp.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 23 01:26:34 1995 by Andries Brouwer (aeb@cwi.nl) +.\" (prompted by Scott Burkett <scottb@IntNet.net>) +.\" Modified Sun Mar 28 23:44:38 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH mktemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mktemp \- make a unique temporary filename +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "char *mktemp(char *" template ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mktemp (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.IR "Never use this function" ; +see BUGS. +.P +The +.BR mktemp () +function generates a unique temporary filename +from \fItemplate\fP. +The last six characters of \fItemplate\fP must +be XXXXXX and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mktemp () +function always returns \fItemplate\fP. +If a unique name was created, the last six bytes of \fItemplate\fP will +have been modified in such a way that the resulting name is unique +(i.e., does not exist already) +If a unique name could not be created, +\fItemplate\fP is made an empty string, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mktemp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +Removed in POSIX.1-2008. +.\" .SH NOTES +.\" The prototype is in +.\" .I <unistd.h> +.\" for libc4, libc5, glibc1; glibc2 follows the Single UNIX Specification +.\" and has the prototype in +.\" .IR <stdlib.h> . +.SH BUGS +Never use +.BR mktemp (). +Some implementations follow 4.3BSD +and replace XXXXXX by the current process ID and a single letter, +so that at most 26 different names can be returned. +Since on the one hand the names are easy to guess, and on the other +hand there is a race between testing whether the name exists and +opening the file, every use of +.BR mktemp () +is a security risk. +The race is avoided by +.BR mkstemp (3) +and +.BR mkdtemp (3). +.SH SEE ALSO +.BR mktemp (1), +.BR mkdtemp (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mktime.3 b/man/man3/mktime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/mktime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/mmap64.3 b/man/man3/mmap64.3 new file mode 100644 index 0000000..8902d1b --- /dev/null +++ b/man/man3/mmap64.3 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man/man3/modf.3 b/man/man3/modf.3 new file mode 100644 index 0000000..89db053 --- /dev/null +++ b/man/man3/modf.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH modf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +modf, modff, modfl \- extract signed integral and fractional values from +floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double modf(double " x ", double *" iptr ); +.BI "float modff(float " x ", float *" iptr ); +.BI "long double modfl(long double " x ", long double *" iptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR modff (), +.BR modfl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions break the argument +.I x +into an integral +part and a fractional part, each of which has the same sign as +.IR x . +The integral part is stored in the location pointed to by +.IR iptr . +.SH RETURN VALUE +These functions return the fractional part of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned, and +.I *iptr +is set to a NaN. +.P +If +.I x +is positive infinity (negative infinity), +0 (\-0) is returned, and +.I *iptr +is set to positive infinity (negative infinity). +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR modf (), +.BR modff (), +.BR modfl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR ldexp (3) diff --git a/man/man3/modff.3 b/man/man3/modff.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man/man3/modff.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man/man3/modfl.3 b/man/man3/modfl.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man/man3/modfl.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man/man3/mpool.3 b/man/man3/mpool.3 new file mode 100644 index 0000000..038be70 --- /dev/null +++ b/man/man3/mpool.3 @@ -0,0 +1,205 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" +.TH mpool 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +mpool \- shared memory buffer pool +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <db.h> +.B #include <mpool.h> +.P +.BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ +", pgno_t " maxcache ); +.P +.BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," +.BI " void (*" pgout ")(void *, pgno_t, void *)," +.BI " void *" pgcookie ); +.P +.BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); +.BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); +.BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); +.P +.BI "int mpool_sync(MPOOL *" mp ); +.BI "int mpool_close(MPOOL *" mp ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +.I Mpool +is the library interface intended to provide page oriented buffer management +of files. +The buffers may be shared between processes. +.P +The function +.BR mpool_open () +initializes a memory pool. +The +.I key +argument is the byte string used to negotiate between multiple +processes wishing to share buffers. +If the file buffers are mapped in shared memory, all processes using +the same key will share the buffers. +If +.I key +is NULL, the buffers are mapped into private memory. +The +.I fd +argument is a file descriptor for the underlying file, which must be seekable. +If +.I key +is non-NULL and matches a file already being mapped, the +.I fd +argument is ignored. +.P +The +.I pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.I maxcache +argument is the maximum number of pages from the underlying file to cache +at any one time. +This value is not relative to the number of processes which share a file's +buffers, but will be the largest value specified by any of the processes +sharing the file. +.P +The +.BR mpool_filter () +function is intended to make transparent input and output processing of the +pages possible. +If the +.I pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.I pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are called with the +.I pgcookie +pointer, the page number and a pointer to the page to being read or written. +.P +The function +.BR mpool_new () +takes an +.I MPOOL +pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.I pgnoaddr +address. +Otherwise, NULL is returned and +.I errno +is set. +.P +The function +.BR mpool_get () +takes an +.I MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, NULL is returned and +.I errno +is set. +The +.I flags +argument is not currently used. +.P +The function +.BR mpool_put () +unpins the page referenced by +.IR pgaddr . +.I pgaddr +must be an address previously returned by +.BR mpool_get () +or +.BR mpool_new (). +The flag value is specified by ORing +any of the following values: +.TP +.B MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.P +.BR mpool_put () +returns 0 on success and \-1 if an error occurs. +.P +The function +.BR mpool_sync () +writes all modified pages associated with the +.I MPOOL +pointer to the +backing file. +.BR mpool_sync () +returns 0 on success and \-1 if an error occurs. +.P +The +.BR mpool_close () +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.B not +written to the backing file. +.BR mpool_close () +returns 0 on success and \-1 if an error occurs. +.SH ERRORS +The +.BR mpool_open () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR malloc (3). +.P +The +.BR mpool_get () +function may fail and set +.I errno +for the following: +.TP 15 +.B EINVAL +The requested record doesn't exist. +.P +The +.BR mpool_new () +and +.BR mpool_get () +functions may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +and +.BR malloc (3). +.P +The +.BR mpool_sync () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR write (2). +.P +The +.BR mpool_close () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR free (3). +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR recno (3) diff --git a/man/man3/mprobe.3 b/man/man3/mprobe.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mprobe.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/mq_close.3 b/man/man3/mq_close.3 new file mode 100644 index 0000000..8ec220f --- /dev/null +++ b/man/man3/mq_close.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_close \- close a message queue descriptor +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.P +.BI "int mq_close(mqd_t " mqdes ); +.fi +.SH DESCRIPTION +.BR mq_close () +closes the message queue descriptor +.IR mqdes . +.P +If the calling process has attached a notification request (see +.BR mq_notify (3)) +to this message queue via +.IR mqdes , +then this request is removed, +and another process can now attach a notification request. +.SH RETURN VALUE +On success +.BR mq_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +All open message queues are automatically closed on process termination, +or upon +.BR execve (2). +.SH SEE ALSO +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_getattr.3 b/man/man3/mq_getattr.3 new file mode 100644 index 0000000..d6d5996 --- /dev/null +++ b/man/man3/mq_getattr.3 @@ -0,0 +1,229 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_getattr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_getattr, mq_setattr \- get/set message queue attributes +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.P +.BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr ); +.BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr , +.BI " struct mq_attr *restrict " oldattr ); +.fi +.SH DESCRIPTION +.BR mq_getattr () +and +.BR mq_setattr () +respectively retrieve and modify attributes of the message queue +referred to by the message queue descriptor +.IR mqdes . +.P +.BR mq_getattr () +returns an +.I mq_attr +structure in the buffer pointed by +.IR attr . +This structure is defined as: +.P +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags: 0 or O_NONBLOCK */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue */ +}; +.EE +.in +.P +The +.I mq_flags +field contains flags associated with the open message queue description. +This field is initialized when the queue is created by +.BR mq_open (3). +The only flag that can appear in this field is +.BR O_NONBLOCK . +.P +The +.I mq_maxmsg +and +.I mq_msgsize +fields are set when the message queue is created by +.BR mq_open (3). +The +.I mq_maxmsg +field is an upper limit on the number of messages +that may be placed on the queue using +.BR mq_send (3). +The +.I mq_msgsize +field is an upper limit on the size of messages +that may be placed on the queue. +Both of these fields must have a value greater than zero. +Two +.I /proc +files that place ceilings on the values for these fields are described in +.BR mq_overview (7). +.P +The +.I mq_curmsgs +field returns the number of messages currently held in the queue. +.P +.BR mq_setattr () +sets message queue attributes using information supplied in the +.I mq_attr +structure pointed to by +.IR newattr . +The only attribute that can be modified is the setting of the +.B O_NONBLOCK +flag in +.IR mq_flags . +The other fields in +.I newattr +are ignored. +If the +.I oldattr +field is not NULL, +then the buffer that it points to is used to return an +.I mq_attr +structure that contains the same information that is returned by +.BR mq_getattr (). +.SH RETURN VALUE +On success +.BR mq_getattr () +and +.BR mq_setattr () +return 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EINVAL +.I newattr\->mq_flags +contained set bits other than +.BR O_NONBLOCK . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_getattr (), +.BR mq_setattr () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_getattr () +and +.BR mq_setattr () +are library functions layered on top of the +.BR mq_getsetattr (2) +system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The program below can be used to show the default +.I mq_maxmsg +and +.I mq_msgsize +values that are assigned to a message queue that is created with a call to +.BR mq_open (3) +in which the +.I attr +argument is NULL. +Here is an example run of the program: +.P +.in +4n +.EX +$ \fB./a.out /testq\fP +Maximum # of messages on queue: 10 +Maximum message size: 8192 +.EE +.in +.P +Since Linux 3.5, the following +.I /proc +files (described in +.BR mq_overview (7)) +can be used to control the defaults: +.P +.in +4n +.EX +$ \fBuname \-sr\fP +Linux 3.8.0 +$ \fBcat /proc/sys/fs/mqueue/msg_default\fP +10 +$ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP +8192 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mq_getattr.c) +.EX +#include <fcntl.h> +#include <mqueue.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/stat.h> +#include <unistd.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + mqd_t mqd; + struct mq_attr attr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s mq\-name\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + mqd = mq_open(argv[1], O_CREAT | O_EXCL, 0600, NULL); + if (mqd == (mqd_t) \-1) + errExit("mq_open"); +\& + if (mq_getattr(mqd, &attr) == \-1) + errExit("mq_getattr"); +\& + printf("Maximum # of messages on queue: %ld\en", attr.mq_maxmsg); + printf("Maximum message size: %ld\en", attr.mq_msgsize); +\& + if (mq_unlink(argv[1]) == \-1) + errExit("mq_unlink"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mq_close (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_notify.3 b/man/man3/mq_notify.3 new file mode 100644 index 0000000..7c4dc50 --- /dev/null +++ b/man/man3/mq_notify.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_notify 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_notify \- register for notification when a message is available +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.BR "#include <signal.h> " "/* Definition of SIGEV_* constants */" +.P +.BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp ); +.fi +.SH DESCRIPTION +.BR mq_notify () +allows the calling process to register or unregister for delivery of +an asynchronous notification when a new message arrives on +the empty message queue referred to by the message queue descriptor +.IR mqdes . +.P +The +.I sevp +argument is a pointer to a +.I sigevent +structure. +For the definition and general details of this structure, see +.BR sigevent (3type). +.P +If +.I sevp +is a non-null pointer, then +.BR mq_notify () +registers the calling process to receive message notification. +The +.I sigev_notify +field of the +.I sigevent +structure to which +.I sevp +points specifies how notification is to be performed. +This field has one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: the calling process is registered as the target +for notification, but when a message arrives, no notification is sent. +.\" When is SIGEV_NONE useful? +.TP +.B SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +See +.BR sigevent (3type) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_MESGQ . +In addition, +.\" I don't know of other implementations that set +.\" si_pid and si_uid -- MTK +.I si_pid +will be set to the PID of the process that sent the message, and +.I si_uid +will be set to the real user ID of the sending process. +.TP +.B SIGEV_THREAD +Upon message delivery, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (3type) +for details. +.P +Only one process can be registered to receive notification +from a message queue. +.P +If +.I sevp +is NULL, and the calling process is currently registered to receive +notifications for this message queue, then the registration is removed; +another process can then register to receive a message notification +for this queue. +.P +Message notification occurs only when a new message arrives and +the queue was previously empty. +If the queue was not empty at the time +.BR mq_notify () +was called, then a notification will occur only after +the queue is emptied and a new message arrives. +.P +If another process or thread is waiting to read a message +from an empty queue using +.BR mq_receive (3), +then any message notification registration is ignored: +the message is delivered to the process or thread calling +.BR mq_receive (3), +and the message notification registration remains in effect. +.P +Notification occurs once: after a notification is delivered, +the notification registration is removed, +and another process can register for message notification. +If the notified process wishes to receive the next notification, +it can use +.BR mq_notify () +to request a further notification. +This should be done before emptying all unread messages from the queue. +(Placing the queue in nonblocking mode is useful for emptying +the queue of messages without blocking once it is empty.) +.SH RETURN VALUE +On success +.BR mq_notify () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EBUSY +Another process has already registered to receive notification +for this message queue. +.TP +.B EINVAL +.I sevp\->sigev_notify +is not one of the permitted values; or +.I sevp\->sigev_notify +is +.B SIGEV_SIGNAL +and +.I sevp\->sigev_signo +is not a valid signal number. +.TP +.B ENOMEM +Insufficient memory. +.P +POSIX.1-2008 says that an implementation +.I may +generate an +.B EINVAL +.\" Linux does not do this +error if +.I sevp +is NULL, and the caller is not currently registered to receive +notifications for the queue +.IR mqdes . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_notify () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +In the glibc implementation, the +.BR mq_notify () +library function is implemented on top of the system call of the same name. +When +.I sevp +is NULL, or specifies a notification mechanism other than +.BR SIGEV_THREAD , +the library function directly invokes the system call. +For +.BR SIGEV_THREAD , +much of the implementation resides within the library, +rather than the kernel. +(This is necessarily so, +since the thread involved in handling the notification is one +that must be managed by the C library POSIX threads implementation.) +The implementation involves the use of a raw +.BR netlink (7) +socket and creates a new thread for each notification that is +delivered to the process. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The following program registers a notification request for the +message queue named in its command-line argument. +Notification is performed by creating a thread. +The thread executes a function which reads one message from the +queue and then terminates the process. +.SS Program source +.\" SRC BEGIN (mq_notify.c) +.EX +#include <mqueue.h> +#include <pthread.h> +#include <signal.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void /* Thread start function */ +tfunc(union sigval sv) +{ + struct mq_attr attr; + ssize_t nr; + void *buf; + mqd_t mqdes = *((mqd_t *) sv.sival_ptr); +\& + /* Determine max. msg size; allocate buffer to receive msg */ +\& + if (mq_getattr(mqdes, &attr) == \-1) + handle_error("mq_getattr"); + buf = malloc(attr.mq_msgsize); + if (buf == NULL) + handle_error("malloc"); +\& + nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); + if (nr == \-1) + handle_error("mq_receive"); +\& + printf("Read %zd bytes from MQ\en", nr); + free(buf); + exit(EXIT_SUCCESS); /* Terminate the process */ +} +\& +int +main(int argc, char *argv[]) +{ + mqd_t mqdes; + struct sigevent sev; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s <mq\-name>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + mqdes = mq_open(argv[1], O_RDONLY); + if (mqdes == (mqd_t) \-1) + handle_error("mq_open"); +\& + sev.sigev_notify = SIGEV_THREAD; + sev.sigev_notify_function = tfunc; + sev.sigev_notify_attributes = NULL; + sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ + if (mq_notify(mqdes, &sev) == \-1) + handle_error("mq_notify"); +\& + pause(); /* Process will be terminated by thread function */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7), +.BR sigevent (3type) diff --git a/man/man3/mq_open.3 b/man/man3/mq_open.3 new file mode 100644 index 0000000..8dde565 --- /dev/null +++ b/man/man3/mq_open.3 @@ -0,0 +1,298 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_open \- open a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#include <fcntl.h>" " /* For O_* constants */" +.BR "#include <sys/stat.h>" " /* For mode constants */" +.B #include <mqueue.h> +.P +.BI "mqd_t mq_open(const char *" name ", int " oflag ); +.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , +.BI " struct mq_attr *" attr ); +.fi +.SH DESCRIPTION +.BR mq_open () +creates a new POSIX message queue or opens an existing queue. +The queue is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR mq_overview (7). +.P +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR <fcntl.h> .) +Exactly one of the following must be specified in +.IR oflag : +.TP +.B O_RDONLY +Open the queue to receive messages only. +.TP +.B O_WRONLY +Open the queue to send messages only. +.TP +.B O_RDWR +Open the queue to both send and receive messages. +.P +Zero or more of the following flags can additionally be +.IR OR ed +in +.IR oflag : +.TP +.BR O_CLOEXEC " (since Linux 2.6.26)" +.\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a +Set the close-on-exec flag for the message queue descriptor. +See +.BR open (2) +for a discussion of why this flag is useful. +.TP +.B O_CREAT +Create the message queue if it does not exist. +The owner (user ID) of the message queue is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +.TP +.B O_EXCL +If +.B O_CREAT +was specified in +.IR oflag , +and a queue with the given +.I name +already exists, then fail with the error +.BR EEXIST . +.TP +.B O_NONBLOCK +Open the queue in nonblocking mode. +In circumstances where +.BR mq_receive (3) +and +.BR mq_send (3) +would normally block, these functions instead fail with the error +.BR EAGAIN . +.P +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new queue, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR <sys/stat.h> .) +The permissions settings are masked against the process umask. +.P +The fields of the +.I struct mq_attr +pointed to +.I attr +specify the maximum number of messages and +the maximum size of messages that the queue will allow. +This structure is defined as follows: +.P +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags (ignored for mq_open()) */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue + (ignored for mq_open()) */ +}; +.EE +.in +.P +Only the +.I mq_maxmsg +and +.I mq_msgsize +fields are employed when calling +.BR mq_open (); +the values in the remaining fields are ignored. +.P +If +.I attr +is NULL, then the queue is created with implementation-defined +default attributes. +Since Linux 3.5, two +.I /proc +files can be used to control these defaults; see +.BR mq_overview (7) +for details. +.SH RETURN VALUE +On success, +.BR mq_open () +returns a message queue descriptor for use by other +message queue functions. +On error, +.BR mq_open () +returns +.IR "(mqd_t)\ \-1", +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The queue exists, but the caller does not have permission to +open it in the specified mode. +.TP +.B EACCES +.I name +contained more than one slash. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a queue with this +.I name +already exists. +.TP +.B EINVAL +.\" glibc checks whether the name starts with a "/" and if not, +.\" gives this error +.I name +doesn't follow the format in +.BR mq_overview (7). +.TP +.B EINVAL +.B O_CREAT +was specified in +.IR oflag , +and +.I attr +was not NULL, but +.I attr\->mq_maxmsg +or +.I attr\->mq_msqsize +was invalid. +Both of these fields must be greater than zero. +In a process that is unprivileged (does not have the +.B CAP_SYS_RESOURCE +capability), +.I attr\->mq_maxmsg +must be less than or equal to the +.I msg_max +limit, and +.I attr\->mq_msgsize +must be less than or equal to the +.I msgsize_max +limit. +In addition, even in a privileged process, +.I attr\->mq_maxmsg +cannot exceed the +.B HARD_MAX +limit. +(See +.BR mq_overview (7) +for details of these limits.) +.TP +.B EMFILE +The per-process limit on the number of open file +and message queue descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files +and message queues has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.IR oflag , +and no queue with this +.I name +exists. +.TP +.B ENOENT +.I name +was just "/" followed by no other characters. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B ENOMEM +Insufficient memory. +.TP +.B ENOSPC +Insufficient space for the creation of a new message queue. +This probably occurred because the +.I queues_max +limit was encountered; see +.BR mq_overview (7). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_open () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +The +.BR mq_open () +library function is implemented on top of a system call of the same name. +The library function performs the check that the +.I name +starts with a slash (/), giving the +.B EINVAL +error if it does not. +The kernel system call expects +.I name +to contain no preceding slash, +so the C library function passes +.I name +without the preceding slash (i.e., +.IR name+1 ) +to the system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +Before Linux 2.6.14, +the process umask was not applied to the permissions specified in +.IR mode . +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_receive.3 b/man/man3/mq_receive.3 new file mode 100644 index 0000000..368177f --- /dev/null +++ b/man/man3/mq_receive.3 @@ -0,0 +1,163 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_receive 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_receive, mq_timedreceive \- receive a message from a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.P +.BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int *" msg_prio ); +.P +.B #include <time.h> +.B #include <mqueue.h> +.P +.BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \ +char *restrict " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int *restrict " msg_prio , +.BI " const struct timespec *restrict " abs_timeout ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mq_timedreceive (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR mq_receive () +removes the oldest message with the highest priority from +the message queue referred to by the message queue descriptor +.IR mqdes , +and places it in the buffer pointed to by +.IR msg_ptr . +The +.I msg_len +argument specifies the size of the buffer pointed to by +.IR msg_ptr ; +this must be greater than or equal to the +.I mq_msgsize +attribute of the queue (see +.BR mq_getattr (3)). +If +.I msg_prio +is not NULL, then the buffer to which it points is used +to return the priority associated with the received message. +.P +If the queue is empty, then, by default, +.BR mq_receive () +blocks until a message becomes available, +or the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.P +.BR mq_timedreceive () +behaves just like +.BR mq_receive (), +except that if the queue is empty and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in a +.BR timespec (3) +structure. +.P +If no message is available, +and the timeout has already expired by the time of the call, +.BR mq_timedreceive () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_receive () +and +.BR mq_timedreceive () +return the number of bytes in the received message; +on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was empty, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for reading. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was less than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_receive (), +.BR mq_timedreceive () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_timedreceive () +is a system call, and +.BR mq_receive () +is a library function layered on top of that system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR timespec (3), +.BR mq_overview (7), +.BR time (7) diff --git a/man/man3/mq_send.3 b/man/man3/mq_send.3 new file mode 100644 index 0000000..de182b9 --- /dev/null +++ b/man/man3/mq_send.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_send 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_send, mq_timedsend \- send a message to a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.P +.BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int " msg_prio ); +.P +.B #include <time.h> +.B #include <mqueue.h> +.P +.BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int " msg_prio , +.BI " const struct timespec *" abs_timeout ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mq_timedsend (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR mq_send () +adds the message pointed to by +.I msg_ptr +to the message queue referred to by the message queue descriptor +.IR mqdes . +The +.I msg_len +argument specifies the length of the message pointed to by +.IR msg_ptr ; +this length must be less than or equal to the queue's +.I mq_msgsize +attribute. +Zero-length messages are allowed. +.P +The +.I msg_prio +argument is a nonnegative integer that specifies the priority +of this message. +Messages are placed on the queue in decreasing order of priority, +with newer messages of the same priority being placed after +older messages with the same priority. +See +.BR mq_overview (7) +for details on the range for the message priority. +.P +If the message queue is already full +(i.e., the number of messages on the queue equals the queue's +.I mq_maxmsg +attribute), then, by default, +.BR mq_send () +blocks until sufficient space becomes available to allow the message +to be queued, or until the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.P +.BR mq_timedsend () +behaves just like +.BR mq_send (), +except that if the queue is full and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in a +.BR timespec (3) +structure. +.P +If the message queue is full, +and the timeout has already expired by the time of the call, +.BR mq_timedsend () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_send () +and +.BR mq_timedsend () +return zero; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was full, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for writing. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was greater than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_send (), +.BR mq_timedsend () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_timedsend () +is a system call, and +.BR mq_send () +is a library function layered on top of that system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_unlink (3), +.BR timespec (3), +.BR mq_overview (7), +.BR time (7) diff --git a/man/man3/mq_setattr.3 b/man/man3/mq_setattr.3 new file mode 100644 index 0000000..a3818a2 --- /dev/null +++ b/man/man3/mq_setattr.3 @@ -0,0 +1 @@ +.so man3/mq_getattr.3 diff --git a/man/man3/mq_timedreceive.3 b/man/man3/mq_timedreceive.3 new file mode 100644 index 0000000..9fed5f2 --- /dev/null +++ b/man/man3/mq_timedreceive.3 @@ -0,0 +1 @@ +.so man3/mq_receive.3 diff --git a/man/man3/mq_timedsend.3 b/man/man3/mq_timedsend.3 new file mode 100644 index 0000000..28b1eff --- /dev/null +++ b/man/man3/mq_timedsend.3 @@ -0,0 +1 @@ +.so man3/mq_send.3 diff --git a/man/man3/mq_unlink.3 b/man/man3/mq_unlink.3 new file mode 100644 index 0000000..4cdb604 --- /dev/null +++ b/man/man3/mq_unlink.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_unlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_unlink \- remove a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <mqueue.h> +.P +.BI "int mq_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR mq_unlink () +removes the specified message queue +.IR name . +The message queue name is removed immediately. +The queue itself is destroyed once any other processes that have +the queue open close their descriptors referring to the queue. +.SH RETURN VALUE +On success +.BR mq_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this message queue. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no message queue with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_unlink () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_overview (7) diff --git a/man/man3/mrand48.3 b/man/man3/mrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/mrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/mrand48_r.3 b/man/man3/mrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/mrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/mtrace.3 b/man/man3/mtrace.3 new file mode 100644 index 0000000..d332cc1 --- /dev/null +++ b/man/man3/mtrace.3 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mtrace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mtrace, muntrace \- malloc tracing +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <mcheck.h>" +.P +.B "void mtrace(void);" +.B "void muntrace(void);" +.fi +.SH DESCRIPTION +The +.BR mtrace () +function installs hook functions for the memory-allocation functions +.RB ( malloc (3), +.BR realloc (3) +.BR memalign (3), +.BR free (3)). +These hook functions record tracing information about memory allocation +and deallocation. +The tracing information can be used to discover memory leaks and +attempts to free nonallocated memory in a program. +.P +The +.BR muntrace () +function disables the hook functions installed by +.BR mtrace (), +so that tracing information is no longer recorded +for the memory-allocation functions. +If no hook functions were successfully installed by +.BR mtrace (), +.BR muntrace () +does nothing. +.P +When +.BR mtrace () +is called, it checks the value of the environment variable +.BR MALLOC_TRACE , +which should contain the pathname of a file in which +the tracing information is to be recorded. +If the pathname is successfully opened, it is truncated to zero length. +.P +If +.B MALLOC_TRACE +is not set, +or the pathname it specifies is invalid or not writable, +then no hook functions are installed, and +.BR mtrace () +has no effect. +In set-user-ID and set-group-ID programs, +.B MALLOC_TRACE +is ignored, and +.BR mtrace () +has no effect. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mtrace (), +.BR muntrace () +T} Thread safety MT-Unsafe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" markings in glibc manual are more detailed: +.\" +.\" mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init +.\" muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale +.\" +.\" But there is something wrong in glibc manual, for example: +.\" glibc manual says muntrace should have marking locale because it calls +.\" fprintf(), but muntrace does not execute area which cause locale problem. +.SH STANDARDS +GNU. +.SH NOTES +In normal usage, +.BR mtrace () +is called once at the start of execution of a program, and +.BR muntrace () +is never called. +.P +The tracing output produced after a call to +.BR mtrace () +is textual, but not designed to be human readable. +The GNU C library provides a Perl script, +.BR mtrace (1), +that interprets the trace log and produces human-readable output. +For best results, +the traced program should be compiled with debugging enabled, +so that line-number information is recorded in the executable. +.P +The tracing performed by +.BR mtrace () +incurs a performance penalty (if +.B MALLOC_TRACE +points to a valid, writable pathname). +.SH BUGS +The line-number information produced by +.BR mtrace (1) +is not always precise: +the line number references may refer to the previous or following (nonblank) +line of the source code. +.SH EXAMPLES +The shell session below demonstrates the use of the +.BR mtrace () +function and the +.BR mtrace (1) +command in a program that has memory leaks at two different locations. +The demonstration uses the following program: +.P +.in +4n +.RB "$ " "cat t_mtrace.c" +.\" SRC BEGIN (t_mtrace.c) +.EX +#include <mcheck.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + mtrace(); +\& + for (unsigned int j = 0; j < 2; j++) + malloc(100); /* Never freed\-\-a memory leak */ +\& + calloc(16, 16); /* Never freed\-\-a memory leak */ + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.P +When we run the program as follows, we see that +.BR mtrace () +diagnosed memory leaks at two different locations in the program: +.P +.in +4n +.EX +.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace" +.RB "$ " "export MALLOC_TRACE=/tmp/t" +.RB "$ " "./t_mtrace" +.RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE" +Memory not freed: +-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Address Size Caller +0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16 +.EE +.in +.P +The first two messages about unfreed memory correspond to the two +.BR malloc (3) +calls inside the +.I for +loop. +The final message corresponds to the call to +.BR calloc (3) +(which in turn calls +.BR malloc (3)). +.SH SEE ALSO +.BR mtrace (1), +.BR malloc (3), +.BR malloc_hook (3), +.BR mcheck (3) diff --git a/man/man3/muntrace.3 b/man/man3/muntrace.3 new file mode 100644 index 0000000..2b03d10 --- /dev/null +++ b/man/man3/muntrace.3 @@ -0,0 +1 @@ +.so man3/mtrace.3 diff --git a/man/man3/nan.3 b/man/man3/nan.3 new file mode 100644 index 0000000..2fb8bc5 --- /dev/null +++ b/man/man3/nan.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" +.\" Corrections by aeb +.\" +.TH nan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nan, nanf, nanl \- return 'Not a Number' +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double nan(const char *" tagp ); +.BI "float nanf(const char *" tagp ); +.BI "long double nanl(const char *" tagp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nan (), +.BR nanf (), +.BR nanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return a representation (determined by +.IR tagp ) +of a quiet NaN. +If the implementation does not support +quiet NaNs, these functions return zero. +.P +The call +.I nan("char\-sequence") +is equivalent to: +.P +.in +4n +.EX +strtod("NAN(char\-sequence)", NULL); +.EE +.in +.P +Similarly, calls to +.BR nanf () +and +.BR nanl () +are equivalent to analogous calls to +.BR strtof (3) +and +.BR strtold (3). +.P +The argument +.I tagp +is used in an unspecified manner. +On IEEE 754 systems, there are many representations of NaN, and +.I tagp +selects one. +On other systems it may do nothing. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nan (), +.BR nanf (), +.BR nanl () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.P +See also IEC 559 and the appendix with +recommended functions in IEEE 754/IEEE 854. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR isnan (3), +.BR strtod (3), +.BR math_error (7) diff --git a/man/man3/nanf.3 b/man/man3/nanf.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man/man3/nanf.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man/man3/nanl.3 b/man/man3/nanl.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man/man3/nanl.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man/man3/nearbyint.3 b/man/man3/nearbyint.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyint.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/nearbyintf.3 b/man/man3/nearbyintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/nearbyintl.3 b/man/man3/nearbyintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/netlink.3 b/man/man3/netlink.3 new file mode 100644 index 0000000..0722568 --- /dev/null +++ b/man/man3/netlink.3 @@ -0,0 +1,87 @@ +.\" This manpage copyright 1998 by Andi Kleen. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on the original comments from Alexey Kuznetsov +.\" $Id: netlink.3,v 1.1 1999/05/14 17:17:24 freitag Exp $ +.\" +.TH netlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +netlink \- Netlink macros +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <asm/types.h> +.B #include <linux/netlink.h> +.P +.BI "int NLMSG_ALIGN(size_t " len ); +.BI "int NLMSG_LENGTH(size_t " len ); +.BI "int NLMSG_SPACE(size_t " len ); +.BI "void *NLMSG_DATA(struct nlmsghdr *" nlh ); +.BI "struct nlmsghdr *NLMSG_NEXT(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_OK(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_PAYLOAD(struct nlmsghdr *" nlh ", int " len ); +.fi +.SH DESCRIPTION +.I <linux/netlink.h> +defines several standard macros to access or create a netlink datagram. +They are similar in spirit to the macros defined in +.BR cmsg (3) +for auxiliary data. +The buffer passed to and from a netlink socket should +be accessed using only these macros. +.TP +.BR NLMSG_ALIGN () +Round the length of a netlink message up to align it properly. +.TP +.BR NLMSG_LENGTH () +Given the payload length, +.IR len , +this macro returns the aligned length to store in the +.I nlmsg_len +field of the +.IR nlmsghdr . +.TP +.BR NLMSG_SPACE () +Return the number of bytes that a netlink message with payload of +.I len +would occupy. +.TP +.BR NLMSG_DATA () +Return a pointer to the payload associated with the passed +.IR nlmsghdr . +.TP +.\" this is bizarre, maybe the interface should be fixed. +.BR NLMSG_NEXT () +Get the next +.I nlmsghdr +in a multipart message. +The caller must check if the current +.I nlmsghdr +didn't have the +.B NLMSG_DONE +set\[em]this function doesn't return NULL on end. +The +.I len +argument is an lvalue containing the remaining length +of the message buffer. +This macro decrements it by the length of the message header. +.TP +.BR NLMSG_OK () +Return true if the netlink message is not truncated and +is in a form suitable for parsing. +.TP +.BR NLMSG_PAYLOAD () +Return the length of the payload associated with the +.IR nlmsghdr . +.SH VERSIONS +It is often better to use netlink via +.I libnetlink +than via the low-level kernel interface. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR libnetlink (3), +.BR netlink (7) diff --git a/man/man3/newlocale.3 b/man/man3/newlocale.3 new file mode 100644 index 0000000..198120f --- /dev/null +++ b/man/man3/newlocale.3 @@ -0,0 +1,356 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH newlocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +newlocale, freelocale \- create, modify, and free a locale object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.BI "locale_t newlocale(int " category_mask ", const char *" locale , +.BI " locale_t " base ); +.BI "void freelocale(locale_t " locobj ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR newlocale (), +.BR freelocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR newlocale () +function creates a new locale object, or modifies an existing object, +returning a reference to the new or modified object as the function result. +Whether the call creates a new object or modifies an existing object +is determined by the value of +.IR base : +.IP \[bu] 3 +If +.I base +is +.IR "(locale_t)\ 0" , +a new object is created. +.IP \[bu] +If +.I base +refers to valid existing locale object +(i.e., an object returned by a previous call to +.BR newlocale () +or +.BR duplocale (3)), +then that object is modified by the call. +If the call is successful, the contents of +.I base +are unspecified (in particular, the object referred to by +.I base +may be freed, and a new object created). +Therefore, the caller should ensure that it stops using +.I base +before the call to +.BR newlocale (), +and should subsequently refer to the modified object via the +reference returned as the function result. +If the call fails, the contents of +.I base +remain valid and unchanged. +.P +If +.I base +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)), +or is not +.I (locale_t)\ 0 +and is not a valid locale object handle, +the behavior is undefined. +.P +The +.I category_mask +argument is a bit mask that specifies the locale categories +that are to be set in a newly created locale object +or modified in an existing object. +The mask is constructed by a bitwise OR of the constants +.BR LC_ADDRESS_MASK , +.BR LC_CTYPE_MASK , +.BR LC_COLLATE_MASK , +.BR LC_IDENTIFICATION_MASK , +.BR LC_MEASUREMENT_MASK , +.BR LC_MESSAGES_MASK , +.BR LC_MONETARY_MASK , +.BR LC_NUMERIC_MASK , +.BR LC_NAME_MASK , +.BR LC_PAPER_MASK , +.BR LC_TELEPHONE_MASK , +and +.BR LC_TIME_MASK . +Alternatively, the mask can be specified as +.BR LC_ALL_MASK , +which is equivalent to ORing all of the preceding constants. +.P +For each category specified in +.IR category_mask , +the locale data from +.I locale +will be used in the object returned by +.BR newlocale (). +If a new locale object is being created, +data for all categories not specified in +.I category_mask +is taken from the default ("POSIX") locale. +.P +The following preset values of +.I locale +are defined for all categories that can be specified in +.IR category_mask : +.TP +"POSIX" +A minimal locale environment for C language programs. +.TP +"C" +Equivalent to "POSIX". +.TP +"" +An implementation-defined native environment +corresponding to the values of the +.B LC_* +and +.B LANG +environment variables (see +.BR locale (7)). +.SS freelocale() +The +.BR freelocale () +function deallocates the resources associated with +.IR locobj , +a locale object previously returned by a call to +.BR newlocale () +or +.BR duplocale (3). +If +.I locobj +is +.B LC_GLOBAL_LOCALE +or is not valid locale object handle, the results are undefined. +.P +Once a locale object has been freed, +the program should make no further use of it. +.SH RETURN VALUE +On success, +.BR newlocale () +returns a handle that can be used in calls to +.BR duplocale (3), +.BR freelocale (), +and other functions that take a +.I locale_t +argument. +On error, +.BR newlocale () +returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +One or more bits in +.I category_mask +do not correspond to a valid locale category. +.TP +.B EINVAL +.I locale +is NULL. +.TP +.B ENOENT +.I locale +is not a string pointer referring to a valid locale. +.TP +.B ENOMEM +Insufficient memory to create a locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +.SH NOTES +Each locale object created by +.BR newlocale () +should be deallocated using +.BR freelocale (). +.SH EXAMPLES +The program below takes up to two command-line arguments, +which each identify locales. +The first argument is required, and is used to set the +.B LC_NUMERIC +category in a locale object created using +.BR newlocale (). +The second command-line argument is optional; +if it is present, it is used to set the +.B LC_TIME +category of the locale object. +.P +Having created and initialized the locale object, +the program then applies it using +.BR uselocale (3), +and then tests the effect of the locale changes by: +.IP (1) 5 +Displaying a floating-point number with a fractional part. +This output will be affected by the +.B LC_NUMERIC +setting. +In many European-language locales, +the fractional part of the number is separated from the integer part +using a comma, rather than a period. +.IP (2) +Displaying the date. +The format and language of the output will be affected by the +.B LC_TIME +setting. +.P +The following shell sessions show some example runs of this program. +.P +Set the +.B LC_NUMERIC +category to +.I fr_FR +(French): +.P +.in +4n +.EX +$ \fB./a.out fr_FR\fP +123456,789 +Fri Mar 7 00:25:08 2014 +.EE +.in +.P +Set the +.B LC_NUMERIC +category to +.I fr_FR +(French), +and the +.B LC_TIME +category to +.I it_IT +(Italian): +.P +.in +4n +.EX +$ \fB./a.out fr_FR it_IT\fP +123456,789 +ven 07 mar 2014 00:26:01 CET +.EE +.in +.P +Specify the +.B LC_TIME +setting as an empty string, +which causes the value to be taken from environment variable settings +(which, here, specify +.IR mi_NZ , +New Zealand Māori): +.P +.in +4n +.EX +$ LC_ALL=mi_NZ ./a.out fr_FR "" +123456,789 +Te Paraire, te 07 o Poutū\-te\-rangi, 2014 00:38:44 CET +.EE +.in +.SS Program source +.\" SRC BEGIN (newlocale.c) +.EX +#define _XOPEN_SOURCE 700 +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + char buf[100]; + time_t t; + size_t s; + struct tm *tm; + locale_t loc, nloc; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s locale1 [locale2]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Create a new locale object, taking the LC_NUMERIC settings + from the locale specified in argv[1]. */ +\& + loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0); + if (loc == (locale_t) 0) + errExit("newlocale"); +\& + /* If a second command\-line argument was specified, modify the + locale object to take the LC_TIME settings from the locale + specified in argv[2]. We assign the result of this newlocale() + call to \[aq]nloc\[aq] rather than \[aq]loc\[aq], since in some cases, we might + want to preserve \[aq]loc\[aq] if this call fails. */ +\& + if (argc > 2) { + nloc = newlocale(LC_TIME_MASK, argv[2], loc); + if (nloc == (locale_t) 0) + errExit("newlocale"); + loc = nloc; + } +\& + /* Apply the newly created locale to this thread. */ +\& + uselocale(loc); +\& + /* Test effect of LC_NUMERIC. */ +\& + printf("%8.3f\en", 123456.789); +\& + /* Test effect of LC_TIME. */ +\& + t = time(NULL); + tm = localtime(&t); + if (tm == NULL) + errExit("time"); +\& + s = strftime(buf, sizeof(buf), "%c", tm); + if (s == 0) + errExit("strftime"); +\& + printf("%s\en", buf); +\& + /* Free the locale object. */ +\& + uselocale(LC_GLOBAL_LOCALE); /* So \[aq]loc\[aq] is no longer in use */ + freelocale(loc); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/nextafter.3 b/man/man3/nextafter.3 new file mode 100644 index 0000000..a48fa43 --- /dev/null +++ b/man/man3/nextafter.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" +.TH nextafter 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- +floating-point number manipulation +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double nextafter(double " x ", double " y ); +.BI "float nextafterf(float " x ", float " y ); +.BI "long double nextafterl(long double " x ", long double " y ); +.P +.BI "double nexttoward(double " x ", long double " y ); +.BI "float nexttowardf(float " x ", long double " y ); +.BI "long double nexttowardl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nextafter (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR nextafterf (), +.BR nextafterl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR nexttoward (), +.BR nexttowardf (), +.BR nexttowardl (): +.nf + _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR nextafter (), +.BR nextafterf (), +and +.BR nextafterl () +functions return the next representable floating-point value following +.I x +in the direction of +.IR y . +If +.I y +is less than +.IR x , +these functions will return the largest representable number less than +.IR x . +.P +If +.I x +equals +.IR y , +the functions return +.IR y . +.P +The +.BR nexttoward (), +.BR nexttowardf (), +and +.BR nexttowardl () +functions do the same as the corresponding +.BR nextafter () +functions, except that they have a +.I "long double" +second argument. +.SH RETURN VALUE +On success, +these functions return the next representable floating-point value after +.I x +in the direction of +.IR y . +.P +If +.I x +equals +.IR y , +then +.I y +(cast to the same type as +.IR x ) +is returned. +.P +If +.I x +or +.I y +is a NaN, +a NaN is returned. +.P +If +.I x +is finite, +.\" e.g., DBL_MAX +and the result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.P +If +.I x +is not equal to +.IR y , +and the correct function result would be subnormal, zero, or underflow, +a range error occurs, +and either the correct value (if it can be represented), +or 0.0, is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.\" e.g., nextafter(DBL_MAX, HUGE_VAL); +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result is subnormal or underflows +.\" e.g., nextafter(DBL_MIN, 0.0); +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nextafter (), +.BR nextafterf (), +.BR nextafterl (), +.BR nexttoward (), +.BR nexttowardf (), +.BR nexttowardl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH HISTORY +C99, POSIX.1-2001. +.SH BUGS +In glibc 2.5 and earlier, these functions do not raise an underflow +floating-point +.RB ( FE_UNDERFLOW ) +exception when an underflow occurs. +.P +Before glibc 2.23 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6799 +these functions did not set +.IR errno . +.SH SEE ALSO +.BR nearbyint (3) diff --git a/man/man3/nextafterf.3 b/man/man3/nextafterf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nextafterf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextafterl.3 b/man/man3/nextafterl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nextafterl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextdown.3 b/man/man3/nextdown.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdown.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextdownf.3 b/man/man3/nextdownf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdownf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextdownl.3 b/man/man3/nextdownl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdownl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nexttoward.3 b/man/man3/nexttoward.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttoward.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nexttowardf.3 b/man/man3/nexttowardf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttowardf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nexttowardl.3 b/man/man3/nexttowardl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttowardl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextup.3 b/man/man3/nextup.3 new file mode 100644 index 0000000..6c74a36 --- /dev/null +++ b/man/man3/nextup.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright (C) 2016, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH nextup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nextup, nextupf, nextupl, nextdown, nextdownf, nextdownl \- +return next floating-point number toward positive/negative infinity +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <math.h> +.P +.BI "double nextup(double " x ); +.BI "float nextupf(float " x ); +.BI "long double nextupl(long double " x ); +.P +.BI "double nextdown(double " x ); +.BI "float nextdownf(float " x ); +.BI "long double nextdownl(long double " x ); +.fi +.SH DESCRIPTION +The +.BR nextup (), +.BR nextupf (), +and +.BR nextupl () +functions return the next representable floating-point number greater than +.IR x . +.P +If +.I x +is the smallest representable negative number in the corresponding type, +these functions return \-0. +If +.I x +is 0, the returned value is the smallest representable positive number +of the corresponding type. +.P +If +.I x +is positive infinity, the returned value is positive infinity. +If +.I x +is negative infinity, +the returned value is the largest representable finite negative number +of the corresponding type. +.P +If +.I x +is Nan, +the returned value is NaN. +.P +The value returned by +.I nextdown(x) +is +.IR \-nextup(\-x) , +and similarly for the other types. +.SH RETURN VALUE +See DESCRIPTION. +.\" .SH ERRORS +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nextup (), +.BR nextupf (), +.BR nextupl (), +.BR nextdown (), +.BR nextdownf (), +.BR nextdownl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +These functions are described in +.I IEEE Std 754-2008 - Standard for Floating-Point Arithmetic +and +.IR "ISO/IEC TS 18661". +.SH HISTORY +glibc 2.24. +.SH SEE ALSO +.BR nearbyint (3), +.BR nextafter (3) diff --git a/man/man3/nextupf.3 b/man/man3/nextupf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextupf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextupl.3 b/man/man3/nextupl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextupl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nftw.3 b/man/man3/nftw.3 new file mode 100644 index 0000000..1a5c9c9 --- /dev/null +++ b/man/man3/nftw.3 @@ -0,0 +1 @@ +.so man3/ftw.3 diff --git a/man/man3/nl_langinfo.3 b/man/man3/nl_langinfo.3 new file mode 100644 index 0000000..fb1be16 --- /dev/null +++ b/man/man3/nl_langinfo.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 2001 Markus Kuhn <mkuhn@acm.org> +.\" and Copyright (c) 2015 Sam Varshavchik <mrsam@courier-mta.com> +.\" and Copyright (c) 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Corrected prototype, 2002-10-18, aeb +.\" +.TH nl_langinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nl_langinfo, nl_langinfo_l \- query language and locale information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <langinfo.h> +.P +.BI "char *nl_langinfo(nl_item " item ); +.BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nl_langinfo_l (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 200809L + glibc 2.23 and earlier: + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR nl_langinfo () +and +.BR nl_langinfo_l () +functions provide access to locale information +in a more flexible way than +.BR localeconv (3). +.BR nl_langinfo () +returns a string which is the value corresponding to +\fIitem\fP in the program's current global +locale. +.BR nl_langinfo_l () +returns a string which is the value corresponding to \fIitem\fP +for the locale identified by the locale object \fIlocale\fP, +which was previously created by +.BR newlocale (3). +Individual and additional elements of the locale categories can +be queried. +.P +Examples for the locale elements that can be specified in \fIitem\fP +using the constants defined in \fI<langinfo.h>\fP are: +.TP +.BR CODESET \ (LC_CTYPE) +Return a string with the name of the character encoding used in the +selected locale, such as "UTF\-8", "ISO\-8859\-1", or "ANSI_X3.4\-1968" +(better known as US-ASCII). +This is the same string that you get with +"locale charmap". +For a list of character encoding names, +try "locale \-m" (see +.BR locale (1)). +.TP +.BR D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent time and date in a locale-specific way +.RB ( %c +conversion specification). +.TP +.BR D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a date in a locale-specific way +.RB ( %x +conversion specification). +.TP +.BR T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a locale-specific way +.RB ( %X +conversion specification). +.TP +.BR AM_STR \ (LC_TIME) +Return a string that represents affix for ante meridiem (before noon, "AM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR PM_STR \ (LC_TIME) +Return a string that represents affix for post meridiem (before midnight, "PM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR T_FMT_AMPM \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a.m. or p.m. notation in a locale-specific way +.RB ( %r +conversion specification). +.TP +.BR ERA \ (LC_TIME) +Return era description, which contains information about how years are counted +and displayed for each era in a locale. +Each era description segment shall have the format: +.RS +.IP +.IR direction : offset : start_date : end_date : era_name : era_format +.RE +.IP +according to the definitions below: +.RS +.TP 12 +.I direction +Either a +.RB \[dq] + "\[dq] or a \[dq]" - \[dq] +character. +The +.RB \[dq] + \[dq] +means that years increase from the +.I start_date +towards the +.IR end_date , +.RB \[dq] - \[dq] +means the opposite. +.TP +.I offset +The epoch year of the +.IR start_date . +.TP +.I start_date +A date in the form +.IR yyyy / mm / dd , +where +.IR yyyy ", " mm ", and " dd +are the year, month, and day numbers respectively of the start of the era. +.TP +.I end_date +The ending date of the era, in the same format as the +.IR start_date , +or one of the two special values +.RB \[dq] -* \[dq] +(minus infinity) or +.RB \[dq] +* \[dq] +(plus infinity). +.TP +.I era_name +The name of the era, corresponding to the +.B %EC +.BR strftime (3) +conversion specification. +.TP +.I era_format +The format of the year in the era, corresponding to the +.B %EY +.BR strftime (3) +conversion specification. +.RE +.IP +Era description segments are separated by semicolons. +Most locales do not define this value. +Examples of locales that do define this value are the Japanese and Thai +locales. +.TP +.BR ERA_D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of time and date in a locale-specific way +.RB ( %Ec +conversion specification). +.TP +.BR ERA_D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a date in a locale-specific way +.RB ( %Ex +conversion specification). +.TP +.BR ERA_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a time in a locale-specific way +.RB ( %EX +conversion specification). +.TP +.BR DAY_ "{1\[en]7} (LC_TIME)" +Return name of the \fIn\fP-th day of the week. +[Warning: this follows +the US convention DAY_1 = Sunday, not the international convention +(ISO\~8601) that Monday is the first day of the week.] +(Used in +.B %A +.BR strftime (3) +conversion specification.) +.TP +.BR ABDAY_ "{1\[en]7} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th day of the week. +(Used in +.B %a +.BR strftime (3) +conversion specification.) +.TP +.BR MON_ "{1\[en]12} (LC_TIME)" +Return name of the \fIn\fP-th month. +(Used in +.B %B +.BR strftime (3) +conversion specification.) +.TP +.BR ABMON_ "{1\[en]12} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th month. +(Used in +.B %b +.BR strftime (3) +conversion specification.) +.TP +.BR RADIXCHAR \ (LC_NUMERIC) +Return radix character (decimal dot, decimal comma, etc.). +.TP +.BR THOUSEP \ (LC_NUMERIC) +Return separator character for thousands (groups of three digits). +.TP +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a positive response to a yes/no question. +.TP +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a negative response to a yes/no question. +.TP +.BR CRNCYSTR \ (LC_MONETARY) +Return the currency symbol, preceded by "\-" if the symbol should +appear before the value, "+" if the symbol should appear after the +value, or "." if the symbol should replace the radix character. +.P +The above list covers just some examples of items that can be requested. +For a more detailed list, consult +.IR "The GNU C Library Reference Manual" . +.SH RETURN VALUE +On success, these functions return a pointer to a string which +is the value corresponding to +.I item +in the specified locale. +.P +If no locale has been selected by +.BR setlocale (3) +for the appropriate category, +.BR nl_langinfo () +return a pointer to the corresponding string in the "C" locale. +The same is true of +.BR nl_langinfo_l () +if +.I locale +specifies a locale where +.I langinfo +data is not defined. +.P +If \fIitem\fP is not valid, a pointer to an empty string is returned. +.P +The pointer returned by these functions may point to static data that +may be overwritten, or the pointer itself may be invalidated, +by a subsequent call to +.BR nl_langinfo (), +.BR nl_langinfo_l (), +or +.BR setlocale (3). +The same statements apply to +.BR nl_langinfo_l () +if the locale object referred to by +.I locale +is freed or modified by +.BR freelocale (3) +or +.BR newlocale (3). +.P +POSIX specifies that the application may not modify +the string returned by these functions. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nl_langinfo () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +.SH NOTES +The behavior of +.BR nl_langinfo_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH EXAMPLES +The following program sets the character type and the numeric locale +according to the environment and queries the terminal character set and +the radix character. +.P +.\" SRC BEGIN (nl_langinfo.c) +.EX +#include <langinfo.h> +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + setlocale(LC_CTYPE, ""); + setlocale(LC_NUMERIC, ""); +\& + printf("%s\en", nl_langinfo(CODESET)); + printf("%s\en", nl_langinfo(RADIXCHAR)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR locale (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charsets (7), +.BR locale (7) +.P +The GNU C Library Reference Manual diff --git a/man/man3/nl_langinfo_l.3 b/man/man3/nl_langinfo_l.3 new file mode 100644 index 0000000..36c3e35 --- /dev/null +++ b/man/man3/nl_langinfo_l.3 @@ -0,0 +1 @@ +.so man3/nl_langinfo.3 diff --git a/man/man3/nrand48.3 b/man/man3/nrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/nrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/nrand48_r.3 b/man/man3/nrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/nrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/ntohl.3 b/man/man3/ntohl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/ntohl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/ntohs.3 b/man/man3/ntohs.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/ntohs.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/ntp_adjtime.3 b/man/man3/ntp_adjtime.3 new file mode 100644 index 0000000..b08b9c8 --- /dev/null +++ b/man/man3/ntp_adjtime.3 @@ -0,0 +1 @@ +.so man2/adjtimex.2 diff --git a/man/man3/ntp_gettime.3 b/man/man3/ntp_gettime.3 new file mode 100644 index 0000000..96ac817 --- /dev/null +++ b/man/man3/ntp_gettime.3 @@ -0,0 +1,135 @@ +'\" t +.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ntp_gettime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ntp_gettime, ntp_gettimex \- get time parameters (NTP daemon interface) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/timex.h> +.P +.BI "int ntp_gettime(struct ntptimeval *" ntv ); +.BI "int ntp_gettimex(struct ntptimeval *" ntv ); +.fi +.SH DESCRIPTION +Both of these APIs return information to the caller via the +.I ntv +argument, a structure of the following type: +.P +.in +4n +.EX +struct ntptimeval { + struct timeval time; /* Current time */ + long maxerror; /* Maximum error */ + long esterror; /* Estimated error */ + long tai; /* TAI offset */ +\& + /* Further padding bytes allowing for future expansion */ +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I time +The current time, expressed as a +.I timeval +structure: +.IP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* Seconds since the Epoch */ + suseconds_t tv_usec; /* Microseconds */ +}; +.EE +.in +.TP +.I maxerror +Maximum error, in microseconds. +This value can be initialized by +.BR ntp_adjtime (3), +and is increased periodically (on Linux: each second), +but is clamped to an upper limit (the kernel constant +.BR NTP_PHASE_MAX , +with a value of 16,000). +.TP +.I esterror +Estimated error, in microseconds. +This value can be set via +.BR ntp_adjtime (3) +to contain an estimate of the difference between the system clock +and the true time. +This value is not used inside the kernel. +.TP +.I tai +TAI (Atomic International Time) offset. +.P +.BR ntp_gettime () +returns an +.I ntptimeval +structure in which the +.IR time , +.IR maxerror , +and +.I esterror +fields are filled in. +.P +.BR ntp_gettimex () +performs the same task as +.BR ntp_gettime (), +but also returns information in the +.I tai +field. +.SH RETURN VALUE +The return values for +.BR ntp_gettime () +and +.BR ntp_gettimex () +are as for +.BR adjtimex (2). +Given a correct pointer argument, these functions always succeed. +.\" FIXME . the info page incorrectly describes the return values. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ntp_gettime (), +.BR ntp_gettimex () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR ntp_gettime () +NTP Kernel Application Program Interface. +.TP +.BR ntp_gettimex () +GNU. +.SH HISTORY +.TP +.BR ntp_gettime () +glibc 2.1. +.TP +.BR ntp_gettimex () +glibc 2.12. +.SH SEE ALSO +.BR adjtimex (2), +.BR ntp_adjtime (3), +.BR time (7) +.P +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE diff --git a/man/man3/ntp_gettimex.3 b/man/man3/ntp_gettimex.3 new file mode 100644 index 0000000..142d76b --- /dev/null +++ b/man/man3/ntp_gettimex.3 @@ -0,0 +1 @@ +.so man3/ntp_gettime.3 diff --git a/man/man3/offsetof.3 b/man/man3/offsetof.3 new file mode 100644 index 0000000..e9ce590 --- /dev/null +++ b/man/man3/offsetof.3 @@ -0,0 +1,110 @@ +.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" /usr/lib/gcc/i486-linux-gnu/4.1.1/include/stddef.h +.\" glibc-doc +.TH offsetof 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +offsetof \- offset of a structure member +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stddef.h> +.P +.BI "size_t offsetof(" type ", " member ); +.fi +.SH DESCRIPTION +The macro +.BR offsetof () +returns the offset of the field +.I member +from the start of the structure +.IR type . +.P +This macro is useful because the sizes of the fields that compose +a structure can vary across implementations, +and compilers may insert different numbers of padding +bytes between fields. +Consequently, an element's offset is not necessarily +given by the sum of the sizes of the previous elements. +.P +A compiler error will result if +.I member +is not aligned to a byte boundary +(i.e., it is a bit field). +.SH RETURN VALUE +.BR offsetof () +returns the offset of the given +.I member +within the given +.IR type , +in units of bytes. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH EXAMPLES +On a Linux/i386 system, when compiled using the default +.BR gcc (1) +options, the program below produces the following output: +.P +.in +4n +.EX +.RB "$" " ./a.out" +offsets: i=0; c=4; d=8 a=16 +sizeof(struct s)=16 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (offsetof.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + struct s { + int i; + char c; + double d; + char a[]; + }; +\& + /* Output is compiler dependent */ +\& + printf("offsets: i=%zu; c=%zu; d=%zu a=%zu\en", + offsetof(struct s, i), offsetof(struct s, c), + offsetof(struct s, d), offsetof(struct s, a)); + printf("sizeof(struct s)=%zu\en", sizeof(struct s)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END diff --git a/man/man3/on_exit.3 b/man/man3/on_exit.3 new file mode 100644 index 0000000..517c6e2 --- /dev/null +++ b/man/man3/on_exit.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-02, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.TH on_exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +on_exit \- register a function to be called at normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int on_exit(void (*" function ")(int, void *), void *" arg ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR on_exit (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR on_exit () +function registers the given +.I function +to be +called at normal process termination, whether via +.BR exit (3) +or via return from the program's +.IR main (). +The +.I function +is passed the status argument given to the last call to +.BR exit (3) +and the +.I arg +argument from +.BR on_exit (). +.P +The same function may be registered multiple times: +it is called once for each registration. +.P +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, all registrations are removed. +.SH RETURN VALUE +The +.BR on_exit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR on_exit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SunOS 4, glibc. +Removed in Solaris (SunOS 5). +Use the standard +.BR atexit (3) +instead. +.SH CAVEATS +By the time +.I function +is executed, stack +.RI ( auto ) +variables may already have gone out of scope. +Therefore, +.I arg +should not be a pointer to a stack variable; +it may however be a pointer to a heap variable or a global variable. +.SH SEE ALSO +.BR _exit (2), +.BR atexit (3), +.BR exit (3) diff --git a/man/man3/open_memstream.3 b/man/man3/open_memstream.3 new file mode 100644 index 0000000..d2a18ec --- /dev/null +++ b/man/man3/open_memstream.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream() +.\" +.TH open_memstream 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +open_memstream, open_wmemstream \- open a dynamic memory buffer stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); +.P +.B #include <wchar.h> +.P +.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR open_memstream (), +.BR open_wmemstream (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR open_memstream () +function opens a stream for writing to a memory buffer. +The function dynamically allocates the buffer, +and the buffer automatically grows as needed. +Initially, the buffer has a size of zero. +After closing the stream, the caller should +.BR free (3) +this buffer. +.P +The locations pointed to by +.I ptr +and +.I sizeloc +are used to report, respectively, +the current location and the size of the buffer. +The locations referred to by these pointers are updated +each time the stream is flushed +.RB ( fflush (3)) +and when the stream is closed +.RB ( fclose (3)). +These values remain valid only as long as the caller +performs no further output on the stream. +If further output is performed, then the stream +must again be flushed before trying to access these values. +.P +A null byte is maintained at the end of the buffer. +This byte is +.I not +included in the size value stored at +.IR sizeloc . +.P +The stream maintains the notion of a current position, +which is initially zero (the start of the buffer). +Each write operation implicitly adjusts the buffer position. +The stream's buffer position can be explicitly changed with +.BR fseek (3) +or +.BR fseeko (3). +Moving the buffer position past the end +of the data already written fills the intervening space with +null characters. +.P +The +.BR open_wmemstream () +is similar to +.BR open_memstream (), +but operates on wide characters instead of bytes. +.SH RETURN VALUE +Upon successful completion, +.BR open_memstream () +and +.BR open_wmemstream () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR open_memstream (), +.BR open_wmemstream () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR open_memstream () +glibc 1.0.x. +.TP +.BR open_wmemstream () +glibc 2.4. +.SH NOTES +There is no file descriptor associated with the file stream +returned by these functions +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.SH BUGS +Before glibc 2.7, seeking past the end of a stream created by +.BR open_memstream () +does not enlarge the buffer; instead the +.BR fseek (3) +call fails, returning \-1. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 +.SH EXAMPLES +See +.BR fmemopen (3). +.SH SEE ALSO +.BR fmemopen (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/open_wmemstream.3 b/man/man3/open_wmemstream.3 new file mode 100644 index 0000000..a113f13 --- /dev/null +++ b/man/man3/open_wmemstream.3 @@ -0,0 +1 @@ +.so man3/open_memstream.3 diff --git a/man/man3/opendir.3 b/man/man3/opendir.3 new file mode 100644 index 0000000..9a558e4 --- /dev/null +++ b/man/man3/opendir.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>: document fdopendir(). +.TH opendir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +opendir, fdopendir \- open a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <dirent.h> +.P +.BI "DIR *opendir(const char *" name ); +.BI "DIR *fdopendir(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdopendir (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR opendir () +function opens a directory stream corresponding to the +directory \fIname\fP, and returns a pointer to the directory stream. +The stream is positioned at the first entry in the directory. +.P +The +.BR fdopendir () +function +is like +.BR opendir (), +but returns a directory stream for the directory referred +to by the open file descriptor +.IR fd . +After a successful call to +.BR fdopendir (), +.I fd +is used internally by the implementation, +and should not otherwise be used by the application. +.SH RETURN VALUE +The +.BR opendir () +and +.BR fdopendir () +functions return a pointer to the directory stream. +On error, NULL is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission denied. +.TP +.B EBADF +.I fd +is not a valid file descriptor opened for reading. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +Directory does not exist, or \fIname\fP is an empty string. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +\fIname\fP is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR opendir (), +.BR fdopendir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH STANDARDS +.TP +.BR opendir () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR fdopendir () +POSIX.1-2008. +glibc 2.4. +.SH NOTES +Filename entries can be read from a directory stream using +.BR readdir (3). +.P +The underlying file descriptor of the directory stream can be obtained using +.BR dirfd (3). +.P +The +.BR opendir () +function sets the close-on-exec flag for the file descriptor underlying the +.IR "DIR *" . +The +.BR fdopendir () +function leaves the setting of the close-on-exec +flag unchanged for the file descriptor, +.IR fd . +POSIX.1-200x leaves it unspecified whether a successful call to +.BR fdopendir () +will set the close-on-exec flag for the file descriptor, +.IR fd . +.SH SEE ALSO +.BR open (2), +.BR closedir (3), +.BR dirfd (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/openlog.3 b/man/man3/openlog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/openlog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/openpty.3 b/man/man3/openpty.3 new file mode 100644 index 0000000..09eb223 --- /dev/null +++ b/man/man3/openpty.3 @@ -0,0 +1,179 @@ +'\" t +.\" Copyright (c) OpenBSD Group +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Converted into a manpage again by Martin Schulze <joey@infodrom.org> +.\" +.\" Added -lutil remark, 030718 +.\" +.TH openpty 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +openpty, login_tty, forkpty \- terminal utility functions +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include <pty.h> +.P +.BI "int openpty(int *" amaster ", int *" aslave ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); +.BI "pid_t forkpty(int *" amaster ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); +.P +.B #include <utmp.h> +.P +.BI "int login_tty(int " fd ); +.fi +.SH DESCRIPTION +The +.BR openpty () +function finds an available pseudoterminal and returns file descriptors +for the master and slave in +.I amaster +and +.IR aslave . +If +.I name +is not NULL, the filename of the slave is returned in +.IR name . +If +.I termp +is not NULL, the terminal parameters of the slave will be set to the +values in +.IR termp . +If +.I winp +is not NULL, the window size of the slave will be set to the values in +.IR winp . +.P +The +.BR login_tty () +function prepares for a login on the terminal +referred to by the file descriptor +.I fd +(which may be a real terminal device, or the slave of a pseudoterminal as +returned by +.BR openpty ()) +by creating a new session, making +.I fd +the controlling terminal for the calling process, setting +.I fd +to be the standard input, output, and error streams of the current +process, and closing +.IR fd . +.P +The +.BR forkpty () +function combines +.BR openpty (), +.BR fork (2), +and +.BR login_tty () +to create a new process operating in a pseudoterminal. +A file descriptor referring to +master side of the pseudoterminal is returned in +.IR amaster . +If +.I name +is not NULL, the buffer it points to is used to return the +filename of the slave. +The +.I termp +and +.I winp +arguments, if not NULL, +will determine the terminal attributes and window size of the slave +side of the pseudoterminal. +.SH RETURN VALUE +If a call to +.BR openpty (), +.BR login_tty (), +or +.BR forkpty () +is not successful, \-1 is returned and +.I errno +is set to indicate the error. +Otherwise, +.BR openpty (), +.BR login_tty (), +and the child process of +.BR forkpty () +return 0, and the parent process of +.BR forkpty () +returns the process ID of the child process. +.SH ERRORS +.BR openpty () +fails if: +.TP +.B ENOENT +There are no available terminals. +.P +.BR login_tty () +fails if +.BR ioctl (2) +fails to set +.I fd +to the controlling terminal of the calling process. +.P +.BR forkpty () +fails if either +.BR openpty () +or +.BR fork (2) +fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR forkpty (), +.BR openpty () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR login_tty () +T} Thread safety MT-Unsafe race:ttyname +.TE +.SH STANDARDS +BSD. +.SH HISTORY +The +.B const +modifiers were added to the structure pointer arguments of +.BR openpty () +and +.BR forkpty () +in glibc 2.8. +.P +Before glibc 2.0.92, +.BR openpty () +returns file descriptors for a BSD pseudoterminal pair; +since glibc 2.0.92, +it first attempts to open a UNIX 98 pseudoterminal pair, +and falls back to opening a BSD pseudoterminal pair if that fails. +.SH BUGS +Nobody knows how much space should be reserved for +.IR name . +So, calling +.BR openpty () +or +.BR forkpty () +with non-NULL +.I name +may not be secure. +.SH SEE ALSO +.BR fork (2), +.BR ttyname (3), +.BR pty (7) diff --git a/man/man3/optarg.3 b/man/man3/optarg.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optarg.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/opterr.3 b/man/man3/opterr.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/opterr.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/optind.3 b/man/man3/optind.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optind.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/optopt.3 b/man/man3/optopt.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optopt.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/passwd2des.3 b/man/man3/passwd2des.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/passwd2des.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/pathconf.3 b/man/man3/pathconf.3 new file mode 100644 index 0000000..46d8c8b --- /dev/null +++ b/man/man3/pathconf.3 @@ -0,0 +1 @@ +.so man3/fpathconf.3 diff --git a/man/man3/pclose.3 b/man/man3/pclose.3 new file mode 100644 index 0000000..663d4a0 --- /dev/null +++ b/man/man3/pclose.3 @@ -0,0 +1 @@ +.so man3/popen.3 diff --git a/man/man3/perror.3 b/man/man3/perror.3 new file mode 100644 index 0000000..4ad088b --- /dev/null +++ b/man/man3/perror.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04 +.\" Copyright (c) 1995 Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de), 1995-03-16 +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith +.\" (msmith@falcon.mercer.peachnet.edu) and various other changes. +.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de) +.\" +.TH perror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +perror \- print a system error message +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "void perror(const char *" s ); +.P +.B #include <errno.h> +.P +.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */" +.P +.BI "[[deprecated]] const char *const " sys_errlist []; +.BI "[[deprecated]] int " sys_nerr ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.IR sys_errlist , +.IR sys_nerr : +.nf + From glibc 2.19 to glibc 2.31: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR perror () +function produces a message on standard error describing the last +error encountered during a call to a system or library function. +.P +First (if +.I s +is not NULL and +.I *s +is not a null byte (\[aq]\e0\[aq])), the argument string +.I s +is printed, followed by a colon and a blank. +Then an error message corresponding to the current value of +.I errno +and a new-line. +.P +To be of most use, the argument string should include the name +of the function that incurred the error. +.P +The global error list +.IR sys_errlist "[]," +which can be indexed by +.IR errno , +can be used to obtain the error message without the newline. +The largest message number provided in the table is +.IR sys_nerr "\-1." +Be careful when directly accessing this list, because new error values +may not have been added to +.IR sys_errlist "[]." +The use of +.IR sys_errlist "[]" +is nowadays deprecated; use +.BR strerror (3) +instead. +.P +When a system call fails, it usually returns \-1 and sets the +variable +.I errno +to a value describing what went wrong. +(These values can be found in +.IR <errno.h> .) +Many library functions do likewise. +The function +.BR perror () +serves to translate this error code into human-readable form. +Note that +.I errno +is undefined after a successful system call or library function call: +this call may well change this variable, even though it succeeds, +for example because it internally used some other library function that failed. +Thus, if a failing call is not immediately followed by a call to +.BR perror (), +the value of +.I errno +should be saved. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR perror () +T} Thread safety MT-Safe race:stderr +.TE +.SH STANDARDS +.TP +.I errno +.TQ +.BR perror () +C11, POSIX.1-2008. +.TP +.I sys_nerr +.TQ +.I sys_errlist +BSD. +.SH HISTORY +.TP +.I errno +.TQ +.BR perror () +POSIX.1-2001, C89, 4.3BSD. +.TP +.I sys_nerr +.TQ +.I sys_errlist +Removed in glibc 2.32. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR strerror (3) diff --git a/man/man3/pmap_getmaps.3 b/man/man3/pmap_getmaps.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_getmaps.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_getport.3 b/man/man3/pmap_getport.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_getport.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_rmtcall.3 b/man/man3/pmap_rmtcall.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_rmtcall.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_set.3 b/man/man3/pmap_set.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_set.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_unset.3 b/man/man3/pmap_unset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_unset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/popen.3 b/man/man3/popen.3 new file mode 100644 index 0000000..9467e06 --- /dev/null +++ b/man/man3/popen.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)popen.3 6.4 (Berkeley) 4/30/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu +.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) +.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.TH popen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +popen, pclose \- pipe stream to or from a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *popen(const char *" command ", const char *" type ); +.BI "int pclose(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR popen (), +.BR pclose (): +.nf + _POSIX_C_SOURCE >= 2 + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR popen () +function opens a process by creating a pipe, forking, and invoking the +shell. +Since a pipe is by definition unidirectional, the +.I type +argument may specify only reading or writing, not both; the resulting +stream is correspondingly read-only or write-only. +.P +The +.I command +argument is a pointer to a null-terminated string containing a shell +command line. +This command is passed to +.I /bin/sh +using the +.B \-c +flag; interpretation, if any, is performed by the shell. +.P +The +.I type +argument is a pointer to a null-terminated string which must contain +either the letter \[aq]r\[aq] for reading or the letter \[aq]w\[aq] for writing. +Since glibc 2.9, +this argument can additionally include the letter \[aq]e\[aq], +which causes the close-on-exec flag +.RB ( FD_CLOEXEC ) +to be set on the underlying file descriptor; +see the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +The return value from +.BR popen () +is a normal standard I/O stream in all respects save that it must be closed +with +.BR pclose () +rather than +.BR fclose (3). +Writing to such a stream writes to the standard input of the command; the +command's standard output is the same as that of the process that called +.BR popen (), +unless this is altered by the command itself. +Conversely, reading from +the stream reads the command's standard output, and the command's +standard input is the same as that of the process that called +.BR popen (). +.P +Note that output +.BR popen () +streams are block buffered by default. +.P +The +.BR pclose () +function waits for the associated process to terminate and returns the exit +status of the command as returned by +.BR wait4 (2). +.SH RETURN VALUE +.BR popen (): +on success, returns a pointer to an open stream that +can be used to read or write to the pipe; +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if the function cannot allocate memory, +NULL is returned. +.P +.BR pclose (): +on success, returns the exit status of the command; if +.\" These conditions actually give undefined results, so I commented +.\" them out. +.\" .I stream +.\" is not associated with a "popen()ed" command, if +.\".I stream +.\" already "pclose()d", or if +.BR wait4 (2) +returns an error, or some other error is detected, +\-1 is returned. +.P +On failure, both functions set +.I errno +to indicate the error. +.SH ERRORS +The +.BR popen () +function does not set +.I errno +if memory allocation fails. +If the underlying +.BR fork (2) +or +.BR pipe (2) +fails, +.I errno +is set to indicate the error. +If the +.I type +argument is invalid, and this condition is detected, +.I errno +is set to +.BR EINVAL . +.P +If +.BR pclose () +cannot obtain the child status, +.I errno +is set to +.BR ECHILD . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR popen (), +.BR pclose () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The \[aq]e\[aq] value for +.I type +is a Linux extension. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH CAVEATS +Carefully read Caveats in +.BR system (3). +.SH BUGS +Since the standard input of a command opened for reading shares its seek +offset with the process that called +.BR popen (), +if the original process has done a buffered read, the command's input +position may not be as expected. +Similarly, the output from a command +opened for writing may become intermingled with that of the original +process. +The latter can be avoided by calling +.BR fflush (3) +before +.BR popen (). +.P +Failure to execute the shell is indistinguishable from the shell's failure +to execute the command, or an immediate exit of the command. +The only hint is an exit status of 127. +.\" .SH HISTORY +.\" A +.\" .BR popen () +.\" and a +.\" .BR pclose () +.\" function appeared in Version 7 AT&T UNIX. +.SH SEE ALSO +.BR sh (1), +.BR fork (2), +.BR pipe (2), +.BR wait4 (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR stdio (3), +.BR system (3) diff --git a/man/man3/posix_fallocate.3 b/man/man3/posix_fallocate.3 new file mode 100644 index 0000000..8736f74 --- /dev/null +++ b/man/man3/posix_fallocate.3 @@ -0,0 +1,181 @@ +'\" t +.\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH posix_fallocate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_fallocate \- allocate file space +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.P +.BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_fallocate (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The function +.BR posix_fallocate () +ensures that disk space is allocated for the file referred to by the +file descriptor +.I fd +for the bytes in the range starting at +.I offset +and continuing for +.I len +bytes. +After a successful call to +.BR posix_fallocate (), +subsequent writes to bytes in the specified range are +guaranteed not to fail because of lack of disk space. +.P +If the size of the file is less than +.IR offset + len , +then the file is increased to this size; +otherwise the file size is left unchanged. +.SH RETURN VALUE +.BR posix_fallocate () +returns zero on success, or an error number on failure. +Note that +.I errno +is not set. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor, or is not opened for writing. +.TP +.B EFBIG +.I offset+len +exceeds the maximum file size. +.TP +.B EINTR +A signal was caught during execution. +.TP +.B EINVAL +.I offset +was less than 0, or +.I len +was less than or equal to 0, or the underlying filesystem does not +support the operation. +.TP +.B ENODEV +.I fd +does not refer to a regular file. +.TP +.B ENOSPC +There is not enough space left on the device containing the file +referred to by +.IR fd . +.TP +.B EOPNOTSUPP +The filesystem containing the file referred to by +.I fd +does not support this operation. +This error code can be returned by C libraries that don't perform the +emulation shown in NOTES, such as musl libc. +.TP +.B ESPIPE +.I fd +refers to a pipe. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR posix_fallocate () +T} Thread safety T{ +.na +.nh +MT-Safe (but see NOTES) +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1.94. +POSIX.1-2001 +.P +POSIX.1-2008 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +was 0, or +.I offset +was less than 0. +POSIX.1-2001 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +is less than 0, or +.I offset +was less than 0, and +.I may +give the error if +.I len +equals zero. +.SH CAVEATS +In the glibc implementation, +.BR posix_fallocate () +is implemented using the +.BR fallocate (2) +system call, which is MT-safe. +If the underlying filesystem does not support +.BR fallocate (2), +then the operation is emulated with the following caveats: +.IP \[bu] 3 +The emulation is inefficient. +.IP \[bu] +There is a race condition where concurrent writes from another thread or +process could be overwritten with null bytes. +.IP \[bu] +There is a race condition where concurrent file size increases by +another thread or process could result in a file whose size is smaller +than expected. +.IP \[bu] +If +.I fd +has been opened with the +.B O_APPEND +or +.B O_WRONLY +flags, the function fails with the error +.BR EBADF . +.P +In general, the emulation is not MT-safe. +On Linux, applications may use +.BR fallocate (2) +if they cannot tolerate the emulation caveats. +In general, this is +only recommended if the application plans to terminate the operation if +.B EOPNOTSUPP +is returned, otherwise the application itself will need to implement a +fallback with all the same problems as the emulation provided by glibc. +.SH SEE ALSO +.BR fallocate (1), +.BR fallocate (2), +.BR lseek (2), +.BR posix_fadvise (2) diff --git a/man/man3/posix_madvise.3 b/man/man3/posix_madvise.3 new file mode 100644 index 0000000..383f4f5 --- /dev/null +++ b/man/man3/posix_madvise.3 @@ -0,0 +1,112 @@ +.\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH posix_madvise 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_madvise \- give advice about patterns of memory usage +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/mman.h> +.P +.BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_madvise (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR posix_madvise () +function allows an application to advise the system about its expected +patterns of usage of memory in the address range starting at +.I addr +and continuing for +.I len +bytes. +The system is free to use this advice in order to improve the performance +of memory accesses (or to ignore the advice altogether), but calling +.BR posix_madvise () +shall not affect the semantics of access to memory in the specified range. +.P +The +.I advice +argument is one of the following: +.TP +.B POSIX_MADV_NORMAL +The application has no special advice regarding its memory usage patterns +for the specified address range. +This is the default behavior. +.TP +.B POSIX_MADV_SEQUENTIAL +The application expects to access the specified address range sequentially, +running from lower addresses to higher addresses. +Hence, pages in this region can be aggressively read ahead, +and may be freed soon after they are accessed. +.TP +.B POSIX_MADV_RANDOM +The application expects to access the specified address range randomly. +Thus, read ahead may be less useful than normally. +.TP +.B POSIX_MADV_WILLNEED +The application expects to access the specified address range +in the near future. +Thus, read ahead may be beneficial. +.TP +.B POSIX_MADV_DONTNEED +The application expects that it will not access the specified address range +in the near future. +.SH RETURN VALUE +On success, +.BR posix_madvise () +returns 0. +On failure, it returns a positive error number. +.SH ERRORS +.TP +.B EINVAL +.I addr +is not a multiple of the system page size or +.I len +is negative. +.TP +.B EINVAL +.I advice +is invalid. +.TP +.B ENOMEM +Addresses in the specified range are partially or completely outside +the caller's address space. +.SH VERSIONS +POSIX.1 permits an implementation to generate an error if +.I len +is 0. +On Linux, specifying +.I len +as 0 is permitted (as a successful no-op). +.P +In glibc, this function is implemented using +.BR madvise (2). +However, since glibc 2.6, +.B POSIX_MADV_DONTNEED +is treated as a no-op, because the corresponding +.BR madvise (2) +value, +.BR MADV_DONTNEED , +has destructive semantics. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH SEE ALSO +.BR madvise (2), +.BR posix_fadvise (2) diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3 new file mode 100644 index 0000000..e89e1f9 --- /dev/null +++ b/man/man3/posix_memalign.3 @@ -0,0 +1,276 @@ +'\" t +.\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk> +.\" Based in part on GNU libc documentation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2001-10-11, 2003-08-22, aeb, added some details +.\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com> +.\" Document pvalloc() and aligned_alloc() +.TH posix_memalign 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- +allocate aligned memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); +.BI "void *aligned_alloc(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *valloc(size_t " size ); +.P +.B #include <malloc.h> +.P +.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *pvalloc(size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_memalign (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR aligned_alloc (): +.nf + _ISOC11_SOURCE +.fi +.P +.BR valloc (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.BR posix_memalign () +allocates +.I size +bytes and places the address of the allocated memory in +.IR "*memptr" . +The address of the allocated memory will be a multiple of +.IR "alignment" , +which must be a power of two and a multiple of +.IR "sizeof(void\ *)" . +This address can later be successfully passed to +.BR free (3). +If +.I size +is 0, then +the value placed in +.I *memptr +is either NULL +.\" glibc does this: +or a unique pointer value. +.P +The obsolete function +.BR memalign () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of +.IR alignment , +which must be a power of two. +.\" The behavior of memalign() for size==0 is as for posix_memalign() +.\" but no standards govern this. +.P +.BR aligned_alloc () +is the same as +.BR memalign (), +except for the added restriction that +.I alignment +must be a power of two. +.P +The obsolete function +.BR valloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of the page size. +It is equivalent to +.IR "memalign(sysconf(_SC_PAGESIZE),size)" . +.P +The obsolete function +.BR pvalloc () +is similar to +.BR valloc (), +but rounds the size of the allocation up to +the next multiple of the system page size. +.P +For all of these functions, the memory is not zeroed. +.SH RETURN VALUE +.BR aligned_alloc (), +.BR memalign (), +.BR valloc (), +and +.BR pvalloc () +return a pointer to the allocated memory on success. +On error, NULL is returned, and \fIerrno\fP is set +to indicate the error. +.P +.BR posix_memalign () +returns zero on success, or one of the error values listed in the +next section on failure. +The value of +.I errno +is not set. +On Linux (and other systems), +.BR posix_memalign () +does not modify +.I memptr +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=520 +.SH ERRORS +.TP +.B EINVAL +The +.I alignment +argument was not a power of two, or was not a multiple of +.IR "sizeof(void\ *)" . +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aligned_alloc (), +.BR memalign (), +.BR posix_memalign () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR valloc (), +.BR pvalloc () +T} Thread safety MT-Unsafe init +.TE +.SH STANDARDS +.TP +.BR aligned_alloc () +C11. +.TP +.BR posix_memalign () +POSIX.1-2008. +.TP +.BR memalign () +.TQ +.BR valloc () +None. +.TP +.BR pvalloc () +GNU. +.SH HISTORY +.TP +.BR aligned_alloc () +glibc 2.16. +C11. +.TP +.BR posix_memalign () +glibc 2.1.91. +POSIX.1d, POSIX.1-2001. +.TP +.BR memalign () +glibc 2.0. +SunOS 4.1.3. +.TP +.BR valloc () +glibc 2.0. +3.0BSD. +Documented as obsolete in 4.3BSD, +and as legacy in SUSv2. +.TP +.BR pvalloc () +glibc 2.0. +.\" +.SS Headers +Everybody agrees that +.BR posix_memalign () +is declared in \fI<stdlib.h>\fP. +.P +On some systems +.BR memalign () +is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP. +.P +According to SUSv2, +.BR valloc () +is declared in \fI<stdlib.h>\fP. +.\" Libc4,5 and +glibc declares it in \fI<malloc.h>\fP, and also in +\fI<stdlib.h>\fP +if suitable feature test macros are defined (see above). +.SH NOTES +On many systems there are alignment restrictions, for example, on buffers +used for direct block device I/O. +POSIX specifies the +.I "pathconf(path,_PC_REC_XFER_ALIGN)" +call that tells what alignment is needed. +Now one can use +.BR posix_memalign () +to satisfy this requirement. +.P +.BR posix_memalign () +verifies that +.I alignment +matches the requirements detailed above. +.BR memalign () +may not check that the +.I alignment +argument is correct. +.P +POSIX requires that memory obtained from +.BR posix_memalign () +can be freed using +.BR free (3). +Some systems provide no way to reclaim memory allocated with +.BR memalign () +or +.BR valloc () +(because one can pass to +.BR free (3) +only a pointer obtained from +.BR malloc (3), +while, for example, +.BR memalign () +would call +.BR malloc (3) +and then align the obtained value). +.\" Other systems allow passing the result of +.\" .IR valloc () +.\" to +.\" .IR free (3), +.\" but not to +.\" .IR realloc (3). +The glibc implementation +allows memory obtained from any of these functions to be +reclaimed with +.BR free (3). +.P +The glibc +.BR malloc (3) +always returns 8-byte aligned memory addresses, so these functions are +needed only if you require larger alignment values. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR free (3), +.BR malloc (3) diff --git a/man/man3/posix_openpt.3 b/man/man3/posix_openpt.3 new file mode 100644 index 0000000..04abebe --- /dev/null +++ b/man/man3/posix_openpt.3 @@ -0,0 +1,107 @@ +'\" t +.\" Copyright (C) 2004 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH posix_openpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_openpt \- open a pseudoterminal device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.B #include <fcntl.h> +.P +.BI "int posix_openpt(int " flags ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_openpt (): +.nf + _XOPEN_SOURCE >= 600 +.fi +.SH DESCRIPTION +The +.BR posix_openpt () +function opens an unused pseudoterminal master device, returning a +file descriptor that can be used to refer to that device. +.P +The +.I flags +argument is a bit mask that ORs together zero or more of +the following flags: +.TP +.B O_RDWR +Open the device for both reading and writing. +It is usual to specify this flag. +.TP +.B O_NOCTTY +Do not make this device the controlling terminal for the process. +.SH RETURN VALUE +On success, +.BR posix_openpt () +returns a file descriptor (a nonnegative integer) which is the lowest +numbered unused file descriptor. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR posix_openpt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2.1. +POSIX.1-2001. +.P +It is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.SH NOTES +Some older UNIX implementations that support System V +(aka UNIX 98) pseudoterminals don't have this function, but it +can be easily implemented by opening the pseudoterminal multiplexor device: +.P +.in +4n +.EX +int +posix_openpt(int flags) +{ + return open("/dev/ptmx", flags); +} +.EE +.in +.P +Calling +.BR posix_openpt () +creates a pathname for the corresponding pseudoterminal slave device. +The pathname of the slave device can be obtained using +.BR ptsname (3). +The slave device pathname exists only as long as the master device is open. +.SH SEE ALSO +.BR open (2), +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/posix_spawn.3 b/man/man3/posix_spawn.3 new file mode 100644 index 0000000..71a5b84 --- /dev/null +++ b/man/man3/posix_spawn.3 @@ -0,0 +1,823 @@ +.\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com) +.\" and Copyright 2010 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux glibc source code +.\" POSIX 1003.1-2004 documentation +.\" (http://www.opengroup.org/onlinepubs/009695399) +.\" +.TH posix_spawn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_spawn, posix_spawnp \- spawn a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <spawn.h> +.P +.BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.BI "int posix_spawnp(pid_t *restrict " pid ", const char *restrict " file , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.fi +.SH DESCRIPTION +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions are used to create a new child process that executes +a specified file. +These functions were specified by POSIX to provide a standardized method +of creating new processes on machines that lack the capability +to support the +.BR fork (2) +system call. +These machines are generally small, embedded systems lacking MMU support. +.P +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions provide the functionality of a combined +.BR fork (2) +and +.BR exec (3), +with some optional housekeeping steps in the child process before the +.BR exec (3). +These functions are not meant to replace the +.BR fork (2) +and +.BR execve (2) +system calls. +In fact, they provide only a subset of the functionality +that can be achieved by using the system calls. +.P +The only difference between +.BR posix_spawn () +and +.BR posix_spawnp () +is the manner in which they specify the file to be executed by +the child process. +With +.BR posix_spawn (), +the executable file is specified as a pathname +(which can be absolute or relative). +With +.BR posix_spawnp (), +the executable file is specified as a simple filename; +the system searches for this file in the list of directories specified by +.B PATH +(in the same way as for +.BR execvp (3)). +For the remainder of this page, the discussion is phrased in terms of +.BR posix_spawn (), +with the understanding that +.BR posix_spawnp () +differs only on the point just described. +.P +The remaining arguments to these two functions are as follows: +.TP +.I pid +points to a buffer that is used to return the process ID +of the new child process. +.TP +.I file_actions +points to a +.I "spawn file actions object" +that specifies file-related actions to be performed in the child +between the +.BR fork (2) +and +.BR exec (3) +steps. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawn_file_actions_init (3) +and the +.BR posix_spawn_file_actions_* () +functions. +.TP +.I attrp +points to an +.I attributes objects +that specifies various attributes of the created child process. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawnattr_init (3) +and the +.BR posix_spawnattr_* () +functions. +.TP +.I argv +.TQ +.I envp +specify the argument list and environment for the program +that is executed in the child process, as for +.BR execve (2). +.P +Below, the functions are described in terms of a three-step process: the +.BR fork () +step, the +.RB pre- exec () +step (executed in the child), +and the +.BR exec () +step (executed in the child). +.SS fork() step +Since glibc 2.24, the +.BR posix_spawn () +function commences by calling +.BR clone (2) +with +.B CLONE_VM +and +.B CLONE_VFORK +flags. +Older implementations use +.BR fork (2), +or possibly +.BR vfork (2) +(see below). +.P +The PID of the new child process is placed in +.IR *pid . +The +.BR posix_spawn () +function then returns control to the parent process. +.P +Subsequently, the parent can use one of the system calls described in +.BR wait (2) +to check the status of the child process. +If the child fails in any of the housekeeping steps described below, +or fails to execute the desired file, +it exits with a status of 127. +.P +Before glibc 2.24, the child process is created using +.BR vfork (2) +instead of +.BR fork (2) +when either of the following is true: +.IP \[bu] 3 +the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +contains the GNU-specific flag +.BR POSIX_SPAWN_USEVFORK ; +or +.IP \[bu] +.I file_actions +is NULL and the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +does \fInot\fP contain +.BR POSIX_SPAWN_SETSIGMASK , +.BR POSIX_SPAWN_SETSIGDEF , +.BR POSIX_SPAWN_SETSCHEDPARAM , +.BR POSIX_SPAWN_SETSCHEDULER , +.BR POSIX_SPAWN_SETPGROUP , +or +.BR POSIX_SPAWN_RESETIDS . +.P +In other words, +.BR vfork (2) +is used if the caller requests it, +or if there is no cleanup expected in the child before it +.BR exec (3)s +the requested file. +.SS pre-exec() step: housekeeping +In between the +.B fork() +and the +.B exec() +steps, a child process may need to perform a set of housekeeping actions. +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions support a small, well-defined set of system tasks that the child +process can accomplish before it executes the executable file. +These operations are controlled by the attributes object pointed to by +.I attrp +and the file actions object pointed to by +.IR file_actions . +In the child, processing is done in the following sequence: +.IP (1) 5 +Process attribute actions: signal mask, signal default handlers, +scheduling algorithm and parameters, +process group, and effective user and group IDs +are changed as specified by the attributes object pointed to by +.IR attrp . +.IP (2) +File actions, as specified in the +.I file_actions +argument, +are performed in the order that they were specified using calls to the +.BR posix_spawn_file_actions_add* () +functions. +.IP (3) +File descriptors with the +.B FD_CLOEXEC +flag set are closed. +.P +All process attributes in the child, +other than those affected by attributes specified in the +object pointed to by +.I attrp +and the file actions in the object pointed to by +.IR file_actions , +will be affected as though the child was created with +.BR fork (2) +and it executed the program with +.BR execve (2). +.P +The process attributes actions are defined by the attributes object +pointed to by +.IR attrp . +The +.I spawn-flags +attribute (set using +.BR posix_spawnattr_setflags (3)) +controls the general actions that occur, +and other attributes in the object specify values +to be used during those actions. +.P +The effects of the flags that may be specified in +.I spawn-flags +are as follows: +.TP +.B POSIX_SPAWN_SETSIGMASK +Set the signal mask to the signal set specified in the +.I spawn-sigmask +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigmask (3)) +of the object pointed to by +.IR attrp . +If the +.B POSIX_SPAWN_SETSIGMASK +flag is not set, then the child inherits the parent's signal mask. +.TP +.B POSIX_SPAWN_SETSIGDEF +Reset the disposition of all signals in the set specified in the +.I spawn-sigdefault +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigdefault (3)) +of the object pointed to by +.I attrp +to the default. +For the treatment of the dispositions of signals not specified in the +.I spawn-sigdefault +attribute, or the treatment when +.B POSIX_SPAWN_SETSIGDEF +is not specified, see +.BR execve (2). +.TP +.B POSIX_SPAWN_SETSCHEDPARAM +.\" (POSIX_PRIORITY_SCHEDULING only) +If this flag is set, and the +.B POSIX_SPAWN_SETSCHEDULER +flag is not set, then set the scheduling parameters +to the parameters specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.IR attrp . +.TP +.B POSIX_SPAWN_SETSCHEDULER +Set the scheduling policy algorithm and parameters of the child, +as follows: +.RS +.IP \[bu] 3 +The scheduling policy is set to the value specified in the +.I spawn-schedpolicy +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpolicy (3)) +of the object pointed to by +.IR attrp . +.IP \[bu] +The scheduling parameters are set to the value specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.I attrp +(but see BUGS). +.P +If the +.B POSIX_SPAWN_SETSCHEDPARAM +and +.B POSIX_SPAWN_SETSCHEDPOLICY +flags are not specified, +the child inherits the corresponding scheduling attributes from the parent. +.RE +.TP +.B POSIX_SPAWN_RESETIDS +If this flag is set, +reset the effective UID and GID to the +real UID and GID of the parent process. +If this flag is not set, +then the child retains the effective UID and GID of the parent. +In either case, if the set-user-ID and set-group-ID permission +bits are enabled on the executable file, their effect will override +the setting of the effective UID and GID (se +.BR execve (2)). +.TP +.B POSIX_SPAWN_SETPGROUP +Set the process group to the value specified in the +.I spawn-pgroup +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpgroup (3)) +of the object pointed to by +.IR attrp . +If the +.I spawn-pgroup +attribute has the value 0, +the child's process group ID is made the same as its process ID. +If the +.B POSIX_SPAWN_SETPGROUP +flag is not set, the child inherits the parent's process group ID. +.TP +.B POSIX_SPAWN_USEVFORK +Since glibc 2.24, this flag has no effect. +On older implementations, setting this flag forces the +.B fork() +step to use +.BR vfork (2) +instead of +.BR fork (2). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.TP +.BR POSIX_SPAWN_SETSID " (since glibc 2.26)" +If this flag is set, +the child process shall create a new session and become the session leader. +The child process shall also become the process group leader of the new process +group in the session (see +.BR setsid (2)). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.\" This flag has been accepted in POSIX, see: +.\" http://austingroupbugs.net/view.php?id=1044 +.\" and has been implemented since glibc 2.26 +.\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b +.P +If +.I attrp +is NULL, then the default behaviors described above for each flag apply. +.\" mtk: I think we probably don't want to say the following, since it +.\" could lead people to do the wrong thing +.\" The POSIX standard tells you to call +.\" this function to de-initialize the attributes object pointed to by +.\" .I attrp +.\" when you are done with it; +.\" however, on Linux systems this operation is a no-op. +.P +The +.I file_actions +argument specifies a sequence of file operations +that are performed in the child process after +the general processing described above, and before it performs the +.BR exec (3). +If +.I file_actions +is NULL, then no special action is taken, and standard +.BR exec (3) +semantics apply\[em]file descriptors open before the exec +remain open in the new process, +except those for which the +.B FD_CLOEXEC +flag has been set. +File locks remain in place. +.P +If +.I file_actions +is not NULL, then it contains an ordered set of requests to +.BR open (2), +.BR close (2), +and +.BR dup2 (2) +files. +These requests are added to the +.I file_actions +by +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_addclose (3), +and +.BR posix_spawn_file_actions_adddup2 (3). +The requested operations are performed in the order they were added to +.IR file_actions . +.\" FIXME . I think the following is best placed in the +.\" posix_spawn_file_actions_adddup2(3) page, and a similar statement is +.\" also needed in posix_spawn_file_actions_addclose(3) +.\" Note that you can specify file descriptors in +.\" .I posix_spawn_file_actions_adddup2 (3) +.\" which would not be usable if you called +.\" .BR dup2 (2) +.\" at that time--i.e., file descriptors that are opened or +.\" closed by the earlier operations +.\" added to +.\" .I file_actions . +.P +If any of the housekeeping actions fails +(due to bogus values being passed or other reasons why signal handling, +process scheduling, process group ID functions, +and file descriptor operations might fail), +the child process exits with exit value 127. +.SS exec() step +Once the child has successfully forked and performed +all requested pre-exec steps, +the child runs the requested executable. +.P +The child process takes its environment from the +.I envp +argument, which is interpreted as if it had been passed to +.BR execve (2). +The arguments to the created process come from the +.I argv +argument, which is processed as for +.BR execve (2). +.SH RETURN VALUE +Upon successful completion, +.BR posix_spawn () +and +.BR posix_spawnp () +place the PID of the child process in +.IR pid , +and return 0. +If there is an error during the +.B fork() +step, +then no child is created, +the contents of +.I *pid +are unspecified, +and these functions return an error number as described below. +.P +Even when these functions return a success status, +the child process may still fail for a plethora of reasons related to its +pre-\fBexec\fR() initialization. +In addition, the +.BR exec (3) +may fail. +In all of these cases, the child process will exit with the exit value of 127. +.SH ERRORS +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions fail only in the case where the underlying +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +call fails; in these cases, these functions return an error number, +which will be one of the errors described for +.BR fork (2), +.BR vfork (2), +or +.BR clone (2). +.P +In addition, these functions fail if: +.TP +.B ENOSYS +Function not supported on this system. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.\" FIXME . This piece belongs in spawnattr_setflags(3) +.\" The +.\" .B POSIX_SPAWN_USEVFORK +.\" flag is a GNU extension; the +.\" .B _GNU_SOURCE +.\" feature test macro must be defined (before including any header files) +.\" to obtain the definition of this constant. +.SH NOTES +The housekeeping activities in the child are controlled by +the objects pointed to by +.I attrp +(for non-file actions) and +.I file_actions +In POSIX parlance, the +.I posix_spawnattr_t +and +.I posix_spawn_file_actions_t +data types are referred to as objects, +and their elements are not specified by name. +Portable programs should initialize these objects using +only the POSIX-specified functions. +(In other words, +although these objects may be implemented as structures containing fields, +portable programs must avoid dependence on such implementation details.) +.P +According to POSIX, it is unspecified whether fork handlers established with +.BR pthread_atfork (3) +are called when +.BR posix_spawn () +is invoked. +Since glibc 2.24, the fork handlers are not executed in any case. +.\" Tested on glibc 2.12 +On older implementations, +fork handlers are called only if the child is created using +.BR fork (2). +.P +There is no "posix_fspawn" function (i.e., a function that is to +.BR posix_spawn () +as +.BR fexecve (3) +is to +.BR execve (2)). +However, this functionality can be obtained by specifying the +.I path +argument as one of the files in the caller's +.I /proc/self/fd +directory. +.SH BUGS +POSIX.1 says that when +.B POSIX_SPAWN_SETSCHEDULER +is specified in +.IR spawn-flags , +then the +.B POSIX_SPAWN_SETSCHEDPARAM +(if present) is ignored. +However, before glibc 2.14, calls to +.BR posix_spawn () +failed with an error if +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052 +.B POSIX_SPAWN_SETSCHEDULER +was specified without also specifying +.BR POSIX_SPAWN_SETSCHEDPARAM . +.SH EXAMPLES +The program below demonstrates the use of various functions in the +POSIX spawn API. +The program accepts command-line attributes that can be used +to create file actions and attributes objects. +The remaining command-line arguments are used as the executable name +and command-line arguments of the program that is executed in the child. +.P +In the first run, the +.BR date (1) +command is executed in the child, and the +.BR posix_spawn () +call employs no file actions or attributes objects. +.P +.in +4n +.EX +$ \fB./a.out date\fP +PID of child: 7634 +Tue Feb 1 19:47:50 CEST 2011 +Child status: exited, status=0 +.EE +.in +.P +In the next run, the +.I \-c +command-line option is used to create a file actions object that closes +standard output in the child. +Consequently, +.BR date (1) +fails when trying to perform output and exits with a status of 1. +.P +.in +4n +.EX +$ \fB./a.out \-c date\fP +PID of child: 7636 +date: write error: Bad file descriptor +Child status: exited, status=1 +.EE +.in +.P +In the next run, the +.I \-s +command-line option is used to create an attributes object that +specifies that all (blockable) signals in the child should be blocked. +Consequently, trying to kill child with the default signal sent by +.BR kill (1) +(i.e., +.BR SIGTERM ) +fails, because that signal is blocked. +Therefore, to kill the child, +.B SIGKILL +is necessary +.RB ( SIGKILL +can't be blocked). +.P +.in +4n +.EX +$ \fB./a.out \-s sleep 60 &\fP +[1] 7637 +$ PID of child: 7638 +.P +$ \fBkill 7638\fP +$ \fBkill \-KILL 7638\fP +$ Child status: killed by signal 9 +[1]+ Done ./a.out \-s sleep 60 +.EE +.in +.P +When we try to execute a nonexistent command in the child, the +.BR exec (3) +fails and the child exits with a status of 127. +.P +.in +4n +.EX +$ \fB./a.out xxxxx +PID of child: 10190 +Child status: exited, status=127 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (posix_spawn.c) +.EX +#include <errno.h> +#include <spawn.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> +#include <wait.h> +\& +#define errExit(msg) do { perror(msg); \e + exit(EXIT_FAILURE); } while (0) +\& +#define errExitEN(en, msg) \e + do { errno = en; perror(msg); \e + exit(EXIT_FAILURE); } while (0) +\& +char **environ; +\& +int +main(int argc, char *argv[]) +{ + pid_t child_pid; + int s, opt, status; + sigset_t mask; + posix_spawnattr_t attr; + posix_spawnattr_t *attrp; + posix_spawn_file_actions_t file_actions; + posix_spawn_file_actions_t *file_actionsp; +\& + /* Parse command\-line options, which can be used to specify an + attributes object and file actions object for the child. */ +\& + attrp = NULL; + file_actionsp = NULL; +\& + while ((opt = getopt(argc, argv, "sc")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: /* \-c: close standard output in child */ +\& + /* Create a file actions object and add a "close" + action to it. */ +\& + s = posix_spawn_file_actions_init(&file_actions); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_init"); +\& + s = posix_spawn_file_actions_addclose(&file_actions, + STDOUT_FILENO); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_addclose"); +\& + file_actionsp = &file_actions; + break; +\& + case \[aq]s\[aq]: /* \-s: block all signals in child */ +\& + /* Create an attributes object and add a "set signal mask" + action to it. */ +\& + s = posix_spawnattr_init(&attr); + if (s != 0) + errExitEN(s, "posix_spawnattr_init"); + s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK); + if (s != 0) + errExitEN(s, "posix_spawnattr_setflags"); +\& + sigfillset(&mask); + s = posix_spawnattr_setsigmask(&attr, &mask); + if (s != 0) + errExitEN(s, "posix_spawnattr_setsigmask"); +\& + attrp = &attr; + break; + } + } +\& + /* Spawn the child. The name of the program to execute and the + command\-line arguments are taken from the command\-line arguments + of this program. The environment of the program execed in the + child is made the same as the parent\[aq]s environment. */ +\& + s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp, + &argv[optind], environ); + if (s != 0) + errExitEN(s, "posix_spawn"); +\& + /* Destroy any objects that we created earlier. */ +\& + if (attrp != NULL) { + s = posix_spawnattr_destroy(attrp); + if (s != 0) + errExitEN(s, "posix_spawnattr_destroy"); + } +\& + if (file_actionsp != NULL) { + s = posix_spawn_file_actions_destroy(file_actionsp); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_destroy"); + } +\& + printf("PID of child: %jd\en", (intmax_t) child_pid); +\& + /* Monitor status of the child until it terminates. */ +\& + do { + s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED); + if (s == \-1) + errExit("waitpid"); +\& + printf("Child status: "); + if (WIFEXITED(status)) { + printf("exited, status=%d\en", WEXITSTATUS(status)); + } else if (WIFSIGNALED(status)) { + printf("killed by signal %d\en", WTERMSIG(status)); + } else if (WIFSTOPPED(status)) { + printf("stopped by signal %d\en", WSTOPSIG(status)); + } else if (WIFCONTINUED(status)) { + printf("continued\en"); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.nh \" Disable hyphenation +.ad l +.BR close (2), +.BR dup2 (2), +.BR execl (2), +.BR execlp (2), +.BR fork (2), +.BR open (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR setpgid (2), +.BR setuid (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR posix_spawn_file_actions_addclose (3), +.BR posix_spawn_file_actions_adddup2 (3), +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_destroy (3), +.BR posix_spawn_file_actions_init (3), +.BR posix_spawnattr_destroy (3), +.BR posix_spawnattr_getflags (3), +.BR posix_spawnattr_getpgroup (3), +.BR posix_spawnattr_getschedparam (3), +.BR posix_spawnattr_getschedpolicy (3), +.BR posix_spawnattr_getsigdefault (3), +.BR posix_spawnattr_getsigmask (3), +.BR posix_spawnattr_init (3), +.BR posix_spawnattr_setflags (3), +.BR posix_spawnattr_setpgroup (3), +.BR posix_spawnattr_setschedparam (3), +.BR posix_spawnattr_setschedpolicy (3), +.BR posix_spawnattr_setsigdefault (3), +.BR posix_spawnattr_setsigmask (3), +.BR pthread_atfork (3), +.IR <spawn.h> , +Base Definitions volume of POSIX.1-2001, +.I http://www.opengroup.org/unix/online.html diff --git a/man/man3/posix_spawnp.3 b/man/man3/posix_spawnp.3 new file mode 100644 index 0000000..a6f49d0 --- /dev/null +++ b/man/man3/posix_spawnp.3 @@ -0,0 +1 @@ +.so man3/posix_spawn.3 diff --git a/man/man3/pow.3 b/man/man3/pow.3 new file mode 100644 index 0000000..6c252cd --- /dev/null +++ b/man/man3/pow.3 @@ -0,0 +1,383 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no> +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH pow 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pow, powf, powl \- power functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double pow(double " x ", double " y ); +.BI "float powf(float " x ", float " y ); +.BI "long double powl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR powf (), +.BR powl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the value of +.I x +raised to the +power of +.IR y . +.SH RETURN VALUE +On success, these functions return the value of +.I x +to the power of +.IR y . +.P +If the result overflows, +a range error occurs, +.\" The range error is generated at least as far back as glibc 2.4 +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.P +If result underflows, and is not representable, +a range error occurs, +and 0.0 with the appropriate sign is returned. +.\" POSIX.1 does not specify the sign of the zero, +.\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678 +.\" points out that the zero has the wrong sign in some cases. +.P +.\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL* +If +.I x +is +0 or \-0, +and +.I y +is an odd integer less than 0, +a pole error occurs and +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +is returned, +with the same sign as +.IR x . +.P +.\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL* +If +.I x +is +0 or \-0, +and +.I y +is less than 0 and not an odd integer, +a pole error occurs and +.\" The pole error is generated at least as far back as glibc 2.4 +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +is returned. +.P +.\" pow(\(+-0, >0 [[odd]]) = \(+-0 +If +.I x +is +0 (\-0), +and +.I y +is an odd integer greater than 0, +the result is +0 (\-0). +.P +.\" pow(\(+-0, >0 [[!odd]]) = +0 +If +.I x +is 0, +and +.I y +greater than 0 and not an odd integer, +the result is +0. +.P +.\" pow(-1, \(+-INFINITY) = 1.0 +If +.I x +is \-1, +and +.I y +is positive infinity or negative infinity, +the result is 1.0. +.P +.\" pow(+1, y) = 1.0 +If +.I x +is +1, the result is 1.0 (even if +.I y +is a NaN). +.P +.\" pow(x, \(+-0) = 1.0 +If +.I y +is 0, the result is 1.0 (even if +.I x +is a NaN). +.P +.\" pow(<0, y) = NaN +If +.I x +is a finite value less than 0, and +.I y +is a finite noninteger, a domain error occurs, +.\" The domain error is generated at least as far back as glibc 2.4 +and a NaN is returned. +.P +.\" pow(|x|<1, -INFINITY) = INFINITY +If the absolute value of +.I x +is less than 1, +and +.I y +is negative infinity, +the result is positive infinity. +.P +.\" pow(|x|>1, -INFINITY) = +0 +If the absolute value of +.I x +is greater than 1, +and +.I y +is negative infinity, +the result is +0. +.P +.\" pow(|x|<1, INFINITY) = +0 +If the absolute value of +.I x +is less than 1, +and +.I y +is positive infinity, +the result is +0. +.P +.\" pow(|x|>1, INFINITY) = INFINITY +If the absolute value of +.I x +is greater than 1, +and +.I y +is positive infinity, +the result is positive infinity. +.P +.\" pow(-INFINITY, <0 [[odd]]) = -0 +If +.I x +is negative infinity, +and +.I y +is an odd integer less than 0, +the result is \-0. +.P +.\" pow(-INFINITY, <0 [[!odd]]) = +0 +If +.I x +is negative infinity, +and +.I y +less than 0 and not an odd integer, +the result is +0. +.P +.\" pow(-INFINITY, >0 [[odd]]) = -INFINITY +If +.I x +is negative infinity, +and +.I y +is an odd integer greater than 0, +the result is negative infinity. +.P +.\" pow(-INFINITY, >0 [[!odd]]) = INFINITY +If +.I x +is negative infinity, +and +.I y +greater than 0 and not an odd integer, +the result is positive infinity. +.P +.\" pow(INFINITY, <0) = +0 +If +.I x +is positive infinity, +and +.I y +less than 0, +the result is +0. +.P +.\" pow(INFINITY, >0) = INFINITY +If +.I x +is positive infinity, +and +.I y +greater than 0, +the result is positive infinity. +.P +.\" pow(NaN, y) or pow(x, NaN) = NaN +Except as specified above, if +.I x +or +.I y +is a NaN, the result is a NaN. +.SH ERRORS +.\" FIXME . review status of this error +.\" longstanding bug report for glibc: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=369 +.\" For negative x, and -large and +large y, glibc 2.8 gives incorrect +.\" results +.\" pow(-0.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +.\" +.\" pow(-1.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-0.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-1.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero, and \fIy\fP is negative +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: the result overflows +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: the result underflows +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pow (), +.BR powf (), +.BR powl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +.SS Historical bugs (now fixed) +Before glibc 2.28, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932 +on some architectures (e.g., x86-64) +.BR pow () +may be more than 10,000 times slower for some inputs +than for other nearby inputs. +This affects only +.BR pow (), +and not +.BR powf () +nor +.BR powl (). +This problem was fixed +.\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5 +in glibc 2.28. +.P +A number of bugs +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866 +in the glibc implementation of +.BR pow () +were fixed in glibc 2.16. +.P +In glibc 2.9 and earlier, +.\" +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776 +when a pole error occurs, +.I errno +is set to +.B EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, +.\" or possibly 2.9, I haven't found the source code change +.\" and I don't have a 2.9 system to test +glibc does the right thing. +.P +In glibc 2.3.2 and earlier, +.\" Actually, glibc 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in glibc 2.3.2. +when an overflow or underflow error occurs, glibc's +.BR pow () +generates a bogus invalid floating-point exception +.RB ( FE_INVALID ) +in addition to the overflow or underflow exception. +.SH SEE ALSO +.BR cbrt (3), +.BR cpow (3), +.BR sqrt (3) diff --git a/man/man3/pow10.3 b/man/man3/pow10.3 new file mode 100644 index 0000000..b8c9bc6 --- /dev/null +++ b/man/man3/pow10.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pow10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pow10, pow10f, pow10l \- base-10 power functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <math.h> +.P +.BI "double pow10(double " x ); +.BI "float pow10f(float " x ); +.BI "long double pow10l(long double " x ); +.fi +.SH DESCRIPTION +These functions return the value of 10 raised to the power +.IR x . +.P +.BR "Note well" : +These functions perform exactly the same task as the functions described in +.BR exp10 (3), +with the difference that the latter functions are now standardized +in TS\ 18661-4:2015. +Those latter functions should be used in preference +to the functions described in this page. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pow10 (), +.BR pow10f (), +.BR pow10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH VERSIONS +glibc 2.1. +Removed in glibc 2.27. +.\" glibc commit 5a80d39d0d2587e9bd8e72f19e92eeb2a66fbe9e +.SH SEE ALSO +.BR exp10 (3), +.BR pow (3) diff --git a/man/man3/pow10f.3 b/man/man3/pow10f.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man/man3/pow10f.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man/man3/pow10l.3 b/man/man3/pow10l.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man/man3/pow10l.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man/man3/powerof2.3 b/man/man3/powerof2.3 new file mode 100644 index 0000000..c6e82d4 --- /dev/null +++ b/man/man3/powerof2.3 @@ -0,0 +1,46 @@ +.\" Copyright (C) 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH powerof2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +powerof2 \- test if a value is a power of 2 +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <sys/param.h> +.P +.BI "int powerof2(" x ); +.fi +.SH DESCRIPTION +This macro returns true if +.I x +is a power of 2, +and false otherwise. +.P +.B 0 +is considered a power of 2. +This can make sense considering wrapping of unsigned integers, +and has interesting properties. +.SH RETURN VALUE +True or false, +if +.I x +is a power of 2 or not, +respectively. +.SH STANDARDS +BSD. +.SH CAVEATS +The arguments may be evaluated more than once. +.P +Because this macro is implemented using bitwise operations, +some negative values can invoke undefined behavior. +For example, +the following invokes undefined behavior: +.IR "powerof2(INT_MIN);". +Call it only with unsigned types to be safe. +.SH SEE ALSO +.BR stdc_bit_ceil (3), +.BR stdc_bit_floor (3) diff --git a/man/man3/powf.3 b/man/man3/powf.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man/man3/powf.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man/man3/powl.3 b/man/man3/powl.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man/man3/powl.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man/man3/printf.3 b/man/man3/printf.3 new file mode 100644 index 0000000..7023e2d --- /dev/null +++ b/man/man3/printf.3 @@ -0,0 +1,1239 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Earlier versions of this page influenced the present text. +.\" It was derived from a Berkeley page with version +.\" @(#)printf.3 6.14 (Berkeley) 7/30/91 +.\" converted for Linux by faith@cs.unc.edu, updated by +.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. +.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes +.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes +.\" +.TH printf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, +vsprintf, vsnprintf \- formatted output conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int printf(const char *restrict " format ", ...);" +.BI "int fprintf(FILE *restrict " stream , +.BI " const char *restrict " format ", ...);" +.BI "int dprintf(int " fd , +.BI " const char *restrict " format ", ...);" +.BI "int sprintf(char *restrict " str , +.BI " const char *restrict " format ", ...);" +.BI "int snprintf(char " str "[restrict ." size "], size_t " size , +.BI " const char *restrict " format ", ...);" +.P +.BI "int vprintf(const char *restrict " format ", va_list " ap ); +.BI "int vfprintf(FILE *restrict " stream , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vdprintf(int " fd , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vsprintf(char *restrict " str , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vsnprintf(char " str "[restrict ." size "], size_t " size , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR snprintf (), +.BR vsnprintf (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR dprintf (), +.BR vdprintf (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The functions in the +.BR printf () +family produce output according to a +.I format +as described below. +The functions +.BR printf () +and +.BR vprintf () +write output to +.IR stdout , +the standard output stream; +.BR fprintf () +and +.BR vfprintf () +write output to the given output +.IR stream ; +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +and +.BR vsnprintf () +write to the character string +.IR str . +.P +The function +.BR dprintf () +is the same as +.BR fprintf () +except that it outputs to a file descriptor, +.IR fd , +instead of to a +.BR stdio (3) +stream. +.P +The functions +.BR snprintf () +and +.BR vsnprintf () +write at most +.I size +bytes (including the terminating null byte (\[aq]\e0\[aq])) to +.IR str . +.P +The functions +.BR vprintf (), +.BR vfprintf (), +.BR vdprintf (), +.BR vsprintf (), +.BR vsnprintf () +are equivalent to the functions +.BR printf (), +.BR fprintf (), +.BR dprintf (), +.BR sprintf (), +.BR snprintf (), +respectively, except that they are called with a +.I va_list +instead of a variable number of arguments. +These functions do not call the +.I va_end +macro. +Because they invoke the +.I va_arg +macro, the value of +.I ap +is undefined after the call. +See +.BR stdarg (3). +.P +All of these functions write the output under the control of a +.I format +string that specifies how subsequent arguments (or arguments accessed via +the variable-length argument facilities of +.BR stdarg (3)) +are converted for output. +.P +C99 and POSIX.1-2001 specify that the results are undefined if a call to +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +or +.BR vsnprintf () +would cause copying to take place between objects that overlap +(e.g., if the target string array and one of the supplied input arguments +refer to the same buffer). +See CAVEATS. +.SS Format of the format string +The format string is a character string, beginning and ending +in its initial shift state, if any. +The format string is composed of zero or more directives: ordinary +characters (not +.BR % ), +which are copied unchanged to the output stream; +and conversion specifications, each of which results in fetching zero or +more subsequent arguments. +Each conversion specification is introduced by +the character +.BR % , +and ends with a +.IR "conversion specifier" . +In between there may be (in this order) zero or more +.IR flags , +an optional minimum +.IR "field width" , +an optional +.I precision +and an optional +.IR "length modifier" . +.P +The overall syntax of a conversion specification is: +.P +.in +4n +.nf +%[$][flags][width][.precision][length modifier]conversion +.fi +.in +.P +The arguments must correspond properly (after type promotion) with the +conversion specifier. +By default, the arguments are used in the order +given, where each \[aq]*\[aq] (see +.I "Field width" +and +.I Precision +below) and each conversion specifier asks for the next +argument (and it is an error if insufficiently many arguments are given). +One can also specify explicitly which argument is taken, +at each place where an argument is required, by writing "%m$" instead +of \[aq]%\[aq] and "*m$" instead of \[aq]*\[aq], +where the decimal integer \fIm\fP denotes +the position in the argument list of the desired argument, indexed starting +from 1. +Thus, +.P +.in +4n +.EX +printf("%*d", width, num); +.EE +.in +.P +and +.P +.in +4n +.EX +printf("%2$*1$d", width, num); +.EE +.in +.P +are equivalent. +The second style allows repeated references to the +same argument. +The C99 standard does not include the style using \[aq]$\[aq], +which comes from the Single UNIX Specification. +If the style using +\[aq]$\[aq] is used, it must be used throughout for all conversions taking an +argument and all width and precision arguments, but it may be mixed +with "%%" formats, which do not consume an argument. +There may be no +gaps in the numbers of arguments specified using \[aq]$\[aq]; for example, if +arguments 1 and 3 are specified, argument 2 must also be specified +somewhere in the format string. +.P +For some numeric conversions a radix character ("decimal point") or +thousands' grouping character is used. +The actual character used +depends on the +.B LC_NUMERIC +part of the locale. +(See +.BR setlocale (3).) +The POSIX locale +uses \[aq].\[aq] as radix character, and does not have a grouping character. +Thus, +.P +.in +4n +.EX +printf("%\[aq].2f", 1234567.89); +.EE +.in +.P +results in "1234567.89" in the POSIX locale, in "1234567,89" in the +nl_NL locale, and in "1.234.567,89" in the da_DK locale. +.SS Flag characters +The character % is followed by zero or more of the following flags: +.TP +.B # +The value should be converted to an "alternate form". +For +.B o +conversions, the first character of the output string is made zero +(by prefixing a 0 if it was not zero already). +For +.B x +and +.B X +conversions, a nonzero result has the string "0x" (or "0X" for +.B X +conversions) prepended to it. +For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of those +conversions only if a digit follows). +For +.B g +and +.B G +conversions, trailing zeros are not removed from the result as they would +otherwise be. +For +.BR m , +if +.I errno +contains a valid error code, +the output of +.I strerrorname_np(errno) +is printed; +otherwise, the value stored in +.I errno +is printed as a decimal number. +For other conversions, the result is undefined. +.TP +.B \&0 +The value should be zero padded. +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the converted value is padded on the left with zeros rather +than blanks. +If the +.B \&0 +and +.B \- +flags both appear, the +.B \&0 +flag is ignored. +If a precision is given with an integer conversion +.RB ( d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X ), +the +.B \&0 +flag is ignored. +For other conversions, the behavior is undefined. +.TP +.B \- +The converted value is to be left adjusted on the field boundary. +(The default is right justification.) +The converted value is padded on the right with blanks, rather +than on the left with blanks or zeros. +A +.B \- +overrides a +.B \&0 +if both are given. +.TP +.B \[aq] \[aq] +(a space) A blank should be left before a positive number +(or empty string) produced by a signed conversion. +.TP +.B + +A sign (+ or \-) should always be placed before a number produced by a signed +conversion. +By default, a sign is used only for negative numbers. +A +.B + +overrides a space if both are used. +.P +The five flag characters above are defined in the C99 standard. +The Single UNIX Specification specifies one further flag character. +.TP +.B \[aq] +For decimal conversion +.RB ( i , +.BR d , +.BR u , +.BR f , +.BR F , +.BR g , +.BR G ) +the output is to be grouped with thousands' grouping characters +if the locale information indicates any. +(See +.BR setlocale (3).) +Note that many versions of +.BR gcc (1) +cannot parse this option and will issue a warning. +(SUSv2 did not +include \fI%\[aq]F\fP, but SUSv3 added it.) +Note also that the default locale of a C program is "C" +whose locale information indicates no thousands' grouping character. +Therefore, without a prior call to +.BR setlocale (3), +no thousands' grouping characters will be printed. +.P +glibc 2.2 adds one further flag character. +.TP +.B I +For decimal integer conversion +.RB ( i , +.BR d , +.BR u ) +the output uses the locale's alternative output digits, if any. +For example, since glibc 2.2.3 this will give Arabic-Indic digits +in the Persian ("fa_IR") locale. +.\" outdigits keyword in locale file +.SS Field width +An optional decimal digit string (with nonzero first digit) specifying +a minimum field width. +If the converted value has fewer characters +than the field width, it will be padded with spaces on the left +(or right, if the left-adjustment flag has been given). +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the field width +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +A negative field width is taken as a \[aq]\-\[aq] flag followed by a +positive field width. +In no case does a nonexistent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.SS Precision +An optional precision, in the form of a period (\[aq].\[aq]) followed by an +optional decimal digit string. +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the precision +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +If the precision is given as just \[aq].\[aq], the precision is taken to +be zero. +A negative precision is taken as if the precision were omitted. +This gives the minimum number of digits to appear for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, the number of digits to appear after the radix character for +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.B F +conversions, the maximum number of significant digits for +.B g +and +.B G +conversions, or the maximum number of characters to be printed from a +string for +.B s +and +.B S +conversions. +.SS Length modifier +Here, "integer conversion" stands for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.B X +conversion. +.TP +.B hh +A following integer conversion corresponds to a +.I signed char +or +.I unsigned char +argument, or a following +.B n +conversion corresponds to a pointer to a +.I signed char +argument. +.TP +.B h +A following integer conversion corresponds to a +.I short +or +.I unsigned short +argument, or a following +.B n +conversion corresponds to a pointer to a +.I short +argument. +.TP +.B l +(ell) A following integer conversion corresponds to a +.I long +or +.I unsigned long +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long +argument, or a following +.B c +conversion corresponds to a +.I wint_t +argument, or a following +.B s +conversion corresponds to a pointer to +.I wchar_t +argument. +On a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion, this length modifier is ignored (C99; not in SUSv2). +.TP +.B ll +(ell-ell). +A following integer conversion corresponds to a +.I long long +or +.I unsigned long long +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long long +argument. +.TP +.B q +A synonym for +.BR ll . +This is a nonstandard extension, derived from BSD; +avoid its use in new code. +.TP +.B L +A following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion corresponds to a +.I long double +argument. +(C99 allows %LF, but SUSv2 does not.) +.TP +.B j +A following integer conversion corresponds to an +.I intmax_t +or +.I uintmax_t +argument, or a following +.B n +conversion corresponds to a pointer to an +.I intmax_t +argument. +.TP +.B z +A following integer conversion corresponds to a +.I size_t +or +.I ssize_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I size_t +argument. +.TP +.B Z +A nonstandard synonym for +.B z +that predates the appearance of +.BR z . +Do not use in new code. +.TP +.B t +A following integer conversion corresponds to a +.I ptrdiff_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I ptrdiff_t +argument. +.P +SUSv3 specifies all of the above, +except for those modifiers explicitly noted as being nonstandard extensions. +SUSv2 specified only the length modifiers +.B h +(in +.BR hd , +.BR hi , +.BR ho , +.BR hx , +.BR hX , +.BR hn ) +and +.B l +(in +.BR ld , +.BR li , +.BR lo , +.BR lx , +.BR lX , +.BR ln , +.BR lc , +.BR ls ) +and +.B L +(in +.BR Le , +.BR LE , +.BR Lf , +.BR Lg , +.BR LG ). +.P +As a nonstandard extension, the GNU implementations treats +.B ll +and +.B L +as synonyms, so that one can, for example, write +.B llg +(as a synonym for the standards-compliant +.BR Lg ) +and +.B Ld +(as a synonym for the standards compliant +.BR lld ). +Such usage is nonportable. +.\" +.SS Conversion specifiers +A character that specifies the type of conversion to be applied. +The conversion specifiers and their meanings are: +.TP +.BR d ", " i +The +.I int +argument is converted to signed decimal notation. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR o ", " u ", " x ", " X +The +.I "unsigned int" +argument is converted to unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal +.RB ( x +and +.BR X ) +notation. +The letters +.B abcdef +are used for +.B x +conversions; the letters +.B ABCDEF +are used for +.B X +conversions. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR e ", " E +The +.I double +argument is rounded and converted in the style +.RB [\-]d \&. ddd e \(+-dd +where there is one digit (which is nonzero if the argument is nonzero) +before the decimal-point character and the number +of digits after it is equal to the precision; if the precision is missing, +it is taken as 6; if the precision is zero, no decimal-point character +appears. +An +.B E +conversion uses the letter +.B E +(rather than +.BR e ) +to introduce the exponent. +The exponent always contains at least two +digits; if the value is zero, the exponent is 00. +.TP +.BR f ", " F +The +.I double +argument is rounded and converted to decimal notation in the style +.RB [\-]ddd \&. ddd, +where the number of digits after the decimal-point character is equal to +the precision specification. +If the precision is missing, it is taken as +6; if the precision is explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.IP +(SUSv2 does not know about +.B F +and says that character string representations for infinity and NaN +may be made available. +SUSv3 adds a specification for +.BR F . +The C99 standard specifies "[\-]inf" or "[\-]infinity" +for infinity, and a string starting with "nan" for NaN, in the case of +.B f +conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of +.B F +conversion.) +.TP +.BR g ", " G +The +.I double +argument is converted in style +.B f +or +.B e +(or +.B F +or +.B E +for +.B G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.B e +is used if the exponent from its conversion is less than \-4 or greater +than or equal to the precision. +Trailing zeros are removed from the +fractional part of the result; a decimal point appears only if it is +followed by at least one digit. +.TP +.BR a ", " A +(C99; not in SUSv2, but added in SUSv3) +For +.B a +conversion, the +.I double +argument is converted to hexadecimal notation (using the letters abcdef) +in the style +.RB [\-] 0x h \&. hhhh p \(+-d; +for +.B A +conversion the prefix +.BR 0X , +the letters ABCDEF, and the exponent separator +.B P +is used. +There is one hexadecimal digit before the decimal point, +and the number of digits after it is equal to the precision. +The default precision suffices for an exact representation of the value +if an exact representation in base 2 exists +and otherwise is sufficiently large to distinguish values of type +.IR double . +The digit before the decimal point is unspecified for nonnormalized +numbers, and nonzero but otherwise unspecified for normalized numbers. +The exponent always contains at least one +digit; if the value is zero, the exponent is 0. +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to an +.IR "unsigned char" , +and the resulting character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is converted to a multibyte sequence by a call +to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state, and the +resulting multibyte string is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const char\ *" +argument is expected to be a pointer to an array of character type (pointer +to a string). +Characters from the array are written up to (but not +including) a terminating null byte (\[aq]\e0\[aq]); +if a precision is specified, no more than the number specified +are written. +If a precision is given, no null byte need be present; +if the precision is not specified, or is greater than the size of the +array, the array must contain a terminating null byte. +.IP +If an +.B l +modifier is present: the +.I "const wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are converted to multibyte characters +(each by a call to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state before +the first wide character), up to and including a terminating null +wide character. +The resulting multibyte characters are written up to +(but not including) the terminating null byte. +If a precision is +specified, no more bytes than the number specified are written, but +no partial multibyte characters are written. +Note that the precision +determines the number of +.I bytes +written, not the number of +.I wide characters +or +.IR "screen positions" . +The array must contain a terminating null wide character, unless a +precision is given and it is so small that the number of bytes written +exceeds it before the end of the array is reached. +.TP +.B C +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR lc . +Don't use. +.TP +.B S +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR ls . +Don't use. +.TP +.B p +The +.I "void\ *" +pointer argument is printed in hexadecimal (as if by +.B %#x +or +.BR %#lx ). +.TP +.B n +The number of characters written so far is stored into the integer +pointed to by the corresponding argument. +That argument shall be an +.IR "int\ *" , +or variant whose size matches the (optionally) +supplied integer length modifier. +No argument is converted. +(This specifier is not supported by the bionic C library.) +The behavior is undefined if the conversion specification includes +any flags, a field width, or a precision. +.TP +.B m +(glibc extension; supported by uClibc and musl.) +Print output of +.I strerror(errno) +(or +.I strerrorname_np(errno) +in the alternate form). +No argument is required. +.TP +.B % +A \[aq]%\[aq] is written. +No argument is converted. +The complete conversion +specification is \[aq]%%\[aq]. +.SH RETURN VALUE +Upon successful return, these functions return the number of bytes +printed (excluding the null byte used to end output to strings). +.P +The functions +.BR snprintf () +and +.BR vsnprintf () +do not write more than +.I size +bytes (including the terminating null byte (\[aq]\e0\[aq])). +If the output was truncated due to this limit, then the return value +is the number of characters (excluding the terminating null byte) +which would have been written to the final string if enough space +had been available. +Thus, a return value of +.I size +or more means that the output was truncated. +(See also below under CAVEATS.) +.P +If an output error is encountered, a negative value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR printf (), +.BR fprintf (), +.BR sprintf (), +.BR snprintf (), +.BR vprintf (), +.BR vfprintf (), +.BR vsprintf (), +.BR vsnprintf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR fprintf () +.TQ +.BR printf () +.TQ +.BR sprintf () +.TQ +.BR vprintf () +.TQ +.BR vfprintf () +.TQ +.BR vsprintf () +.TQ +.BR snprintf () +.TQ +.BR vsnprintf () +C11, POSIX.1-2008. +.TP +.BR dprintf () +.TQ +.BR vdprintf () +GNU, POSIX.1-2008. +.SH HISTORY +.TP +.BR fprintf () +.TQ +.BR printf () +.TQ +.BR sprintf () +.TQ +.BR vprintf () +.TQ +.BR vfprintf () +.TQ +.BR vsprintf () +C89, POSIX.1-2001. +.TP +.BR snprintf () +.TQ +.BR vsnprintf () +SUSv2, C99, POSIX.1-2001. +.IP +Concerning the return value of +.BR snprintf (), +SUSv2 and C99 contradict each other: when +.BR snprintf () +is called with +.IR size =0 +then SUSv2 stipulates an unspecified return value less than 1, +while C99 allows +.I str +to be NULL in this case, and gives the return value (as always) +as the number of characters that would have been written in case +the output string has been large enough. +POSIX.1-2001 and later align their specification of +.BR snprintf () +with C99. +.TP +.BR dprintf () +.TQ +.BR vdprintf () +GNU, POSIX.1-2008. +.P +.\" Linux libc4 knows about the five C standard flags. +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" and the conversions +.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, +.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, +.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP, +.\" where \fBF\fP is a synonym for \fBf\fP. +.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms +.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP. +.\" (This is bad, and caused serious bugs later, when +.\" support for \fB%D\fP disappeared.) +.\" No locale-dependent radix character, +.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". +.\" .P +.\" Linux libc5 knows about the five C standard flags and the \[aq] flag, +.\" locale, "%m$" and "*m$". +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP +.\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug). +.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP, +.\" but adds the conversion character +.\" .BR m , +.\" which outputs +.\" .IR strerror(errno) . +.\" .P +.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. +.\" .P +glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP +and conversion characters \fBa\fP and \fBA\fP. +.P +glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, +and the flag character \fBI\fP. +.P +glibc 2.35 gives a meaning to the alternate form +.RB ( # ) +of the +.B m +conversion specifier, that is +.IR %#m . +.SH CAVEATS +Some programs imprudently rely on code such as the following +.P +.in +4n +.EX +sprintf(buf, "%s some further text", buf); +.EE +.in +.P +to append text to +.IR buf . +However, the standards explicitly note that the results are undefined +if source and destination buffers overlap when calling +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +and +.BR vsnprintf (). +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075 +Depending on the version of +.BR gcc (1) +used, and the compiler options employed, calls such as the above will +.B not +produce the expected results. +.P +The glibc implementation of the functions +.BR snprintf () +and +.BR vsnprintf () +conforms to the C99 standard, that is, behaves as described above, +since glibc 2.1. +Until glibc 2.0.6, they would return \-1 +when the output was truncated. +.\" .SH HISTORY +.\" UNIX V7 defines the three routines +.\" .BR printf (), +.\" .BR fprintf (), +.\" .BR sprintf (), +.\" and has the flag \-, the width or precision *, the length modifier l, +.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. +.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags +.\" #, + and <space> and no longer mentions D,O,U,X. +.\" 2.11BSD has +.\" .BR vprintf (), +.\" .BR vfprintf (), +.\" .BR vsprintf (), +.\" and warns not to use D,O,U,X. +.\" 4.3BSD Reno has the flag 0, the length modifiers h and L, +.\" and the conversions n, p, E, G, X (with current meaning) +.\" and deprecates D,O,U. +.\" 4.4BSD introduces the functions +.\" .BR snprintf () +.\" and +.\" .BR vsnprintf (), +.\" and the length modifier q. +.\" FreeBSD also has functions +.\" .BR asprintf () +.\" and +.\" .BR vasprintf (), +.\" that allocate a buffer large enough for +.\" .BR sprintf (). +.\" In glibc there are functions +.\" .BR dprintf () +.\" and +.\" .BR vdprintf () +.\" that print to a file descriptor instead of a stream. +.SH BUGS +Because +.BR sprintf () +and +.BR vsprintf () +assume an arbitrarily long string, callers must be careful not to overflow +the actual space; this is often impossible to assure. +Note that the length +of the strings produced is locale-dependent and difficult to predict. +Use +.BR snprintf () +and +.BR vsnprintf () +instead (or +.BR asprintf (3) +and +.BR vasprintf (3)). +.\" .P +.\" Linux libc4.[45] does not have a +.\" .BR snprintf (), +.\" but provides a libbsd that contains an +.\" .BR snprintf () +.\" equivalent to +.\" .BR sprintf (), +.\" that is, one that ignores the +.\" .I size +.\" argument. +.\" Thus, the use of +.\" .BR snprintf () +.\" with early libc4 leads to serious security problems. +.P +Code such as +.BI printf( foo ); +often indicates a bug, since +.I foo +may contain a % character. +If +.I foo +comes from untrusted user input, it may contain \fB%n\fP, causing the +.BR printf () +call to write to memory and creating a security hole. +.\" .P +.\" Some floating-point conversions under early libc4 +.\" caused memory leaks. +.SH EXAMPLES +To print +.I Pi +to five decimal places: +.P +.in +4n +.EX +#include <math.h> +#include <stdio.h> +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.EE +.in +.P +To print a date and time in the form "Sunday, July 3, 10:02", +where +.I weekday +and +.I month +are pointers to strings: +.P +.in +4n +.EX +#include <stdio.h> +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.EE +.in +.P +Many countries use the day-month-year order. +Hence, an internationalized version must be able to print +the arguments in an order specified by the format: +.P +.in +4n +.EX +#include <stdio.h> +fprintf(stdout, format, + weekday, month, day, hour, min); +.EE +.in +.P +where +.I format +depends on locale, and may permute the arguments. +With the value: +.P +.in +4n +.EX +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.EE +.in +.P +one might obtain "Sonntag, 3. Juli, 10:02". +.P +To allocate a sufficiently large string and print into it +(code correct for both glibc 2.0 and glibc 2.1): +.P +.EX +#include <stdio.h> +#include <stdlib.h> +#include <stdarg.h> +\& +char * +make_message(const char *fmt, ...) +{ + int n = 0; + size_t size = 0; + char *p = NULL; + va_list ap; +\& + /* Determine required size. */ +\& + va_start(ap, fmt); + n = vsnprintf(p, size, fmt, ap); + va_end(ap); +\& + if (n < 0) + return NULL; +\& + size = (size_t) n + 1; /* One extra byte for \[aq]\e0\[aq] */ + p = malloc(size); + if (p == NULL) + return NULL; +\& + va_start(ap, fmt); + n = vsnprintf(p, size, fmt, ap); + va_end(ap); +\& + if (n < 0) { + free(p); + return NULL; + } +\& + return p; +} +.EE +.P +If truncation occurs in glibc versions prior to glibc 2.0.6, +this is treated as an error instead of being handled gracefully. +.SH SEE ALSO +.BR printf (1), +.BR asprintf (3), +.BR puts (3), +.BR scanf (3), +.BR setlocale (3), +.BR strfromd (3), +.BR wcrtomb (3), +.BR wprintf (3), +.BR locale (5) diff --git a/man/man3/profil.3 b/man/man3/profil.3 new file mode 100644 index 0000000..d4773c3 --- /dev/null +++ b/man/man3/profil.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer <aeb@cwi.nl> +.\" (prompted by Bas V. de Bakker <bas@phys.uva.nl>) +.\" Corrected (and moved to man3), 980612, aeb +.TH profil 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +profil \- execution time profile +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int profil(unsigned short *" buf ", size_t " bufsiz , +.BI " size_t " offset ", unsigned int " scale ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR profil (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +This routine provides a means to find out in what areas your program +spends most of its time. +The argument +.I buf +points to +.I bufsiz +bytes of core. +Every virtual 10 milliseconds, the user's program counter (PC) +is examined: +.I offset +is subtracted and the result is multiplied by +.I scale +and divided by 65536. +If the resulting value is less than +.IR bufsiz , +then the corresponding entry in +.I buf +is incremented. +If +.I buf +is NULL, profiling is disabled. +.SH RETURN VALUE +Zero is always returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR profil () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +Similar to a call in SVr4. +.SH BUGS +.BR profil () +cannot be used on a program that also uses +.B ITIMER_PROF +interval timers (see +.BR setitimer (2)). +.P +True kernel profiling provides more accurate results. +.\" Libc 4.4 contained a kernel patch providing a system call profil. +.SH SEE ALSO +.BR gprof (1), +.BR sprof (1), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2) diff --git a/man/man3/program_invocation_name.3 b/man/man3/program_invocation_name.3 new file mode 100644 index 0000000..874420d --- /dev/null +++ b/man/man3/program_invocation_name.3 @@ -0,0 +1,66 @@ +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH program_invocation_name 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +program_invocation_name, program_invocation_short_name \- \ +obtain name used to invoke calling program +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <errno.h> +.P +.BI "extern char *" program_invocation_name ; +.BI "extern char *" program_invocation_short_name ; +.fi +.SH DESCRIPTION +.I program_invocation_name +contains the name that was used to invoke the calling program. +This is the same as the value of +.I argv[0] +in +.IR main (), +with the difference that the scope of +.I program_invocation_name +is global. +.P +.I program_invocation_short_name +contains the basename component of name that was used to invoke +the calling program. +That is, it is the same value as +.IR program_invocation_name , +with all text up to and including the final slash (/), if any, removed. +.P +These variables are automatically initialized by the glibc run-time +startup code. +.SH VERSIONS +The Linux-specific +.IR /proc/ pid /cmdline +file provides access to similar information. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man3/program_invocation_short_name.3 b/man/man3/program_invocation_short_name.3 new file mode 100644 index 0000000..f603f6c --- /dev/null +++ b/man/man3/program_invocation_short_name.3 @@ -0,0 +1 @@ +.so man3/program_invocation_name.3 diff --git a/man/man3/psiginfo.3 b/man/man3/psiginfo.3 new file mode 100644 index 0000000..cd748fa --- /dev/null +++ b/man/man3/psiginfo.3 @@ -0,0 +1 @@ +.so man3/psignal.3 diff --git a/man/man3/psignal.3 b/man/man3/psignal.3 new file mode 100644 index 0000000..b453ae7 --- /dev/null +++ b/man/man3/psignal.3 @@ -0,0 +1,114 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH psignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +psignal, psiginfo \- print signal description +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "void psignal(int " sig ", const char *" s ); +.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR psignal (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR psiginfo (): +.nf + _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR psignal () +function displays a message on \fIstderr\fP +consisting of the string \fIs\fP, a colon, a space, a string +describing the signal number \fIsig\fP, and a trailing newline. +If the string \fIs\fP is NULL or empty, the colon and space are omitted. +If \fIsig\fP is invalid, +the message displayed will indicate an unknown signal. +.P +The +.BR psiginfo () +function is like +.BR psignal (), +except that it displays information about the signal described by +.IR pinfo , +which should point to a valid +.I siginfo_t +structure. +As well as the signal description, +.BR psiginfo () +displays information about the origin of the signal, +and other information relevant to the signal +(e.g., the relevant memory address for hardware-generated signals, +the child process ID for +.BR SIGCHLD , +and the user ID and process ID of the sender, for signals set using +.BR kill (2) +or +.BR sigqueue (3)). +.SH RETURN VALUE +The +.BR psignal () +and +.BR psiginfo () +functions return no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR psignal (), +.BR psiginfo () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.10. +POSIX.1-2008, 4.3BSD. +.SH BUGS +Up to glibc 2.12, +.BR psiginfo () +had the following bugs: +.IP \[bu] 3 +In some circumstances, a trailing newline is not printed. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12107 +.\" Reportedly now fixed; check glibc 2.13 +.IP \[bu] +Additional details are not displayed for real-time signals. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12108 +.\" Reportedly now fixed; check glibc 2.13 +.SH SEE ALSO +.BR sigaction (2), +.BR perror (3), +.BR strsignal (3), +.BR signal (7) diff --git a/man/man3/pthread_atfork.3 b/man/man3/pthread_atfork.3 new file mode 100644 index 0000000..a5844ab --- /dev/null +++ b/man/man3/pthread_atfork.3 @@ -0,0 +1,108 @@ +.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_atfork 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_atfork \- register fork handlers +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void)," +.BI " void (*" child ")(void));" +.fi +.SH DESCRIPTION +The +.BR pthread_atfork () +function registers fork handlers that are to be executed when +.BR fork (2) +is called by any thread in a process. +The handlers are executed in the context of the thread that calls +.BR fork (2). +.P +Three kinds of handler can be registered: +.IP \[bu] 3 +.I prepare +specifies a handler that is executed in the parent process before +.BR fork (2) +processing starts. +.IP \[bu] +.I parent +specifies a handler that is executed in the parent process after +.BR fork (2) +processing completes. +.IP \[bu] +.I child +specifies a handler that is executed in the child process after +.BR fork (2) +processing completes. +.P +Any of the three arguments may be NULL if no handler is needed +in the corresponding phase of +.BR fork (2) +processing. +.SH RETURN VALUE +On success, +.BR pthread_atfork () +returns zero. +On error, it returns an error number. +.BR pthread_atfork () +may be called multiple times by a process +to register additional handlers. +The handlers for each phase are called in a specified order: the +.I prepare +handlers are called in reverse order of registration; the +.I parent +and +.I child +handlers are called in the order of registration. +.SH ERRORS +.TP +.B ENOMEM +Could not allocate memory to record the fork handler list entry. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +When +.BR fork (2) +is called in a multithreaded process, +only the calling thread is duplicated in the child process. +The original intention of +.BR pthread_atfork () +was to allow the child process to be returned to a consistent state. +For example, at the time of the call to +.BR fork (2), +other threads may have locked mutexes that are visible in the +user-space memory duplicated in the child. +Such mutexes would never be unlocked, +since the threads that placed the locks are not duplicated in the child. +The intent of +.BR pthread_atfork () +was to provide a mechanism whereby the application (or a library) +could ensure that mutexes and other process and thread state would be +restored to a consistent state. +In practice, this task is generally too difficult to be practicable. +.P +After a +.BR fork (2) +in a multithreaded process returns in the child, +the child should call only async-signal-safe functions (see +.BR signal\-safety (7)) +until such time as it calls +.BR execve (2) +to execute a new program. +.P +POSIX.1 specifies that +.BR pthread_atfork () +shall not fail with the error +.BR EINTR . +.SH SEE ALSO +.BR fork (2), +.BR atexit (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_destroy.3 b/man/man3/pthread_attr_destroy.3 new file mode 100644 index 0000000..4e7c949 --- /dev/null +++ b/man/man3/pthread_attr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_init.3 diff --git a/man/man3/pthread_attr_getaffinity_np.3 b/man/man3/pthread_attr_getaffinity_np.3 new file mode 100644 index 0000000..c6af8fa --- /dev/null +++ b/man/man3/pthread_attr_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setaffinity_np.3 diff --git a/man/man3/pthread_attr_getdetachstate.3 b/man/man3/pthread_attr_getdetachstate.3 new file mode 100644 index 0000000..c57ecd5 --- /dev/null +++ b/man/man3/pthread_attr_getdetachstate.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setdetachstate.3 diff --git a/man/man3/pthread_attr_getguardsize.3 b/man/man3/pthread_attr_getguardsize.3 new file mode 100644 index 0000000..766ca2f --- /dev/null +++ b/man/man3/pthread_attr_getguardsize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setguardsize.3 diff --git a/man/man3/pthread_attr_getinheritsched.3 b/man/man3/pthread_attr_getinheritsched.3 new file mode 100644 index 0000000..65239cb --- /dev/null +++ b/man/man3/pthread_attr_getinheritsched.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setinheritsched.3 diff --git a/man/man3/pthread_attr_getschedparam.3 b/man/man3/pthread_attr_getschedparam.3 new file mode 100644 index 0000000..3f830fd --- /dev/null +++ b/man/man3/pthread_attr_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedparam.3 diff --git a/man/man3/pthread_attr_getschedpolicy.3 b/man/man3/pthread_attr_getschedpolicy.3 new file mode 100644 index 0000000..10f740c --- /dev/null +++ b/man/man3/pthread_attr_getschedpolicy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedpolicy.3 diff --git a/man/man3/pthread_attr_getscope.3 b/man/man3/pthread_attr_getscope.3 new file mode 100644 index 0000000..965fd62 --- /dev/null +++ b/man/man3/pthread_attr_getscope.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setscope.3 diff --git a/man/man3/pthread_attr_getsigmask_np.3 b/man/man3/pthread_attr_getsigmask_np.3 new file mode 100644 index 0000000..92b55d3 --- /dev/null +++ b/man/man3/pthread_attr_getsigmask_np.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setsigmask_np.3 diff --git a/man/man3/pthread_attr_getstack.3 b/man/man3/pthread_attr_getstack.3 new file mode 100644 index 0000000..2b20d7e --- /dev/null +++ b/man/man3/pthread_attr_getstack.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstack.3 diff --git a/man/man3/pthread_attr_getstackaddr.3 b/man/man3/pthread_attr_getstackaddr.3 new file mode 100644 index 0000000..49d8a85 --- /dev/null +++ b/man/man3/pthread_attr_getstackaddr.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstackaddr.3 diff --git a/man/man3/pthread_attr_getstacksize.3 b/man/man3/pthread_attr_getstacksize.3 new file mode 100644 index 0000000..52431f5 --- /dev/null +++ b/man/man3/pthread_attr_getstacksize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstacksize.3 diff --git a/man/man3/pthread_attr_init.3 b/man/man3/pthread_attr_init.3 new file mode 100644 index 0000000..0cb3a5a --- /dev/null +++ b/man/man3/pthread_attr_init.3 @@ -0,0 +1,313 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_init, pthread_attr_destroy \- initialize and destroy +thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_init(pthread_attr_t *" attr ); +.BI "int pthread_attr_destroy(pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_init () +function initializes the thread attributes object pointed to by +.I attr +with default attribute values. +After this call, individual attributes of the object can be set +using various related functions (listed under SEE ALSO), +and then the object can be used in one or more +.BR pthread_create (3) +calls that create threads. +.P +Calling +.BR pthread_attr_init () +on a thread attributes object that has already been initialized +results in undefined behavior. +.P +When a thread attributes object is no longer required, +it should be destroyed using the +.BR pthread_attr_destroy () +function. +Destroying a thread attributes object has no effect +on threads that were created using that object. +.P +Once a thread attributes object has been destroyed, +it can be reinitialized using +.BR pthread_attr_init (). +Any other use of a destroyed thread attributes object +has undefined results. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B ENOMEM +error for +.BR pthread_attr_init (); +on Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_init (), +.BR pthread_attr_destroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.I pthread_attr_t +type should be treated as opaque: +any access to the object other than via pthreads functions +is nonportable and produces undefined results. +.SH EXAMPLES +The program below optionally makes use of +.BR pthread_attr_init () +and various related functions to initialize a thread attributes +object that is used to create a single thread. +Once created, the thread uses the +.BR pthread_getattr_np (3) +function (a nonstandard GNU extension) to retrieve the thread's +attributes, and then displays those attributes. +.P +If the program is run with no command-line argument, +then it passes NULL as the +.I attr +argument of +.BR pthread_create (3), +so that the thread is created with default attributes. +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.P +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Thread attributes: + Detach state = PTHREAD_CREATE_JOINABLE + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_INHERIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 4096 bytes + Stack address = 0x40196000 + Stack size = 0x201000 bytes +.EE +.in +.P +When we supply a stack size as a command-line argument, +the program initializes a thread attributes object, +sets various attributes in that object, +and passes a pointer to the object in the call to +.BR pthread_create (3). +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.P +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ./a.out 0x3000000" +posix_memalign() allocated at 0x40197000 +Thread attributes: + Detach state = PTHREAD_CREATE_DETACHED + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_EXPLICIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 0 bytes + Stack address = 0x40197000 + Stack size = 0x3000000 bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_attr_init.c) +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include <err.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +static void +display_pthread_attr(pthread_attr_t *attr, char *prefix) +{ + int s, i; + size_t v; + void *stkaddr; + struct sched_param sp; +\& + s = pthread_attr_getdetachstate(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); + printf("%sDetach state = %s\en", prefix, + (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : + (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : + "???"); +\& + s = pthread_attr_getscope(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getscope"); + printf("%sScope = %s\en", prefix, + (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : + (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : + "???"); +\& + s = pthread_attr_getinheritsched(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); + printf("%sInherit scheduler = %s\en", prefix, + (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : + (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : + "???"); +\& + s = pthread_attr_getschedpolicy(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); + printf("%sScheduling policy = %s\en", prefix, + (i == SCHED_OTHER) ? "SCHED_OTHER" : + (i == SCHED_FIFO) ? "SCHED_FIFO" : + (i == SCHED_RR) ? "SCHED_RR" : + "???"); +\& + s = pthread_attr_getschedparam(attr, &sp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); + printf("%sScheduling priority = %d\en", prefix, sp.sched_priority); +\& + s = pthread_attr_getguardsize(attr, &v); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("%sGuard size = %zu bytes\en", prefix, v); +\& + s = pthread_attr_getstack(attr, &stkaddr, &v); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstack"); + printf("%sStack address = %p\en", prefix, stkaddr); + printf("%sStack size = %#zx bytes\en", prefix, v); +} +\& +static void * +thread_start(void *arg) +{ + int s; + pthread_attr_t gattr; +\& + /* pthread_getattr_np() is a non\-standard GNU extension that + retrieves the attributes of the thread specified in its + first argument. */ +\& + s = pthread_getattr_np(pthread_self(), &gattr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_np"); +\& + printf("Thread attributes:\en"); + display_pthread_attr(&gattr, "\et"); +\& + exit(EXIT_SUCCESS); /* Terminate all threads */ +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp; /* NULL or &attr */ + int s; +\& + attrp = NULL; +\& + /* If a command\-line argument was supplied, use it to set the + stack\-size attribute and set a few other thread attributes, + and set attrp pointing to thread attributes object. */ +\& + if (argc > 1) { + size_t stack_size; + void *sp; +\& + attrp = &attr; +\& + s = pthread_attr_init(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_init"); +\& + s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate"); +\& + s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched"); +\& + stack_size = strtoul(argv[1], NULL, 0); +\& + s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "posix_memalign"); +\& + printf("posix_memalign() allocated at %p\en", sp); +\& + s = pthread_attr_setstack(&attr, sp, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstack"); + } +\& + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_create"); +\& + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); + } +\& + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setdetachstate (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_attr_setsigmask_np (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthread_getattr_np (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setaffinity_np.3 b/man/man3/pthread_attr_setaffinity_np.3 new file mode 100644 index 0000000..a7d104a --- /dev/null +++ b/man/man3/pthread_attr_setaffinity_np.3 @@ -0,0 +1,120 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setaffinity_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get +CPU affinity attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", const cpu_set_t *" cpuset ); +.BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", cpu_set_t *" cpuset ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setaffinity_np () +function +sets the CPU affinity mask attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR cpuset . +This attribute determines the CPU affinity mask +of a thread created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getaffinity_np () +function +returns the CPU affinity mask attribute of the thread attributes object +referred to by +.I attr +in the buffer pointed to by +.IR cpuset . +.P +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +.P +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.B EINVAL +.RB ( pthread_attr_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.B CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_attr_getaffinity_np ()) +A CPU in the affinity mask of the thread attributes object referred to by +.I attr +lies outside the range specified by +.I cpusetsize +(i.e., +.IR cpuset / cpusetsize +is too small). +.TP +.B ENOMEM +.RB ( pthread_attr_setaffinity_np ()) +Could not allocate memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setaffinity_np (), +.BR pthread_attr_getaffinity_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.4. +.SH NOTES +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_init (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setdetachstate.3 b/man/man3/pthread_attr_setdetachstate.3 new file mode 100644 index 0000000..eeb5c03 --- /dev/null +++ b/man/man3/pthread_attr_setdetachstate.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setdetachstate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setdetachstate, pthread_attr_getdetachstate \- +set/get detach state attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setdetachstate(pthread_attr_t *" attr \ +", int " detachstate ); +.BI "int pthread_attr_getdetachstate(const pthread_attr_t *" attr , +.BI " int *" detachstate ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setdetachstate () +function sets the detach state attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR detachstate . +The detach state attribute determines whether a thread created using +the thread attributes object +.I attr +will be created in a joinable or a detached state. +.P +The following values may be specified in +.IR detachstate : +.TP +.B PTHREAD_CREATE_DETACHED +Threads that are created using +.I attr +will be created in a detached state. +.TP +.B PTHREAD_CREATE_JOINABLE +Threads that are created using +.I attr +will be created in a joinable state. +.P +The default setting of the detach state attribute in a newly initialized +thread attributes object is +.BR PTHREAD_CREATE_JOINABLE . +.P +The +.BR pthread_attr_getdetachstate () +returns the detach state attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR detachstate . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setdetachstate () +can fail with the following error: +.TP +.B EINVAL +An invalid value was specified in +.IR detachstate . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setdetachstate (), +.BR pthread_attr_getdetachstate () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +See +.BR pthread_create (3) +for more details on detached and joinable threads. +.P +A thread that is created in a joinable state should +eventually either be joined using +.BR pthread_join (3) +or detached using +.BR pthread_detach (3); +see +.BR pthread_create (3). +.P +It is an error to specify the thread ID of +a thread that was created in a detached state +in a later call to +.BR pthread_detach (3) +or +.BR pthread_join (3). +.SH EXAMPLES +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setguardsize.3 b/man/man3/pthread_attr_setguardsize.3 new file mode 100644 index 0000000..0056650 --- /dev/null +++ b/man/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,163 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setguardsize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ +", size_t " guardsize ); +.BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr , +.BI " size_t *restrict " guardsize ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setguardsize () +function sets the guard size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR guardsize . +.P +If +.I guardsize +is greater than 0, +then for each new thread created using +.I attr +the system allocates an additional region of at least +.I guardsize +bytes at the end of the thread's stack to act as the guard area +for the stack (but see BUGS). +.P +If +.I guardsize +is 0, then new threads created with +.I attr +will not have a guard area. +.P +The default guard size is the same as the system page size. +.P +If the stack address attribute has been set in +.I attr +(using +.BR pthread_attr_setstack (3) +or +.BR pthread_attr_setstackaddr (3)), +meaning that the caller is allocating the thread's stack, +then the guard size attribute is ignored +(i.e., no guard area is created by the system): +it is the application's responsibility to handle stack overflow +(perhaps by using +.BR mprotect (2) +to manually define a guard area at the end of the stack +that it has allocated). +.P +The +.BR pthread_attr_getguardsize () +function returns the guard size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR guardsize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B EINVAL +error if +.I attr +or +.I guardsize +is invalid. +On Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setguardsize (), +.BR pthread_attr_getguardsize () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +A guard area consists of virtual memory pages that are protected +to prevent read and write access. +If a thread overflows its stack into the guard area, +then, on most hard architectures, it receives a +.B SIGSEGV +signal, thus notifying it of the overflow. +Guard areas start on page boundaries, +and the guard size is internally rounded up to +the system page size when creating a thread. +(Nevertheless, +.BR pthread_attr_getguardsize () +returns the guard size that was set by +.BR pthread_attr_setguardsize ().) +.P +Setting a guard size of 0 may be useful to save memory +in an application that creates many threads +and knows that stack overflow can never occur. +.P +Choosing a guard size larger than the default size +may be necessary for detecting stack overflows +if a thread allocates large data structures on the stack. +.SH BUGS +As at glibc 2.8, the NPTL threading implementation includes +the guard area within the stack size allocation, +rather than allocating extra space at the end of the stack, +as POSIX.1 requires. +(This can result in an +.B EINVAL +error from +.BR pthread_create (3) +if the guard size value is too large, +leaving no space for the actual stack.) +.P +The obsolete LinuxThreads implementation did the right thing, +allocating extra space at the end of the stack for the guard area. +.\" glibc includes the guardsize within the allocated stack size, +.\" which looks pretty clearly to be in violation of POSIX. +.\" +.\" Filed bug, 22 Oct 2008: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6973 +.\" +.\" Older reports: +.\" https//bugzilla.redhat.com/show_bug.cgi?id=435337 +.\" Reportedly, LinuxThreads did the right thing, allocating +.\" extra space at the end of the stack: +.\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html +.SH EXAMPLES +See +.BR pthread_getattr_np (3). +.SH SEE ALSO +.BR mmap (2), +.BR mprotect (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setinheritsched.3 b/man/man3/pthread_attr_setinheritsched.3 new file mode 100644 index 0000000..48406e2 --- /dev/null +++ b/man/man3/pthread_attr_setinheritsched.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setinheritsched 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setinheritsched, pthread_attr_getinheritsched \- set/get +inherit-scheduler attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr , +.BI " int " inheritsched ); +.BI "int pthread_attr_getinheritsched(const pthread_attr_t *restrict " attr , +.BI " int *restrict " inheritsched ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setinheritsched () +function sets the inherit-scheduler attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR inheritsched . +The inherit-scheduler attribute determines whether a thread created using +the thread attributes object +.I attr +will inherit its scheduling attributes from the calling thread +or whether it will take them from +.IR attr . +.P +The following scheduling attributes are affected by the +inherit-scheduler attribute: +scheduling policy +.RB ( pthread_attr_setschedpolicy (3)), +scheduling priority +.RB ( pthread_attr_setschedparam (3)), +and contention scope +.RB ( pthread_attr_setscope (3)). +.P +The following values may be specified in +.IR inheritsched : +.TP +.B PTHREAD_INHERIT_SCHED +Threads that are created using +.I attr +inherit scheduling attributes from the creating thread; +the scheduling attributes in +.I attr +are ignored. +.TP +.B PTHREAD_EXPLICIT_SCHED +Threads that are created using +.I attr +take their scheduling attributes from the values specified +by the attributes object. +.\" FIXME Document the defaults for scheduler settings +.P +The default setting of the inherit-scheduler attribute in +a newly initialized thread attributes object is +.BR PTHREAD_INHERIT_SCHED . +.P +The +.BR pthread_attr_getinheritsched () +returns the inherit-scheduler attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR inheritsched . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setinheritsched () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR inheritsched . +.P +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setinheritsched (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setinheritsched (), +.BR pthread_attr_getinheritsched () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH BUGS +As at glibc 2.8, if a thread attributes object is initialized using +.BR pthread_attr_init (3), +then the scheduling policy of the attributes object is set to +.B SCHED_OTHER +and the scheduling priority is set to 0. +However, if the inherit-scheduler attribute is then set to +.BR PTHREAD_EXPLICIT_SCHED , +then a thread created using the attribute object +wrongly inherits its scheduling attributes from the creating thread. +This bug does not occur if either the scheduling policy or +scheduling priority attribute is explicitly set +in the thread attributes object before calling +.BR pthread_create (3). +.\" FIXME . Track status of the following bug: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7007 +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setschedparam.3 b/man/man3/pthread_attr_setschedparam.3 new file mode 100644 index 0000000..e3403b0 --- /dev/null +++ b/man/man3/pthread_attr_setschedparam.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setschedparam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setschedparam, pthread_attr_getschedparam \- set/get +scheduling parameter attributes in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setschedparam(pthread_attr_t *restrict " attr , +.BI " const struct sched_param *restrict " param ); +.BI "int pthread_attr_getschedparam(const pthread_attr_t *restrict " attr , +.BI " struct sched_param *restrict " param ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedparam () +function sets the scheduling parameter attributes of the +thread attributes object referred to by +.I attr +to the values specified in the buffer pointed to by +.IR param . +These attributes determine the scheduling parameters of +a thread created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getschedparam () +returns the scheduling parameter attributes of the thread attributes object +.I attr +in the buffer pointed to by +.IR param . +.P +Scheduling parameters are maintained in the following structure: +.P +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.P +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.P +In order for the parameter setting made by +.BR pthread_attr_setschedparam () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedparam () +can fail with the following error: +.TP +.B EINVAL +The priority specified in +.I param +does not make sense for the current scheduling policy of +.IR attr . +.P +POSIX.1 also documents an +.B ENOTSUP +error for +.BR pthread_attr_setschedparam (). +This value is never returned on Linux +(but portable and future-proof applications should nevertheless +handle this error return value). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setschedparam (), +.BR pthread_attr_getschedparam () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.0. +.SH NOTES +See +.BR pthread_attr_setschedpolicy (3) +for a list of the thread scheduling policies supported on Linux. +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setschedpolicy.3 b/man/man3/pthread_attr_setschedpolicy.3 new file mode 100644 index 0000000..5217fe2 --- /dev/null +++ b/man/man3/pthread_attr_setschedpolicy.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setschedpolicy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy \- set/get +scheduling policy attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setschedpolicy(pthread_attr_t *" attr ", int " policy ); +.BI "int pthread_attr_getschedpolicy(const pthread_attr_t *restrict " attr , +.BI " int *restrict " policy ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedpolicy () +function sets the scheduling policy attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR policy . +This attribute determines the scheduling policy of +a thread created using the thread attributes object +.IR attr . +.P +The supported values for +.I policy +are +.BR SCHED_FIFO , +.BR SCHED_RR , +and +.BR SCHED_OTHER , +with the semantics described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.P +The +.BR pthread_attr_getschedpolicy () +returns the scheduling policy attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR policy . +.P +In order for the policy setting made by +.BR pthread_attr_setschedpolicy () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedpolicy () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR policy . +.P +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setschedpolicy (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setschedpolicy (), +.BR pthread_attr_getschedpolicy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setscope.3 b/man/man3/pthread_attr_setscope.3 new file mode 100644 index 0000000..6fc3fc0 --- /dev/null +++ b/man/man3/pthread_attr_setscope.3 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setscope 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope ); +.BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr , +.BI " int *restrict " scope ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setscope () +function sets the contention scope attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR scope . +The contention scope attribute defines the set of threads +against which a thread competes for resources such as the CPU. +POSIX.1 specifies two possible values for +.IR scope : +.TP +.B PTHREAD_SCOPE_SYSTEM +The thread competes for resources with all other threads +in all processes on the system that are in the same scheduling +allocation domain (a group of one or more processors). +.B PTHREAD_SCOPE_SYSTEM +threads are scheduled relative to one another +according to their scheduling policy and priority. +.TP +.B PTHREAD_SCOPE_PROCESS +The thread competes for resources with all other threads +in the same process that were also created with the +.B PTHREAD_SCOPE_PROCESS +contention scope. +.B PTHREAD_SCOPE_PROCESS +threads are scheduled relative to other threads in the process +according to their scheduling policy and priority. +POSIX.1 leaves it unspecified how these threads contend +with other threads in other process on the system or +with other threads in the same process that +were created with the +.B PTHREAD_SCOPE_SYSTEM +contention scope. +.P +POSIX.1 requires that an implementation support at least one of these +contention scopes. +Linux supports +.BR PTHREAD_SCOPE_SYSTEM , +but not +.BR PTHREAD_SCOPE_PROCESS . +.P +On systems that support multiple contention scopes, then, +in order for the parameter setting made by +.BR pthread_attr_setscope () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.P +The +.BR pthread_attr_getscope () +function returns the contention scope attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR scope . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setscope () +can fail with the following errors: +.TP +.B EINVAL +An invalid value was specified in +.IR scope . +.TP +.B ENOTSUP +.I scope +specified the value +.BR PTHREAD_SCOPE_PROCESS , +which is not supported on Linux. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setscope (), +.BR pthread_attr_getscope () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.B PTHREAD_SCOPE_SYSTEM +contention scope typically indicates that a user-space thread is +bound directly to a single kernel-scheduling entity. +This is the case on Linux for the obsolete LinuxThreads implementation +and the modern NPTL implementation, +which are both 1:1 threading implementations. +.P +POSIX.1 specifies that the default contention scope is +implementation-defined. +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setsigmask_np.3 b/man/man3/pthread_attr_setsigmask_np.3 new file mode 100644 index 0000000..9b75a49 --- /dev/null +++ b/man/man3/pthread_attr_setsigmask_np.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setsigmask_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setsigmask_np, pthread_attr_getsigmask_np \- set/get +signal mask attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_attr_setsigmask_np(pthread_attr_t *" attr , +.BI " const sigset_t *" sigmask ); +.BI "int pthread_attr_getsigmask_np(const pthread_attr_t *" attr , +.BI " sigset_t *" sigmask ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setsigmask_np () +function sets the signal mask attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR *sigmask . +If +.I sigmask +is specified as NULL, then any existing signal mask attribute in +.I attr +is unset. +.P +The +.BR pthread_attr_getsigmask_np () +function returns the signal mask attribute of the thread attributes object +referred to by +.I attr +in the buffer pointed to by +.IR sigmask . +If the signal mask attribute is currently unset, +then this function returns the special value +.B PTHREAD_ATTR_NO_SIGMASK_NP +as its result. +.SH RETURN VALUE +The +.BR pthread_attr_setsigmask_np () +function returns 0 on success, or a nonzero error number on failure. +.P +the +.BR pthread_attr_getsigmask_np () +function returns either 0 or +.BR PTHREAD_ATTR_NO_SIGMASK_NP . +When 0 is returned, the signal mask attribute is returned via +.IR sigmask . +A return value of +.B PTHREAD_ATTR_NO_SIGMASK_NP +indicates that the signal mask attribute is not set in +.IR attr . +.P +On error, these functions return a positive error number. +.SH ERRORS +.TP +.B ENOMEM +.RB ( pthread_attr_setsigmask_np ()) +Could not allocate memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setsigmask_np (), +.BR pthread_attr_getsigmask_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.32. +.SH NOTES +The signal mask attribute determines the signal mask that will be assigned to +a thread created using the thread attributes object +.IR attr . +If this attribute is not set, then a thread created using +.I attr +will inherit a copy of the creating thread's signal mask. +.P +For more details on signal masks, see +.BR sigprocmask (2). +For a description of a set of macros +that can be used to manipulate and inspect signal sets, see +.BR sigsetops (3). +.P +In the absence of +.BR pthread_attr_setsigmask_np () +it is possible to create a thread with a desired signal mask as follows: +.IP \[bu] 3 +The creating thread uses +.BR pthread_sigmask (3) +to save its current signal mask and set its mask to block all signals. +.IP \[bu] +The new thread is then created using +.BR pthread_create (); +the new thread will inherit the creating thread's signal mask. +.IP \[bu] +The new thread sets its signal mask to the desired value using +.BR pthread_sigmask (3). +.IP \[bu] +The creating thread restores its signal mask to the original value. +.P +Following the above steps, +there is no possibility for the new thread to receive a signal +before it has adjusted its signal mask to the desired value. +.SH SEE ALSO +.BR sigprocmask (2), +.BR pthread_attr_init (3), +.BR pthread_sigmask (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_attr_setstack.3 b/man/man3/pthread_attr_setstack.3 new file mode 100644 index 0000000..e060f43 --- /dev/null +++ b/man/man3/pthread_attr_setstack.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstack 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstack, pthread_attr_getstack \- set/get stack +attributes in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setstack(pthread_attr_t *" attr , +.BI " void " stackaddr [. stacksize ], +.BI " size_t " stacksize ); +.BI "int pthread_attr_getstack(const pthread_attr_t *restrict " attr , +.BI " void **restrict " stackaddr , +.BI " size_t *restrict " stacksize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_attr_getstack (), +.BR pthread_attr_setstack (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setstack () +function sets the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +to the values specified in +.I stackaddr +and +.IR stacksize , +respectively. +These attributes specify the location and size of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.P +.I stackaddr +should point to the lowest addressable byte of a buffer of +.I stacksize +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.P +The +.BR pthread_attr_getstack () +function returns the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +in the buffers pointed to by +.I stackaddr +and +.IR stacksize , +respectively. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstack () +can fail with the following error: +.TP +.B EINVAL +.I stacksize +is less than +.B PTHREAD_STACK_MIN +(16384) bytes. +On some systems, this error may also occur if +.I stackaddr +or +.I stackaddr\~+\~stacksize +is not suitably aligned. +.P +POSIX.1 also documents an +.B EACCES +error if the stack area described by +.I stackaddr +and +.I stacksize +is not both readable and writable by the caller. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstack (), +.BR pthread_attr_getstack () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +These functions are provided for applications that must ensure that +a thread's stack is placed in a particular location. +For most applications, this is not necessary, +and the use of these functions should be avoided. +(Use +.BR pthread_attr_setstacksize (3) +if an application simply requires a stack size other than the default.) +.P +When an application employs +.BR pthread_attr_setstack (), +it takes over the responsibility of allocating the stack. +Any guard size value that was set using +.BR pthread_attr_setguardsize (3) +is ignored. +If deemed necessary, +it is the application's responsibility to allocate a guard area +(one or more pages protected against reading and writing) +to handle the possibility of stack overflow. +.P +The address specified in +.I stackaddr +should be suitably aligned: +for full portability, align it on a page boundary +.RI ( sysconf(_SC_PAGESIZE) ). +.BR posix_memalign (3) +may be useful for allocation. +Probably, +.I stacksize +should also be a multiple of the system page size. +.P +If +.I attr +is used to create multiple threads, then the caller must change the +stack address attribute between calls to +.BR pthread_create (3); +otherwise, the threads will attempt to use the same memory area +for their stacks, and chaos will ensue. +.SH EXAMPLES +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR mprotect (2), +.BR posix_memalign (3), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setstackaddr.3 b/man/man3/pthread_attr_setstackaddr.3 new file mode 100644 index 0000000..9744a57 --- /dev/null +++ b/man/man3/pthread_attr_setstackaddr.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstackaddr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstackaddr, pthread_attr_getstackaddr \- +set/get stack address attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.B [[deprecated]] +.BI "int pthread_attr_setstackaddr(pthread_attr_t *" attr \ +", void *" stackaddr ); +.B [[deprecated]] +.BI "int pthread_attr_getstackaddr(const pthread_attr_t *restrict " attr , +.BI " void **restrict " stackaddr ); +.fi +.SH DESCRIPTION +These functions are obsolete: +.B do not use them. +Use +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3) +instead. +.P +The +.BR pthread_attr_setstackaddr () +function sets the stack address attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stackaddr . +This attribute specifies the location of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.P +.I stackaddr +should point to a buffer of at least +.B PTHREAD_STACK_MIN +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.P +The +.BR pthread_attr_getstackaddr () +function returns the stack address attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stackaddr . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +No errors are defined +(but applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstackaddr (), +.BR pthread_attr_getstackaddr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1. +Marked obsolete in POSIX.1-2001. +Removed in POSIX.1-2008. +.SH NOTES +.I Do not use these functions! +They cannot be portably used, since they provide no way of specifying +the direction of growth or the range of the stack. +For example, on architectures with a stack that grows downward, +.I stackaddr +specifies the next address past the +.I highest +address of the allocated stack area. +However, on architectures with a stack that grows upward, +.I stackaddr +specifies the +.I lowest +address in the allocated stack area. +By contrast, the +.I stackaddr +used by +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3), +is always a pointer to the lowest address in the allocated stack area +(and the +.I stacksize +argument specifies the range of the stack). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setstacksize.3 b/man/man3/pthread_attr_setstacksize.3 new file mode 100644 index 0000000..9c98ef0 --- /dev/null +++ b/man/man3/pthread_attr_setstacksize.3 @@ -0,0 +1,114 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstacksize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack size +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \ +", size_t " stacksize ); +.BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr , +.BI " size_t *restrict " stacksize ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setstacksize () +function sets the stack size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stacksize . +.P +The stack size attribute determines the minimum size (in bytes) that +will be allocated for threads created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getstacksize () +function returns the stack size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stacksize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstacksize () +can fail with the following error: +.TP +.B EINVAL +The stack size is less than +.B PTHREAD_STACK_MIN +(16384) bytes. +.P +On some systems, +.\" e.g., MacOS +.BR pthread_attr_setstacksize () +can fail with the error +.B EINVAL +if +.I stacksize +is not a multiple of the system page size. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstacksize (), +.BR pthread_attr_getstacksize () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are provided since glibc 2.1. +.SH STANDARDS +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For details on the default stack size of new threads, see +.BR pthread_create (3). +.P +A thread's stack size is fixed at the time of thread creation. +Only the main thread can dynamically grow its stack. +.P +The +.BR pthread_attr_setstack (3) +function allows an application to set both the size and location +of a caller-allocated stack that is to be used by a thread. +.SH BUGS +As at glibc 2.8, +if the specified +.I stacksize +is not a multiple of +.B STACK_ALIGN +(16 bytes on most architectures), it may be rounded +.IR downward , +in violation of POSIX.1, which says that the allocated stack will +be at least +.I stacksize +bytes. +.SH EXAMPLES +See +.BR pthread_create (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstack (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cancel.3 b/man/man3/pthread_cancel.3 new file mode 100644 index 0000000..99232b4 --- /dev/null +++ b/man/man3/pthread_cancel.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cancel \- send a cancelation request to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_cancel(pthread_t " thread ); +.fi +.SH DESCRIPTION +The +.BR pthread_cancel () +function sends a cancelation request to the thread +.IR thread . +Whether and when the target thread +reacts to the cancelation request depends on +two attributes that are under the control of that thread: +its cancelability +.I state +and +.IR type . +.P +A thread's cancelability state, determined by +.BR pthread_setcancelstate (3), +can be +.I enabled +(the default for new threads) or +.IR disabled . +If a thread has disabled cancelation, +then a cancelation request remains queued until the thread +enables cancelation. +If a thread has enabled cancelation, +then its cancelability type determines when cancelation occurs. +.P +A thread's cancelation type, determined by +.BR pthread_setcanceltype (3), +may be either +.I asynchronous +or +.I deferred +(the default for new threads). +Asynchronous cancelability +means that the thread can be canceled at any time +(usually immediately, but the system does not guarantee this). +Deferred cancelability means that cancelation will be delayed until +the thread next calls a function that is a +.IR "cancelation point" . +A list of functions that are or may be cancelation points is provided in +.BR pthreads (7). +.P +When a cancelation requested is acted on, the following steps occur for +.I thread +(in this order): +.IP (1) 5 +Cancelation clean-up handlers are popped +(in the reverse of the order in which they were pushed) and called. +(See +.BR pthread_cleanup_push (3).) +.IP (2) +Thread-specific data destructors are called, +in an unspecified order. +(See +.BR pthread_key_create (3).) +.IP (3) +The thread is terminated. +(See +.BR pthread_exit (3).) +.P +The above steps happen asynchronously with respect to the +.BR pthread_cancel () +call; +the return status of +.BR pthread_cancel () +merely informs the caller whether the cancelation request +was successfully queued. +.P +After a canceled thread has terminated, +a join with that thread using +.BR pthread_join (3) +obtains +.B PTHREAD_CANCELED +as the thread's exit status. +(Joining with a thread is the only way to know that cancelation +has completed.) +.SH RETURN VALUE +On success, +.BR pthread_cancel () +returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_cancel () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, cancelation is implemented using signals. +Under the NPTL threading implementation, +the first real-time signal (i.e., signal 32) is used for this purpose. +On LinuxThreads, the second real-time signal is used, +if real-time signals are available, otherwise +.B SIGUSR2 +is used. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH EXAMPLES +The program below creates a thread and then cancels it. +The main thread joins with the canceled thread to check +that its exit status was +.BR PTHREAD_CANCELED . +The following shell session shows what happens when we run the program: +.P +.in +4n +.EX +$ ./a.out +thread_func(): started; cancelation disabled +main(): sending cancelation request +thread_func(): about to enable cancelation +main(): thread was canceled +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_cancel.c) +.EX +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +thread_func(void *ignored_argument) +{ + int s; +\& + /* Disable cancelation for a while, so that we don\[aq]t + immediately react to a cancelation request. */ +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + printf("%s(): started; cancelation disabled\en", __func__); + sleep(5); + printf("%s(): about to enable cancelation\en", __func__); +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + /* sleep() is a cancelation point. */ +\& + sleep(1000); /* Should get canceled while we sleep */ +\& + /* Should never get here. */ +\& + printf("%s(): not canceled!\en", __func__); + return NULL; +} +\& +int +main(void) +{ + pthread_t thr; + void *res; + int s; +\& + /* Start a thread and then send it a cancelation request. */ +\& + s = pthread_create(&thr, NULL, &thread_func, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + sleep(2); /* Give thread a chance to get started */ +\& + printf("%s(): sending cancelation request\en", __func__); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); +\& + /* Join with thread to see what its exit status was. */ +\& + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + if (res == PTHREAD_CANCELED) + printf("%s(): thread was canceled\en", __func__); + else + printf("%s(): thread wasn\[aq]t canceled (shouldn\[aq]t happen!)\en", + __func__); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_cleanup_push (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthread_key_create (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cleanup_pop.3 b/man/man3/pthread_cleanup_pop.3 new file mode 100644 index 0000000..fb0e68b --- /dev/null +++ b/man/man3/pthread_cleanup_pop.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push.3 diff --git a/man/man3/pthread_cleanup_pop_restore_np.3 b/man/man3/pthread_cleanup_pop_restore_np.3 new file mode 100644 index 0000000..c47e20a --- /dev/null +++ b/man/man3/pthread_cleanup_pop_restore_np.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push_defer_np.3 diff --git a/man/man3/pthread_cleanup_push.3 b/man/man3/pthread_cleanup_push.3 new file mode 100644 index 0000000..729e086 --- /dev/null +++ b/man/man3/pthread_cleanup_push.3 @@ -0,0 +1,319 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cleanup_push 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cleanup_push, pthread_cleanup_pop \- push and pop +thread cancelation clean-up handlers +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "void pthread_cleanup_push(void (*" routine ")(void *), void *" arg ); +.BI "void pthread_cleanup_pop(int " execute ); +.fi +.SH DESCRIPTION +These functions manipulate the calling thread's stack of +thread-cancelation clean-up handlers. +A clean-up handler is a function that is automatically executed +when a thread is canceled (or in various other circumstances +described below); +it might, for example, unlock a mutex so that +it becomes available to other threads in the process. +.P +The +.BR pthread_cleanup_push () +function pushes +.I routine +onto the top of the stack of clean-up handlers. +When +.I routine +is later invoked, it will be given +.I arg +as its argument. +.P +The +.BR pthread_cleanup_pop () +function removes the routine at the top of the stack of clean-up handlers, +and optionally executes it if +.I execute +is nonzero. +.P +A cancelation clean-up handler is popped from the stack +and executed in the following circumstances: +.IP \[bu] 3 +When a thread is canceled, +all of the stacked clean-up handlers are popped and executed in +the reverse of the order in which they were pushed onto the stack. +.IP \[bu] +When a thread terminates by calling +.BR pthread_exit (3), +all clean-up handlers are executed as described in the preceding point. +(Clean-up handlers are +.I not +called if the thread terminates by +performing a +.I return +from the thread start function.) +.IP \[bu] +When a thread calls +.BR pthread_cleanup_pop () +with a nonzero +.I execute +argument, the top-most clean-up handler is popped and executed. +.P +POSIX.1 permits +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +to be implemented as macros that expand to text +containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively. +For this reason, the caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +(In other words, a clean-up handler is established only +during the execution of a specified section of code.) +.P +Calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +produces undefined results if any call has been made to +.BR pthread_cleanup_push () +or +.BR pthread_cleanup_pop () +without the matching call of the pair since the jump buffer +was filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)). +Likewise, calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +from inside a clean-up handler produces undefined results +unless the jump buffer was also filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)) +inside the handler. +.SH RETURN VALUE +These functions do not return a value. +.SH ERRORS +There are no errors. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_cleanup_push (), +.BR pthread_cleanup_pop () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On glibc, the +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +functions +.I are +implemented as macros that expand to text +containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively. +This means that variables declared within the scope of +paired calls to these functions will be visible within only that scope. +.P +POSIX.1 +.\" The text was actually added in the 2004 TC2 +says that the effect of using +.IR return , +.IR break , +.IR continue , +or +.I goto +to prematurely leave a block bracketed +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +is undefined. +Portable applications should avoid doing this. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.0. +.SH EXAMPLES +The program below provides a simple example of the use of the functions +described in this page. +The program creates a thread that executes a loop bracketed by +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop (). +This loop increments a global variable, +.IR cnt , +once each second. +Depending on what command-line arguments are supplied, +the main thread sends the other thread a cancelation request, +or sets a global variable that causes the other thread +to exit its loop and terminate normally (by doing a +.IR return ). +.P +In the following shell session, +the main thread sends a cancelation request to the other thread: +.P +.in +4n +.EX +$ \fB./a.out\fP +New thread started +cnt = 0 +cnt = 1 +Canceling thread +Called clean\-up handler +Thread was canceled; cnt = 0 +.EE +.in +.P +From the above, we see that the thread was canceled, +and that the cancelation clean-up handler was called +and it reset the value of the global variable +.I cnt +to 0. +.P +In the next run, the main program sets a +global variable that causes other thread to terminate normally: +.P +.in +4n +.EX +$ \fB./a.out x\fP +New thread started +cnt = 0 +cnt = 1 +Thread terminated normally; cnt = 2 +.EE +.in +.P +From the above, we see that the clean-up handler was not executed (because +.I cleanup_pop_arg +was 0), and therefore the value of +.I cnt +was not reset. +.P +In the next run, the main program sets a global variable that +causes the other thread to terminate normally, +and supplies a nonzero value for +.IR cleanup_pop_arg : +.P +.in +4n +.EX +$ \fB./a.out x 1\fP +New thread started +cnt = 0 +cnt = 1 +Called clean\-up handler +Thread terminated normally; cnt = 0 +.EE +.in +.P +In the above, we see that although the thread was not canceled, +the clean-up handler was executed, because the argument given to +.BR pthread_cleanup_pop () +was nonzero. +.SS Program source +\& +.\" SRC BEGIN (pthread_cleanup_push.c) +.EX +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static int done = 0; +static int cleanup_pop_arg = 0; +static int cnt = 0; +\& +static void +cleanup_handler(void *arg) +{ + printf("Called clean\-up handler\en"); + cnt = 0; +} +\& +static void * +thread_start(void *arg) +{ + time_t curr; +\& + printf("New thread started\en"); +\& + pthread_cleanup_push(cleanup_handler, NULL); +\& + curr = time(NULL); +\& + while (!done) { + pthread_testcancel(); /* A cancelation point */ + if (curr < time(NULL)) { + curr = time(NULL); + printf("cnt = %d\en", cnt); /* A cancelation point */ + cnt++; + } + } +\& + pthread_cleanup_pop(cleanup_pop_arg); + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thr; + int s; + void *res; +\& + s = pthread_create(&thr, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + sleep(2); /* Allow new thread to run a while */ +\& + if (argc > 1) { + if (argc > 2) + cleanup_pop_arg = atoi(argv[2]); + done = 1; +\& + } else { + printf("Canceling thread\en"); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); + } +\& + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + if (res == PTHREAD_CANCELED) + printf("Thread was canceled; cnt = %d\en", cnt); + else + printf("Thread terminated normally; cnt = %d\en", cnt); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push_defer_np (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cleanup_push_defer_np.3 b/man/man3/pthread_cleanup_push_defer_np.3 new file mode 100644 index 0000000..d1d2792 --- /dev/null +++ b/man/man3/pthread_cleanup_push_defer_np.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cleanup_push_defer_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop +thread cancelation clean-up handlers while saving cancelability type +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg ); +.BI "void pthread_cleanup_pop_restore_np(int " execute ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_cleanup_push_defer_np (), +.BR pthread_cleanup_pop_defer_np (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions are the same as +.BR pthread_cleanup_push (3) +and +.BR pthread_cleanup_pop (3), +except for the differences noted on this page. +.P +Like +.BR pthread_cleanup_push (3), +.BR pthread_cleanup_push_defer_np () +pushes +.I routine +onto the thread's stack of cancelation clean-up handlers. +In addition, it also saves the thread's current cancelability type, +and sets the cancelability type to "deferred" (see +.BR pthread_setcanceltype (3)); +this ensures that cancelation clean-up will occur +even if the thread's cancelability type was "asynchronous" +before the call. +.P +Like +.BR pthread_cleanup_pop (3), +.BR pthread_cleanup_pop_restore_np () +pops the top-most clean-up handler from the thread's +stack of cancelation clean-up handlers. +In addition, it restores the thread's cancelability +type to its value at the time of the matching +.BR pthread_cleanup_push_defer_np (). +.P +The caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +Other restrictions apply, as described in +.BR pthread_cleanup_push (3). +.P +This sequence of calls: +.P +.in +4n +.EX +pthread_cleanup_push_defer_np(routine, arg); +pthread_cleanup_pop_restore_np(execute); +.EE +.in +.P +is equivalent to (but shorter and more efficient than): +.P +.\" As far as I can see, LinuxThreads reverses the two substeps +.\" in the push and pop below. +.in +4n +.EX +int oldtype; +\& +pthread_cleanup_push(routine, arg); +pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); +\&... +pthread_setcanceltype(oldtype, NULL); +pthread_cleanup_pop(execute); +.EE +.in +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.0 +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cond_broadcast.3 b/man/man3/pthread_cond_broadcast.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_broadcast.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_destroy.3 b/man/man3/pthread_cond_destroy.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_init.3 b/man/man3/pthread_cond_init.3 new file mode 100644 index 0000000..0b7468d --- /dev/null +++ b/man/man3/pthread_cond_init.3 @@ -0,0 +1,268 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cond_init 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_cond_init, +pthread_cond_signal, +pthread_cond_broadcast, +pthread_cond_wait, +pthread_cond_timedwait, +pthread_cond_destroy +\- +operations on conditions +. +. +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;" +.P +.BI "int pthread_cond_init(pthread_cond_t *" cond , +.BI " pthread_condattr_t *" cond_attr ); +.BI "int pthread_cond_signal(pthread_cond_t *" cond ); +.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ); +.BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ); +.BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex , +.BI " const struct timespec *" abstime ); +.BI "int pthread_cond_destroy(pthread_cond_t *" cond ); +.fi +. +. +.SH DESCRIPTION +A condition (short for ``condition variable'') +is a synchronization device that allows threads +to suspend execution and relinquish the processors +until some predicate on shared data is satisfied. +The basic operations on conditions are: +signal the condition (when the predicate becomes true), +and wait for the condition, +suspending the thread execution until another thread signals the condition. +.P +A condition variable must always be associated with a mutex, +to avoid the race condition where +a thread prepares to wait on a condition variable +and another thread signals the condition +just before the first thread actually waits on it. +.P +\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP, +using the condition attributes specified in \fIcond_attr\fP, +or default attributes if \fIcond_attr\fP is \fBNULL\fP. +The LinuxThreads implementation supports no attributes for conditions, +hence the \fIcond_attr\fP parameter is actually ignored. +.P +Variables of type \fBpthread_cond_t\fP can also be initialized statically, +using the constant \fBPTHREAD_COND_INITIALIZER\fP. +.P +\fBpthread_cond_signal\fP restarts one of the threads that +are waiting on the condition variable \fIcond\fP. +If no threads are waiting on \fIcond\fP, +nothing happens. +If several threads are waiting on \fIcond\fP, +exactly one is restarted, +but it is not specified which. +.P +\fBpthread_cond_broadcast\fP restarts all the threads that +are waiting on the condition variable \fIcond\fP. +Nothing happens if no threads are waiting on \fIcond\fP. +.P +\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP +(as per \fBpthread_unlock_mutex\fP) +and waits for the condition variable \fIcond\fP to be signaled. +The thread execution is suspended and does not consume any CPU time +until the condition variable is signaled. +The \fImutex\fP must be locked by the calling thread +on entrance to \fBpthread_cond_wait\fP. +Before returning to the calling thread, +\fBpthread_cond_wait\fP re-acquires \fImutex\fP +(as per \fBpthread_lock_mutex\fP). +.P +Unlocking the mutex and suspending on the condition variable is done atomically. +Thus, +if all threads always acquire the mutex before signaling the condition, +this guarantees that the condition cannot be signaled (and thus ignored) +between the time a thread locks the mutex +and the time it waits on the condition variable. +.P +\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP +and waits on \fIcond\fP, +as \fBpthread_cond_wait\fP does, +but it also bounds the duration of the wait. +If \fIcond\fP has not been signaled +within the amount of time specified by \fIabstime\fP, +the mutex \fImutex\fP is re-acquired +and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP. +The \fIabstime\fP parameter specifies an absolute time, +with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2): +an \fIabstime\fP of 0 +corresponds to 00:00:00 GMT, January 1, 1970. +.P +\fBpthread_cond_destroy\fP destroys a condition variable, +freeing the resources it might hold. +No threads must be waiting on the condition variable +on entrance to \fBpthread_cond_destroy\fP. +In the LinuxThreads implementation, +no resources are associated with condition variables, +thus \fBpthread_cond_destroy\fP actually does nothing +except checking that the condition has no waiting threads. +. +. +.SH CANCELLATION +\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP +are cancelation points. +If a thread is cancelled while suspended in one of these functions, +the thread immediately resumes execution, +then locks again the \fImutex\fP +argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP, +and finally executes the cancelation. +Consequently, +cleanup handlers are assured that \fImutex\fP is locked +when they are called. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The condition functions are not async-signal safe, +and should not be called from a signal handler. +In particular, +calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +All condition variable functions return 0 on success +and a non-zero error code on error. +. +. +.SH ERRORS +\fBpthread_cond_init\fP, +\fBpthread_cond_signal\fP, +\fBpthread_cond_broadcast\fP, +and \fBpthread_cond_wait\fP +never return an error code. +.P +The \fBpthread_cond_timedwait\fP function returns +the following error codes on error: +.RS +.TP +\fBETIMEDOUT\fP +The condition variable was not signaled +until the timeout specified by \fIabstime\fP. +.TP +\fBEINTR\fP +\fBpthread_cond_timedwait\fP was interrupted by a signal. +.RE +.P +The \fBpthread_cond_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +Some threads are currently waiting on \fIcond\fP. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_condattr_init\fP(3), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3), +\fBgettimeofday\fP(2), +\fBnanosleep\fP(2). +. +. +.SH EXAMPLE +Consider two shared variables \fIx\fP and \fIy\fP, +protected by the mutex \fImut\fP, +and a condition variable \fIcond\fP +that is to be signaled +whenever \fIx\fP becomes greater than \fIy\fP. +.P +.RS +.ft 3 +.nf +.sp +int x,y; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +.ft +.P +.RE +.fi +.P +Waiting until \fIx\fP is greater than \fIy\fP is performed as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +while (x <= y) { + pthread_cond_wait(&cond, &mut); +} +/* operate on x and y */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +Modifications on \fIx\fP and \fIy\fP +that may cause \fIx\fP to become greater than \fIy\fP +should signal the condition if needed: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* modify x and y */ +if (x > y) pthread_cond_broadcast(&cond); +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +If it can be proved that at most one waiting thread needs to be waken up +(for instance, +if there are only two threads communicating through \fIx\fP and \fIy\fP), +\fBpthread_cond_signal\fP can be used as +a slightly more efficient alternative to \fBpthread_cond_broadcast\fP. +In doubt, +use \fBpthread_cond_broadcast\fP. +.P +To wait for \fIx\fP to become greater than \fIy\fP +with a timeout of 5 seconds, +do: +.P +.RS +.ft 3 +.nf +.sp +struct timeval now; +struct timespec timeout; +int retcode; +\& +pthread_mutex_lock(&mut); +gettimeofday(&now); +timeout.tv_sec = now.tv_sec + 5; +timeout.tv_nsec = now.tv_usec * 1000; +retcode = 0; +while (x <= y && retcode != ETIMEDOUT) { + retcode = pthread_cond_timedwait(&cond, &mut, &timeout); +} +if (retcode == ETIMEDOUT) { + /* timeout occurred */ +} else { + /* operate on x and y */ +} +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_cond_signal.3 b/man/man3/pthread_cond_signal.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_signal.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_timedwait.3 b/man/man3/pthread_cond_timedwait.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_timedwait.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_wait.3 b/man/man3/pthread_cond_wait.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_wait.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_condattr_destroy.3 b/man/man3/pthread_condattr_destroy.3 new file mode 100644 index 0000000..ae5c63c --- /dev/null +++ b/man/man3/pthread_condattr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_condattr_init.3 diff --git a/man/man3/pthread_condattr_init.3 b/man/man3/pthread_condattr_init.3 new file mode 100644 index 0000000..cf7fd33 --- /dev/null +++ b/man/man3/pthread_condattr_init.3 @@ -0,0 +1,48 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_condattr_init 3 2024-05-02 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_condattr_init, +pthread_condattr_destroy +\- +condition creation attributes +. +. +.SH SYNOPSIS +.B #include <pthread.h> +.P +.BI "int pthread_condattr_init(pthread_condattr_t *" attr ");" +.BI "int pthread_condattr_destroy(pthread_condattr_t *" attr ");" +. +. +.SH DESCRIPTION +Condition attributes can be specified at condition creation time, +by passing a condition attribute object +as second argument to \fBpthread_cond_init\fP(3). +Passing \fBNULL\fP is equivalent to +passing a condition attribute object +with all attributes set to their default values. +.P +The LinuxThreads implementation supports no attributes for conditions. +The functions on condition attributes are +included only for compliance with the POSIX standard. +.P +\fBpthread_condattr_init\fP +initializes the condition attribute object \fIattr\fP +and fills it with default values for the attributes. +\fBpthread_condattr_destroy\fP destroys a condition attribute object, +which must not be reused until it is reinitialized. +Both functions do nothing in the LinuxThreads implementation. +. +. +.SH "RETURN VALUE" +\fBpthread_condattr_init\fP and \fBpthread_condattr_destroy\fP always return 0. +. +. +.SH "SEE ALSO" +\fBpthread_cond_init\fP(3). diff --git a/man/man3/pthread_create.3 b/man/man3/pthread_create.3 new file mode 100644 index 0000000..a7f33de --- /dev/null +++ b/man/man3/pthread_create.3 @@ -0,0 +1,395 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_create 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_create \- create a new thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_create(pthread_t *restrict " thread , +.BI " const pthread_attr_t *restrict " attr , +.BI " void *(*" start_routine ")(void *)," +.BI " void *restrict " arg ); +.fi +.SH DESCRIPTION +The +.BR pthread_create () +function starts a new thread in the calling process. +The new thread starts execution by invoking +.IR start_routine (); +.I arg +is passed as the sole argument of +.IR start_routine (). +.P +The new thread terminates in one of the following ways: +.IP \[bu] 3 +It calls +.BR pthread_exit (3), +specifying an exit status value that is available to another thread +in the same process that calls +.BR pthread_join (3). +.IP \[bu] +It returns from +.IR start_routine (). +This is equivalent to calling +.BR pthread_exit (3) +with the value supplied in the +.I return +statement. +.IP \[bu] +It is canceled (see +.BR pthread_cancel (3)). +.IP \[bu] +Any of the threads in the process calls +.BR exit (3), +or the main thread performs a return from +.IR main (). +This causes the termination of all threads in the process. +.P +The +.I attr +argument points to a +.I pthread_attr_t +structure whose contents are used at thread creation time to +determine attributes for the new thread; +this structure is initialized using +.BR pthread_attr_init (3) +and related functions. +If +.I attr +is NULL, +then the thread is created with default attributes. +.P +Before returning, a successful call to +.BR pthread_create () +stores the ID of the new thread in the buffer pointed to by +.IR thread ; +this identifier is used to refer to the thread +in subsequent calls to other pthreads functions. +.P +The new thread inherits a copy of the creating thread's signal mask +.RB ( pthread_sigmask (3)). +The set of pending signals for the new thread is empty +.RB ( sigpending (2)). +The new thread does not inherit the creating thread's +alternate signal stack +.RB ( sigaltstack (2)). +.P +The new thread inherits the calling thread's floating-point environment +.RB ( fenv (3)). +.P +The initial value of the new thread's CPU-time clock is 0 +(see +.BR pthread_getcpuclockid (3)). +.\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2) +.SS Linux-specific details +The new thread inherits copies of the calling thread's capability sets +(see +.BR capabilities (7)) +and CPU affinity mask (see +.BR sched_setaffinity (2)). +.SH RETURN VALUE +On success, +.BR pthread_create () +returns 0; +on error, it returns an error number, and the contents of +.I *thread +are undefined. +.SH ERRORS +.TP +.B EAGAIN +Insufficient resources to create another thread. +.TP +.B EAGAIN +.\" NOTE! The following should match the description in fork(2) +A system-imposed limit on the number of threads was encountered. +There are a number of limits that may trigger this error: the +.B RLIMIT_NPROC +soft resource limit (set via +.BR setrlimit (2)), +which limits the number of processes and threads for a real user ID, +was reached; +the kernel's system-wide limit on the number of processes and threads, +.IR /proc/sys/kernel/threads\-max , +was reached (see +.BR proc (5)); +or the maximum number of PIDs, +.IR /proc/sys/kernel/pid_max , +was reached (see +.BR proc (5)). +.TP +.B EINVAL +Invalid settings in +.IR attr . +.TP +.\" FIXME . Test the following +.B EPERM +No permission to set the scheduling policy and parameters specified in +.IR attr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_create () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +See +.BR pthread_self (3) +for further information on the thread ID returned in +.I *thread +by +.BR pthread_create (). +Unless real-time scheduling policies are being employed, +after a call to +.BR pthread_create (), +it is indeterminate which thread\[em]the caller or the new thread\[em]will +next execute. +.P +A thread may either be +.I joinable +or +.IR detached . +If a thread is joinable, then another thread can call +.BR pthread_join (3) +to wait for the thread to terminate and fetch its exit status. +Only when a terminated joinable thread has been joined are +the last of its resources released back to the system. +When a detached thread terminates, +its resources are automatically released back to the system: +it is not possible to join with the thread in order to obtain +its exit status. +Making a thread detached is useful for some types of daemon threads +whose exit status the application does not need to care about. +By default, a new thread is created in a joinable state, unless +.I attr +was set to create the thread in a detached state (using +.BR pthread_attr_setdetachstate (3)). +.P +Under the NPTL threading implementation, if the +.B RLIMIT_STACK +soft resource limit +.I at the time the program started +has any value other than "unlimited", +then it determines the default stack size of new threads. +Using +.BR pthread_attr_setstacksize (3), +the stack size attribute can be explicitly set in the +.I attr +argument used to create a thread, +in order to obtain a stack size other than the default. +If the +.B RLIMIT_STACK +resource limit is set to "unlimited", +a per-architecture value is used for the stack size: +2 MB on most architectures; 4 MB on POWER and Sparc-64. +.SH BUGS +In the obsolete LinuxThreads implementation, +each of the threads in a process has a different process ID. +This is in violation of the POSIX threads specification, +and is the source of many other nonconformances to the standard; see +.BR pthreads (7). +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_create (), +as well as a number of other functions in the pthreads API. +.P +In the following run, +on a system providing the NPTL threading implementation, +the stack size defaults to the value given by the +"stack size" resource limit: +.P +.in +4n +.EX +.RB "$" " ulimit \-s" +8192 # The stack size limit is 8 MB (0x800000 bytes) +.RB "$" " ./a.out hola salut servus" +Thread 1: top of stack near 0xb7dd03b8; argv_string=hola +Thread 2: top of stack near 0xb75cf3b8; argv_string=salut +Thread 3: top of stack near 0xb6dce3b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.P +In the next run, the program explicitly sets a stack size of 1\ MB (using +.BR pthread_attr_setstacksize (3)) +for the created threads: +.P +.in +4n +.EX +.RB "$" " ./a.out \-s 0x100000 hola salut servus" +Thread 1: top of stack near 0xb7d723b8; argv_string=hola +Thread 2: top of stack near 0xb7c713b8; argv_string=salut +Thread 3: top of stack near 0xb7b703b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_create.c) +.EX +#include <ctype.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/types.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +struct thread_info { /* Used as argument to thread_start() */ + pthread_t thread_id; /* ID returned by pthread_create() */ + int thread_num; /* Application\-defined thread # */ + char *argv_string; /* From command\-line argument */ +}; +\& +/* Thread start function: display address near top of our stack, + and return upper\-cased copy of argv_string. */ +\& +static void * +thread_start(void *arg) +{ + struct thread_info *tinfo = arg; + char *uargv; +\& + printf("Thread %d: top of stack near %p; argv_string=%s\en", + tinfo\->thread_num, (void *) &tinfo, tinfo\->argv_string); +\& + uargv = strdup(tinfo\->argv_string); + if (uargv == NULL) + handle_error("strdup"); +\& + for (char *p = uargv; *p != \[aq]\e0\[aq]; p++) + *p = toupper(*p); +\& + return uargv; +} +\& +int +main(int argc, char *argv[]) +{ + int s, opt; + void *res; + size_t num_threads; + ssize_t stack_size; + pthread_attr_t attr; + struct thread_info *tinfo; +\& + /* The "\-s" option specifies a stack size for our threads. */ +\& + stack_size = \-1; + while ((opt = getopt(argc, argv, "s:")) != \-1) { + switch (opt) { + case \[aq]s\[aq]: + stack_size = strtoul(optarg, NULL, 0); + break; +\& + default: + fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en", + argv[0]); + exit(EXIT_FAILURE); + } + } +\& + num_threads = argc \- optind; +\& + /* Initialize thread creation attributes. */ +\& + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); +\& + if (stack_size > 0) { + s = pthread_attr_setstacksize(&attr, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } +\& + /* Allocate memory for pthread_create() arguments. */ +\& + tinfo = calloc(num_threads, sizeof(*tinfo)); + if (tinfo == NULL) + handle_error("calloc"); +\& + /* Create one thread for each command\-line argument. */ +\& + for (size_t tnum = 0; tnum < num_threads; tnum++) { + tinfo[tnum].thread_num = tnum + 1; + tinfo[tnum].argv_string = argv[optind + tnum]; +\& + /* The pthread_create() call stores the thread ID into + corresponding element of tinfo[]. */ +\& + s = pthread_create(&tinfo[tnum].thread_id, &attr, + &thread_start, &tinfo[tnum]); + if (s != 0) + handle_error_en(s, "pthread_create"); + } +\& + /* Destroy the thread attributes object, since it is no + longer needed. */ +\& + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); +\& + /* Now join with each thread, and display its returned value. */ +\& + for (size_t tnum = 0; tnum < num_threads; tnum++) { + s = pthread_join(tinfo[tnum].thread_id, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + printf("Joined with thread %d; returned value was %s\en", + tinfo[tnum].thread_num, (char *) res); + free(res); /* Free memory allocated by thread */ + } +\& + free(tinfo); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_cancel (3), +.BR pthread_detach (3), +.BR pthread_equal (3), +.BR pthread_exit (3), +.BR pthread_getattr_np (3), +.BR pthread_join (3), +.BR pthread_self (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_detach.3 b/man/man3/pthread_detach.3 new file mode 100644 index 0000000..b3c924d --- /dev/null +++ b/man/man3/pthread_detach.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_detach 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_detach \- detach a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_detach(pthread_t " thread ); +.fi +.SH DESCRIPTION +The +.BR pthread_detach () +function marks the thread identified by +.I thread +as detached. +When a detached thread terminates, +its resources are automatically released back to the system without +the need for another thread to join with the terminated thread. +.P +Attempting to detach an already detached thread results +in unspecified behavior. +.SH RETURN VALUE +On success, +.BR pthread_detach () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_detach () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Once a thread has been detached, it can't be joined with +.BR pthread_join (3) +or be made joinable again. +.P +A new thread can be created in a detached state using +.BR pthread_attr_setdetachstate (3) +to set the detached attribute of the +.I attr +argument of +.BR pthread_create (3). +.P +The detached attribute merely determines the behavior of the system +when the thread terminates; +it does not prevent the thread from being terminated +if the process terminates using +.BR exit (3) +(or equivalently, if the main thread returns). +.P +Either +.BR pthread_join (3) +or +.BR pthread_detach () +should be called for each thread that an application creates, +so that system resources for the thread can be released. +(But note that the resources of any threads for which one of these +actions has not been done will be freed when the process terminates.) +.SH EXAMPLES +The following statement detaches the calling thread: +.P +.in +4n +.EX +pthread_detach(pthread_self()); +.EE +.in +.SH SEE ALSO +.BR pthread_attr_setdetachstate (3), +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_equal.3 b/man/man3/pthread_equal.3 new file mode 100644 index 0000000..f8a861b --- /dev/null +++ b/man/man3/pthread_equal.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_equal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_equal \- compare thread IDs +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_equal(pthread_t " t1 ", pthread_t " t2 ); +.fi +.SH DESCRIPTION +The +.BR pthread_equal () +function compares two thread identifiers. +.SH RETURN VALUE +If the two thread IDs are equal, +.BR pthread_equal () +returns a nonzero value; otherwise, it returns 0. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_equal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.BR pthread_equal () +function is necessary because thread IDs should be considered opaque: +there is no portable way for applications to directly compare two +.I pthread_t +values. +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthreads (7) diff --git a/man/man3/pthread_exit.3 b/man/man3/pthread_exit.3 new file mode 100644 index 0000000..479e40a --- /dev/null +++ b/man/man3/pthread_exit.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_exit \- terminate calling thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "[[noreturn]] void pthread_exit(void *" retval ); +.fi +.SH DESCRIPTION +The +.BR pthread_exit () +function terminates the calling thread and returns a value via +.I retval +that (if the thread is joinable) +is available to another thread in the same process that calls +.BR pthread_join (3). +.P +Any clean-up handlers established by +.BR pthread_cleanup_push (3) +that have not yet been popped, +are popped (in the reverse of the order in which they were pushed) +and executed. +If the thread has any thread-specific data, then, +after the clean-up handlers have been executed, +the corresponding destructor functions are called, +in an unspecified order. +.P +When a thread terminates, +process-shared resources (e.g., mutexes, condition variables, +semaphores, and file descriptors) are not released, +and functions registered using +.BR atexit (3) +are not called. +.P +After the last thread in a process terminates, +the process terminates as by calling +.BR exit (3) +with an exit status of zero; +thus, process-shared resources +are released and functions registered using +.BR atexit (3) +are called. +.SH RETURN VALUE +This function does not return to the caller. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_exit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Performing a return from the start function of any thread other +than the main thread results in an implicit call to +.BR pthread_exit (), +using the function's return value as the thread's exit status. +.P +To allow other threads to continue execution, +the main thread should terminate by calling +.BR pthread_exit () +rather than +.BR exit (3). +.P +The value pointed to by +.I retval +should not be located on the calling thread's stack, +since the contents of that stack are undefined after the thread terminates. +.SH BUGS +Currently, +.\" Linux 2.6.27 +there are limitations in the kernel implementation logic for +.BR wait (2)ing +on a stopped thread group with a dead thread group leader. +This can manifest in problems such as a locked terminal if a stop signal is +sent to a foreground process whose thread group leader has already called +.BR pthread_exit (). +.\" FIXME . review a later kernel to see if this gets fixed +.\" http://thread.gmane.org/gmane.linux.kernel/611611 +.\" http://marc.info/?l=linux-kernel&m=122525468300823&w=2 +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getaffinity_np.3 b/man/man3/pthread_getaffinity_np.3 new file mode 100644 index 0000000..c4cd6af --- /dev/null +++ b/man/man3/pthread_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setaffinity_np.3 diff --git a/man/man3/pthread_getattr_default_np.3 b/man/man3/pthread_getattr_default_np.3 new file mode 100644 index 0000000..c185c96 --- /dev/null +++ b/man/man3/pthread_getattr_default_np.3 @@ -0,0 +1,192 @@ +'\" t +.\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getattr_default_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getattr_default_np, pthread_setattr_default_np, \- +get or set default thread-creation attributes +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_getattr_default_np(pthread_attr_t *" attr ); +.BI "int pthread_setattr_default_np(const pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_setattr_default_np () +function sets the default attributes used for creation of a new +thread\[em]that is, the attributes that are used when +.BR pthread_create (3) +is called with a second argument that is NULL. +The default attributes are set using the attributes supplied in +.IR *attr , +a previously initialized thread attributes object. +Note the following details about the supplied attributes object: +.IP \[bu] 3 +The attribute settings in the object must be valid. +.IP \[bu] +The +.I stack address +attribute must not be set in the object. +.IP \[bu] +Setting the +.I stack size +attribute to zero means leave the default stack size unchanged. +.P +The +.BR pthread_getattr_default_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains the default attributes used for thread creation. +.SH ERRORS +.TP +.B EINVAL +.RB ( pthread_setattr_default_np ()) +One of the attribute settings in +.I attr +is invalid, or the stack address attribute is set in +.IR attr . +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +.RB ( pthread_setattr_default_np ()) +Insufficient memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getattr_default_np (), +.BR pthread_setattr_default_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in their names. +.SH HISTORY +glibc 2.18. +.SH EXAMPLES +The program below uses +.BR pthread_getattr_default_np () +to fetch the default thread-creation attributes and then displays +various settings from the returned thread attributes object. +When running the program, we see the following output: +.P +.in +4n +.EX +$ \fB./a.out\fP +Stack size: 8388608 +Guard size: 4096 +Scheduling policy: SCHED_OTHER +Scheduling priority: 0 +Detach state: JOINABLE +Inherit scheduler: INHERIT +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getattr_default_np.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +\& +static void +display_pthread_attr(pthread_attr_t *attr) +{ + int s; + size_t stacksize; + size_t guardsize; + int policy; + struct sched_param schedparam; + int detachstate; + int inheritsched; +\& + s = pthread_attr_getstacksize(attr, &stacksize); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstacksize"); + printf("Stack size: %zu\en", stacksize); +\& + s = pthread_attr_getguardsize(attr, &guardsize); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("Guard size: %zu\en", guardsize); +\& + s = pthread_attr_getschedpolicy(attr, &policy); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); + printf("Scheduling policy: %s\en", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]"); +\& + s = pthread_attr_getschedparam(attr, &schedparam); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); + printf("Scheduling priority: %d\en", schedparam.sched_priority); +\& + s = pthread_attr_getdetachstate(attr, &detachstate); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); + printf("Detach state: %s\en", + (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" : + (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" : + "???"); +\& + s = pthread_attr_getinheritsched(attr, &inheritsched); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); + printf("Inherit scheduler: %s\en", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); +} +\& +int +main(void) +{ + int s; + pthread_attr_t attr; +\& + s = pthread_getattr_default_np(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_default_np"); +\& + display_pthread_attr(&attr); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getattr_np.3 b/man/man3/pthread_getattr_np.3 new file mode 100644 index 0000000..6135cc4 --- /dev/null +++ b/man/man3/pthread_getattr_np.3 @@ -0,0 +1,356 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getattr_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getattr_np \- get attributes of created thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_getattr_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains actual attribute values describing the running thread +.IR thread . +.P +The returned attribute values may differ from +the corresponding attribute values passed in the +.I attr +object that was used to create the thread using +.BR pthread_create (3). +In particular, the following attributes may differ: +.IP \[bu] 3 +the detach state, since a joinable thread may have detached itself +after creation; +.IP \[bu] +the stack size, +which the implementation may align to a suitable boundary. +.IP \[bu] +and the guard size, +which the implementation may round upward to a multiple of the page size, +or ignore (i.e., treat as 0), +if the application is allocating its own stack. +.P +Furthermore, if the stack address attribute was not set +in the thread attributes object used to create the thread, +then the returned thread attributes object will report the actual +stack address that the implementation selected for the thread. +.P +When the thread attributes object returned by +.BR pthread_getattr_np () +is no longer required, it should be destroyed using +.BR pthread_attr_destroy (3). +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +Insufficient memory. +.P +In addition, if +.I thread +refers to the main thread, then +.BR pthread_getattr_np () +can fail because of errors from various underlying calls: +.BR fopen (3), +if +.I /proc/self/maps +can't be opened; +and +.BR getrlimit (2), +if the +.B RLIMIT_STACK +resource limit is not supported. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getattr_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the name. +.SH HISTORY +glibc 2.2.3. +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_getattr_np (). +The program creates a thread that then uses +.BR pthread_getattr_np () +to retrieve and display its guard size, stack address, +and stack size attributes. +Command-line arguments can be used to set these attributes +to values other than the default when creating the thread. +The shell sessions below demonstrate the use of the program. +.P +In the first run, on an x86-32 system, +a thread is created using default attributes: +.P +.in +4n +.EX +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Attributes of created thread: + Guard size = 4096 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.P +In the following run, we see that if a guard size is specified, +it is rounded up to the next multiple of the system page size +(4096 bytes on x86-32): +.P +.in +4n +.EX +.RB "$" " ./a.out \-g 4097" +Thread attributes object after initializations: + Guard size = 4097 bytes + Stack address = (nil) + Stack size = 0x0 (0) bytes +\& +Attributes of created thread: + Guard size = 8192 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.\".in +4n +.\".nf +.\"$ ./a.out \-s 0x8000 +.\"Thread attributes object after initializations: +.\" Guard size = 4096 bytes +.\" Stack address = 0xffff8000 (EOS = (nil)) +.\" Stack size = 0x8000 (32768) bytes +.\" +.\"Attributes of created thread: +.\" Guard size = 4096 bytes +.\" Stack address = 0x4001e000 (EOS = 0x40026000) +.\" Stack size = 0x8000 (32768) bytes +.\".fi +.\".in +.P +In the last run, the program manually allocates a stack for the thread. +In this case, the guard size attribute is ignored. +.P +.in +4n +.EX +.RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a" +Allocated thread stack at 0x804d000 +\& +Thread attributes object after initializations: + Guard size = 4096 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +\& +Attributes of created thread: + Guard size = 0 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getattr_np.c) +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include <err.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +static void +display_stack_related_attributes(pthread_attr_t *attr, char *prefix) +{ + int s; + size_t stack_size, guard_size; + void *stack_addr; +\& + s = pthread_attr_getguardsize(attr, &guard_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("%sGuard size = %zu bytes\en", prefix, guard_size); +\& + s = pthread_attr_getstack(attr, &stack_addr, &stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstack"); + printf("%sStack address = %p", prefix, stack_addr); + if (stack_size > 0) + printf(" (EOS = %p)", (char *) stack_addr + stack_size); + printf("\en"); + printf("%sStack size = %#zx (%zu) bytes\en", + prefix, stack_size, stack_size); +} +\& +static void +display_thread_attributes(pthread_t thread, char *prefix) +{ + int s; + pthread_attr_t attr; +\& + s = pthread_getattr_np(thread, &attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_np"); +\& + display_stack_related_attributes(&attr, prefix); +\& + s = pthread_attr_destroy(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); +} +\& +static void * /* Start function for thread we create */ +thread_start(void *arg) +{ + printf("Attributes of created thread:\en"); + display_thread_attributes(pthread_self(), "\et"); +\& + exit(EXIT_SUCCESS); /* Terminate all threads */ +} +\& +static void +usage(char *pname, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]" + " [\-g guard\-size]\en", pname); + fprintf(stderr, "\et\et\-a means program should allocate stack\en"); + exit(EXIT_FAILURE); +} +\& +static pthread_attr_t * /* Get thread attributes from command line */ +get_thread_attributes_from_cl(int argc, char *argv[], + pthread_attr_t *attrp) +{ + int s, opt, allocate_stack; + size_t stack_size, guard_size; + void *stack_addr; + pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize + a thread attributes object */ + allocate_stack = 0; + stack_size = \-1; + guard_size = \-1; +\& + while ((opt = getopt(argc, argv, "ag:s:")) != \-1) { + switch (opt) { + case \[aq]a\[aq]: allocate_stack = 1; break; + case \[aq]g\[aq]: guard_size = strtoul(optarg, NULL, 0); break; + case \[aq]s\[aq]: stack_size = strtoul(optarg, NULL, 0); break; + default: usage(argv[0], NULL); + } + } +\& + if (allocate_stack && stack_size == \-1) + usage(argv[0], "Specifying \-a without \-s makes no sense\en"); +\& + if (argc > optind) + usage(argv[0], "Extraneous command\-line arguments\en"); +\& + if (stack_size != -1 || guard_size > 0) { + ret_attrp = attrp; +\& + s = pthread_attr_init(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_init"); + } +\& + if (stack_size != -1) { + if (!allocate_stack) { + s = pthread_attr_setstacksize(attrp, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } else { + s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE), + stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "posix_memalign"); + printf("Allocated thread stack at %p\en\en", stack_addr); +\& + s = pthread_attr_setstack(attrp, stack_addr, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } + } +\& + if (guard_size != -1) { + s = pthread_attr_setguardsize(attrp, guard_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } +\& + return ret_attrp; +} +\& +int +main(int argc, char *argv[]) +{ + int s; + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize + a thread attributes object */ +\& + attrp = get_thread_attributes_from_cl(argc, argv, &attr); +\& + if (attrp != NULL) { + printf("Thread attributes object after initializations:\en"); + display_stack_related_attributes(attrp, "\et"); + printf("\en"); + } +\& + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_create"); +\& + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); + } +\& + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getconcurrency.3 b/man/man3/pthread_getconcurrency.3 new file mode 100644 index 0000000..8b2d543 --- /dev/null +++ b/man/man3/pthread_getconcurrency.3 @@ -0,0 +1 @@ +.so man3/pthread_setconcurrency.3 diff --git a/man/man3/pthread_getcpuclockid.3 b/man/man3/pthread_getcpuclockid.3 new file mode 100644 index 0000000..7ad000d --- /dev/null +++ b/man/man3/pthread_getcpuclockid.3 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getcpuclockid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.B #include <time.h> +.P +.BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid ); +.fi +.SH DESCRIPTION +The +.BR pthread_getcpuclockid () +function obtains the ID of the CPU-time clock of the thread whose ID is +given in +.IR thread , +and returns it in the location pointed to by +.IR clockid . +.\" The clockid is constructed as follows: +.\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE) +.\" where CLOCK_IDFIELD_SIZE is 3. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOENT +.\" CLOCK_THREAD_CPUTIME_ID not defined +Per-thread CPU time clocks are not supported by the system. +.\" +.\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would +.\" be possible if kernel thread IDs took more than 29 bits (which +.\" they currently cannot). +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +When +.I thread +refers to the calling thread, +this function returns an identifier that refers to the same clock +manipulated by +.BR clock_gettime (2) +and +.BR clock_settime (2) +when given the clock ID +.BR CLOCK_THREAD_CPUTIME_ID . +.SH EXAMPLES +The program below creates a thread and then uses +.BR clock_gettime (2) +to retrieve the total process CPU time, +and the per-thread CPU time consumed by the two threads. +The following shell session shows an example run: +.P +.in +4n +.EX +$ \fB./a.out\fP +Main thread sleeping +Subthread starting infinite loop +Main thread consuming some CPU time... +Process total CPU time: 1.368 +Main thread CPU time: 0.376 +Subthread CPU time: 0.992 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getcpuclockid.c) +.EX +/* Link with "\-lrt" */ +\& +#include <errno.h> +#include <pthread.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> +#include <unistd.h> +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +thread_start(void *arg) +{ + printf("Subthread starting infinite loop\en"); + for (;;) + continue; +} +\& +static void +pclock(char *msg, clockid_t cid) +{ + struct timespec ts; +\& + printf("%s", msg); + if (clock_gettime(cid, &ts) == \-1) + handle_error("clock_gettime"); + printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000); +} +\& +int +main(void) +{ + pthread_t thread; + clockid_t cid; + int s; +\& + s = pthread_create(&thread, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + printf("Main thread sleeping\en"); + sleep(1); +\& + printf("Main thread consuming some CPU time...\en"); + for (unsigned int j = 0; j < 2000000; j++) + getppid(); +\& + pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID); +\& + s = pthread_getcpuclockid(pthread_self(), &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Main thread CPU time: ", cid); +\& + /* The preceding 4 lines of code could have been replaced by: + pclock("Main thread CPU time: ", CLOCK_THREAD_CPUTIME_ID); */ +\& + s = pthread_getcpuclockid(thread, &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Subthread CPU time: 1 ", cid); +\& + exit(EXIT_SUCCESS); /* Terminates both threads */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_settime (2), +.BR timer_create (2), +.BR clock_getcpuclockid (3), +.BR pthread_self (3), +.BR pthreads (7), +.BR time (7) diff --git a/man/man3/pthread_getname_np.3 b/man/man3/pthread_getname_np.3 new file mode 100644 index 0000000..a385c6e --- /dev/null +++ b/man/man3/pthread_getname_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setname_np.3 diff --git a/man/man3/pthread_getschedparam.3 b/man/man3/pthread_getschedparam.3 new file mode 100644 index 0000000..67299c5 --- /dev/null +++ b/man/man3/pthread_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_setschedparam.3 diff --git a/man/man3/pthread_getspecific.3 b/man/man3/pthread_getspecific.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_getspecific.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_join.3 b/man/man3/pthread_join.3 new file mode 100644 index 0000000..1d3fbb8 --- /dev/null +++ b/man/man3/pthread_join.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_join 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_join \- join with a terminated thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_join(pthread_t " thread ", void **" retval ); +.fi +.SH DESCRIPTION +The +.BR pthread_join () +function waits for the thread specified by +.I thread +to terminate. +If that thread has already terminated, then +.BR pthread_join () +returns immediately. +The thread specified by +.I thread +must be joinable. +.P +If +.I retval +is not NULL, then +.BR pthread_join () +copies the exit status of the target thread +(i.e., the value that the target thread supplied to +.BR pthread_exit (3)) +into the location pointed to by +.IR retval . +If the target thread was canceled, then +.B PTHREAD_CANCELED +is placed in the location pointed to by +.IR retval . +.P +If multiple threads simultaneously try to join with the same thread, +the results are undefined. +If the thread calling +.BR pthread_join () +is canceled, then the target thread will remain joinable +(i.e., it will not be detached). +.SH RETURN VALUE +On success, +.BR pthread_join () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EDEADLK +A deadlock was detected +.\" The following verified by testing on glibc 2.8/NPTL: +(e.g., two threads tried to join with each other); +or +.\" The following verified by testing on glibc 2.8/NPTL: +.I thread +specifies the calling thread. +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B EINVAL +Another thread is already waiting to join with this thread. +.\" POSIX.1-2001 does not specify this error case. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_join () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +After a successful call to +.BR pthread_join (), +the caller is guaranteed that the target thread has terminated. +The caller may then choose to do any clean-up that is required +after termination of the thread (e.g., freeing memory or other +resources that were allocated to the target thread). +.P +Joining with a thread that has previously been joined results in +undefined behavior. +.P +Failure to join with a thread that is joinable +(i.e., one that is not detached), +produces a "zombie thread". +Avoid doing this, +since each zombie thread consumes some system resources, +and when enough zombie threads have accumulated, +it will no longer be possible to create new threads (or processes). +.P +There is no pthreads analog of +.IR "waitpid(\-1,\ &status,\ 0)" , +that is, "join with any terminated thread". +If you believe you need this functionality, +you probably need to rethink your application design. +.P +All of the threads in a process are peers: +any thread can join with any other thread in the process. +.SH EXAMPLES +See +.BR pthread_create (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_exit (3), +.BR pthread_tryjoin_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_key_create.3 b/man/man3/pthread_key_create.3 new file mode 100644 index 0000000..f319426 --- /dev/null +++ b/man/man3/pthread_key_create.3 @@ -0,0 +1,181 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_key_create 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_key_create, +pthread_key_delete, +pthread_setspecific, +pthread_getspecific +\- +management of thread-specific data +. +. +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_key_create(pthread_key_t *" key , +.BI " void (*" destr_function ") (void *));" +.BI "int pthread_key_delete(pthread_key_t " key ); +.BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ); +.BI "void * pthread_getspecific(pthread_key_t " key ); +.fi +. +. +.SH DESCRIPTION +Programs often need global or static variables +that have different values in different threads. +Since threads share one memory space, +this cannot be achieved with regular variables. +Thread-specific data is the POSIX threads answer to this need. +.P +Each thread possesses a private memory block, +the thread-specific data area, +or TSD area for short. +This area is indexed by TSD keys. +The TSD area associates values of type \fBvoid *\fP to TSD keys. +TSD keys are common to all threads, +but the value associated with a given TSD key +can be different in each thread. +.P +For concreteness, +the TSD areas can be viewed as arrays of \fBvoid *\fP pointers, +TSD keys as integer indices into these arrays, +and the value of a TSD key +as the value of the corresponding array element in the calling thread. +.P +When a thread is created, +its TSD area initially associates \fBNULL\fP with all keys. +.P +\fBpthread_key_create\fP allocates a new TSD key. +The key is stored in the location pointed to by \fIkey\fP. +There is a limit of \fBPTHREAD_KEYS_MAX\fP +on the number of keys allocated at a given time. +The value initially associated with the returned key +is \fBNULL\fP in all currently executing threads. +.P +The \fIdestr_function\fP argument, +if not \fBNULL\fP, +specifies a destructor function associated with the key. +When a thread terminates via \fBpthread_exit\fP or by cancelation, +\fIdestr_function\fP is called with arguments +the value associated with the key in that thread. +The \fIdestr_function\fP is not called if that value is \fBNULL\fP. +The order in which destructor functions are called at thread termination time +is unspecified. +.P +Before the destructor function is called, +the \fBNULL\fP value is associated with the key in the current thread. +A destructor function might, +however, +re-associate non-\fBNULL\fP values to that key or some other key. +To deal with this, +if after all the destructors have been called +for all non-\fBNULL\fP values, +there are still some non-\fBNULL\fP values with associated destructors, +then the process is repeated. +The glibc implementation stops the process +after \fBPTHREAD_DESTRUCTOR_ITERATIONS\fP iterations, +even if some non-\fBNULL\fP values with associated descriptors remain. +Other implementations may loop indefinitely. +.P +\fBpthread_key_delete\fP deallocates a TSD key. +It does not check +whether non-\fBNULL\fP values are associated with that key +in the currently executing threads, +nor call the destructor function associated with the key. +.P +\fBpthread_setspecific\fP changes the value +associated with \fIkey\fP in the calling thread, +storing the given \fIpointer\fP instead. +.P +\fBpthread_getspecific\fP returns the value +currently associated with \fIkey\fP in the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_key_create\fP, +\fBpthread_key_delete\fP, +and \fBpthread_setspecific\fP +return 0 on success and a non-zero error code on failure. +If successful, +\fBpthread_key_create\fP stores the newly allocated key +in the location pointed to by its \fIkey\fP argument. +.P +\fBpthread_getspecific\fP returns +the value associated with \fIkey\fP on success, +and \fBNULL\fP on error. +. +. +.SH ERRORS +\fBpthread_key_create\fP returns the following error code on error: +.RS +.TP +\fBEAGAIN\fP +\fBPTHREAD_KEYS_MAX\fP keys are already allocated. +.RE +.P +\fBpthread_key_delete\fP and \fBpthread_setspecific\fP return +the following error code on error: +.RS +.TP +\fBEINVAL\fP +\fIkey\fP is not a valid, allocated TSD key. +.RE +.P +\fBpthread_getspecific\fP returns \fBNULL\fP if \fIkey\fP is not a valid, +allocated TSD key. +. +. +.SH "SEE ALSO" +pthread_create(3), pthread_exit(3), pthread_testcancel(3). +. +. +.SH EXAMPLE +The following code fragment +allocates a thread-specific array of 100 characters, +with automatic reclamation at thread exit: +.P +.RS +.ft 3 +.nf +.sp +/* Key for the thread-specific buffer */ +static pthread_key_t buffer_key; +\& +/* Once-only initialisation of the key */ +static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT; +\& +/* Allocate the thread-specific buffer */ +void buffer_alloc(void) +{ + pthread_once(&buffer_key_once, buffer_key_alloc); + pthread_setspecific(buffer_key, malloc(100)); +} +\& +/* Return the thread-specific buffer */ +char * get_buffer(void) +{ + return (char *) pthread_getspecific(buffer_key); +} +\& +/* Allocate the key */ +static void buffer_key_alloc() +{ + pthread_key_create(&buffer_key, buffer_destroy); +} +\& +/* Free the thread-specific buffer */ +static void buffer_destroy(void * buf) +{ + free(buf); +} +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_key_delete.3 b/man/man3/pthread_key_delete.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_key_delete.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_kill.3 b/man/man3/pthread_kill.3 new file mode 100644 index 0000000..3d445ed --- /dev/null +++ b/man/man3/pthread_kill.3 @@ -0,0 +1,108 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_kill 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_kill \- send a signal to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int pthread_kill(pthread_t " thread ", int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_kill (): +.nf + _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +The +.BR pthread_kill () +function sends the signal +.I sig +to +.IR thread , +a thread in the same process as the caller. +The signal is asynchronously directed to +.IR thread . +.P +If +.I sig +is 0, then no signal is sent, but error checking is still performed. +.SH RETURN VALUE +On success, +.BR pthread_kill () +returns 0; +on error, it returns an error number, and no signal is sent. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_kill () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc implementation of +.BR pthread_kill () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.P +POSIX.1-2008 recommends that if an implementation detects the use +of a thread ID after the end of its lifetime, +.BR pthread_kill () +should return the error +.BR ESRCH . +The glibc implementation returns this error in the cases where +an invalid thread ID can be detected. +But note also that POSIX says that an attempt to use a thread ID whose +lifetime has ended produces undefined behavior, +and an attempt to use an invalid thread ID in a call to +.BR pthread_kill () +can, for example, cause a segmentation fault. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Signal dispositions are process-wide: +if a signal handler is installed, +the handler will be invoked in the thread +.IR thread , +but if the disposition of the signal is "stop", "continue", or "terminate", +this action will affect the whole process. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigpending (2), +.BR pthread_self (3), +.BR pthread_sigmask (3), +.BR raise (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_kill_other_threads_np.3 b/man/man3/pthread_kill_other_threads_np.3 new file mode 100644 index 0000000..dea465f --- /dev/null +++ b/man/man3/pthread_kill_other_threads_np.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_kill_other_threads_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_kill_other_threads_np \- terminate all other threads in process +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.B void pthread_kill_other_threads_np(void); +.fi +.SH DESCRIPTION +.BR pthread_kill_other_threads_np () +has an effect only in the LinuxThreads threading implementation. +On that implementation, +calling this function causes the immediate termination of +all threads in the application, +except the calling thread. +The cancelation state and cancelation type of the +to-be-terminated threads are ignored, +and the cleanup handlers are not called in those threads. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_kill_other_threads_np () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +In the NPTL threading implementation, +.BR pthread_kill_other_threads_np () +exists, but does nothing. +(Nothing needs to be done, +because the implementation does the right thing during an +.BR execve (2).) +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the name. +.SH HISTORY +glibc 2.0 +.SH NOTES +.BR pthread_kill_other_threads_np () +is intended to be called just before a thread calls +.BR execve (2) +or a similar function. +This function is designed to address a limitation in the obsolete +LinuxThreads implementation whereby the other threads of an application +are not automatically terminated (as POSIX.1-2001 requires) during +.BR execve (2). +.SH SEE ALSO +.BR execve (2), +.BR pthread_cancel (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutex_consistent.3 b/man/man3/pthread_mutex_consistent.3 new file mode 100644 index 0000000..d81b364 --- /dev/null +++ b/man/man3/pthread_mutex_consistent.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com> +.\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutex_consistent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutex_consistent \- make a robust mutex consistent +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_mutex_consistent(pthread_mutex_t *" mutex ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_mutex_consistent (): +.nf + _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +This function makes a robust mutex consistent if it is in an inconsistent +state. +A mutex can be left in an inconsistent state if its owner terminates +while holding the mutex, in which case the next owner who acquires the +mutex will succeed and be notified by a return value of +.B EOWNERDEAD +from a call to +.BR pthread_mutex_lock (). +.SH RETURN VALUE +On success, +.IR pthread_mutex_consistent () +returns 0. +Otherwise, +it returns a positive error number to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The mutex is either not robust or is not in an inconsistent state. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.12. +POSIX.1-2008. +.P +Before the addition of +.BR pthread_mutex_consistent () +to POSIX, +glibc defined the following equivalent nonstandard function if +.B _GNU_SOURCE +was defined: +.P +.nf +.B [[deprecated]] +.BI "int pthread_mutex_consistent_np(const pthread_mutex_t *" mutex ); +.fi +.P +This GNU-specific API, which first appeared in glibc 2.4, +is nowadays obsolete and should not be used in new programs; +since glibc 2.34 it has been marked as deprecated. +.SH NOTES +.BR pthread_mutex_consistent () +simply informs the implementation that the state (shared data) +guarded by the mutex has been restored to a consistent state and that +normal operations can now be performed with the mutex. +It is the application's responsibility to ensure that the +shared data has been restored to a consistent state before calling +.BR pthread_mutex_consistent (). +.SH EXAMPLES +See +.BR pthread_mutexattr_setrobust (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_lock (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthread_mutexattr_init (3), +.BR pthread_mutexattr_setrobust (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutex_consistent_np.3 b/man/man3/pthread_mutex_consistent_np.3 new file mode 100644 index 0000000..a45bea4 --- /dev/null +++ b/man/man3/pthread_mutex_consistent_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_consistent.3 diff --git a/man/man3/pthread_mutex_destroy.3 b/man/man3/pthread_mutex_destroy.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_init.3 b/man/man3/pthread_mutex_init.3 new file mode 100644 index 0000000..0b05459 --- /dev/null +++ b/man/man3/pthread_mutex_init.3 @@ -0,0 +1,244 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutex_init 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_mutex_init, +pthread_mutex_lock, +pthread_mutex_trylock, +pthread_mutex_unlock, +pthread_mutex_destroy +\- +operations on mutexes +. +. +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;" +.BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;" +.BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;" +.P +.BI "int pthread_mutex_init(pthread_mutex_t *" mutex , +.BI " const pthread_mutexattr_t *" mutexattr ); +.BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex ); +.fi +. +. +.SH DESCRIPTION +A mutex is a MUTual EXclusion device, +and is useful for +protecting shared data structures from concurrent modifications, +and implementing critical sections and monitors. +.P +A mutex has two possible states: +unlocked (not owned by any thread), +and locked (owned by one thread). +A mutex can never be owned by two different threads simultaneously. +A thread attempting to lock a mutex +that is already locked by another thread +is suspended until the owning thread unlocks the mutex first. +.P +\fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP +according to the mutex attributes specified in \fImutexattr\fP. +If \fImutexattr\fP is \fBNULL\fP, +default attributes are used instead. +.P +The LinuxThreads implementation supports only one mutex attributes, +the \fImutex kind\fP, +which is either ``fast'', +``recursive'', +or ``error checking''. +The kind of a mutex determines +whether it can be locked again by a thread that already owns it. +The default kind is ``fast''. +See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes. +.P +Variables of type \fBpthread_mutex_t\fP can also be initialized statically, +using the constants +\fBPTHREAD_MUTEX_INITIALIZER\fP +(for fast mutexes), +\fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP +(for recursive mutexes), +and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP +(for error checking mutexes). +.P +\fBpthread_mutex_lock\fP locks the given mutex. +If the mutex is currently unlocked, +it becomes locked and owned by the calling thread, +and \fBpthread_mutex_lock\fP returns immediately. +If the mutex is already locked by another thread, +\fBpthread_mutex_lock\fP suspends the calling thread +until the mutex is unlocked. +.P +If the mutex is already locked by the calling thread, +the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex. +If the mutex is of the ``fast'' kind, +the calling thread is suspended until the mutex is unlocked, +thus effectively causing the calling thread to deadlock. +If the mutex is of the ``error checking'' kind, +\fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP. +If the mutex is of the ``recursive'' kind, +\fBpthread_mutex_lock\fP succeeds and returns immediately, +recording the number of times the calling thread has locked the mutex. +An equal number of \fBpthread_mutex_unlock\fP operations +must be performed before the mutex returns to the unlocked state. +.P +\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP, +except that it does not block the calling thread +if the mutex is already locked by another thread +(or by the calling thread in the case of a ``fast'' mutex). +Instead, +\fBpthread_mutex_trylock\fP returns immediately +with the error code \fBEBUSY\fP. +.P +\fBpthread_mutex_unlock\fP unlocks the given mutex. +The mutex is assumed to be locked and owned by the calling thread +on entrance to \fBpthread_mutex_unlock\fP. +If the mutex is of the ``fast'' kind, +\fBpthread_mutex_unlock\fP always returns it to the unlocked state. +If it is of the ``recursive'' kind, +it decrements the locking count of the mutex +(number of \fBpthread_mutex_lock\fP operations +performed on it by the calling thread), +and only when this count reaches zero is the mutex actually unlocked. +.P +On ``error checking'' and ``recursive'' mutexes, +\fBpthread_mutex_unlock\fP actually checks at run-time +that the mutex is locked on entrance, +and that it was locked by the same thread +that is now calling \fBpthread_mutex_unlock\fP. +If these conditions are not met, +an error code is returned and the mutex remains unchanged. +``Fast'' mutexes perform no such checks, +thus allowing a locked mutex to be +unlocked by a thread other than its owner. +This is non-portable behavior and must not be relied upon. +.P +\fBpthread_mutex_destroy\fP destroys a mutex object, +freeing the resources it might hold. +The mutex must be unlocked on entrance. +In the LinuxThreads implementation, +no resources are associated with mutex objects, +thus \fBpthread_mutex_destroy\fP actually does nothing +except checking that the mutex is unlocked. +. +. +.SH CANCELLATION +None of the mutex functions is a cancelation point, +not even \fBpthread_mutex_lock\fP, +in spite of the fact that it can suspend a thread for arbitrary durations. +This way, +the status of mutexes at cancelation points is predictable, +allowing cancelation handlers +to unlock precisely those mutexes that need to be unlocked +before the thread stops executing. +Consequently, +threads using deferred cancelation +should never hold a mutex for extended periods of time. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The mutex functions are not async-signal safe. +What this means is that they should not be called from a signal handler. +In particular, +calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_mutex_init\fP always returns 0. +The other mutex functions +return 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +The \fBpthread_mutex_lock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEDEADLK\fP +The mutex is already locked by the calling thread +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_trylock\fP function returns +the following error codes on error: +.RS +.TP +\fBEBUSY\fP +The mutex could not be acquired because it was currently locked. +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.RE +.P +The \fBpthread_mutex_unlock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEPERM\fP +The calling thread does not own the mutex +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +The mutex is currently locked. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_init\fP(3), +\fBpthread_mutexattr_setkind_np\fP(3), +\fBpthread_cancel\fP(3). +. +. +.SH EXAMPLE +A shared global variable \fIx\fP can be protected by a mutex as follows: +.P +.RS +.ft 3 +.nf +.sp +int x; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +.ft +.P +.RE +.fi +.P +All accesses and modifications to \fIx\fP +should be bracketed by calls to +\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP +as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* operate on x */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_mutex_lock.3 b/man/man3/pthread_mutex_lock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_lock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_trylock.3 b/man/man3/pthread_mutex_trylock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_trylock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_unlock.3 b/man/man3/pthread_mutex_unlock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_unlock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutexattr_destroy.3 b/man/man3/pthread_mutexattr_destroy.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_mutexattr_getkind_np.3 b/man/man3/pthread_mutexattr_getkind_np.3 new file mode 100644 index 0000000..af2ab96 --- /dev/null +++ b/man/man3/pthread_mutexattr_getkind_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setkind_np.3 diff --git a/man/man3/pthread_mutexattr_getpshared.3 b/man/man3/pthread_mutexattr_getpshared.3 new file mode 100644 index 0000000..0d19e60 --- /dev/null +++ b/man/man3/pthread_mutexattr_getpshared.3 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_getpshared 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get/set +process-shared mutex attribute +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.B int pthread_mutexattr_getpshared( +.BI " const pthread_mutexattr_t *restrict " attr , +.BI " int *restrict " pshared ); +.BI "int pthread_mutexattr_setpshared(pthread_mutexattr_t *" attr , +.BI " int " pshared ); +.fi +.SH DESCRIPTION +These functions get and set the process-shared attribute +in a mutex attributes object. +This attribute must be appropriately set to ensure correct, +efficient operation of a mutex created using this attributes object. +.P +The process-shared attribute can have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +Mutexes created with this attributes object are to be shared +only among threads in the same process that initialized the mutex. +This is the default value for the process-shared mutex attribute. +.TP +.B PTHREAD_PROCESS_SHARED +Mutexes created with this attributes object can be shared between +any threads that have access to the memory containing the object, +including threads in different processes. +.P +.BR pthread_mutexattr_getpshared () +places the value of the process-shared attribute of +the mutex attributes object referred to by +.I attr +in the location pointed to by +.IR pshared . +.P +.BR pthread_mutexattr_setpshared () +sets the value of the process-shared attribute of +the mutex attributes object referred to by +.I attr +to the value specified in +.BR pshared . +.P +If +.I attr +does not refer to an initialized mutex attributes object, +the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH ERRORS +.BR pthread_mutexattr_setpshared () +can fail with the following errors: +.TP +.B EINVAL +The value specified in +.I pshared +is invalid. +.TP +.B ENOTSUP +.I pshared is +.B PTHREAD_PROCESS_SHARED +but the implementation does not support process-shared mutexes. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutexattr_init (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_getrobust.3 b/man/man3/pthread_mutexattr_getrobust.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_getrobust.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_getrobust_np.3 b/man/man3/pthread_mutexattr_getrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_getrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_gettype.3 b/man/man3/pthread_mutexattr_gettype.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_gettype.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_mutexattr_init.3 b/man/man3/pthread_mutexattr_init.3 new file mode 100644 index 0000000..8b89bad --- /dev/null +++ b/man/man3/pthread_mutexattr_init.3 @@ -0,0 +1,53 @@ +.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_init, pthread_mutexattr_destroy \- initialize and +destroy a mutex attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");" +.BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");" +.fi +.SH DESCRIPTION +The +.BR pthread_mutexattr_init () +function initializes the mutex attributes object pointed to by +.I attr +with default values for all attributes defined by the implementation. +.P +The results of initializing an already initialized mutex attributes +object are undefined. +.P +The +.BR pthread_mutexattr_destroy () +function destroys a mutex attribute object (making it uninitialized). +Once a mutex attributes object has been destroyed, it can be reinitialized with +.BR pthread_mutexattr_init (). +.P +The results of destroying an uninitialized mutex attributes +object are undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Subsequent changes to a mutex attributes object do not affect mutex that +have already been initialized using that object. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutexattr_getpshared (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_setkind_np.3 b/man/man3/pthread_mutexattr_setkind_np.3 new file mode 100644 index 0000000..4480d88 --- /dev/null +++ b/man/man3/pthread_mutexattr_setkind_np.3 @@ -0,0 +1,55 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_setkind_np 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_mutexattr_setkind_np, +pthread_mutexattr_getkind_np +\- +deprecated mutex creation attributes +. +. +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_mutexattr_setkind_np(pthread_mutexattr_t *" attr ", int " kind ); +.BI "int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *" attr , +.BI " int *" kind ); +.fi +. +. +.SH DESCRIPTION +These functions are deprecated, +use \fBpthread_mutexattr_settype\fP(3) +and \fBpthread_mutexattr_gettype\fP(3) +instead. +. +. +.SH "RETURN VALUE" +\fBpthread_mutexattr_getkind_np\fP always returns 0. +.P +\fBpthread_mutexattr_setkind_np\fP +returns 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +On error, +\fBpthread_mutexattr_setkind_np\fP returns the following error code: +.TP +\fBEINVAL\fP +\fIkind\fP is neither +\fBPTHREAD_MUTEX_FAST_NP\fP +nor +\fBPTHREAD_MUTEX_RECURSIVE_NP\fP +nor +\fBPTHREAD_MUTEX_ERRORCHECK_NP\fP. +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_settype\fP(3), +\fBpthread_mutexattr_gettype\fP(3). diff --git a/man/man3/pthread_mutexattr_setpshared.3 b/man/man3/pthread_mutexattr_setpshared.3 new file mode 100644 index 0000000..07899fd --- /dev/null +++ b/man/man3/pthread_mutexattr_setpshared.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_getpshared.3 diff --git a/man/man3/pthread_mutexattr_setrobust.3 b/man/man3/pthread_mutexattr_setrobust.3 new file mode 100644 index 0000000..7467722 --- /dev/null +++ b/man/man3/pthread_mutexattr_setrobust.3 @@ -0,0 +1,264 @@ +.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com> +.\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_setrobust 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_getrobust, pthread_mutexattr_setrobust +\- get and set the robustness attribute of a mutex attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_mutexattr_getrobust (), +.BR pthread_mutexattr_setrobust (): +.nf + _POSIX_C_SOURCE >= 200809L +.\" FIXME . +.\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125 +.fi +.SH DESCRIPTION +The +.BR pthread_mutexattr_getrobust () +function places the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +in +.IR *robustness . +The +.BR pthread_mutexattr_setrobust () +function sets the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +to the value specified in +.IR *robustness . +.P +The robustness attribute specifies the behavior of the mutex when +the owning thread dies without unlocking the mutex. +The following values are valid for +.IR robustness : +.TP +.B PTHREAD_MUTEX_STALLED +This is the default value for a mutex attributes object. +If a mutex is initialized with the +.B PTHREAD_MUTEX_STALLED +attribute and its owner dies without unlocking it, +the mutex remains locked afterwards and any future attempts to call +.BR pthread_mutex_lock (3) +on the mutex will block indefinitely. +.TP +.B PTHREAD_MUTEX_ROBUST +If a mutex is initialized with the +.B PTHREAD_MUTEX_ROBUST +attribute and its owner dies without unlocking it, +any future attempts to call +.BR pthread_mutex_lock (3) +on this mutex will succeed and return +.B EOWNERDEAD +to indicate that the original owner no longer exists and the mutex is in +an inconsistent state. +Usually after +.B EOWNERDEAD +is returned, the next owner should call +.BR pthread_mutex_consistent (3) +on the acquired mutex to make it consistent again before using it any further. +.IP +If the next owner unlocks the mutex using +.BR pthread_mutex_unlock (3) +before making it consistent, the mutex will be permanently unusable and any +subsequent attempts to lock it using +.BR pthread_mutex_lock (3) +will fail with the error +.BR ENOTRECOVERABLE . +The only permitted operation on such a mutex is +.BR pthread_mutex_destroy (3). +.IP +If the next owner terminates before calling +.BR pthread_mutex_consistent (3), +further +.BR pthread_mutex_lock (3) +operations on this mutex will still return +.BR EOWNERDEAD . +.P +Note that the +.I attr +argument of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +should refer to a mutex attributes object that was initialized by +.BR pthread_mutexattr_init (3), +otherwise the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.P +In the glibc implementation, +.BR pthread_mutexattr_getrobust () +always return zero. +.SH ERRORS +.TP +.B EINVAL +A value other than +.B PTHREAD_MUTEX_STALLED +or +.B PTHREAD_MUTEX_ROBUST +was passed to +.BR pthread_mutexattr_setrobust (). +.SH VERSIONS +In the Linux implementation, +when using process-shared robust mutexes, a waiting thread also receives the +.B EOWNERDEAD +notification if the owner of a robust mutex performs an +.BR execve (2) +without first unlocking the mutex. +POSIX.1 does not specify this detail, +but the same behavior also occurs in at least some +.\" E.g., Solaris, according to its manual page +other implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.12. +POSIX.1-2008. +.P +Before the addition of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +to POSIX, +glibc defined the following equivalent nonstandard functions if +.B _GNU_SOURCE +was defined: +.P +.nf +.B [[deprecated]] +.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.B [[deprecated]] +.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.P +Correspondingly, the constants +.B PTHREAD_MUTEX_STALLED_NP +and +.B PTHREAD_MUTEX_ROBUST_NP +were also defined. +.P +These GNU-specific APIs, which first appeared in glibc 2.4, +are nowadays obsolete and should not be used in new programs; +since glibc 2.34 these APIs are marked as deprecated. +.SH EXAMPLES +The program below demonstrates the use of the robustness attribute of a +mutex attributes object. +In this program, a thread holding the mutex +dies prematurely without unlocking the mutex. +The main thread subsequently acquires the mutex +successfully and gets the error +.BR EOWNERDEAD , +after which it makes the mutex consistent. +.P +The following shell session shows what we see when running this program: +.P +.in +4n +.EX +$ \fB./a.out\fP +[original owner] Setting lock... +[original owner] Locked. Now exiting without unlocking. +[main] Attempting to lock the robust mutex. +[main] pthread_mutex_lock() returned EOWNERDEAD +[main] Now make the mutex consistent +[main] Mutex is now consistent; unlocking +.EE +.in +.SS Program source +.\" SRC BEGIN (pthread_mutexattr_setrobust.c) +.EX +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static pthread_mutex_t mtx; +\& +static void * +original_owner_thread(void *ptr) +{ + printf("[original owner] Setting lock...\en"); + pthread_mutex_lock(&mtx); + printf("[original owner] Locked. Now exiting without unlocking.\en"); + pthread_exit(NULL); +} +\& +int +main(void) +{ + pthread_t thr; + pthread_mutexattr_t attr; + int s; +\& + pthread_mutexattr_init(&attr); +\& + pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); +\& + pthread_mutex_init(&mtx, &attr); +\& + pthread_create(&thr, NULL, original_owner_thread, NULL); +\& + sleep(2); +\& + /* "original_owner_thread" should have exited by now. */ +\& + printf("[main] Attempting to lock the robust mutex.\en"); + s = pthread_mutex_lock(&mtx); + if (s == EOWNERDEAD) { + printf("[main] pthread_mutex_lock() returned EOWNERDEAD\en"); + printf("[main] Now make the mutex consistent\en"); + s = pthread_mutex_consistent(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_consistent"); + printf("[main] Mutex is now consistent; unlocking\en"); + s = pthread_mutex_unlock(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_unlock"); +\& + exit(EXIT_SUCCESS); + } else if (s == 0) { + printf("[main] pthread_mutex_lock() unexpectedly succeeded\en"); + exit(EXIT_FAILURE); + } else { + printf("[main] pthread_mutex_lock() unexpectedly failed\en"); + handle_error_en(s, "pthread_mutex_lock"); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR get_robust_list (2), +.BR set_robust_list (2), +.BR pthread_mutex_consistent (3), +.BR pthread_mutex_init (3), +.BR pthread_mutex_lock (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_setrobust_np.3 b/man/man3/pthread_mutexattr_setrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_setrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_settype.3 b/man/man3/pthread_mutexattr_settype.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_settype.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_once.3 b/man/man3/pthread_once.3 new file mode 100644 index 0000000..86ecd84 --- /dev/null +++ b/man/man3/pthread_once.3 @@ -0,0 +1,44 @@ +.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_once 3 2024-05-02 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_once +\- +once-only initialization +. +. +.SH SYNOPSIS +.B #include <pthread.h> +.P +.BI "pthread_once_t " once_control " = PTHREAD_ONCE_INIT;" +.P +.BI "int pthread_once(pthread_once_t *" once_control ", void (*" init_routine ") (void));" +. +. +.SH DESCRIPTION +The purpose of \fBpthread_once\fP is +to ensure that a piece of initialization code is executed at most once. +The \fIonce_control\fP argument points to a static or extern variable +statically initialized to \fBPTHREAD_ONCE_INIT\fP. +.P +The first time \fBpthread_once\fP is called +with a given \fIonce_control\fP argument, +it calls \fIinit_routine\fP with no argument +and changes the value of the \fIonce_control\fP variable +to record that initialization has been performed. +Subsequent calls to \fBpthread_once\fP +with the same \fBonce_control\fP argument +do nothing. +. +. +.SH "RETURN VALUE" +\fBpthread_once\fP always returns 0. +. +. +.SH ERRORS +None. diff --git a/man/man3/pthread_rwlockattr_getkind_np.3 b/man/man3/pthread_rwlockattr_getkind_np.3 new file mode 100644 index 0000000..6f3f740 --- /dev/null +++ b/man/man3/pthread_rwlockattr_getkind_np.3 @@ -0,0 +1 @@ +.so man3/pthread_rwlockattr_setkind_np.3 diff --git a/man/man3/pthread_rwlockattr_setkind_np.3 b/man/man3/pthread_rwlockattr_setkind_np.3 new file mode 100644 index 0000000..ce6a14c --- /dev/null +++ b/man/man3/pthread_rwlockattr_setkind_np.3 @@ -0,0 +1,119 @@ +.\"Copyright (c) 2010 Novell Inc., written by Robert Schweikert +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_rwlockattr_setkind_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get +the read-write lock kind of the thread read-write lock attribute object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr , +.BI " int " pref ); +.B int pthread_rwlockattr_getkind_np( +.BI " const pthread_rwlockattr_t *restrict " attr , +.BI " int *restrict " pref ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_rwlockattr_setkind_np (), +.BR pthread_rwlockattr_getkind_np (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR pthread_rwlockattr_setkind_np () +function sets the "lock kind" attribute of the +read-write lock attribute object referred to by +.I attr +to the value specified in +.IR pref . +The argument +.I pref +may be set to one of the following: +.TP +.B PTHREAD_RWLOCK_PREFER_READER_NP +This is the default. +A thread may hold multiple read locks; that is, read locks are recursive. +According to The Single Unix Specification, the behavior is unspecified when a +reader tries to place a lock, and there is no write lock but writers are +waiting. +Giving preference to the reader, as is set by +.BR PTHREAD_RWLOCK_PREFER_READER_NP , +implies that the reader will receive the requested lock, even if +a writer is waiting. +As long as there are readers, the writer will be +starved. +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NP +This is intended as the write lock analog of +.BR PTHREAD_RWLOCK_PREFER_READER_NP . +This is ignored by glibc because the POSIX requirement to support +recursive read locks would cause this option to create trivial +deadlocks; instead use +.B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +which ensures the application developer will not take recursive +read locks thus avoiding deadlocks. +.\" --- +.\" Here is the relevant wording: +.\" +.\" A thread may hold multiple concurrent read locks on rwlock (that is, +.\" successfully call the pthread_rwlock_rdlock() function n times). If +.\" so, the thread must perform matching unlocks (that is, it must call +.\" the pthread_rwlock_unlock() function n times). +.\" +.\" By making write-priority work correctly, I broke the above requirement, +.\" because I had no clue that recursive read locks are permissible. +.\" +.\" If a thread which holds a read lock tries to acquire another read lock, +.\" and now one or more writers is waiting for a write lock, then the algorithm +.\" will lead to an obvious deadlock. The reader will be suspended, waiting for +.\" the writers to acquire and release the lock, and the writers will be +.\" suspended waiting for every existing read lock to be released. +.\" --- +.\" https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html +.\" https://sourceware.org/legacy-ml/libc-alpha/2000-01/msg00055.html +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=7057 +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +Setting the lock kind to this +avoids writer starvation as long as any read locking is not done in a +recursive fashion. +.P +The +.BR pthread_rwlockattr_getkind_np () +function returns the value of the lock kind attribute of the +read-write lock attribute object referred to by +.I attr +in the pointer +.IR pref . +.SH RETURN VALUE +On success, these functions return 0. +Given valid pointer arguments, +.BR pthread_rwlockattr_getkind_np () +always succeeds. +On error, +.BR pthread_rwlockattr_setkind_np () +returns a nonzero error number. +.SH ERRORS +.TP +.B EINVAL +.I pref +specifies an unsupported value. +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR pthreads (7) diff --git a/man/man3/pthread_self.3 b/man/man3/pthread_self.3 new file mode 100644 index 0000000..1d2f5ce --- /dev/null +++ b/man/man3/pthread_self.3 @@ -0,0 +1,77 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_self 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_self \- obtain ID of the calling thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.B pthread_t pthread_self(void); +.fi +.SH DESCRIPTION +The +.BR pthread_self () +function returns the ID of the calling thread. +This is the same value that is returned in +.I *thread +in the +.BR pthread_create (3) +call that created this thread. +.SH RETURN VALUE +This function always succeeds, returning the calling thread's ID. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_self () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +POSIX.1 allows an implementation wide freedom in choosing +the type used to represent a thread ID; +for example, representation using either an arithmetic type or +a structure is permitted. +Therefore, variables of type +.I pthread_t +can't portably be compared using the C equality operator (\fB==\fP); +use +.BR pthread_equal (3) +instead. +.P +Thread identifiers should be considered opaque: +any attempt to use a thread ID other than in pthreads calls +is nonportable and can lead to unspecified results. +.P +Thread IDs are guaranteed to be unique only within a process. +A thread ID may be reused after a terminated thread has been joined, +or a detached thread has terminated. +.P +The thread ID returned by +.BR pthread_self () +is not the same thing as the kernel thread ID returned by a call to +.BR gettid (2). +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_equal (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setaffinity_np.3 b/man/man3/pthread_setaffinity_np.3 new file mode 100644 index 0000000..779f389 --- /dev/null +++ b/man/man3/pthread_setaffinity_np.3 @@ -0,0 +1,207 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setaffinity_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setaffinity_np, pthread_getaffinity_np \- set/get +CPU affinity of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " const cpu_set_t *" cpuset ); +.BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " cpu_set_t *" cpuset ); +.fi +.SH DESCRIPTION +The +.BR pthread_setaffinity_np () +function +sets the CPU affinity mask of the thread +.I thread +to the CPU set pointed to by +.IR cpuset . +If the call is successful, +and the thread is not currently running on one of the CPUs in +.IR cpuset , +then it is migrated to one of those CPUs. +.P +The +.BR pthread_getaffinity_np () +function returns the CPU affinity mask of the thread +.I thread +in the buffer pointed to by +.IR cpuset . +.P +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.P +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +(It may be some other value, if using the macros described in +.BR CPU_SET (3) +for dynamically allocating a CPU set.) +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +.RB ( pthread_setaffinity_np ()) +The affinity bit mask +.I mask +contains no processors that are currently physically on the system +and permitted to the thread according to any restrictions that +may be imposed by the "cpuset" mechanism described in +.BR cpuset (7). +.TP +.B EINVAL +.RB ( pthread_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.B CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_getaffinity_np ()) +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setaffinity_np (), +.BR pthread_getaffinity_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.4. +.P +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.SH NOTES +After a call to +.BR pthread_setaffinity_np (), +the set of CPUs on which the thread will actually run is +the intersection of the set specified in the +.I cpuset +argument and the set of CPUs actually present on the system. +The system may further restrict the set of CPUs on which the thread +runs if the "cpuset" mechanism described in +.BR cpuset (7) +is being used. +These restrictions on the actual set of CPUs on which the thread +will run are silently imposed by the kernel. +.P +These functions are implemented on top of the +.BR sched_setaffinity (2) +and +.BR sched_getaffinity (2) +system calls. +.P +A new thread created by +.BR pthread_create (3) +inherits a copy of its creator's CPU affinity mask. +.SH EXAMPLES +In the following program, the main thread uses +.BR pthread_setaffinity_np () +to set its CPU affinity mask to include CPUs 0 to 7 +(which may not all be available on the system), +and then calls +.BR pthread_getaffinity_np () +to check the resulting CPU affinity mask of the thread. +.P +.\" SRC BEGIN (pthread_setaffinity_np.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + int s; + cpu_set_t cpuset; + pthread_t thread; +\& + thread = pthread_self(); +\& + /* Set affinity mask to include CPUs 0 to 7. */ +\& + CPU_ZERO(&cpuset); + for (size_t j = 0; j < 8; j++) + CPU_SET(j, &cpuset); +\& + s = pthread_setaffinity_np(thread, sizeof(cpuset), &cpuset); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_setaffinity_np"); +\& + /* Check the actual affinity mask assigned to the thread. */ +\& + s = pthread_getaffinity_np(thread, sizeof(cpuset), &cpuset); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getaffinity_np"); +\& + printf("Set returned by pthread_getaffinity_np() contained:\en"); + for (size_t j = 0; j < CPU_SETSIZE; j++) + if (CPU_ISSET(j, &cpuset)) + printf(" CPU %zu\en", j); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR CPU_SET (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_self (3), +.BR sched_getcpu (3), +.BR cpuset (7), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setattr_default_np.3 b/man/man3/pthread_setattr_default_np.3 new file mode 100644 index 0000000..1ea2ab6 --- /dev/null +++ b/man/man3/pthread_setattr_default_np.3 @@ -0,0 +1 @@ +.so man3/pthread_getattr_default_np.3 diff --git a/man/man3/pthread_setcancelstate.3 b/man/man3/pthread_setcancelstate.3 new file mode 100644 index 0000000..6b65f0f --- /dev/null +++ b/man/man3/pthread_setcancelstate.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setcancelstate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setcancelstate, pthread_setcanceltype \- +set cancelability state and type +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_setcancelstate(int " state ", int *" oldstate ); +.BI "int pthread_setcanceltype(int " type ", int *" oldtype ); +.fi +.SH DESCRIPTION +The +.BR pthread_setcancelstate () +sets the cancelability state of the calling thread to the value +given in +.IR state . +The previous cancelability state of the thread is returned +in the buffer pointed to by +.IR oldstate . +The +.I state +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_ENABLE +The thread is cancelable. +This is the default cancelability state in all new threads, +including the initial thread. +The thread's cancelability type determines when a cancelable thread +will respond to a cancelation request. +.TP +.B PTHREAD_CANCEL_DISABLE +The thread is not cancelable. +If a cancelation request is received, +it is blocked until cancelability is enabled. +.P +The +.BR pthread_setcanceltype () +sets the cancelability type of the calling thread to the value +given in +.IR type . +The previous cancelability type of the thread is returned +in the buffer pointed to by +.IR oldtype . +The +.I type +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_DEFERRED +A cancelation request is deferred until the thread next calls +a function that is a cancelation point (see +.BR pthreads (7)). +This is the default cancelability type in all new threads, +including the initial thread. +.IP +Even with deferred cancelation, a +cancelation point in an asynchronous signal handler may still +be acted upon and the effect is as if it was an asynchronous +cancelation. +.TP +.B PTHREAD_CANCEL_ASYNCHRONOUS +The thread can be canceled at any time. +(Typically, +it will be canceled immediately upon receiving a cancelation request, +but the system doesn't guarantee this.) +.P +The set-and-get operation performed by each of these functions +is atomic with respect to other threads in the process +calling the same function. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setcancelstate () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR state . +.P +The +.BR pthread_setcanceltype () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR type . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +T{ +.na +.nh +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Async-cancel safety T{ +.na +.nh +AC-Safe +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH NOTES +For details of what happens when a thread is canceled, see +.BR \%pthread_cancel (3). +.P +Briefly disabling cancelability is useful +if a thread performs some critical action +that must not be interrupted by a cancelation request. +Beware of disabling cancelability for long periods, +or around operations that may block for long periods, +since that will render the thread unresponsive to cancelation requests. +.SS Asynchronous cancelability +Setting the cancelability type to +.B PTHREAD_CANCEL_ASYNCHRONOUS +is rarely useful. +Since the thread could be canceled at +.I any +time, it cannot safely reserve resources (e.g., allocating memory with +.BR malloc (3)), +acquire mutexes, semaphores, or locks, and so on. +Reserving resources is unsafe because the application has no way of +knowing what the state of these resources is when the thread is canceled; +that is, did cancelation occur before the resources were reserved, +while they were reserved, or after they were released? +Furthermore, some internal data structures +(e.g., the linked list of free blocks managed by the +.BR malloc (3) +family of functions) may be left in an inconsistent state +if cancelation occurs in the middle of the function call. +Consequently, clean-up handlers cease to be useful. +.P +Functions that can be safely asynchronously canceled are called +.IR "async-cancel-safe functions" . +POSIX.1-2001 and POSIX.1-2008 require only that +.BR pthread_cancel (3), +.BR pthread_setcancelstate (), +and +.BR pthread_setcanceltype () +be async-cancel-safe. +In general, other library functions +can't be safely called from an asynchronously cancelable thread. +.P +One of the few circumstances in which asynchronous cancelability is useful +is for cancelation of a thread that is in a pure compute-bound loop. +.SS Portability notes +The Linux threading implementations permit the +.I oldstate +argument of +.BR pthread_setcancelstate () +to be NULL, in which case the information about the previous +cancelability state is not returned to the caller. +Many other implementations also permit a NULL +.I oldstat +argument, +.\" It looks like at least Solaris, FreeBSD and Tru64 support this. +but POSIX.1 does not specify this point, +so portable applications should always specify a non-NULL value in +.IR oldstate . +A precisely analogous set of statements applies for the +.I oldtype +argument of +.BR pthread_setcanceltype (). +.SH EXAMPLES +See +.BR pthread_cancel (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setcanceltype.3 b/man/man3/pthread_setcanceltype.3 new file mode 100644 index 0000000..9625bc2 --- /dev/null +++ b/man/man3/pthread_setcanceltype.3 @@ -0,0 +1 @@ +.so man3/pthread_setcancelstate.3 diff --git a/man/man3/pthread_setconcurrency.3 b/man/man3/pthread_setconcurrency.3 new file mode 100644 index 0000000..cee31b6 --- /dev/null +++ b/man/man3/pthread_setconcurrency.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) 2009 Michael Kerrisk, <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setconcurrency 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setconcurrency, pthread_getconcurrency \- set/get +the concurrency level +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_setconcurrency(int " new_level ); +.BI "int pthread_getconcurrency(" void ); +.fi +.SH DESCRIPTION +The +.BR pthread_setconcurrency () +function informs the implementation of the application's +desired concurrency level, specified in +.IR new_level . +The implementation takes this only as a hint: +POSIX.1 does not specify the level of concurrency that +should be provided as a result of calling +.BR pthread_setconcurrency (). +.P +Specifying +.I new_level +as 0 instructs the implementation to manage the concurrency level +as it deems appropriate. +.P +.BR pthread_getconcurrency () +returns the current value of the concurrency level for this process. +.SH RETURN VALUE +On success, +.BR pthread_setconcurrency () +returns 0; +on error, it returns a nonzero error number. +.P +.BR pthread_getconcurrency () +always succeeds, returning the concurrency level set by a previous call to +.BR pthread_setconcurrency (), +or 0, if +.BR pthread_setconcurrency () +has not previously been called. +.SH ERRORS +.BR pthread_setconcurrency () +can fail with the following error: +.TP +.B EINVAL +.I new_level +is negative. +.P +POSIX.1 also documents an +.B EAGAIN +error ("the value specified by +.I new_level +would cause a system resource to be exceeded"). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setconcurrency (), +.BR pthread_getconcurrency () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +The default concurrency level is 0. +.P +Concurrency levels are meaningful only for M:N threading implementations, +where at any moment a subset of a process's set of user-level threads +may be bound to a smaller number of kernel-scheduling entities. +Setting the concurrency level allows the application to +give the system a hint as to the number of kernel-scheduling entities +that should be provided for efficient execution of the application. +.P +Both LinuxThreads and NPTL are 1:1 threading implementations, +so setting the concurrency level has no meaning. +In other words, +on Linux these functions merely exist for compatibility with other systems, +and they have no effect on the execution of a program. +.SH SEE ALSO +.BR pthread_attr_setscope (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setname_np.3 b/man/man3/pthread_setname_np.3 new file mode 100644 index 0000000..b426d51 --- /dev/null +++ b/man/man3/pthread_setname_np.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2012 Chandan Apsangi <chandan.jc@gmail.com> +.\" and Copyright (C) 2013 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setname_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setname_np, pthread_getname_np \- set/get the name of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_setname_np(pthread_t " thread ", const char *" name ); +.BI "int pthread_getname_np(pthread_t " thread ", char " name [. size "], \ +size_t " size ); +.fi +.SH DESCRIPTION +By default, all the threads created using +.BR pthread_create () +inherit the program name. +The +.BR pthread_setname_np () +function can be used to set a unique name for a thread, +which can be useful for debugging +multithreaded applications. +The thread name is a meaningful C language string, +whose length is restricted to 16 characters, +including the terminating null byte (\[aq]\e0\[aq]). +The +.I thread +argument specifies the thread whose name is to be changed; +.I name +specifies the new name. +.P +The +.BR pthread_getname_np () +function can be used to retrieve the name of the thread. +The +.I thread +argument specifies the thread whose name is to be retrieved. +The buffer +.I name +is used to return the thread name; +.I size +specifies the number of bytes available in +.IR name . +The buffer specified by +.I name +should be at least 16 characters in length. +The returned thread name in the output buffer will be null terminated. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setname_np () +function can fail with the following error: +.TP +.B ERANGE +The length of the string specified pointed to by +.I name +exceeds the allowed limit. +.P +The +.BR pthread_getname_np () +function can fail with the following error: +.TP +.B ERANGE +The buffer specified by +.I name +and +.I size +is too small to hold the thread name. +.P +If either of these functions fails to open +.IR /proc/self/task/ tid /comm , +then the call may fail with one of the errors described in +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setname_np (), +.BR pthread_getname_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.12. +.SH NOTES +.BR pthread_setname_np () +internally writes to the thread-specific +.I comm +file under the +.I /proc +filesystem: +.IR /proc/self/task/ tid /comm . +.BR pthread_getname_np () +retrieves it from the same location. +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_setname_np () +and +.BR pthread_getname_np (). +.P +The following shell session shows a sample run of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out" +Created a thread. Default name is: a.out +The thread name after setting it is THREADFOO. +\fB\[ha]Z\fP # Suspend the program +[1]+ Stopped ./a.out +.RB "$ " "ps H \-C a.out \-o \[aq]pid tid cmd comm\[aq]" + PID TID CMD COMMAND + 5990 5990 ./a.out a.out + 5990 5991 ./a.out THREADFOO +.RB "$ " "cat /proc/5990/task/5990/comm" +a.out +.RB "$ " "cat /proc/5990/task/5991/comm" +THREADFOO +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_setname_np.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> +\& +#define NAMELEN 16 +\& +static void * +threadfunc(void *parm) +{ + sleep(5); // allow main program to set the thread name + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thread; + int rc; + char thread_name[NAMELEN]; +\& + rc = pthread_create(&thread, NULL, threadfunc, NULL); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_create"); +\& + rc = pthread_getname_np(thread, thread_name, NAMELEN); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_getname_np"); +\& + printf("Created a thread. Default name is: %s\en", thread_name); + rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO"); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_setname_np"); +\& + sleep(2); +\& + rc = pthread_getname_np(thread, thread_name, NAMELEN); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_getname_np"); + printf("The thread name after setting it is %s.\en", thread_name); +\& + rc = pthread_join(thread, NULL); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_join"); +\& + printf("Done\en"); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR prctl (2), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setschedparam.3 b/man/man3/pthread_setschedparam.3 new file mode 100644 index 0000000..f212f33 --- /dev/null +++ b/man/man3/pthread_setschedparam.3 @@ -0,0 +1,448 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setschedparam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setschedparam, pthread_getschedparam \- set/get +scheduling policy and parameters of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_setschedparam(pthread_t " thread ", int " policy , +.BI " const struct sched_param *" param ); +.BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy , +.BI " struct sched_param *restrict " param ); +.fi +.SH DESCRIPTION +The +.BR pthread_setschedparam () +function sets the scheduling policy and parameters of the thread +.IR thread . +.P +.I policy +specifies the new scheduling policy for +.IR thread . +The supported values for +.IR policy , +and their semantics, are described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.P +The structure pointed to by +.I param +specifies the new scheduling parameters for +.IR thread . +Scheduling parameters are maintained in the following structure: +.P +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.P +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.P +The +.BR pthread_getschedparam () +function returns the scheduling policy and parameters of the thread +.IR thread , +in the buffers pointed to by +.I policy +and +.IR param , +respectively. +The returned priority value is that set by the most recent +.BR pthread_setschedparam (), +.BR pthread_setschedprio (3), +or +.BR pthread_create (3) +call that affected +.IR thread . +The returned priority does not reflect any temporary priority adjustments +as a result of calls to any priority inheritance or +priority ceiling functions (see, for example, +.BR pthread_mutexattr_setprioceiling (3) +and +.BR pthread_mutexattr_setprotocol (3)). +.\" FIXME . nptl/pthread_setschedparam.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +If +.BR pthread_setschedparam () +fails, the scheduling policy and parameters of +.I thread +are not changed. +.SH ERRORS +Both of these functions can fail with the following error: +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.P +.BR pthread_setschedparam () +may additionally fail with the following errors: +.TP +.B EINVAL +.I policy +is not a recognized policy, or +.I param +does not make sense for the +.IR policy . +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified scheduling policy and parameters. +.P +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the policy or scheduling parameters +to an unsupported value") error for +.BR pthread_setschedparam (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setschedparam (), +.BR pthread_getschedparam () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling policy and priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_setschedparam () +and +.BR pthread_getschedparam (), +as well as the use of a number of other scheduling-related +pthreads functions. +.P +In the following run, the main thread sets its scheduling policy to +.B SCHED_FIFO +with a priority of 10, +and initializes a thread attributes object with +a scheduling policy attribute of +.B SCHED_RR +and a scheduling priority attribute of 20. +The program then sets (using +.BR pthread_attr_setinheritsched (3)) +the inherit scheduler attribute of the thread attributes object to +.BR PTHREAD_EXPLICIT_SCHED , +meaning that threads created using this attributes object should +take their scheduling attributes from the thread attributes object. +The program then creates a thread using the thread attributes object, +and that thread displays its scheduling policy and priority. +.P +.in +4n +.EX +$ \fBsu\fP # Need privilege to set real\-time scheduling policies +Password: +# \fB./a.out \-mf10 \-ar20 \-i e\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 +\& +Scheduler settings in \[aq]attr\[aq] + policy=SCHED_RR, priority=20 + inheritsched is EXPLICIT +\& +Scheduler attributes of new thread + policy=SCHED_RR, priority=20 +.EE +.in +.P +In the above output, one can see that the scheduling policy and priority +were taken from the values specified in the thread attributes object. +.P +The next run is the same as the previous, +except that the inherit scheduler attribute is set to +.BR PTHREAD_INHERIT_SCHED , +meaning that threads created using the thread attributes object should +ignore the scheduling attributes specified in the attributes object +and instead take their scheduling attributes from the creating thread. +.P +.in +4n +.EX +# \fB./a.out \-mf10 \-ar20 \-i i\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 +\& +Scheduler settings in \[aq]attr\[aq] + policy=SCHED_RR, priority=20 + inheritsched is INHERIT +\& +Scheduler attributes of new thread + policy=SCHED_FIFO, priority=10 +.EE +.in +.P +In the above output, one can see that the scheduling policy and priority +were taken from the creating thread, +rather than the thread attributes object. +.P +Note that if we had omitted the +.I \-i\~i +option, the output would have been the same, since +.B PTHREAD_INHERIT_SCHED +is the default for the inherit scheduler attribute. +.SS Program source +\& +.\" SRC BEGIN (pthreads_sched_test.c) +.EX +/* pthreads_sched_test.c */ +\& +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +[[noreturn]] +static void +usage(char *prog_name, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); +\& + fprintf(stderr, "Usage: %s [options]\en", prog_name); + fprintf(stderr, "Options are:\en"); +#define fpe(msg) fprintf(stderr, "\et%s", msg) /* Shorter */ + fpe("\-a<policy><prio> Set scheduling policy and priority in\en"); + fpe(" thread attributes object\en"); + fpe(" <policy> can be\en"); + fpe(" f SCHED_FIFO\en"); + fpe(" r SCHED_RR\en"); + fpe(" o SCHED_OTHER\en"); + fpe("\-A Use default thread attributes object\en"); + fpe("\-i {e|i} Set inherit scheduler attribute to\en"); + fpe(" \[aq]explicit\[aq] or \[aq]inherit\[aq]\en"); + fpe("\-m<policy><prio> Set scheduling policy and priority on\en"); + fpe(" main thread before pthread_create() call\en"); + exit(EXIT_FAILURE); +} +\& +static int +get_policy(char p, int *policy) +{ + switch (p) { + case \[aq]f\[aq]: *policy = SCHED_FIFO; return 1; + case \[aq]r\[aq]: *policy = SCHED_RR; return 1; + case \[aq]o\[aq]: *policy = SCHED_OTHER; return 1; + default: return 0; + } +} +\& +static void +display_sched_attr(int policy, const struct sched_param *param) +{ + printf(" policy=%s, priority=%d\en", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : + "???", + param\->sched_priority); +} +\& +static void +display_thread_sched_attr(char *msg) +{ + int policy, s; + struct sched_param param; +\& + s = pthread_getschedparam(pthread_self(), &policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_getschedparam"); +\& + printf("%s\en", msg); + display_sched_attr(policy, ¶m); +} +\& +static void * +thread_start(void *arg) +{ + display_thread_sched_attr("Scheduler attributes of new thread"); +\& + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + int s, opt, inheritsched, use_null_attrib, policy; + pthread_t thread; + pthread_attr_t attr; + pthread_attr_t *attrp; + char *attr_sched_str, *main_sched_str, *inheritsched_str; + struct sched_param param; +\& + /* Process command\-line options. */ +\& + use_null_attrib = 0; + attr_sched_str = NULL; + main_sched_str = NULL; + inheritsched_str = NULL; +\& + while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) { + switch (opt) { + case \[aq]a\[aq]: attr_sched_str = optarg; break; + case \[aq]A\[aq]: use_null_attrib = 1; break; + case \[aq]i\[aq]: inheritsched_str = optarg; break; + case \[aq]m\[aq]: main_sched_str = optarg; break; + default: usage(argv[0], "Unrecognized option\en"); + } + } +\& + if (use_null_attrib + && (inheritsched_str != NULL || attr_sched_str != NULL)) + { + usage(argv[0], "Can\[aq]t specify \-A with \-i or \-a\en"); + } +\& + /* Optionally set scheduling attributes of main thread, + and display the attributes. */ +\& + if (main_sched_str != NULL) { + if (!get_policy(main_sched_str[0], &policy)) + usage(argv[0], "Bad policy for main thread (\-m)\en"); + param.sched_priority = strtol(&main_sched_str[1], NULL, 0); +\& + s = pthread_setschedparam(pthread_self(), policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_setschedparam"); + } +\& + display_thread_sched_attr("Scheduler settings of main thread"); + printf("\en"); +\& + /* Initialize thread attributes object according to options. */ +\& + attrp = NULL; +\& + if (!use_null_attrib) { + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + attrp = &attr; + } +\& + if (inheritsched_str != NULL) { + if (inheritsched_str[0] == \[aq]e\[aq]) + inheritsched = PTHREAD_EXPLICIT_SCHED; + else if (inheritsched_str[0] == \[aq]i\[aq]) + inheritsched = PTHREAD_INHERIT_SCHED; + else + usage(argv[0], "Value for \-i must be \[aq]e\[aq] or \[aq]i\[aq]\en"); +\& + s = pthread_attr_setinheritsched(&attr, inheritsched); + if (s != 0) + handle_error_en(s, "pthread_attr_setinheritsched"); + } +\& + if (attr_sched_str != NULL) { + if (!get_policy(attr_sched_str[0], &policy)) + usage(argv[0], "Bad policy for \[aq]attr\[aq] (\-a)\en"); + param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); +\& + s = pthread_attr_setschedpolicy(&attr, policy); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedpolicy"); + s = pthread_attr_setschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedparam"); + } +\& + /* If we initialized a thread attributes object, display + the scheduling attributes that were set in the object. */ +\& + if (attrp != NULL) { + s = pthread_attr_getschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedparam"); + s = pthread_attr_getschedpolicy(&attr, &policy); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedpolicy"); +\& + printf("Scheduler settings in \[aq]attr\[aq]\en"); + display_sched_attr(policy, ¶m); +\& + pthread_attr_getinheritsched(&attr, &inheritsched); + printf(" inheritsched is %s\en", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); + printf("\en"); + } +\& + /* Create a thread that will display its scheduling attributes. */ +\& + s = pthread_create(&thread, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + /* Destroy unneeded thread attributes object. */ +\& + if (!use_null_attrib) { + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } +\& + s = pthread_join(thread, NULL); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setschedprio.3 b/man/man3/pthread_setschedprio.3 new file mode 100644 index 0000000..668d1ec --- /dev/null +++ b/man/man3/pthread_setschedprio.3 @@ -0,0 +1,101 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setschedprio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setschedprio \- set scheduling priority of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_setschedprio(pthread_t " thread ", int " prio ); +.fi +.SH DESCRIPTION +The +.BR pthread_setschedprio () +function sets the scheduling priority of the thread +.I thread +to the value specified in +.IR prio . +(By contrast +.BR pthread_setschedparam (3) +changes both the scheduling policy and priority of a thread.) +.\" FIXME . nptl/pthread_setschedprio.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.\" nptl/pthread_setschedparam.c has a similar case. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +If +.BR pthread_setschedprio () +fails, the scheduling priority of +.I thread +is not changed. +.SH ERRORS +.TP +.B EINVAL +.I prio +is not valid for the scheduling policy of the specified thread. +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified priority. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.P +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the priority +to an unsupported value") error for +.BR pthread_setschedparam (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setschedprio () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3.4. +POSIX.1-2001. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedparam (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setspecific.3 b/man/man3/pthread_setspecific.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_setspecific.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_sigmask.3 b/man/man3/pthread_sigmask.3 new file mode 100644 index 0000000..810edf3 --- /dev/null +++ b/man/man3/pthread_sigmask.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_sigmask 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_sigmask \- examine and change mask of blocked signals +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int pthread_sigmask(int " how ", const sigset_t *" set \ +", sigset_t *" oldset ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_sigmask (): +.nf + _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +The +.BR pthread_sigmask () +function is just like +.BR sigprocmask (2), +with the difference that its use in multithreaded programs +is explicitly specified by POSIX.1. +Other differences are noted in this page. +.P +For a description of the arguments and operation of this function, see +.BR sigprocmask (2). +.SH RETURN VALUE +On success, +.BR pthread_sigmask () +returns 0; +on error, it returns an error number. +.SH ERRORS +See +.BR sigprocmask (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_sigmask () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +A new thread inherits a copy of its creator's signal mask. +.P +The glibc +.BR pthread_sigmask () +function silently ignores attempts to block the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH EXAMPLES +The program below blocks some signals in the main thread, +and then creates a dedicated thread to fetch those signals via +.BR sigwait (3). +The following shell session demonstrates its use: +.P +.in +4n +.EX +.RB "$" " ./a.out &" +[1] 5423 +.RB "$" " kill \-QUIT %1" +Signal handling thread got signal 3 +.RB "$" " kill \-USR1 %1" +Signal handling thread got signal 10 +.RB "$" " kill \-TERM %1" +[1]+ Terminated ./a.out +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_sigmask.c) +.EX +#include <errno.h> +#include <pthread.h> +#include <signal.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +/* Simple error handling functions */ +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +sig_thread(void *arg) +{ + sigset_t *set = arg; + int s, sig; +\& + for (;;) { + s = sigwait(set, &sig); + if (s != 0) + handle_error_en(s, "sigwait"); + printf("Signal handling thread got signal %d\en", sig); + } +} +\& +int +main(void) +{ + pthread_t thread; + sigset_t set; + int s; +\& + /* Block SIGQUIT and SIGUSR1; other threads created by main() + will inherit a copy of the signal mask. */ +\& + sigemptyset(&set); + sigaddset(&set, SIGQUIT); + sigaddset(&set, SIGUSR1); + s = pthread_sigmask(SIG_BLOCK, &set, NULL); + if (s != 0) + handle_error_en(s, "pthread_sigmask"); +\& + s = pthread_create(&thread, NULL, &sig_thread, &set); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + /* Main thread carries on to create other threads and/or do + other work. */ +\& + pause(); /* Dummy pause so we can test program */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR pthread_attr_setsigmask_np (3), +.BR pthread_create (3), +.BR pthread_kill (3), +.BR sigsetops (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_sigqueue.3 b/man/man3/pthread_sigqueue.3 new file mode 100644 index 0000000..32e234a --- /dev/null +++ b/man/man3/pthread_sigqueue.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright (c) 2010 Michael Kerrisk, <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_sigqueue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_sigqueue \- queue a signal and data to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.B #include <pthread.h> +.P +.BI "int pthread_sigqueue(pthread_t " thread ", int " sig , +.BI " const union sigval " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_sigqueue (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR pthread_sigqueue () +function performs a similar task to +.BR sigqueue (3), +but, rather than sending a signal to a process, +it sends a signal to a thread in the same process as the +calling thread. +.P +The +.I thread +argument is the ID of a thread in the same process as the caller. +The +.I sig +argument specifies the signal to be sent. +The +.I value +argument specifies data to accompany the signal; see +.BR sigqueue (3) +for details. +.SH RETURN VALUE +On success, +.BR pthread_sigqueue () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B ENOSYS +.BR pthread_sigqueue () +is not supported on this system. +.TP +.B ESRCH +.I thread +is not valid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_sigqueue () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc implementation of +.BR pthread_sigqueue () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.11. +.SH SEE ALSO +.BR rt_tgsigqueueinfo (2), +.BR sigaction (2), +.BR pthread_sigmask (3), +.BR sigqueue (3), +.BR sigwait (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_spin_destroy.3 b/man/man3/pthread_spin_destroy.3 new file mode 100644 index 0000000..f19c345 --- /dev/null +++ b/man/man3/pthread_spin_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_init.3 diff --git a/man/man3/pthread_spin_init.3 b/man/man3/pthread_spin_init.3 new file mode 100644 index 0000000..74b6414 --- /dev/null +++ b/man/man3/pthread_spin_init.3 @@ -0,0 +1,148 @@ +.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_spin_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");" +.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_spin_init (), +.BR pthread_spin_destroy (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.IR "General note" : +Most programs should use mutexes +instead of spin locks. +Spin locks are primarily useful in conjunction with real-time +scheduling policies. +See NOTES. +.P +The +.BR pthread_spin_init () +function allocates any resources required for the use of +the spin lock referred to by +.I lock +and initializes the lock to be in the unlocked state. +The +.I pshared +argument must have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +The spin lock is to be operated on only by threads in the same process +as the thread that calls +.BR pthread_spin_init (). +(Attempting to share the spin lock between processes +results in undefined behavior.) +.TP +.B PTHREAD_PROCESS_SHARED +The spin lock may be operated on by any thread in any process that +has access to the memory containing the lock +(i.e., the lock may be in a shared memory object that is +shared among multiple processes). +.P +Calling +.BR pthread_spin_init () +on a spin lock that has already been initialized results +in undefined behavior. +.P +The +.BR pthread_spin_destroy () +function destroys a previously initialized spin lock, +freeing any resources that were allocated for that lock. +Destroying a spin lock that has not been previously been initialized +or destroying a spin lock while another thread holds the lock +results in undefined behavior. +.P +Once a spin lock has been destroyed, +performing any operation on the lock other than +once more initializing it with +.BR pthread_spin_init () +results in undefined behavior. +.P +The result of performing operations such as +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +and +.BR pthread_spin_destroy () +on +.I copies +of the object referred to by +.I lock +is undefined. +.SH RETURN VALUE +On success, there functions return zero. +On failure, they return an error number. +In the event that +.BR pthread_spin_init () +fails, the lock is not initialized. +.SH ERRORS +.BR pthread_spin_init () +may fail with the following errors: +.\" These errors don't occur on the glibc implementation +.TP +.B EAGAIN +The system has insufficient resources to initialize +a new spin lock. +.TP +.B ENOMEM +Insufficient memory to initialize the spin lock. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.P +Support for process-shared spin locks is a POSIX option. +The option is supported in the glibc implementation. +.SH NOTES +Spin locks should be employed in conjunction with +real-time scheduling policies +.RB ( SCHED_FIFO , +or possibly +.BR SCHED_RR ). +Use of spin locks with nondeterministic scheduling policies such as +.B SCHED_OTHER +probably indicates a design mistake. +The problem is that if a thread operating under such a policy +is scheduled off the CPU while it holds a spin lock, +then other threads will waste time spinning on the lock +until the lock holder is once more rescheduled and releases the lock. +.P +If threads create a deadlock situation while employing spin locks, +those threads will spin forever consuming CPU time. +.P +User-space spin locks are +.I not +applicable as a general locking solution. +They are, by definition, +prone to priority inversion and unbounded spin times. +A programmer using spin locks must be exceptionally careful not +only in the code, but also in terms of system configuration, +thread placement, and priority assignment. +.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document +.\" make reference to it here +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutex_lock (3), +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +.BR pthreads (7) diff --git a/man/man3/pthread_spin_lock.3 b/man/man3/pthread_spin_lock.3 new file mode 100644 index 0000000..56c31da --- /dev/null +++ b/man/man3/pthread_spin_lock.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_spin_lock 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \- +lock and unlock a spin lock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_spin_lock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_trylock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_unlock(pthread_spinlock_t *" lock ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_spin_lock (), +.BR pthread_spin_trylock (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR pthread_spin_lock () +function locks the spin lock referred to by +.IR lock . +If the spin lock is currently unlocked, +the calling thread acquires the lock immediately. +If the spin lock is currently locked by another thread, +the calling thread spins, testing the lock until it becomes available, +at which point the calling thread acquires the lock. +.P +Calling +.BR pthread_spin_lock () +on a lock that is already held by the caller +or a lock that has not been initialized with +.BR pthread_spin_init (3) +results in undefined behavior. +.P +The +.BR pthread_spin_trylock () +function is like +.BR pthread_spin_lock (), +except that if the spin lock referred to by +.I lock +is currently locked, +then, instead of spinning, the call returns immediately with the error +.BR EBUSY . +.P +The +.BR pthread_spin_unlock () +function unlocks the spin lock referred to +.IR lock . +If any threads are spinning on the lock, +one of those threads will then acquire the lock. +.P +Calling +.BR pthread_spin_unlock () +on a lock that is not held by the caller results in undefined behavior. +.SH RETURN VALUE +On success, these functions return zero. +On failure, they return an error number. +.SH ERRORS +.BR pthread_spin_lock () +may fail with the following errors: +.TP +.B EDEADLOCK +.\" Not detected in glibc +The system detected a deadlock condition. +.P +.BR pthread_spin_trylock () +fails with the following errors: +.TP +.B EBUSY +The spin lock is currently locked by another thread. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH CAVEATS +Applying any of the functions described on this page to +an uninitialized spin lock results in undefined behavior. +.P +Carefully read NOTES in +.BR pthread_spin_init (3). +.SH SEE ALSO +.ad l +.nh +.\" FIXME . .BR pthread_mutex_lock (3), +.BR pthread_spin_destroy (3), +.BR pthread_spin_init (3), +.BR pthreads (7) diff --git a/man/man3/pthread_spin_trylock.3 b/man/man3/pthread_spin_trylock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man/man3/pthread_spin_trylock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man/man3/pthread_spin_unlock.3 b/man/man3/pthread_spin_unlock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man/man3/pthread_spin_unlock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man/man3/pthread_testcancel.3 b/man/man3/pthread_testcancel.3 new file mode 100644 index 0000000..b1ce9fa --- /dev/null +++ b/man/man3/pthread_testcancel.3 @@ -0,0 +1,64 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_testcancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_testcancel \- request delivery of any pending cancelation request +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.B void pthread_testcancel(void); +.fi +.SH DESCRIPTION +Calling +.BR pthread_testcancel () +creates a cancelation point within the calling thread, +so that a thread that is otherwise executing code that contains +no cancelation points will respond to a cancelation request. +.P +If cancelability is disabled (using +.BR pthread_setcancelstate (3)), +or no cancelation request is pending, +then a call to +.BR pthread_testcancel () +has no effect. +.SH RETURN VALUE +This function does not return a value. +If the calling thread is canceled as a consequence of a call +to this function, then the function does not return. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_testcancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_cleanup_push (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthreads (7) diff --git a/man/man3/pthread_timedjoin_np.3 b/man/man3/pthread_timedjoin_np.3 new file mode 100644 index 0000000..a741f46 --- /dev/null +++ b/man/man3/pthread_timedjoin_np.3 @@ -0,0 +1 @@ +.so man3/pthread_tryjoin_np.3 diff --git a/man/man3/pthread_tryjoin_np.3 b/man/man3/pthread_tryjoin_np.3 new file mode 100644 index 0000000..3e2a32a --- /dev/null +++ b/man/man3/pthread_tryjoin_np.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_tryjoin_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_tryjoin_np, pthread_timedjoin_np \- try to join with a +terminated thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval ); +.BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval , +.BI " const struct timespec *" abstime ); +.fi +.SH DESCRIPTION +These functions operate in the same way as +.BR pthread_join (3), +except for the differences described on this page. +.P +The +.BR pthread_tryjoin_np () +function performs a nonblocking join with the thread +.IR thread , +returning the exit status of the thread in +.IR *retval . +If +.I thread +has not yet terminated, then instead of blocking, as is done by +.BR pthread_join (3), +the call returns an error. +.P +The +.BR pthread_timedjoin_np () +function performs a join-with-timeout. +If +.I thread +has not yet terminated, +then the call blocks until a maximum time, specified in +.IR abstime , +measured against the +.B CLOCK_REALTIME +clock. +If the timeout expires before +.I thread +terminates, +the call returns an error. +The +.I abstime +argument is a +.BR timespec (3) +structure, +specifying an absolute time measured since the Epoch (see +.BR time (2)). +.SH RETURN VALUE +On success, +these functions return 0; +on error, they return an error number. +.SH ERRORS +These functions can fail with the same errors as +.BR pthread_join (3). +.BR pthread_tryjoin_np () +can in addition fail with the following error: +.TP +.B EBUSY +.I thread +had not yet terminated at the time of the call. +.P +.BR pthread_timedjoin_np () +can in addition fail with the following errors: +.TP +.B EINVAL +.I abstime +value is invalid +.RI ( tv_sec +is less than 0 or +.I tv_nsec +is greater than 1e9). +.TP +.B ETIMEDOUT +The call timed out before +.I thread +terminated. +.P +.BR pthread_timedjoin_np () +never returns the error +.BR EINTR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_tryjoin_np (), +.BR pthread_timedjoin_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.3. +.SH BUGS +The +.BR pthread_timedjoin_np () +function measures time by internally calculating a relative sleep interval +that is then measured against the +.B CLOCK_MONOTONIC +clock instead of the +.B CLOCK_REALTIME +clock. +Consequently, the timeout is unaffected by discontinuous changes to the +.B CLOCK_REALTIME +clock. +.SH EXAMPLES +The following code waits to join for up to 5 seconds: +.P +.in +4n +.EX +struct timespec ts; +int s; +\& +\&... +\& +if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) { + /* Handle error */ +} +\& +ts.tv_sec += 5; +\& +s = pthread_timedjoin_np(thread, NULL, &ts); +if (s != 0) { + /* Handle error */ +} +.EE +.in +.SH SEE ALSO +.BR clock_gettime (2), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR timespec (3), +.BR pthreads (7) diff --git a/man/man3/pthread_yield.3 b/man/man3/pthread_yield.3 new file mode 100644 index 0000000..14ff6b5 --- /dev/null +++ b/man/man3/pthread_yield.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) 2009 Michael Kerrisk, <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_yield 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_yield \- yield the processor +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <pthread.h> +.P +.B [[deprecated]] int pthread_yield(void); +.fi +.SH DESCRIPTION +.BR Note : +This function is deprecated; see below. +.P +.BR pthread_yield () +causes the calling thread to relinquish the CPU. +The thread is placed at the end of the run queue for its static +priority and another thread is scheduled to run. +For further details, see +.BR sched_yield (2) +.SH RETURN VALUE +On success, +.BR pthread_yield () +returns 0; +on error, it returns an error number. +.SH ERRORS +On Linux, this call always succeeds +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_yield () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, this function is implemented as a call to +.BR sched_yield (2). +.SH STANDARDS +None. +.SH HISTORY +.\" BSD, Tru64, AIX, and Irix. +Deprecated since glibc 2.34. +Use the standardized +.BR sched_yield (2) +instead. +.SH NOTES +.BR pthread_yield () +is intended for use with real-time scheduling policies (i.e., +.B SCHED_FIFO +or +.BR SCHED_RR ). +Use of +.BR pthread_yield () +with nondeterministic scheduling policies such as +.B SCHED_OTHER +is unspecified and very likely means your application design is broken. +.SH SEE ALSO +.BR sched_yield (2), +.\" FIXME . .BR pthread_cond_wait (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/ptsname.3 b/man/man3/ptsname.3 new file mode 100644 index 0000000..14cad01 --- /dev/null +++ b/man/man3/ptsname.3 @@ -0,0 +1,146 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS +.\" +.TH ptsname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ptsname, ptsname_r \- get the name of the slave pseudoterminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "char *ptsname(int " fd ); +.BI "int ptsname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ptsname (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.P +.BR ptsname_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR ptsname () +function returns the name of the slave pseudoterminal device +corresponding to the master referred to by the file descriptor +.IR fd . +.P +The +.BR ptsname_r () +function is the reentrant equivalent of +.BR ptsname (). +It returns the name of the slave pseudoterminal device as a +null-terminated string in the buffer pointed to by +.IR buf . +The +.I buflen +argument specifies the number of bytes available in +.IR buf . +.SH RETURN VALUE +On success, +.BR ptsname () +returns a pointer to a string in static storage which will be +overwritten by subsequent calls. +This pointer must not be freed. +On failure, NULL is returned. +.P +On success, +.BR ptsname_r () +returns 0. +On failure, an error number is returned to indicate the error. +.\" In glibc, the error number is not only returned as the return value +.\" but also stored in errno. But this is not true for musl libc. +.SH ERRORS +.TP +.B EINVAL +.RB ( ptsname_r () +only) +.I buf +is NULL. +(This error is returned only for +.\" glibc commit 8f0a947cf55f3b0c4ebdf06953c57eff67a22fa9 +glibc 2.25 and earlier.) +.TP +.B ENOTTY +.I fd +does not refer to a pseudoterminal master device. +.TP +.B ERANGE +.RB ( ptsname_r () +only) +.I buf +is too small. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ptsname () +T} Thread safety MT-Unsafe race:ptsname +T{ +.na +.nh +.BR ptsname_r () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +A version of +.BR ptsname_r () +is documented on Tru64 and HP-UX, +but on those implementations, +\-1 is returned on error, with +.I errno +set to indicate the error. +Avoid using this function in portable programs. +.SH STANDARDS +.TP +.BR ptsname (): +POSIX.1-2008. +.P +.BR ptsname_r () +is a Linux extension, that is proposed for inclusion +.\" FIXME . for later review when Issue 8 is one day released +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +in the next major revision of POSIX.1 (Issue 8). +.SH HISTORY +.TP +.BR ptsname (): +POSIX.1-2001. +glibc 2.1. +.P +.BR ptsname () +is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ttyname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/ptsname_r.3 b/man/man3/ptsname_r.3 new file mode 100644 index 0000000..0a5f98d --- /dev/null +++ b/man/man3/ptsname_r.3 @@ -0,0 +1 @@ +.so man3/ptsname.3 diff --git a/man/man3/putc.3 b/man/man3/putc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/putc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/putc_unlocked.3 b/man/man3/putc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putchar.3 b/man/man3/putchar.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/putchar.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/putchar_unlocked.3 b/man/man3/putchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putenv.3 b/man/man3/putenv.3 new file mode 100644 index 0000000..fd6bc81 --- /dev/null +++ b/man/man3/putenv.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Single UNIX Specification, Version 2 +.\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe +.\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl) +.TH putenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putenv \- change or add an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int putenv(char *" string ); +.\" Not: const char * +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR putenv (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR putenv () +function adds or changes the value of environment +variables. +The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. +If \fIname\fP does not already exist in the environment, then +\fIstring\fP is added to the environment. +If \fIname\fP does exist, +then the value of \fIname\fP in the environment is changed to +\fIvalue\fP. +The string pointed to by \fIstring\fP becomes part of the environment, +so altering the string changes the environment. +.SH RETURN VALUE +The +.BR putenv () +function returns zero on success. +On failure, it returns a nonzero value, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient space to allocate new environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr2, 4.3BSD-Reno. +.P +The +.BR putenv () +function is not required to be reentrant, and the +one in glibc 2.0 is not, but the glibc 2.1 version is. +.\" .P +.\" Description for libc4, libc5, glibc: +.\" If the argument \fIstring\fP is of the form \fIname\fP, +.\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP +.\" is removed from the environment. +.\" If +.\" .BR putenv () +.\" has to allocate a new array \fIenviron\fP, +.\" and the previous array was also allocated by +.\" .BR putenv (), +.\" then it will be freed. +.\" In no case will the old storage associated +.\" to the environment variable itself be freed. +.P +Since glibc 2.1.2, the glibc implementation conforms to SUSv2: +the pointer \fIstring\fP given to +.BR putenv () +is used. +In particular, this string becomes part of the environment; +changing it later will change the environment. +(Thus, it is an error to call +.BR putenv () +with an automatic variable +as the argument, then return from the calling function while \fIstring\fP +is still part of the environment.) +However, from glibc 2.0 to glibc 2.1.1, it differs: +a copy of the string is used. +On the one hand this causes a memory leak, and on the other hand +it violates SUSv2. +.P +The 4.3BSD-Reno version, like glibc 2.0, uses a copy; +this is fixed in all modern BSDs. +.P +SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3. +.P +The GNU C library implementation provides a nonstandard extension. +If +.I string +does not include an equal sign: +.P +.in +4n +.EX +putenv("NAME"); +.EE +.in +.P +then the named variable is removed from the caller's environment. +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) diff --git a/man/man3/putgrent.3 b/man/man3/putgrent.3 new file mode 100644 index 0000000..6437698 --- /dev/null +++ b/man/man3/putgrent.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH putgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putgrent \- write a group database entry to a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <grp.h> +.P +.BI "int putgrent(const struct group *restrict " grp \ +", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR putgrent () +function is the counterpart for +.BR fgetgrent (3). +The function writes the content of the provided +.I struct group +into the +.IR stream . +The list of group members must be NULL-terminated or NULL-initialized. +.P +The +.I struct group +is defined as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* group members */ +}; +.EE +.in +.SH RETURN VALUE +The function returns zero on success, and a nonzero value on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putgrent () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR group (5) diff --git a/man/man3/putpwent.3 b/man/man3/putpwent.3 new file mode 100644 index 0000000..6742b79 --- /dev/null +++ b/man/man3/putpwent.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:43:46 1993 by Rik Faith (faith@cs.unc.edu) +.TH putpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putpwent \- write a password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <sys/types.h> +.B #include <pwd.h> +.P +.BI "int putpwent(const struct passwd *restrict " p \ +", FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR putpwent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR putpwent () +function writes a password entry from the +structure \fIp\fP in the file associated with \fIstream\fP. +.P +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR putpwent () +function returns 0 on success. +On failure, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid (NULL) argument given. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putpwent () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR setpwent (3) diff --git a/man/man3/puts.3 b/man/man3/puts.3 new file mode 100644 index 0000000..5724f62 --- /dev/null +++ b/man/man3/puts.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:42:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH puts 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputc, fputs, putc, putchar, puts \- output of characters and strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int fputc(int " c ", FILE *" stream ); +.BI "int putc(int " c ", FILE *" stream ); +.BI "int putchar(int " c ); +.P +.BI "int fputs(const char *restrict " s ", FILE *restrict " stream ); +.BI "int puts(const char *" s ); +.fi +.SH DESCRIPTION +.BR fputc () +writes the character +.IR c , +cast to an +.IR "unsigned char" , +to +.IR stream . +.P +.BR putc () +is equivalent to +.BR fputc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.P +.BI "putchar(" c ) +is equivalent to +.BI "putc(" c ", " stdout ) \fR. +.P +.BR fputs () +writes the string +.I s +to +.IR stream , +without its terminating null byte (\[aq]\e0\[aq]). +.P +.BR puts () +writes the string +.I s +and a trailing newline +to +.IR stdout . +.P +Calls to the functions described here can be mixed with each other and with +calls to other output functions from the +.I stdio +library for the same output stream. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fputc (), +.BR putc (), +and +.BR putchar () +return the character written as an +.I unsigned char +cast to an +.I int +or +.B EOF +on error. +.P +.BR puts () +and +.BR fputs () +return a nonnegative number on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputc (), +.BR fputs (), +.BR putc (), +.BR putchar (), +.BR puts () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99. +.SH BUGS +It is not advisable to mix calls to output functions from the +.I stdio +library with low-level calls to +.BR write (2) +for the file descriptor associated with the same output stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR write (2), +.BR ferror (3), +.BR fgets (3), +.BR fopen (3), +.BR fputwc (3), +.BR fputws (3), +.BR fseek (3), +.BR fwrite (3), +.BR putwchar (3), +.BR scanf (3), +.BR unlocked_stdio (3) diff --git a/man/man3/putspent.3 b/man/man3/putspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/putspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/pututline.3 b/man/man3/pututline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/pututline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/pututxline.3 b/man/man3/pututxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/pututxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/putw.3 b/man/man3/putw.3 new file mode 100644 index 0000000..7509345 --- /dev/null +++ b/man/man3/putw.3 @@ -0,0 +1 @@ +.so man3/getw.3 diff --git a/man/man3/putwc.3 b/man/man3/putwc.3 new file mode 100644 index 0000000..81826be --- /dev/null +++ b/man/man3/putwc.3 @@ -0,0 +1 @@ +.so man3/fputwc.3 diff --git a/man/man3/putwc_unlocked.3 b/man/man3/putwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putwchar.3 b/man/man3/putwchar.3 new file mode 100644 index 0000000..14a01ea --- /dev/null +++ b/man/man3/putwchar.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH putwchar 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putwchar \- write a wide character to standard output +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wint_t putwchar(wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR putwchar () +function is the wide-character equivalent of the +.BR putchar (3) +function. +It writes the wide character +.I wc +to +.IR stdout . +If +.I ferror(stdout) +becomes true, it returns +.BR WEOF . +If a wide character +conversion error occurs, it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +Otherwise, it returns +.IR wc . +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR putwchar () +function returns +.I wc +if no error occurred, or +.B WEOF +to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putwchar () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR putwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +It is reasonable to expect that +.BR putwchar () +will actually write +the multibyte sequence corresponding to the wide character +.IR wc . +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/putwchar_unlocked.3 b/man/man3/putwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/pvalloc.3 b/man/man3/pvalloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/pvalloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/qecvt.3 b/man/man3/qecvt.3 new file mode 100644 index 0000000..89b169b --- /dev/null +++ b/man/man3/qecvt.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de>. +.\" +.TH qecvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +qecvt, qfcvt, qgcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "[[deprecated]] char *qecvt(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *qfcvt(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *qgcvt(long double " number ", int " ndigit ", char *" buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR qecvt (), +.BR qfcvt (), +.BR qgcvt (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _SVID_SOURCE +.fi +.\" FIXME . The full FTM picture looks to have been something like the +.\" following mess: +.\" glibc 2.20 onward +.\" _DEFAULT_SOURCE +.\" glibc 2.18 to glibc 2.19 +.\" _BSD_SOURCE || _SVID_SOURCE +.\" glibc 2.10 to glibc 2.17 +.\" _SVID_SOURCE || (_XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && +.\" ! (_POSIX_C_SOURCE >= 200809L)) +.\" Before glibc 2.10: +.\" _SVID_SOURCE || _XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.SH DESCRIPTION +The functions +.BR qecvt (), +.BR qfcvt (), +and +.BR qgcvt () +are identical to +.BR ecvt (3), +.BR fcvt (3), +and +.BR gcvt (3) +respectively, except that they use a +.I "long double" +argument +.IR number . +See +.BR ecvt (3) +and +.BR gcvt (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR qecvt () +T} Thread safety MT-Unsafe race:qecvt +T{ +.na +.nh +.BR qfcvt () +T} Thread safety MT-Unsafe race:qfcvt +T{ +.na +.nh +.BR qgcvt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, SunOS, GNU. +.\" Not supported by libc4 and libc5. +.P +These functions are obsolete. +Instead, +.BR snprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR ecvt_r (3), +.BR gcvt (3), +.BR sprintf (3) diff --git a/man/man3/qecvt_r.3 b/man/man3/qecvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/qecvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/qfcvt.3 b/man/man3/qfcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man/man3/qfcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man/man3/qfcvt_r.3 b/man/man3/qfcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/qfcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/qgcvt.3 b/man/man3/qgcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man/man3/qgcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man/man3/qsort.3 b/man/man3/qsort.3 new file mode 100644 index 0000000..9cb493e --- /dev/null +++ b/man/man3/qsort.3 @@ -0,0 +1,157 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" 2006-01-15, mtk, Added example program. +.\" Modified 2012-03-08, Mark R. Bannister <cambridge@users.sourceforge.net> +.\" and Ben Bacarisse <software@bsb.me.uk> +.\" Document qsort_r() +.\" +.TH qsort 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +qsort, qsort_r \- sort an array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "void qsort(void " base [. size " * ." nmemb "], size_t " nmemb ", \ +size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size ])); +.BI "void qsort_r(void " base [. size " * ." nmemb "], size_t " nmemb ", \ +size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size "], void *)," +.BI " void *" arg ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR qsort_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR qsort () +function sorts an array with \fInmemb\fP elements of +size \fIsize\fP. +The \fIbase\fP argument points to the start of the +array. +.P +The contents of the array are sorted in ascending order according to a +comparison function pointed to by \fIcompar\fP, which is called with two +arguments that point to the objects being compared. +.P +The comparison function must return an integer less than, equal to, or +greater than zero if the first argument is considered to be respectively +less than, equal to, or greater than the second. +If two members compare as equal, +their order in the sorted array is undefined. +.P +The +.BR qsort_r () +function is identical to +.BR qsort () +except that the comparison function +.I compar +takes a third argument. +A pointer is passed to the comparison function via +.IR arg . +In this way, the comparison function does not need to use global variables to +pass through arbitrary arguments, and is therefore reentrant and safe to +use in threads. +.SH RETURN VALUE +The +.BR qsort () +and +.BR qsort_r () +functions return no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR qsort (), +.BR qsort_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR qsort () +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR qsort () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR qsort_r () +glibc 2.8. +.SH NOTES +To compare C strings, the comparison function can call +.BR strcmp (3), +as shown in the example below. +.SH EXAMPLES +For one example of use, see the example under +.BR bsearch (3). +.P +Another example is the following program, +which sorts the strings given in its command-line arguments: +.P +.\" SRC BEGIN (qsort.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +static int +cmpstringp(const void *p1, const void *p2) +{ + /* The actual arguments to this function are "pointers to + pointers to char", but strcmp(3) arguments are "pointers + to char", hence the following cast plus dereference. */ +\& + return strcmp(*(const char **) p1, *(const char **) p2); +} +\& +int +main(int argc, char *argv[]) +{ + if (argc < 2) { + fprintf(stderr, "Usage: %s <string>...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + qsort(&argv[1], argc \- 1, sizeof(char *), cmpstringp); +\& + for (size_t j = 1; j < argc; j++) + puts(argv[j]); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sort (1), +.BR alphasort (3), +.BR strcmp (3), +.BR versionsort (3) diff --git a/man/man3/qsort_r.3 b/man/man3/qsort_r.3 new file mode 100644 index 0000000..d073335 --- /dev/null +++ b/man/man3/qsort_r.3 @@ -0,0 +1 @@ +.so man3/qsort.3 diff --git a/man/man3/queue.3 b/man/man3/queue.3 new file mode 100644 index 0000000..000e4b1 --- /dev/null +++ b/man/man3/queue.3 @@ -0,0 +1 @@ +.so man7/queue.7 diff --git a/man/man3/raise.3 b/man/man3/raise.3 new file mode 100644 index 0000000..b4ac02d --- /dev/null +++ b/man/man3/raise.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:40:56 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" +.TH raise 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +raise \- send a signal to the caller +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int raise(int " sig ); +.fi +.SH DESCRIPTION +The +.BR raise () +function sends a signal to the calling process or thread. +In a single-threaded program it is equivalent to +.P +.in +4n +.EX +kill(getpid(), sig); +.EE +.in +.P +In a multithreaded program it is equivalent to +.P +.in +4n +.EX +pthread_kill(pthread_self(), sig); +.EE +.in +.P +If the signal causes a handler to be called, +.BR raise () +will return only after the signal handler has returned. +.SH RETURN VALUE +.BR raise () +returns 0 on success, and nonzero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR raise () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.P +Since glibc 2.3.3, +.BR raise () +is implemented by calling +.BR tgkill (2), +.\" 2.3.2 used the obsolete tkill(), if available. +if the kernel supports that system call. +Older glibc versions implemented +.BR raise () +using +.BR kill (2). +.SH SEE ALSO +.BR getpid (2), +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_kill (3), +.BR signal (7) diff --git a/man/man3/rand.3 b/man/man3/rand.3 new file mode 100644 index 0000000..d5357fb --- /dev/null +++ b/man/man3/rand.3 @@ -0,0 +1,240 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-04-28, Lars Wirzenius +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add +.\" better discussion of problems with rand on other systems. +.\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) +.\" Modified 1998-04-10, Nicolás Lichtmaier <nick@debian.org> +.\" with contribution from Francesco Potorti <F.Potorti@cnuce.cnr.it> +.\" Modified 2003-11-15, aeb, added rand_r +.\" 2010-09-13, mtk, added example program +.\" +.TH rand 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B int rand(void); +.BI "void srand(unsigned int " seed ); +.P +.BI "[[deprecated]] int rand_r(unsigned int *" seedp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR rand_r (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 199506L + glibc 2.23 and earlier + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR rand () +function returns a pseudo-random integer in the range 0 to +.B RAND_MAX +inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). +.P +The +.BR srand () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR rand (). +These sequences are repeatable by calling +.BR srand () +with the same seed value. +.P +If no seed value is provided, the +.BR rand () +function is automatically seeded with a value of 1. +.P +The function +.BR rand () +is not reentrant, since it +uses hidden state that is modified on each call. +This might just be the seed value to be used by the next call, +or it might be something more elaborate. +In order to get reproducible behavior in a threaded +application, this state must be made explicit; +this can be done using the reentrant function +.BR rand_r (). +.P +Like +.BR rand (), +.BR rand_r () +returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR]. +The +.I seedp +argument is a pointer to an +.I unsigned int +that is used to store state between calls. +If +.BR rand_r () +is called with the same initial value for the integer pointed to by +.IR seedp , +and that value is not modified between calls, +then the same pseudo-random sequence will result. +.P +The value pointed to by the +.I seedp +argument of +.BR rand_r () +provides only a very small amount of state, +so this function will be a weak pseudo-random generator. +Try +.BR drand48_r (3) +instead. +.SH RETURN VALUE +The +.BR rand () +and +.BR rand_r () +functions return a value between 0 and +.B RAND_MAX +(inclusive). +The +.BR srand () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rand (), +.BR rand_r (), +.BR srand () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The versions of +.BR rand () +and +.BR srand () +in the Linux C Library use the same random number generator as +.BR random (3) +and +.BR srandom (3), +so the lower-order bits should be as random as the higher-order bits. +However, on older +.BR rand () +implementations, and on current implementations on different systems, +the lower-order bits are much less random than the higher-order bits. +Do not use this function in applications intended to be portable +when good randomness is needed. +(Use +.BR random (3) +instead.) +.SH STANDARDS +.TP +.BR rand () +.TQ +.BR srand () +C11, POSIX.1-2008. +.TP +.BR rand_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR rand () +.TQ +.BR srand () +SVr4, 4.3BSD, C89, POSIX.1-2001. +.TP +.BR rand_r () +POSIX.1-2001. +Obsolete in POSIX.1-2008. +.SH EXAMPLES +POSIX.1-2001 gives the following example of an implementation of +.BR rand () +and +.BR srand (), +possibly useful when one needs the same sequence on two different machines. +.P +.in +4n +.EX +static unsigned long next = 1; +\& +/* RAND_MAX assumed to be 32767 */ +int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); +} +\& +void mysrand(unsigned int seed) { + next = seed; +} +.EE +.in +.P +The following program can be used to display the +pseudo-random sequence produced by +.BR rand () +when given a particular seed. +When the seed is +.IR \-1 , +the program uses a random seed. +.P +.in +4n +.\" SRC BEGIN (rand.c) +.EX +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + int r; + unsigned int seed, nloops; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + seed = atoi(argv[1]); + nloops = atoi(argv[2]); +\& + if (seed == \-1) { + seed = arc4random(); + printf("seed: %u\en", seed); + } +\& + srand(seed); + for (unsigned int j = 0; j < nloops; j++) { + r = rand(); + printf("%d\en", r); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR drand48 (3), +.BR random (3) diff --git a/man/man3/rand_r.3 b/man/man3/rand_r.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man/man3/rand_r.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man/man3/random.3 b/man/man3/random.3 new file mode 100644 index 0000000..ff788e4 --- /dev/null +++ b/man/man3/random.3 @@ -0,0 +1,193 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Mar 28 00:25:51 1993, David Metcalfe +.\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 20 21:47:07 2000, aeb +.\" +.TH random 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random, srandom, initstate, setstate \- random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B long random(void); +.BI "void srandom(unsigned int " seed ); +.P +.BI "char *initstate(unsigned int " seed ", char " state [. n "], size_t " n ); +.BI "char *setstate(char *" state ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR random (), +.BR srandom (), +.BR initstate (), +.BR setstate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR random () +function uses a nonlinear additive feedback random +number generator employing a default table of size 31 long integers to +return successive pseudo-random numbers in +the range from 0 to 2\[ha]31\ \-\ 1. +The period of this random number generator is very large, approximately +.IR "16\ *\ ((2\[ha]31)\ \-\ 1)" . +.P +The +.BR srandom () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR random (). +These sequences are repeatable by calling +.BR srandom () +with the same +seed value. +If no seed value is provided, the +.BR random () +function +is automatically seeded with a value of 1. +.P +The +.BR initstate () +function allows a state array \fIstate\fP to +be initialized for use by +.BR random (). +The size of the state array +\fIn\fP is used by +.BR initstate () +to decide how sophisticated a +random number generator it should use\[em]the larger the state array, +the better the random numbers will be. +Current "optimal" values for the size of the state array \fIn\fP are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. +Using less than 8 bytes results in an error. +\fIseed\fP is the seed for the +initialization, which specifies a starting point for the random number +sequence, and provides for restarting at the same point. +.P +The +.BR setstate () +function changes the state array used by the +.BR random () +function. +The state array \fIstate\fP is used for +random number generation until the next call to +.BR initstate () +or +.BR setstate (). +\fIstate\fP must first have been initialized +using +.BR initstate () +or be the result of a previous call of +.BR setstate (). +.SH RETURN VALUE +The +.BR random () +function returns a value between 0 and +.IR "(2\[ha]31)\ \-\ 1" . +The +.BR srandom () +function returns no value. +.P +The +.BR initstate () +function returns a pointer to the previous state array. +On failure, it returns NULL, and +.I errno +is set to indicate the error. +.P +On success, +.BR setstate () +returns a pointer to the previous state array. +On failure, it returns NULL, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I state +argument given to +.BR setstate () +was NULL. +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR random (), +.BR srandom (), +.BR initstate (), +.BR setstate () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH NOTES +Random-number generation is a complex topic. +.I Numerical Recipes in C: The Art of Scientific Computing +(William H.\& Press, Brian P.\& Flannery, Saul A.\& Teukolsky, +William T.\& Vetterling; New York: Cambridge University Press, 2007, 3rd ed.) +provides an excellent discussion of practical random-number generation +issues in Chapter 7 (Random Numbers). +.P +For a more theoretical discussion which also covers many practical issues +in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's +.IR "The Art of Computer Programming" , +volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: +Addison-Wesley Publishing Company, 1981. +.SH CAVEATS +The +.BR random () +function should not be used in multithreaded programs +where reproducible behavior is required. +Use +.BR random_r (3) +for that purpose. +.SH BUGS +According to POSIX, +.BR initstate () +should return NULL on error. +In the glibc implementation, +.I errno +is (as specified) set on error, but the function does not return NULL. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=15380 +.SH SEE ALSO +.BR getrandom (2), +.BR drand48 (3), +.BR rand (3), +.BR random_r (3), +.BR srand (3) diff --git a/man/man3/random_r.3 b/man/man3/random_r.3 new file mode 100644 index 0000000..5215975 --- /dev/null +++ b/man/man3/random_r.3 @@ -0,0 +1,176 @@ +'\" t +.\" Copyright 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH random_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random_r, srandom_r, initstate_r, setstate_r \- reentrant +random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int random_r(struct random_data *restrict " buf , +.BI " int32_t *restrict " result ); +.BI "int srandom_r(unsigned int " seed ", struct random_data *" buf ); +.P +.BI "int initstate_r(unsigned int " seed ", \ +char " statebuf "[restrict ." statelen ], +.BI " size_t " statelen ", struct random_data *restrict " buf ); +.BI "int setstate_r(char *restrict " statebuf , +.BI " struct random_data *restrict " buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are the reentrant equivalents +of the functions described in +.BR random (3). +They are suitable for use in multithreaded programs where each thread +needs to obtain an independent, reproducible sequence of random numbers. +.P +The +.BR random_r () +function is like +.BR random (3), +except that instead of using state information maintained +in a global variable, +it uses the state information in the argument pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (). +The generated random number is returned in the argument +.IR result . +.P +The +.BR srandom_r () +function is like +.BR srandom (3), +except that it initializes the seed for the random number generator +whose state is maintained in the object pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (), +instead of the seed associated with the global state variable. +.P +The +.BR initstate_r () +function is like +.BR initstate (3) +except that it initializes the state in the object pointed to by +.IR buf , +rather than initializing the global state variable. +Before calling this function, the +.I buf.state +field must be initialized to NULL. +The +.BR initstate_r () +function records a pointer to the +.I statebuf +argument inside the structure pointed to by +.IR buf . +Thus, +.I statebuf +should not be deallocated so long as +.I buf +is still in use. +(So, +.I statebuf +should typically be allocated as a static variable, +or allocated on the heap using +.BR malloc (3) +or similar.) +.P +The +.BR setstate_r () +function is like +.BR setstate (3) +except that it modifies the state in the object pointed to by +.IR buf , +rather than modifying the global state variable. +\fIstate\fP must first have been initialized +using +.BR initstate_r () +or be the result of a previous call of +.BR setstate_r (). +.SH RETURN VALUE +All of these functions return 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate_r (). +.TP +.B EINVAL +The +.I statebuf +or +.I buf +argument to +.BR setstate_r () +was NULL. +.TP +.B EINVAL +The +.I buf +or +.I result +argument to +.BR random_r () +was NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r () +T} Thread safety MT-Safe race:buf +.TE +.SH STANDARDS +GNU. +.\" These functions appear to be on Tru64, but don't seem to be on +.\" Solaris, HP-UX, or FreeBSD. +.SH BUGS +The +.BR initstate_r () +interface is confusing. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662 +It appears that the +.I random_data +type is intended to be opaque, +but the implementation requires the user to either initialize the +.I buf.state +field to NULL or zero out the entire structure before the call. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) diff --git a/man/man3/rawmemchr.3 b/man/man3/rawmemchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man/man3/rawmemchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man/man3/rcmd.3 b/man/man3/rcmd.3 new file mode 100644 index 0000000..718a049 --- /dev/null +++ b/man/man3/rcmd.3 @@ -0,0 +1,304 @@ +'\" t +.\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Contributed as Linux man page by David A. Holland, 970908 +.\" I have not checked whether the Linux situation is exactly the same. +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH rcmd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rcmd, rresvport, iruserok, ruserok, rcmd_af, +rresvport_af, iruserok_af, ruserok_af \- routines for returning a +stream to a remote command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <netdb.h> " "/* Or <unistd.h> on some systems */" +.P +.BI "int rcmd(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p ); +.P +.BI "int rresvport(int *" port ); +.P +.BI "int iruserok(uint32_t " raddr ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.BI "int ruserok(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.P +.BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p , +.BI " sa_family_t " af ); +.P +.BI "int rresvport_af(int *" port ", sa_family_t " af ); +.P +.BI "int iruserok_af(const void *restrict " raddr ", int " superuser , +.BI " const char *restrict " ruser ", const char *restrict " luser , +.BI " sa_family_t " af ); +.BI "int ruserok_af(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser , +.BI " sa_family_t " af ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR rcmd (), +.BR rcmd_af (), +.BR rresvport (), +.BR rresvport_af (), +.BR iruserok (), +.BR iruserok_af (), +.BR ruserok (), +.BR ruserok_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.ad +.SH DESCRIPTION +The +.BR rcmd () +function is used by the superuser to execute a command on +a remote machine using an authentication scheme based +on privileged port numbers. +The +.BR rresvport () +function +returns a file descriptor to a socket +with an address in the privileged port space. +The +.BR iruserok () +and +.BR ruserok () +functions are used by servers +to authenticate clients requesting service with +.BR rcmd (). +All four functions are used by the +.BR rshd (8) +server (among others). +.SS rcmd() +The +.BR rcmd () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.IR inport . +.P +If the connection succeeds, +a socket in the Internet domain of type +.B SOCK_STREAM +is returned to the caller, and given to the remote +command as +.I stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be set up, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +If +.I fd2p +is 0, then the +.I stderr +(unit 2 of the remote +command) will be made the same as the +.I stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.P +The protocol is described in detail in +.BR rshd (8). +.SS rresvport() +The +.BR rresvport () +function is used to obtain a socket with a privileged +port bound to it. +This socket is suitable for use by +.BR rcmd () +and several other functions. +Privileged ports are those in the range 0 to 1023. +Only a privileged process +(on Linux, a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace) +is allowed to bind to a privileged port. +In the glibc implementation, +this function restricts its search to the ports from 512 to 1023. +The +.I port +argument is value-result: +the value it supplies to the call is used as the starting point +for a circular search of the port range; +on (successful) return, it contains the port number that was bound to. +.\" +.SS iruserok() and ruserok() +The +.BR iruserok () +and +.BR ruserok () +functions take a remote host's IP address or name, respectively, +two usernames and a flag indicating whether the local user's +name is that of the superuser. +Then, if the user is +.I not +the superuser, it checks the +.I /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.I .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.P +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the superuser, is writable by anyone other +than the owner, or is hardlinked anywhere, the check automatically fails. +Zero is returned if the machine name is listed in the +.I hosts.equiv +file, or the host and remote username are found in the +.I .rhosts +file; otherwise +.BR iruserok () +and +.BR ruserok () +return \-1. +If the local domain (as obtained from +.BR gethostname (2)) +is the same as the remote domain, only the machine name need be specified. +.P +If the IP address of the remote host is known, +.BR iruserok () +should be used in preference to +.BR ruserok (), +as it does not require trusting the DNS server for the remote host's domain. +.SS *_af() variants +All of the functions described above work with IPv4 +.RB ( AF_INET ) +sockets. +The "_af" variants take an extra argument that allows the +socket address family to be specified. +For these functions, the +.I af +argument can be specified as +.B AF_INET +or +.BR AF_INET6 . +In addition, +.BR rcmd_af () +supports the use of +.BR AF_UNSPEC . +.SH RETURN VALUE +The +.BR rcmd () +function +returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.P +The +.BR rresvport () +function +returns a valid, bound socket descriptor on success. +On failure, it returns \-1 and sets +.I errno +to indicate the error. +The error code +.B EAGAIN +is overloaded to mean: "All network ports in use". +.P +For information on the return from +.BR ruserok () +and +.BR iruserok (), +see above. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rcmd (), +.BR rcmd_af () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR rresvport (), +.BR rresvport_af () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR iruserok (), +.BR ruserok (), +.BR iruserok_af (), +.BR ruserok_af () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +.TP +.BR iruserok_af () +.TQ +.BR rcmd_af () +.TQ +.BR rresvport_af () +.TQ +.BR ruserok_af () +glibc 2.2. +.P +Solaris, 4.2BSD. +The "_af" variants are more recent additions, +and are not present on as wide a range of systems. +.SH BUGS +.BR iruserok () +and +.BR iruserok_af () +are declared in glibc headers only since glibc 2.12. +.\" Bug filed 25 Nov 2007: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399 +.SH SEE ALSO +.BR rlogin (1), +.BR rsh (1), +.BR rexec (3), +.BR rexecd (8), +.BR rlogind (8), +.BR rshd (8) diff --git a/man/man3/rcmd_af.3 b/man/man3/rcmd_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rcmd_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/re_comp.3 b/man/man3/re_comp.3 new file mode 100644 index 0000000..16e0a5a --- /dev/null +++ b/man/man3/re_comp.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@@ee.surrey.ac.uk) +.\" +.TH re_comp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +re_comp, re_exec \- BSD regex functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _REGEX_RE_COMP +.B #include <sys/types.h> +.B #include <regex.h> +.P +.BI "[[deprecated]] char *re_comp(const char *" regex ); +.BI "[[deprecated]] int re_exec(const char *" string ); +.fi +.SH DESCRIPTION +.BR re_comp () +is used to compile the null-terminated regular expression pointed to by +.IR regex . +The compiled pattern occupies a static area, the pattern buffer, +which is overwritten by subsequent use of +.BR re_comp (). +If +.I regex +is NULL, +no operation is performed and the pattern buffer's contents are not +altered. +.P +.BR re_exec () +is used to assess whether the null-terminated string pointed to by +.I string +matches the previously compiled +.IR regex . +.SH RETURN VALUE +.BR re_comp () +returns NULL on successful compilation of +.I regex +otherwise it returns a pointer to an appropriate error message. +.P +.BR re_exec () +returns 1 for a successful match, zero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR re_comp (), +.BR re_exec () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.P +These functions are obsolete; the functions documented in +.BR regcomp (3) +should be used instead. +.SH SEE ALSO +.BR regcomp (3), +.BR regex (7), +GNU regex manual diff --git a/man/man3/re_exec.3 b/man/man3/re_exec.3 new file mode 100644 index 0000000..36aba39 --- /dev/null +++ b/man/man3/re_exec.3 @@ -0,0 +1 @@ +.so man3/re_comp.3 diff --git a/man/man3/readdir.3 b/man/man3/readdir.3 new file mode 100644 index 0000000..887dde8 --- /dev/null +++ b/man/man3/readdir.3 @@ -0,0 +1,304 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk: +.\" Rework discussion of nonstandard structure fields. +.\" +.TH readdir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readdir \- read a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "struct dirent *readdir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR readdir () +function returns a pointer to a \fIdirent\fP structure +representing the next directory entry in the directory stream pointed +to by \fIdirp\fP. +It returns NULL on reaching the end of the directory stream or if +an error occurred. +.P +In the glibc implementation, the +.I dirent +structure is defined as follows: +.P +.in +4n +.EX +struct dirent { + ino_t d_ino; /* Inode number */ + off_t d_off; /* Not an offset; see below */ + unsigned short d_reclen; /* Length of this record */ + unsigned char d_type; /* Type of file; not supported + by all filesystem types */ + char d_name[256]; /* Null\-terminated filename */ +}; +.EE +.in +.P +The only fields in the +.I dirent +structure that are mandated by POSIX.1 are +.I d_name +and +.IR d_ino . +The other fields are unstandardized, and not present on all systems; +see NOTES below for some further details. +.P +The fields of the +.I dirent +structure are as follows: +.TP +.I d_ino +This is the inode number of the file. +.TP +.I d_off +The value returned in +.I d_off +is the same as would be returned by calling +.BR telldir (3) +at the current position in the directory stream. +Be aware that despite its type and name, the +.I d_off +field is seldom any kind of directory offset on modern filesystems. +.\" https://lwn.net/Articles/544298/ +Applications should treat this field as an opaque value, +making no assumptions about its contents; see also +.BR telldir (3). +.TP +.I d_reclen +This is the size (in bytes) of the returned record. +This may not match the size of the structure definition shown above; +see NOTES. +.TP +.I d_type +This field contains a value indicating the file type, +making it possible to avoid the expense of calling +.BR lstat (2) +if further actions depend on the type of the file. +.IP +When a suitable feature test macro is defined +.RB ( _DEFAULT_SOURCE +since glibc 2.19, or +.B _BSD_SOURCE +on glibc 2.19 and earlier), +glibc defines the following macro constants for the value returned in +.IR d_type : +.RS +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type could not be determined. +.RE +.IP +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in getdents.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.TP +.I d_name +This field contains the null terminated filename. +.IR "See NOTES" . +.P +The data returned by +.BR readdir () +may be overwritten by subsequent calls to +.BR readdir () +for the same directory stream. +.SH RETURN VALUE +On success, +.BR readdir () +returns a pointer to a +.I dirent +structure. +(This structure may be statically allocated; do not attempt to +.BR free (3) +it.) +.P +If the end of the directory stream is reached, NULL is returned and +.I errno +is not changed. +If an error occurs, NULL is returned and +.I errno +is set to indicate the error. +To distinguish end of stream from an error, set +.I errno +to zero before calling +.BR readdir () +and then check the value of +.I errno +if NULL is returned. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR readdir () +T} Thread safety MT-Unsafe race:dirstream +.TE +.P +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir () +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir () +that specify different directory streams are thread-safe. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir () +with external synchronization is still preferable to the use of the deprecated +.BR readdir_r (3) +function. +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will require that +.BR readdir () +be thread-safe when concurrently employed on different directory streams. +.SH VERSIONS +Only the fields +.I d_name +and (as an XSI extension) +.I d_ino +are specified in POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +Other than Linux, the +.I d_type +field is available mainly only on BSD systems. +The remaining fields are available on many, but not all systems. +Under glibc, +programs can check for the availability of the fields not defined +in POSIX.1 by testing whether the macros +.BR _DIRENT_HAVE_D_NAMLEN , +.BR _DIRENT_HAVE_D_RECLEN , +.BR _DIRENT_HAVE_D_OFF , +or +.B _DIRENT_HAVE_D_TYPE +are defined. +.\" +.SS The d_name field +The +.I dirent +structure definition shown above is taken from the glibc headers, +and shows the +.I d_name +field with a fixed size. +.P +.IR Warning : +applications should avoid any dependence on the size of the +.I d_name +field. +POSIX defines it as +.IR "char\ d_name[]", +a character array of unspecified size, with at most +.B NAME_MAX +characters preceding the terminating null byte (\[aq]\e0\[aq]). +.P +POSIX.1 explicitly notes that this field should not be used as an lvalue. +The standard also notes that the use of +.I sizeof(d_name) +is incorrect; use +.I strlen(d_name) +instead. +(On some systems, this field is defined as +.IR char\~d_name[1] !) +By implication, the use +.I sizeof(struct dirent) +to capture the size of the record including the size of +.I d_name +is also incorrect. +.P +Note that while the call +.P +.in +4n +.EX +fpathconf(fd, _PC_NAME_MAX) +.EE +.in +.P +returns the value 255 for most filesystems, +on some filesystems (e.g., CIFS, Windows SMB servers), +the null-terminated filename that is (correctly) returned in +.I d_name +can actually exceed this size. +In such cases, the +.I d_reclen +field will contain a value that exceeds the size of the glibc +.I dirent +structure shown above. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +A directory stream is opened using +.BR opendir (3). +.P +The order in which filenames are read by successive calls to +.BR readdir () +depends on the filesystem implementation; +it is unlikely that the names will be sorted in any fashion. +.SH SEE ALSO +.BR getdents (2), +.BR read (2), +.BR closedir (3), +.BR dirfd (3), +.BR ftw (3), +.BR offsetof (3), +.BR opendir (3), +.BR readdir_r (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/readdir_r.3 b/man/man3/readdir_r.3 new file mode 100644 index 0000000..a46c19c --- /dev/null +++ b/man/man3/readdir_r.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (C) 2016 Florian Weimer <fweimer@redhat.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH readdir_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readdir_r \- read a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "[[deprecated]] int readdir_r(DIR *restrict " dirp , +.BI " struct dirent *restrict " entry , +.BI " struct dirent **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR readdir_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +This function is deprecated; use +.BR readdir (3) +instead. +.P +The +.BR readdir_r () +function was invented as a reentrant version of +.BR readdir (3). +It reads the next directory entry from the directory stream +.IR dirp , +and returns it in the caller-allocated buffer pointed to by +.IR entry . +For details of the +.I dirent +structure, see +.BR readdir (3). +.P +A pointer to the returned buffer is placed in +.IR *result ; +if the end of the directory stream was encountered, +then NULL is instead returned in +.IR *result . +.P +It is recommended that applications use +.BR readdir (3) +instead of +.BR readdir_r (). +Furthermore, since glibc 2.24, glibc deprecates +.BR readdir_r (). +The reasons are as follows: +.IP \[bu] 3 +On systems where +.B NAME_MAX +is undefined, calling +.BR readdir_r () +may be unsafe because the interface does not allow the caller to specify +the length of the buffer used for the returned directory entry. +.IP \[bu] +On some systems, +.BR readdir_r () +can't read directory entries with very long names. +When the glibc implementation encounters such a name, +.BR readdir_r () +fails with the error +.B ENAMETOOLONG +.IR "after the final directory entry has been read" . +On some other systems, +.BR readdir_r () +may return a success status, but the returned +.I d_name +field may not be null terminated or may be truncated. +.IP \[bu] +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir (3) +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir (3) +that specify different directory streams are thread-safe. +Therefore, the use of +.BR readdir_r () +is generally unnecessary in multithreaded programs. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir (3) +with external synchronization is still preferable to the use of +.BR readdir_r (), +for the reasons given in the points above. +.IP \[bu] +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will make +.BR readdir_r () +obsolete, and require that +.BR readdir (3) +be thread-safe when concurrently employed on different directory streams. +.SH RETURN VALUE +The +.BR readdir_r () +function returns 0 on success. +On error, it returns a positive error number (listed under ERRORS). +If the end of the directory stream is reached, +.BR readdir_r () +returns 0, and returns NULL in +.IR *result . +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.TP +.B ENAMETOOLONG +A directory entry whose name was too long to be read was encountered. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR readdir_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR readdir (3) diff --git a/man/man3/realloc.3 b/man/man3/realloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/realloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/reallocarray.3 b/man/man3/reallocarray.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/reallocarray.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/realpath.3 b/man/man3/realpath.3 new file mode 100644 index 0000000..581edf8 --- /dev/null +++ b/man/man3/realpath.3 @@ -0,0 +1,231 @@ +'\" t +.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 990824, aeb@cwi.nl +.\" 2004-12-14, mtk, added discussion of resolved_path == NULL +.\" +.TH realpath 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +realpath \- return the canonicalized absolute pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <limits.h> +.B #include <stdlib.h> +.P +.BI "char *realpath(const char *restrict " path , +.BI " char *restrict " resolved_path ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR realpath (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR realpath () +expands all symbolic links and resolves references +to +.IR "/./" ", " "/../" +and extra \[aq]/\[aq] +characters in the null-terminated string named by +.I path +to produce a canonicalized absolute pathname. +The resulting pathname is stored as a null-terminated string, +up to a maximum of +.B PATH_MAX +bytes, +in the buffer pointed to by +.IR resolved_path . +The resulting path will have no symbolic link, +.I "/./" +or +.I "/../" +components. +.P +If +.I resolved_path +is specified as NULL, then +.BR realpath () +uses +.BR malloc (3) +to allocate a buffer of up to +.B PATH_MAX +bytes to hold the resolved pathname, +and returns a pointer to this buffer. +The caller should deallocate this buffer using +.BR free (3). +.\" Even if we use resolved_path == NULL, then realpath() will still +.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX +.\" bytes -- MTK, Dec 04 +.SH RETURN VALUE +If there is no error, +.BR realpath () +returns a pointer to the +.IR resolved_path . +.P +Otherwise, it returns NULL, the contents +of the array +.I resolved_path +are undefined, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read or search permission was denied for a component of the path prefix. +.TP +.B EINVAL +.I path +is NULL. +.\" (In libc5 this would just cause a segfault.) +(Before glibc 2.3, +this error is also returned if +.I resolved_path +is NULL.) +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded +.B NAME_MAX +characters, or an entire pathname exceeded +.B PATH_MAX +characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR realpath () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS GNU extensions +If the call fails with either +.B EACCES +or +.B ENOENT +and +.I resolved_path +is not NULL, then the prefix of +.I path +that is not readable or does not exist is returned in +.IR resolved_path . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.4BSD, POSIX.1-2001, Solaris. +.P +POSIX.1-2001 says that the behavior if +.I resolved_path +is NULL is implementation-defined. +POSIX.1-2008 specifies the behavior described in this page. +.P +In 4.4BSD and Solaris, the limit on the pathname length is +.B MAXPATHLEN +(found in \fI<sys/param.h>\fP). +SUSv2 prescribes +.B PATH_MAX +and +.BR NAME_MAX , +as found in \fI<limits.h>\fP or provided by the +.BR pathconf (3) +function. +A typical source fragment would be +.P +.in +4n +.EX +#ifdef PATH_MAX + path_max = PATH_MAX; +#else + path_max = pathconf(path, _PC_PATH_MAX); + if (path_max <= 0) + path_max = 4096; +#endif +.EE +.in +.P +(But see the BUGS section.) +.\".P +.\" 2012-05-05, According to Casper Dik, the statement about +.\" Solaris was not true at least as far back as 1997, and +.\" may never have been true. +.\" +.\" The 4.4BSD, Linux and SUSv2 versions always return an absolute +.\" pathname. +.\" Solaris may return a relative pathname when the +.\" .I path +.\" argument is relative. +.\" The prototype of +.\" .BR realpath () +.\" is given in \fI<unistd.h>\fP in libc4 and libc5, +.\" but in \fI<stdlib.h>\fP everywhere else. +.SH BUGS +The POSIX.1-2001 standard version of this function is broken by design, +since it is impossible to determine a suitable size for the output buffer, +.IR resolved_path . +According to POSIX.1-2001 a buffer of size +.B PATH_MAX +suffices, but +.B PATH_MAX +need not be a defined constant, and may have to be obtained using +.BR pathconf (3). +And asking +.BR pathconf (3) +does not really help, since, on the one hand POSIX warns that +the result of +.BR pathconf (3) +may be huge and unsuitable for mallocing memory, +and on the other hand +.BR pathconf (3) +may return \-1 to signify that +.B PATH_MAX +is not bounded. +The +.I "resolved_path\ ==\ NULL" +feature, not standardized in POSIX.1-2001, +but standardized in POSIX.1-2008, allows this design problem to be avoided. +.\" .P +.\" The libc4 and libc5 implementation contained a buffer overflow +.\" (fixed in libc-5.4.13). +.\" Thus, set-user-ID programs like +.\" .BR mount (8) +.\" needed a private version. +.SH SEE ALSO +.BR realpath (1), +.BR readlink (2), +.BR canonicalize_file_name (3), +.BR getcwd (3), +.BR pathconf (3), +.BR sysconf (3) diff --git a/man/man3/recno.3 b/man/man3/recno.3 new file mode 100644 index 0000000..03bcf1c --- /dev/null +++ b/man/man3/recno.3 @@ -0,0 +1,207 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" +.TH recno 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +recno \- record number database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include <sys/types.h> +#include <db.h> +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the recno-specific information. +.P +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.P +The recno access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I <db.h> +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + unsigned int psize; + int lorder; + size_t reclen; + unsigned char bval; + char *bfname; +} RECNOINFO; +.EE +.in +.P +The elements of this structure are defined as follows: +.TP +.I flags +The flag value is specified by ORing +any of the following values: +.RS +.TP +.B R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.I reclen +specifies the length of the record, and the structure element +.I bval +is used as the pad character. +Any records, inserted into the database, that are less than +.I reclen +bytes long are automatically padded. +.TP +.B R_NOKEY +In the interface specified by +.BR dbopen (3), +the sequential record retrieval fills in both the caller's key and +data structures. +If the +.B R_NOKEY +flag is specified, the +.I cursor +routines are not required to fill in the key structure. +This permits applications to retrieve records at the end of files without +reading all of the intervening records. +.TP +.B R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.BR dbopen (3) +is called, instead of permitting any unmodified records to be read from +the original file. +.RE +.TP +.I cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather than fail. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I psize +The recno access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that tree. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +See +.BR btree (3) +for more information. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.TP +.I reclen +The length of a fixed-length record. +.TP +.I bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines ("\en") are used to mark the end +of variable-length records and fixed-length records are padded with +spaces. +.TP +.I bfname +The recno access method stores the in-memory copies of its records +in a btree. +If +.I bfname +is non-NULL, it specifies the name of the btree file, +as if specified as the filename for a +.BR dbopen (3) +of a btree file. +.P +The data part of the key/data pair used by the +.I recno +access method +is the same as other access methods. +The key is different. +The +.I data +field of the key should be a pointer to a memory location of type +.IR recno_t , +as defined in the +.I <db.h> +include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.I size +field of the key should be the size of that type. +.P +Because there can be no metadata associated with the underlying +recno access method files, any changes made to the default values +(e.g., fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.P +In the interface specified by +.BR dbopen (3), +using the +.I put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.SH ERRORS +The +.I recno +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3) +or the following: +.TP +.B EINVAL +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR mpool (3) +.P +.IR "Document Processing in a Relational Database System" , +Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, +Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. diff --git a/man/man3/regcomp.3 b/man/man3/regcomp.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regcomp.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regerror.3 b/man/man3/regerror.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regerror.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regex.3 b/man/man3/regex.3 new file mode 100644 index 0000000..2b3c795 --- /dev/null +++ b/man/man3/regex.3 @@ -0,0 +1,411 @@ +'\" t +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" Copyright 2023, Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> +.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" Tiny change in formatting - aeb, 950812 +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.\" show the synopsis section nicely +.TH regex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +regcomp, regexec, regerror, regfree \- POSIX regex functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <regex.h> +.P +.BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex , +.BI " int " cflags ); +.BI "int regexec(const regex_t *restrict " preg \ +", const char *restrict " string , +.BI " size_t " nmatch ", \ +regmatch_t " pmatch "[_Nullable restrict ." nmatch ], +.BI " int " eflags ); +.P +.BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg , +.BI " char " errbuf "[_Nullable restrict ." errbuf_size ], +.BI " size_t " errbuf_size ); +.BI "void regfree(regex_t *" preg ); +.P +.B typedef struct { +.B " size_t re_nsub;" +.B } regex_t; +.P +.B typedef struct { +.B " regoff_t rm_so;" +.B " regoff_t rm_eo;" +.B } regmatch_t; +.P +.BR typedef " /* ... */ " regoff_t; +.fi +.SH DESCRIPTION +.SS Compilation +.BR regcomp () +is used to compile a regular expression into a form that is suitable +for subsequent +.BR regexec () +searches. +.P +On success, the pattern buffer at +.I *preg +is initialized. +.I regex +is a null-terminated string. +The locale must be the same when running +.BR regexec (). +.P +After +.BR regcomp () +succeeds, +.I preg->re_nsub +holds the number of subexpressions in +.IR regex . +Thus, a value of +.I preg->re_nsub ++ 1 +passed as +.I nmatch +to +.BR regexec () +is sufficient to capture all matches. +.P +.I cflags +is the +bitwise OR +of zero or more of the following: +.TP +.B REG_EXTENDED +Use +POSIX +Extended Regular Expression syntax when interpreting +.IR regex . +If not set, +POSIX +Basic Regular Expression syntax is used. +.TP +.B REG_ICASE +Do not differentiate case. +Subsequent +.BR regexec () +searches using this pattern buffer will be case insensitive. +.TP +.B REG_NOSUB +Report only overall success. +.BR regexec () +will use only +.I pmatch +for +.BR REG_STARTEND , +ignoring +.IR nmatch . +.TP +.B REG_NEWLINE +Match-any-character operators don't match a newline. +.IP +A nonmatching list +.RB ( [\[ha]...\&] ) +not containing a newline does not match a newline. +.IP +Match-beginning-of-line operator +.RB ( \[ha] ) +matches the empty string immediately after a newline, regardless of +whether +.IR eflags , +the execution flags of +.BR regexec (), +contains +.BR REG_NOTBOL . +.IP +Match-end-of-line operator +.RB ( $ ) +matches the empty string immediately before a newline, regardless of +whether +.I eflags +contains +.BR REG_NOTEOL . +.SS Matching +.BR regexec () +is used to match a null-terminated string +against the compiled pattern buffer in +.IR *preg , +which must have been initialised with +.BR regexec (). +.I eflags +is the +bitwise OR +of zero or more of the following flags: +.TP +.B REG_NOTBOL +The match-beginning-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +This flag may be used when different portions of a string are passed to +.BR regexec () +and the beginning of the string should not be interpreted as the +beginning of the line. +.TP +.B REG_NOTEOL +The match-end-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +.TP +.B REG_STARTEND +Match +.RI [ "string + pmatch[0].rm_so" , " string + pmatch[0].rm_eo" ) +instead of +.RI [ string , " string + strlen(string)" ). +This allows matching embedded NUL bytes +and avoids a +.BR strlen (3) +on known-length strings. +If any matches are returned +.RB ( REG_NOSUB +wasn't passed to +.BR regcomp (), +the match succeeded, and +.I nmatch +> 0), they overwrite +.I pmatch +as usual, and the match offsets remain relative to +.I string +(not +.IR "string + pmatch[0].rm_so" ). +This flag is a BSD extension, not present in POSIX. +.SS Match offsets +Unless +.B REG_NOSUB +was passed to +.BR regcomp (), +it is possible to +obtain the locations of matches within +.IR string : +.BR regexec () +fills +.I nmatch +elements of +.I pmatch +with results: +.I pmatch[0] +corresponds to the entire match, +.I pmatch[1] +to the first subexpression, etc. +If there were more matches than +.IR nmatch , +they are discarded; +if fewer, +unused elements of +.I pmatch +are filled with +.BR \-1 s. +.P +Each returned valid +.RB (non- \-1 ) +match corresponds to the range +.RI [ "string + rm_so" , " string + rm_eo" ). +.P +.I regoff_t +is a signed integer type +capable of storing the largest value that can be stored in either an +.I ptrdiff_t +type or a +.I ssize_t +type. +.SS Error reporting +.BR regerror () +is used to turn the error codes that can be returned by both +.BR regcomp () +and +.BR regexec () +into error message strings. +.P +If +.I preg +isn't a null pointer, +.I errcode +must be the latest error returned from an operation on +.IR preg . +.P +If +.I errbuf_size +isn't 0, up to +.I errbuf_size +bytes are copied to +.IR errbuf ; +the error string is always null-terminated, and truncated to fit. +.SS Freeing +.BR regfree () +deinitializes the pattern buffer at +.IR *preg , +freeing any associated memory; +.I *preg +must have been initialized via +.BR regcomp (). +.SH RETURN VALUE +.BR regcomp () +returns zero for a successful compilation or an error code for failure. +.P +.BR regexec () +returns zero for a successful match or +.B REG_NOMATCH +for failure. +.P +.BR regerror () +returns the size of the buffer required to hold the string. +.SH ERRORS +The following errors can be returned by +.BR regcomp (): +.TP +.B REG_BADBR +Invalid use of back reference operator. +.TP +.B REG_BADPAT +Invalid use of pattern operators such as group or list. +.TP +.B REG_BADRPT +Invalid use of repetition operators such as using \[aq]*\[aq] +as the first character. +.TP +.B REG_EBRACE +Un-matched brace interval operators. +.TP +.B REG_EBRACK +Un-matched bracket list operators. +.TP +.B REG_ECOLLATE +Invalid collating element. +.TP +.B REG_ECTYPE +Unknown character class name. +.TP +.B REG_EEND +Nonspecific error. +This is not defined by POSIX. +.TP +.B REG_EESCAPE +Trailing backslash. +.TP +.B REG_EPAREN +Un-matched parenthesis group operators. +.TP +.B REG_ERANGE +Invalid use of the range operator; for example, the ending point of the range +occurs prior to the starting point. +.TP +.B REG_ESIZE +Compiled regular expression requires a pattern buffer larger than 64\ kB. +This is not defined by POSIX. +.TP +.B REG_ESPACE +The regex routines ran out of memory. +.TP +.B REG_ESUBREG +Invalid back reference to a subexpression. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR regcomp (), +.BR regexec () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR regerror () +T} Thread safety MT-Safe env +T{ +.na +.nh +.BR regfree () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Prior to POSIX.1-2008, +.I regoff_t +was required to be +capable of storing the largest value that can be stored in either an +.I off_t +type or a +.I ssize_t +type. +.SH CAVEATS +.I re_nsub +is only required to be initialized if +.B REG_NOSUB +wasn't specified, but all known implementations initialize it regardless. +.\" glibc, musl, 4.4BSD, illumos +.P +Both +.I regex_t +and +.I regmatch_t +may (and do) have more members, in any order. +Always reference them by name. +.\" illumos has two more start/end pairs and the first one is of pointers +.SH EXAMPLES +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <regex.h> +\& +#define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +static const char *const str = + "1) John Driverhacker;\en2) John Doe;\en3) John Foo;\en"; +static const char *const re = "John.*o"; +\& +int main(void) +{ + static const char *s = str; + regex_t regex; + regmatch_t pmatch[1]; + regoff_t off, len; +\& + if (regcomp(®ex, re, REG_NEWLINE)) + exit(EXIT_FAILURE); +\& + printf("String = \e"%s\e"\en", str); + printf("Matches:\en"); +\& + for (unsigned int i = 0; ; i++) { + if (regexec(®ex, s, ARRAY_SIZE(pmatch), pmatch, 0)) + break; +\& + off = pmatch[0].rm_so + (s \- str); + len = pmatch[0].rm_eo \- pmatch[0].rm_so; + printf("#%zu:\en", i); + printf("offset = %jd; length = %jd\en", (intmax_t) off, + (intmax_t) len); + printf("substring = \e"%.*s\e"\en", len, s + pmatch[0].rm_so); +\& + s += pmatch[0].rm_eo; + } +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR grep (1), +.BR regex (7) +.P +The glibc manual section, +.I "Regular Expressions" diff --git a/man/man3/regexec.3 b/man/man3/regexec.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regexec.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regfree.3 b/man/man3/regfree.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regfree.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/register_printf_modifier.3 b/man/man3/register_printf_modifier.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_modifier.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/register_printf_specifier.3 b/man/man3/register_printf_specifier.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_specifier.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/register_printf_type.3 b/man/man3/register_printf_type.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_type.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/registerrpc.3 b/man/man3/registerrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/registerrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/remainder.3 b/man/man3/remainder.3 new file mode 100644 index 0000000..430e81c --- /dev/null +++ b/man/man3/remainder.3 @@ -0,0 +1,234 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" Modified 2003-11-18, 2004-10-05 aeb +.\" +.TH remainder 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drem, dremf, dreml, remainder, remainderf, remainderl \- \ +floating-point remainder function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double remainder(double " x ", double " y ); +.BI "float remainderf(float " x ", float " y ); +.BI "long double remainderl(long double " x ", long double " y ); +.P +/* Obsolete synonyms */ +.BI "[[deprecated]] double drem(double " x ", double " y ); +.BI "[[deprecated]] float dremf(float " x ", float " y ); +.BI "[[deprecated]] long double dreml(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR remainder (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR remainderf (), +.BR remainderl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR drem (), +.BR dremf (), +.BR dreml (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These +functions compute the remainder of dividing +.I x +by +.IR y . +The return value is +\fIx\fP\-\fIn\fP*\fIy\fP, +where +.I n +is the value +.IR "x\ /\ y" , +rounded to the nearest integer. +If the absolute value of +\fIx\fP\-\fIn\fP*\fIy\fP +is 0.5, +.I n +is chosen to be even. +.P +These functions are unaffected by the current rounding mode (see +.BR fenv (3)). +.P +The +.BR drem () +function does precisely the same thing. +.SH RETURN VALUE +On success, these +functions return the floating-point remainder, +\fIx\fP\-\fIn\fP*\fIy\fP. +If the return value is 0, it has the sign of +.IR x . +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +.\" FIXME . Instead, glibc gives a domain error even if x is a NaN +and +.I x +is not a NaN, +.\" Interestingly, remquo(3) does not have the same problem. +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.IP +These functions do not set +.I errno +for this case. +.TP +Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drem (), +.BR dremf (), +.BR dreml (), +.BR remainder (), +.BR remainderf (), +.BR remainderl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.\" IEC 60559. +.TP +.BR remainder () +.TQ +.BR remainderf () +.TQ +.BR remainderl () +C11, POSIX.1-2008. +.TP +.BR drem () +.TQ +.BR dremf () +.TQ +.BR dreml () +None. +.SH HISTORY +.\" IEC 60559. +.TP +.BR remainder () +.TQ +.BR remainderf () +.TQ +.BR remainderl () +C99, POSIX.1-2001. +.TP +.BR drem () +4.3BSD. +.TP +.BR dremf () +.TQ +.BR dreml () +Tru64, glibc2. +.SH BUGS +Before glibc 2.15, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779 +the call +.P +.in +4n +.EX +remainder(nan(""), 0); +.EE +.in +.P +returned a NaN, as expected, but wrongly caused a domain error. +Since glibc 2.15, a silent NaN (i.e., no domain error) is returned. +.P +Before glibc 2.15, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6783 +.I errno +was not set to +.B EDOM +for the domain error that occurs when +.I x +is an infinity and +.I y +is not a NaN. +.SH EXAMPLES +The call "remainder(29.0, 3.0)" returns \-1. +.SH SEE ALSO +.BR div (3), +.BR fmod (3), +.BR remquo (3) diff --git a/man/man3/remainderf.3 b/man/man3/remainderf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/remainderf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/remainderl.3 b/man/man3/remainderl.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/remainderl.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/remove.3 b/man/man3/remove.3 new file mode 100644 index 0000000..b6bedf1 --- /dev/null +++ b/man/man3/remove.3 @@ -0,0 +1,93 @@ +'\" t +.\" This file is derived from unlink.2, which has the following copyright: +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Ian Jackson. +.\" +.\" Edited into remove.3 shape by: +.\" Graeme W. Wilford (G.Wilford@ee.surrey.ac.uk) on 13th July 1994 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH remove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +remove \- remove a file or directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int remove(const char *" pathname ); +.fi +.SH DESCRIPTION +.BR remove () +deletes a name from the filesystem. +It calls +.BR unlink (2) +for files, and +.BR rmdir (2) +for directories. +.P +If the removed name was the +last link to a file and no processes have the file open, the file is +deleted and the space it was using is made available for reuse. +.P +If the name was the last link to a file, +but any processes still have the file open, +the file will remain in existence until the last file +descriptor referring to it is closed. +.P +If the name referred to a symbolic link, the link is removed. +.P +If the name referred to a socket, FIFO, or device, the name is removed, +but processes which have the object open may continue to use it. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The errors that occur are those for +.BR unlink (2) +and +.BR rmdir (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR remove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, 4.3BSD. +.\" .SH NOTES +.\" Under libc4 and libc5, +.\" .BR remove () +.\" was an alias for +.\" .BR unlink (2) +.\" (and hence would not remove directories). +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR unlink (1), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR unlink (2), +.BR mkfifo (3), +.BR symlink (7) diff --git a/man/man3/remque.3 b/man/man3/remque.3 new file mode 100644 index 0000000..a0c8836 --- /dev/null +++ b/man/man3/remque.3 @@ -0,0 +1 @@ +.so man3/insque.3 diff --git a/man/man3/remquo.3 b/man/man3/remquo.3 new file mode 100644 index 0000000..4a78671 --- /dev/null +++ b/man/man3/remquo.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" polished, aeb +.\" +.TH remquo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +remquo, remquof, remquol \- remainder and part of quotient +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double remquo(double " x ", double " y ", int *" quo ); +.BI "float remquof(float " x ", float " y ", int *" quo ); +.BI "long double remquol(long double " x ", long double " y ", int *" quo ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR remquo (), +.BR remquof (), +.BR remquol (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions compute the remainder and part of the quotient +upon division of +.I x +by +.IR y . +A few bits of the quotient are stored via the +.I quo +pointer. +The remainder is returned as the function result. +.P +The value of the remainder is the same as that computed by the +.BR remainder (3) +function. +.P +The value stored via the +.I quo +pointer has the sign of +.I x\~/\~y +and agrees with the quotient in at least the low order 3 bits. +.P +For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2. +Note that the actual quotient might not fit in an integer. +.\" A possible application of this function might be the computation +.\" of sin(x). Compute remquo(x, pi/2, &quo) or so. +.\" +.\" glibc, UnixWare: return 3 bits +.\" MacOS 10: return 7 bits +.SH RETURN VALUE +On success, these functions return the same value as +the analogous functions described in +.BR remainder (3). +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +and +.I x +is not a NaN, +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity or \fIy\fP is 0, \ +and the other argument is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6802 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR remquo (), +.BR remquof (), +.BR remquol () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fmod (3), +.BR logb (3), +.BR remainder (3) diff --git a/man/man3/remquof.3 b/man/man3/remquof.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man/man3/remquof.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man/man3/remquol.3 b/man/man3/remquol.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man/man3/remquol.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man/man3/res_init.3 b/man/man3/res_init.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_init.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_mkquery.3 b/man/man3/res_mkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_mkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nclose.3 b/man/man3/res_nclose.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nclose.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_ninit.3 b/man/man3/res_ninit.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_ninit.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nmkquery.3 b/man/man3/res_nmkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nmkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nquery.3 b/man/man3/res_nquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nquerydomain.3 b/man/man3/res_nquerydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nquerydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nsearch.3 b/man/man3/res_nsearch.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nsearch.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nsend.3 b/man/man3/res_nsend.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nsend.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_query.3 b/man/man3/res_query.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_query.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_querydomain.3 b/man/man3/res_querydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_querydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_search.3 b/man/man3/res_search.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_search.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_send.3 b/man/man3/res_send.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_send.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/resolver.3 b/man/man3/resolver.3 new file mode 100644 index 0000000..cc5f404 --- /dev/null +++ b/man/man3/resolver.3 @@ -0,0 +1,511 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH resolver 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, +res_nclose, +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +dn_comp, dn_expand \- +resolver routines +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include <netinet/in.h> +.B #include <arpa/nameser.h> +.B #include <resolv.h> +.P +.B struct __res_state; +.B typedef struct __res_state *res_state; +.P +.BI "int res_ninit(res_state " statep ); +.P +.BI "void res_nclose(res_state " statep ); +.P +.BI "int res_nquery(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nsearch(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nquerydomain(res_state " statep , +.BI " const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.BI "int res_nmkquery(res_state " statep , +.BI " int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.BI "int res_nsend(res_state " statep , +.BI " const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ], +.BI " int " length ", unsigned char **" dnptrs , +.BI " unsigned char **" lastdnptr ); +.P +.BI "int dn_expand(const unsigned char *" msg , +.BI " const unsigned char *" eomorig , +.BI " const unsigned char *" comp_dn ", char " exp_dn [. length ], +.BI " int " length ); +.P +.B [[deprecated]] extern struct __res_state _res; +.P +.B [[deprecated]] int res_init(void); +.P +.B [[deprecated]] +.BI "int res_query(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_search(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_querydomain(const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.B [[deprecated]] +.BI "int res_mkquery(int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.B [[deprecated]] +.BI "int res_send(const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.fi +.SH DESCRIPTION +.B Note: +This page is incomplete (various resolver functions provided by glibc +are not described) and likely out of date. +.P +The functions described below make queries to and interpret +the responses from Internet domain name servers. +.P +The API consists of a set of more modern, reentrant functions +and an older set of nonreentrant functions that have been superseded. +The traditional resolver interfaces such as +.BR res_init () +and +.BR res_query () +use some static (global) state stored in the +.I _res +structure, rendering these functions non-thread-safe. +BIND 8.2 introduced a set of new interfaces +.BR res_ninit (), +.BR res_nquery (), +and so on, which take a +.I res_state +as their first argument, so you can use a per-thread resolver state. +.P +The +.BR res_ninit () +and +.BR res_init () +functions read the configuration files (see +.BR resolv.conf (5)) +to get the default domain name and name +server address(es). +If no server is given, the local host is tried. +If no domain is given, that associated with the local host is used. +It can be overridden with the environment variable +.BR LOCALDOMAIN . +.BR res_ninit () +or +.BR res_init () +is normally executed by the first call to one of the +other functions. +Every call to +.BR res_ninit () +requires a corresponding call to +.BR res_nclose () +to free memory allocated by +.BR res_ninit () +and subsequent calls to +.BR res_nquery (). +.P +The +.BR res_nquery () +and +.BR res_query () +functions query the name server for the +fully qualified domain name \fIname\fP of specified \fItype\fP and +\fIclass\fP. +The reply is left in the buffer \fIanswer\fP of length +\fIanslen\fP supplied by the caller. +.P +The +.BR res_nsearch () +and +.BR res_search () +functions make a query and waits for the response like +.BR res_nquery () +and +.BR res_query (), +but in addition they implement the default and search +rules controlled by +.B RES_DEFNAMES +and +.B RES_DNSRCH +(see description of +\fI_res\fP options below). +.P +The +.BR res_nquerydomain () +and +.BR res_querydomain () +functions make a query using +.BR res_nquery ()/ res_query () +on the concatenation of \fIname\fP and \fIdomain\fP. +.P +The following functions are lower-level routines used by +.BR res_nquery ()/ res_query (). +.P +The +.BR res_nmkquery () +and +.BR res_mkquery () +functions construct a query message in \fIbuf\fP +of length \fIbuflen\fP for the domain name \fIdname\fP. +The query type +\fIop\fP is one of the following (typically +.BR QUERY ): +.TP +.B QUERY +Standard query. +.TP +.B IQUERY +Inverse query. +This option was removed in glibc 2.26, +.\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244 +since it has not been supported by DNS servers for a very long time. +.TP +.B NS_NOTIFY_OP +Notify secondary of SOA (Start of Authority) change. +.P +\fInewrr\fP is currently unused. +.P +The +.BR res_nsend () +and +.BR res_send () +function send a preformatted query given in +\fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP +which is of length \fIanslen\fP. +They will call +.BR res_ninit ()/ res_init () +if it has not already been called. +.P +The +.BR dn_comp () +function compresses the domain name \fIexp_dn\fP +and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. +The compression uses an array of pointers \fIdnptrs\fP to previously +compressed names in the current message. +The first pointer points +to the beginning of the message and the list ends with NULL. +The limit of the array is specified by \fIlastdnptr\fP. +If \fIdnptr\fP is NULL, domain names are not compressed. +If \fIlastdnptr\fP is NULL, the list +of labels is not updated. +.P +The +.BR dn_expand () +function expands the compressed domain name +\fIcomp_dn\fP to a full domain name, which is placed in the buffer +\fIexp_dn\fP of size \fIlength\fP. +The compressed name is contained +in a query or reply message, and \fImsg\fP points to the beginning of +the message. +.P +The resolver routines use configuration and state information +contained in a +.I __res_state +structure (either passed as the +.I statep +argument, or in the global variable +.IR _res , +in the case of the older nonreentrant functions). +The only field of this structure that is normally manipulated by the +user is the +.I options +field. +This field can contain the bitwise "OR" +of the following options: +.TP +.B RES_INIT +True if +.BR res_ninit () +or +.BR res_init () +has been called. +.TP +.B RES_DEBUG +Print debugging messages. +This option is available only if glibc was built with debugging enabled, +.\" See resolv/README. +.\" Support for RES_DEBUG was made conditional in glibc 2.2. +which is not the default. +.TP +.BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)" +Accept authoritative answers only. +.BR res_send () +continues until +it finds an authoritative answer or returns an error. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_USEVC +Use TCP connections for queries rather than UDP datagrams. +.TP +.BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)" +Query primary domain name server only. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_IGNTC +Ignore truncation errors. +Don't retry with TCP. +.TP +.B RES_RECURSE +Set the recursion desired bit in queries. +Recursion is carried out +by the domain name server, not by +.BR res_send (). +[Enabled by default]. +.TP +.B RES_DEFNAMES +If set, +.BR res_search () +will append the default domain name to +single component names\[em]that is, those that do not contain a dot. +[Enabled by default]. +.TP +.B RES_STAYOPEN +Used with +.B RES_USEVC +to keep the TCP connection open between queries. +.TP +.B RES_DNSRCH +If set, +.BR res_search () +will search for hostnames in the current +domain and in parent domains. +This option is used by +.BR gethostbyname (3). +[Enabled by default]. +.TP +.B RES_INSECURE1 +Accept a response from a wrong server. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_INSECURE2 +Accept a response which contains a wrong query. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_NOALIASES +Disable usage of +.B HOSTALIASES +environment variable. +.TP +.B RES_USE_INET6 +Try an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records +are found but an A record set exists. +Since glibc 2.25, this option is deprecated, +and its usage produces a warning; +applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.B RES_ROTATE +Causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every +time. +.TP +.BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)" +Disable the modern BIND checking of incoming hostnames and mail names +for invalid characters such as underscore (_), non-ASCII, +or control characters. +This option was present until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)" +Do not strip TSIG records. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)" +Send each query simultaneously and recursively to all servers. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_USEBSTRING " (glibc 2.3.4 to glibc 2.24)" +Make reverse IPv6 lookups using the bit-label format described in RFC 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)" +Use +.I ip6.arpa +zone in IPv6 reverse lookup instead of +.IR ip6.int , +which is deprecated since glibc 2.3.4. +This option is present up to and including glibc 2.24, +where it is enabled by default. +In glibc 2.25, this option was removed. +.TP +.BR RES_USE_EDNS0 " (since glibc 2.6)" +Enables support for the DNS extensions (EDNS0) described in RFC 2671. +.TP +.BR RES_SNGLKUP " (since glibc 2.10)" +By default, glibc performs IPv4 and IPv6 lookups in parallel +since glibc 2.9. +Some appliance DNS servers cannot handle these queries properly +and make the requests time out. +This option disables the behavior and makes glibc +perform the IPv6 and IPv4 requests sequentially +(at the cost of some slowdown of the resolving process). +.TP +.B RES_SNGLKUPREOP +When +.B RES_SNGLKUP +option is enabled, opens a new socket for the each request. +.TP +.B RES_USE_DNSSEC +Use DNSSEC with OK bit in OPT record. +This option implies +.BR RES_USE_EDNS0 . +.TP +.B RES_NOTLDQUERY +Do not look up unqualified name as a top-level domain (TLD). +.TP +.B RES_DEFAULT +Default option which implies: +.BR RES_RECURSE , +.BR RES_DEFNAMES , +.BR RES_DNSRCH , +and +.BR RES_NOIP6DOTINT . +.\" +.SH RETURN VALUE +The +.BR res_ninit () +and +.BR res_init () +functions return 0 on success, or \-1 if an error +occurs. +.P +The +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +.BR res_querydomain (), +.BR res_nmkquery (), +.BR res_mkquery (), +.BR res_nsend (), +and +.BR res_send () +functions return the length +of the response, or \-1 if an error occurs. +.P +The +.BR dn_comp () +and +.BR dn_expand () +functions return the length +of the compressed name, or \-1 if an error occurs. +.P +In the case of an error return from +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +or +.BR res_querydomain (), +the global variable +.I h_errno +(see +.BR gethostbyname (3)) +can be consulted to determine the cause of the error. +.SH FILES +.TP +.I /etc/resolv.conf +resolver configuration file +.TP +.I /etc/host.conf +resolver configuration file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR res_ninit (), +.BR res_nclose (), +.BR res_nquery (), +.BR res_nsearch (), +.BR res_nquerydomain (), +.BR res_nsend () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR res_nmkquery (), +.BR dn_comp (), +.BR dn_expand () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.P +The GNU C library source file +.IR resolv/README . diff --git a/man/man3/rewind.3 b/man/man3/rewind.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/rewind.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/rewinddir.3 b/man/man3/rewinddir.3 new file mode 100644 index 0000000..74ab903 --- /dev/null +++ b/man/man3/rewinddir.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH rewinddir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rewinddir \- reset directory stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <dirent.h> +.P +.BI "void rewinddir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR rewinddir () +function resets the position of the directory +stream +.I dirp +to the beginning of the directory. +.SH RETURN VALUE +The +.BR rewinddir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rewinddir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/rexec.3 b/man/man3/rexec.3 new file mode 100644 index 0000000..7b6c839 --- /dev/null +++ b/man/man3/rexec.3 @@ -0,0 +1,161 @@ +'\" t +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)rexec.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD: src/lib/libcompat/4.3/rexec.3,v 1.12 2004/07/02 23:52:14 ru Exp $ +.\" +.\" Taken from FreeBSD 5.4; not checked against Linux reality (mtk) +.\" +.\" 2013-06-21, mtk, Converted from mdoc to man macros +.\" +.TH rexec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rexec, rexec_af \- return stream to a remote command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.B [[deprecated]] +.BI "int rexec(char **restrict " ahost ", int " inport , +.BI " const char *restrict " user ", const char *restrict " passwd , +.BI " const char *restrict " cmd ", int *restrict " fd2p ); +.P +.B [[deprecated]] +.BI "int rexec_af(char **restrict " ahost ", int " inport , +.BI " const char *restrict " user ", const char *restrict " passwd , +.BI " const char *restrict " cmd ", int *restrict " fd2p , +.BI " sa_family_t " af ); +.fi +.P +.BR rexec (), +.BR rexec_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +This interface is obsoleted by +.BR rcmd (3). +.P +The +.BR rexec () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *ahost +is set to the standard name of the host. +If a username and password are both specified, then these +are used to authenticate to the foreign host; otherwise +the environment and then the +.I .netrc +file in user's +home directory are searched for appropriate information. +If all this fails, the user is prompted for the information. +.P +The port +.I inport +specifies which well-known DARPA Internet port to use for +the connection; the call +.I "getservbyname(""exec"", ""tcp"")" +(see +.BR getservent (3)) +will return a pointer to a structure that contains the necessary port. +The protocol for connection is described in detail in +.BR rexecd (8). +.P +If the connection succeeds, +a socket in the Internet domain of type +.B SOCK_STREAM +is returned to +the caller, and given to the remote command as +.I stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be setup, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +The diagnostic +information returned does not include remote authorization failure, +as the secondary connection is set up after authorization has been +verified. +If +.I fd2p +is 0, then the +.I stderr +(unit 2 of the remote +command) will be made the same as the +.I stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.SS rexec_af() +The +.BR rexec () +function works over IPv4 +.RB ( AF_INET ). +By contrast, the +.BR rexec_af () +function provides an extra argument, +.IR af , +that allows the caller to select the protocol. +This argument can be specified as +.BR AF_INET , +.BR AF_INET6 , +or +.B AF_UNSPEC +(to allow the implementation to select the protocol). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rexec (), +.BR rexec_af () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR rexec () +4.2BSD, BSD, Solaris. +.TP +.BR rexec_af () +glibc 2.2. +.SH BUGS +The +.BR rexec () +function sends the unencrypted password across the network. +.P +The underlying service is considered a big security hole and therefore +not enabled on many sites; see +.BR rexecd (8) +for explanations. +.SH SEE ALSO +.BR rcmd (3), +.BR rexecd (8) diff --git a/man/man3/rexec_af.3 b/man/man3/rexec_af.3 new file mode 100644 index 0000000..517a2d2 --- /dev/null +++ b/man/man3/rexec_af.3 @@ -0,0 +1 @@ +.so man3/rexec.3 diff --git a/man/man3/rindex.3 b/man/man3/rindex.3 new file mode 100644 index 0000000..a9cd4b3 --- /dev/null +++ b/man/man3/rindex.3 @@ -0,0 +1 @@ +.so man3/index.3 diff --git a/man/man3/rint.3 b/man/man3/rint.3 new file mode 100644 index 0000000..87538b0 --- /dev/null +++ b/man/man3/rint.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH rint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round +to nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double nearbyint(double " x ); +.BI "float nearbyintf(float " x ); +.BI "long double nearbyintl(long double " x ); +.P +.BI "double rint(double " x ); +.BI "float rintf(float " x ); +.BI "long double rintl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nearbyint (), +.BR nearbyintf (), +.BR nearbyintl (): +.nf + _POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE +.fi +.P +.BR rint (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR rintf (), +.BR rintl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR nearbyint (), +.BR nearbyintf (), +and +.BR nearbyintl () +functions round their argument to an integer value in floating-point +format, using the current rounding direction (see +.BR fesetround (3)) +and without raising the +.I inexact +exception. +When the current rounding direction is to nearest, these +functions round halfway cases to the even integer in accordance with +IEEE-754. +.P +The +.BR rint (), +.BR rintf (), +and +.BR rintl () +functions do the same, but will raise the +.I inexact +exception +.RB ( FE_INEXACT , +checkable via +.BR fetestexcept (3)) +when the result differs in value from the argument. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nearbyint (), +.BR nearbyintf (), +.BR nearbyintl (), +.BR rint (), +.BR rintf (), +.BR rintl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lrint (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/rintf.3 b/man/man3/rintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/rintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/rintl.3 b/man/man3/rintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/rintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/round.3 b/man/man3/round.3 new file mode 100644 index 0000000..86bc373 --- /dev/null +++ b/man/man3/round.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH round 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +round, roundf, roundl \- round to nearest integer, away from zero +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double round(double " x ); +.BI "float roundf(float " x ); +.BI "long double roundl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR round (), +.BR roundf (), +.BR roundl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round +.I x +to the nearest integer, but +round halfway cases away from zero (regardless of the current rounding +direction, see +.BR fenv (3)), +instead of to the nearest even integer like +.BR rint (3). +.P +For example, +.I round(0.5) +is 1.0, and +.I round(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR round (), +.BR roundf (), +.BR roundl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +POSIX.1-2001 contains text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lround (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR trunc (3) diff --git a/man/man3/roundf.3 b/man/man3/roundf.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man/man3/roundf.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man/man3/roundl.3 b/man/man3/roundl.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man/man3/roundl.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man/man3/roundup.3 b/man/man3/roundup.3 new file mode 100644 index 0000000..4265e96 --- /dev/null +++ b/man/man3/roundup.3 @@ -0,0 +1,56 @@ +.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH roundup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +roundup \- round up in steps +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <sys/param.h> +.P +.BI roundup( x ", " step ); +.fi +.SH DESCRIPTION +This macro rounds +.I x +to the nearest multiple of +.I step +that is not less than +.IR x . +.P +It is typically used for +rounding up a pointer to align it or +increasing a buffer to be allocated. +.P +This API is not designed to be generic, +and doesn't work in some cases +that are not important for the typical use cases described above. +See CAVEATS. +.SH RETURN VALUE +This macro returns the rounded value. +.SH STANDARDS +None. +.SH CAVEATS +The arguments may be evaluated more than once. +.P +.I x +should be nonnegative, +and +.I step +should be positive. +.P +If +.I x + step +would overflow or wrap around, +the behavior is undefined. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR rint (3), +.BR lround (3), +.BR round (3) diff --git a/man/man3/rpc.3 b/man/man3/rpc.3 new file mode 100644 index 0000000..3de9704 --- /dev/null +++ b/man/man3/rpc.3 @@ -0,0 +1,1201 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH rpc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rpc \- library routines for remote procedure calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS AND DESCRIPTION +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a reply. +Finally, the procedure call returns to the client. +.\" .P +.\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05 +.\" Routines that are used for Secure RPC (DES authentication) are described in +.\" .BR rpc_secure (3). +.\" Secure RPC can be used only if DES encryption is available. +.P +To take use of these routines, include the header file +.IR "<rpc/rpc.h>" . +.P +The prototypes below make use of the following types: +.P +.RS 4 +.EX +.BI "typedef int " bool_t ; +.P +.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *, ...);" +.P +.BI "typedef bool_t (*" resultproc_t ")(caddr_t " resp , +.BI " struct sockaddr_in *" raddr ); +.EE +.RE +.P +See the header files for the declarations of the +.IR AUTH , +.IR CLIENT , +.IR SVCXPRT , +and +.I XDR +types. +.P +.nf +.BI "void auth_destroy(AUTH *" auth ); +.fi +.IP +A macro that destroys the authentication information associated with +.IR auth . +Destruction usually involves deallocation of private data structures. +The use of +.I auth +is undefined after calling +.BR auth_destroy (). +.P +.nf +.B AUTH *authnone_create(void); +.fi +.IP +Create and return an RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. +This is the default authentication used by RPC. +.P +.nf +.BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid , +.BI " int " len ", gid_t " aup_gids [. len ]); +.fi +.IP +Create and return an RPC authentication handle that contains +authentication information. +The parameter +.I host +is the name of the machine on which the information was created; +.I uid +is the user's user ID; +.I gid +is the user's current group ID; +.I len +and +.I aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.P +.nf +.B AUTH *authunix_create_default(void); +.fi +.IP +Calls +.BR authunix_create () +with the appropriate parameters. +.P +.nf +.BI "int callrpc(char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", const char *" in , +.BI " xdrproc_t " outproc ", char *" out ); +.fi +.IP +Call the remote procedure associated with +.IR prognum , +.IR versnum , +and +.I procnum +on the machine, +.IR host . +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.B "enum clnt_stat" +cast to an integer if it fails. +The routine +.BR clnt_perrno () +is handy for translating failure statuses into messages. +.IP +Warning: calling remote procedures with this routine +uses UDP/IP as a transport; see +.BR clntudp_create () +for restrictions. +You do not have control of timeouts or authentication using this routine. +.P +.nf +.BI "enum clnt_stat clnt_broadcast(unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " resultproc_t " eachresult ); +.fi +.IP +Like +.BR callrpc (), +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a response, this routine calls +.BR eachresult (), +whose form is: +.IP +.in +4n +.EX +.BI "eachresult(char *" out ", struct sockaddr_in *" addr ); +.EE +.in +.IP +where +.I out +is the same as +.I out +passed to +.BR clnt_broadcast (), +except that the remote procedure's output is decoded there; +.I addr +points to the address of the machine that sent the results. +If +.BR eachresult () +returns zero, +.BR clnt_broadcast () +waits for more replies; otherwise it returns with appropriate status. +.IP +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. +.P +.nf +.BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ); +.fi +.IP +A macro that calls the remote procedure +.I procnum +associated with the client handle, +.IR clnt , +which is obtained with an RPC client creation routine such as +.BR clnt_create (). +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results; +.I tout +is the time allowed for results to come back. +.P +.nf +.BI "clnt_destroy(CLIENT *" clnt ); +.fi +.IP +A macro that destroys the client's RPC handle. +Destruction usually involves deallocation +of private data structures, including +.I clnt +itself. +Use of +.I clnt +is undefined after calling +.BR clnt_destroy (). +If the RPC library opened the associated socket, it will close it also. +Otherwise, the socket remains open. +.P +.nf +.BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog , +.BI " unsigned long " vers ", const char *" proto ); +.fi +.IP +Generic client creation routine. +.I host +identifies the name of the remote host where the server is located. +.I proto +indicates which kind of transport protocol to use. +The currently supported values for this field are \[lq]udp\[rq] +and \[lq]tcp\[rq]. +Default timeouts are set, but can be modified using +.BR clnt_control (). +.IP +Warning: using UDP has its shortcomings. +Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data, +this transport cannot be used for procedures that take +large arguments or return huge results. +.P +.nf +.BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info ); +.fi +.IP +A macro used to change or retrieve various information +about a client object. +.I req +indicates the type of operation, and +.I info +is a pointer to the information. +For both UDP and TCP, the supported values of +.I req +and their argument types and what they do are: +.IP +.in +4n +.EX +\fBCLSET_TIMEOUT\fP \fIstruct timeval\fP // set total timeout +\fBCLGET_TIMEOUT\fP \fIstruct timeval\fP // get total timeout +.EE +.in +.IP +Note: if you set the timeout using +.BR clnt_control (), +the timeout parameter passed to +.BR clnt_call () +will be ignored in all future calls. +.IP +.in +4n +.EX +\fBCLGET_SERVER_ADDR\fP \fIstruct sockaddr_in\fP + // get server\[aq]s address +.EE +.in +.IP +The following operations are valid for UDP only: +.IP +.in +4n +.EX +\fBCLSET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // set the retry timeout +\fBCLGET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // get the retry timeout +.EE +.in +.IP +The retry timeout is the time that "UDP RPC" +waits for the server to reply before +retransmitting the request. +.P +.nf +.BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the results of an RPC call. +The parameter +.I out +is the address of the results, and +.I outproc +is the XDR routine describing the results. +This routine returns one if the results were successfully freed, +and zero otherwise. +.P +.nf +.BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp ); +.fi +.IP +A macro that copies the error structure out of the client +handle to the structure at address +.IR errp . +.P +.nf +.BI "void clnt_pcreateerror(const char *" s ); +.fi +.IP +Print a message to standard error indicating why a client RPC +handle could not be created. +The message is prepended with string +.I s +and a colon. +Used when a +.BR clnt_create (), +.BR clntraw_create (), +.BR clnttcp_create (), +or +.BR clntudp_create () +call fails. +.P +.nf +.BI "void clnt_perrno(enum clnt_stat " stat ); +.fi +.IP +Print a message to standard error corresponding +to the condition indicated by +.IR stat . +Used after +.BR callrpc (). +.P +.nf +.BI "clnt_perror(CLIENT *" clnt ", const char *" s ); +.fi +.IP +Print a message to standard error indicating why an RPC call failed; +.I clnt +is the handle used to do the call. +The message is prepended with string +.I s +and a colon. +Used after +.BR clnt_call (). +.P +.nf +.BI "char *clnt_spcreateerror(const char *" s ); +.fi +.IP +Like +.BR clnt_pcreateerror (), +except that it returns a string instead of printing to the standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.P +.nf +.BI "char *clnt_sperrno(enum clnt_stat " stat ); +.fi +.IP +Take the same arguments as +.BR clnt_perrno (), +but instead of sending a message to the standard error indicating why an RPC +call failed, return a pointer to a string which contains the message. +The string ends with a NEWLINE. +.IP +.BR clnt_sperrno () +is used instead of +.BR clnt_perrno () +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the programmer +does not want the message to be output with +.BR printf (3), +or if a message format different than that supported by +.BR clnt_perrno () +is to be used. +Note: unlike +.BR clnt_sperror () +and +.BR clnt_spcreateerror (), +.BR clnt_sperrno () +returns pointer to static data, but the +result will not get overwritten on each call. +.P +.nf +.BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s ); +.fi +.IP +Like +.BR clnt_perror (), +except that (like +.BR clnt_sperrno ()) +it returns a string instead of printing to standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.P +.nf +.BI "CLIENT *clntraw_create(unsigned long " prognum \ +", unsigned long " versnum ); +.fi +.IP +This routine creates a toy RPC client for the remote program +.IR prognum , +version +.IR versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding RPC server should live in the same address space; see +.BR svcraw_create (). +This allows simulation of RPC and acquisition of RPC +overheads, such as round trip times, without any kernel interference. +This routine returns NULL if it fails. +.P +.nf +.BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " int *" sockp ", unsigned int " sendsz \ +", unsigned int " recvsz ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses TCP/IP as a transport. +The remote program is located at Internet address +.IR *addr . +If +.\"The following inline font conversion is necessary for the hyphen indicator +.I addr\->sin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +Since TCP-based RPC uses buffered I/O, +the user may specify the size of the send and receive buffers +with the parameters +.I sendsz +and +.IR recvsz ; +values of zero choose suitable defaults. +This routine returns NULL if it fails. +.P +.nf +.BI "CLIENT *clntudp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +Warning: since UDP-based RPC messages can hold only up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.P +.nf +.BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp , +.BI " unsigned int " sendsize ", unsigned int "recosize ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +on +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +This allows the user to specify the maximum packet +size for sending and receiving UDP-based RPC messages. +.P +.nf +.BI "void get_myaddress(struct sockaddr_in *" addr ); +.fi +.IP +Stuff the machine's IP address into +.IR *addr , +without consulting the library routines that deal with +.IR /etc/hosts . +The port number is always set to +.BR htons(PMAPPORT) . +.P +.nf +.BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr ); +.fi +.IP +A user interface to the +.B portmap +service, which returns a list of the current RPC +program-to-port mappings on the host located at IP address +.IR *addr . +This routine can return NULL. +The command +.I rpcinfo\~\-p +uses this routine. +.P +.nf +.BI "unsigned short pmap_getport(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned int " protocol ); +.fi +.IP +A user interface to the +.B portmap +service, which returns the port number +on which waits a service that supports program number +.IR prognum , +version +.IR versnum , +and speaks the transport protocol associated with +.IR protocol . +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +A return value of zero means that the mapping does not exist +or that the RPC system failed to contact the remote +.B portmap +service. +In the latter case, the global variable +.I rpc_createerr +contains the RPC status. +.P +.nf +.BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ", unsigned long *" portp ); +.fi +.IP +A user interface to the +.B portmap +service, which instructs +.B portmap +on the host at IP address +.I *addr +to make an RPC call on your behalf to a procedure on that host. +The parameter +.I *portp +will be modified to the program's port number if the procedure succeeds. +The definitions of other parameters are discussed +in +.BR callrpc () +and +.BR clnt_call (). +This procedure should be used for a \[lq]ping\[rq] and nothing else. +See also +.BR clnt_broadcast (). +.P +.nf +.BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum , +.BI " int " protocol ", unsigned short " port ); +.fi +.IP +A user interface to the +.B portmap +service, which establishes a mapping between the triple +.RI [ prognum , versnum , protocol ] +and +.I port +on the machine's +.B portmap +service. +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.BR svc_register (). +.P +.nf +.BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +A user interface to the +.B portmap +service, which destroys all mapping between the triple +.RI [ prognum , versnum , * ] +and +.B ports +on the machine's +.B portmap +service. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum ", char *(*" procname ")(char *)," +.BI " xdrproc_t " inproc ", xdrproc_t " outproc ); +.fi +.IP +Register procedure +.I procname +with the RPC service package. +If a request arrives for program +.IR prognum , +version +.IR versnum , +and procedure +.IR procnum , +.I procname +is called with a pointer to its parameter(s); +.I procname +should return a pointer to its static result(s); +.I inproc +is used to decode the parameters while +.I outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 otherwise. +.IP +Warning: remote procedures registered in this form +are accessed using the UDP/IP transport; see +.BR svcudp_create () +for restrictions. +.P +.nf +.BI "struct rpc_createerr " rpc_createerr ; +.fi +.IP +A global variable whose value is set by any RPC client creation routine +that does not succeed. +Use the routine +.BR clnt_pcreateerror () +to print the reason why. +.P +.nf +.BI "void svc_destroy(SVCXPRT *" xprt ); +.fi +.IP +A macro that destroys the RPC service transport handle, +.IR xprt . +Destruction usually involves deallocation +of private data structures, including +.I xprt +itself. +Use of +.I xprt +is undefined after calling this routine. +.P +.nf +.BI "fd_set " svc_fdset ; +.fi +.IP +A global variable reflecting the RPC service side's +read file descriptor bit mask; it is suitable as a parameter to the +.BR select (2) +system call. +This is of interest only if a service implementor does their own +asynchronous event processing, instead of calling +.BR svc_run (). +This variable is read-only (do not pass its address to +.BR select (2)!), +yet it may change after calls to +.BR svc_getreqset () +or any creation routines. +.P +.nf +.BI "int " svc_fds ; +.fi +.IP +Similar to +.BR svc_fdset , +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_fdset . +.P +.nf +.BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the arguments to a service procedure using +.BR svc_getargs (). +This routine returns 1 if the results were successfully freed, +and zero otherwise. +.P +.nf +.BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that decodes the arguments of an RPC request +associated with the RPC service transport handle, +.IR xprt . +The parameter +.I in +is the address where the arguments will be placed; +.I inproc +is the XDR routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero otherwise. +.P +.nf +.BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt ); +.fi +.IP +The approved way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.IR xprt . +.P +.nf +.BI "void svc_getreqset(fd_set *" rdfds ); +.fi +.IP +This routine is of interest only if a service implementor does not call +.BR svc_run (), +but instead implements custom asynchronous event processing. +It is called when the +.BR select (2) +system call has determined that an RPC request has arrived on some +RPC socket(s); +.I rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the value of +.I rdfds +have been serviced. +.P +.nf +.BI "void svc_getreq(int " rdfds ); +.fi +.IP +Similar to +.BR svc_getreqset (), +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_getreqset (). +.P +.nf +.BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum , +.BI " unsigned long " versnum , +.BI " void (*" dispatch ")(struct svc_req *, SVCXPRT *)," +.BI " unsigned long " protocol ); +.fi +.IP +Associates +.I prognum +and +.I versnum +with the service dispatch procedure, +.IR dispatch . +If +.I protocol +is zero, the service is not registered with the +.B portmap +service. +If +.I protocol +is nonzero, then a mapping of the triple +.RI [ prognum , versnum , protocol ] +to +.I xprt\->xp_port +is established with the local +.B portmap +service (generally +.I protocol +is zero, +.B IPPROTO_UDP +or +.BR IPPROTO_TCP ). +The procedure +.I dispatch +has the following form: +.IP +.in +4n +.EX +dispatch(struct svc_req *request, SVCXPRT *xprt); +.EE +.in +.IP +The +.BR svc_register () +routine returns one if it succeeds, and zero otherwise. +.P +.nf +.B "void svc_run(void);" +.fi +.IP +This routine never returns. +It waits for RPC requests to arrive, and calls the appropriate service +procedure using +.BR svc_getreq () +when one arrives. +This procedure is usually waiting for a +.BR select (2) +system call to return. +.P +.nf +.BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \ +", char *" out ); +.fi +.IP +Called by an RPC service's dispatch routine to send the results of a +remote procedure call. +The parameter +.I xprt +is the request's associated transport handle; +.I outproc +is the XDR routine which is used to encode the results; and +.I out +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +Remove all mapping of the double +.RI [ prognum , versnum ] +to dispatch routines, and of the triple +.RI [ prognum , versnum , * ] +to port number. +.P +.nf +.BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.P +.nf +.BI "void svcerr_decode(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that cannot successfully +decode its parameters. +See also +.BR svc_getargs (). +.P +.nf +.BI "void svcerr_noproc(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.P +.nf +.BI "void svcerr_noprog(SVCXPRT *" xprt ); +.fi +.IP +Called when the desired program is not registered with the RPC package. +Service implementors usually do not need this routine. +.P +.nf +.BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers , +.BI " unsigned long " high_vers ); +.fi +.IP +Called when the desired version of a program is not registered +with the RPC package. +Service implementors usually do not need this routine. +.P +.nf +.BI "void svcerr_systemerr(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine when it detects a system +error not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.P +.nf +.BI "void svcerr_weakauth(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient authentication parameters. +The routine calls +.BR "svcerr_auth(xprt, AUTH_TOOWEAK)" . +.P +.nf +.BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize , +.BI " unsigned int " recvsize ); +.fi +.IP +Create a service on top of any open file descriptor. +Typically, this file descriptor is a connected socket for a stream protocol such +as TCP. +.I sendsize +and +.I recvsize +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. +.P +.nf +.B SVCXPRT *svcraw_create(void); +.fi +.IP +This routine creates a toy RPC +service transport, to which it returns a pointer. +The transport is really a buffer within the process's address space, +so the corresponding RPC client should live in the same address space; see +.BR clntraw_create (). +This routine allows simulation of RPC and acquisition of RPC +overheads (such as round trip times), without any kernel interference. +This routine returns NULL if it fails. +.P +.nf +.BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size , +.BI " unsigned int " recv_buf_size ); +.fi +.IP +This routine creates a TCP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local TCP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +Since TCP-based RPC uses buffered I/O, +users may specify the size of buffers; values of zero +choose suitable defaults. +.P +.nf +.BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize , +.BI " unsigned int " recosize ); +.fi +.IP +This routine creates a UDP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local UDP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +.IP +This allows the user to specify the maximum packet size for sending and +receiving UDP-based RPC messages. +.P +.nf +.BI "SVCXPRT *svcudp_create(int " sock ); +.fi +.IP +This call is equivalent to +.I svcudp_bufcreate(sock,SZ,SZ) +for some default size +.IR SZ . +.P +.nf +.BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar ); +.fi +.IP +Used for encoding RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp ); +.fi +.IP +Used for describing UNIX credentials. +This routine is useful for users +who wish to generate these credentials without using the RPC +authentication package. +.P +.nf +.BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr ); +.fi +.IP +Used for describing RPC call header messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg ); +.fi +.IP +Used for describing RPC call messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap ); +.fi +.IP +Used for describing RPC authentication information messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs ); +.fi +.IP +Used for describing parameters to various +.B portmap +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.P +.nf +.BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp ); +.fi +.IP +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.P +.nf +.BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC style messages without using the RPC package. +.P +.nf +.BI "void xprt_register(SVCXPRT *" xprt ); +.fi +.IP +After RPC service transport handles are created, +they should register themselves with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.P +.nf +.BI "void xprt_unregister(SVCXPRT *" xprt ); +.fi +.IP +Before an RPC service transport handle is destroyed, +it should unregister itself with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR auth_destroy (), +.BR authnone_create (), +.BR authunix_create (), +.BR authunix_create_default (), +.BR callrpc (), +.BR clnt_broadcast (), +.BR clnt_call (), +.BR clnt_destroy (), +.BR clnt_create (), +.BR clnt_control (), +.BR clnt_freeres (), +.BR clnt_geterr (), +.BR clnt_pcreateerror (), +.BR clnt_perrno (), +.BR clnt_perror (), +.BR clnt_spcreateerror (), +.BR clnt_sperrno (), +.BR clnt_sperror (), +.BR clntraw_create (), +.BR clnttcp_create (), +.BR clntudp_create (), +.BR clntudp_bufcreate (), +.BR get_myaddress (), +.BR pmap_getmaps (), +.BR pmap_getport (), +.BR pmap_rmtcall (), +.BR pmap_set (), +.BR pmap_unset (), +.BR registerrpc (), +.BR svc_destroy (), +.BR svc_freeargs (), +.BR svc_getargs (), +.BR svc_getcaller (), +.BR svc_getreqset (), +.BR svc_getreq (), +.BR svc_register (), +.BR svc_run (), +.BR svc_sendreply (), +.BR svc_unregister (), +.BR svcerr_auth (), +.BR svcerr_decode (), +.BR svcerr_noproc (), +.BR svcerr_noprog (), +.BR svcerr_progvers (), +.BR svcerr_systemerr (), +.BR svcerr_weakauth (), +.BR svcfd_create (), +.BR svcraw_create (), +.BR svctcp_create (), +.BR svcudp_bufcreate (), +.BR svcudp_create (), +.BR xdr_accepted_reply (), +.BR xdr_authunix_parms (), +.BR xdr_callhdr (), +.BR xdr_callmsg (), +.BR xdr_opaque_auth (), +.BR xdr_pmap (), +.BR xdr_pmaplist (), +.BR xdr_rejected_reply (), +.BR xdr_replymsg (), +.BR xprt_register (), +.BR xprt_unregister () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05 +.\" .BR rpc_secure (3), +.BR xdr (3) +.P +The following manuals: +.RS +Remote Procedure Calls: Protocol Specification +.br +Remote Procedure Call Programming Guide +.br +rpcgen Programming Guide +.br +.RE +.P +.IR "RPC: Remote Procedure Call Protocol Specification" , +RFC\ 1050, Sun Microsystems, Inc., +USC-ISI. diff --git a/man/man3/rpmatch.3 b/man/man3/rpmatch.3 new file mode 100644 index 0000000..5739b82 --- /dev/null +++ b/man/man3/rpmatch.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.\" +.\" 2006-05-19, mtk, various edits and example program +.\" +.TH rpmatch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rpmatch \- determine if the answer to a question is affirmative or negative +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int rpmatch(const char *" response ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR rpmatch (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR rpmatch () +handles a user response to yes or no questions, with +support for internationalization. +.P +.I response +should be a null-terminated string containing a +user-supplied response, perhaps obtained with +.BR fgets (3) +or +.BR getline (3). +.P +The user's language preference is taken into account per the +environment variables +.BR LANG , +.BR LC_MESSAGES , +and +.BR LC_ALL , +if the program has called +.BR setlocale (3) +to effect their changes. +.P +Regardless of the locale, responses matching +.B \[ha][Yy] +are always accepted as affirmative, and those matching +.B \[ha][Nn] +are always accepted as negative. +.SH RETURN VALUE +After examining +.IR response , +.BR rpmatch () +returns 0 for a recognized negative response ("no"), 1 +for a recognized positive response ("yes"), and \-1 when the value +of +.I response +is unrecognized. +.SH ERRORS +A return value of \-1 may indicate either an invalid input, or some +other error. +It is incorrect to only test if the return value is nonzero. +.P +.BR rpmatch () +can fail for any of the reasons that +.BR regcomp (3) +or +.BR regexec (3) +can fail; the cause of the error +is not available from +.I errno +or anywhere else, but indicates a +failure of the regex engine (but this case is indistinguishable from +that of an unrecognized value of +.IR response ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rpmatch () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +GNU, FreeBSD, AIX. +.SH BUGS +The +.BR YESEXPR " and " NOEXPR +of some locales (including "C") only inspect the first character of the +.IR response . +This can mean that "yno" et al. resolve to +.BR 1 . +This is an unfortunate historical side-effect which should be fixed in time +with proper localisation, and should not deter from +.BR rpmatch () +being the proper way to distinguish between binary answers. +.SH EXAMPLES +The following program displays the results when +.BR rpmatch () +is applied to the string given in the program's command-line argument. +.P +.\" SRC BEGIN (rpmatch.c) +.EX +#define _DEFAULT_SOURCE +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s response\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + setlocale(LC_ALL, ""); + printf("rpmatch() returns: %d\en", rpmatch(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fgets (3), +.BR getline (3), +.BR nl_langinfo (3), +.BR regcomp (3), +.BR setlocale (3) diff --git a/man/man3/rresvport.3 b/man/man3/rresvport.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rresvport.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/rresvport_af.3 b/man/man3/rresvport_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rresvport_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/rtime.3 b/man/man3/rtime.3 new file mode 100644 index 0000000..f116831 --- /dev/null +++ b/man/man3/rtime.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2003-04-04 Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de> +.\" +.\" Slightly polished, aeb, 2003-04-06 +.\" +.TH rtime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtime \- get time from a remote machine +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <rpc/auth_des.h>" +.P +.BI "int rtime(struct sockaddr_in *" addrp ", struct rpc_timeval *" timep , +.BI " struct rpc_timeval *" timeout ); +.fi +.SH DESCRIPTION +This function uses the Time Server Protocol as described in +RFC\ 868 to obtain the time from a remote machine. +.P +The Time Server Protocol gives the time in seconds since +00:00:00 UTC, 1 Jan 1900, +and this function subtracts the appropriate constant in order to +convert the result to seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +When +.I timeout +is non-NULL, the udp/time socket (port 37) is used. +Otherwise, the tcp/time socket (port 37) is used. +.SH RETURN VALUE +On success, 0 is returned, and the obtained 32-bit time value is stored in +.IR timep\->tv_sec . +In case of error \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +All errors for underlying functions +.RB ( sendto (2), +.BR poll (2), +.BR recvfrom (2), +.BR connect (2), +.BR read (2)) +can occur. +Moreover: +.TP +.B EIO +The number of returned bytes is not 4. +.TP +.B ETIMEDOUT +The waiting time as defined in timeout has expired. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rtime () +T} Thread safety MT-Safe +.TE +.SH NOTES +Only IPv4 is supported. +.P +Some +.I in.timed +versions support only TCP. +Try the example program with +.I use_tcp +set to 1. +.\" .P +.\" Libc5 uses the prototype +.\" .P +.\" .nf +.\" int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); +.\" .fi +.\" .P +.\" and requires +.\" .I <sys/time.h> +.\" instead of +.\" .IR <rpc/auth_des.h> . +.SH BUGS +.BR rtime () +in glibc 2.2.5 and earlier does not work properly on 64-bit machines. +.SH EXAMPLES +This example requires that port 37 is up and open. +You may check +that the time entry within +.I /etc/inetd.conf +is not commented out. +.P +The program connects to a computer called "linux". +Using "localhost" does not work. +The result is the localtime of the computer "linux". +.P +.\" SRC BEGIN (rtime.c) +.EX +#include <errno.h> +#include <netdb.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> +\& +#include <rpc/auth_des.h> +\& +static int use_tcp = 0; +static const char servername[] = "linux"; +\& +int +main(void) +{ + int ret; + time_t t; + struct hostent *hent; + struct rpc_timeval time1 = {0, 0}; + struct rpc_timeval timeout = {1, 0}; + struct sockaddr_in name; +\& + memset(&name, 0, sizeof(name)); + sethostent(1); + hent = gethostbyname(servername); + memcpy(&name.sin_addr, hent\->h_addr, hent\->h_length); +\& + ret = rtime(&name, &time1, use_tcp ? NULL : &timeout); + if (ret < 0) + perror("rtime error"); + else { + t = time1.tv_sec; + printf("%s\en", ctime(&t)); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.\" .BR netdate (1), +.BR ntpdate (1), +.\" .BR rdate (1), +.BR inetd (8) diff --git a/man/man3/rtnetlink.3 b/man/man3/rtnetlink.3 new file mode 100644 index 0000000..7eaef31 --- /dev/null +++ b/man/man3/rtnetlink.3 @@ -0,0 +1,122 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" +.\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $ +.\" +.TH rtnetlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtnetlink \- macros to manipulate rtnetlink messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <asm/types.h> +.B #include <linux/netlink.h> +.B #include <linux/rtnetlink.h> +.B #include <sys/socket.h> +.P +.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \ +", NETLINK_ROUTE);" +.P +.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); +.P +.BI "void *RTA_DATA(struct rtattr *" rta ); +.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); +.P +.BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \ +", unsigned int " rtabuflen ); +.P +.BI "unsigned int RTA_LENGTH(unsigned int " length ); +.BI "unsigned int RTA_SPACE(unsigned int "length ); +.fi +.SH DESCRIPTION +All +.BR rtnetlink (7) +messages consist of a +.BR netlink (7) +message header and appended attributes. +The attributes should be manipulated only using the macros provided here. +.P +.BI RTA_OK( rta ", " attrlen ) +returns true if +.I rta +points to a valid routing attribute; +.I attrlen +is the running length of the attribute buffer. +When not true then you must assume there are no more attributes in the +message, even if +.I attrlen +is nonzero. +.P +.BI RTA_DATA( rta ) +returns a pointer to the start of this attribute's data. +.P +.BI RTA_PAYLOAD( rta ) +returns the length of this attribute's data. +.P +.BI RTA_NEXT( rta ", " attrlen ) +gets the next attribute after +.IR rta . +Calling this macro will update +.IR attrlen . +You should use +.B RTA_OK +to check the validity of the returned pointer. +.P +.BI RTA_LENGTH( len ) +returns the length which is required for +.I len +bytes of data plus the header. +.P +.BI RTA_SPACE( len ) +returns the amount of space which will be needed in a message with +.I len +bytes of data. +.SH STANDARDS +Linux. +.SH BUGS +This manual page is incomplete. +.SH EXAMPLES +.\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here +Creating a rtnetlink message to set the MTU of a device: +.P +.in +4n +.EX +#include <linux/rtnetlink.h> +\& +\&... +\& +struct { + struct nlmsghdr nh; + struct ifinfomsg if; + char attrbuf[512]; +} req; +\& +struct rtattr *rta; +unsigned int mtu = 1000; +\& +int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); +\& +memset(&req, 0, sizeof(req)); +req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(req.if)); +req.nh.nlmsg_flags = NLM_F_REQUEST; +req.nh.nlmsg_type = RTM_NEWLINK; +req.if.ifi_family = AF_UNSPEC; +req.if.ifi_index = INTERFACE_INDEX; +req.if.ifi_change = 0xffffffff; /* ??? */ +rta = (struct rtattr *)(((char *) &req) + + NLMSG_ALIGN(req.nh.nlmsg_len)); +rta\->rta_type = IFLA_MTU; +rta\->rta_len = RTA_LENGTH(sizeof(mtu)); +req.nh.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) + + RTA_LENGTH(sizeof(mtu)); +memcpy(RTA_DATA(rta), &mtu, sizeof(mtu)); +send(rtnetlink_sk, &req, req.nh.nlmsg_len, 0); +.EE +.in +.SH SEE ALSO +.BR netlink (3), +.BR netlink (7), +.BR rtnetlink (7) diff --git a/man/man3/ruserok.3 b/man/man3/ruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/ruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/ruserok_af.3 b/man/man3/ruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/ruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/scalb.3 b/man/man3/scalb.3 new file mode 100644 index 0000000..754530c --- /dev/null +++ b/man/man3/scalb.3 @@ -0,0 +1,196 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scalb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scalb, scalbf, scalbl \- multiply floating-point number +by integral power of radix (OBSOLETE) +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "[[deprecated]] double scalb(double " x ", double " exp ); +.BI "[[deprecated]] float scalbf(float " x ", float " exp ); +.BI "[[deprecated]] long double scalbl(long double " x ", long double " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scalb (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR scalbf (), +.BR scalbl (): +.nf + _XOPEN_SOURCE >= 600 + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.P +.nf + x * FLT_RADIX ** exp +.fi +.P +The definition of +.B FLT_RADIX +can be obtained by including +.IR <float.h> . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.I x +* +.B FLT_RADIX +** +.IR exp . +.P +If +.I x +or +.I exp +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +and +.I exp +is not negative infinity, +positive infinity (negative infinity) is returned. +.P +If +.I x +is +0 (\-0), and +.I exp +is not positive infinity, +0 (\-0) is returned. +.P +If +.I x +is zero, and +.I exp +is positive infinity, +a domain error occurs, and +a NaN is returned. +.P +If +.I x +is an infinity, +and +.I exp +is negative infinity, +a domain error occurs, and +a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.P +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is 0, and \fIexp\fP is positive infinity, \ +or \fIx\fP is positive infinity and \fIexp\fP is negative infinity \ +and the other argument is not a NaN +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scalb (), +.BR scalbf (), +.BR scalbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR scalb () +4.3BSD. +Obsolescent in POSIX.1-2001; +Removed in POSIX.1-2008, +recommending the use of +.BR scalbln (3), +.BR scalblnf (3), +or +.BR scalblnl (3) +instead. +.\" Looking at header files: scalbf() is present on the +.\" BSDs, Tru64, HP-UX 11, Irix 6.5; scalbl() is on HP-UX 11 and Tru64. +.SH BUGS +Before glibc 2.20, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6803 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6804 +these functions did not set +.I errno +for domain and range errors. +.SH SEE ALSO +.BR ldexp (3), +.BR scalbln (3) diff --git a/man/man3/scalbf.3 b/man/man3/scalbf.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man/man3/scalbf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man/man3/scalbl.3 b/man/man3/scalbl.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man/man3/scalbl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man/man3/scalbln.3 b/man/man3/scalbln.3 new file mode 100644 index 0000000..a7b8f9f --- /dev/null +++ b/man/man3/scalbln.3 @@ -0,0 +1,174 @@ +'\" t +.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>. +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scalbln 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \- +multiply floating-point number by integral power of radix +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double scalbln(double " x ", long " exp ); +.BI "float scalblnf(float " x ", long " exp ); +.BI "long double scalblnl(long double " x ", long " exp ); +.P +.BI "double scalbn(double " x ", int " exp ); +.BI "float scalbnf(float " x ", int " exp ); +.BI "long double scalbnl(long double " x ", int " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE +.fi +.P +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.P +.nf + x * FLT_RADIX ** exp +.fi +.P +The definition of +.B FLT_RADIX +can be obtained by including +.IR <float.h> . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.I x +* +.B FLT_RADIX +** +.IR exp . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.P +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (), +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH HISTORY +These functions differ from the obsolete functions described in +.BR scalb (3) +in the type of their second argument. +The functions described on this page have a second argument +of an integral type, while those in +.BR scalb (3) +have a second argument of type +.IR double . +.SH NOTES +If +.B FLT_RADIX +equals 2 (which is usual), then +.BR scalbn () +is equivalent to +.BR ldexp (3). +.SH BUGS +Before glibc 2.20, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6803 +these functions did not set +.I errno +for range errors. +.SH SEE ALSO +.BR ldexp (3), +.BR scalb (3) diff --git a/man/man3/scalblnf.3 b/man/man3/scalblnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalblnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalblnl.3 b/man/man3/scalblnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalblnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbn.3 b/man/man3/scalbn.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbn.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbnf.3 b/man/man3/scalbnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbnl.3 b/man/man3/scalbnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scandir.3 b/man/man3/scandir.3 new file mode 100644 index 0000000..dff2c6b --- /dev/null +++ b/man/man3/scandir.3 @@ -0,0 +1,310 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:26:16 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 11 17:11:33 1996 by Andries Brouwer (aeb@cwi.nl): +.\" Corrected type of compar routines, as suggested by +.\" Miguel Barreiro (enano@avalon.yaix.es). Added example. +.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen. +.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort. +.\" +.\" The pieces on scandirat(3) were copyright and licensed as follows. +.\" +.\" Copyright (c) 2012, Mark R. Bannister <cambridge@users.sourceforge.net> +.\" based on text in mkfifoat.3 Copyright (c) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH scandir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scandir, scandirat, alphasort, versionsort \- scan +a directory for matching entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "int scandir(const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.P +.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); +.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b ); +.P +.BR "#include <fcntl.h>" " /* Definition of AT_* constants */" +.B #include <dirent.h> +.P +.BI "int scandirat(int " dirfd ", const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scandir (), +.BR alphasort (): +.nf + /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR versionsort (): +.nf + _GNU_SOURCE +.fi +.P +.BR scandirat (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR scandir () +function scans the directory \fIdirp\fP, calling +\fIfilter\fP() on each directory entry. +Entries for which +\fIfilter\fP() returns nonzero are stored in strings allocated via +.BR malloc (3), +sorted using +.BR qsort (3) +with the comparison +function \fIcompar\fP(), and collected in array \fInamelist\fP +which is allocated via +.BR malloc (3). +If \fIfilter\fP is NULL, all entries are selected. +.P +The +.BR alphasort () +and +.BR versionsort () +functions can be used as the comparison function +.IR compar (). +The former sorts directory entries using +.BR strcoll (3), +the latter using +.BR strverscmp (3) +on the strings \fI(*a)\->d_name\fP and \fI(*b)\->d_name\fP. +.SS scandirat() +The +.BR scandirat () +function operates in exactly the same way as +.BR scandir (), +except for the differences described here. +.P +If the pathname given in +.I dirp +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR scandir () +for a relative pathname). +.P +If +.I dirp +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I dirp +is interpreted relative to the current working +directory of the calling process (like +.BR scandir ()). +.P +If +.I dirp +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR scandirat (). +.SH RETURN VALUE +The +.BR scandir () +function returns the number of directory entries +selected. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.P +The +.BR alphasort () +and +.BR versionsort () +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be +respectively less than, equal to, or greater than the second. +.SH ERRORS +.TP +.B EBADF +.RB ( scandirat ()) +.I dirp +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B ENOENT +The path in \fIdirp\fR does not exist. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +The path in \fIdirp\fR is not a directory. +.TP +.B ENOTDIR +.RB ( scandirat ()) +.I dirp +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scandir (), +.BR scandirat () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR alphasort (), +.BR versionsort () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR alphasort () +.TQ +.BR scandir () +POSIX.1-2008. +.TP +.BR versionsort () +.TQ +.BR scandirat () +GNU. +.SH HISTORY +.TP +.BR alphasort () +.TQ +.BR scandir () +4.3BSD, POSIX.1-2008. +.TP +.BR versionsort () +glibc 2.1. +.TP +.BR scandirat () +glibc 2.15. +.\" .P +.\" The functions +.\" .BR scandir () +.\" and +.\" .BR alphasort () +.\" are from 4.3BSD, and have been available under Linux since libc4. +.\" Libc4 and libc5 use the more precise prototype +.\" .sp +.\" .nf +.\" int alphasort(const struct dirent ** a, +.\" const struct dirent **b); +.\" .fi +.\" .sp +.\" but glibc 2.0 returns to the imprecise BSD prototype. +.SH NOTES +Since glibc 2.1, +.BR alphasort () +calls +.BR strcoll (3); +earlier it used +.BR strcmp (3). +.P +Before glibc 2.10, the two arguments of +.BR alphasort () +and +.BR versionsort () +were typed as +.IR "const void\ *" . +When +.BR alphasort () +was standardized in POSIX.1-2008, +the argument type was specified as the type-safe +.IR "const struct dirent\ **", +and glibc 2.10 changed the definition of +.BR alphasort () +(and the nonstandard +.BR versionsort ()) +to match the standard. +.SH EXAMPLES +The program below prints a list of the files in the current directory +in reverse order. +.\" +.SS Program source +\& +.\" SRC BEGIN (scandir.c) +.EX +#define _DEFAULT_SOURCE +#include <dirent.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + struct dirent **namelist; + int n; +\& + n = scandir(".", &namelist, NULL, alphasort); + if (n == \-1) { + perror("scandir"); + exit(EXIT_FAILURE); + } +\& + while (n\-\-) { + printf("%s\en", namelist[n]\->d_name); + free(namelist[n]); + } + free(namelist); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR closedir (3), +.BR fnmatch (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR seekdir (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strverscmp (3), +.BR telldir (3) diff --git a/man/man3/scandirat.3 b/man/man3/scandirat.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/scandirat.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/scanf.3 b/man/man3/scanf.3 new file mode 100644 index 0000000..3855e77 --- /dev/null +++ b/man/man3/scanf.3 @@ -0,0 +1,159 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scanf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scanf, fscanf, vscanf, vfscanf \- input FILE format conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int scanf(const char *restrict " format ", ...);" +.BI "int fscanf(FILE *restrict " stream , +.BI " const char *restrict " format ", ...);" +.P +.B #include <stdarg.h> +.P +.BI "int vscanf(const char *restrict " format ", va_list " ap ); +.BI "int vfscanf(FILE *restrict " stream , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vscanf (), +.BR vfscanf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR scanf () +family of functions scans formatted input like +.BR sscanf (3), +but read from a +.IR FILE . +It is very difficult to use these functions correctly, +and it is preferable to read entire lines with +.BR fgets (3) +or +.BR getline (3) +and parse them later with +.BR sscanf (3) +or more specialized functions such as +.BR strtol (3). +.P +The +.BR scanf () +function reads input from the standard input stream +.I stdin +and +.BR fscanf () +reads input from the stream pointer +.IR stream . +.P +The +.BR vfscanf () +function is analogous to +.BR vfprintf (3) +and reads input from the stream pointer +.I stream +using a variable argument list of pointers (see +.BR stdarg (3). +The +.BR vscanf () +function is analogous to +.BR vprintf (3) +and reads from the standard input. +.SH RETURN VALUE +On success, these functions return the number of input items +successfully matched and assigned; +this can be fewer than provided for, +or even zero, in the event of an early matching failure. +.P +The value +.B EOF +is returned if the end of input is reached before either the first +successful conversion or a matching failure occurs. +.B EOF +is also returned if a read error occurs, +in which case the error indicator for the stream (see +.BR ferror (3)) +is set, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor underlying +.I stream +is marked nonblocking, and the read operation would block. +.TP +.B EBADF +The file descriptor underlying +.I stream +is invalid, or not open for reading. +.TP +.B EILSEQ +Input byte sequence does not form a valid character. +.TP +.B EINTR +The read operation was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +Not enough arguments; or +.I format +is NULL. +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scanf (), +.BR fscanf (), +.BR vscanf (), +.BR vfscanf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH CAVEATS +These functions make it difficult to +distinguish newlines from other white space, +This is especially problematic with line-buffered input, +like the standard input stream. +.P +These functions can't report errors after the last +non-suppressed conversion specification. +.SH BUGS +It is impossible to accurately know +how many characters these functions have consumed from the input stream, +since they only report the number of successful conversions. +For example, +if the input is "123\en\ a", +.I scanf(\[dq]%d\ %d\[dq], &a, &b) +will consume the digits, the newline, and the space, but not the letter a. +This makes it difficult to recover from invalid input. +.SH SEE ALSO +.BR fgets (3), +.BR getline (3), +.BR sscanf (3) diff --git a/man/man3/sched_getcpu.3 b/man/man3/sched_getcpu.3 new file mode 100644 index 0000000..a1c6c67 --- /dev/null +++ b/man/man3/sched_getcpu.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sched_getcpu 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_getcpu \- determine CPU on which the calling thread is running +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sched.h> +.P +.B int sched_getcpu(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sched_getcpu (): +.nf + Since glibc 2.14: + _GNU_SOURCE + Before glibc 2.14: + _BSD_SOURCE || _SVID_SOURCE + /* _GNU_SOURCE also suffices */ +.fi +.SH DESCRIPTION +.BR sched_getcpu () +returns the number of the CPU +on which the calling thread is currently executing. +.SH RETURN VALUE +On success, +.BR sched_getcpu () +returns a nonnegative CPU number. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +This kernel does not implement +.BR getcpu (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sched_getcpu () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.6. +.SH NOTES +The call +.P +.in +4n +.EX +cpu = sched_getcpu(); +.EE +.in +.P +is equivalent to the following +.BR getcpu (2) +call: +.P +.in +4n +.EX +int c, s; +s = getcpu(&c, NULL); +cpu = (s == \-1) ? s : c; +.EE +.in +.SH SEE ALSO +.BR getcpu (2), +.BR sched (7) diff --git a/man/man3/secure_getenv.3 b/man/man3/secure_getenv.3 new file mode 100644 index 0000000..5142bef --- /dev/null +++ b/man/man3/secure_getenv.3 @@ -0,0 +1 @@ +.so man3/getenv.3 diff --git a/man/man3/seed48.3 b/man/man3/seed48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/seed48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/seed48_r.3 b/man/man3/seed48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/seed48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/seekdir.3 b/man/man3/seekdir.3 new file mode 100644 index 0000000..a053f5b --- /dev/null +++ b/man/man3/seekdir.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.TH seekdir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +seekdir \- set the position of the next readdir() call in the directory +stream. +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "void seekdir(DIR *" dirp ", long " loc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR seekdir (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR seekdir () +function sets the location in the directory stream +from which the next +.BR readdir (2) +call will start. +The +.I loc +argument should be a value returned by a previous call to +.BR telldir (3). +.SH RETURN VALUE +The +.BR seekdir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR seekdir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH CAVEATS +Up to glibc 2.1.1, the type of the +.I loc +argument was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +See +.BR telldir (3) +for information on why you should be careful in making any +assumptions about the value in this argument. +.SH SEE ALSO +.BR lseek (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR telldir (3) diff --git a/man/man3/sem_close.3 b/man/man3/sem_close.3 new file mode 100644 index 0000000..46331ac --- /dev/null +++ b/man/man3/sem_close.3 @@ -0,0 +1,63 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_close \- close a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_close(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_close () +closes the named semaphore referred to by +.IR sem , +allowing any resources that the system has allocated to +the calling process for this semaphore to be freed. +.SH RETURN VALUE +On success +.BR sem_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +All open named semaphores are automatically closed on process +termination, or upon +.BR execve (2). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_destroy.3 b/man/man3/sem_destroy.3 new file mode 100644 index 0000000..6675537 --- /dev/null +++ b/man/man3/sem_destroy.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_destroy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_destroy \- destroy an unnamed semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_destroy(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_destroy () +destroys the unnamed semaphore at the address pointed to by +.IR sem . +.P +Only a semaphore that has been initialized by +.BR sem_init (3) +should be destroyed using +.BR sem_destroy (). +.P +Destroying a semaphore that other processes or threads are +currently blocked on (in +.BR sem_wait (3)) +produces undefined behavior. +.P +Using a semaphore that has been destroyed produces undefined results, +until the semaphore has been reinitialized using +.BR sem_init (3). +.SH RETURN VALUE +.BR sem_destroy () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_destroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +An unnamed semaphore should be destroyed with +.BR sem_destroy () +before the memory in which it is located is deallocated. +Failure to do this can result in resource leaks on some implementations. +.\" But not on NPTL, where sem_destroy () is a no-op.. +.SH SEE ALSO +.BR sem_init (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_getvalue.3 b/man/man3/sem_getvalue.3 new file mode 100644 index 0000000..bfadd47 --- /dev/null +++ b/man/man3/sem_getvalue.3 @@ -0,0 +1,74 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_getvalue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_getvalue \- get the value of a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_getvalue(sem_t *restrict " sem ", int *restrict " sval ); +.fi +.SH DESCRIPTION +.BR sem_getvalue () +places the current value of the semaphore pointed to +.I sem +into the integer pointed to by +.IR sval . +.P +If one or more processes or threads are blocked +waiting to lock the semaphore with +.BR sem_wait (3), +POSIX.1 permits two possibilities for the value returned in +.IR sval : +either 0 is returned; +or a negative number whose absolute value is the count +of the number of processes and threads currently blocked in +.BR sem_wait (3). +Linux adopts the former behavior. +.SH RETURN VALUE +.BR sem_getvalue () +returns 0 on success; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +(The glibc implementation currently does not check whether +.I sem +is valid.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_getvalue () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The value of the semaphore may already have changed by the time +.BR sem_getvalue () +returns. +.SH SEE ALSO +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_init.3 b/man/man3/sem_init.3 new file mode 100644 index 0000000..8ea6b64 --- /dev/null +++ b/man/man3/sem_init.3 @@ -0,0 +1,108 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_init \- initialize an unnamed semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value ); +.fi +.SH DESCRIPTION +.BR sem_init () +initializes the unnamed semaphore at the address pointed to by +.IR sem . +The +.I value +argument specifies the initial value for the semaphore. +.P +The +.I pshared +argument indicates whether this semaphore is to be shared +between the threads of a process, or between processes. +.P +If +.I pshared +has the value 0, +then the semaphore is shared between the threads of a process, +and should be located at some address that is visible to all threads +(e.g., a global variable, or a variable allocated dynamically on +the heap). +.P +If +.I pshared +is nonzero, then the semaphore is shared between processes, +and should be located in a region of shared memory (see +.BR shm_open (3), +.BR mmap (2), +and +.BR shmget (2)). +(Since a child created by +.BR fork (2) +inherits its parent's memory mappings, it can also access the semaphore.) +Any process that can access the shared memory region +can operate on the semaphore using +.BR sem_post (3), +.BR sem_wait (3), +and so on. +.P +Initializing a semaphore that has already been initialized +results in undefined behavior. +.SH RETURN VALUE +.BR sem_init () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I value +exceeds +.BR SEM_VALUE_MAX . +.TP +.B ENOSYS +.I pshared +is nonzero, +but the system does not support process-shared semaphores (see +.BR sem_overview (7)). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_init () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Bizarrely, POSIX.1-2001 does not specify the value that should +be returned by a successful call to +.BR sem_init (). +POSIX.1-2008 rectifies this, specifying the zero return on success. +.SH EXAMPLES +See +.BR shm_open (3) +and +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_destroy (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_open.3 b/man/man3/sem_open.3 new file mode 100644 index 0000000..0f29dcf --- /dev/null +++ b/man/man3/sem_open.3 @@ -0,0 +1,175 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_open \- initialize and open a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#include <fcntl.h>" " /* For O_* constants */" +.BR "#include <sys/stat.h>" " /* For mode constants */" +.B #include <semaphore.h> +.P +.BI "sem_t *sem_open(const char *" name ", int " oflag ); +.BI "sem_t *sem_open(const char *" name ", int " oflag , +.BI " mode_t " mode ", unsigned int " value ); +.fi +.SH DESCRIPTION +.BR sem_open () +creates a new POSIX semaphore or opens an existing semaphore. +The semaphore is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR sem_overview (7). +.P +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR <fcntl.h> .) +If +.B O_CREAT +is specified in +.IR oflag , +then the semaphore is created if +it does not already exist. +The owner (user ID) of the semaphore is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +If both +.B O_CREAT +and +.B O_EXCL +are specified in +.IR oflag , +then an error is returned if a semaphore with the given +.I name +already exists. +.P +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new semaphore, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR <sys/stat.h> .) +The permissions settings are masked against the process umask. +Both read and write permission should be granted to each class of +user that will access the semaphore. +The +.I value +argument specifies the initial value for the new semaphore. +If +.B O_CREAT +is specified, and a semaphore with the given +.I name +already exists, then +.I mode +and +.I value +are ignored. +.SH RETURN VALUE +On success, +.BR sem_open () +returns the address of the new semaphore; +this address is used when calling other semaphore-related functions. +On error, +.BR sem_open () +returns +.BR SEM_FAILED , +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The semaphore exists, but the caller does not have permission to +open it. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a semaphore with this +.I name +already exists. +.TP +.B EINVAL +.I value +was greater than +.BR SEM_VALUE_MAX . +.TP +.B EINVAL +.I name +consists of just "/", followed by no other characters. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.I oflag +and no semaphore with this +.I name +exists; +or, +.\" this error can occur if we have a name of the (nonportable) form +.\" /dir/name, and the directory /dev/shm/dir does not exist. +.B O_CREAT +was specified, but +.I name +wasn't well formed. +.TP +.B ENOMEM +Insufficient memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_open () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR sem_close (3), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_post.3 b/man/man3/sem_post.3 new file mode 100644 index 0000000..eb23ef5 --- /dev/null +++ b/man/man3/sem_post.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_post 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_post \- unlock a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_post(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_post () +increments (unlocks) the semaphore pointed to by +.IR sem . +If the semaphore's value consequently becomes greater than zero, +then another process or thread blocked in a +.BR sem_wait (3) +call will be woken up and proceed to lock the semaphore. +.SH RETURN VALUE +.BR sem_post () +returns 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.TP +.B EOVERFLOW +.\" Added in POSIX.1-2008 TC1 (Austin Interpretation 213) +The maximum allowable value for a semaphore would be exceeded. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_post () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +.BR sem_post () +is async-signal-safe: +it may be safely called within a signal handler. +.SH EXAMPLES +See +.BR sem_wait (3) +and +.BR shm_open (3). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_wait (3), +.BR sem_overview (7), +.BR signal\-safety (7) diff --git a/man/man3/sem_timedwait.3 b/man/man3/sem_timedwait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man/man3/sem_timedwait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man/man3/sem_trywait.3 b/man/man3/sem_trywait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man/man3/sem_trywait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man/man3/sem_unlink.3 b/man/man3/sem_unlink.3 new file mode 100644 index 0000000..c061332 --- /dev/null +++ b/man/man3/sem_unlink.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_unlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_unlink \- remove a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR sem_unlink () +removes the named semaphore referred to by +.IR name . +The semaphore name is removed immediately. +The semaphore is destroyed once all other processes that have +the semaphore open close it. +.SH RETURN VALUE +On success +.BR sem_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this semaphore. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no semaphore with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_unlink () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_wait.3 b/man/man3/sem_wait.3 new file mode 100644 index 0000000..f09f697 --- /dev/null +++ b/man/man3/sem_wait.3 @@ -0,0 +1,251 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_wait 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_wait, sem_timedwait, sem_trywait \- lock a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <semaphore.h> +.P +.BI "int sem_wait(sem_t *" sem ); +.BI "int sem_trywait(sem_t *" sem ); +.BI "int sem_timedwait(sem_t *restrict " sem , +.BI " const struct timespec *restrict " abs_timeout ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sem_timedwait (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR sem_wait () +decrements (locks) the semaphore pointed to by +.IR sem . +If the semaphore's value is greater than zero, +then the decrement proceeds, and the function returns, immediately. +If the semaphore currently has the value zero, +then the call blocks until either it becomes possible to perform +the decrement (i.e., the semaphore value rises above zero), +or a signal handler interrupts the call. +.P +.BR sem_trywait () +is the same as +.BR sem_wait (), +except that if the decrement cannot be immediately performed, +then call returns an error +.RI ( errno +set to +.BR EAGAIN ) +instead of blocking. +.P +.BR sem_timedwait () +is the same as +.BR sem_wait (), +except that +.I abs_timeout +specifies a limit on the amount of time that the call +should block if the decrement cannot be immediately performed. +The +.I abs_timeout +argument points to a +.BR timespec (3) +structure that specifies an absolute timeout +in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +If the timeout has already expired by the time of the call, +and the semaphore could not be locked immediately, +then +.BR sem_timedwait () +fails with a timeout error +.RI ( errno +set to +.BR ETIMEDOUT ). +.P +If the operation can be performed immediately, then +.BR sem_timedwait () +never fails with a timeout error, regardless of the value of +.IR abs_timeout . +Furthermore, the validity of +.I abs_timeout +is not checked in this case. +.SH RETURN VALUE +All of these functions return 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.RB ( sem_trywait ()) +The operation could not be performed without blocking (i.e., the +semaphore currently has the value zero). +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.TP +.B EINVAL +.RB ( sem_timedwait ()) +The value of +.I abs_timeout.tv_nsecs +is less than 0, or greater than or equal to 1000 million. +.TP +.B ETIMEDOUT +.RB ( sem_timedwait ()) +The call timed out before the semaphore could be locked. +.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition +.\" was detected", but this does not occur on Linux(?). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_wait (), +.BR sem_trywait (), +.BR sem_timedwait () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The (somewhat trivial) program shown below operates on an +unnamed semaphore. +The program expects two command-line arguments. +The first argument specifies a seconds value that is used to +set an alarm timer to generate a +.B SIGALRM +signal. +This handler performs a +.BR sem_post (3) +to increment the semaphore that is being waited on in +.I main() +using +.BR sem_timedwait (). +The second command-line argument specifies the length +of the timeout, in seconds, for +.BR sem_timedwait (). +The following shows what happens on two different runs of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out 2 3" +About to call sem_timedwait() +sem_post() from handler +sem_timedwait() succeeded +.RB "$" " ./a.out 2 1" +About to call sem_timedwait() +sem_timedwait() timed out +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (sem_wait.c) +.EX +#include <errno.h> +#include <semaphore.h> +#include <signal.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +#include <unistd.h> +\& +#include <assert.h> +\& +sem_t sem; +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void +handler(int sig) +{ + write(STDOUT_FILENO, "sem_post() from handler\en", 24); + if (sem_post(&sem) == \-1) { + write(STDERR_FILENO, "sem_post() failed\en", 18); + _exit(EXIT_FAILURE); + } +} +\& +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + struct timespec ts; + int s; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + if (sem_init(&sem, 0, 0) == \-1) + handle_error("sem_init"); +\& + /* Establish SIGALRM handler; set alarm timer using argv[1]. */ +\& + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + if (sigaction(SIGALRM, &sa, NULL) == \-1) + handle_error("sigaction"); +\& + alarm(atoi(argv[1])); +\& + /* Calculate relative interval as current time plus + number of seconds given argv[2]. */ +\& + if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) + handle_error("clock_gettime"); +\& + ts.tv_sec += atoi(argv[2]); +\& + printf("%s() about to call sem_timedwait()\en", __func__); + while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR) + continue; /* Restart if interrupted by handler. */ +\& + /* Check what happened. */ +\& + if (s == \-1) { + if (errno == ETIMEDOUT) + printf("sem_timedwait() timed out\en"); + else + perror("sem_timedwait"); + } else + printf("sem_timedwait() succeeded\en"); +\& + exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_gettime (2), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR timespec (3), +.BR sem_overview (7), +.BR time (7) diff --git a/man/man3/setaliasent.3 b/man/man3/setaliasent.3 new file mode 100644 index 0000000..c82b647 --- /dev/null +++ b/man/man3/setaliasent.3 @@ -0,0 +1,184 @@ +'\" t +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Polished a bit, added a little, aeb +.\" +.TH setaliasent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setaliasent, endaliasent, getaliasent, getaliasent_r, +getaliasbyname, getaliasbyname_r \- read an alias entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <aliases.h> +.P +.B "void setaliasent(void);" +.B "void endaliasent(void);" +.P +.B "struct aliasent *getaliasent(void);" +.BI "int getaliasent_r(struct aliasent *restrict " result , +.BI " char " buffer "[restrict ." buflen "], \ +size_t " buflen , +.BI " struct aliasent **restrict " res ); +.P +.BI "struct aliasent *getaliasbyname(const char *" name ); +.BI "int getaliasbyname_r(const char *restrict " name , +.BI " struct aliasent *restrict " result , +.BI " char " buffer "[restrict ." buflen "], \ +size_t " buflen , +.BI " struct aliasent **restrict " res ); +.fi +.SH DESCRIPTION +One of the databases available with the Name Service Switch (NSS) +is the aliases database, that contains mail aliases. +(To find out which databases are supported, try +.IR "getent \-\-help" .) +Six functions are provided to access the aliases database. +.P +The +.BR getaliasent () +function returns a pointer to a structure containing +the group information from the aliases database. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +.P +The +.BR setaliasent () +function rewinds the file pointer to the beginning of the +aliases database. +.P +The +.BR endaliasent () +function closes the aliases database. +.P +.BR getaliasent_r () +is the reentrant version of the previous function. +The requested structure +is stored via the first argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.P +The function +.BR getaliasbyname () +takes the name argument and searches the aliases database. +The entry is returned as a pointer to a +.IR "struct aliasent" . +.P +.BR getaliasbyname_r () +is the reentrant version of the previous function. +The requested structure +is stored via the second argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.P +The +.I "struct aliasent" +is defined in +.IR <aliases.h> : +.P +.in +4n +.EX +struct aliasent { + char *alias_name; /* alias name */ + size_t alias_members_len; + char **alias_members; /* alias name list */ + int alias_local; +}; +.EE +.in +.SH RETURN VALUE +The functions +.BR getaliasent_r () +and +.BR getaliasbyname_r () +return a nonzero value on error. +.SH FILES +The default alias database is the file +.IR /etc/aliases . +This can be changed in the +.I /etc/nsswitch.conf +file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setaliasent (), +.BR endaliasent (), +.BR getaliasent_r (), +.BR getaliasbyname_r () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR getaliasent (), +.BR getaliasbyname () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +The NeXT system has similar routines: +.P +.in +4n +.EX +#include <aliasdb.h> +\& +void alias_setent(void); +void alias_endent(void); +alias_ent *alias_getent(void); +alias_ent *alias_getbyname(char *name); +.EE +.in +.SH EXAMPLES +The following example compiles with +.IR "gcc example.c \-o example" . +It will dump all names in the alias database. +.P +.\" SRC BEGIN (setaliasent.c) +.EX +#include <aliases.h> +#include <errno.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + struct aliasent *al; +\& + setaliasent(); + for (;;) { + al = getaliasent(); + if (al == NULL) + break; + printf("Name: %s\en", al\->alias_name); + } + if (errno) { + perror("reading alias"); + exit(EXIT_FAILURE); + } + endaliasent(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getgrent (3), +.BR getpwent (3), +.BR getspent (3), +.BR aliases (5) +.\" +.\" /etc/sendmail/aliases +.\" Yellow Pages +.\" newaliases, postalias diff --git a/man/man3/setbuf.3 b/man/man3/setbuf.3 new file mode 100644 index 0000000..38400e4 --- /dev/null +++ b/man/man3/setbuf.3 @@ -0,0 +1,227 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu +.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, +.\" Thomas.Koenig@ciw.uni-karlsruhe.de +.\" Correction, Sun, 11 Apr 1999 15:55:18, +.\" Martin Vicente <martin@netadmin.dgac.fr> +.\" Correction, 2000-03-03, Andreas Jaeger <aj@suse.de> +.\" Added return value for setvbuf, aeb, +.\" +.TH setbuf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " int " mode ", size_t " size ); +.P +.BI "void setbuf(FILE *restrict " stream ", char *restrict " buf ); +.BI "void setbuffer(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " size_t " size ); +.BI "void setlinebuf(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setbuffer (), +.BR setlinebuf (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, and +line buffered. +When an output stream is unbuffered, information appears on +the destination file or terminal as soon as written; when it is block +buffered, many characters are saved up and written as a block; when it is +line buffered, characters are saved up until a newline is output or input is +read from any stream attached to a terminal device (typically \fIstdin\fP). +The function +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +.P +Normally all files are block buffered. +If a stream refers to a terminal (as +.I stdout +normally does), it is line buffered. +The standard error stream +.I stderr +is always unbuffered by default. +.P +The +.BR setvbuf () +function may be used on any open stream to change its buffer. +The +.I mode +argument must be one of the following three macros: +.RS +.TP +.B _IONBF +unbuffered +.TP +.B _IOLBF +line buffered +.TP +.B _IOFBF +fully buffered +.RE +.P +Except for unbuffered files, the +.I buf +argument should point to a buffer at least +.I size +bytes long; this buffer will be used instead of the current buffer. +If the argument +.I buf +is NULL, +only the mode is affected; a new buffer will be allocated on the next read +or write operation. +The +.BR setvbuf () +function may be used only after opening a stream and before any other +operations have been performed on it. +.P +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf (). +The +.BR setbuf () +function is exactly equivalent to the call +.P +.in +4n +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.in +.P +The +.BR setbuffer () +function is the same, except that the size of the buffer is up to the +caller, rather than being determined by the default +.BR BUFSIZ . +The +.BR setlinebuf () +function is exactly equivalent to the call: +.P +.in +4n +setvbuf(stream, NULL, _IOLBF, 0); +.in +.SH RETURN VALUE +The function +.BR setvbuf () +returns 0 on success. +It returns nonzero on failure +.RI ( mode +is invalid or the request cannot be honored). +It may set +.I errno +on failure. +.P +The other functions do not return a value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setbuf (), +.BR setbuffer (), +.BR setlinebuf (), +.BR setvbuf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C89, POSIX.1-2001. +.SH CAVEATS +POSIX notes +.\" https://www.austingroupbugs.net/view.php?id=397#c799 +.\" 0000397: setbuf and errno +that the value of +.I errno +is unspecified after a call to +.BR setbuf () +and further notes that, since the value of +.I errno +is not required to be unchanged after a successful call to +.BR setbuf (), +applications should instead use +.BR setvbuf () +in order to detect errors. +.SH BUGS +.\" The +.\" .BR setbuffer () +.\" and +.\" .BR setlinebuf () +.\" functions are not portable to versions of BSD before 4.2BSD, and +.\" are available under Linux since libc 4.5.21. +.\" On 4.2BSD and 4.3BSD systems, +.\" .BR setbuf () +.\" always uses a suboptimal buffer size and should be avoided. +.\".P +You must make sure that the space that +.I buf +points to still exists by the time +.I stream +is closed, which also happens at program termination. +For example, the following is invalid: +.P +.\" SRC BEGIN (setbuf.c) +.EX +#include <stdio.h> +\& +int +main(void) +{ + char buf[BUFSIZ]; +\& + setbuf(stdout, buf); + printf("Hello, world!\en"); + return 0; +} +.EE +.\" SRC END +.SH SEE ALSO +.BR stdbuf (1), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR fread (3), +.BR malloc (3), +.BR printf (3), +.BR puts (3) diff --git a/man/man3/setbuffer.3 b/man/man3/setbuffer.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setbuffer.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/setcontext.3 b/man/man3/setcontext.3 new file mode 100644 index 0000000..b01818d --- /dev/null +++ b/man/man3/setcontext.3 @@ -0,0 +1 @@ +.so man3/getcontext.3 diff --git a/man/man3/setenv.3 b/man/man3/setenv.3 new file mode 100644 index 0000000..d6f9683 --- /dev/null +++ b/man/man3/setenv.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2004, 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 9 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Changed unsetenv() prototype; added EINVAL error +.\" Noted nonstandard behavior of setenv() if name contains '=' +.\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug +.\" +.TH setenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setenv \- change or add an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); +.BI "int unsetenv(const char *" name ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setenv (), +.BR unsetenv (): +.nf + _POSIX_C_SOURCE >= 200112L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR setenv () +function adds the variable +.I name +to the +environment with the value +.IR value , +if +.I name +does not +already exist. +If +.I name +does exist in the environment, then +its value is changed to +.I value +if +.I overwrite +is nonzero; +if +.I overwrite +is zero, then the value of +.I name +is not changed (and +.BR setenv () +returns a success status). +This function makes copies of the strings pointed to by +.I name +and +.I value +(by contrast with +.BR putenv (3)). +.P +The +.BR unsetenv () +function deletes the variable +.I name +from +the environment. +If +.I name +does not exist in the environment, +then the function succeeds, and the environment is unchanged. +.SH RETURN VALUE +.BR setenv () +and +.BR unsetenv () +functions return zero on success, +or \-1 on error, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I name +is NULL, points to a string of length 0, +or contains an \[aq]=\[aq] character. +.TP +.B ENOMEM +Insufficient memory to add a new variable to the environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setenv (), +.BR unsetenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Prior to glibc 2.2.2, +.BR unsetenv () +was prototyped +as returning +.IR void ; +more recent glibc versions follow the +POSIX.1-compliant prototype shown in the SYNOPSIS. +.SH CAVEATS +POSIX.1 does not require +.BR setenv () +or +.BR unsetenv () +to be reentrant. +.SH BUGS +POSIX.1 specifies that if +.I name +contains an \[aq]=\[aq] character, then +.BR setenv () +should fail with the error +.BR EINVAL ; +however, versions of glibc before glibc 2.3.4 allowed an \[aq]=\[aq] sign in +.IR name . +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR putenv (3), +.BR environ (7) diff --git a/man/man3/setfsent.3 b/man/man3/setfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/setfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/setgrent.3 b/man/man3/setgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man/man3/setgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man/man3/sethostent.3 b/man/man3/sethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/sethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/sethostid.3 b/man/man3/sethostid.3 new file mode 100644 index 0000000..3210db0 --- /dev/null +++ b/man/man3/sethostid.3 @@ -0,0 +1 @@ +.so man3/gethostid.3 diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 new file mode 100644 index 0000000..b42e0d2 --- /dev/null +++ b/man/man3/setjmp.3 @@ -0,0 +1,332 @@ +'\" t +.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH setjmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <setjmp.h> +.P +.BI "int setjmp(jmp_buf " env ); +.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); +.P +.BI "[[noreturn]] void longjmp(jmp_buf " env ", int " val ); +.BI "[[noreturn]] void siglongjmp(sigjmp_buf " env ", int " val ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setjmp (): +see NOTES. +.P +.BR sigsetjmp (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The functions described on this page are used for performing "nonlocal gotos": +transferring execution from one function to a predetermined location +in another function. +The +.BR setjmp () +function dynamically establishes the target to which control +will later be transferred, and +.BR longjmp () +performs the transfer of execution. +.P +The +.BR setjmp () +function saves various information about the calling environment +(typically, the stack pointer, the instruction pointer, +possibly the values of other registers and the signal mask) +in the buffer +.I env +for later use by +.BR longjmp (). +In this case, +.BR setjmp () +returns 0. +.P +The +.BR longjmp () +function uses the information saved in +.I env +to transfer control back to the point where +.BR setjmp () +was called and to restore ("rewind") the stack to its state at the time of the +.BR setjmp () +call. +In addition, and depending on the implementation (see NOTES), +the values of some other registers and the process signal mask +may be restored to their state at the time of the +.BR setjmp () +call. +.P +Following a successful +.BR longjmp (), +execution continues as if +.BR setjmp () +had returned for a second time. +This "fake" return can be distinguished from a true +.BR setjmp () +call because the "fake" return returns the value provided in +.IR val . +If the programmer mistakenly passes the value 0 in +.IR val , +the "fake" return will instead return 1. +.SS sigsetjmp() and siglongjmp() +.BR sigsetjmp () +and +.BR siglongjmp () +also perform nonlocal gotos, but provide predictable handling of +the process signal mask. +.P +If, and only if, the +.I savesigs +argument provided to +.BR sigsetjmp () +is nonzero, the process's current signal mask is saved in +.I env +and will be restored if a +.BR siglongjmp () +is later performed with this +.IR env . +.SH RETURN VALUE +.BR setjmp () +and +.BR sigsetjmp () +return 0 when called directly; +on the "fake" return that occurs after +.BR longjmp () +or +.BR siglongjmp (), +the nonzero value specified in +.I val +is returned. +.P +The +.BR longjmp () +or +.BR siglongjmp () +functions do not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setjmp (), +.BR sigsetjmp () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR longjmp (), +.BR siglongjmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR setjmp () +.TQ +.BR longjmp () +C11, POSIX.1-2008. +.TP +.BR sigsetjmp () +.TQ +.BR siglongjmp () +POSIX.1-2008. +.SH HISTORY +.TP +.BR setjmp () +.TQ +.BR longjmp () +POSIX.1-2001, C89. +.TP +.BR sigsetjmp () +.TQ +.BR siglongjmp () +POSIX.1-2001. +.P +POSIX does not specify whether +.BR setjmp () +will save the signal mask +(to be later restored during +.BR longjmp ()). +In System V it will not. +In 4.3BSD it will, and there +is a function +.BR _setjmp () +that will not. +The behavior under Linux depends on the glibc version +and the setting of feature test macros. +Before glibc 2.19, +.BR setjmp () +follows the System V behavior by default, +but the BSD behavior is provided if the +.B _BSD_SOURCE +feature test macro is explicitly defined +.\" so that _FAVOR_BSD is triggered +and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.\" .BR _XOPEN_SOURCE_EXTENDED , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Since glibc 2.19, +.I <setjmp.h> +exposes only the System V version of +.BR setjmp (). +Programs that need the BSD semantics should replace calls to +.BR setjmp () +with calls to +.BR sigsetjmp () +with a nonzero +.I savesigs +argument. +.SH NOTES +.BR setjmp () +and +.BR longjmp () +can be useful for dealing with errors inside deeply nested function calls +or to allow a signal handler to pass control to +a specific point in the program, +rather than returning to the point where the handler interrupted +the main program. +In the latter case, +if you want to portably save and restore signal masks, use +.BR sigsetjmp () +and +.BR siglongjmp (). +See also the discussion of program readability below. +.SH CAVEATS +The compiler may optimize variables into registers, and +.BR longjmp () +may restore the values of other registers in addition to the +stack pointer and program counter. +Consequently, the values of automatic variables are unspecified +after a call to +.BR longjmp () +if they meet all the following criteria: +.IP \[bu] 3 +they are local to the function that made the corresponding +.BR setjmp () +call; +.IP \[bu] +their values are changed between the calls to +.BR setjmp () +and +.BR longjmp (); +and +.IP \[bu] +they are not declared as +.IR volatile . +.P +Analogous remarks apply for +.BR siglongjmp (). +.\" +.SS Nonlocal gotos and program readability +While it can be abused, +the traditional C "goto" statement at least has the benefit that lexical cues +(the goto statement and the target label) +allow the programmer to easily perceive the flow of control. +Nonlocal gotos provide no such cues: multiple +.BR setjmp () +calls might employ the same +.I jmp_buf +variable so that the content of the variable may change +over the lifetime of the application. +Consequently, the programmer may be forced to perform detailed +reading of the code to determine the dynamic target of a particular +.BR longjmp () +call. +(To make the programmer's life easier, each +.BR setjmp () +call should employ a unique +.I jmp_buf +variable.) +.P +Adding further difficulty, the +.BR setjmp () +and +.BR longjmp () +calls may not even be in the same source code module. +.P +In summary, nonlocal gotos can make programs harder to understand +and maintain, and an alternative should be used if possible. +.\" +.SS Undefined Behavior +If the function which called +.BR setjmp () +returns before +.BR longjmp () +is called, the behavior is undefined. +Some kind of subtle or unsubtle chaos is sure to result. +.P +If, in a multithreaded program, a +.BR longjmp () +call employs an +.I env +buffer that was initialized by a call to +.BR setjmp () +in a different thread, the behavior is undefined. +.\" +.\" The following statement appeared in versions up to POSIX.1-2008 TC1, +.\" but is set to be removed in POSIX.1-2008 TC2: +.\" +.\" According to POSIX.1, if a +.\" .BR longjmp () +.\" call is performed from a nested signal handler +.\" (i.e., from a handler that was invoked in response to a signal that was +.\" generated while another signal was already in the process of being +.\" handled), the behavior is undefined. +.P +POSIX.1-2008 Technical Corrigendum 2 adds +.\" http://austingroupbugs.net/view.php?id=516#c1195 +.BR longjmp () +and +.BR siglongjmp () +to the list of async-signal-safe functions. +However, the standard recommends avoiding the use of these functions +from signal handlers and goes on to point out that +if these functions are called from a signal handler that interrupted +a call to a non-async-signal-safe function (or some equivalent, +such as the steps equivalent to +.BR exit (3) +that occur upon a return from the initial call to +.IR main ()), +the behavior is undefined if the program subsequently makes a call to +a non-async-signal-safe function. +The only way of avoiding undefined behavior is to ensure one of the following: +.IP \[bu] 3 +After long jumping from the signal handler, +the program does not call any non-async-signal-safe functions +and does not return from the initial call to +.IR main (). +.IP \[bu] +Any signal whose handler performs a long jump must be blocked during +.I every +call to a non-async-signal-safe function and +no non-async-signal-safe functions are called after +returning from the initial call to +.IR main (). +.SH SEE ALSO +.BR signal (7), +.BR signal\-safety (7) diff --git a/man/man3/setkey.3 b/man/man3/setkey.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/setkey.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/setkey_r.3 b/man/man3/setkey_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/setkey_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/setlinebuf.3 b/man/man3/setlinebuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setlinebuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/setlocale.3 b/man/man3/setlocale.3 new file mode 100644 index 0000000..fe01130 --- /dev/null +++ b/man/man3/setlocale.3 @@ -0,0 +1,248 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 1999 by Bruno Haible (haible@clisp.cons.org) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org) +.\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH setlocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setlocale \- set the current locale +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.BI "char *setlocale(int " category ", const char *" locale ); +.fi +.SH DESCRIPTION +The +.BR setlocale () +function is used to set or query the program's current locale. +.P +If +.I locale +is not NULL, +the program's current locale is modified according to the arguments. +The argument +.I category +determines which parts of the program's current locale should be modified. +.TS +lB lB +lB lx. +Category Governs +LC_ALL All of the locale +LC_ADDRESS T{ +Formatting of addresses and +geography-related items (*) +T} +LC_COLLATE String collation +LC_CTYPE Character classification +LC_IDENTIFICATION T{ +Metadata describing the locale (*) +T} +LC_MEASUREMENT T{ +Settings related to measurements +(metric versus US customary) (*) +T} +LC_MESSAGES T{ +Localizable natural-language messages +T} +LC_MONETARY T{ +Formatting of monetary values +T} +LC_NAME T{ +Formatting of salutations for persons (*) +T} +LC_NUMERIC T{ +Formatting of nonmonetary numeric values +T} +LC_PAPER T{ +Settings related to the standard paper size (*) +T} +LC_TELEPHONE T{ +Formats to be used with telephone services (*) +T} +LC_TIME T{ +Formatting of date and time values +T} +.TE +.P +The categories marked with an asterisk in the above table +are GNU extensions. +For further information on these locale categories, see +.BR locale (7). +.P +The argument +.I locale +is a pointer to a character string containing the +required setting of +.IR category . +Such a string is either a well-known constant like "C" or "da_DK" +(see below), or an opaque string that was returned by another call of +.BR setlocale (). +.P +If +.I locale +is an empty string, +.BR \[dq]\[dq] , +each part of the locale that should be modified is set according to the +environment variables. +The details are implementation-dependent. +For glibc, first (regardless of +.IR category ), +the environment variable +.B LC_ALL +is inspected, +next the environment variable with the same name as the category +(see the table above), +and finally the environment variable +.BR LANG . +The first existing environment variable is used. +If its value is not a valid locale specification, the locale +is unchanged, and +.BR setlocale () +returns NULL. +.P +The locale +.B \[dq]C\[dq] +or +.B \[dq]POSIX\[dq] +is a portable locale; +it exists on all conforming systems. +.P +A locale name is typically of the form +.IR language "[_" territory "][." codeset "][@" modifier "]," +where +.I language +is an ISO\~639 language code, +.I territory +is an ISO\~3166 country code, and +.I codeset +is a character set or encoding identifier like +.B "ISO\-8859\-1" +or +.BR "UTF\-8" . +For a list of all supported locales, try "locale \-a" (see +.BR locale (1)). +.P +If +.I locale +is NULL, the current locale is only queried, not modified. +.P +On startup of the main program, the portable +.B \[dq]C\[dq] +locale is selected as default. +A program may be made portable to all locales by calling: +.P +.in +4n +.EX +setlocale(LC_ALL, ""); +.EE +.in +.P +after program initialization, and then: +.IP \[bu] 3 +using the values returned from a +.BR localeconv (3) +call for locale-dependent information; +.IP \[bu] +using the multibyte and wide character functions for text processing if +.BR "MB_CUR_MAX > 1" ; +.IP \[bu] +using +.BR strcoll (3) +and +.BR strxfrm (3) +to compare strings; and +.IP \[bu] +using +.BR wcscoll (3) +and +.BR wcsxfrm (3) +to compare wide-character strings. +.SH RETURN VALUE +A successful call to +.BR setlocale () +returns an opaque string that corresponds to the locale set. +This string may be allocated in static storage. +The string returned is such that a subsequent call with that string +and its associated category will restore that part of the process's +locale. +The return value is NULL if the request cannot be honored. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setlocale () +T} Thread safety MT-Unsafe const:locale env +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SS Categories +.TP +.B LC_ALL +.TQ +.B LC_COLLATE +.TQ +.B LC_CTYPE +.TQ +.B LC_MONETARY +.TQ +.B LC_NUMERIC +.TQ +.B LC_TIME +C11, POSIX.1-2008. +.TP +.B LC_MESSAGES +POSIX.1-2008. +.TP +Others: +GNU. +.SH HISTORY +POSIX.1-2001, C89. +.SS Categories +.TP +.B LC_ALL +.TQ +.B LC_COLLATE +.TQ +.B LC_CTYPE +.TQ +.B LC_MONETARY +.TQ +.B LC_NUMERIC +.TQ +.B LC_TIME +C89, POSIX.1-2001. +.TP +.B LC_MESSAGES +POSIX.1-2001. +.TP +Others: +GNU. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR localeconv (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR strcoll (3), +.BR strftime (3), +.BR charsets (7), +.BR locale (7) diff --git a/man/man3/setlogmask.3 b/man/man3/setlogmask.3 new file mode 100644 index 0000000..c4a5ddb --- /dev/null +++ b/man/man3/setlogmask.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH setlogmask 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setlogmask \- set log priority mask +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <syslog.h> +.P +.BI "int setlogmask(int " mask ); +.fi +.SH DESCRIPTION +A process has a log priority mask that determines which calls to +.BR syslog (3) +may be logged. +All other calls will be ignored. +Logging is enabled for the priorities that have the corresponding +bit set in +.IR mask . +The initial mask is such that logging is enabled for all priorities. +.P +The +.BR setlogmask () +function sets this logmask for the calling process, +and returns the previous mask. +If the +.I mask +argument is +.BR 0 , +the current logmask is not modified. +.P +The eight priorities are +.BR LOG_EMERG , +.BR LOG_ALERT , +.BR LOG_CRIT , +.BR LOG_ERR , +.BR LOG_WARNING , +.BR LOG_NOTICE , +.BR LOG_INFO , +and +.BR LOG_DEBUG . +The bit corresponding to a priority +.I p +is +.IR LOG_MASK(p) . +Some systems also provide a macro +.I LOG_UPTO(p) +for the mask +of all priorities in the above list up to and including +.IR p . +.SH RETURN VALUE +This function returns the previous log priority mask. +.SH ERRORS +None. +.\" .SH NOTES +.\" The glibc logmask handling was broken before glibc 2.1.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setlogmask () +T} Thread safety MT-Unsafe race:LogMask +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.\" Note that the description in POSIX.1-2001 is flawed. +.P +.BR LOG_UPTO () +will be included in the next release of the POSIX specification (Issue 8). +.\" FIXME . https://www.austingroupbugs.net/view.php?id=1033 +.SH SEE ALSO +.BR closelog (3), +.BR openlog (3), +.BR syslog (3) diff --git a/man/man3/setmntent.3 b/man/man3/setmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/setmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/setnetent.3 b/man/man3/setnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/setnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/setnetgrent.3 b/man/man3/setnetgrent.3 new file mode 100644 index 0000000..b47d4d7 --- /dev/null +++ b/man/man3/setnetgrent.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" polished - aeb +.\" +.TH setnetgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- +handle network group entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <netdb.h> +.P +.BI "int setnetgrent(const char *" netgroup ); +.B "void endnetgrent(void);" +.P +.BI "int getnetgrent(char **restrict " host , +.BI " char **restrict " user ", char **restrict " domain ); +.BI "int getnetgrent_r(char **restrict " host , +.BI " char **restrict " user ", char **restrict " domain , +.BI " char " buf "[restrict ." buflen "], size_t " buflen ); +.P +.BI "int innetgr(const char *" netgroup ", const char *" host , +.BI " const char *" user ", const char *" domain ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR \%setnetgrent (), +.BR \%endnetgrent (), +.BR \%getnetgrent (), +.BR \%getnetgrent_r (), +.BR \%innetgr (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.I netgroup +is a SunOS invention. +A netgroup database is a list of string triples +.RI ( hostname ", " username ", " domainname ) +or other netgroup names. +Any of the elements in a triple can be empty, +which means that anything matches. +The functions described here allow access to the netgroup databases. +The file +.I /etc/nsswitch.conf +defines what database is searched. +.P +The +.BR setnetgrent () +call defines the netgroup that will be searched by subsequent +.BR getnetgrent () +calls. +The +.BR getnetgrent () +function retrieves the next netgroup entry, and returns pointers in +.IR host , +.IR user , +.IR domain . +A null pointer means that the corresponding entry matches any string. +The pointers are valid only as long as there is no call to other +netgroup-related functions. +To avoid this problem you can use the GNU function +.BR getnetgrent_r () +that stores the strings in the supplied buffer. +To free all allocated buffers use +.BR endnetgrent (). +.P +In most cases you want to check only if the triplet +.RI ( hostname ", " username ", " domainname ) +is a member of a netgroup. +The function +.BR innetgr () +can be used for this without calling the above three functions. +Again, a null pointer is a wildcard and matches any string. +The function is thread-safe. +.SH RETURN VALUE +These functions return 1 on success and 0 for failure. +.SH FILES +.I /etc/netgroup +.br +.I /etc/nsswitch.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setnetgrent (), +.BR getnetgrent_r (), +.BR innetgr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +locale +T} +T{ +.na +.nh +.BR endnetgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +T} +T{ +.na +.nh +.BR getnetgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +race:netgrentbuf locale +T} +.TE +.P +In the above table, +.I netgrent +in +.I race:netgrent +signifies that if any of the functions +.BR setnetgrent (), +.BR getnetgrent_r (), +.BR innetgr (), +.BR getnetgrent (), +or +.BR endnetgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +In the BSD implementation, +.BR setnetgrent () +returns void. +.SH STANDARDS +None. +.SH HISTORY +.BR setnetgrent (), +.BR endnetgrent (), +.BR getnetgrent (), +and +.BR innetgr () +are available on most UNIX systems. +.BR getnetgrent_r () +is not widely available on other systems. +.\" getnetgrent_r() is on Solaris 8 and AIX 5.1, but not the BSDs. +.SH SEE ALSO +.BR sethostent (3), +.BR setprotoent (3), +.BR setservent (3) diff --git a/man/man3/setprotoent.3 b/man/man3/setprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/setprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/setpwent.3 b/man/man3/setpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man/man3/setpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man/man3/setrpcent.3 b/man/man3/setrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/setrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/setservent.3 b/man/man3/setservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/setservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/setspent.3 b/man/man3/setspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/setspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/setstate.3 b/man/man3/setstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/setstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/setstate_r.3 b/man/man3/setstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/setstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/setttyent.3 b/man/man3/setttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/setttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/setusershell.3 b/man/man3/setusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man/man3/setusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man/man3/setutent.3 b/man/man3/setutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/setutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/setutxent.3 b/man/man3/setutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/setutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/setvbuf.3 b/man/man3/setvbuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setvbuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/sgetspent.3 b/man/man3/sgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/sgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/sgetspent_r.3 b/man/man3/sgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/sgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/shm_open.3 b/man/man3/shm_open.3 new file mode 100644 index 0000000..257e460 --- /dev/null +++ b/man/man3/shm_open.3 @@ -0,0 +1,521 @@ +'\" t +.\" Copyright (C) 2002, 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH shm_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <sys/mman.h> +.BR "#include <sys/stat.h>" " /* For mode constants */" +.BR "#include <fcntl.h>" " /* For O_* constants */" +.P +.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); +.BI "int shm_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR shm_open () +creates and opens a new, or opens an existing, POSIX shared memory object. +A POSIX shared memory object is in effect a handle which can +be used by unrelated processes to +.BR mmap (2) +the same region of shared memory. +The +.BR shm_unlink () +function performs the converse operation, +removing an object previously created by +.BR shm_open (). +.P +The operation of +.BR shm_open () +is analogous to that of +.BR open (2). +.I name +specifies the shared memory object to be created or opened. +For portable use, +a shared memory object should be identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.B NAME_MAX +(i.e., 255) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory must exist under /dev/shm, and allow the +.\" required permissions if a user wants to create a shared memory +.\" object in that subdirectory. +.P +.I oflag +is a bit mask created by ORing together exactly one of +.B O_RDONLY +or +.B O_RDWR +and any of the other flags listed here: +.TP +.B O_RDONLY +Open the object for read access. +A shared memory object opened in this way can be +.BR mmap (2)ed +only for read +.RB ( PROT_READ ) +access. +.TP +.B O_RDWR +Open the object for read-write access. +.TP +.B O_CREAT +Create the shared memory object if it does not exist. +The user and group ownership of the object are taken +from the corresponding effective IDs of the calling process, +.\" In truth it is actually the filesystem IDs on Linux, but these +.\" are nearly always the same as the effective IDs. (MTK, Jul 05) +and the object's +permission bits are set according to the low-order 9 bits of +.IR mode , +except that those bits set in the process file mode +creation mask (see +.BR umask (2)) +are cleared for the new object. +A set of macro constants which can be used to define +.I mode +is listed in +.BR open (2). +(Symbolic definitions of these constants can be obtained by including +.IR <sys/stat.h> .) +.IP +A new shared memory object initially has zero length\[em]the size of the +object can be set using +.BR ftruncate (2). +The newly allocated bytes of a shared memory +object are automatically initialized to 0. +.TP +.B O_EXCL +If +.B O_CREAT +was also specified, and a shared memory object with the given +.I name +already exists, return an error. +The check for the existence of the object, and its creation if it +does not exist, are performed atomically. +.TP +.B O_TRUNC +If the shared memory object already exists, truncate it to zero bytes. +.P +Definitions of these flag values can be obtained by including +.IR <fcntl.h> . +.P +On successful completion +.BR shm_open () +returns a new file descriptor referring to the shared memory object. +This file descriptor is guaranteed to be the lowest-numbered file descriptor +not previously opened within the process. +The +.B FD_CLOEXEC +flag (see +.BR fcntl (2)) +is set for the file descriptor. +.P +The file descriptor is normally used in subsequent calls +to +.BR ftruncate (2) +(for a newly created object) and +.BR mmap (2). +After a call to +.BR mmap (2) +the file descriptor may be closed without affecting the memory mapping. +.P +The operation +of +.BR shm_unlink () +is analogous to +.BR unlink (2): +it removes a shared memory object name, and, once all processes +have unmapped the object, deallocates and +destroys the contents of the associated memory region. +After a successful +.BR shm_unlink (), +attempts to +.BR shm_open () +an object with the same +.I name +fail (unless +.B O_CREAT +was specified, in which case a new, distinct object is created). +.SH RETURN VALUE +On success, +.BR shm_open () +returns a file descriptor (a nonnegative integer). +On success, +.BR shm_unlink () +returns 0. +On failure, both functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission to +.BR shm_unlink () +the shared memory object was denied. +.TP +.B EACCES +Permission was denied to +.BR shm_open () +.I name +in the specified +.IR mode , +or +.B O_TRUNC +was specified and the caller does not have write permission on the object. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified to +.BR shm_open () +and the shared memory object specified by +.I name +already exists. +.TP +.B EINVAL +The +.I name +argument to +.BR shm_open () +was invalid. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +The length of +.I name +exceeds +.BR PATH_MAX . +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +An attempt was made to +.BR shm_open () +a +.I name +that did not exist, and +.B O_CREAT +was not specified. +.TP +.B ENOENT +An attempt was to made to +.BR shm_unlink () +a +.I name +that does not exist. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR shm_open (), +.BR shm_unlink () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +POSIX leaves the behavior of the combination of +.B O_RDONLY +and +.B O_TRUNC +unspecified. +On Linux, this will successfully truncate an existing +shared memory object\[em]this may not be so on other UNIX systems. +.P +The POSIX shared memory object implementation on Linux makes use +of a dedicated +.BR tmpfs (5) +filesystem that is normally mounted under +.IR /dev/shm . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.P +POSIX.1-2001 says that the group ownership of a newly created shared +memory object is set to either the calling process's effective group ID +or "a system default group ID". +POSIX.1-2008 says that the group ownership +may be set to either the calling process's effective group ID +or, if the object is visible in the filesystem, +the group ID of the parent directory. +.SH EXAMPLES +The programs below employ POSIX shared memory and POSIX unnamed semaphores +to exchange a piece of data. +The "bounce" program (which must be run first) raises the case +of a string that is placed into the shared memory by the "send" program. +Once the data has been modified, the "send" program then prints +the contents of the modified shared memory. +An example execution of the two programs is the following: +.P +.in +4n +.EX +$ \fB./pshm_ucase_bounce /myshm &\fP +[1] 270171 +$ \fB./pshm_ucase_send /myshm hello\fP +HELLO +.EE +.in +.P +Further detail about these programs is provided below. +.\" +.SS Program source: pshm_ucase.h +The following header file is included by both programs below. +Its primary purpose is to define a structure that will be imposed +on the memory object that is shared between the two programs. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase.h) +.EX +#ifndef PSHM_UCASE_H +#define PSHM_UCASE_H +\& +#include <semaphore.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +#define BUF_SIZE 1024 /* Maximum size for exchanged string */ +\& +/* Define a structure that will be imposed on the shared + memory object */ +\& +struct shmbuf { + sem_t sem1; /* POSIX unnamed semaphore */ + sem_t sem2; /* POSIX unnamed semaphore */ + size_t cnt; /* Number of bytes used in \[aq]buf\[aq] */ + char buf[BUF_SIZE]; /* Data being transferred */ +}; +\& +#endif // include guard +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_bounce.c +The "bounce" program creates a new shared memory object with the name +given in its command-line argument and sizes the object to +match the size of the +.I shmbuf +structure defined in the header file. +It then maps the object into the process's address space, +and initializes two POSIX semaphores inside the object to 0. +.P +After the "send" program has posted the first of the semaphores, +the "bounce" program upper cases the data that has been placed +in the memory by the "send" program and then posts the second semaphore +to tell the "send" program that it may now access the shared memory. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_bounce.c) +.EX +/* pshm_ucase_bounce.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <ctype.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/mman.h> +#include <unistd.h> +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath; + struct shmbuf *shmp; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s /shm\-path\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; +\& + /* Create shared memory object and set its size to the size + of our structure. */ +\& + fd = shm_open(shmpath, O_CREAT | O_EXCL | O_RDWR, 0600); + if (fd == \-1) + errExit("shm_open"); +\& + if (ftruncate(fd, sizeof(struct shmbuf)) == \-1) + errExit("ftruncate"); +\& + /* Map the object into the caller\[aq]s address space. */ +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Initialize semaphores as process\-shared, with value 0. */ +\& + if (sem_init(&shmp\->sem1, 1, 0) == \-1) + errExit("sem_init\-sem1"); + if (sem_init(&shmp\->sem2, 1, 0) == \-1) + errExit("sem_init\-sem2"); +\& + /* Wait for \[aq]sem1\[aq] to be posted by peer before touching + shared memory. */ +\& + if (sem_wait(&shmp\->sem1) == \-1) + errExit("sem_wait"); +\& + /* Convert data in shared memory into upper case. */ +\& + for (size_t j = 0; j < shmp\->cnt; j++) + shmp\->buf[j] = toupper((unsigned char) shmp\->buf[j]); +\& + /* Post \[aq]sem2\[aq] to tell the peer that it can now + access the modified data in shared memory. */ +\& + if (sem_post(&shmp\->sem2) == \-1) + errExit("sem_post"); +\& + /* Unlink the shared memory object. Even if the peer process + is still using the object, this is okay. The object will + be removed only after all open references are closed. */ +\& + shm_unlink(shmpath); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_send.c +The "send" program takes two command-line arguments: +the pathname of a shared memory object previously created by the "bounce" +program and a string that is to be copied into that object. +.P +The program opens the shared memory object +and maps the object into its address space. +It then copies the data specified in its second argument +into the shared memory, +and posts the first semaphore, +which tells the "bounce" program that it can now access that data. +After the "bounce" program posts the second semaphore, +the "send" program prints the contents of the shared memory +on standard output. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_send.c) +.EX +/* pshm_ucase_send.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <fcntl.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/mman.h> +#include <unistd.h> +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath, *string; + size_t len; + struct shmbuf *shmp; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s /shm\-path string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; + string = argv[2]; + len = strlen(string); +\& + if (len > BUF_SIZE) { + fprintf(stderr, "String is too long\en"); + exit(EXIT_FAILURE); + } +\& + /* Open the existing shared memory object and map it + into the caller\[aq]s address space. */ +\& + fd = shm_open(shmpath, O_RDWR, 0); + if (fd == \-1) + errExit("shm_open"); +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Copy data into the shared memory object. */ +\& + shmp\->cnt = len; + memcpy(&shmp\->buf, string, len); +\& + /* Tell peer that it can now access shared memory. */ +\& + if (sem_post(&shmp\->sem1) == \-1) + errExit("sem_post"); +\& + /* Wait until peer says that it has finished accessing + the shared memory. */ +\& + if (sem_wait(&shmp\->sem2) == \-1) + errExit("sem_wait"); +\& + /* Write modified data in shared memory to standard output. */ +\& + write(STDOUT_FILENO, &shmp\->buf, len); + write(STDOUT_FILENO, "\en", 1); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR close (2), +.BR fchmod (2), +.BR fchown (2), +.BR fcntl (2), +.BR fstat (2), +.BR ftruncate (2), +.BR memfd_create (2), +.BR mmap (2), +.BR open (2), +.BR umask (2), +.BR shm_overview (7) diff --git a/man/man3/shm_unlink.3 b/man/man3/shm_unlink.3 new file mode 100644 index 0000000..74f2986 --- /dev/null +++ b/man/man3/shm_unlink.3 @@ -0,0 +1 @@ +.so man3/shm_open.3 diff --git a/man/man3/sigabbrev_np.3 b/man/man3/sigabbrev_np.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sigabbrev_np.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sigaddset.3 b/man/man3/sigaddset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigaddset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigandset.3 b/man/man3/sigandset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigandset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigblock.3 b/man/man3/sigblock.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigblock.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sigdelset.3 b/man/man3/sigdelset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigdelset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigdescr_np.3 b/man/man3/sigdescr_np.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sigdescr_np.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sigemptyset.3 b/man/man3/sigemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigfillset.3 b/man/man3/sigfillset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigfillset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/siggetmask.3 b/man/man3/siggetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/siggetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sighold.3 b/man/man3/sighold.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sighold.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/sigignore.3 b/man/man3/sigignore.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sigignore.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/siginterrupt.3 b/man/man3/siginterrupt.3 new file mode 100644 index 0000000..82c17e2 --- /dev/null +++ b/man/man3/siginterrupt.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl) +.TH siginterrupt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +siginterrupt \- allow signals to interrupt system calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "[[deprecated]] int siginterrupt(int " sig ", int " flag ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR siginterrupt (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR siginterrupt () +function changes the restart behavior when +a system call is interrupted by the signal \fIsig\fP. +If the \fIflag\fP +argument is false (0), then system calls will be restarted if interrupted +by the specified signal \fIsig\fP. +This is the default behavior in Linux. +.P +If the \fIflag\fP argument is true (1) and no data has been transferred, +then a system call interrupted by the signal \fIsig\fP will return \-1 +and \fIerrno\fP will be set to +.BR EINTR . +.P +If the \fIflag\fP argument is true (1) and data transfer has started, +then the system call will be interrupted and will return the actual +amount of data transferred. +.SH RETURN VALUE +The +.BR siginterrupt () +function returns 0 on success. +It returns \-1 if the +signal number +.I sig +is invalid, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The specified signal number is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR siginterrupt () +T} Thread safety T{ +.na +.nh +MT-Unsafe const:sigintr +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.3BSD, POSIX.1-2001. +Obsolete in POSIX.1-2008, +recommending the use of +.BR sigaction (2) +with the +.B SA_RESTART +flag instead. +.SH SEE ALSO +.BR signal (2) diff --git a/man/man3/sigisemptyset.3 b/man/man3/sigisemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigisemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigismember.3 b/man/man3/sigismember.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigismember.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/siglongjmp.3 b/man/man3/siglongjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/siglongjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/sigmask.3 b/man/man3/sigmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/signbit.3 b/man/man3/signbit.3 new file mode 100644 index 0000000..8c39fc0 --- /dev/null +++ b/man/man3/signbit.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages, copyright Free Software Foundation +.\" +.TH signbit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signbit \- test sign of a real floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B "#include <math.h>" +.P +.BI "int signbit(" x ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR signbit (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR signbit () +is a generic macro which can work on all real floating-point types. +It returns a nonzero value if the value of +.I x +has its sign bit set. +.P +This is not the same as +.IR "x < 0.0" , +because IEEE 754 floating point allows zero to be signed. +The comparison +.I \-0.0\~<\~0.0 +is false, but +.I signbit(\-0.0) +will return a nonzero value. +.P +NaNs and infinities have a sign bit. +.SH RETURN VALUE +The +.BR signbit () +macro returns nonzero if the sign of +.I x +is negative; otherwise it returns zero. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR signbit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH SEE ALSO +.BR copysign (3) diff --git a/man/man3/signgam.3 b/man/man3/signgam.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/signgam.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/significand.3 b/man/man3/significand.3 new file mode 100644 index 0000000..1966d24 --- /dev/null +++ b/man/man3/significand.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" heavily based on glibc infopages, copyright Free Software Foundation +.\" +.TH significand 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +significand, significandf, significandl \- +get mantissa of floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double significand(double " x ); +.BI "float significandf(float " x ); +.BI "long double significandl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR significand (), +.BR significandf (), +.BR significandl (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the mantissa of +.I x +scaled to the range +.RB [ 1 ,\~ FLT_RADIX ). +They are equivalent to +.P +.in +4n +.EX +scalb(x, (double) \-ilogb(x)) +.EE +.in +.P +This function exists mainly for use in certain standardized tests +for IEEE 754 conformance. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR significand (), +.BR significandf (), +.BR significandl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.TP +.BR significand () +BSD. +.SH HISTORY +.TP +.BR significand () +BSD. +.SH SEE ALSO +.BR ilogb (3), +.BR scalb (3) diff --git a/man/man3/significandf.3 b/man/man3/significandf.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man/man3/significandf.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man/man3/significandl.3 b/man/man3/significandl.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man/man3/significandl.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man/man3/sigorset.3 b/man/man3/sigorset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigorset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigpause.3 b/man/man3/sigpause.3 new file mode 100644 index 0000000..bd93593 --- /dev/null +++ b/man/man3/sigpause.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigpause 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigpause \- atomically release blocked signals and wait for interrupt +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see NOTES) */" +.P +.BI "[[deprecated]] int sigpause(int " sig "); /* POSIX.1 / SysV / UNIX 95 */" +.fi +.SH DESCRIPTION +Don't use this function. +Use +.BR sigsuspend (2) +instead. +.P +The function +.BR sigpause () +is designed to wait for some signal. +It changes the process's signal mask (set of blocked signals), +and then waits for a signal to arrive. +Upon arrival of a signal, the original signal mask is restored. +.SH RETURN VALUE +If +.BR sigpause () +returns, it was interrupted by a signal and the return value is \-1 +with +.I errno +set to +.BR EINTR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigpause () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" marking in glibc manual is more detailed: +.\" +.\" sigpause: MT-Unsafe race:sigprocmask/!bsd!linux +.\" +.\" glibc manual says /!linux!bsd indicate the preceding marker only applies +.\" when the underlying kernel is neither Linux nor a BSD kernel. +.\" So, it is safe in Linux kernel. +.SH VERSIONS +On Linux, this routine is a system call only on the Sparc (sparc64) +architecture. +.P +.\" Libc4 and libc5 know only about the BSD version. +.\" +glibc uses the BSD version if the +.B _BSD_SOURCE +feature test macro is defined and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Otherwise, the System V version is used, +and feature test macros must be defined as follows to obtain the declaration: +.IP \[bu] 3 +Since glibc 2.26: +_XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.IP \[bu] +glibc 2.25 and earlier: _XOPEN_SOURCE +.P +Since glibc 2.19, only the System V version is exposed by +.IR <signal.h> ; +applications that formerly used the BSD +.BR sigpause () +should be amended to use +.BR sigsuspend (2). +.\" +.\" For the BSD version, one usually uses a zero +.\" .I sigmask +.\" to indicate that no signals are to be blocked. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +Obsoleted in POSIX.1-2008. +.P +The classical BSD version of this function appeared in 4.2BSD. +It sets the process's signal mask to +.IR sigmask . +UNIX 95 standardized the incompatible System V version of +this function, which removes only the specified signal +.I sig +from the process's signal mask. +.\" __xpg_sigpause: UNIX 95, spec 1170, SVID, SVr4, XPG +The unfortunate situation with two incompatible functions with the +same name was solved by the +.BR \%sigsuspend (2) +function, that takes a +.I "sigset_t\ *" +argument (instead of an +.IR int ). +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigblock (3), +.BR sigvec (3), +.BR feature_test_macros (7) diff --git a/man/man3/sigqueue.3 b/man/man3/sigqueue.3 new file mode 100644 index 0000000..341d942 --- /dev/null +++ b/man/man3/sigqueue.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" added note on self-signaling, aeb, 2002-06-07 +.\" added note on CAP_KILL, mtk, 2004-06-16 +.\" +.TH sigqueue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigqueue \- queue a signal and data to a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigqueue (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR sigqueue () +sends the signal specified in +.I sig +to the process whose PID is given in +.IR pid . +The permissions required to send a signal are the same as for +.BR kill (2). +As with +.BR kill (2), +the null signal (0) can be used to check if a process with a given +PID exists. +.P +The +.I value +argument is used to specify an accompanying item of data (either an integer +or a pointer value) to be sent with the signal, and has the following type: +.P +.in +4n +.EX +union sigval { + int sival_int; + void *sival_ptr; +}; +.EE +.in +.P +If the receiving process has installed a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_code +field of that structure will be set to +.BR SI_QUEUE . +.SH RETURN VALUE +On success, +.BR sigqueue () +returns 0, indicating that the signal was successfully +queued to the receiving process. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B EPERM +The process does not have permission to send the signal +to the receiving process. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process has a PID matching +.IR pid . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigqueue () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +On Linux, +.BR sigqueue () +is implemented using the +.BR rt_sigqueueinfo (2) +system call. +The system call differs in its third argument, which is the +.I siginfo_t +structure that will be supplied to the receiving process's +signal handler or returned by the receiving process's +.BR sigtimedwait (2) +call. +Inside the glibc +.BR sigqueue () +wrapper, this argument, +.IR uinfo , +is initialized as follows: +.P +.in +4n +.EX +uinfo.si_signo = sig; /* Argument supplied to sigqueue() */ +uinfo.si_code = SI_QUEUE; +uinfo.si_pid = getpid(); /* Process ID of sender */ +uinfo.si_uid = getuid(); /* Real UID of sender */ +uinfo.si_value = val; /* Argument supplied to sigqueue() */ +.EE +.in +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.2. +POSIX.1-2001. +.SH NOTES +If this function results in the sending of a signal to the process +that invoked it, and that signal was not blocked by the calling thread, +and no other threads were willing to handle this signal (either by +having it unblocked, or by waiting for it using +.BR sigwait (3)), +then at least some signal must be delivered to this thread before this +function returns. +.SH SEE ALSO +.BR kill (2), +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_sigqueue (3), +.BR sigwait (3), +.BR signal (7) diff --git a/man/man3/sigrelse.3 b/man/man3/sigrelse.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sigrelse.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/sigset.3 b/man/man3/sigset.3 new file mode 100644 index 0000000..195b5fe --- /dev/null +++ b/man/man3/sigset.3 @@ -0,0 +1,265 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigset, sighold, sigrelse, sigignore \- System V signal API +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "[[deprecated]] sighandler_t sigset(int " sig ", sighandler_t " disp ); +.P +.BI "[[deprecated]] int sighold(int " sig ); +.BI "[[deprecated]] int sigrelse(int " sig ); +.BI "[[deprecated]] int sigignore(int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigset (), +.BR sighold (), +.BR sigrelse (), +.BR sigignore (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical System V signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.) +.P +The +.BR sigset () +function modifies the disposition of the signal +.IR sig . +The +.I disp +argument can be the address of a signal handler function, +or one of the following constants: +.TP +.B SIG_DFL +Reset the disposition of +.I sig +to the default. +.TP +.B SIG_IGN +Ignore +.IR sig . +.TP +.B SIG_HOLD +Add +.I sig +to the process's signal mask, but leave the disposition of +.I sig +unchanged. +.P +If +.I disp +specifies the address of a signal handler, then +.I sig +is added to the process's signal mask during execution of the handler. +.P +If +.I disp +was specified as a value other than +.BR SIG_HOLD , +then +.I sig +is removed from the process's signal mask. +.P +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.P +The +.BR sighold () +function adds +.I sig +to the calling process's signal mask. +.P +The +.BR sigrelse () +function removes +.I sig +from the calling process's signal mask. +.P +The +.BR sigignore () +function sets the disposition of +.I sig +to +.BR SIG_IGN . +.SH RETURN VALUE +On success, +.BR sigset () +returns +.B SIG_HOLD +if +.I sig +was blocked before the call, +or the signal's previous disposition +if it was not blocked before the call. +On error, +.BR sigset () +returns \-1, with +.I errno +set to indicate the error. +(But see BUGS below.) +.P +The +.BR sighold (), +.BR sigrelse (), +and +.BR sigignore () +functions return 0 on success; on error, these functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +For +.BR sigset () +see the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.P +For +.BR sighold () +and +.BR sigrelse () +see the ERRORS under +.BR sigprocmask (2). +.P +For +.BR sigignore (), +see the errors under +.BR sigaction (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigset (), +.BR sighold (), +.BR sigrelse (), +.BR sigignore () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.TP +.I sighandler_t +GNU. +POSIX.1 uses the same type but without a +.IR typedef . +.SH HISTORY +glibc 2.1. +SVr4, POSIX.1-2001. +POSIX.1-2008 marks these functions +as obsolete, recommending the use of +.BR sigaction (2), +.BR sigprocmask (2), +.BR pthread_sigmask (3), +and +.BR sigsuspend (2) +instead. +.SH NOTES +The +.BR sigset () +function provides reliable signal handling semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to 0). +.P +On System V, the +.BR signal () +function provides unreliable semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to +.IR "SA_RESETHAND | SA_NODEFER" ). +On BSD, +.BR signal () +provides reliable semantics. +POSIX.1-2001 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.P +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH BUGS +Before glibc 2.2, +.BR sigset () +did not unblock +.I sig +if +.I disp +was specified as a value other than +.BR SIG_HOLD . +.P +Before glibc 2.5, +.BR sigset () +does not correctly return the previous disposition of the signal +in two cases. +First, if +.I disp +is specified as +.BR SIG_HOLD , +then a successful +.BR sigset () +always returns +.BR SIG_HOLD . +Instead, it should return the previous disposition of the signal +(unless the signal was blocked, in which case +.B SIG_HOLD +should be returned). +Second, if the signal is currently blocked, then +the return value of a successful +.BR sigset () +should be +.BR SIG_HOLD . +Instead, the previous disposition of the signal is returned. +These problems have been fixed since glibc 2.5. +.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigvec (3), +.BR signal (7) diff --git a/man/man3/sigsetjmp.3 b/man/man3/sigsetjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/sigsetjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/sigsetmask.3 b/man/man3/sigsetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigsetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sigsetops.3 b/man/man3/sigsetops.3 new file mode 100644 index 0000000..fd1ea9a --- /dev/null +++ b/man/man3/sigsetops.3 @@ -0,0 +1,190 @@ +'\" t +.\" Copyright (c) 1994 Mike Battersby +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by aeb, 960721 +.\" 2005-11-21, mtk, added descriptions of sigisemptyset(), sigandset(), +.\" and sigorset() +.\" 2007-10-26 mdw added wording that a sigset_t must be initialized +.\" prior to use +.\" +.TH SIGSETOPS 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- POSIX +signal set operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int sigemptyset(sigset_t *" set ); +.BI "int sigfillset(sigset_t *" set ); +.P +.BI "int sigaddset(sigset_t *" set ", int " signum ); +.BI "int sigdelset(sigset_t *" set ", int " signum ); +.P +.BI "int sigismember(const sigset_t *" set ", int " signum ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +.BR sigdelset (), +.BR sigismember (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +These functions allow the manipulation of POSIX signal sets. +.P +.BR sigemptyset () +initializes the signal set given by +.I set +to empty, with all signals excluded from the set. +.P +.BR sigfillset () +initializes +.I set +to full, including all signals. +.P +.BR sigaddset () +and +.BR sigdelset () +add and delete respectively signal +.I signum +from +.IR set . +.P +.BR sigismember () +tests whether +.I signum +is a member of +.IR set . +.P +Objects of type +.I sigset_t +must be initialized by a call to either +.BR sigemptyset () +or +.BR sigfillset () +before being passed to the functions +.BR sigaddset (), +.BR sigdelset (), +and +.BR sigismember () +or the additional glibc functions described below +.RB ( sigisemptyset (), +.BR sigandset (), +and +.BR sigorset ()). +The results are undefined if this is not done. +.SH RETURN VALUE +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +and +.BR sigdelset () +return 0 on success and \-1 on error. +.P +.BR sigismember () +returns 1 if +.I signum +is a member of +.IR set , +0 if +.I signum +is not a member, and \-1 on error. +.P +On error, these functions set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I signum +is not a valid signal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +.BR sigdelset (), +.BR sigismember (), +.BR sigisemptyset (), +.BR sigorset (), +.BR sigandset () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS GNU +If the +.B _GNU_SOURCE +feature test macro is defined, then \fI<signal.h>\fP +exposes three other functions for manipulating signal +sets: +.P +.nf +.BI "int sigisemptyset(const sigset_t *" set ); +.BI "int sigorset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.BI "int sigandset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.fi +.P +.BR sigisemptyset () +returns 1 if +.I set +contains no signals, and 0 otherwise. +.P +.BR sigorset () +places the union of the sets +.I left +and +.I right +in +.IR dest . +.BR sigandset () +places the intersection of the sets +.I left +and +.I right +in +.IR dest . +Both functions return 0 on success, and \-1 on failure. +.P +These functions are nonstandard (a few other systems provide similar +functions) and their use should be avoided in portable applications. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +When creating a filled signal set, the glibc +.BR sigfillset () +function does not include the two real-time signals used internally +by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2) diff --git a/man/man3/sigstack.3 b/man/man3/sigstack.3 new file mode 100644 index 0000000..bf85961 --- /dev/null +++ b/man/man3/sigstack.3 @@ -0,0 +1,3 @@ +.so man2/sigaltstack.2 +.\" No new programs should use sigstack(3). +.\" sigaltstack(2) briefly discusses sigstack(3), so point the user there. diff --git a/man/man3/sigvec.3 b/man/man3/sigvec.3 new file mode 100644 index 0000000..31f5ef4 --- /dev/null +++ b/man/man3/sigvec.3 @@ -0,0 +1,282 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigvec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "[[deprecated]] int sigvec(int " sig ", const struct sigvec *" vec , +.BI " struct sigvec *" ovec ); +.P +.BI "[[deprecated]] int sigmask(int " signum ); +.P +.BI "[[deprecated]] int sigblock(int " mask ); +.BI "[[deprecated]] int sigsetmask(int " mask ); +.B [[deprecated]] int siggetmask(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical BSD signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.). +.P +The +.BR sigvec () +function sets and/or gets the disposition of the signal +.I sig +(like the POSIX +.BR sigaction (2)). +If +.I vec +is not NULL, it points to a +.I sigvec +structure that defines the new disposition for +.IR sig . +If +.I ovec +is not NULL, it points to a +.I sigvec +structure that is used to return the previous disposition of +.IR sig . +To obtain the current disposition of +.I sig +without changing it, specify NULL for +.IR vec , +and a non-null pointer for +.IR ovec . +.P +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.P +The +.I sigvec +structure has the following form: +.P +.in +4n +.EX +struct sigvec { + void (*sv_handler)(int); /* Signal disposition */ + int sv_mask; /* Signals to be blocked in handler */ + int sv_flags; /* Flags */ +}; +.EE +.in +.P +The +.I sv_handler +field specifies the disposition of the signal, and is either: +the address of a signal handler function; +.BR SIG_DFL , +meaning the default disposition applies for the signal; or +.BR SIG_IGN , +meaning that the signal is ignored. +.P +If +.I sv_handler +specifies the address of a signal handler, then +.I sv_mask +specifies a mask of signals that are to be blocked while +the handler is executing. +In addition, the signal for which the handler is invoked is +also blocked. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.P +If +.I sv_handler +specifies the address of a signal handler, then the +.I sv_flags +field specifies flags controlling what happens when the handler is called. +This field may contain zero or more of the following flags: +.TP +.B SV_INTERRUPT +If the signal handler interrupts a blocking system call, +then upon return from the handler the system call is not restarted: +instead it fails with the error +.BR EINTR . +If this flag is not specified, then system calls are restarted +by default. +.TP +.B SV_RESETHAND +Reset the disposition of the signal to the default +before calling the signal handler. +If this flag is not specified, then the handler remains established +until explicitly removed by a later call to +.BR sigvec () +or until the process performs an +.BR execve (2). +.TP +.B SV_ONSTACK +Handle the signal on the alternate signal stack +(historically established under BSD using the obsolete +.BR sigstack () +function; the POSIX replacement is +.BR sigaltstack (2)). +.P +The +.BR sigmask () +macro constructs and returns a "signal mask" for +.IR signum . +For example, we can initialize the +.I vec.sv_mask +field given to +.BR sigvec () +using code such as the following: +.P +.in +4n +.EX +vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT); + /* Block SIGQUIT and SIGABRT during + handler execution */ +.EE +.in +.P +The +.BR sigblock () +function adds the signals in +.I mask +to the process's signal mask +(like POSIX +.IR sigprocmask(SIG_BLOCK) ), +and returns the process's previous signal mask. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.P +The +.BR sigsetmask () +function sets the process's signal mask to the value given in +.I mask +(like POSIX +.IR sigprocmask(SIG_SETMASK) ), +and returns the process's previous signal mask. +.P +The +.BR siggetmask () +function returns the process's current signal mask. +This call is equivalent to +.IR sigblock(0) . +.SH RETURN VALUE +The +.BR sigvec () +function returns 0 on success; on error, it returns \-1 and sets +.I errno +to indicate the error. +.P +The +.BR sigblock () +and +.BR sigsetmask () +functions return the previous signal mask. +.P +The +.BR sigmask () +macro returns the signal mask for +.IR signum . +.SH ERRORS +See the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigvec (), +.BR sigmask (), +.BR sigblock (), +.BR sigsetmask (), +.BR siggetmask () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR sigvec () +.TQ +.BR sigblock () +.TQ +.BR sigmask () +.TQ +.BR sigsetmask () +4.3BSD. +.TP +.BR siggetmask () +Unclear origin. +.TP +.BR sigvec () +Removed in glibc 2.21. +.SH NOTES +On 4.3BSD, the +.BR signal () +function provided reliable semantics (as when calling +.BR sigvec () +with +.I vec.sv_mask +equal to 0). +On System V, +.BR signal () +provides unreliable semantics. +POSIX.1 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.P +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigset (3), +.BR signal (7) diff --git a/man/man3/sigwait.3 b/man/man3/sigwait.3 new file mode 100644 index 0000000..f79c917 --- /dev/null +++ b/man/man3/sigwait.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigwait 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigwait \- wait for a signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.P +.BI "int sigwait(const sigset_t *restrict " set ", int *restrict " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigwait (): +.nf + Since glibc 2.26: + _POSIX_C_SOURCE >= 199506L + glibc 2.25 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR sigwait () +function suspends execution of the calling thread until +one of the signals specified in the signal set +.I set +becomes pending. +For a signal to become pending, +it must first be blocked with +.BR sigprocmask (2). +The function accepts the signal +(removes it from the pending list of signals), +and returns the signal number in +.IR sig . +.P +The operation of +.BR sigwait () +is the same as +.BR sigwaitinfo (2), +except that: +.IP \[bu] 3 +.BR sigwait () +returns only the signal number, rather than a +.I siginfo_t +structure describing the signal. +.IP \[bu] +The return values of the two functions are different. +.SH RETURN VALUE +On success, +.BR sigwait () +returns 0. +On error, it returns a positive error number (listed in ERRORS). +.SH ERRORS +.TP +.B EINVAL +.\" Does not occur for glibc. +.I set +contains an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigwait () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.BR sigwait () +is implemented using +.BR sigtimedwait (2); +consult its +.BR NOTES . +.P +The glibc implementation of +.BR sigwait () +silently ignores attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_sigmask (3). +.SH SEE ALSO +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR sigsetops (3), +.BR signal (7) diff --git a/man/man3/simpleq.3 b/man/man3/simpleq.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/simpleq.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/sin.3 b/man/man3/sin.3 new file mode 100644 index 0000000..7d90bee --- /dev/null +++ b/man/man3/sin.3 @@ -0,0 +1,122 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH sin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sin, sinf, sinl \- sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double sin(double " x ); +.BI "float sinf(float " x ); +.BI "long double sinl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sinf (), +.BR sinl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the sine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1 allows an optional range error for subnormal x +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sin (), +.BR sinf (), +.BR sinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6781 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR csin (3), +.BR sincos (3), +.BR tan (3) diff --git a/man/man3/sincos.3 b/man/man3/sincos.3 new file mode 100644 index 0000000..69769f1 --- /dev/null +++ b/man/man3/sincos.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH sincos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sincos, sincosf, sincosl \- calculate sin and cos simultaneously +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <math.h> +.P +.BI "void sincos(double " x ", double *" sin ", double *" cos ); +.BI "void sincosf(float " x ", float *" sin ", float *" cos ); +.BI "void sincosl(long double " x ", long double *" sin ", long double *" cos ); +.fi +.SH DESCRIPTION +Several applications need sine and cosine of the same angle +.IR x . +These functions compute both at the same time, and store the results in +.I *sin +and +.IR *cos . +Using this function can be more efficient than two separate calls to +.BR sin (3) +and +.BR cos (3). +.P +If +.I x +is a NaN, +a NaN is returned in +.I *sin +and +.IR *cos . +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, and +a NaN is returned in +.I *sin +and +.IR *cos . +.SH RETURN VALUE +These functions return +.IR void . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sincos (), +.BR sincosf (), +.BR sincosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH NOTES +To see the performance advantage of +.BR sincos (), +it may be necessary to disable +.BR gcc (1) +built-in optimizations, using flags such as: +.P +.in +4n +.EX +cc \-O \-lm \-fno\-builtin prog.c +.EE +.in +.SH BUGS +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=15467 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/sincosf.3 b/man/man3/sincosf.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man/man3/sincosf.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man/man3/sincosl.3 b/man/man3/sincosl.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man/man3/sincosl.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man/man3/sinf.3 b/man/man3/sinf.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man/man3/sinf.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man/man3/sinh.3 b/man/man3/sinh.3 new file mode 100644 index 0000000..a80a95f --- /dev/null +++ b/man/man3/sinh.3 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH sinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sinh, sinhf, sinhl \- hyperbolic sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double sinh(double " x ); +.BI "float sinhf(float " x ); +.BI "long double sinhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sinhf (), +.BR sinhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic sine of +.IR x , +which +is defined mathematically as: +.P +.nf + sinh(x) = (exp(x) \- exp(\-x)) / 2 +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as +.IR x . +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sinh (), +.BR sinhf (), +.BR sinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR csinh (3), +.BR tanh (3) diff --git a/man/man3/sinhf.3 b/man/man3/sinhf.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man/man3/sinhf.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man/man3/sinhl.3 b/man/man3/sinhl.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man/man3/sinhl.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man/man3/sinl.3 b/man/man3/sinl.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man/man3/sinl.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 new file mode 100644 index 0000000..8d3effc --- /dev/null +++ b/man/man3/sleep.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:16:02 1993 by Rik Faith (faith@cs.unc.edu) +.TH sleep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sleep \- sleep for a specified number of seconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "unsigned int sleep(unsigned int " "seconds" ); +.fi +.SH DESCRIPTION +.BR sleep () +causes the calling thread to sleep either until +the number of real-time seconds specified in +.I seconds +have elapsed or until a signal arrives which is not ignored. +.SH RETURN VALUE +Zero if the requested time has elapsed, +or the number of seconds left to sleep, +if the call was interrupted by a signal handler. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sleep () +T} Thread safety MT-Unsafe sig:SIGCHLD/linux +.TE +.SH VERSIONS +On Linux, +.BR sleep () +is implemented via +.BR nanosleep (2). +See the +.BR nanosleep (2) +man page for a discussion of the clock used. +.P +On some systems, +.BR sleep () +may be implemented using +.BR alarm (2) +and +.B SIGALRM +(POSIX.1 permits this); +mixing calls to +.BR alarm (2) +and +.BR sleep () +is a bad idea. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH CAVEATS +Using +.BR longjmp (3) +from a signal handler or modifying the handling of +.B SIGALRM +while sleeping will cause undefined results. +.SH SEE ALSO +.BR sleep (1), +.BR alarm (2), +.BR nanosleep (2), +.BR signal (2), +.BR signal (7) diff --git a/man/man3/slist.3 b/man/man3/slist.3 new file mode 100644 index 0000000..ecdfe5c --- /dev/null +++ b/man/man3/slist.3 @@ -0,0 +1,319 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH SLIST 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +SLIST_EMPTY, +SLIST_ENTRY, +SLIST_FIRST, +SLIST_FOREACH, +.\"SLIST_FOREACH_FROM, +.\"SLIST_FOREACH_FROM_SAFE, +.\"SLIST_FOREACH_SAFE, +SLIST_HEAD, +SLIST_HEAD_INITIALIZER, +SLIST_INIT, +SLIST_INSERT_AFTER, +SLIST_INSERT_HEAD, +SLIST_NEXT, +SLIST_REMOVE, +.\"SLIST_REMOVE_AFTER, +SLIST_REMOVE_HEAD +.\"SLIST_SWAP +\- implementation of a singly linked list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/queue.h> +.P +.B SLIST_ENTRY(TYPE); +.P +.B SLIST_HEAD(HEADNAME, TYPE); +.BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head ); +.BI "void SLIST_INIT(SLIST_HEAD *" head ); +.P +.BI "int SLIST_EMPTY(SLIST_HEAD *" head ); +.P +.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head , +.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.P +.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head ); +.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.P +.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ); +.\" .BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ); +.\" .P +.\" .BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm , +.BI " SLIST_ENTRY " NAME ); +.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head , +.BI " SLIST_ENTRY " NAME ); +.\" .BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm , +.\" .BI " SLIST_ENTRY " NAME ); +.\" .P +.\" .BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 , +.\" .BI " SLIST_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on singly linked lists. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR SLIST_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR SLIST_HEAD (). +.SS Creation +A singly linked list is headed by a structure defined by the +.BR SLIST_HEAD () +macro. +This structure contains a single pointer to the first element on the list. +The elements are singly linked +for minimum space and pointer manipulation overhead +at the expense of O(n) removal for arbitrary elements. +New elements can be added to the list +after an existing element +or at the head of the list. +An +.I SLIST_HEAD +structure is declared as follows: +.P +.in +4 +.EX +SLIST_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR SLIST_ENTRY () +declares a structure that connects the elements in +the list. +.P +.BR SLIST_HEAD_INITIALIZER () +evaluates to an initializer for the list +.IR head . +.P +.BR SLIST_INIT () +initializes the list referenced by +.IR head . +.P +.BR SLIST_EMPTY () +evaluates to true if there are no elements in the list. +.SS Insertion +.BR SLIST_INSERT_HEAD () +inserts the new element +.I elm +at the head of the list. +.P +.BR SLIST_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR SLIST_FIRST () +returns the first element in the list, or NULL if the list is empty. +.P +.BR SLIST_NEXT () +returns the next element in the list. +.P +.BR SLIST_FOREACH () +traverses the list referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR SLIST_FOREACH_FROM () +.\" behaves identically to +.\" .BR SLIST_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found SLIST element and begins the loop at +.\" .I var +.\" instead of the first element in the SLIST referenced by +.\" .IR head . +.\" .Pp +.\" .BR SLIST_FOREACH_SAFE () +.\" traverses the list referenced by +.\" .I head +.\" in the forward direction, assigning each element in +.\" turn to +.\" .IR var . +.\" However, unlike +.\" .BR SLIST_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR SLIST_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR SLIST_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found SLIST element and begins the loop at +.\" .I var +.\" instead of the first element in the SLIST referenced by +.\" .IR head . +.SS Removal +.BR SLIST_REMOVE () +removes the element +.I elm +from the list. +.P +.BR SLIST_REMOVE_HEAD () +removes the element +.I elm +from the head of the list. +For optimum efficiency, +elements being removed from the head of the list +should explicitly use this macro instead of the generic +.BR SLIST_REMOVE (). +.\" .P +.\" .BR SLIST_REMOVE_AFTER () +.\" removes the element after +.\" .I elm +.\" from the list. +.\" Unlike +.\" .IR SLIST_REMOVE , +.\" this macro does not traverse the entire list. +.\" .SS Other features +.\" .BR SLIST_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR SLIST_EMPTY () +returns nonzero if the list is empty, +and zero if the list contains at least one entry. +.P +.BR SLIST_FIRST (), +and +.BR SLIST_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR SLIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH BUGS +.BR SLIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR SLIST_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (slist.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> +\& +struct entry { + int data; + SLIST_ENTRY(entry) entries; /* Singly linked list */ +}; +\& +SLIST_HEAD(slisthead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct slisthead head; /* Singly linked list + head */ +\& + SLIST_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + SLIST_INSERT_HEAD(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + SLIST_INSERT_AFTER(n1, n2, entries); +\& + SLIST_REMOVE(&head, n2, entry, entries);/* Deletion */ + free(n2); +\& + n3 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head */ + free(n3); +\& + for (unsigned int i = 0; i < 5; i++) { + n1 = malloc(sizeof(struct entry)); + SLIST_INSERT_HEAD(&head, n1, entries); + n1\->data = i; + } +\& + /* Forward traversal */ + SLIST_FOREACH(np, &head, entries) + printf("%i\en", np\->data); +\& + while (!SLIST_EMPTY(&head)) { /* List deletion */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); + } + SLIST_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/snprintf.3 b/man/man3/snprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/snprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/sockatmark.3 b/man/man3/sockatmark.3 new file mode 100644 index 0000000..62d1ba1 --- /dev/null +++ b/man/man3/sockatmark.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sockatmark 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sockatmark \- determine whether socket is at out-of-band mark +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.P +.BI "int sockatmark(int " sockfd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sockatmark (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR sockatmark () +returns a value indicating whether or not the socket referred +to by the file descriptor +.I sockfd +is at the out-of-band mark. +If the socket is at the mark, then 1 is returned; +if the socket is not at the mark, 0 is returned. +This function does not remove the out-of-band mark. +.SH RETURN VALUE +A successful call to +.BR sockatmark () +returns 1 if the socket is at the out-of-band mark, or 0 if it is not. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +.\" POSIX.1 says ENOTTY for this case +.I sockfd +is not a file descriptor to which +.BR sockatmark () +can be applied. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sockatmark () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2.4. +POSIX.1-2001. +.SH NOTES +If +.BR sockatmark () +returns 1, then the out-of-band data can be read using the +.B MSG_OOB +flag of +.BR recv (2). +.P +Out-of-band data is supported only on some stream socket protocols. +.P +.BR sockatmark () +can safely be called from a handler for the +.B SIGURG +signal. +.P +.BR sockatmark () +is implemented using the +.B SIOCATMARK +.BR ioctl (2) +operation. +.SH BUGS +Prior to glibc 2.4, +.BR sockatmark () +did not work. +.SH EXAMPLES +The following code can be used after receipt of a +.B SIGURG +signal to read (and discard) all data up to the mark, +and then read the byte of data at the mark: +.P +.EX + char buf[BUF_LEN]; + char oobdata; + int atmark, s; +\& + for (;;) { + atmark = sockatmark(sockfd); + if (atmark == \-1) { + perror("sockatmark"); + break; + } +\& + if (atmark) + break; +\& + s = read(sockfd, buf, BUF_LEN); + if (s == \-1) + perror("read"); + if (s <= 0) + break; + } +\& + if (atmark == 1) { + if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) { + perror("recv"); + ... + } + } +.EE +.SH SEE ALSO +.BR fcntl (2), +.BR recv (2), +.BR send (2), +.BR tcp (7) diff --git a/man/man3/sprintf.3 b/man/man3/sprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/sprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/sqrt.3 b/man/man3/sqrt.3 new file mode 100644 index 0000000..6f012ab --- /dev/null +++ b/man/man3/sqrt.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH sqrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sqrt, sqrtf, sqrtl \- square root function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double sqrt(double " x ); +.BI "float sqrtf(float " x ); +.BI "long double sqrtl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sqrtf (), +.BR sqrtl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the nonnegative square root of +.IR x . +.SH RETURN VALUE +On success, these functions return the square root of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is less than \-0, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-0 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sqrt (), +.BR sqrtf (), +.BR sqrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR csqrt (3), +.BR hypot (3) diff --git a/man/man3/sqrtf.3 b/man/man3/sqrtf.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man/man3/sqrtf.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man/man3/sqrtl.3 b/man/man3/sqrtl.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man/man3/sqrtl.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man/man3/srand.3 b/man/man3/srand.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man/man3/srand.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man/man3/srand48.3 b/man/man3/srand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/srand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/srand48_r.3 b/man/man3/srand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/srand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/srandom.3 b/man/man3/srandom.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/srandom.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/srandom_r.3 b/man/man3/srandom_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/srandom_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/sscanf.3 b/man/man3/sscanf.3 new file mode 100644 index 0000000..46eef25 --- /dev/null +++ b/man/man3/sscanf.3 @@ -0,0 +1,730 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" modified to resemble the GNU libio setup used in the Linux libc +.\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de +.\" Modified, aeb, 970121 +.\" 2005-07-14, mtk, added description of %n$ form; various text +.\" incorporated from the GNU C library documentation ((C) The +.\" Free Software Foundation); other parts substantially rewritten. +.\" +.\" 2008-06-23, mtk +.\" Add ERRORS section. +.\" Document the 'a' and 'm' modifiers for dynamic string allocation. +.\" +.TH sscanf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sscanf, vsscanf \- input string format conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int sscanf(const char *restrict " str , +.BI " const char *restrict " format ", ...);" +.P +.B #include <stdarg.h> +.P +.BI "int vsscanf(const char *restrict " str , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vsscanf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR sscanf () +family of functions scans formatted input according to +.I format +as described below. +This format may contain +.IR "conversion specifications" ; +the results from such conversions, if any, +are stored in the locations pointed to by the +.I pointer +arguments that follow +.IR format . +Each +.I pointer +argument must be of a type that is appropriate for the value returned +by the corresponding conversion specification. +.P +If the number of conversion specifications in +.I format +exceeds the number of +.I pointer +arguments, the results are undefined. +If the number of +.I pointer +arguments exceeds the number of conversion specifications, then the excess +.I pointer +arguments are evaluated, but are otherwise ignored. +.P +.BR sscanf () +These functions +read their input from the string pointed to by +.IR str . +.P +The +.BR vsscanf () +function is analogous to +.BR vsprintf (3). +.P +The +.I format +string consists of a sequence of +.I directives +which describe how to process the sequence of input characters. +If processing of a directive fails, no further input is read, and +.BR sscanf () +returns. +A "failure" can be either of the following: +.IR "input failure" , +meaning that input characters were unavailable, or +.IR "matching failure" , +meaning that the input was inappropriate (see below). +.P +A directive is one of the following: +.TP +\[bu] +A sequence of white-space characters (space, tab, newline, etc.; see +.BR isspace (3)). +This directive matches any amount of white space, +including none, in the input. +.TP +\[bu] +An ordinary character (i.e., one other than white space or \[aq]%\[aq]). +This character must exactly match the next character of input. +.TP +\[bu] +A conversion specification, +which commences with a \[aq]%\[aq] (percent) character. +A sequence of characters from the input is converted according to +this specification, and the result is placed in the corresponding +.I pointer +argument. +If the next item of input does not match the conversion specification, +the conversion fails\[em]this is a +.IR "matching failure" . +.P +Each +.I conversion specification +in +.I format +begins with either the character \[aq]%\[aq] or the character sequence +"\fB%\fP\fIn\fP\fB$\fP" +(see below for the distinction) followed by: +.TP +\[bu] +An optional \[aq]*\[aq] assignment-suppression character: +.BR sscanf () +reads input as directed by the conversion specification, +but discards the input. +No corresponding +.I pointer +argument is required, and this specification is not +included in the count of successful assignments returned by +.BR scanf (). +.TP +\[bu] +For decimal conversions, an optional quote character (\[aq]). +This specifies that the input number may include thousands' +separators as defined by the +.B LC_NUMERIC +category of the current locale. +(See +.BR setlocale (3).) +The quote character may precede or follow the \[aq]*\[aq] +assignment-suppression character. +.TP +\[bu] +An optional \[aq]m\[aq] character. +This is used with string conversions +.RI ( %s , +.IR %c , +.IR %[ ), +and relieves the caller of the +need to allocate a corresponding buffer to hold the input: instead, +.BR sscanf () +allocates a buffer of sufficient size, +and assigns the address of this buffer to the corresponding +.I pointer +argument, which should be a pointer to a +.I "char\ *" +variable (this variable does not need to be initialized before the call). +The caller should subsequently +.BR free (3) +this buffer when it is no longer required. +.TP +\[bu] +An optional decimal integer which specifies the +.IR "maximum field width" . +Reading of characters stops either when this maximum is reached or +when a nonmatching character is found, whichever happens first. +Most conversions discard initial white space characters (the exceptions +are noted below), +and these discarded characters don't count toward the maximum field width. +String input conversions store a terminating null byte (\[aq]\e0\[aq]) +to mark the end of the input; +the maximum field width does not include this terminator. +.TP +\[bu] +An optional +.IR "type modifier character" . +For example, the +.B l +type modifier is used with integer conversions such as +.B %d +to specify that the corresponding +.I pointer +argument refers to a +.I "long" +rather than a pointer to an +.IR int . +.TP +\[bu] +A +.I "conversion specifier" +that specifies the type of input conversion to be performed. +.P +The conversion specifications in +.I format +are of two forms, either beginning with \[aq]%\[aq] or beginning with +"\fB%\fP\fIn\fP\fB$\fP". +The two forms should not be mixed in the same +.I format +string, except that a string containing +"\fB%\fP\fIn\fP\fB$\fP" +specifications can include +.B %% +and +.BR %* . +If +.I format +contains \[aq]%\[aq] +specifications, then these correspond in order with successive +.I pointer +arguments. +In the +"\fB%\fP\fIn\fP\fB$\fP" +form (which is specified in POSIX.1-2001, but not C99), +.I n +is a decimal integer that specifies that the converted input should +be placed in the location referred to by the +.IR n -th +.I pointer +argument following +.IR format . +.SS Conversions +The following +.I "type modifier characters" +can appear in a conversion specification: +.TP +.B h +Indicates that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I short +or +.I unsigned short +(rather than +.IR int ). +.TP +.B hh +As for +.BR h , +but the next pointer is a pointer to a +.I signed char +or +.IR "unsigned char" . +.TP +.B j +As for +.BR h , +but the next pointer is a pointer to an +.I intmax_t +or a +.IR uintmax_t . +This modifier was introduced in C99. +.TP +.B l +Indicates either that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I long +or +.I unsigned long +(rather than +.IR int ), +or that the conversion will be one of +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I double +(rather than +.IR float ). +If used with +.B %c +or +.BR %s , +the corresponding parameter is considered +as a pointer to a wide character or wide-character string respectively. +.\" This use of l was introduced in Amendment 1 to ISO C90. +.TP +.B ll +(ell-ell) +Indicates that the conversion will be one of +.BR b , +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.B n +and the next pointer is a pointer to a +.I long long +or +.I unsigned long long +(rather than +.IR int ). +.TP +.B L +Indicates that the conversion will be either +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I "long double" +or +(as a GNU extension) +the conversion will be +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP +and the next pointer is a pointer to +.IR "long long" . +.\" MTK, Jul 05: The following is no longer true for modern +.\" ANSI C (i.e., C99): +.\" (Note that long long is not an +.\" ANSI C +.\" type. Any program using this will not be portable to all +.\" architectures). +.TP +.B q +equivalent to +.BR L . +This specifier does not exist in ANSI C. +.TP +.B t +As for +.BR h , +but the next pointer is a pointer to a +.IR ptrdiff_t . +This modifier was introduced in C99. +.TP +.B z +As for +.BR h , +but the next pointer is a pointer to a +.IR size_t . +This modifier was introduced in C99. +.P +The following +.I "conversion specifiers" +are available: +.TP +.B % +Matches a literal \[aq]%\[aq]. +That is, +.B %\&% +in the format string matches a +single input \[aq]%\[aq] character. +No conversion is done (but initial white space characters are discarded), +and assignment does not occur. +.TP +.B d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR int . +.\" .TP +.\" .B D +.\" Equivalent to +.\" .IR ld ; +.\" this exists only for backward compatibility. +.\" (Note: thus only in libc4 +.\" In libc5 and glibc the +.\" .B %D +.\" is silently ignored, causing old programs to fail mysteriously.) +.TP +.B i +Matches an optionally signed integer; the next pointer must be a pointer to +.IR int . +The integer is read in base 16 if it begins with +.I 0x +or +.IR 0X , +in base 8 if it begins with +.IR 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.TP +.B o +Matches an unsigned octal integer; the next pointer must be a pointer to +.IR "unsigned int" . +.TP +.B u +Matches an unsigned decimal integer; the next pointer must be a +pointer to +.IR "unsigned int" . +.TP +.B x +Matches an unsigned hexadecimal integer +(that may optionally begin with a prefix of +.I 0x +or +.IR 0X , +which is discarded); the next pointer must +be a pointer to +.IR "unsigned int" . +.TP +.B X +Equivalent to +.BR x . +.TP +.B f +Matches an optionally signed floating-point number; the next pointer must +be a pointer to +.IR float . +.TP +.B e +Equivalent to +.BR f . +.TP +.B g +Equivalent to +.BR f . +.TP +.B E +Equivalent to +.BR f . +.TP +.B a +(C99) Equivalent to +.BR f . +.TP +.B s +Matches a sequence of non-white-space characters; +the next pointer must be a pointer to the initial element of a +character array that is long enough to hold the input sequence and +the terminating null byte (\[aq]\e0\[aq]), which is added automatically. +The input string stops at white space or at the maximum field +width, whichever occurs first. +.TP +.B c +Matches a sequence of characters whose length is specified by the +.I maximum field width +(default 1); the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters +(no terminating null byte is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.TP +.B \&[ +Matches a nonempty sequence of characters from the specified set of +accepted characters; the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters in the string, plus a +terminating null byte. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in (or not in) a particular set; +the set is defined by the characters between the open bracket +.B [ +character and a close bracket +.B ] +character. +The set +.I excludes +those characters if the first character after the open bracket is a +circumflex +.RB ( \[ha] ). +To include a close bracket in the set, make it the first character after +the open bracket or the circumflex; any other position will end the set. +The hyphen character +.B \- +is also special; when placed between two other characters, it adds all +intervening characters to the set. +To include a hyphen, make it the last +character before the final close bracket. +For instance, +.B [\[ha]]0\-9\-] +means +the set "everything except close bracket, zero through nine, and hyphen". +The string ends with the appearance of a character not in the (or, with a +circumflex, in) set or when the field width runs out. +.TP +.B p +Matches a pointer value (as printed by +.B %p +in +.BR printf (3)); +the next pointer must be a pointer to a pointer to +.IR void . +.TP +.B n +Nothing is expected; instead, the number of characters consumed thus far +from the input is stored through the next pointer, which must be a pointer +to +.IR int , +or variant whose size matches the (optionally) +supplied integer length modifier. +This is +.I not +a conversion and does +.I not +increase the count returned by the function. +The assignment can be suppressed with the +.B * +assignment-suppression character, but the effect on the +return value is undefined. +Therefore +.B %*n +conversions should not be used. +.SH RETURN VALUE +On success, these functions return the number of input items +successfully matched and assigned; +this can be fewer than provided for, +or even zero, in the event of an early matching failure. +.P +The value +.B EOF +is returned if the end of input is reached before either the first +successful conversion or a matching failure occurs. +.SH ERRORS +.TP +.B EILSEQ +Input byte sequence does not form a valid character. +.TP +.B EINVAL +Not enough arguments; or +.I format +is NULL. +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sscanf (), +.BR vsscanf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +The +.B q +specifier is the 4.4BSD notation for +.IR "long long" , +while +.B ll +or the usage of +.B L +in integer conversions is the GNU notation. +.P +The Linux version of these functions is based on the +.I GNU +.I libio +library. +Take a look at the +.I info +documentation of +.I GNU +.I libc (glibc-1.08) +for a more concise description. +.SH NOTES +.SS The 'a' assignment-allocation modifier +Originally, the GNU C library supported dynamic allocation for string inputs +(as a nonstandard extension) via the +.B a +character. +(This feature is present at least as far back as glibc 2.0.) +Thus, one could write the following to have +.BR sscanf () +allocate a buffer for a string, +with a pointer to that buffer being returned in +.IR *buf : +.P +.in +4n +.EX +char *buf; +sscanf(str, "%as", &buf); +.EE +.in +.P +The use of the letter +.B a +for this purpose was problematic, since +.B a +is also specified by the ISO C standard as a synonym for +.B f +(floating-point input). +POSIX.1-2008 instead specifies the +.B m +modifier for assignment allocation (as documented in DESCRIPTION, above). +.P +Note that the +.B a +modifier is not available if the program is compiled with +.I gcc\~\-std=c99 +or +.I gcc\~\-D_ISOC99_SOURCE +(unless +.B _GNU_SOURCE +is also specified), in which case the +.B a +is interpreted as a specifier for floating-point numbers (see above). +.P +Support for the +.B m +modifier was added to glibc 2.7, +and new programs should use that modifier instead of +.BR a . +.P +As well as being standardized by POSIX, the +.B m +modifier has the following further advantages over +the use of +.BR a : +.IP \[bu] 3 +It may also be applied to +.B %c +conversion specifiers (e.g., +.BR %3mc ). +.IP \[bu] +It avoids ambiguity with respect to the +.B %a +floating-point conversion specifier (and is unaffected by +.I gcc\~\-std=c99 +etc.). +.SH BUGS +.SS Numeric conversion specifiers +Use of the numeric conversion specifiers produces Undefined Behavior +for invalid input. +See +.UR https://port70.net/\:%7Ensz/\:c/\:c11/\:n1570.html\:#7.21.6.2p10 +C11 7.21.6.2/10 +.UE . +This is a bug in the ISO C standard, +and not an inherent design issue with the API. +However, +current implementations are not safe from that bug, +so it is not recommended to use them. +Instead, +programs should use functions such as +.BR strtol (3) +to parse numeric input. +Alternatively, +mitigate it by specifying a maximum field width. +.SS Nonstandard modifiers +These functions are fully C99 conformant, but provide the +additional modifiers +.B q +and +.B a +as well as an additional behavior of the +.B L +and +.B ll +modifiers. +The latter may be considered to be a bug, as it changes the +behavior of modifiers defined in C99. +.P +Some combinations of the type modifiers and conversion +specifiers defined by C99 do not make sense +(e.g., +.BR "%Ld" ). +While they may have a well-defined behavior on Linux, this need not +to be so on other architectures. +Therefore it usually is better to use +modifiers that are not defined by C99 at all, that is, use +.B q +instead of +.B L +in combination with +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP +conversions or +.BR ll . +.P +The usage of +.B q +is not the same as on 4.4BSD, +as it may be used in float conversions equivalently to +.BR L . +.SH EXAMPLES +To use the dynamic allocation conversion specifier, specify +.B m +as a length modifier (thus +.B %ms +or +\fB%m[\fP\fIrange\fP\fB]\fP). +The caller must +.BR free (3) +the returned string, as in the following example: +.P +.in +4n +.EX +char *p; +int n; +\& +errno = 0; +n = sscanf(str, "%m[a\-z]", &p); +if (n == 1) { + printf("read: %s\en", p); + free(p); +} else if (errno != 0) { + perror("sscanf"); +} else { + fprintf(stderr, "No matching characters\en"); +} +.EE +.in +.P +As shown in the above example, it is necessary to call +.BR free (3) +only if the +.BR sscanf () +call successfully read a string. +.SH SEE ALSO +.BR getc (3), +.BR printf (3), +.BR setlocale (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/ssignal.3 b/man/man3/ssignal.3 new file mode 100644 index 0000000..047cab2 --- /dev/null +++ b/man/man3/ssignal.3 @@ -0,0 +1 @@ +.so man3/gsignal.3 diff --git a/man/man3/stailq.3 b/man/man3/stailq.3 new file mode 100644 index 0000000..2441dcf --- /dev/null +++ b/man/man3/stailq.3 @@ -0,0 +1,377 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH STAILQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +.\"SIMPLEQ_CONCAT, +SIMPLEQ_EMPTY, +SIMPLEQ_ENTRY, +SIMPLEQ_FIRST, +SIMPLEQ_FOREACH, +.\"SIMPLEQ_FOREACH_FROM, +.\"SIMPLEQ_FOREACH_FROM_SAFE, +.\"SIMPLEQ_FOREACH_SAFE, +SIMPLEQ_HEAD, +SIMPLEQ_HEAD_INITIALIZER, +SIMPLEQ_INIT, +SIMPLEQ_INSERT_AFTER, +SIMPLEQ_INSERT_HEAD, +SIMPLEQ_INSERT_TAIL, +.\"SIMPLEQ_LAST, +SIMPLEQ_NEXT, +SIMPLEQ_REMOVE, +.\"SIMPLEQ_REMOVE_AFTER, +SIMPLEQ_REMOVE_HEAD, +.\"SIMPLEQ_SWAP, +STAILQ_CONCAT, +STAILQ_EMPTY, +STAILQ_ENTRY, +STAILQ_FIRST, +STAILQ_FOREACH, +.\"STAILQ_FOREACH_FROM, +.\"STAILQ_FOREACH_FROM_SAFE, +.\"STAILQ_FOREACH_SAFE, +STAILQ_HEAD, +STAILQ_HEAD_INITIALIZER, +STAILQ_INIT, +STAILQ_INSERT_AFTER, +STAILQ_INSERT_HEAD, +STAILQ_INSERT_TAIL, +.\"STAILQ_LAST, +STAILQ_NEXT, +STAILQ_REMOVE, +.\"STAILQ_REMOVE_AFTER, +STAILQ_REMOVE_HEAD, +.\"STAILQ_SWAP +\- implementation of a singly linked tail queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/queue.h> +.P +.B STAILQ_ENTRY(TYPE); +.P +.B STAILQ_HEAD(HEADNAME, TYPE); +.BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head ); +.BI "void STAILQ_INIT(STAILQ_HEAD *" head ); +.P +.BI "int STAILQ_EMPTY(STAILQ_HEAD *" head ); +.P +.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.P +.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ); +.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm , +.\" .BI " STAILQ_ENTRY " NAME ); +.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.P +.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ); +.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ); +.\" .P +.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE," +.BI " STAILQ_ENTRY " NAME ); +.BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head , +.BI " STAILQ_ENTRY " NAME ); +.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm , +.\" .BI " STAILQ_ENTRY " NAME ); +.P +.BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ); +.\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 , +.\" .BI " STAILQ_ENTRY " NAME ); +.fi +.IR Note : +Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see NOTES. +.SH DESCRIPTION +These macros define and operate on singly linked tail queues. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR STAILQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure that must be declared +using the macro +.BR STAILQ_HEAD (). +.SS Creation +A singly linked tail queue is headed by a structure defined by the +.BR STAILQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are singly linked for minimum space and pointer +manipulation overhead at the expense of O(n) removal for arbitrary elements. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.I STAILQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +STAILQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR STAILQ_ENTRY () +declares a structure that connects the elements in the tail queue. +.P +.BR STAILQ_HEAD_INITIALIZER () +evaluates to an initializer for the tail queue +.IR head . +.P +.BR STAILQ_INIT () +initializes the tail queue referenced by +.IR head . +.P +.BR STAILQ_EMPTY () +evaluates to true if there are no items on the tail queue. +.SS Insertion +.BR STAILQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the tail queue. +.P +.BR STAILQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the tail queue. +.P +.BR STAILQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR STAILQ_FIRST () +returns the first item on the tail queue or NULL if the tail queue is empty. +.\" .P +.\" .BR STAILQ_LAST () +.\" returns the last item on the tail queue. +.\" If the tail queue is empty the return value is NULL . +.P +.BR STAILQ_NEXT () +returns the next item on the tail queue, or NULL this item is the last. +.P +.BR STAILQ_FOREACH () +traverses the tail queue referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR STAILQ_FOREACH_FROM () +.\" behaves identically to +.\" .BR STAILQ_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found STAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the STAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR STAILQ_FOREACH_SAFE () +.\" traverses the tail queue referenced by +.\" .I head +.\" in the forward direction, assigning each element +.\" in turn to +.\" .IR var . +.\" However, unlike +.\" .BR STAILQ_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR STAILQ_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR STAILQ_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found STAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the STAILQ referenced by +.\" .IR head . +.SS Removal +.BR STAILQ_REMOVE () +removes the element +.I elm +from the tail queue. +.P +.BR STAILQ_REMOVE_HEAD () +removes the element at the head of the tail queue. +For optimum efficiency, +elements being removed from the head of the tail queue should +use this macro explicitly rather than the generic +.BR STAILQ_REMOVE () +macro. +.\" .P +.\" .BR STAILQ_REMOVE_AFTER () +.\" removes the element after +.\" .I elm +.\" from the tail queue. +.\" Unlike +.\" .BR STAILQ_REMOVE (), +.\" this macro does not traverse the entire tail queue. +.SS Other features +.BR STAILQ_CONCAT () +concatenates the tail queue headed by +.I head2 +onto the end of the one headed by +.I head1 +removing all entries from the former. +.\" .P +.\" .BR STAILQ_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR STAILQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR STAILQ_FIRST (), +and +.BR STAILQ_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR STAILQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH VERSIONS +Some BSDs provide SIMPLEQ instead of STAILQ. +They are identical, but for historical reasons +they were named differently on different BSDs. +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD. +For compatibility reasons, some systems provide both sets of macros. +glibc provides both STAILQ and SIMPLEQ, +which are identical except for a missing SIMPLEQ equivalent to +.BR STAILQ_CONCAT (). +.SH BUGS +.BR STAILQ_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR STAILQ_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH EXAMPLES +.\" SRC BEGIN (stailq.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> +\& +struct entry { + int data; + STAILQ_ENTRY(entry) entries; /* Singly linked tail queue */ +}; +\& +STAILQ_HEAD(stailhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct stailhead head; /* Singly linked tail queue + head */ +\& + STAILQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + STAILQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + STAILQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + STAILQ_INSERT_AFTER(&head, n1, n2, entries); +\& + STAILQ_REMOVE(&head, n2, entry, entries); /* Deletion */ + free(n2); +\& + n3 = STAILQ_FIRST(&head); + STAILQ_REMOVE_HEAD(&head, entries); /* Deletion from the head */ + free(n3); +\& + n1 = STAILQ_FIRST(&head); + n1\->data = 0; + for (unsigned int i = 1; i < 5; i++) { + n1 = malloc(sizeof(struct entry)); + STAILQ_INSERT_HEAD(&head, n1, entries); + n1\->data = i; + } + /* Forward traversal */ + STAILQ_FOREACH(np, &head, entries) + printf("%i\en", np\->data); + /* TailQ deletion */ + n1 = STAILQ_FIRST(&head); + while (n1 != NULL) { + n2 = STAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + STAILQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/static_assert.3 b/man/man3/static_assert.3 new file mode 100644 index 0000000..ee83779 --- /dev/null +++ b/man/man3/static_assert.3 @@ -0,0 +1,119 @@ +.\" Copyright (c) 2022 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH static_assert 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +static_assert, _Static_assert \- fail compilation if assertion is false +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <assert.h> +.P +.BI "void static_assert(scalar " constant-expression ", const char *" msg ); +.P +/* Since C23: */ +.BI "void static_assert(scalar " constant-expression ); +.fi +.SH DESCRIPTION +This macro is similar to +.BR \%assert (3), +but it works at compile time, +generating a compilation error (with an optional message) +when the input is false (i.e., compares equal to zero). +.P +If the input is nonzero, +no code is emitted. +.P +.I msg +must be a string literal. +Since C23, this argument is optional. +.P +There's a keyword, +.BR \%_Static_assert (), +that behaves identically, +and can be used without including +.IR <assert.h> . +.SH RETURN VALUE +No value is returned. +.SH VERSIONS +In C11, +the second argument +.RI ( msg ) +was mandatory; +since C23, +it can be omitted. +.SH STANDARDS +C11 and later. +.SH EXAMPLES +.BR static_assert () +can't be used in some places, +like for example at global scope. +For that, +a macro +.BR \%must_be () +can be written in terms of +.BR \%static_assert (). +The following program uses the macro to get the size of an array safely. +.P +.in +4n +.\" SRC BEGIN (must_be.c) +.EX +#include <assert.h> +#include <stddef.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +/* + * This macro behaves like static_assert(), failing to + * compile if its argument is not true. However, it always + * returns 0, which allows using it everywhere an expression + * can be used. + */ +#define must_be(e) \e +( \e + 0 * (int) sizeof( \e + struct { \e + static_assert(e); \e + int ISO_C_forbids_a_struct_with_no_members; \e + } \e + ) \e +) +\& +#define is_same_type(a, b) \e + __builtin_types_compatible_p(typeof(a), typeof(b)) +\& +#define is_array(arr) (!is_same_type((arr), &*(arr))) +#define must_be_array(arr) must_be(is_array(arr)) +\& +#define sizeof_array(arr) (sizeof(arr) + must_be_array(arr)) +#define nitems(arr) (sizeof((arr)) / sizeof((arr)[0]) \e + + must_be_array(arr)) +\& +int foo[10]; +int8_t bar[sizeof_array(foo)]; +\& +int +main(void) +{ + for (size_t i = 0; i < nitems(foo); i++) { + foo[i] = i; + } +\& + memcpy(bar, foo, sizeof_array(bar)); +\& + for (size_t i = 0; i < nitems(bar); i++) { + printf("%d,", bar[i]); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR assert (3) diff --git a/man/man3/statvfs.3 b/man/man3/statvfs.3 new file mode 100644 index 0000000..15b4f86 --- /dev/null +++ b/man/man3/statvfs.3 @@ -0,0 +1,256 @@ +'\" t +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" The pathconf note is from Walter Harms +.\" This is not a system call on Linux +.\" +.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH statvfs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +statvfs, fstatvfs \- get filesystem statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/statvfs.h> +.P +.BI "int statvfs(const char *restrict " path \ +", struct statvfs *restrict " buf ); +.BI "int fstatvfs(int " fd ", struct statvfs *" buf ); +.fi +.SH DESCRIPTION +The function +.BR statvfs () +returns information about a mounted filesystem. +.I path +is the pathname of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statvfs +structure defined approximately as follows: +.P +.in +4n +.EX +struct statvfs { + unsigned long f_bsize; /* Filesystem block size */ + unsigned long f_frsize; /* Fragment size */ + fsblkcnt_t f_blocks; /* Size of fs in f_frsize units */ + fsblkcnt_t f_bfree; /* Number of free blocks */ + fsblkcnt_t f_bavail; /* Number of free blocks for + unprivileged users */ + fsfilcnt_t f_files; /* Number of inodes */ + fsfilcnt_t f_ffree; /* Number of free inodes */ + fsfilcnt_t f_favail; /* Number of free inodes for + unprivileged users */ + unsigned long f_fsid; /* Filesystem ID */ + unsigned long f_flag; /* Mount flags */ + unsigned long f_namemax; /* Maximum filename length */ +}; +.EE +.in +.P +Here the types +.I fsblkcnt_t +and +.I fsfilcnt_t +are defined in +.IR <sys/types.h> . +Both used to be +.IR "unsigned long" . +.P +The field +.I f_flag +is a bit mask indicating various options that were employed +when mounting this filesystem. +It contains zero or more of the following flags: +.\" XXX Keep this list in sync with statfs(2) +.TP +.B ST_MANDLOCK +Mandatory locking is permitted on the filesystem (see +.BR fcntl (2)). +.TP +.B ST_NOATIME +Do not update access times; see +.BR mount (2). +.TP +.B ST_NODEV +Disallow access to device special files on this filesystem. +.TP +.B ST_NODIRATIME +Do not update directory access times; see +.BR mount (2). +.TP +.B ST_NOEXEC +Execution of programs is disallowed on this filesystem. +.TP +.B ST_NOSUID +The set-user-ID and set-group-ID bits are ignored by +.BR exec (3) +for executable files on this filesystem +.TP +.B ST_RDONLY +This filesystem is mounted read-only. +.TP +.B ST_RELATIME +Update atime relative to mtime/ctime; see +.BR mount (2). +.TP +.B ST_SYNCHRONOUS +Writes are synched to the filesystem immediately (see the description of +.B O_SYNC +in +.BR open (2)). +.P +It is unspecified whether all members of the returned struct +have meaningful values on all filesystems. +.P +.BR fstatvfs () +returns the same information about an open file referenced by descriptor +.IR fd . +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.RB ( statvfs ()) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fstatvfs ()) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I Buf +or +.I path +points to an invalid address. +.TP +.B EINTR +This call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +.RB ( statvfs ()) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +.RB ( statvfs ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( statvfs ()) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The filesystem does not support this call. +.TP +.B ENOTDIR +.RB ( statvfs ()) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR statvfs (), +.BR fstatvfs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Only the +.B ST_NOSUID +and +.B ST_RDONLY +flags of the +.I f_flag +field are specified in POSIX.1. +To obtain definitions of the remaining flags, one must define +.BR _GNU_SOURCE . +.SH NOTES +The Linux kernel has system calls +.BR statfs (2) +and +.BR fstatfs (2) +to support this library call. +.P +The glibc implementations of +.P +.in +4n +.EX +pathconf(path, _PC_REC_XFER_ALIGN); +pathconf(path, _PC_ALLOC_SIZE_MIN); +pathconf(path, _PC_REC_MIN_XFER_SIZE); +.EE +.in +.P +respectively use the +.IR f_frsize , +.IR f_frsize , +and +.I f_bsize +fields returned by a call to +.BR statvfs () +with the argument +.IR path . +.P +Under Linux, +.I f_favail +is always the same as +.IR f_ffree , +and there's no way for a filesystem to report otherwise. +This is not an issue, +since no filesystems with an inode root reservation exist. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Before glibc 2.13, +.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d +.BR statvfs () +populated the bits of the +.I f_flag +field by scanning the mount options shown in +.IR /proc/mounts . +However, starting with Linux 2.6.36, the underlying +.BR statfs (2) +system call provides the necessary information via the +.I f_flags +field, and since glibc 2.13, the +.BR statvfs () +function will use information from that field rather than scanning +.IR /proc/mounts . +.SH SEE ALSO +.BR statfs (2) diff --git a/man/man3/stdarg.3 b/man/man3/stdarg.3 new file mode 100644 index 0000000..40f6cc9 --- /dev/null +++ b/man/man3/stdarg.3 @@ -0,0 +1,297 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu +.\" Additions, 2001-10-14, aeb +.\" +.TH stdarg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdarg.h> +.P +.BI "void va_start(va_list " ap ", " last ); +.IB type " va_arg(va_list " ap ", " type ); +.BI "void va_end(va_list " ap ); +.BI "void va_copy(va_list " dest ", va_list " src ); +.fi +.SH DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.I <stdarg.h> +declares a type +.I va_list +and defines three macros for stepping through a list of arguments whose +number and types are not known to the called function. +.P +The called function must declare an object of type +.I va_list +which is used by the macros +.BR va_start (), +.BR va_arg (), +and +.BR va_end (). +.SS va_start() +The +.BR va_start () +macro initializes +.I ap +for subsequent use by +.BR va_arg () +and +.BR va_end (), +and must be called first. +.P +The argument +.I last +is the name of the last argument before the variable argument list, that is, +the last argument of which the calling function knows the type. +.P +Because the address of this argument may be used in the +.BR va_start () +macro, it should not be declared as a register variable, +or as a function or an array type. +.SS va_arg() +The +.BR va_arg () +macro expands to an expression that has the type and value of the next +argument in the call. +The argument +.I ap +is the +.I va_list +.I ap +initialized by +.BR va_start (). +Each call to +.BR va_arg () +modifies +.I ap +so that the next call returns the next argument. +The argument +.I type +is a type name specified so that the type of a pointer to an object that +has the specified type can be obtained simply by adding a * to +.IR type . +.P +The first use of the +.BR va_arg () +macro after that of the +.BR va_start () +macro returns the argument after +.IR last . +Successive invocations return the values of the remaining arguments. +.P +If there is no next argument, or if +.I type +is not compatible with the type of the actual next argument (as promoted +according to the default argument promotions), random errors will occur. +.P +If +.I ap +is passed to a function that uses +.BI va_arg( ap , type ), +then the value of +.I ap +is undefined after the return of that function. +.SS va_end() +Each invocation of +.BR va_start () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +After the call +.BI va_end( ap ) +the variable +.I ap +is undefined. +Multiple traversals of the list, each +bracketed by +.BR va_start () +and +.BR va_end () +are possible. +.BR va_end () +may be a macro or a function. +.SS va_copy() +The +.BR va_copy () +macro copies the (previously initialized) variable argument list +.I src +to +.IR dest . +The behavior is as if +.BR va_start () +were applied to +.I dest +with the same +.I last +argument, followed by the same number of +.BR va_arg () +invocations that was used to reach the current state of +.IR src . +.P +.\" Proposal from clive@demon.net, 1997-02-28 +An obvious implementation would have a +.I va_list +be a pointer to the stack frame of the variadic function. +In such a setup (by far the most common) there seems +nothing against an assignment +.P +.in +4n +.EX +va_list aq = ap; +.EE +.in +.P +Unfortunately, there are also systems that make it an +array of pointers (of length 1), and there one needs +.P +.in +4n +.EX +va_list aq; +*aq = *ap; +.EE +.in +.P +Finally, on systems where arguments are passed in registers, +it may be necessary for +.BR va_start () +to allocate memory, store the arguments there, and also +an indication of which argument is next, so that +.BR va_arg () +can step through the list. +Now +.BR va_end () +can free the allocated memory again. +To accommodate this situation, C99 adds a macro +.BR va_copy (), +so that the above assignment can be replaced by +.P +.in +4n +.EX +va_list aq; +va_copy(aq, ap); +\&... +va_end(aq); +.EE +.in +.P +Each invocation of +.BR va_copy () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +Some systems that do not supply +.BR va_copy () +have +.B __va_copy +instead, since that was the name used in the draft proposal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR va_start (), +.BR va_end (), +.BR va_copy () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR va_arg () +T} Thread safety MT-Safe race:ap +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR va_start () +.TQ +.BR va_arg () +.TQ +.BR va_end () +C89, POSIX.1-2001. +.TP +.BR va_copy () +C99, POSIX.1-2001. +.SH CAVEATS +Unlike the historical +.B varargs +macros, the +.B stdarg +macros do not permit programmers to code a function with no fixed +arguments. +This problem generates work mainly when converting +.B varargs +code to +.B stdarg +code, but it also creates difficulties for variadic functions that wish to +pass all of their arguments on to a function that takes a +.I va_list +argument, such as +.BR vfprintf (3). +.SH EXAMPLES +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.P +.EX +#include <stdio.h> +#include <stdarg.h> +\& +void +foo(char *fmt, ...) /* \[aq]...\[aq] is C syntax for a variadic function */ +\& +{ + va_list ap; + int d; + char c; + char *s; +\& + va_start(ap, fmt); + while (*fmt) + switch (*fmt++) { + case \[aq]s\[aq]: /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case \[aq]d\[aq]: /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case \[aq]c\[aq]: /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.EE +.SH SEE ALSO +.BR vprintf (3), +.BR vscanf (3), +.BR vsyslog (3) diff --git a/man/man3/stderr.3 b/man/man3/stderr.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man/man3/stderr.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man/man3/stdin.3 b/man/man3/stdin.3 new file mode 100644 index 0000000..7ffbc9a --- /dev/null +++ b/man/man3/stdin.3 @@ -0,0 +1,160 @@ +.\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998 +.\" +.\" This man page was written in 1998 by David A. Holland +.\" Polished a bit by aeb. +.\" +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" Placed in the Public Domain. +.\" %%%LICENSE_END +.\" +.\" 2005-06-16 mtk, mentioned freopen() +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH stdin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdin, stdout, stderr \- standard I/O streams +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "extern FILE *" stdin ; +.BI "extern FILE *" stdout ; +.BI "extern FILE *" stderr ; +.fi +.SH DESCRIPTION +Under normal circumstances every UNIX program has three streams opened +for it when it starts up, one for input, one for output, and one for +printing diagnostic or error messages. +These are typically attached to +the user's terminal (see +.BR tty (4)) +but might instead refer to files or other devices, depending on what +the parent process chose to set up. +(See also the "Redirection" section of +.BR sh (1).) +.P +The input stream is referred to as "standard input"; the output stream is +referred to as "standard output"; and the error stream is referred to +as "standard error". +These terms are abbreviated to form the symbols +used to refer to these files, namely +.IR stdin , +.IR stdout , +and +.IR stderr . +.P +Each of these symbols is a +.BR stdio (3) +macro of type pointer to +.IR FILE , +and can be used with functions like +.BR fprintf (3) +or +.BR fread (3). +.P +Since +.IR FILE s +are a buffering wrapper around UNIX file descriptors, the +same underlying files may also be accessed using the raw UNIX file +interface, that is, the functions like +.BR read (2) +and +.BR lseek (2). +.P +On program startup, the integer file descriptors +associated with the streams +.IR stdin , +.IR stdout , +and +.I stderr +are 0, 1, and 2, respectively. +The preprocessor symbols +.BR STDIN_FILENO , +.BR STDOUT_FILENO , +and +.B STDERR_FILENO +are defined with these values in +.IR <unistd.h> . +(Applying +.BR freopen (3) +to one of these streams can change the file descriptor number +associated with the stream.) +.P +Note that mixing use of +.IR FILE s +and raw file descriptors can produce +unexpected results and should generally be avoided. +(For the masochistic among you: POSIX.1, section 8.2.3, describes +in detail how this interaction is supposed to work.) +A general rule is that file descriptors are handled in the kernel, +while stdio is just a library. +This means for example, that after an +.BR exec (3), +the child inherits all open file descriptors, but all old streams +have become inaccessible. +.P +Since the symbols +.IR stdin , +.IR stdout , +and +.I stderr +are specified to be macros, assigning to them is nonportable. +The standard streams can be made to refer to different files +with help of the library function +.BR freopen (3), +specially introduced to make it possible to reassign +.IR stdin , +.IR stdout , +and +.IR stderr . +The standard streams are closed by a call to +.BR exit (3) +and by normal program termination. +.SH STANDARDS +C11, POSIX.1-2008. +.P +The standards also stipulate that these three +streams shall be open at program startup. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +The stream +.I stderr +is unbuffered. +The stream +.I stdout +is line-buffered when it points to a terminal. +Partial lines will not +appear until +.BR fflush (3) +or +.BR exit (3) +is called, or a newline is printed. +This can produce unexpected +results, especially with debugging output. +The buffering mode of the standard streams (or any other stream) +can be changed using the +.BR setbuf (3) +or +.BR setvbuf (3) +call. +Note that in case +.I stdin +is associated with a terminal, there may also be input buffering +in the terminal driver, entirely unrelated to stdio buffering. +(Indeed, normally terminal input is line buffered in the kernel.) +This kernel input handling can be modified using calls like +.BR tcsetattr (3); +see also +.BR stty (1), +and +.BR termios (3). +.SH SEE ALSO +.BR csh (1), +.BR sh (1), +.BR open (2), +.BR fopen (3), +.BR stdio (3) diff --git a/man/man3/stdio.3 b/man/man3/stdio.3 new file mode 100644 index 0000000..45a8727 --- /dev/null +++ b/man/man3/stdio.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 1990, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 +.\" +.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu +.\" Modified, 2001-12-26, aeb +.\" +.TH stdio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdio \- standard input/output library functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *" stdin ; +.BI "FILE *" stdout ; +.BI "FILE *" stderr ; +.fi +.SH DESCRIPTION +The standard I/O library provides a simple and efficient buffered stream +I/O interface. +Input and output is mapped into logical data streams and the +physical I/O characteristics are concealed. +The functions and macros are +listed below; more information is available from the individual man pages. +.P +A stream is associated with an external file (which may be a physical +device) by +.I opening +a file, which may involve creating a new file. +Creating an existing file +causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, +as opposed to a terminal), then a +.I file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. +If append mode is used, +it is unspecified whether the position indicator will be placed at the +start or the end of the file. +The position indicator is maintained by +subsequent reads, writes, and positioning requests. +All input occurs as if the characters were read by successive calls to the +.BR fgetc (3) +function; all output takes place as if all characters were written by +successive calls to the +.BR fputc (3) +function. +.P +A file is disassociated from a stream by +.I closing +the file. +Output streams are flushed (any unwritten buffer contents are +transferred to the host environment) before the stream is disassociated from +the file. +The value of a pointer to a +.I FILE +object is indeterminate after a file is closed (garbage). +.P +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be +repositioned at the start). +If the main function returns to its original +caller, or the +.BR exit (3) +function is called, all open files are closed (hence all output streams are +flushed) before program termination. +Other methods of program termination, +such as +.BR abort (3) +do not bother about closing files properly. +.P +At program startup, three text streams are predefined and need not be +opened explicitly: +.I standard input +(for reading conventional input), +.I standard output +(for writing conventional output), and +.I standard error +(for writing diagnostic output). +These streams are abbreviated +.IR stdin , +.IR stdout , +and +.IR stderr . +When opened, the standard error stream is not fully buffered; the standard +input and output streams are fully buffered if and only if the streams do +not refer to an interactive device. +.P +Output streams that refer to terminal devices are always line buffered by +default; pending output to such streams is written automatically whenever +an input stream that refers to a terminal device is read. +In cases where a +large amount of computation is done after printing part of a line on an +output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output will +appear. +.P +The +.I stdio +library is a part of the library +.B libc +and routines are automatically loaded as needed by +.BR cc (1). +The +SYNOPSIS +sections of the following manual pages indicate which include files are to +be used, what the compiler declaration for the function looks like and +which external variables are of interest. +.P +The following are defined as macros; these names may not be reused without +first removing their current definitions with +.BR #undef : +.BR BUFSIZ , +.BR EOF , +.BR FILENAME_MAX , +.BR FOPEN_MAX , +.BR L_cuserid , +.BR L_ctermid , +.BR L_tmpnam , +.BR NULL , +.BR SEEK_END , +.BR SEEK_SET , +.BR SEEK_CUR , +.BR TMP_MAX , +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno , +.\" Not on Linux: .BR fropen , +.\" Not on Linux: .BR fwopen , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR stderr , +.BR stdin , +.BR stdout . +Function versions of the macro functions +.BR feof , +.BR ferror , +.BR clearerr , +.BR fileno , +.BR getc , +.BR getchar , +.BR putc , +and +.B putchar +exist and will be used if the macros definitions are explicitly removed. +.SS List of functions +.TS +; +lb lbx +l l. +Function Description +_ +\fBclearerr\fP(3) T{ +check and reset stream status +T} +\fBfclose\fP(3) T{ +close a stream +T} +\fBfdopen\fP(3) T{ +stream open functions +T} +\fBfeof\fP(3) T{ +check and reset stream status +T} +\fBferror\fP(3) T{ +check and reset stream status +T} +\fBfflush\fP(3) T{ +flush a stream +T} +\fBfgetc\fP(3) T{ +get next character or word from input stream +T} +\fBfgetpos\fP(3) T{ +reposition a stream +T} +\fBfgets\fP(3) T{ +get a line from a stream +T} +\fBfileno\fP(3) T{ +return the integer descriptor of the argument stream +T} +\fBfmemopen\fP(3) T{ +open memory as stream +T} +\fBfopen\fP(3) T{ +stream open functions +T} +\fBfopencookie\fP(3) T{ +open a custom stream +T} +\fBfprintf\fP(3) T{ +formatted output conversion +T} +\fBfpurge\fP(3) T{ +flush a stream +T} +\fBfputc\fP(3) T{ +output a character or word to a stream +T} +\fBfputs\fP(3) T{ +output a line to a stream +T} +\fBfread\fP(3) T{ +binary stream input/output +T} +\fBfreopen\fP(3) T{ +stream open functions +T} +\fBfscanf\fP(3) T{ +input format conversion +T} +\fBfseek\fP(3) T{ +reposition a stream +T} +\fBfsetpos\fP(3) T{ +reposition a stream +T} +\fBftell\fP(3) T{ +reposition a stream +T} +\fBfwrite\fP(3) T{ +binary stream input/output +T} +\fBgetc\fP(3) T{ +get next character or word from input stream +T} +\fBgetchar\fP(3) T{ +get next character or word from input stream +T} +\fBgets\fP(3) T{ +get a line from a stream +T} +\fBgetw\fP(3) T{ +get next character or word from input stream +T} +\fBmktemp\fP(3) T{ +make temporary filename (unique) +T} +\fBopen_memstream\fP(3) T{ +open a dynamic memory buffer stream +T} +\fBopen_wmemstream\fP(3) T{ +open a dynamic memory buffer stream +T} +\fBperror\fP(3) T{ +system error messages +T} +\fBprintf\fP(3) T{ +formatted output conversion +T} +\fBputc\fP(3) T{ +output a character or word to a stream +T} +\fBputchar\fP(3) T{ +output a character or word to a stream +T} +\fBputs\fP(3) T{ +output a line to a stream +T} +\fBputw\fP(3) T{ +output a character or word to a stream +T} +\fBremove\fP(3) T{ +remove directory entry +T} +\fBrewind\fP(3) T{ +reposition a stream +T} +\fBscanf\fP(3) T{ +input format conversion +T} +\fBsetbuf\fP(3) T{ +stream buffering operations +T} +\fBsetbuffer\fP(3) T{ +stream buffering operations +T} +\fBsetlinebuf\fP(3) T{ +stream buffering operations +T} +\fBsetvbuf\fP(3) T{ +stream buffering operations +T} +\fBsprintf\fP(3) T{ +formatted output conversion +T} +\fBsscanf\fP(3) T{ +input format conversion +T} +\fBstrerror\fP(3) T{ +system error messages +T} +\fBsys_errlist\fP(3) T{ +system error messages +T} +\fBsys_nerr\fP(3) T{ +system error messages +T} +\fBtempnam\fP(3) T{ +temporary file routines +T} +\fBtmpfile\fP(3) T{ +temporary file routines +T} +\fBtmpnam\fP(3) T{ +temporary file routines +T} +\fBungetc\fP(3) T{ +un-get character from input stream +T} +\fBvfprintf\fP(3) T{ +formatted output conversion +T} +\fBvfscanf\fP(3) T{ +input format conversion +T} +\fBvprintf\fP(3) T{ +formatted output conversion +T} +\fBvscanf\fP(3) T{ +input format conversion +T} +\fBvsprintf\fP(3) T{ +formatted output conversion +T} +\fBvsscanf\fP(3) T{ +input format conversion +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH SEE ALSO +.BR close (2), +.BR open (2), +.BR read (2), +.BR write (2), +.BR stdout (3), +.BR unlocked_stdio (3) diff --git a/man/man3/stdio_ext.3 b/man/man3/stdio_ext.3 new file mode 100644 index 0000000..ed0203c --- /dev/null +++ b/man/man3/stdio_ext.3 @@ -0,0 +1,137 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH stdio_ext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__fbufsize, __flbf, __fpending, __fpurge, __freadable, +__freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \- +interfaces to stdio FILE structure +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <stdio_ext.h> +.P +.BI "size_t __fbufsize(FILE *" stream ); +.BI "size_t __fpending(FILE *" stream ); +.BI "int __flbf(FILE *" stream ); +.BI "int __freadable(FILE *" stream ); +.BI "int __fwritable(FILE *" stream ); +.BI "int __freading(FILE *" stream ); +.BI "int __fwriting(FILE *" stream ); +.BI "int __fsetlocking(FILE *" stream ", int " type ); +.B "void _flushlbf(void);" +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +Solaris introduced routines to allow portable access to the +internals of the +.I FILE +structure, and glibc also implemented these. +.P +The +.BR __fbufsize () +function returns the size of the buffer currently used +by the given stream. +.P +The +.BR __fpending () +function returns the number of bytes in the output buffer. +For wide-oriented streams the unit is wide characters. +This function is undefined on buffers in reading mode, +or opened read-only. +.P +The +.BR __flbf () +function returns a nonzero value if the stream is line-buffered, +and zero otherwise. +.P +The +.BR __freadable () +function returns a nonzero value if the stream allows reading, +and zero otherwise. +.P +The +.BR __fwritable () +function returns a nonzero value if the stream allows writing, +and zero otherwise. +.P +The +.BR __freading () +function returns a nonzero value if the stream is read-only, or +if the last operation on the stream was a read operation, +and zero otherwise. +.P +The +.BR __fwriting () +function returns a nonzero value if the stream is write-only (or +append-only), or if the last operation on the stream was a write +operation, and zero otherwise. +.P +The +.BR __fsetlocking () +function can be used to select the desired type of locking on the stream. +It returns the current type. +The +.I type +argument can take the following three values: +.TP +.B FSETLOCKING_INTERNAL +Perform implicit locking around every operation on the given stream +(except for the *_unlocked ones). +This is the default. +.TP +.B FSETLOCKING_BYCALLER +The caller will take care of the locking (possibly using +.BR flockfile (3) +in case there is more than one thread), and the stdio routines +will not do locking until the state is reset to +.BR FSETLOCKING_INTERNAL . +.TP +.B FSETLOCKING_QUERY +Don't change the type of locking. +(Only return it.) +.P +The +.BR _flushlbf () +function flushes all line-buffered streams. +(Presumably so that +output to a terminal is forced out, say before reading keyboard input.) +.P +The +.BR __fpurge () +function discards the contents of the stream's buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __fbufsize (), +.BR __fpending (), +.BR __fpurge (), +.BR __fsetlocking () +T} Thread safety MT-Safe race:stream +T{ +.na +.nh +.BR __flbf (), +.BR __freadable (), +.BR __freading (), +.BR __fwritable (), +.BR __fwriting (), +.BR _flushlbf () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR flockfile (3), +.BR fpurge (3) diff --git a/man/man3/stdout.3 b/man/man3/stdout.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man/man3/stdout.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man/man3/stpcpy.3 b/man/man3/stpcpy.3 new file mode 100644 index 0000000..ff7476a --- /dev/null +++ b/man/man3/stpcpy.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man/man3/stpncpy.3 b/man/man3/stpncpy.3 new file mode 100644 index 0000000..3e45f79 --- /dev/null +++ b/man/man3/stpncpy.3 @@ -0,0 +1,178 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH stpncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpncpy, strncpy +\- +fill a fixed-size buffer with non-null bytes from a string, +padding with null bytes as needed +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR stpncpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions copy non-null bytes from the string pointed to by +.I src +into the array pointed to by +.IR dst . +If the source has too few non-null bytes to fill the destination, +the functions pad the destination with trailing null bytes. +If the destination buffer, +limited by its size, +isn't large enough to hold the copy, +the resulting character sequence is truncated. +For the difference between the two functions, see RETURN VALUE. +.P +An implementation of these functions might be: +.P +.in +4n +.EX +char * +strncpy(char *restrict dst, const char *restrict src, size_t dsize) +{ + stpncpy(dst, src, dsize); + return dst; +} +\& +char * +stpncpy(char *restrict dst, const char *restrict src, size_t dsize) +{ + size_t dlen; +\& + dlen = strnlen(src, dsize); + return memset(mempcpy(dst, src, dlen), 0, dsize \- dlen); +} +.EE +.in +.SH RETURN VALUE +.TP +.BR strncpy () +returns +.IR dst . +.TP +.BR stpncpy () +returns a pointer to +one after the last character in the destination character sequence. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR stpncpy (), +.BR strncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strncpy () +C11, POSIX.1-2008. +.TP +.BR stpncpy () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strncpy () +C89, POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR stpncpy () +glibc 1.07. +POSIX.1-2008. +.SH CAVEATS +The name of these functions is confusing. +These functions produce a null-padded character sequence, +not a string (see +.BR string_copying (7)). +For example: +.P +.in +4n +.EX +strncpy(buf, "1", 5); // { \[aq]1\[aq], 0, 0, 0, 0 } +strncpy(buf, "1234", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], 0 } +strncpy(buf, "12345", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +strncpy(buf, "123456", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +.EE +.in +.P +It's impossible to distinguish truncation by the result of the call, +from a character sequence that just fits the destination buffer; +truncation should be detected by +comparing the length of the input string +with the size of the destination buffer. +.P +If you're going to use this function in chained calls, +it would be useful to develop a similar function that accepts +a pointer to the end (one after the last element) of the destination buffer +instead of its size. +.SH EXAMPLES +.\" SRC BEGIN (stpncpy.c) +.EX +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(void) +{ + char *p; + char buf1[20]; + char buf2[20]; + size_t len; +\& + if (sizeof(buf2) < strlen("Hello world!")) + errx("strncpy: truncating character sequence"); + strncpy(buf2, "Hello world!", sizeof(buf2)); + len = strnlen(buf2, sizeof(buf2)); +\& + printf("[len = %zu]: ", len); + fwrite(buf2, 1, len, stdout); + putchar(\[aq]\en\[aq]); +\& + if (sizeof(buf1) < strlen("Hello world!")) + errx("stpncpy: truncating character sequence"); + p = stpncpy(buf1, "Hello world!", sizeof(buf1)); + len = p \- buf1; +\& + printf("[len = %zu]: ", len); + fwrite(buf1, 1, len, stdout); + putchar(\[aq]\en\[aq]); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR wcpncpy (3), +.BR string_copying (7) diff --git a/man/man3/strcasecmp.3 b/man/man3/strcasecmp.3 new file mode 100644 index 0000000..647f211 --- /dev/null +++ b/man/man3/strcasecmp.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH strcasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcasecmp, strncasecmp \- compare two strings ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <strings.h> +.P +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +.BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcasecmp () +function performs a byte-by-byte comparison of the strings +.I s1 +and +.IR s2 , +ignoring the case of the characters. +It returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, +respectively, to be less than, to match, or be greater than +.IR s2 . +.P +The +.BR strncasecmp () +function is similar, except that it compares +no more than +.I n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcasecmp () +and +.BR strncasecmp () +functions return +an integer less than, equal to, or greater than zero if +.I s1 +is, after ignoring case, found to be +less than, to match, or be greater than +.IR s2 , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcasecmp (), +.BR strncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.4BSD, POSIX.1-2001. +.P +The +.BR strcasecmp () +and +.BR strncasecmp () +functions first appeared in 4.4BSD, where they were declared in +.IR <string.h> . +Thus, for reasons of historical compatibility, the glibc +.I <string.h> +header file also declares these functions, if the +.B _DEFAULT_SOURCE +(or, in glibc 2.19 and earlier, +.BR _BSD_SOURCE ) +feature test macro is defined. +.P +The POSIX.1-2008 standard says of these functions: +.P +.RS +When the +.B LC_CTYPE +category of the locale being used is from the POSIX locale, +these functions shall behave as if the strings had been converted +to lowercase and then a byte comparison performed. +Otherwise, the results are unspecified. +.RE +.SH SEE ALSO +.BR memcmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncmp (3), +.BR wcscasecmp (3), +.BR wcsncasecmp (3) diff --git a/man/man3/strcasestr.3 b/man/man3/strcasestr.3 new file mode 100644 index 0000000..2feb2c5 --- /dev/null +++ b/man/man3/strcasestr.3 @@ -0,0 +1 @@ +.so man3/strstr.3 diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 new file mode 100644 index 0000000..ff7476a --- /dev/null +++ b/man/man3/strcat.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man/man3/strchr.3 b/man/man3/strchr.3 new file mode 100644 index 0000000..3abb02e --- /dev/null +++ b/man/man3/strchr.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:51:24 1993, David Metcalfe +.\" 2006-05-19, Justin Pryzby <pryzbyj@justinpryzby.com> +.\" Document strchrnul(3). +.\" +.TH strchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strchr, strrchr, strchrnul \- locate character in string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strchr(const char *" s ", int " c ); +.BI "char *strrchr(const char *" s ", int " c ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "char *strchrnul(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The +.BR strchr () +function returns a pointer to the first occurrence +of the character +.I c +in the string +.IR s . +.P +The +.BR strrchr () +function returns a pointer to the last occurrence +of the character +.I c +in the string +.IR s . +.P +The +.BR strchrnul () +function is like +.BR strchr () +except that if +.I c +is not found in +.IR s , +then it returns a pointer to the null byte +at the end of +.IR s , +rather than NULL. +.P +Here "character" means "byte"; these functions do not work with +wide or multibyte characters. +.SH RETURN VALUE +The +.BR strchr () +and +.BR strrchr () +functions return a pointer to +the matched character or NULL if the character is not found. +The terminating null byte is considered part of the string, +so that if +.I c +is specified as \[aq]\e0\[aq], +these functions return a pointer to the terminator. +.P +The +.BR strchrnul () +function returns a pointer to the matched character, +or a pointer to the null byte at the end of +.I s +(i.e., +.IR "s+strlen(s)" ) +if the character is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strchr (), +.BR strrchr (), +.BR strchrnul () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strchr () +.TQ +.BR strrchr () +C11, POSIX.1-2008. +.TP +.BR strchrnul () +GNU. +.SH HISTORY +.TP +.BR strchr () +.TQ +.BR strrchr () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strchrnul () +glibc 2.1.1, +FreeBSD 10, +NetBSD 8. +.SH SEE ALSO +.BR memchr (3), +.BR string (3), +.BR strlen (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcschr (3), +.BR wcsrchr (3) diff --git a/man/man3/strchrnul.3 b/man/man3/strchrnul.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man/man3/strchrnul.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man/man3/strcmp.3 b/man/man3/strcmp.3 new file mode 100644 index 0000000..ba9eefb --- /dev/null +++ b/man/man3/strcmp.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-08-31, aeb +.\" +.TH strcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcmp, strncmp \- compare two strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcmp () +function compares the two strings +.I s1 +and +.IR s2 . +The locale is not taken into account (for a locale-aware comparison, see +.BR strcoll (3)). +The comparison is done using unsigned characters. +.P +.BR strcmp () +returns an integer indicating the result of the comparison, as follows: +.IP \[bu] 3 +0, if the +.I s1 +and +.I s2 +are equal; +.IP \[bu] +a negative value if +.I s1 +is less than +.IR s2 ; +.IP \[bu] +a positive value if +.I s1 +is greater than +.IR s2 . +.P +The +.BR strncmp () +function is similar, except it compares +only the first (at most) +.I n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcmp () +and +.BR strncmp () +functions return an integer +less than, equal to, or greater than zero if +.I s1 +(or the first +.I n +bytes thereof) is found, respectively, to be less than, to +match, or be greater than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcmp (), +.BR strncmp () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 specifies only that: +.RS +.P +The sign of a nonzero return value shall be determined by the sign +of the difference between the values of the first pair of bytes +(both interpreted as type +.IR "unsigned char" ) +that differ in the strings being compared. +.RE +.P +In glibc, as in most other implementations, +the return value is the arithmetic result of subtracting +the last compared byte in +.I s2 +from the last compared byte in +.IR s1 . +(If the two characters are equal, this difference is 0.) +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH EXAMPLES +The program below can be used to demonstrate the operation of +.BR strcmp () +(when given two arguments) and +.BR strncmp () +(when given three arguments). +First, some examples using +.BR strcmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC ABC\fP +<str1> and <str2> are equal +$ \fB./string_comp ABC AB\fP # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67 +<str1> is greater than <str2> (67) +$ \fB./string_comp ABA ABZ\fP # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90 +<str1> is less than <str2> (\-25) +$ \fB./string_comp ABJ ABC\fP +<str1> is greater than <str2> (7) +$ .\fB/string_comp $\[aq]\e201\[aq] A\fP # 0201 \- 0101 = 0100 (or 64 decimal) +<str1> is greater than <str2> (64) +.EE +.in +.P +The last example uses +.BR bash (1)-specific +syntax to produce a string containing an 8-bit ASCII code; +the result demonstrates that the string comparison uses unsigned +characters. +.P +And then some examples using +.BR strncmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC AB 3\fP +<str1> is greater than <str2> (67) +$ \fB./string_comp ABC AB 2\fP +<str1> and <str2> are equal in the first 2 bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (string_comp.c) +.EX +/* string_comp.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + int res; +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (argc == 3) + res = strcmp(argv[1], argv[2]); + else + res = strncmp(argv[1], argv[2], atoi(argv[3])); +\& + if (res == 0) { + printf("<str1> and <str2> are equal"); + if (argc > 3) + printf(" in the first %d bytes\en", atoi(argv[3])); + printf("\en"); + } else if (res < 0) { + printf("<str1> is less than <str2> (%d)\en", res); + } else { + printf("<str1> is greater than <str2> (%d)\en", res); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncasecmp (3), +.BR strverscmp (3), +.BR wcscmp (3), +.BR wcsncmp (3), +.BR ascii (7) diff --git a/man/man3/strcoll.3 b/man/man3/strcoll.3 new file mode 100644 index 0000000..8b19cfc --- /dev/null +++ b/man/man3/strcoll.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH strcoll 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcoll \- compare two strings using the current locale +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +The +.BR strcoll () +function compares the two strings +.I s1 +and +.IR s2 . +It returns an integer less than, equal to, or greater +than zero if +.I s1 +is found, respectively, to be less than, +to match, or be greater than +.IR s2 . +The comparison is based on +strings interpreted as appropriate for the program's current locale +for category +.BR LC_COLLATE . +(See +.BR setlocale (3).) +.SH RETURN VALUE +The +.BR strcoll () +function returns an integer less than, equal to, +or greater than zero if +.I s1 +is found, respectively, to be less +than, to match, or be greater than +.IR s2 , +when both are interpreted +as appropriate for the current locale. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcoll () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH NOTES +In the +.I "POSIX" +or +.I "C" +locales +.BR strcoll () +is equivalent to +.BR strcmp (3). +.SH SEE ALSO +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR string (3), +.BR strxfrm (3) diff --git a/man/man3/strcpy.3 b/man/man3/strcpy.3 new file mode 100644 index 0000000..a14e8cf --- /dev/null +++ b/man/man3/strcpy.3 @@ -0,0 +1,204 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpcpy, strcpy, strcat \- copy or catenate a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcat(char *restrict " dst ", const char *restrict " src ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR stpcpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.TP +.BR stpcpy () +.TQ +.BR strcpy () +These functions copy the string pointed to by +.IR src , +into a string +at the buffer pointed to by +.IR dst . +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(src) + 1" . +For the difference between the two functions, see RETURN VALUE. +.TP +.BR strcat () +This function catenates the string pointed to by +.IR src , +after the string pointed to by +.I dst +(overwriting its terminating null byte). +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(dst) + strlen(src) + 1" . +.P +An implementation of these functions might be: +.P +.in +4n +.EX +char * +stpcpy(char *restrict dst, const char *restrict src) +{ + char *p; +\& + p = mempcpy(dst, src, strlen(src)); + *p = \[aq]\e0\[aq]; +\& + return p; +} +\& +char * +strcpy(char *restrict dst, const char *restrict src) +{ + stpcpy(dst, src); + return dst; +} +\& +char * +strcat(char *restrict dst, const char *restrict src) +{ + stpcpy(dst + strlen(dst), src); + return dst; +} +.EE +.in +.SH RETURN VALUE +.TP +.BR stpcpy () +This function returns +a pointer to the terminating null byte of the copied string. +.TP +.BR strcpy () +.TQ +.BR strcat () +These functions return +.IR dst . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR stpcpy (), +.BR strcpy (), +.BR strcat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR stpcpy () +POSIX.1-2008. +.TP +.BR strcpy () +.TQ +.BR strcat () +C11, POSIX.1-2008. +.SH STANDARDS +.TP +.BR stpcpy () +POSIX.1-2008. +.TP +.BR strcpy () +.TQ +.BR strcat () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +The strings +.I src +and +.I dst +may not overlap. +.P +If the destination buffer is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.P +.BR strcat () +can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strcpy.c) +.EX +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(void) +{ + char *p; + char *buf1; + char *buf2; + size_t len, maxsize; +\& + maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1; + buf1 = malloc(sizeof(*buf1) * maxsize); + if (buf1 == NULL) + err(EXIT_FAILURE, "malloc()"); + buf2 = malloc(sizeof(*buf2) * maxsize); + if (buf2 == NULL) + err(EXIT_FAILURE, "malloc()"); +\& + p = buf1; + p = stpcpy(p, "Hello "); + p = stpcpy(p, "world"); + p = stpcpy(p, "!"); + len = p \- buf1; +\& + printf("[len = %zu]: ", len); + puts(buf1); // "Hello world!" + free(buf1); +\& + strcpy(buf2, "Hello "); + strcat(buf2, "world"); + strcat(buf2, "!"); + len = strlen(buf2); +\& + printf("[len = %zu]: ", len); + puts(buf2); // "Hello world!" + free(buf2); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR strdup (3), +.BR string (3), +.BR wcscpy (3), +.BR string_copying (7) diff --git a/man/man3/strcspn.3 b/man/man3/strcspn.3 new file mode 100644 index 0000000..26284f2 --- /dev/null +++ b/man/man3/strcspn.3 @@ -0,0 +1 @@ +.so man3/strspn.3 diff --git a/man/man3/strdup.3 b/man/man3/strdup.3 new file mode 100644 index 0000000..530ffb9 --- /dev/null +++ b/man/man3/strdup.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 17 01:12:26 2001 by John Levon <moz@compsoc.man.ac.uk> +.TH strdup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strdup, strndup, strdupa, strndupa \- duplicate a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strdup(const char *" s ); +.P +.BI "char *strndup(const char " s [. n "], size_t " n ); +.BI "char *strdupa(const char *" s ); +.BI "char *strndupa(const char " s [. n "], size_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strdup (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR strndup (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.BR strdupa (), +.BR strndupa (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR strdup () +function returns a pointer to a new string which +is a duplicate of the string +.IR s . +Memory for the new string is +obtained with +.BR malloc (3), +and can be freed with +.BR free (3). +.P +The +.BR strndup () +function is similar, but copies at most +.I n +bytes. +If +.I s +is longer than +.IR n , +only +.I n +bytes are copied, and a terminating null byte (\[aq]\e0\[aq]) is added. +.P +.BR strdupa () +and +.BR strndupa () +are similar, but use +.BR alloca (3) +to allocate the buffer. +.SH RETURN VALUE +On success, the +.BR strdup () +function returns a pointer to the duplicated +string. +It returns NULL if insufficient memory was available, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strdup (), +.BR strndup (), +.BR strdupa (), +.BR strndupa () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strdup () +.TQ +.BR strndup () +POSIX.1-2008. +.TP +.BR strdupa () +.TQ +.BR strndupa () +GNU. +.SH HISTORY +.TP +.BR strdup () +SVr4, 4.3BSD-Reno, POSIX.1-2001. +.TP +.BR strndup () +POSIX.1-2008. +.TP +.BR strdupa () +.TQ +.BR strndupa () +GNU. +.SH SEE ALSO +.BR alloca (3), +.BR calloc (3), +.BR free (3), +.BR malloc (3), +.BR realloc (3), +.BR string (3), +.BR wcsdup (3) diff --git a/man/man3/strdupa.3 b/man/man3/strdupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strdupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strerror.3 b/man/man3/strerror.3 new file mode 100644 index 0000000..62a99c6 --- /dev/null +++ b/man/man3/strerror.3 @@ -0,0 +1,324 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl> +.\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl> +.\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk> +.\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl> +.\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl> +.\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description +.\" Addition of extra material on portability and standards. +.\" +.TH strerror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- +return string describing error number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strerror(int " errnum ); +.BI "const char *strerrorname_np(int " errnum ); +.BI "const char *strerrordesc_np(int " errnum ); +.P +.BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); + /* XSI-compliant */ +.P +.BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); + /* GNU-specific */ +.P +.BI "char *strerror_l(int " errnum ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strerrorname_np (), +.BR strerrordesc_np (): +.nf + _GNU_SOURCE +.fi +.P +.BR strerror_r (): +.nf + The XSI-compliant version is provided if: + (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE + Otherwise, the GNU-specific version is provided. +.fi +.SH DESCRIPTION +The +.BR strerror () +function returns a pointer to a string that describes the error +code passed in the argument +.IR errnum , +possibly using the +.B LC_MESSAGES +part of the current locale to select the appropriate language. +(For example, if +.I errnum +is +.BR EINVAL , +the returned description will be "Invalid argument".) +This string must not be modified by the application, +and the returned pointer will be invalidated on a subsequent call to +.BR strerror () +or +.BR strerror_l (), +or if the thread that obtained the string exits. +No other library function, including +.BR perror (3), +will modify this string. +.P +Like +.BR strerror (), +the +.BR strerrordesc_np () +function returns a pointer to a string that describes the error +code passed in the argument +.IR errnum , +with the difference that the returned string is not translated +according to the current locale. +.P +The +.BR strerrorname_np () +function returns a pointer to a string containing the name of the error +code passed in the argument +.IR errnum . +For example, given +.B EPERM +as an argument, this function returns a pointer to the string "EPERM". +Given +.B 0 +as an argument, +this function returns a pointer to the string "0". +.\" +.SS strerror_r() +.BR strerror_r () +is like +.BR strerror (), +but might use the supplied buffer +.I buf +instead of allocating one internally. +This function is available in two versions: +an XSI-compliant version specified in POSIX.1-2001 +(available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), +and a GNU-specific version (available since glibc 2.0). +The XSI-compliant version is provided with the feature test macros +settings shown in the SYNOPSIS; +otherwise the GNU-specific version is provided. +If no feature test macros are explicitly defined, +then (since glibc 2.4) +.B _POSIX_C_SOURCE +is defined by default with the value +200112L, so that the XSI-compliant version of +.BR strerror_r () +is provided by default. +.P +The XSI-compliant +.BR strerror_r () +is preferred for portable applications. +It returns the error string in the user-supplied buffer +.I buf +of length +.IR buflen . +.P +The GNU-specific +.BR strerror_r () +returns a pointer to a string containing the error message. +This may be either a pointer to a string that the function stores in +.IR buf , +or a pointer to some (immutable) static string +(in which case +.I buf +is unused). +If the function stores a string in +.IR buf , +then at most +.I buflen +bytes are stored (the string may be truncated if +.I buflen +is too small and +.I errnum +is unknown). +The string always includes a terminating null byte (\[aq]\e0\[aq]). +.\" +.SS strerror_l() +.BR strerror_l () +is like +.BR strerror (), +but maps +.I errnum +to a locale-dependent error message in the locale specified by +.IR locale . +The behavior of +.BR strerror_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH RETURN VALUE +The +.BR strerror (), +.BR strerror_l (), +and the GNU-specific +.BR strerror_r () +functions return +the appropriate error description string, +or an "Unknown error nnn" message if the error number is unknown. +.P +On success, +.BR strerrorname_np () +and +.BR strerrordesc_np () +return the appropriate error description string. +If +.I errnum +is an invalid error number, these functions return NULL. +.P +The XSI-compliant +.BR strerror_r () +function returns 0 on success. +On error, +a (positive) error number is returned (since glibc 2.13), +or \-1 is returned and +.I errno +is set to indicate the error (before glibc 2.13). +.P +POSIX.1-2001 and POSIX.1-2008 require that a successful call to +.BR strerror () +or +.BR strerror_l () +shall leave +.I errno +unchanged, and note that, +since no function return value is reserved to indicate an error, +an application that wishes to check for errors should initialize +.I errno +to zero before the call, +and then check +.I errno +after the call. +.SH ERRORS +.TP +.B EINVAL +The value of +.I errnum +is not a valid error number. +.TP +.B ERANGE +Insufficient storage was supplied to contain the error description string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strerror () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +T{ +.na +.nh +.BR strerrorname_np (), +.BR strerrordesc_np () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR strerror_r (), +.BR strerror_l () +T} Thread safety MT-Safe +.TE +.P +Before glibc 2.32, +.BR strerror () +is not MT-Safe. +.SH STANDARDS +.TP +.BR strerror () +C11, POSIX.1-2008. +.TP +.BR strerror_r () +.\" FIXME . for later review when Issue 8 is one day released... +.\" A future POSIX.1 may remove strerror_r() +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +.TQ +.BR strerror_l () +POSIX.1-2008. +.TP +.BR strerrorname_np () +.TQ +.BR strerrordesc_np () +GNU. +.P +POSIX.1-2001 permits +.BR strerror () +to set +.I errno +if the call encounters an error, but does not specify what +value should be returned as the function result in the event of an error. +On some systems, +.\" e.g., Solaris 8, HP-UX 11 +.BR strerror () +returns NULL if the error number is unknown. +On other systems, +.\" e.g., FreeBSD 5.4, Tru64 5.1B +.BR strerror () +returns a string something like "Error nnn occurred" and sets +.I errno +to +.B EINVAL +if the error number is unknown. +C99 and POSIX.1-2008 require the return value to be non-NULL. +.SH HISTORY +.TP +.BR strerror () +POSIX.1-2001, C89. +.TP +.BR strerror_r () +POSIX.1-2001. +.TP +.BR strerror_l () +glibc 2.6. +POSIX.1-2008. +.TP +.BR strerrorname_np () +.TQ +.BR strerrordesc_np () +glibc 2.32. +.SH NOTES +.BR strerrorname_np () +and +.BR strerrordesc_np () +are thread-safe and async-signal-safe. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR perror (3), +.BR strsignal (3), +.BR locale (7), +.BR signal-safety (7) diff --git a/man/man3/strerror_l.3 b/man/man3/strerror_l.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerror_l.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerror_r.3 b/man/man3/strerror_r.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerror_r.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerrordesc_np.3 b/man/man3/strerrordesc_np.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerrordesc_np.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerrorname_np.3 b/man/man3/strerrorname_np.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerrorname_np.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strfmon.3 b/man/man3/strfmon.3 new file mode 100644 index 0000000..c3a9cb2 --- /dev/null +++ b/man/man3/strfmon.3 @@ -0,0 +1,209 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH strfmon 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfmon, strfmon_l \- convert monetary value to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <monetary.h> +.P +.BI "ssize_t strfmon(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format ", ...);" +.BI "ssize_t strfmon_l(char " s "[restrict ." max "], size_t " max ", \ +locale_t " locale , +.BI " const char *restrict " format ", ...);" +.fi +.SH DESCRIPTION +The +.BR strfmon () +function formats the specified monetary amount +according to the current locale +and format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +.P +The +.BR strfmon_l () +function performs the same task, +but uses +the locale specified by +.IR locale . +The behavior of +.BR strfmon_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +Ordinary characters in +.I format +are copied to +.I s +without conversion. +Conversion specifiers are introduced by a \[aq]%\[aq] +character. +Immediately following it there can be zero or more +of the following flags: +.TP +.BI = f +The single-byte character +.I f +is used as the numeric fill character (to be used with +a left precision, see below). +When not specified, the space character is used. +.TP +.B \[ha] +Do not use any grouping characters that might be defined +for the current locale. +By default, grouping is enabled. +.TP +.BR ( " or " + +The ( flag indicates that negative amounts should be enclosed between +parentheses. +The + flag indicates that signs should be handled +in the default way, that is, amounts are preceded by the locale's +sign indication, for example, nothing for positive, "\-" for negative. +.TP +.B ! +Omit the currency symbol. +.TP +.B \- +Left justify all fields. +The default is right justification. +.P +Next, there may be a field width: a decimal digit string specifying +a minimum field width in bytes. +The default is 0. +A result smaller than this width is padded with spaces +(on the left, unless the left-justify flag was given). +.P +Next, there may be a left precision of the form "#" followed by +a decimal digit string. +If the number of digits left of the +radix character is smaller than this, the representation is +padded on the left with the numeric fill character. +Grouping characters are not counted in this field width. +.P +Next, there may be a right precision of the form "." followed by +a decimal digit string. +The amount being formatted is rounded to +the specified number of digits prior to formatting. +The default is specified in the +.I frac_digits +and +.I int_frac_digits +items of the current locale. +If the right precision is 0, no radix character is printed. +(The radix character here is determined by +.BR LC_MONETARY , +and may differ from that specified by +.BR LC_NUMERIC .) +.P +Finally, the conversion specification must be ended with a +conversion character. +The three conversion characters are +.TP +.B % +(In this case, the entire specification must be exactly "%%".) +Put a \[aq]%\[aq] character in the result string. +.TP +.B i +One argument of type +.I double +is converted using the locale's international currency format. +.TP +.B n +One argument of type +.I double +is converted using the locale's national currency format. +.SH RETURN VALUE +The +.BR strfmon () +function returns the number of characters placed +in the array +.IR s , +not including the terminating null byte, +provided the string, including the terminating null byte, fits. +Otherwise, it sets +.I errno +to +.BR E2BIG , +returns \-1, and the contents of the array is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfmon () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR strfmon_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The call +.P +.in +4n +.EX +strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]", + 1234.567, 1234.567); +.EE +.in +.P +outputs +.P +.in +4n +.EX +[€ **1234,57] [EUR **1 234,57] +.EE +.in +.P +in the +.I nl_NL +locale. +The +.IR de_DE , +.IR de_CH , +.IR en_AU , +and +.I en_GB +locales yield +.P +.in +4n +.EX +[ **1234,57 €] [ **1.234,57 EUR] +[ Fr. **1234.57] [ CHF **1\[aq]234.57] +[ $**1234.57] [ AUD**1,234.57] +[ £**1234.57] [ GBP**1,234.57] +.EE +.in +.SH SEE ALSO +.BR duplocale (3), +.BR setlocale (3), +.BR sprintf (3), +.BR locale (7) diff --git a/man/man3/strfmon_l.3 b/man/man3/strfmon_l.3 new file mode 100644 index 0000000..cdbc310 --- /dev/null +++ b/man/man3/strfmon_l.3 @@ -0,0 +1 @@ +.so man3/strfmon.3 diff --git a/man/man3/strfromd.3 b/man/man3/strfromd.3 new file mode 100644 index 0000000..74bc736 --- /dev/null +++ b/man/man3/strfromd.3 @@ -0,0 +1,231 @@ +'\" t +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" glibc 2.25 source code and manual. +.\" C99 standard document. +.\" ISO/IEC TS 18661-1 technical specification. +.\" snprintf and other man.3 pages. +.\" +.TH strfromd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfromd, strfromf, strfroml \- convert a floating-point value into +a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int strfromd(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", double " fp ");" +.BI "int strfromf(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", float "fp ");" +.BI "int strfroml(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", long double " fp ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strfromd (), +.BR strfromf (), +.BR strfroml (): +.nf + __STDC_WANT_IEC_60559_BFP_EXT__ +.fi +.SH DESCRIPTION +These functions convert a floating-point value, +.IR fp , +into a string of characters, +.IR str , +with a configurable +.I format +string. +At most +.I n +characters are stored into +.IR str . +.P +The terminating null byte ('\e0') is written if and only if +.I n +is sufficiently large, otherwise the written string is truncated at +.I n +characters. +.P +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions are equivalent to +.P +.in +4n +.EX +snprintf(str, n, format, fp); +.EE +.in +.P +except for the +.I format +string. +.SS Format of the format string +The +.I format +string must start with the character \[aq]%\[aq]. +This is followed by an optional precision which starts with the period +character (.), followed by an optional decimal integer. +If no integer is specified after the period character, +a precision of zero is used. +Finally, the format string should have one of the conversion specifiers +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G . +.P +The conversion specifier is applied based on the floating-point type +indicated by the function suffix. +Therefore, unlike +.BR snprintf (), +the format string does not have a length modifier character. +See +.BR snprintf (3) +for a detailed description of these conversion specifiers. +.P +The implementation conforms to the C99 standard on conversion of NaN and +infinity values: +.P +.RS +If +.I fp +is a NaN, +NaN, or \-NaN, and +.B f +(or +.BR a , +.BR e , +.BR g ) +is the conversion specifier, the conversion is to "nan", "nan", or "\-nan", +respectively. +If +.B F +(or +.BR A , +.BR E , +.BR G ) +is the conversion specifier, the conversion is to "NAN" or "\-NAN". +.P +Likewise if +.I fp +is infinity, it is converted to [\-]inf or [\-]INF. +.RE +.P +A malformed +.I format +string results in undefined behavior. +.SH RETURN VALUE +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions return the number of characters that would have been written in +.I str +if +.I n +had enough space, +not counting the terminating null byte. +Thus, a return value of +.I n +or greater means that the output was truncated. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7) +and the +.B POSIX Safety Concepts +section in GNU C Library manual. +.P +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfromd (), +.BR strfromf (), +.BR strfroml () +T} Thread safety MT-Safe locale +\^ Async-signal safety AS-Unsafe heap +\^ Async-cancel safety AC-Unsafe mem +.TE +.P +Note: these attributes are preliminary. +.SH STANDARDS +ISO/IEC TS 18661-1. +.SH VERSIONS +.TP +.BR strfromd () +.TQ +.BR strfromf () +.TQ +.BR strfroml () +glibc 2.25. +.SH NOTES +These functions take account of the +.B LC_NUMERIC +category of the current locale. +.SH EXAMPLES +To convert the value 12.1 as a float type to a string using decimal +notation, resulting in "12.100000": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include <stdlib.h> +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%f", 12.1); +.EE +.in +.P +To convert the value 12.3456 as a float type to a string using +decimal notation with two digits of precision, resulting in "12.35": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include <stdlib.h> +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%.2f", 12.3456); +.EE +.in +.P +To convert the value 12.345e19 as a double type to a string using +scientific notation with zero digits of precision, resulting in "1E+20": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include <stdlib.h> +int ssize = 10; +char s[ssize]; +strfromd(s, ssize, "%.E", 12.345e19); +.EE +.in +.SH SEE ALSO +.BR atof (3), +.BR snprintf (3), +.BR strtod (3) diff --git a/man/man3/strfromf.3 b/man/man3/strfromf.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man/man3/strfromf.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man/man3/strfroml.3 b/man/man3/strfroml.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man/man3/strfroml.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man/man3/strfry.3 b/man/man3/strfry.3 new file mode 100644 index 0000000..2f7daec --- /dev/null +++ b/man/man3/strfry.3 @@ -0,0 +1,55 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:39:43 1993 by Rik Faith (faith@cs.unc.edu) +.TH strfry 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfry \- randomize a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "char *strfry(char *" string ); +.fi +.SH DESCRIPTION +The +.BR strfry () +function randomizes the contents of +.I string +by randomly swapping characters in the string. +The result is an anagram of +.IR string . +.SH RETURN VALUE +The +.BR strfry () +functions returns a pointer to the randomized +string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfry () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR memfrob (3), +.BR string (3) diff --git a/man/man3/strftime.3 b/man/man3/strftime.3 new file mode 100644 index 0000000..e94a3ef --- /dev/null +++ b/man/man3/strftime.3 @@ -0,0 +1,777 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" GNU texinfo documentation on glibc date/time functions. +.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Applied fix by Wolfgang Franke, aeb, 961011 +.\" Corrected return value, aeb, 970307 +.\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329. +.\" 2005-11-22 mtk, added glibc Notes covering optional 'flag' and +.\" 'width' components of conversion specifications. +.\" +.TH strftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strftime \- format date and time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "size_t strftime(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format , +.BI " const struct tm *restrict " tm ); +.P +.BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format , +.BI " const struct tm *restrict " tm , +.BI " locale_t " locale ); +.fi +.SH DESCRIPTION +The +.BR strftime () +function formats the broken-down time +.I tm +according to the format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +The broken-down time structure +.I tm +is defined in +.IR <time.h> . +See also +.BR ctime (3). +.\" FIXME . POSIX says: Local timezone information is used as though +.\" strftime() called tzset(). But this doesn't appear to be the case +.P +The format specification is a null-terminated string and may contain +special character sequences called +.IR "conversion specifications", +each of which is introduced by a \[aq]%\[aq] character and terminated by +some other character known as a +.IR "conversion specifier character". +All other character sequences are +.IR "ordinary character sequences". +.P +The characters of ordinary character sequences (including the null byte) +are copied verbatim from +.I format +to +.IR s . +However, the characters +of conversion specifications are replaced as shown in the list below. +In this list, the field(s) employed from the +.I tm +structure are also shown. +.TP +.B %a +The abbreviated name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR ABDAY_ { 1 \[en] 7 } +as an argument.) +.TP +.B %A +The full name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR DAY_ { 1 \[en] 7 } +as an argument.) +.TP +.B %b +The abbreviated month name according to the current locale. +(Calculated from +.IR tm_mon .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR ABMON_ { 1 \[en] 12 } +as an argument.) +.TP +.B %B +The full month name according to the current locale. +(Calculated from +.IR tm_mon .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR MON_ { 1 \[en] 12 } +as an argument.) +.TP +.B %c +The preferred date and time representation for the current locale. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B D_T_FMT +as an argument for the +.B %c +conversion specification, and with +.B ERA_D_T_FMT +for the +.B %Ec +conversion specification.) +(In the POSIX locale this is equivalent to +.BR "%a %b %e %H:%M:%S %Y" .) +.TP +.B %C +The century number (year/100) as a 2-digit integer. (SU) +(The +.B %EC +conversion specification corresponds to the name of the era.) +(Calculated from +.IR tm_year .) +.TP +.B %d +The day of the month as a decimal number (range 01 to 31). +(Calculated from +.IR tm_mday .) +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(Yecch\[em]for Americans only. +Americans should note that in other countries +.B %d/%m/%y +is rather common. +This means that in international context this format is +ambiguous and should not be used.) (SU) +.TP +.B %e +Like +.BR %d , +the day of the month as a decimal number, but a leading +zero is replaced by a space. (SU) +(Calculated from +.IR tm_mday .) +.TP +.B %E +Modifier: use alternative ("era-based") format, see below. (SU) +.TP +.B %F +Equivalent to +.B %Y\-%m\-%d +(the ISO\~8601 date format). (C99) +.TP +.B %G +The ISO\~8601 week-based year (see NOTES) with century as a decimal number. +The 4-digit year corresponding to the ISO week number (see +.BR %V ). +This has the same format and value as +.BR %Y , +except that if the ISO week number belongs to the previous or next year, +that year is used instead. (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %g +Like +.BR %G , +but without century, that is, with a 2-digit year (00\[en]99). (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %h +Equivalent to +.BR %b . +(SU) +.TP +.B %H +The hour as a decimal number using a 24-hour clock (range 00 to 23). +(Calculated from +.IR tm_hour .) +.TP +.B %I +The hour as a decimal number using a 12-hour clock (range 01 to 12). +(Calculated from +.IR tm_hour .) +.TP +.B %j +The day of the year as a decimal number (range 001 to 366). +(Calculated from +.IR tm_yday .) +.TP +.B %k +The hour (24-hour clock) as a decimal number (range 0 to 23); +single digits are preceded by a blank. +(See also +.BR %H .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %l +The hour (12-hour clock) as a decimal number (range 1 to 12); +single digits are preceded by a blank. +(See also +.BR %I .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %m +The month as a decimal number (range 01 to 12). +(Calculated from +.IR tm_mon .) +.TP +.B %M +The minute as a decimal number (range 00 to 59). +(Calculated from +.IR tm_min .) +.TP +.B %n +A newline character. (SU) +.TP +.B %O +Modifier: use alternative numeric symbols, see below. (SU) +.TP +.B %p +Either "AM" or "PM" according to the given time value, or the +corresponding strings for the current locale. +Noon is treated as "PM" and midnight as "AM". +(Calculated from +.IR tm_hour .) +(The specific string representations used for "AM" and "PM" +in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR AM_STR " and " PM_STR , +respectively.) +.TP +.B %P +Like +.B %p +but in lowercase: "am" or "pm" or a corresponding +string for the current locale. +(Calculated from +.IR tm_hour .) +(GNU) +.TP +.B %r +The time in a.m. or p.m. notation. +(SU) +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B T_FMT_AMPM +as an argument.) +(In the POSIX locale this is equivalent to +.BR "%I:%M:%S %p" .) +.TP +.B %R +The time in 24-hour notation +.RB ( %H:%M ). +(SU) +For a version including the seconds, see +.B %T +below. +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ) +(Calculated from +.IR mktime(tm) .) +.TP +.B %S +The second as a decimal number (range 00 to 60). +(The range is up to 60 to allow for occasional leap seconds.) +(Calculated from +.IR tm_sec .) +.TP +.B %t +A tab character. (SU) +.TP +.B %T +The time in 24-hour notation +.RB ( %H:%M:%S ). +(SU) +.TP +.B %u +The day of the week as a decimal, range 1 to 7, Monday being 1. +See also +.BR %w . +(Calculated from +.IR tm_wday .) +(SU) +.TP +.B %U +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Sunday as the first day +of week 01. +See also +.B %V +and +.BR %W . +(Calculated from +.I tm_yday +and +.IR tm_wday .) +.TP +.B %V +The ISO\~8601 week number (see NOTES) of the current year as a decimal number, +range 01 to 53, where week 1 is the first week that has at least +4 days in the new year. +See also +.B %U +and +.BR %W . +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +(SU) +.TP +.B %w +The day of the week as a decimal, range 0 to 6, Sunday being 0. +See also +.BR %u . +(Calculated from +.IR tm_wday .) +.TP +.B %W +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Monday as the first day of week 01. +(Calculated from +.I tm_yday +and +.IR tm_wday .) +.TP +.B %x +The preferred date representation for the current locale without the time. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B D_FMT +as an argument for the +.B %x +conversion specification, and with +.B ERA_D_FMT +for the +.B %Ex +conversion specification.) +(In the POSIX locale this is equivalent to +.BR %m/%d/%y .) +.TP +.B %X +The preferred time representation for the current locale without the date. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B T_FMT +as an argument for the +.B %X +conversion specification, and with +.B ERA_T_FMT +for the +.B %EX +conversion specification.) +(In the POSIX locale this is equivalent to +.BR %H:%M:%S .) +.TP +.B %y +The year as a decimal number without a century (range 00 to 99). +(The +.B %Ey +conversion specification corresponds to the year since the beginning of the era +denoted by the +.B %EC +conversion specification.) +(Calculated from +.IR tm_year ) +.TP +.B %Y +The year as a decimal number including the century. +(The +.B %EY +conversion specification corresponds to +the full alternative year representation.) +(Calculated from +.IR tm_year ) +.TP +.B %z +The +.I +hhmm +or +.I \-hhmm +numeric timezone (that is, the hour and minute offset from UTC). (SU) +.TP +.B %Z +The timezone name or abbreviation. +.TP +.B %+ +.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to +.\" their man pages) +The date and time in +.BR date (1) +format. (TZ) +(Not supported in glibc2.) +.TP +.B %% +A literal \[aq]%\[aq] character. +.P +Some conversion specifications can be modified by preceding the +conversion specifier character by the +.B E +or +.B O +.I modifier +to indicate that an alternative format should be used. +If the alternative format or specification does not exist for +the current locale, the behavior will be as if the unmodified +conversion specification were used. (SU) +The Single UNIX Specification mentions +.BR %Ec , +.BR %EC , +.BR %Ex , +.BR %EX , +.BR %Ey , +.BR %EY , +.BR %Od , +.BR %Oe , +.BR %OH , +.BR %OI , +.BR %Om , +.BR %OM , +.BR %OS , +.BR %Ou , +.BR %OU , +.BR %OV , +.BR %Ow , +.BR %OW , +.BR %Oy , +where the effect of the +.B O +modifier is to use +alternative numeric symbols (say, roman numerals), and that of the +.B E +modifier is to use a locale-dependent alternative representation. +The rules governing date representation with the +.B E +modifier can be obtained by supplying +.B ERA +as an argument to a +.BR nl_langinfo (3). +One example of such alternative forms is the Japanese era calendar scheme in the +.B ja_JP +glibc locale. +.P +.BR strftime_l () +is equivalent to +.BR strftime (), +except it uses the specified +.I locale +instead of the current locale. +The behaviour is undefined if +.I locale +is invalid or +.BR LC_GLOBAL_LOCALE . +.SH RETURN VALUE +Provided that the result string, +including the terminating null byte, does not exceed +.I max +bytes, +.BR strftime () +returns the number of bytes (excluding the terminating null byte) +placed in the array +.IR s . +If the length of the result string (including the terminating null byte) +would exceed +.I max +bytes, then +.BR strftime () +returns 0, and the contents of the array are undefined. +.\" (This behavior applies since at least libc 4.4.4; +.\" very old versions of libc, such as libc 4.4.1, +.\" would return +.\" .I max +.\" if the array was too small.) +.P +Note that the return value 0 does not necessarily indicate an error. +For example, in many locales +.B %p +yields an empty string. +An empty +.I format +string will likewise yield an empty string. +.SH ENVIRONMENT +The environment variables +.B TZ +and +.B LC_TIME +are used. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strftime (), +.BR strftime_l () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR strftime () +C11, POSIX.1-2008. +.TP +.BR strftime_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strftime () +SVr4, C89. +.\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details +.\" in the standards changed across versions. Investigate and +.\" write up. +.TP +.BR strftime_l () +POSIX.1-2008. +.P +There are strict inclusions between the set of conversions +given in ANSI C (unmarked), those given in the Single UNIX Specification +(marked SU), those given in Olson's timezone package (marked TZ), +and those given in glibc (marked GNU), except that +.B %+ +is not supported in glibc2. +On the other hand glibc2 has several more extensions. +POSIX.1 only refers to ANSI C; POSIX.2 describes under +.BR date (1) +several extensions that could apply to +.BR strftime () +as well. +The +.B %F +conversion is in C99 and POSIX.1-2001. +.P +In SUSv2, the +.B %S +specifier allowed a range of 00 to 61, +to allow for the theoretical possibility of a minute that +included a double leap second +(there never has been such a minute). +.SH NOTES +.SS ISO\~8601 week dates +.BR %G , +.BR %g , +and +.B %V +yield values calculated from the week-based year defined by the +ISO\~8601 standard. +In this system, weeks start on a Monday, and are numbered from 01, +for the first week, up to 52 or 53, for the last week. +Week 1 is the first week where four or more days fall within the +new year (or, synonymously, week 01 is: +the first week of the year that contains a Thursday; +or, the week that has 4 January in it). +When three or fewer days of the first calendar week of the new year fall +within that year, +then the ISO\~8601 week-based system counts those days as part of week 52 +or 53 of the preceding year. +For example, 1 January 2010 is a Friday, +meaning that just three days of that calendar week fall in 2010. +Thus, the ISO\~8601 week-based system considers these days to be part of +week 53 +.RB ( %V ) +of the year 2009 +.RB ( %G ); +week 01 of ISO\~8601 year 2010 starts on Monday, 4 January 2010. +Similarly, the first two days of January 2011 are considered to be part +of week 52 of the year 2010. +.SS glibc notes +glibc provides some extensions for conversion specifications. +(These extensions are not specified in POSIX.1-2001, but a few other +systems provide similar features.) +.\" HP-UX and Tru64 also have features like this. +Between the \[aq]%\[aq] character and the conversion specifier character, +an optional +.I flag +and field +.I width +may be specified. +(These precede the +.B E +or +.B O +modifiers, if present.) +.P +The following flag characters are permitted: +.TP +.B _ +(underscore) +Pad a numeric result string with spaces. +.TP +.B \- +(dash) +Do not pad a numeric result string. +.TP +.B 0 +Pad a numeric result string with zeros even if the conversion +specifier character uses space-padding by default. +.TP +.B \[ha] +Convert alphabetic characters in result string to uppercase. +.TP +.B # +Swap the case of the result string. +(This flag works only with certain conversion specifier characters, +and of these, it is only really useful with +.BR %Z .) +.P +An optional decimal width specifier may follow the (possibly absent) flag. +If the natural size of the field is smaller than this width, +then the result string is padded (on the left) to the specified width. +.SH BUGS +If the output string would exceed +.I max +bytes, +.I errno +is +.I not +set. +This makes it impossible to distinguish this error case from cases where the +.I format +string legitimately produces a zero-length output string. +POSIX.1-2001 +does +.I not +specify any +.I errno +settings for +.BR strftime (). +.P +Some buggy versions of +.BR gcc (1) +complain about the use of +.BR %c : +.IR "warning: \`%c\[aq] yields only last 2 digits of year in some locales" . +Of course programmers are encouraged to use +.BR %c , +as it gives the preferred date and time representation. +One meets all kinds of strange obfuscations +to circumvent this +.BR gcc (1) +problem. +A relatively clean one is to add an +intermediate function +.P +.in +4n +.EX +size_t +my_strftime(char *s, size_t max, const char *fmt, + const struct tm *tm) +{ + return strftime(s, max, fmt, tm); +} +.EE +.in +.P +Nowadays, +.BR gcc (1) +provides the +.I \-Wno\-format\-y2k +option to prevent the warning, +so that the above workaround is no longer required. +.SH EXAMPLES +.B RFC\~2822-compliant date format +(with an English locale for %a and %b) +.P +.in +4n +.EX +"%a,\ %d\ %b\ %Y\ %T\ %z" +.EE +.in +.P +.B RFC\~822-compliant date format +(with an English locale for %a and %b) +.P +.in +4n +.EX +"%a,\ %d\ %b\ %y\ %T\ %z" +.EE +.in +.SS Example program +The program below can be used to experiment with +.BR strftime (). +.P +Some examples of the result string produced by the glibc implementation of +.BR strftime () +are as follows: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]%m\[aq]" +Result string is "11" +.RB "$" " ./a.out \[aq]%5m\[aq]" +Result string is "00011" +.RB "$" " ./a.out \[aq]%_5m\[aq]" +Result string is " 11" +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strftime.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +\& +int +main(int argc, char *argv[]) +{ + char outstr[200]; + time_t t; + struct tm *tmp; +\& + t = time(NULL); + tmp = localtime(&t); + if (tmp == NULL) { + perror("localtime"); + exit(EXIT_FAILURE); + } +\& + if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) { + fprintf(stderr, "strftime returned 0"); + exit(EXIT_FAILURE); + } +\& + printf("Result string is \e"%s\e"\en", outstr); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR date (1), +.BR time (2), +.BR ctime (3), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR sprintf (3), +.BR strptime (3) diff --git a/man/man3/strftime_l.3 b/man/man3/strftime_l.3 new file mode 100644 index 0000000..02e797a --- /dev/null +++ b/man/man3/strftime_l.3 @@ -0,0 +1 @@ +.so man3/strftime.3 diff --git a/man/man3/string.3 b/man/man3/string.3 new file mode 100644 index 0000000..c7069b6 --- /dev/null +++ b/man/man3/string.3 @@ -0,0 +1,217 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu) +.TH string 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpcpy, strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, +strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, +strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex +\- string operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.B #include <strings.h> +.TP +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \ +size_t " n ); +Compare the first +.I n +bytes of the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "char *index(const char *" s ", int " c ); +Identical to +.BR strchr (3). +.TP +.BI "char *rindex(const char *" s ", int " c ); +Identical to +.BR strrchr (3). +.TP +.B #include <string.h> +.TP +.BI "char *stpcpy(char *restrict " dest ", const char *restrict " src ); +Copy a string from +.I src +to +.IR dest , +returning a pointer to the end of the resulting string at +.IR dest . +.TP +.BI "char *strcat(char *restrict " dest ", const char *restrict " src ); +Append the string +.I src +to the string +.IR dest , +returning a pointer +.IR dest . +.TP +.BI "char *strchr(const char *" s ", int " c ); +Return a pointer to the first occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.IR s2 . +.TP +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.I s2 +using the current locale. +.TP +.BI "char *strcpy(char *restrict " dest ", const char *restrict " src ); +Copy the string +.I src +to +.IR dest , +returning a pointer to the start of +.IR dest . +.TP +.BI "size_t strcspn(const char *" s ", const char *" reject ); +Calculate the length of the initial segment of the string +.I s +which does not contain any of bytes in the string +.IR reject , +.TP +.BI "char *strdup(const char *" s ); +Return a duplicate of the string +.I s +in memory allocated using +.BR malloc (3). +.TP +.BI "char *strfry(char *" string ); +Randomly swap the characters in +.IR string . +.TP +.BI "size_t strlen(const char *" s ); +Return the length of the string +.IR s . +.TP +.nf +.BI "char *strncat(char " dest "[restrict strlen(." dest ") + ." n " + 1]," +.BI " const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Append at most +.I n +bytes from the unterminated string +.I src +to the string +.IR dest , +returning a pointer to +.IR dest . +.TP +.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); +Compare at most +.I n +bytes of the strings +.I s1 +and +.IR s2 . +.TP +.BI "char *strpbrk(const char *" s ", const char *" accept ); +Return a pointer to the first occurrence in the string +.I s +of one of the bytes in the string +.IR accept . +.TP +.BI "char *strrchr(const char *" s ", int " c ); +Return a pointer to the last occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "char *strsep(char **restrict " stringp ", const char *restrict " delim ); +Extract the initial token in +.I stringp +that is delimited by one of the bytes in +.IR delim . +.TP +.BI "size_t strspn(const char *" s ", const char *" accept ); +Calculate the length of the starting segment in the string +.I s +that consists entirely of bytes in +.IR accept . +.TP +.BI "char *strstr(const char *" haystack ", const char *" needle ); +Find the first occurrence of the substring +.I needle +in the string +.IR haystack , +returning a pointer to the found substring. +.TP +.BI "char *strtok(char *restrict " s ", const char *restrict " delim ); +Extract tokens from the string +.I s +that are delimited by one of the bytes in +.IR delim . +.TP +.nf +.BI "size_t strxfrm(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Transforms +.I src +to the current locale and copies the first +.I n +bytes to +.IR dest . +.TP +.nf +.BI "char *strncpy(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Fill a fixed-size buffer with leading non-null bytes from a source array, +padding with null bytes as needed. +.SH DESCRIPTION +The string functions perform operations on null-terminated +strings. +See the individual man pages for descriptions of each function. +.SH SEE ALSO +.BR bstring (3), +.BR stpcpy (3), +.BR strcasecmp (3), +.BR strcat (3), +.BR strchr (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strcpy (3), +.BR strcspn (3), +.BR strdup (3), +.BR strfry (3), +.BR strlen (3), +.BR strncasecmp (3), +.BR strncat (3), +.BR strncmp (3), +.BR strncpy (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR strxfrm (3) diff --git a/man/man3/strlen.3 b/man/man3/strlen.3 new file mode 100644 index 0000000..69aa2e8 --- /dev/null +++ b/man/man3/strlen.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu) +.TH strlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strlen \- calculate the length of a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "size_t strlen(const char *" s ); +.fi +.SH DESCRIPTION +The +.BR strlen () +function calculates the length of the string pointed to by +.IR s , +excluding the terminating null byte (\[aq]\e0\[aq]). +.SH RETURN VALUE +The +.BR strlen () +function returns the number of bytes in the string pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH NOTES +In cases where the input buffer may not contain +a terminating null byte, +.BR strnlen (3) +should be used instead. +.SH SEE ALSO +.BR string (3), +.BR strnlen (3), +.BR wcslen (3), +.BR wcsnlen (3) diff --git a/man/man3/strncasecmp.3 b/man/man3/strncasecmp.3 new file mode 100644 index 0000000..fd3b671 --- /dev/null +++ b/man/man3/strncasecmp.3 @@ -0,0 +1 @@ +.so man3/strcasecmp.3 diff --git a/man/man3/strncat.3 b/man/man3/strncat.3 new file mode 100644 index 0000000..275e8d0 --- /dev/null +++ b/man/man3/strncat.3 @@ -0,0 +1,132 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strncat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strncat +\- +append non-null bytes from a source array to a string, +and null-terminate the result +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); +.fi +.SH DESCRIPTION +This function appends at most +.I ssize +non-null bytes from the array pointed to by +.IR src , +followed by a null character, +to the end of the string pointed to by +.IR dst . +.I dst +must point to a string contained in a buffer that is large enough, +that is, the buffer size must be at least +.IR "strlen(dst) + strnlen(src, ssize) + 1" . +.P +An implementation of this function might be: +.P +.in +4n +.EX +char * +strncat(char *restrict dst, const char *restrict src, size_t ssize) +{ + #define strnul(s) (s + strlen(s)) +\& + stpcpy(mempcpy(strnul(dst), src, strnlen(src, ssize)), ""); + return dst; +} +.EE +.in +.SH RETURN VALUE +.BR strncat () +returns +.IR dst . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strncat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +The name of this function is confusing; +it has no relation to +.BR strncpy (3). +.P +If the destination buffer does not already contain a string, +or is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.SH BUGS +This function can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strncat.c) +.EX +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define nitems(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +int +main(void) +{ + size_t n; +\& + // Null-padded fixed-size character sequences + char pre[4] = "pre."; + char new_post[50] = ".foo.bar"; +\& + // Strings + char post[] = ".post"; + char src[] = "some_long_body.post"; + char *dest; +\& + n = nitems(pre) + strlen(src) \- strlen(post) + nitems(new_post) + 1; + dest = malloc(sizeof(*dest) * n); + if (dest == NULL) + err(EXIT_FAILURE, "malloc()"); +\& + dest[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. + strncat(dest, pre, nitems(pre)); + strncat(dest, src, strlen(src) \- strlen(post)); + strncat(dest, new_post, nitems(new_post)); +\& + puts(dest); // "pre.some_long_body.foo.bar" + free(dest); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR string (3), +.BR string_copying (7) diff --git a/man/man3/strncmp.3 b/man/man3/strncmp.3 new file mode 100644 index 0000000..1007f43 --- /dev/null +++ b/man/man3/strncmp.3 @@ -0,0 +1 @@ +.so man3/strcmp.3 diff --git a/man/man3/strncpy.3 b/man/man3/strncpy.3 new file mode 100644 index 0000000..4710b02 --- /dev/null +++ b/man/man3/strncpy.3 @@ -0,0 +1 @@ +.so man3/stpncpy.3 diff --git a/man/man3/strndup.3 b/man/man3/strndup.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strndup.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strndupa.3 b/man/man3/strndupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strndupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strnlen.3 b/man/man3/strnlen.3 new file mode 100644 index 0000000..147f9aa --- /dev/null +++ b/man/man3/strnlen.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.TH strnlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strnlen \- determine the length of a fixed-size string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "size_t strnlen(const char " s [. maxlen "], size_t " maxlen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strnlen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR strnlen () +function returns the number of bytes in the string +pointed to by +.IR s , +excluding the terminating null byte (\[aq]\e0\[aq]), +but at most +.IR maxlen . +In doing this, +.BR strnlen () +looks only at the first +.I maxlen +characters in the string pointed to by +.I s +and never beyond +.IR s[maxlen\-1] . +.SH RETURN VALUE +The +.BR strnlen () +function returns +.IR strlen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null terminating (\[aq]\e0\[aq]) among the first +.I maxlen +characters pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strnlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2008. +.SH SEE ALSO +.BR strlen (3) diff --git a/man/man3/strpbrk.3 b/man/man3/strpbrk.3 new file mode 100644 index 0000000..2ad85af --- /dev/null +++ b/man/man3/strpbrk.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH strpbrk 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strpbrk \- search a string for any of a set of bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strpbrk(const char *" s ", const char *" accept ); +.fi +.SH DESCRIPTION +The +.BR strpbrk () +function locates the first occurrence in the +string +.I s +of any of the bytes in the string +.IR accept . +.SH RETURN VALUE +The +.BR strpbrk () +function returns a pointer to the byte in +.I s +that matches one of the bytes in +.IR accept , +or NULL +if no such byte is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strpbrk () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcspbrk (3) diff --git a/man/man3/strptime.3 b/man/man3/strptime.3 new file mode 100644 index 0000000..ba6c383 --- /dev/null +++ b/man/man3/strptime.3 @@ -0,0 +1,413 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 +.\" Modified, aeb, 2000-04-07 +.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 +.\" Modified, aeb, 2001-08-31 +.\" Modified, wharms 2001-11-12, remark on white space and example +.\" +.TH strptime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strptime \- convert a string representation of time to a time tm structure +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <time.h> +.P +.BI "char *strptime(const char *restrict " s ", const char *restrict " format , +.BI " struct tm *restrict " tm ); +.fi +.SH DESCRIPTION +The +.BR strptime () +function is the converse of +.BR strftime (3); +it converts the character string pointed to by +.I s +to values which are stored in the +"broken-down time" +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.P +The broken-down time structure +.I tm +is described in +.BR tm (3type). +.P +The +.I format +argument +is a character string that consists of field descriptors and text characters, +reminiscent of +.BR scanf (3). +Each field descriptor consists of a +.B % +character followed by another character that specifies the replacement +for the field descriptor. +All other characters in the +.I format +string must have a matching character in the input string, +except for whitespace, which matches zero or more +whitespace characters in the input string. +There should be white\%space or other alphanumeric characters +between any two field descriptors. +.P +The +.BR strptime () +function processes the input string from left +to right. +Each of the three possible input elements (whitespace, +literal, or format) are handled one after the other. +If the input cannot be matched to the format string, the function stops. +The remainder of the format and input strings are not processed. +.P +The supported input field descriptors are listed below. +In case a text string (such as the name of a day of the week or a month name) +is to be matched, the comparison is case insensitive. +In case a number is to be matched, leading zeros are +permitted but not required. +.TP +.B %% +The +.B % +character. +.TP +.BR %a " or " %A +The name of the day of the week according to the current locale, +in abbreviated form or the full name. +.TP +.BR %b " or " %B " or " %h +The month name according to the current locale, +in abbreviated form or the full name. +.TP +.B %c +The date and time representation for the current locale. +.TP +.B %C +The century number (0\[en]99). +.TP +.BR %d " or " %e +The day of month (1\[en]31). +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(This is the American style date, very confusing +to non-Americans, especially since +.B %d/%m/%y +is widely used in Europe. +The ISO\~8601 standard format is +.BR %Y\-%m\-%d .) +.TP +.B %H +The hour (0\[en]23). +.TP +.B %I +The hour on a 12-hour clock (1\[en]12). +.TP +.B %j +The day number in the year (1\[en]366). +.TP +.B %m +The month number (1\[en]12). +.TP +.B %M +The minute (0\[en]59). +.TP +.B %n +Arbitrary whitespace. +.TP +.B %p +The locale's equivalent of AM or PM. +(Note: there may be none.) +.TP +.B %r +The 12-hour clock time (using the locale's AM or PM). +In the POSIX locale equivalent to +.BR "%I:%M:%S %p" . +If +.I t_fmt_ampm +is empty in the +.B LC_TIME +part of the current locale, +then the behavior is undefined. +.TP +.B %R +Equivalent to +.BR %H:%M . +.TP +.B %S +The second (0\[en]60; 60 may occur for leap seconds; +earlier also 61 was allowed). +.TP +.B %t +Arbitrary whitespace. +.TP +.B %T +Equivalent to +.BR %H:%M:%S . +.TP +.B %U +The week number with Sunday the first day of the week (0\[en]53). +The first Sunday of January is the first day of week 1. +.TP +.B %w +The ordinal number of the day of the week (0\[en]6), with Sunday = 0. +.TP +.B %W +The week number with Monday the first day of the week (0\[en]53). +The first Monday of January is the first day of week 1. +.TP +.B %x +The date, using the locale's date format. +.TP +.B %X +The time, using the locale's time format. +.TP +.B %y +The year within century (0\[en]99). +When a century is not otherwise specified, values in the range 69\[en]99 refer +to years in the twentieth century (1969\[en]1999); values in the +range 00\[en]68 refer to years in the twenty-first century (2000\[en]2068). +.TP +.B %Y +The year, including century (for example, 1991). +.P +Some field descriptors can be modified by the E or O modifier characters +to indicate that an alternative format or specification should be used. +If the +alternative format or specification does not exist in the current locale, the +unmodified field descriptor is used. +.P +The E modifier specifies that the input string may contain +alternative locale-dependent versions of the date and time representation: +.TP +.B %Ec +The locale's alternative date and time representation. +.TP +.B %EC +The name of the base year (period) in the locale's alternative representation. +.TP +.B %Ex +The locale's alternative date representation. +.TP +.B %EX +The locale's alternative time representation. +.TP +.B %Ey +The offset from +.B %EC +(year only) in the locale's alternative representation. +.TP +.B %EY +The full alternative year representation. +.P +The O modifier specifies that the numerical input may be in an +alternative locale-dependent format: +.TP +.BR %Od " or " %Oe +The day of the month using the locale's alternative numeric symbols; +leading zeros are permitted but not required. +.TP +.B %OH +The hour (24-hour clock) using the locale's alternative numeric symbols. +.TP +.B %OI +The hour (12-hour clock) using the locale's alternative numeric symbols. +.TP +.B %Om +The month using the locale's alternative numeric symbols. +.TP +.B %OM +The minutes using the locale's alternative numeric symbols. +.TP +.B %OS +The seconds using the locale's alternative numeric symbols. +.TP +.B %OU +The week number of the year (Sunday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Ow +The ordinal number of the day of the week (Sunday=0), +using the locale's alternative numeric symbols. +.TP +.B %OW +The week number of the year (Monday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Oy +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.SH RETURN VALUE +The return value of the function is a pointer to the first character +not processed in this function call. +In case the input string +contains more characters than required by the format string, the return +value points right after the last consumed input character. +In case the whole input string is consumed, +the return value points to the null byte at the end of the string. +If +.BR strptime () +fails to match all +of the format string and therefore an error occurred, the function +returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strptime () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +.SH NOTES +In principle, this function does not initialize +.I tm +but +stores only the values specified. +This means that +.I tm +should be initialized before the call. +Details differ a bit between different UNIX systems. +The glibc implementation does not touch those fields which are not +explicitly specified, except that it recomputes the +.I tm_wday +and +.I tm_yday +field if any of the year, month, or day elements changed. +.\" .P +.\" This function is available since libc 4.6.8. +.\" Linux libc4 and libc5 includes define the prototype unconditionally; +.\" glibc2 includes provide a prototype only when +.\" .B _XOPEN_SOURCE +.\" or +.\" .B _GNU_SOURCE +.\" are defined. +.\" .P +.\" Before libc 5.4.13 whitespace +.\" (and the \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled, +.\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted, +.\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification. +.P +The \[aq]y\[aq] (year in century) specification is taken to specify a year +.\" in the 20th century by libc4 and libc5. +.\" It is taken to be a year +in the range 1950\[en]2049 by glibc 2.0. +It is taken to be a year in +1969\[en]2068 since glibc 2.1. +.\" In libc4 and libc5 the code for %I is broken (fixed in glibc; +.\" %OI was fixed in glibc 2.2.4). +.SS glibc notes +For reasons of symmetry, glibc tries to support for +.BR strptime () +the same format characters as for +.BR strftime (3). +(In most cases, the corresponding fields are parsed, but no field in +.I tm +is changed.) +This leads to +.TP +.B %F +Equivalent to +.BR %Y\-%m\-%d , +the ISO\~8601 date format. +.TP +.B %g +The year corresponding to the ISO week number, but without the century +(0\[en]99). +.TP +.B %G +The year corresponding to the ISO week number. +(For example, 1991.) +.TP +.B %u +The day of the week as a decimal number (1\[en]7, where Monday = 1). +.TP +.B %V +The ISO\~8601:1988 week number as a decimal number (1\[en]53). +If the week (starting on Monday) containing 1 January has four or more days +in the new year, then it is considered week 1. +Otherwise, it is the last week +of the previous year, and the next week is week 1. +.TP +.B %z +An RFC-822/ISO\~8601 standard timezone specification. +.TP +.B %Z +The timezone name. +.P +Similarly, because of GNU extensions to +.BR strftime (3), +.B %k +is accepted as a synonym for +.BR %H , +and +.B %l +should be accepted +as a synonym for +.BR %I , +and +.B %P +is accepted as a synonym for +.BR %p . +Finally +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +Leap seconds are not counted unless leap second support is available. +.P +The glibc implementation does not require whitespace between +two field descriptors. +.SH EXAMPLES +The following example demonstrates the use of +.BR strptime () +and +.BR strftime (3). +.P +.\" SRC BEGIN (strptime.c) +.EX +#define _XOPEN_SOURCE +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> +\& +int +main(void) +{ + struct tm tm; + char buf[255]; +\& + memset(&tm, 0, sizeof(tm)); + strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm); + strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); + puts(buf); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR getdate (3), +.BR scanf (3), +.BR setlocale (3), +.BR strftime (3) diff --git a/man/man3/strrchr.3 b/man/man3/strrchr.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man/man3/strrchr.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man/man3/strsep.3 b/man/man3/strsep.3 new file mode 100644 index 0000000..a3f0153 --- /dev/null +++ b/man/man3/strsep.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH strsep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strsep \- extract token from string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strsep(char **restrict " stringp ", const char *restrict " delim ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strsep (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +If +.I *stringp +is NULL, the +.BR strsep () +function returns NULL +and does nothing else. +Otherwise, this function finds the first token +in the string +.I *stringp +that is delimited by one of the bytes in the string +.IR delim . +This token is terminated by overwriting the delimiter +with a null byte (\[aq]\e0\[aq]), +and +.I *stringp +is updated to point past the token. +In case no delimiter was found, the token is taken to be +the entire string +.IR *stringp , +and +.I *stringp +is made NULL. +.SH RETURN VALUE +The +.BR strsep () +function returns a pointer to the token, +that is, it returns the original value of +.IR *stringp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strsep () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.4BSD. +.P +The +.BR strsep () +function was introduced as a replacement for +.BR strtok (3), +since the latter cannot handle empty fields. +However, +.BR strtok (3) +conforms to C89/C99 and hence is more portable. +.SH BUGS +Be cautious when using this function. +If you do use it, note that: +.IP \[bu] 3 +This function modifies its first argument. +.IP \[bu] +This function cannot be used on constant strings. +.IP \[bu] +The identity of the delimiting character is lost. +.SH EXAMPLES +The program below is a port of the one found in +.BR strtok (3), +which, however, doesn't discard multiple delimiters or empty tokens: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> + \-\-> + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +4: + \-\-> +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strsep.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + char *token, *subtoken; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s string delim subdelim\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) { + printf("%u: %s\en", j, token); +\& + while ((subtoken = strsep(&token, argv[3]))) + printf("\et \-\-> %s\en", subtoken); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man/man3/strsignal.3 b/man/man3/strsignal.3 new file mode 100644 index 0000000..168cde4 --- /dev/null +++ b/man/man3/strsignal.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH strsignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strsignal, sigabbrev_np, sigdescr_np, sys_siglist \- +return string describing signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strsignal(int " sig ); +.BI "const char *sigdescr_np(int " sig ); +.BI "const char *sigabbrev_np(int " sig ); +.P +.BI "[[deprecated]] extern const char *const " sys_siglist []; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigabbrev_np (), +.BR sigdescr_np (): +.nf + _GNU_SOURCE +.fi +.P +.BR strsignal (): +.nf + From glibc 2.10 to glibc 2.31: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.IR sys_siglist : +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strsignal () +function returns a string describing the signal +number passed in the argument +.IR sig . +The string can be used only until the next call to +.BR strsignal (). +The string returned by +.BR strsignal () +is localized according to the +.B LC_MESSAGES +category in the current locale. +.P +The +.BR sigdescr_np () +function returns a string describing the signal +number passed in the argument +.IR sig . +Unlike +.BR strsignal () +this string is not influenced by the current locale. +.P +The +.BR sigabbrev_np () +function returns the abbreviated name of the signal, +.IR sig . +For example, given the value +.BR SIGINT , +it returns the string "INT". +.P +The (deprecated) array +.I sys_siglist +holds the signal description strings +indexed by signal number. +The +.BR strsignal () +or the +.BR sigdescr_np () +function should be used instead of this array; see also VERSIONS. +.SH RETURN VALUE +The +.BR strsignal () +function returns the appropriate description +string, or an unknown signal message if the signal number is invalid. +On some systems (but not on Linux), NULL may instead be +returned for an invalid signal number. +.P +The +.BR sigdescr_np () +and +.BR sigabbrev_np () +functions return the appropriate description string. +The returned string is statically allocated and valid for +the lifetime of the program. +These functions return NULL for an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strsignal () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:strsignal locale +T} +T{ +.na +.nh +.BR sigdescr_np (), +.BR sigabbrev_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strsignal () +POSIX.1-2008. +.TP +.BR sigdescr_np () +.TQ +.BR sigabbrev_np () +GNU. +.TP +.I sys_siglist +None. +.\" glibc commit b1ccfc061feee9ce616444ded8e1cd5acf9fa97f +.SH HISTORY +.TP +.BR strsignal () +POSIX.1-2008. +Solaris, BSD. +.TP +.BR sigdescr_np () +.TQ +.BR sigabbrev_np () +glibc 2.32. +.TP +.I sys_siglist +Removed in glibc 2.32. +.SH NOTES +.BR sigdescr_np () +and +.BR sigabbrev_np () +are thread-safe and async-signal-safe. +.SH SEE ALSO +.BR psignal (3), +.BR strerror (3) diff --git a/man/man3/strspn.3 b/man/man3/strspn.3 new file mode 100644 index 0000000..c1739c5 --- /dev/null +++ b/man/man3/strspn.3 @@ -0,0 +1,85 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu) +.TH strspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strspn, strcspn \- get length of a prefix substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "size_t strspn(const char *" s ", const char *" accept ); +.BI "size_t strcspn(const char *" s ", const char *" reject ); +.fi +.SH DESCRIPTION +The +.BR strspn () +function calculates the length (in bytes) of the initial +segment of +.I s +which consists entirely of bytes in +.IR accept . +.P +The +.BR strcspn () +function calculates the length of the initial +segment of +.I s +which consists entirely of bytes not in +.IR reject . +.SH RETURN VALUE +The +.BR strspn () +function returns the number of bytes in +the initial segment of +.I s +which consist only of bytes +from +.IR accept . +.P +The +.BR strcspn () +function returns the number of bytes in +the initial segment of +.I s +which are not in the string +.IR reject . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strspn (), +.BR strcspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strstr (3), +.BR strtok (3), +.BR wcscspn (3), +.BR wcsspn (3) diff --git a/man/man3/strstr.3 b/man/man3/strstr.3 new file mode 100644 index 0000000..c62469d --- /dev/null +++ b/man/man3/strstr.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:56:43 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added history, aeb, 980113. +.\" 2005-05-05 mtk: added strcasestr() +.\" +.TH strstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strstr, strcasestr \- locate a substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strstr(const char *" haystack ", const char *" needle ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "char *strcasestr(const char *" haystack ", const char *" needle ); +.fi +.SH DESCRIPTION +The +.BR strstr () +function finds the first occurrence of the substring +.I needle +in the string +.IR haystack . +The terminating null bytes (\[aq]\e0\[aq]) are not compared. +.P +The +.BR strcasestr () +function is like +.BR strstr (), +but ignores the case of both arguments. +.SH RETURN VALUE +These functions return a pointer to the beginning of the +located substring, or NULL if the substring is not found. +.P +If +.I needle +is the empty string, +the return value is always +.I haystack +itself. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strstr () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR strcasestr () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR strstr () +C11, POSIX.1-2008. +.TP +.BR strcasestr () +GNU. +.SH HISTORY +.TP +.BR strstr () +POSIX.1-2001, C89. +.TP +.BR strcasestr () +GNU. +.SH SEE ALSO +.BR memchr (3), +.BR memmem (3), +.BR strcasecmp (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strtok (3), +.BR wcsstr (3) diff --git a/man/man3/strtod.3 b/man/man3/strtod.3 new file mode 100644 index 0000000..c1b36cc --- /dev/null +++ b/man/man3/strtod.3 @@ -0,0 +1,205 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)strtod.3 5.3 (Berkeley) 6/29/91 +.\" +.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.\" Added strof, strtold, aeb, 2001-06-07 +.\" +.TH strtod 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtod, strtof, strtold \- convert ASCII string to floating-point number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "double strtod(const char *restrict " nptr ", char **restrict " endptr ); +.BI "float strtof(const char *restrict " nptr ", char **restrict " endptr ); +.BI "long double strtold(const char *restrict " nptr \ +", char **restrict " endptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtof (), +.BR strtold (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR strtod (), +.BR strtof (), +and +.BR strtold () +functions convert the initial portion of the string pointed to by +.I nptr +to +.IR double , +.IR float , +and +.I long double +representation, respectively. +.P +The expected form of the (initial portion of the) string is +optional leading white space as recognized by +.BR isspace (3), +an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either +(i) a decimal number, or (ii) a hexadecimal number, +or (iii) an infinity, or (iv) a NAN (not-a-number). +.P +A +.I "decimal number" +consists of a nonempty sequence of decimal digits +possibly containing a radix character (decimal point, locale-dependent, +usually \[aq].\[aq]), optionally followed by a decimal exponent. +A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an +optional plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 10. +.P +A +.I "hexadecimal number" +consists of a "0x" or "0X" followed by a nonempty sequence of +hexadecimal digits possibly containing a radix character, +optionally followed by a binary exponent. +A binary exponent +consists of a \[aq]P\[aq] or \[aq]p\[aq], followed by an optional +plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 2. +At least one of radix character and binary exponent must be present. +.P +An +.I infinity +is either "INF" or "INFINITY", disregarding case. +.P +A +.I NAN +is "NAN" (disregarding case) optionally followed by a string, +.IR (n-char-sequence) , +where +.I n-char-sequence +specifies in an implementation-dependent +way the type of NAN (see NOTES). +.SH RETURN VALUE +These functions return the converted value, if any. +.P +If +.I endptr +is not NULL, +a pointer to the character after the last character used in the conversion +is stored in the location referenced by +.IR endptr . +.P +If no conversion is performed, zero is returned and (unless +.I endptr +is null) the value of +.I nptr +is stored in the location referenced by +.IR endptr . +.P +If the correct value would cause overflow, plus or minus +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.B HUGE_VALL +is returned (according to the return type and sign of the value), +and +.B ERANGE +is stored in +.IR errno . +.P +If the correct value would cause underflow, +a value with magnitude no larger than +.BR DBL_MIN , +.BR FLT_MIN , +or +.B LDBL_MIN +is returned and +.B ERANGE +is stored in +.IR errno . +.SH ERRORS +.TP +.B ERANGE +Overflow or underflow occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtod (), +.BR strtof (), +.BR strtold () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +In the glibc implementation, the +.I n-char-sequence +that optionally follows "NAN" +is interpreted as an integer number +(with an optional '0' or '0x' prefix to select base 8 or 16) +that is to be placed in the +mantissa component of the returned value. +.\" From glibc 2.8's stdlib/strtod_l.c: +.\" We expect it to be a number which is put in the +.\" mantissa of the number. +.\" It looks as though at least FreeBSD (according to the manual) does +.\" something similar. +.\" C11 says: "An implementation may use the n-char sequence to determine +.\" extra information to be represented in the NaN's significant." +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtod () +C89, POSIX.1-2001. +.TP +.BR strtof () +.TQ +.BR strtold () +C99, POSIX.1-2001. +.SH NOTES +Since +0 can legitimately be returned +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.SH EXAMPLES +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR nan (3), +.BR nanf (3), +.BR nanl (3), +.BR strfromd (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/strtof.3 b/man/man3/strtof.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man/man3/strtof.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man/man3/strtoimax.3 b/man/man3/strtoimax.3 new file mode 100644 index 0000000..54799d5 --- /dev/null +++ b/man/man3/strtoimax.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH strtoimax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtoimax, strtoumax \- convert string to integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <inttypes.h> +.P +.BI "intmax_t strtoimax(const char *restrict " nptr ", char **restrict " endptr , +.BI " int " base ); +.BI "uintmax_t strtoumax(const char *restrict " nptr ", char **restrict " endptr , +.BI " int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR strtol (3) +and +.BR strtoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH RETURN VALUE +On success, the converted value is returned. +If nothing was found to convert, zero is returned. +On overflow or underflow +.B INTMAX_MAX +or +.B INTMAX_MIN +or +.B UINTMAX_MAX +is returned, and +.I errno +is set to +.BR ERANGE . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtoimax (), +.BR strtoumax () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtol (3), +.BR strtoul (3), +.BR wcstoimax (3) diff --git a/man/man3/strtok.3 b/man/man3/strtok.3 new file mode 100644 index 0000000..efd56de --- /dev/null +++ b/man/man3/strtok.3 @@ -0,0 +1,288 @@ +'\" t +.\" Copyright (C) 2005, 2013 Michael Kerrisk <mtk.manpages@gmail.com> +.\" a few fragments from an earlier (1996) version by +.\" Andries Brouwer (aeb@cwi.nl) remain. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 960210, aeb@cwi.nl +.\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org> +.\" 2005-11-17, mtk: Substantial parts rewritten +.\" 2013-05-19, mtk: added much further detail on the operation of strtok() +.\" +.TH strtok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtok, strtok_r \- extract tokens from strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "char *strtok(char *restrict " str ", const char *restrict " delim ); +.BI "char *strtok_r(char *restrict " str ", const char *restrict " delim , +.BI " char **restrict " saveptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtok_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtok () +function breaks a string into a sequence of zero or more nonempty tokens. +On the first call to +.BR strtok (), +the string to be parsed should be +specified in +.IR str . +In each subsequent call that should parse the same string, +.I str +must be NULL. +.P +The +.I delim +argument specifies a set of bytes that +delimit the tokens in the parsed string. +The caller may specify different strings in +.I delim +in successive +calls that parse the same string. +.P +Each call to +.BR strtok () +returns a pointer to a +null-terminated string containing the next token. +This string does not include the delimiting byte. +If no more tokens are found, +.BR strtok () +returns NULL. +.P +A sequence of calls to +.BR strtok () +that operate on the same string maintains a pointer +that determines the point from which to start searching for the next token. +The first call to +.BR strtok () +sets this pointer to point to the first byte of the string. +The start of the next token is determined by scanning forward +for the next nondelimiter byte in +.IR str . +If such a byte is found, it is taken as the start of the next token. +If no such byte is found, +then there are no more tokens, and +.BR strtok () +returns NULL. +(A string that is empty or that contains only delimiters +will thus cause +.BR strtok () +to return NULL on the first call.) +.P +The end of each token is found by scanning forward until either +the next delimiter byte is found or until the +terminating null byte (\[aq]\e0\[aq]) is encountered. +If a delimiter byte is found, it is overwritten with +a null byte to terminate the current token, and +.BR strtok () +saves a pointer to the following byte; +that pointer will be used as the starting point +when searching for the next token. +In this case, +.BR strtok () +returns a pointer to the start of the found token. +.P +From the above description, +it follows that a sequence of two or more contiguous delimiter bytes in +the parsed string is considered to be a single delimiter, and that +delimiter bytes at the start or end of the string are ignored. +Put another way: the tokens returned by +.BR strtok () +are always nonempty strings. +Thus, for example, given the string "\fIaaa;;bbb,\fP", +successive calls to +.BR strtok () +that specify the delimiter string "\fI;,\fP" +would return the strings "\fIaaa\fP" and "\fIbbb\fP", +and then a null pointer. +.P +The +.BR strtok_r () +function is a reentrant version of +.BR strtok (). +The +.I saveptr +argument is a pointer to a +.I char\~* +variable that is used internally by +.BR strtok_r () +in order to maintain context between successive calls that parse the +same string. +.P +On the first call to +.BR strtok_r (), +.I str +should point to the string to be parsed, and the value of +.I *saveptr +is ignored (but see NOTES). +In subsequent calls, +.I str +should be NULL, and +.I saveptr +(and the buffer that it points to) +should be unchanged since the previous call. +.P +Different strings may be parsed concurrently using sequences of calls to +.BR strtok_r () +that specify different +.I saveptr +arguments. +.SH RETURN VALUE +The +.BR strtok () +and +.BR strtok_r () +functions return a pointer to +the next token, or NULL if there are no more tokens. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtok () +T} Thread safety MT-Unsafe race:strtok +T{ +.na +.nh +.BR strtok_r () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On some implementations, +.\" Tru64, according to its manual page +.I *saveptr +is required to be NULL on the first call to +.BR strtok_r () +that is being used to parse +.IR str . +.SH STANDARDS +.TP +.BR strtok () +C11, POSIX.1-2008. +.TP +.BR strtok_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strtok () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtok_r () +POSIX.1-2001. +.SH BUGS +Be cautious when using these functions. +If you do use them, note that: +.IP \[bu] 3 +These functions modify their first argument. +.IP \[bu] +These functions cannot be used on constant strings. +.IP \[bu] +The identity of the delimiting byte is lost. +.IP \[bu] +The +.BR strtok () +function uses a static buffer while parsing, so it's not thread safe. +Use +.BR strtok_r () +if this matters to you. +.SH EXAMPLES +The program below uses nested loops that employ +.BR strtok_r () +to break a string into a two-level hierarchy of tokens. +The first command-line argument specifies the string to be parsed. +The second argument specifies the delimiter byte(s) +to be used to separate that string into "major" tokens. +The third argument specifies the delimiter byte(s) +to be used to separate the "major" tokens into subtokens. +.P +An example of the output produced by this program is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strtok.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + char *str1, *str2, *token, *subtoken; + char *saveptr1, *saveptr2; + int j; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s string delim subdelim\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) { + token = strtok_r(str1, argv[2], &saveptr1); + if (token == NULL) + break; + printf("%d: %s\en", j, token); +\& + for (str2 = token; ; str2 = NULL) { + subtoken = strtok_r(str2, argv[3], &saveptr2); + if (subtoken == NULL) + break; + printf("\et \-\-> %s\en", subtoken); + } + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +Another example program using +.BR strtok () +can be found in +.BR getaddrinfo_a (3). +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wcstok (3) diff --git a/man/man3/strtok_r.3 b/man/man3/strtok_r.3 new file mode 100644 index 0000000..19095a0 --- /dev/null +++ b/man/man3/strtok_r.3 @@ -0,0 +1 @@ +.so man3/strtok.3 diff --git a/man/man3/strtol.3 b/man/man3/strtol.3 new file mode 100644 index 0000000..c001265 --- /dev/null +++ b/man/man3/strtol.3 @@ -0,0 +1,321 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@ganil.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 +.TH strtol 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtol, strtoll, strtoq \- convert a string to a long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "long strtol(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.BI "long long strtoll(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtoll (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtol () +function converts the initial part of the string +in +.I nptr +to a long integer value according to the given +.IR base , +which must be between 2 and 36 inclusive, or be the special value 0. +.P +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] sign. +If +.I base +is zero or 16, the string may then include a +"0x" or "0X" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \[aq]0\[aq], in which case it is taken as 8 (octal). +.P +The remainder of the string is converted to a +.I long +value +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.P +If +.I endptr +is not NULL, +and the +.I base +is supported, +.BR strtol () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtol () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \[aq]\e0\[aq] but +.I **endptr +is \[aq]\e0\[aq] on return, the entire string is valid. +.P +The +.BR strtoll () +function works just like the +.BR strtol () +function but returns a +.I long long +integer value. +.SH RETURN VALUE +The +.BR strtol () +function returns the result of the conversion, +unless the value would underflow or overflow. +If an underflow occurs, +.BR strtol () +returns +.BR LONG_MIN . +If an overflow occurs, +.BR strtol () +returns +.BR LONG_MAX . +In both cases, +.I errno +is set to +.BR ERANGE . +Precisely the same holds for +.BR strtoll () +(with +.B LLONG_MIN +and +.B LLONG_MAX +instead of +.B LONG_MIN +and +.BR LONG_MAX ). +.SH ERRORS +This function does not modify +.I errno +on success. +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.P +The implementation may also set +.I errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtol (), +.BR strtoll (), +.BR strtoq () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtol () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtoll () +POSIX.1-2001, C99. +.SH NOTES +Since +.BR strtol () +can legitimately return 0, +.BR LONG_MAX , +or +.B LONG_MIN +.RB ( LLONG_MAX +or +.B LLONG_MIN +for +.BR strtoll ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno == ERANGE +after the call. +.P +According to POSIX.1, +in locales other than "C" and "POSIX", +these functions may accept other, +implementation-defined numeric strings. +.P +BSD also has +.P +.in +4n +.EX +.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.P +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoll () +or to +.BR strtol (). +.SH CAVEATS +If the +.I base +needs to be tested, +it should be tested in a call where the string is known to succeed. +Otherwise, it's impossible to portably differentiate the errors. +.P +.in +4n +.EX +errno = 0; +strtol("0", NULL, base); +if (errno == EINVAL) + goto unsupported_base; +.EE +.in +.SH EXAMPLES +The program shown below demonstrates the use of +.BR strtol (). +The first command-line argument specifies a string from which +.BR strtol () +should parse a number. +The second (optional) argument specifies the base to be used for +the conversion. +(This argument is converted to numeric form using +.BR atoi (3), +a function that performs no error checking and +has a simpler interface than +.BR strtol ().) +Some examples of the results produced by this program are the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 123" +strtol() returned 123 +.RB "$" " ./a.out \[aq] 123\[aq]" +strtol() returned 123 +.RB "$" " ./a.out 123abc" +strtol() returned 123 +Further characters after number: "abc" +.RB "$" " ./a.out 123abc 55" +strtol: Invalid argument +.RB "$" " ./a.out \[aq]\[aq]" +No digits were found +.RB "$" " ./a.out 4000000000" +strtol: Numerical result out of range +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strtol.c) +.EX +#include <errno.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + int base; + char *endptr, *str; + long val; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s str [base]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + str = argv[1]; + base = (argc > 2) ? atoi(argv[2]) : 0; +\& + errno = 0; /* To distinguish success/failure after call */ + strtol("0", NULL, base); + if (errno == EINVAL) { + perror("strtol"); + exit(EXIT_FAILURE); + } +\& + errno = 0; /* To distinguish success/failure after call */ + val = strtol(str, &endptr, base); +\& + /* Check for various possible errors. */ +\& + if (errno == ERANGE) { + perror("strtol"); + exit(EXIT_FAILURE); + } +\& + if (endptr == str) { + fprintf(stderr, "No digits were found\en"); + exit(EXIT_FAILURE); + } +\& + /* If we got here, strtol() successfully parsed a number. */ +\& + printf("strtol() returned %ld\en", val); +\& + if (*endptr != \[aq]\e0\[aq]) /* Not necessarily an error... */ + printf("Further characters after number: \e"%s\e"\en", endptr); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtoimax (3), +.BR strtoul (3) diff --git a/man/man3/strtold.3 b/man/man3/strtold.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man/man3/strtold.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man/man3/strtoll.3 b/man/man3/strtoll.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man/man3/strtoll.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man/man3/strtoq.3 b/man/man3/strtoq.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man/man3/strtoq.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3 new file mode 100644 index 0000000..dd9d2c1 --- /dev/null +++ b/man/man3/strtoul.3 @@ -0,0 +1,224 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu) +.\" Fixed typo, aeb, 950823 +.\" 2002-02-22, joey, mihtjel: Added strtoull() +.\" +.TH strtoul 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "unsigned long strtoul(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.BI "unsigned long long strtoull(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtoull (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtoul () +function converts the initial part of the string +in +.I nptr +to an +.I "unsigned long" +value according to the +given +.IR base , +which must be between 2 and 36 inclusive, or be +the special value 0. +.P +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] +sign. +If +.I base +is zero or 16, the string may then include a +"0x" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \[aq]0\[aq], in which case it is taken as 8 (octal). +.P +The remainder of the string is converted to an +.I "unsigned long" +value in the obvious manner, +stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.P +If +.I endptr +is not NULL, +and the +.I base +is supported, +.BR strtoul () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtoul () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \[aq]\e0\[aq] but +.I **endptr +is \[aq]\e0\[aq] on return, the entire string is valid. +.P +The +.BR strtoull () +function works just like the +.BR strtoul () +function but returns an +.I "unsigned long long" +value. +.SH RETURN VALUE +The +.BR strtoul () +function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion represented as an unsigned value, +unless the original (nonnegated) value would overflow; in +the latter case, +.BR strtoul () +returns +.B ULONG_MAX +and sets +.I errno +to +.BR ERANGE . +Precisely the same holds for +.BR strtoull () +(with +.B ULLONG_MAX +instead of +.BR ULONG_MAX ). +.SH ERRORS +This function does not modify +.I errno +on success. +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.P +The implementation may also set +.I errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtoul (), +.BR strtoull (), +.BR strtouq () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtoul () +POSIX.1-2001, C89, SVr4. +.TP +.BR strtoull () +POSIX.1-2001, C99. +.SH NOTES +Since +.BR strtoul () +can legitimately return 0 or +.B ULONG_MAX +.RB ( ULLONG_MAX +for +.BR strtoull ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.P +In locales other than the "C" locale, other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.P +BSD also has +.P +.in +4n +.EX +.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.P +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoull () +or to +.BR strtoul (). +.P +Negative values are considered valid input and are +silently converted to the equivalent +.I "unsigned long" +value. +.SH EXAMPLES +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR a64l (3), +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoumax (3) diff --git a/man/man3/strtoull.3 b/man/man3/strtoull.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man/man3/strtoull.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man/man3/strtoumax.3 b/man/man3/strtoumax.3 new file mode 100644 index 0000000..753be84 --- /dev/null +++ b/man/man3/strtoumax.3 @@ -0,0 +1 @@ +.so man3/strtoimax.3 diff --git a/man/man3/strtouq.3 b/man/man3/strtouq.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man/man3/strtouq.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man/man3/strverscmp.3 b/man/man3/strverscmp.3 new file mode 100644 index 0000000..9e3cc39 --- /dev/null +++ b/man/man3/strverscmp.3 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl> +.\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strverscmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strverscmp \- compare two version strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <string.h> +.P +.BI "int strverscmp(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +Often one has files +.IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..." +and it feels wrong when +.BR ls (1) +orders them +.IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 . +.\" classical solution: "rename jan jan0 jan?" +In order to rectify this, GNU introduced the +.I \-v +option to +.BR ls (1), +which is implemented using +.BR versionsort (3), +which again uses +.BR strverscmp (). +.P +Thus, the task of +.BR strverscmp () +is to compare two strings and find the "right" order, while +.BR strcmp (3) +finds only the lexicographic order. +This function does not use +the locale category +.BR LC_COLLATE , +so is meant mostly for situations +where the strings are expected to be in ASCII. +.P +What this function does is the following. +If both strings are equal, return 0. +Otherwise, find the position +between two bytes with the property that before it both strings are equal, +while directly after it there is a difference. +Find the largest consecutive digit strings containing (or starting at, +or ending at) this position. +If one or both of these is empty, +then return what +.BR strcmp (3) +would have returned (numerical ordering of byte values). +Otherwise, compare both digit strings numerically, where digit strings with +one or more leading zeros are interpreted as if they have a decimal point +in front (so that in particular digit strings with more leading zeros +come before digit strings with fewer leading zeros). +Thus, the ordering is +.IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . +.SH RETURN VALUE +The +.BR strverscmp () +function returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, respectively, to be earlier than, equal to, +or later than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strverscmp () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" strverscmp: MT-Safe locale +.\" +.\" glibc manual says strverscmp should have marking locale because it calls +.\" isdigit() multiple times and isdigit() uses locale variable. +.\" But isdigit() has two implementations. With different compiling conditions, +.\" we may call isdigit() in macro, then strverscmp() should not have locale +.\" problem. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below can be used to demonstrate the behavior of +.BR strverscmp (). +It uses +.BR strverscmp () +to compare the two strings given as its command-line arguments. +An example of its use is the following: +.P +.in +4n +.EX +$ \fB./a.out jan1 jan10\fP +jan1 < jan10 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strverscmp.c) +.EX +#define _GNU_SOURCE +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + int res; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <string1> <string2>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + res = strverscmp(argv[1], argv[2]); +\& + printf("%s %s %s\en", argv[1], + (res < 0) ? "<" : (res == 0) ? "==" : ">", argv[2]); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR rename (1), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3) diff --git a/man/man3/strxfrm.3 b/man/man3/strxfrm.3 new file mode 100644 index 0000000..8fb9097 --- /dev/null +++ b/man/man3/strxfrm.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu) +.TH strxfrm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strxfrm \- string transformation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "size_t strxfrm(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strxfrm () +function transforms the +.I src +string into a +form such that the result of +.BR strcmp (3) +on two strings that have +been transformed with +.BR strxfrm () +is the same as the result of +.BR strcoll (3) +on the two strings before their transformation. +The first +.I n +bytes of the transformed string are placed in +.IR dest . +The transformation is based on the program's current +locale for category +.BR LC_COLLATE . +(See +.BR setlocale (3)). +.SH RETURN VALUE +The +.BR strxfrm () +function returns the number of bytes required to +store the transformed string in +.I dest +excluding the +terminating null byte (\[aq]\e0\[aq]). +If the value returned is +.I n +or more, the +contents of +.I dest +are indeterminate. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strxfrm () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3) diff --git a/man/man3/svc_destroy.3 b/man/man3/svc_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_freeargs.3 b/man/man3/svc_freeargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_freeargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getargs.3 b/man/man3/svc_getargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getcaller.3 b/man/man3/svc_getcaller.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getcaller.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getreq.3 b/man/man3/svc_getreq.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getreq.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getreqset.3 b/man/man3/svc_getreqset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getreqset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_register.3 b/man/man3/svc_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_run.3 b/man/man3/svc_run.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_run.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_sendreply.3 b/man/man3/svc_sendreply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_sendreply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_unregister.3 b/man/man3/svc_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_auth.3 b/man/man3/svcerr_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_decode.3 b/man/man3/svcerr_decode.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_decode.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_noproc.3 b/man/man3/svcerr_noproc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_noproc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_noprog.3 b/man/man3/svcerr_noprog.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_noprog.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_progvers.3 b/man/man3/svcerr_progvers.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_progvers.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_systemerr.3 b/man/man3/svcerr_systemerr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_systemerr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_weakauth.3 b/man/man3/svcerr_weakauth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_weakauth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcfd_create.3 b/man/man3/svcfd_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcfd_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcraw_create.3 b/man/man3/svcraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svctcp_create.3 b/man/man3/svctcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svctcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcudp_bufcreate.3 b/man/man3/svcudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcudp_create.3 b/man/man3/svcudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/swab.3 b/man/man3/swab.3 new file mode 100644 index 0000000..b263846 --- /dev/null +++ b/man/man3/swab.3 @@ -0,0 +1,76 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-12-15, aeb +.TH swab 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +swab \- swap adjacent bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <unistd.h> +.P +.BI "void swab(const void " from "[restrict ." n "], void " to "[restrict ." n ], +.BI " ssize_t " n ); +.fi +.SH DESCRIPTION +The +.BR swab () +function copies +.I n +bytes from the array pointed +to by +.I from +to the array pointed to by +.IR to , +exchanging +adjacent even and odd bytes. +This function is used to exchange data +between machines that have different low/high byte ordering. +.P +This function does nothing when +.I n +is negative. +When +.I n +is positive and odd, it handles +.I n\-1 +bytes +as above, and does something unspecified with the last byte. +(In other words, +.I n +should be even.) +.SH RETURN VALUE +The +.BR swab () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR swab () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3) diff --git a/man/man3/swapcontext.3 b/man/man3/swapcontext.3 new file mode 100644 index 0000000..cdccd64 --- /dev/null +++ b/man/man3/swapcontext.3 @@ -0,0 +1 @@ +.so man3/makecontext.3 diff --git a/man/man3/swprintf.3 b/man/man3/swprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/swprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/sys_errlist.3 b/man/man3/sys_errlist.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man/man3/sys_errlist.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man/man3/sys_nerr.3 b/man/man3/sys_nerr.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man/man3/sys_nerr.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man/man3/sys_siglist.3 b/man/man3/sys_siglist.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sys_siglist.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sysconf.3 b/man/man3/sysconf.3 new file mode 100644 index 0000000..2c269fd --- /dev/null +++ b/man/man3/sysconf.3 @@ -0,0 +1,390 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il) +.TH sysconf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysconf \- get configuration information at run time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "long sysconf(int " "name" ); +.fi +.SH DESCRIPTION +POSIX allows an application to test at compile or run time +whether certain options are supported, or what the value is +of certain configurable constants or limits. +.P +At compile time this is done by including +.I <unistd.h> +and/or +.I <limits.h> +and testing the value of certain macros. +.P +At run time, one can ask for numerical values using the present function +.BR sysconf (). +One can ask for numerical values that may depend +on the filesystem in which a file resides using +.BR fpathconf (3) +and +.BR pathconf (3). +One can ask for string values using +.BR confstr (3). +.P +The values obtained from these functions are system configuration constants. +They do not change during the lifetime of a process. +.\" except that sysconf(_SC_OPEN_MAX) may change answer after a call +.\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit +.P +For options, typically, there is a constant +.B _POSIX_FOO +that may be defined in +.IR <unistd.h> . +If it is undefined, one should ask at run time. +If it is defined to \-1, then the option is not supported. +If it is defined to 0, then relevant functions and headers exist, +but one has to ask at run time what degree of support is available. +If it is defined to a value other than \-1 or 0, then the option is +supported. +Usually the value (such as 200112L) indicates the year and month +of the POSIX revision describing the option. +glibc uses the value 1 +to indicate support as long as the POSIX revision has not been published yet. +.\" and 999 to indicate support for options no longer present in the latest +.\" standard. (?) +The +.BR sysconf () +argument will be +.BR _SC_FOO . +For a list of options, see +.BR posixoptions (7). +.P +For variables or limits, typically, there is a constant +.BR _FOO , +maybe defined in +.IR <limits.h> , +or +.BR _POSIX_FOO , +maybe defined in +.IR <unistd.h> . +The constant will not be defined if the limit is unspecified. +If the constant is defined, it gives a guaranteed value, and +a greater value might actually be supported. +If an application wants to take advantage of values which may change +between systems, a call to +.BR sysconf () +can be made. +The +.BR sysconf () +argument will be +.BR _SC_FOO . +.SS POSIX.1 variables +We give the name of the variable, the name of the +.BR sysconf () +argument used to inquire about its value, +and a short description. +.P +First, the POSIX.1 compatible values. +.\" [for the moment: only the things that are unconditionally present] +.\" .TP +.\" .BR AIO_LISTIO_MAX " - " _SC_AIO_LISTIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of I/O operations in a single list I/O call. +.\" Must not be less than _POSIX_AIO_LISTIO_MAX. +.\" .TP +.\" .BR AIO_MAX " - " _SC_AIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of outstanding asynchronous I/O operations. +.\" Must not be less than _POSIX_AIO_MAX. +.\" .TP +.\" .BR AIO_PRIO_DELTA_MAX " - " _SC_AIO_PRIO_DELTA_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" The maximum amount by which a process can decrease its +.\" asynchronous I/O priority level from its own scheduling priority. +.\" Must be nonnegative. +.TP +.BR ARG_MAX " - " _SC_ARG_MAX +The maximum length of the arguments to the +.BR exec (3) +family of functions. +Must not be less than +.B _POSIX_ARG_MAX +(4096). +.TP +.BR CHILD_MAX " - " _SC_CHILD_MAX +The maximum number of simultaneous processes per user ID. +Must not be less than +.B _POSIX_CHILD_MAX +(25). +.TP +.BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX +Maximum length of a hostname, not including the terminating null byte, +as returned by +.BR gethostname (2). +Must not be less than +.B _POSIX_HOST_NAME_MAX +(255). +.TP +.BR LOGIN_NAME_MAX " - " _SC_LOGIN_NAME_MAX +Maximum length of a login name, including the terminating null byte. +Must not be less than +.B _POSIX_LOGIN_NAME_MAX +(9). +.TP +.BR NGROUPS_MAX " - " _SC_NGROUPS_MAX +Maximum number of supplementary group IDs. +.TP +.BR "" "clock ticks - " _SC_CLK_TCK +The number of clock ticks per second. +The corresponding variable is obsolete. +It was of course called +.BR CLK_TCK . +(Note: the macro +.B CLOCKS_PER_SEC +does not give information: it must equal 1000000.) +.TP +.BR OPEN_MAX " - " _SC_OPEN_MAX +The maximum number of files that a process can have open at any time. +Must not be less than +.B _POSIX_OPEN_MAX +(20). +.TP +.BR PAGESIZE " - " _SC_PAGESIZE +Size of a page in bytes. +Must not be less than 1. +.TP +.BR PAGE_SIZE " - " _SC_PAGE_SIZE +A synonym for +.BR PAGESIZE / _SC_PAGESIZE . +(Both +.B PAGESIZE +and +.B PAGE_SIZE +are specified in POSIX.) +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The number of repeated occurrences of a BRE permitted by +.BR regexec (3) +and +.BR regcomp (3). +Must not be less than +.B _POSIX2_RE_DUP_MAX +(255). +.TP +.BR STREAM_MAX " - " _SC_STREAM_MAX +The maximum number of streams that a process can have open at any +time. +If defined, it has the same value as the standard C macro +.BR FOPEN_MAX . +Must not be less than +.B _POSIX_STREAM_MAX +(8). +.TP +.BR SYMLOOP_MAX " - " _SC_SYMLOOP_MAX +The maximum number of symbolic links seen in a pathname before resolution +returns +.BR ELOOP . +Must not be less than +.B _POSIX_SYMLOOP_MAX +(8). +.TP +.BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX +The maximum length of terminal device name, +including the terminating null byte. +Must not be less than +.B _POSIX_TTY_NAME_MAX +(9). +.TP +.BR TZNAME_MAX " - " _SC_TZNAME_MAX +The maximum number of bytes in a timezone name. +Must not be less than +.B _POSIX_TZNAME_MAX +(6). +.TP +.BR _POSIX_VERSION " - " _SC_VERSION +indicates the year and month the POSIX.1 standard was approved in the +format +.BR YYYYMML ; +the value +.B 199009L +indicates the Sept. 1990 revision. +.SS POSIX.2 variables +Next, the POSIX.2 values, giving limits for utilities. +.TP +.BR BC_BASE_MAX " - " _SC_BC_BASE_MAX +indicates the maximum +.I obase +value accepted by the +.BR bc (1) +utility. +.TP +.BR BC_DIM_MAX " - " _SC_BC_DIM_MAX +indicates the maximum value of elements permitted in an array by +.BR bc (1). +.TP +.BR BC_SCALE_MAX " - " _SC_BC_SCALE_MAX +indicates the maximum +.I scale +value allowed by +.BR bc (1). +.TP +.BR BC_STRING_MAX " - " _SC_BC_STRING_MAX +indicates the maximum length of a string accepted by +.BR bc (1). +.TP +.BR COLL_WEIGHTS_MAX " - " _SC_COLL_WEIGHTS_MAX +indicates the maximum numbers of weights that can be assigned to an +entry of the +.B LC_COLLATE order +keyword in the locale definition file. +.TP +.BR EXPR_NEST_MAX " - " _SC_EXPR_NEST_MAX +is the maximum number of expressions which can be nested within +parentheses by +.BR expr (1). +.TP +.BR LINE_MAX " - " _SC_LINE_MAX +The maximum length of a utility's input line, either from +standard input or from a file. +This includes space for a trailing +newline. +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression when +the interval notation +.B \e{m,n\e} +is used. +.TP +.BR POSIX2_VERSION " - " _SC_2_VERSION +indicates the version of the POSIX.2 standard in the format of +YYYYMML. +.TP +.BR POSIX2_C_DEV " - " _SC_2_C_DEV +indicates whether the POSIX.2 C language development facilities are +supported. +.TP +.BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV +indicates whether the POSIX.2 FORTRAN development utilities are +supported. +.TP +.BR POSIX2_FORT_RUN " - " _SC_2_FORT_RUN +indicates whether the POSIX.2 FORTRAN run-time utilities are supported. +.TP +.BR _POSIX2_LOCALEDEF " - " _SC_2_LOCALEDEF +indicates whether the POSIX.2 creation of locales via +.BR localedef (1) +is supported. +.TP +.BR POSIX2_SW_DEV " - " _SC_2_SW_DEV +indicates whether the POSIX.2 software development utilities option is +supported. +.P +These values also exist, but may not be standard. +.TP +.BR "" " - " _SC_PHYS_PAGES +The number of pages of physical memory. +Note that it is possible +for the product of this value and the value of +.B _SC_PAGESIZE +to overflow. +.TP +.BR "" " - " _SC_AVPHYS_PAGES +The number of currently available pages of physical memory. +.TP +.BR "" " - " _SC_NPROCESSORS_CONF +The number of processors configured. +See also +.BR get_nprocs_conf (3). +.TP +.BR "" " - " _SC_NPROCESSORS_ONLN +The number of processors currently online (available). +See also +.BR get_nprocs_conf (3). +.SH RETURN VALUE +The return value of +.BR sysconf () +is one of the following: +.IP \[bu] 3 +On error, \-1 is returned and +.I errno +is set to indicate the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP \[bu] +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP \[bu] +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP \[bu] +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I <unistd.h> +or +.I <limits.h> +when the application was compiled. +.SH ERRORS +.TP +.B EINVAL +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sysconf () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +It is difficult to use +.B ARG_MAX +because it is not specified how much of the argument space for +.BR exec (3) +is consumed by the user's environment variables. +.P +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR bc (1), +.BR expr (1), +.BR getconf (1), +.BR locale (1), +.BR confstr (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR posixoptions (7) diff --git a/man/man3/syslog.3 b/man/man3/syslog.3 new file mode 100644 index 0000000..e6b885b --- /dev/null +++ b/man/man3/syslog.3 @@ -0,0 +1,359 @@ +'\" t +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org> +.\" +.\" Updated 13 Oct 2001, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added description of vsyslog +.\" Added descriptions of LOG_ODELAY and LOG_NOWAIT +.\" Added brief description of facility and option arguments +.\" Added CONFORMING TO section +.\" 2001-10-13, aeb, minor changes +.\" Modified 13 Dec 2001, Martin Schulze <joey@infodrom.org> +.\" Modified 3 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH syslog 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +closelog, openlog, syslog, vsyslog \- send messages to the system logger +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <syslog.h> +.P +.BI "void openlog(const char *" ident ", int " option ", int " facility ); +.BI "void syslog(int " priority ", const char *" format ", ...);" +.B "void closelog(void);" +.P +.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vsyslog (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.SS openlog() +.BR openlog () +opens a connection to the system logger for a program. +.P +The string pointed to by +.I ident +is prepended to every message, and is typically set to the program name. +If +.I ident +is NULL, the program name is used. +(POSIX.1-2008 does not specify the behavior when +.I ident +is NULL.) +.P +The +.I option +argument specifies flags which control the operation of +.BR openlog () +and subsequent calls to +.BR syslog (). +The +.I facility +argument establishes a default to be used if +none is specified in subsequent calls to +.BR syslog (). +The values that may be specified for +.I option +and +.I facility +are described below. +.P +The use of +.BR openlog () +is optional; it will automatically be called by +.BR syslog () +if necessary, in which case +.I ident +will default to NULL. +.\" +.SS syslog() and vsyslog() +.BR syslog () +generates a log message, which will be distributed by +.BR syslogd (8). +.P +The +.I priority +argument is formed by ORing together a +.I facility +value and a +.I level +value (described below). +If no +.I facility +value is ORed into +.IR priority , +then the default value set by +.BR openlog () +is used, or, if there was no preceding +.BR openlog () +call, a default of +.B LOG_USER +is employed. +.P +The remaining arguments are a +.IR format , +as in +.BR printf (3), +and any arguments required by the +.IR format , +except that the two-character sequence +.B %m +will be replaced by +the error message string +.IR strerror ( errno ). +The format string need not include a terminating newline character. +.P +The function +.BR vsyslog () +performs the same task as +.BR syslog () +with the difference that it takes a set of arguments which have +been obtained using the +.BR stdarg (3) +variable argument list macros. +.\" +.SS closelog() +.BR closelog () +closes the file descriptor being used to write to the system logger. +The use of +.BR closelog () +is optional. +.\" +.SS Values for \fIoption\fP +The +.I option +argument to +.BR openlog () +is a bit mask constructed by ORing together any of the following values: +.TP 15 +.B LOG_CONS +Write directly to the system console if there is an error while sending to +the system logger. +.TP +.B LOG_NDELAY +Open the connection immediately (normally, the connection is opened when +the first message is logged). +This may be useful, for example, if a subsequent +.BR chroot (2) +would make the pathname used internally by the logging facility unreachable. +.TP +.B LOG_NOWAIT +Don't wait for child processes that may have been created while logging +the message. +(The GNU C library does not create a child process, so this +option has no effect on Linux.) +.TP +.B LOG_ODELAY +The converse of +.BR LOG_NDELAY ; +opening of the connection is delayed until +.BR syslog () +is called. +(This is the default, and need not be specified.) +.TP +.B LOG_PERROR +(Not in POSIX.1-2001 or POSIX.1-2008.) +Also log the message to +.IR stderr . +.TP +.B LOG_PID +Include the caller's PID with each message. +.\" +.SS Values for \fIfacility\fP +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP 15 +.B LOG_AUTH +security/authorization messages +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +system daemons without separate facility value +.TP +.B LOG_FTP +ftp daemon +.TP +.B LOG_KERN +kernel messages (these can't be generated from user processes) +.\" LOG_KERN has the value 0; if used as a facility, zero translates to: +.\" "use the default facility". +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.BR syslogd (8) +.TP +.BR LOG_USER " (default)" +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem +.\" +.SS Values for \fIlevel\fP +This determines the importance of the message. +The levels are, in order of decreasing importance: +.TP 15 +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.P +The function +.BR setlogmask (3) +can be used to restrict logging to specified levels only. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR openlog (), +.BR closelog () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR syslog (), +.BR vsyslog () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR syslog () +.TQ +.BR openlog () +.TQ +.BR closelog () +POSIX.1-2008. +.TP +.BR vsyslog () +None. +.SH HISTORY +.TP +.BR syslog () +4.2BSD, SUSv2, POSIX.1-2001. +.TP +.BR openlog () +.TQ +.BR closelog () +4.3BSD, SUSv2, POSIX.1-2001. +.\" .SH HISTORY +.\" 4.3BSD documents +.\" .BR setlogmask (). +.TP +.BR vsyslog () +4.3BSD-Reno. +.\" Of course early v* functions used the +.\" .I <varargs.h> +.\" mechanism, which is not compatible with +.\" .IR <stdarg.h> . +.P +POSIX.1-2001 specifies only the +.B LOG_USER +and +.B LOG_LOCAL* +values for +.IR facility . +However, with the exception of +.B LOG_AUTHPRIV +and +.BR LOG_FTP , +the other +.I facility +values appear on most UNIX systems. +.P +The +.B LOG_PERROR +value for +.I option +is not specified by POSIX.1-2001 or POSIX.1-2008, but is available +in most versions of UNIX. +.SH NOTES +The argument +.I ident +in the call of +.BR openlog () +is probably stored as-is. +Thus, if the string it points to +is changed, +.BR syslog () +may start prepending the changed string, and if the string +it points to ceases to exist, the results are undefined. +Most portable is to use a string constant. +.P +Never pass a string with user-supplied data as a format, +use the following instead: +.P +.in +4n +.EX +syslog(priority, "%s", string); +.EE +.in +.SH SEE ALSO +.BR journalctl (1), +.BR logger (1), +.BR setlogmask (3), +.BR syslog.conf (5), +.BR syslogd (8) diff --git a/man/man3/system.3 b/man/man3/system.3 new file mode 100644 index 0000000..8a00ba8 --- /dev/null +++ b/man/man3/system.3 @@ -0,0 +1,269 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 14 May 2001, 23 Sep 2001 by aeb +.\" 2004-12-20, mtk +.\" +.TH system 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +system \- execute a shell command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int system(const char *" "command" ); +.fi +.SH DESCRIPTION +The +.BR system () +library function behaves as if it used +.BR fork (2) +to create a child process that executed the shell command specified in +.I command +using +.BR execl (3) +as follows: +.P +.in +4n +.EX +execl("/bin/sh", "sh", "\-c", command, (char *) NULL); +.EE +.in +.P +.BR system () +returns after the command has been completed. +.P +During execution of the command, +.B SIGCHLD +will be blocked, and +.B SIGINT +and +.B SIGQUIT +will be ignored, in the process that calls +.BR system (). +(These signals will be handled according to their defaults inside +the child process that executes +.IR command .) +.P +If +.I command +is NULL, then +.BR system () +returns a status indicating whether a shell is available on the system. +.SH RETURN VALUE +The return value of +.BR system () +is one of the following: +.IP \[bu] 3 +If +.I command +is NULL, then a nonzero value if a shell is available, +or 0 if no shell is available. +.IP \[bu] +If a child process could not be created, +or its status could not be retrieved, +the return value is \-1 and +.I errno +is set to indicate the error. +.IP \[bu] +If a shell could not be executed in the child process, +then the return value is as though the child shell terminated by calling +.BR _exit (2) +with the status 127. +.IP \[bu] +If all system calls succeed, +then the return value is the termination status of the child shell +used to execute +.IR command . +(The termination status of a shell is the termination status of +the last command it executes.) +.P +In the last two cases, +the return value is a "wait status" that can be examined using +the macros described in +.BR waitpid (2). +(i.e., +.BR WIFEXITED (), +.BR WEXITSTATUS (), +and so on). +.P +.BR system () +does not affect the wait status of any other children. +.SH ERRORS +.BR system () +can fail with any of the same errors as +.BR fork (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR system () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH NOTES +.BR system () +provides simplicity and convenience: +it handles all of the details of calling +.BR fork (2), +.BR execl (3), +and +.BR waitpid (2), +as well as the necessary manipulations of signals; +in addition, +the shell performs the usual substitutions and I/O redirections for +.IR command . +The main cost of +.BR system () +is inefficiency: +additional system calls are required to create the process that +runs the shell and to execute the shell. +.P +If the +.B _XOPEN_SOURCE +feature test macro is defined +(before including +.I any +header files), +then the macros described in +.BR waitpid (2) +.RB ( WEXITSTATUS (), +etc.) are made available when including +.IR <stdlib.h> . +.P +As mentioned, +.BR system () +ignores +.B SIGINT +and +.BR SIGQUIT . +This may make programs that call it +from a loop uninterruptible, unless they take care themselves +to check the exit status of the child. +For example: +.P +.in +4n +.EX +while (something) { + int ret = system("foo"); +\& + if (WIFSIGNALED(ret) && + (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) + break; +} +.EE +.in +.P +According to POSIX.1, it is unspecified whether handlers registered using +.BR pthread_atfork (3) +are called during the execution of +.BR system (). +In the glibc implementation, such handlers are not called. +.P +Before glibc 2.1.3, the check for the availability of +.I /bin/sh +was not actually performed if +.I command +was NULL; instead it was always assumed to be available, and +.BR system () +always returned 1 in this case. +Since glibc 2.1.3, this check is performed because, even though +POSIX.1-2001 requires a conforming implementation to provide +a shell, that shell may not be available or executable if +the calling program has previously called +.BR chroot (2) +(which is not specified by POSIX.1-2001). +.P +It is possible for the shell command to terminate with a status of 127, +which yields a +.BR system () +return value that is indistinguishable from the case +where a shell could not be executed in the child process. +.\" +.SS Caveats +Do not use +.BR system () +from a privileged program +(a set-user-ID or set-group-ID program, or a program with capabilities) +because strange values for some environment variables +might be used to subvert system integrity. +For example, +.B PATH +could be manipulated so that an arbitrary program +is executed with privilege. +Use the +.BR exec (3) +family of functions instead, but not +.BR execlp (3) +or +.BR execvp (3) +(which also use the +.B PATH +environment variable to search for an executable). +.P +.BR system () +will not, in fact, work properly from programs with set-user-ID or +set-group-ID privileges on systems on which +.I /bin/sh +is bash version 2: as a security measure, bash 2 drops privileges on startup. +(Debian uses a different shell, +.BR dash (1), +which does not do this when invoked as +.BR sh .) +.P +Any user input that is employed as part of +.I command +should be +.I carefully +sanitized, to ensure that unexpected shell commands or command options +are not executed. +Such risks are especially grave when using +.BR system () +from a privileged program. +.SH BUGS +.\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029) +.\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143) +.\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440) +If the command name starts with a hyphen, +.BR sh (1) +interprets the command name as an option, +and the behavior is undefined. +(See the +.B \-c +option to +.BR sh (1).) +To work around this problem, +prepend the command with a space as in the following call: +.P +.in +4n +.EX + system(" \-unfortunate\-command\-name"); +.EE +.in +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR fork (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR wait (2), +.BR exec (3), +.BR signal (7) diff --git a/man/man3/sysv_signal.3 b/man/man3/sysv_signal.3 new file mode 100644 index 0000000..fcdfa6b --- /dev/null +++ b/man/man3/sysv_signal.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sysv_signal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysv_signal \- signal handling with System V semantics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <signal.h> +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler ); +.fi +.SH DESCRIPTION +The +.BR sysv_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.P +However +.BR sysv_signal () +provides the System V unreliable signal semantics, that is: +a) the disposition of the signal is reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is not blocked while +the signal handler is executing; and +c) if the handler interrupts (certain) blocking system calls, +then the system call is not automatically restarted. +.SH RETURN VALUE +The +.BR sysv_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sysv_signal () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use of +.BR sysv_signal () +should be avoided; use +.BR sigaction (2) +instead. +.P +On older Linux systems, +.BR sysv_signal () +and +.BR signal (2) +were equivalent. +But on newer systems, +.BR signal (2) +provides reliable signal semantics; see +.BR signal (2) +for details. +.P +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if +the +.B _GNU_SOURCE +feature test macro is defined. +.SH STANDARDS +None. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR bsd_signal (3), +.BR signal (7) diff --git a/man/man3/tailq.3 b/man/man3/tailq.3 new file mode 100644 index 0000000..45899a6 --- /dev/null +++ b/man/man3/tailq.3 @@ -0,0 +1,397 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH TAILQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +TAILQ_CONCAT, +TAILQ_EMPTY, +TAILQ_ENTRY, +TAILQ_FIRST, +TAILQ_FOREACH, +.\"TAILQ_FOREACH_FROM, +.\"TAILQ_FOREACH_FROM_SAFE, +TAILQ_FOREACH_REVERSE, +.\"TAILQ_FOREACH_REVERSE_FROM, +.\"TAILQ_FOREACH_REVERSE_FROM_SAFE, +.\"TAILQ_FOREACH_REVERSE_SAFE, +.\"TAILQ_FOREACH_SAFE, +TAILQ_HEAD, +TAILQ_HEAD_INITIALIZER, +TAILQ_INIT, +TAILQ_INSERT_AFTER, +TAILQ_INSERT_BEFORE, +TAILQ_INSERT_HEAD, +TAILQ_INSERT_TAIL, +TAILQ_LAST, +TAILQ_NEXT, +TAILQ_PREV, +TAILQ_REMOVE +.\"TAILQ_SWAP +\- implementation of a doubly linked tail queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/queue.h> +.P +.B TAILQ_ENTRY(TYPE); +.P +.B TAILQ_HEAD(HEADNAME, TYPE); +.BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head ); +.BI "void TAILQ_INIT(TAILQ_HEAD *" head ); +.P +.BI "int TAILQ_EMPTY(TAILQ_HEAD *" head ); +.P +.BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_BEFORE(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.P +.BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head ); +.BI "struct TYPE *TAILQ_LAST(TAILQ_HEAD *" head ", HEADNAME);" +.BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME ); +.BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.P +.BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head , +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME ); +.BI "TAILQ_FOREACH_REVERSE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME," +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME," +.\" .BI " TAILQ_ENTRY " NAME ); +.\" .P +.\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_REVERSE_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " HEADNAME, TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " HEADNAME, TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.P +.BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm , +.BI " TAILQ_ENTRY " NAME ); +.P +.BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 , +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE," +.\" .BI " TAILQ_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked tail queues. +.P +In the macro definitions, +.I TYPE +is the name of a user defined structure, +that must contain a field of type +.IR TAILQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user defined structure that must be declared +using the macro +.BR TAILQ_HEAD (). +.SS Creation +A tail queue is headed by a structure defined by the +.BR TAILQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the queue +and the other to the last element in the queue. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the queue. +New elements can be added to the queue +after an existing element, +before an existing element, +at the head of the queue, +or at the end of the queue. +A +.I TAILQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +TAILQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the queue. +A pointer to the head of the queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR TAILQ_ENTRY () +declares a structure that connects the elements in the queue. +.P +.BR TAILQ_HEAD_INITIALIZER () +evaluates to an initializer for the queue +.IR head . +.P +.BR TAILQ_INIT () +initializes the queue referenced by +.P +.BR TAILQ_EMPTY () +evaluates to true if there are no items on the queue. +.IR head . +.SS Insertion +.BR TAILQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the queue. +.P +.BR TAILQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the queue. +.P +.BR TAILQ_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR TAILQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR TAILQ_FIRST () +returns the first item on the queue, or NULL if the queue is empty. +.P +.BR TAILQ_LAST () +returns the last item on the queue. +If the queue is empty the return value is NULL. +.P +.BR TAILQ_PREV () +returns the previous item on the queue, or NULL if this item is the first. +.P +.BR TAILQ_NEXT () +returns the next item on the queue, or NULL if this item is the last. +.P +.BR TAILQ_FOREACH () +traverses the queue referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.I var +is set to NULL if the loop completes normally, +or if there were no elements. +.\" .P +.\" .BR TAILQ_FOREACH_FROM () +.\" behaves identically to +.\" .BR TAILQ_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the TAILQ referenced by +.\" .IR head . +.P +.BR TAILQ_FOREACH_REVERSE () +traverses the queue referenced by +.I head +in the reverse direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR TAILQ_FOREACH_REVERSE_FROM () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_REVERSE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .I var +.\" instead of the last element in the TAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR TAILQ_FOREACH_SAFE () +.\" and +.\" .BR TAILQ_FOREACH_REVERSE_SAFE () +.\" traverse the list referenced by +.\" .I head +.\" in the forward or reverse direction respectively, +.\" assigning each element in turn to +.\" .IR var . +.\" However, unlike their unsafe counterparts, +.\" .BR TAILQ_FOREACH () +.\" and +.\" .BR TAILQ_FOREACH_REVERSE () +.\" permit to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR TAILQ_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the TAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR TAILQ_FOREACH_REVERSE_FROM_SAFE () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_REVERSE_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .I var +.\" instead of the last element in the TAILQ referenced by +.\" .IR head . +.SS Removal +.BR TAILQ_REMOVE () +removes the element +.I elm +from the queue. +.SS Other features +.\" .BR TAILQ_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.\" .P +.BR TAILQ_CONCAT () +concatenates the queue headed by +.I head2 +onto the end of the one headed by +.I head1 +removing all entries from the former. +.SH RETURN VALUE +.BR TAILQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR TAILQ_FIRST (), +.BR TAILQ_LAST (), +.BR TAILQ_PREV (), +and +.BR TAILQ_NEXT () +return a pointer to the first, last, previous, or next +.I TYPE +structure, respectively. +.P +.BR TAILQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH CAVEATS +.BR TAILQ_FOREACH () +and +.BR TAILQ_FOREACH_REVERSE () +don't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR TAILQ_FOREACH_SAFE () +and +.BR TAILQ_FOREACH_REVERSE_SAFE (), +which are present on the BSDs but are not present in glibc, +fix this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (tailq.c) +.EX +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/queue.h> +\& +struct entry { + int data; + TAILQ_ENTRY(entry) entries; /* Tail queue */ +}; +\& +TAILQ_HEAD(tailhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct tailhead head; /* Tail queue head */ + int i; +\& + TAILQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + TAILQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + TAILQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + TAILQ_INSERT_AFTER(&head, n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + TAILQ_INSERT_BEFORE(n2, n3, entries); +\& + TAILQ_REMOVE(&head, n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + i = 0; + TAILQ_FOREACH(np, &head, entries) + np\->data = i++; + /* Reverse traversal */ + TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + printf("%i\en", np\->data); + /* TailQ deletion */ + n1 = TAILQ_FIRST(&head); + while (n1 != NULL) { + n2 = TAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + TAILQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/tan.3 b/man/man3/tan.3 new file mode 100644 index 0000000..738a052 --- /dev/null +++ b/man/man3/tan.3 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH tan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tan, tanf, tanl \- tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double tan(double " x ); +.BI "float tanf(float " x ); +.BI "long double tanl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tanf (), +.BR tanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the tangent of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If the correct result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.\" I think overflow can't occur, because the closest floating-point +.\" representation of pi/2 is still not close enough to pi/2 to +.\" produce a large enough value to overflow. +.\" Testing certainly seems to bear this out. -- mtk, Jul 08 +.\" +.\" POSIX.1 allows an optional underflow error; +.\" glibc 2.8 doesn't do this +.\" POSIX.1 an optional range error for subnormal x; +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" Unable to test this case, since the best approximation of +.\" pi/2 in double precision only yields a tan() value of 1.633e16. +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tan (), +.BR tanf (), +.BR tanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6782 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR ctan (3), +.BR sin (3) diff --git a/man/man3/tanf.3 b/man/man3/tanf.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man/man3/tanf.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man/man3/tanh.3 b/man/man3/tanh.3 new file mode 100644 index 0000000..08a7a29 --- /dev/null +++ b/man/man3/tanh.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH tanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tanh, tanhf, tanhl \- hyperbolic tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double tanh(double " x ); +.BI "float tanhf(float " x ); +.BI "long double tanhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tanhf (), +.BR tanhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic tangent of +.IR x , +which +is defined mathematically as: +.P +.nf + tanh(x) = sinh(x) / cosh(x) +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tanh (), +.BR tanhf (), +.BR tanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR ctanh (3), +.BR sinh (3) diff --git a/man/man3/tanhf.3 b/man/man3/tanhf.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man/man3/tanhf.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man/man3/tanhl.3 b/man/man3/tanhl.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man/man3/tanhl.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man/man3/tanl.3 b/man/man3/tanl.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man/man3/tanl.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man/man3/tcdrain.3 b/man/man3/tcdrain.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcdrain.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcflow.3 b/man/man3/tcflow.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcflow.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcflush.3 b/man/man3/tcflush.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcflush.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcgetattr.3 b/man/man3/tcgetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcgetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcgetpgrp.3 b/man/man3/tcgetpgrp.3 new file mode 100644 index 0000000..b29c9ab --- /dev/null +++ b/man/man3/tcgetpgrp.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tcgetpgrp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <unistd.h>" +.P +.BI "pid_t tcgetpgrp(int " fd ); +.BI "int tcsetpgrp(int " fd ", pid_t " pgrp ); +.fi +.SH DESCRIPTION +The function +.BR tcgetpgrp () +returns the process group ID of the foreground process group on the +terminal associated to +.IR fd , +which must be the controlling terminal of the calling process. +.\" The process itself may be a background process. +.P +The function +.BR tcsetpgrp () +makes the process group with process group ID +.I pgrp +the foreground process group on the terminal associated to +.IR fd , +which must be the controlling terminal of the calling process, +and still be associated with its session. +Moreover, +.I pgrp +must be a (nonempty) process group belonging to +the same session as the calling process. +.P +If +.BR tcsetpgrp () +is called by a member of a background process group in its session, +and the calling process is not blocking or ignoring +.BR SIGTTOU , +a +.B SIGTTOU +signal is sent to all members of this background process group. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of the calling process, +the function +.BR tcgetpgrp () +will return the foreground process group ID of that terminal +if there is one, and some value larger than 1 that is not +presently a process group ID otherwise. +When +.I fd +does not refer to the controlling terminal of the calling process, +\-1 is returned, and +.I errno +is set to indicate the error. +.P +When successful, +.BR tcsetpgrp () +returns 0. +Otherwise, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I pgrp +has an unsupported value. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd , +or, for +.BR tcsetpgrp (), +this controlling terminal is no longer associated with the session +of the calling process. +.TP +.B EPERM +.I pgrp +has a supported value, but is not the process group ID of a +process in the same session as the calling process. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetpgrp (), +.BR tcsetpgrp () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are implemented via the +.B TIOCGPGRP +and +.B TIOCSPGRP +ioctls. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +The ioctls appeared in 4.2BSD. +The functions are POSIX inventions. +.SH SEE ALSO +.BR setpgid (2), +.BR setsid (2), +.BR credentials (7) diff --git a/man/man3/tcgetsid.3 b/man/man3/tcgetsid.3 new file mode 100644 index 0000000..a8925f7 --- /dev/null +++ b/man/man3/tcgetsid.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tcgetsid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tcgetsid \- get session ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */" +.B "#include <termios.h>" +.P +.BI "pid_t tcgetsid(int " fd ); +.fi +.SH DESCRIPTION +The function +.BR tcgetsid () +returns the session ID of the current session that has the +terminal associated to +.I fd +as controlling terminal. +This terminal must be the controlling terminal of the calling process. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of our session, +the function +.BR tcgetsid () +will return the session ID of this session. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetsid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +This function is implemented via the +.B TIOCGSID +.BR ioctl (2), +present +since Linux 2.1.71. +.SH SEE ALSO +.BR getsid (2) diff --git a/man/man3/tcsendbreak.3 b/man/man3/tcsendbreak.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcsendbreak.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcsetattr.3 b/man/man3/tcsetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcsetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcsetpgrp.3 b/man/man3/tcsetpgrp.3 new file mode 100644 index 0000000..1a8b360 --- /dev/null +++ b/man/man3/tcsetpgrp.3 @@ -0,0 +1 @@ +.so man3/tcgetpgrp.3 diff --git a/man/man3/tdelete.3 b/man/man3/tdelete.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tdelete.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tdestroy.3 b/man/man3/tdestroy.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tdestroy.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/telldir.3 b/man/man3/telldir.3 new file mode 100644 index 0000000..90ae1f3 --- /dev/null +++ b/man/man3/telldir.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu) +.TH telldir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +telldir \- return current location in directory stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "long telldir(DIR *" dirp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR telldir (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR telldir () +function returns the current location associated with +the directory stream \fIdirp\fP. +.SH RETURN VALUE +On success, the +.BR telldir () +function returns the current location +in the directory stream. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR telldir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Up to glibc 2.1.1, the return type of +.BR telldir () +was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +.P +In early filesystems, the value returned by +.BR telldir () +was a simple file offset within a directory. +Modern filesystems use tree or hash structures, rather than flat tables, +to represent directories. +On such filesystems, the value returned by +.BR telldir () +(and used internally by +.BR readdir (3)) +is a "cookie" that is used by the implementation +to derive a position within a directory. +.\" https://lwn.net/Articles/544298/ +Application programs should treat this strictly as an opaque value, making +.I no +assumptions about its contents. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3) diff --git a/man/man3/tempnam.3 b/man/man3/tempnam.3 new file mode 100644 index 0000000..3f9baca --- /dev/null +++ b/man/man3/tempnam.3 @@ -0,0 +1,175 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tempnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tempnam \- create a name for a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "char *tempnam(const char *" dir ", const char *" pfx ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tempnam (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.I "Never use this function." +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.P +The +.BR tempnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist when +.BR tempnam () +checked. +The filename suffix of the pathname generated will start with +.I pfx +in case +.I pfx +is a non-NULL string of at most five bytes. +The directory prefix part of the pathname generated is required to +be "appropriate" (often that at least implies writable). +.P +Attempts to find an appropriate directory go through the following +steps: +.TP 3 +a) +In case the environment variable +.B TMPDIR +exists and +contains the name of an appropriate directory, that is used. +.TP +b) +Otherwise, if the +.I dir +argument is non-NULL and appropriate, it is used. +.TP +c) +Otherwise, +.I P_tmpdir +(as defined in +.IR <stdio.h> ) +is used when appropriate. +.TP +d) +Finally an implementation-defined directory may be used. +.P +The string returned by +.BR tempnam () +is allocated using +.BR malloc (3) +and hence should be freed by +.BR free (3). +.SH RETURN VALUE +On success, the +.BR tempnam () +function returns a pointer to a unique temporary filename. +It returns NULL if a unique name cannot be generated, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Allocation of storage failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tempnam () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +Obsoleted in POSIX.1-2008. +.SH NOTES +Although +.BR tempnam () +generates names that are difficult to guess, +it is nevertheless possible that between the time that +.BR tempnam () +returns a pathname, and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.P +SUSv2 does not mention the use of +.BR TMPDIR ; +glibc will use it only +when the program is not set-user-ID. +On SVr4, the directory used under \fBd)\fP is +.I /tmp +(and this is what glibc does). +.P +Because it dynamically allocates memory used to return the pathname, +.BR tempnam () +is reentrant, and thus thread safe, unlike +.BR tmpnam (3). +.P +The +.BR tempnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +(defined in +.IR <stdio.h> ) +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.P +.BR tempnam () +uses at most the first five bytes from +.IR pfx . +.P +The glibc implementation of +.BR tempnam () +fails with the error +.B EEXIST +upon failure to find a unique name. +.SH BUGS +The precise meaning of "appropriate" is undefined; +it is unspecified how accessibility of a directory is determined. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/termios.3 b/man/man3/termios.3 new file mode 100644 index 0000000..932cfb4 --- /dev/null +++ b/man/man3/termios.3 @@ -0,0 +1,1235 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" Copyright (c) 2006-2015, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" moved to man3, aeb, 950919 +.\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 2001-12-17, aeb +.\" Modified 2004-10-31, aeb +.\" 2006-12-28, mtk: +.\" Added .SS headers to give some structure to this page; and a +.\" small amount of reordering. +.\" Added a section on canonical and noncanonical mode. +.\" Enhanced the discussion of "raw" mode for cfmakeraw(). +.\" Document CMSPAR. +.\" +.TH termios 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, +cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- +get and set terminal attributes, line control, get and set baud rate +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <termios.h> +.B #include <unistd.h> +.P +.BI "int tcgetattr(int " fd ", struct termios *" termios_p ); +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.P +.BI "int tcsendbreak(int " fd ", int " duration ); +.BI "int tcdrain(int " fd ); +.BI "int tcflush(int " fd ", int " queue_selector ); +.BI "int tcflow(int " fd ", int " action ); +.P +.BI "void cfmakeraw(struct termios *" termios_p ); +.P +.BI "speed_t cfgetispeed(const struct termios *" termios_p ); +.BI "speed_t cfgetospeed(const struct termios *" termios_p ); +.P +.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cfsetspeed (), +.BR cfmakeraw (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The termios functions describe a general terminal interface that is +provided to control asynchronous communications ports. +.SS The termios structure +Many of the functions described here have a \fItermios_p\fP argument +that is a pointer to a \fItermios\fP structure. +This structure contains at least the following members: +.P +.in +4n +.EX +tcflag_t c_iflag; /* input modes */ +tcflag_t c_oflag; /* output modes */ +tcflag_t c_cflag; /* control modes */ +tcflag_t c_lflag; /* local modes */ +cc_t c_cc[NCCS]; /* special characters */ +.EE +.in +.P +The values that may be assigned to these fields are described below. +In the case of the first four bit-mask fields, +the definitions of some of the associated flags that may be set are +exposed only if a specific feature test macro (see +.BR feature_test_macros (7)) +is defined, as noted in brackets ("[]"). +.P +In the descriptions below, "not in POSIX" means that the +value is not specified in POSIX.1-2001, +and "XSI" means that the value is specified in POSIX.1-2001 +as part of the XSI extension. +.P +\fIc_iflag\fP flag constants: +.TP +.B IGNBRK +Ignore BREAK condition on input. +.TP +.B BRKINT +If \fBIGNBRK\fP is set, a BREAK is ignored. +If it is not set +but \fBBRKINT\fP is set, then a BREAK causes the input and output +queues to be flushed, and if the terminal is the controlling +terminal of a foreground process group, it will cause a +\fBSIGINT\fP to be sent to this foreground process group. +When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK +reads as a null byte (\[aq]\e0\[aq]), except when \fBPARMRK\fP is set, +in which case it reads as the sequence \e377 \e0 \e0. +.TP +.B IGNPAR +Ignore framing errors and parity errors. +.TP +.B PARMRK +If this bit is set, input bytes with parity or framing errors are +marked when passed to the program. +This bit is meaningful only when +\fBINPCK\fP is set and \fBIGNPAR\fP is not set. +The way erroneous bytes are marked is with two preceding bytes, +\e377 and \e0. +Thus, the program actually reads three bytes for one +erroneous byte received from the terminal. +If a valid byte has the value \e377, +and \fBISTRIP\fP (see below) is not set, +the program might confuse it with the prefix that marks a +parity error. +Therefore, a valid byte \e377 is passed to the program as two +bytes, \e377 \e377, in this case. +.IP +If neither \fBIGNPAR\fP nor \fBPARMRK\fP +is set, read a character with a parity error or framing error +as \e0. +.TP +.B INPCK +Enable input parity checking. +.TP +.B ISTRIP +Strip off eighth bit. +.TP +.B INLCR +Translate NL to CR on input. +.TP +.B IGNCR +Ignore carriage return on input. +.TP +.B ICRNL +Translate carriage return to newline on input (unless \fBIGNCR\fP is set). +.TP +.B IUCLC +(not in POSIX) Map uppercase characters to lowercase on input. +.TP +.B IXON +Enable XON/XOFF flow control on output. +.TP +.B IXANY +(XSI) Typing any character will restart stopped output. +(The default is to allow just the START character to restart output.) +.TP +.B IXOFF +Enable XON/XOFF flow control on input. +.TP +.B IMAXBEL +(not in POSIX) Ring bell when input queue is full. +Linux does not implement this bit, and acts as if it is always set. +.TP +.BR IUTF8 " (since Linux 2.6.4)" +(not in POSIX) Input is UTF8; +this allows character-erase to be correctly performed in cooked mode. +.P +.I c_oflag +flag constants: +.TP +.B OPOST +Enable implementation-defined output processing. +.TP +.B OLCUC +(not in POSIX) Map lowercase characters to uppercase on output. +.TP +.B ONLCR +(XSI) Map NL to CR-NL on output. +.TP +.B OCRNL +Map CR to NL on output. +.TP +.B ONOCR +Don't output CR at column 0. +.TP +.B ONLRET +The NL character is assumed to do the carriage-return function; +the kernel's idea of the current column is set to 0 +after both NL and CR. +.TP +.B OFILL +Send fill characters for a delay, rather than using a timed delay. +.TP +.B OFDEL +Fill character is ASCII DEL (0177). +If unset, fill character is ASCII NUL (\[aq]\e0\[aq]). +(Not implemented on Linux.) +.TP +.B NLDLY +Newline delay mask. +Values are \fBNL0\fP and \fBNL1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B CRDLY +Carriage return delay mask. +Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B TABDLY +Horizontal tab delay mask. +Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP, +but see the +.B BUGS +section). +A value of TAB3, that is, XTABS, expands tabs to spaces +(with tab stops every eight columns). +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B BSDLY +Backspace delay mask. +Values are \fBBS0\fP or \fBBS1\fP. +(Has never been implemented.) +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B VTDLY +Vertical tab delay mask. +Values are \fBVT0\fP or \fBVT1\fP. +.TP +.B FFDLY +Form feed delay mask. +Values are \fBFF0\fP or \fBFF1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.P +\fIc_cflag\fP flag constants: +.TP +.B CBAUD +(not in POSIX) Baud speed mask (4+1 bits). +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CBAUDEX +(not in POSIX) Extra baud speed mask (1 bit), included in +.BR CBAUD . +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.IP +(POSIX says that the baud speed is stored in the +.I termios +structure without specifying where precisely, and provides +.BR cfgetispeed () +and +.BR cfsetispeed () +for getting at it. +Some systems use bits selected by +.B CBAUD +in +.IR c_cflag , +other systems use separate fields, for example, +.I sg_ispeed +and +.IR sg_ospeed .) +.TP +.B CSIZE +Character size mask. +Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. +.TP +.B CSTOPB +Set two stop bits, rather than one. +.TP +.B CREAD +Enable receiver. +.TP +.B PARENB +Enable parity generation on output and parity checking for input. +.TP +.B PARODD +If set, then parity for input and output is odd; +otherwise even parity is used. +.TP +.B HUPCL +Lower modem control lines after last process closes the device (hang up). +.TP +.B CLOCAL +Ignore modem control lines. +.TP +.B LOBLK +(not in POSIX) Block output from a noncurrent shell layer. +For use by \fBshl\fP (shell layers). +(Not implemented on Linux.) +.TP +.B CIBAUD +(not in POSIX) Mask for input speeds. +The values for the +.B CIBAUD +bits are +the same as the values for the +.B CBAUD +bits, shifted left +.B IBSHIFT +bits. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +(Not implemented in glibc, supported on Linux via +.BR TCGET * +and +.BR TCSET * +ioctls; see +.BR ioctl_tty (2)) +.TP +.B CMSPAR +(not in POSIX) +Use "stick" (mark/space) parity (supported on certain serial +devices): if +.B PARODD +is set, the parity bit is always 1; if +.B PARODD +is not set, then the parity bit is always 0. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CRTSCTS +(not in POSIX) Enable RTS/CTS (hardware) flow control. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.P +\fIc_lflag\fP flag constants: +.TP +.B ISIG +When any of the characters INTR, QUIT, SUSP, or DSUSP are received, +generate the corresponding signal. +.TP +.B ICANON +Enable canonical mode (described below). +.TP +.B XCASE +(not in POSIX; not supported under Linux) +If \fBICANON\fP is also set, terminal is uppercase only. +Input is converted to lowercase, except for characters preceded by \e. +On output, uppercase characters are preceded by \e and lowercase +characters are converted to uppercase. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.\" glibc is probably now wrong to allow +.\" Define +.\" .B _XOPEN_SOURCE +.\" to expose +.\" .BR XCASE . +.TP +.B ECHO +Echo input characters. +.TP +.B ECHOE +If \fBICANON\fP is also set, the ERASE character erases the preceding +input character, and WERASE erases the preceding word. +.TP +.B ECHOK +If \fBICANON\fP is also set, the KILL character erases the current line. +.TP +.B ECHONL +If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. +.TP +.B ECHOCTL +(not in POSIX) If \fBECHO\fP is also set, +terminal special characters other than +TAB, NL, START, and STOP are echoed as \fB\[ha]X\fP, +where X is the character with +ASCII code 0x40 greater than the special character. +For example, character +0x08 (BS) is echoed as \fB\[ha]H\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOPRT +(not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters +are printed as they are being erased. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOKE +(not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing +each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B DEFECHO +(not in POSIX) Echo only when a process is reading. +(Not implemented on Linux.) +.TP +.B FLUSHO +(not in POSIX; not supported under Linux) +Output is being flushed. +This flag is toggled by typing +the DISCARD character. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B NOFLSH +Disable flushing the input and output queues when generating signals for the +INT, QUIT, and SUSP characters. +.\" Stevens lets SUSP only flush the input queue +.TP +.B TOSTOP +Send the +.B SIGTTOU +signal to the process group of a background process +which tries to write to its controlling terminal. +.TP +.B PENDIN +(not in POSIX; not supported under Linux) +All characters in the input queue are reprinted when +the next character is read. +.RB ( bash (1) +handles typeahead this way.) +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B IEXTEN +Enable implementation-defined input processing. +This flag, as well as \fBICANON\fP must be enabled for the +special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, +and for the \fBIUCLC\fP flag to be effective. +.P +The \fIc_cc\fP array defines the terminal special characters. +The symbolic indices (initial values) and meaning are: +.TP +.B VDISCARD +(not in POSIX; not supported under Linux; 017, SI, Ctrl-O) +Toggle: start/stop discarding pending output. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VDSUSP +(not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) +Delayed suspend character (DSUSP): +send +.B SIGTSTP +signal when the character is read by the user program. +Recognized when +.B IEXTEN +and +.B ISIG +are set, and the system supports +job control, and then not passed as input. +.TP +.B VEOF +(004, EOT, Ctrl-D) +End-of-file character (EOF). +More precisely: this character causes the pending tty buffer to be sent +to the waiting user program without waiting for end-of-line. +If it is the first character of the line, the +.BR read (2) +in the user program returns 0, which signifies end-of-file. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VEOL +(0, NUL) +Additional end-of-line character (EOL). +Recognized when +.B ICANON +is set. +.TP +.B VEOL2 +(not in POSIX; 0, NUL) +Yet another end-of-line character (EOL2). +Recognized when +.B ICANON +is set. +.TP +.B VERASE +(0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) +Erase character (ERASE). +This erases the previous not-yet-erased character, +but does not erase past EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VINTR +(003, ETX, Ctrl-C, or also 0177, DEL, rubout) +Interrupt character (INTR). +Send a +.B SIGINT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VKILL +(025, NAK, Ctrl-U, or Ctrl-X, or also @) +Kill character (KILL). +This erases the input since the last EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VLNEXT +(not in POSIX; 026, SYN, Ctrl-V) +Literal next (LNEXT). +Quotes the next input character, depriving it of +a possible special meaning. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VMIN +Minimum number of characters for noncanonical read (MIN). +.TP +.B VQUIT +(034, FS, Ctrl-\e) +Quit character (QUIT). +Send +.B SIGQUIT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VREPRINT +(not in POSIX; 022, DC2, Ctrl-R) +Reprint unread characters (REPRINT). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.TP +.B VSTART +(021, DC1, Ctrl-Q) +Start character (START). +Restarts output stopped by the Stop character. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSTATUS +(not in POSIX; not supported under Linux; +status request: 024, DC4, Ctrl-T). +Status character (STATUS). +Display status information at terminal, +including state of foreground process and amount of CPU time it has consumed. +Also sends a +.B SIGINFO +signal (not supported on Linux) to the foreground process group. +.TP +.B VSTOP +(023, DC3, Ctrl-S) +Stop character (STOP). +Stop output until Start character typed. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSUSP +(032, SUB, Ctrl-Z) +Suspend character (SUSP). +Send +.B SIGTSTP +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VSWTCH +(not in POSIX; not supported under Linux; 0, NUL) +Switch character (SWTCH). +Used in System V to switch shells in +.IR "shell layers" , +a predecessor to shell job control. +.TP +.B VTIME +Timeout in deciseconds for noncanonical read (TIME). +.TP +.B VWERASE +(not in POSIX; 027, ETB, Ctrl-W) +Word erase (WERASE). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.P +An individual terminal special character can be disabled by setting +the value of the corresponding +.I c_cc +element to +.BR _POSIX_VDISABLE . +.P +The above symbolic subscript values are all different, except that +.BR VTIME , +.B VMIN +may have the same value as +.BR VEOL , +.BR VEOF , +respectively. +In noncanonical mode the special character meaning is replaced +by the timeout meaning. +For an explanation of +.B VMIN +and +.BR VTIME , +see the description of +noncanonical mode below. +.SS Retrieving and changing terminal settings +.BR tcgetattr () +gets the parameters associated with the object referred by \fIfd\fP and +stores them in the \fItermios\fP structure referenced by +\fItermios_p\fP. +This function may be invoked from a background process; +however, the terminal attributes may be subsequently changed by a +foreground process. +.P +.BR tcsetattr () +sets the parameters associated with the terminal (unless support is +required from the underlying hardware that is not available) from the +\fItermios\fP structure referred to by \fItermios_p\fP. +\fIoptional_actions\fP specifies when the changes take effect: +.TP +.B TCSANOW +the change occurs immediately. +.TP +.B TCSADRAIN +the change occurs after all output written to +.I fd +has been transmitted. +This option should be used when changing +parameters that affect output. +.TP +.B TCSAFLUSH +the change occurs after all output written to the object referred by +.I fd +has been transmitted, and all input that has been received but not read +will be discarded before the change is made. +.SS Canonical and noncanonical mode +The setting of the +.B ICANON +canon flag in +.I c_lflag +determines whether the terminal is operating in canonical mode +.RB ( ICANON +set) or +noncanonical mode +.RB ( ICANON +unset). +By default, +.B ICANON +is set. +.P +In canonical mode: +.IP \[bu] 3 +Input is made available line by line. +An input line is available when one of the line delimiters +is typed (NL, EOL, EOL2; or EOF at the start of line). +Except in the case of EOF, the line delimiter is included +in the buffer returned by +.BR read (2). +.IP \[bu] +Line editing is enabled (ERASE, KILL; +and if the +.B IEXTEN +flag is set: WERASE, REPRINT, LNEXT). +A +.BR read (2) +returns at most one line of input; if the +.BR read (2) +requested fewer bytes than are available in the current line of input, +then only as many bytes as requested are read, +and the remaining characters will be available for a future +.BR read (2). +.IP \[bu] +The maximum line length is 4096 chars +(including the terminating newline character); +lines longer than 4096 chars are truncated. +After 4095 characters, input processing (e.g., +.B ISIG +and +.B ECHO* +processing) continues, but any input data after 4095 characters up to +(but not including) any terminating newline is discarded. +This ensures that the terminal can always receive +more input until at least one line can be read. +.P +In noncanonical mode input is available immediately (without +the user having to type a line-delimiter character), +no input processing is performed, +and line editing is disabled. +The read buffer will only accept 4095 chars; this provides the +necessary space for a newline char if the input mode is switched +to canonical. +The settings of MIN +.RI ( c_cc[VMIN] ) +and TIME +.RI ( c_cc[VTIME] ) +determine the circumstances in which a +.BR read (2) +completes; there are four distinct cases: +.TP +MIN == 0, TIME == 0 (polling read) +If data is available, +.BR read (2) +returns immediately, with the lesser of the number of bytes +available, or the number of bytes requested. +If no data is available, +.BR read (2) +returns 0. +.TP +MIN > 0, TIME == 0 (blocking read) +.BR read (2) +blocks until MIN bytes are available, +and returns up to the number of bytes requested. +.TP +MIN == 0, TIME > 0 (read with timeout) +TIME specifies the limit for a timer in tenths of a second. +The timer is started when +.BR read (2) +is called. +.BR read (2) +returns either when at least one byte of data is available, +or when the timer expires. +If the timer expires without any input becoming available, +.BR read (2) +returns 0. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.TP +MIN > 0, TIME > 0 (read with interbyte timeout) +TIME specifies the limit for a timer in tenths of a second. +Once an initial byte of input becomes available, +the timer is restarted after each further byte is received. +.BR read (2) +returns when any of the following conditions is met: +.RS +.IP \[bu] 3 +MIN bytes have been received. +.IP \[bu] +The interbyte timer expires. +.IP \[bu] +The number of bytes requested by +.BR read (2) +has been received. +(POSIX does not specify this termination condition, +and on some other implementations +.\" e.g., Solaris +.BR read (2) +does not return in this case.) +.RE +.IP +Because the timer is started only after the initial byte +becomes available, at least one byte will be read. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.P +POSIX +.\" POSIX.1-2008 XBD 11.1.7 +does not specify whether the setting of the +.B O_NONBLOCK +file status flag takes precedence over the MIN and TIME settings. +If +.B O_NONBLOCK +is set, a +.BR read (2) +in noncanonical mode may return immediately, +regardless of the setting of MIN or TIME. +Furthermore, if no data is available, +POSIX permits a +.BR read (2) +in noncanonical mode to return either 0, or \-1 with +.I errno +set to +.BR EAGAIN . +.SS Raw mode +.BR cfmakeraw () +sets the terminal to something like the +"raw" mode of the old Version 7 terminal driver: +input is available character by character, +echoing is disabled, and all special processing of +terminal input and output characters is disabled. +The terminal attributes are set as follows: +.P +.in +4n +.EX +termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP + | INLCR | IGNCR | ICRNL | IXON); +termios_p\->c_oflag &= \[ti]OPOST; +termios_p\->c_lflag &= \[ti](ECHO | ECHONL | ICANON | ISIG | IEXTEN); +termios_p\->c_cflag &= \[ti](CSIZE | PARENB); +termios_p\->c_cflag |= CS8; +.EE +.in +.\" +.SS Line control +.BR tcsendbreak () +transmits a continuous stream of zero-valued bits for a specific +duration, if the terminal is using asynchronous serial data +transmission. +If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more than 0.5 seconds. +If \fIduration\fP is not zero, it sends zero-valued bits for some +implementation-defined length of time. +.P +If the terminal is not using asynchronous serial data transmission, +.BR tcsendbreak () +returns without taking any action. +.P +.BR tcdrain () +waits until all output written to the object referred to by +.I fd +has been transmitted. +.P +.BR tcflush () +discards data written to the object referred to by +.I fd +but not transmitted, or data received but not read, depending on the +value of +.IR queue_selector : +.TP +.B TCIFLUSH +flushes data received but not read. +.TP +.B TCOFLUSH +flushes data written but not transmitted. +.TP +.B TCIOFLUSH +flushes both data received but not read, and data written but not +transmitted. +.P +.BR tcflow () +suspends transmission or reception of data on the object referred to by +.IR fd , +depending on the value of +.IR action : +.TP +.B TCOOFF +suspends output. +.TP +.B TCOON +restarts suspended output. +.TP +.B TCIOFF +transmits a STOP character, which stops the terminal device from +transmitting data to the system. +.TP +.B TCION +transmits a START character, which starts the terminal device +transmitting data to the system. +.P +The default on open of a terminal file is that neither its input nor its +output is suspended. +.SS Line speed +The baud rate functions are provided for getting and setting the values +of the input and output baud rates in the \fItermios\fP structure. +The new values do not take effect +until +.BR tcsetattr () +is successfully called. +.P +Setting the speed to \fBB0\fP instructs the modem to "hang up". +The actual bit rate corresponding to \fBB38400\fP may be altered with +.BR setserial (8). +.P +The input and output baud rates are stored in the \fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure +pointed to by +.IR termios_p . +.P +.BR cfsetospeed () +sets the output baud rate stored in the \fItermios\fP structure pointed +to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: +.RS +.TP +.B B0 +.TQ +.B B50 +.TQ +.B B75 +.TQ +.B B110 +.TQ +.B B134 +.TQ +.B B150 +.TQ +.B B200 +.TQ +.B B300 +.TQ +.B B600 +.TQ +.B B1200 +.TQ +.B B1800 +.TQ +.B B2400 +.TQ +.B B4800 +.TQ +.B B9600 +.TQ +.B B19200 +.TQ +.B B38400 +.TQ +.B B57600 +.TQ +.B B115200 +.TQ +.B B230400 +.TQ +.B B460800 +.TQ +.B B500000 +.TQ +.B B576000 +.TQ +.B B921600 +.TQ +.B B1000000 +.TQ +.B B1152000 +.TQ +.B B1500000 +.TQ +.B B2000000 +.RE +.P +These constants are additionally supported on the SPARC architecture: +.RS +.TP +.B B76800 +.TQ +.B B153600 +.TQ +.B B307200 +.TQ +.B B614400 +.RE +.P +These constants are additionally supported on non-SPARC architectures: +.RS +.TP +.B B2500000 +.TQ +.B B3000000 +.TQ +.B B3500000 +.TQ +.B B4000000 +.RE +.P +Due to differences between architectures, portable applications should check +if a particular +.BI B nnn +constant is defined prior to using it. +.P +The zero baud rate, +.BR B0 , +is used to terminate the connection. +If +.B B0 +is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. +.B CBAUDEX +is a mask +for the speeds beyond those defined in POSIX.1 (57600 and above). +Thus, +.BR B57600 " & " CBAUDEX +is nonzero. +.P +Setting the baud rate to a value other than those defined by +.BI B nnn +constants is possible via the +.B TCSETS2 +ioctl; see +.BR ioctl_tty (2). +.P +.BR cfgetispeed () +returns the input baud rate stored in the +.I termios +structure. +.P +.BR cfsetispeed () +sets the input baud rate stored in the +.I termios +structure to +.IR speed , +which must be specified as one of the +.BI B nnn +constants listed above for +.BR cfsetospeed (). +If the input baud rate is set to the literal constant +.B 0 +(not the symbolic constant +.BR B0 ), +the input baud rate will be +equal to the output baud rate. +.P +.BR cfsetspeed () +is a 4.4BSD extension. +It takes the same arguments as +.BR cfsetispeed (), +and sets both input and output speed. +.SH RETURN VALUE +.BR cfgetispeed () +returns the input baud rate stored in the +\fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure. +.P +All other functions return: +.TP +.B 0 +on success. +.TP +.B \-1 +on failure and set +.I errno +to indicate the error. +.P +Note that +.BR tcsetattr () +returns success if \fIany\fP of the requested changes could be +successfully carried out. +Therefore, when making multiple changes +it may be necessary to follow this call with a further call to +.BR tcgetattr () +to check that all changes have been performed successfully. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetattr (), +.BR tcsetattr (), +.BR tcdrain (), +.BR tcflush (), +.BR tcflow (), +.BR tcsendbreak (), +.BR cfmakeraw (), +.BR cfgetispeed (), +.BR cfgetospeed (), +.BR cfsetispeed (), +.BR cfsetospeed (), +.BR cfsetspeed () +T} Thread safety MT-Safe +.TE +.\" FIXME: The markings are different from that in the glibc manual. +.\" markings in glibc manual are more detailed: +.\" +.\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd +.\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd +.\" +.\" glibc manual says /bsd indicate the preceding marker only applies +.\" when the underlying kernel is a BSD kernel. +.\" So, it is safety in Linux kernel. +.SH STANDARDS +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2008. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH HISTORY +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2001. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH NOTES +UNIX\ V7 and several later systems have a list of baud rates +where after the values +.B B0 +through +.B B9600 +one finds the two constants +.BR EXTA , +.B EXTB +("External A" and "External B"). +Many systems extend the list with much higher baud rates. +.P +The effect of a nonzero \fIduration\fP with +.BR tcsendbreak () +varies. +SunOS specifies a break of +.I "duration\ *\ N" +seconds, where \fIN\fP is at least 0.25, and not more than 0.5. +Linux, AIX, DU, Tru64 send a break of +.I duration +milliseconds. +FreeBSD and NetBSD and HP-UX and MacOS ignore the value of +.IR duration . +Under Solaris and UnixWare, +.BR tcsendbreak () +with nonzero +.I duration +behaves like +.BR tcdrain (). +.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. +.\" libc4.7.6, libc5, glibc for unix: duration in ms. +.\" glibc for bsd: duration in us +.\" glibc for sunos4: ignore duration +.SH BUGS +.\" kernel 77e5bff1640432f28794a00800955e646dcd7455 +.\" glibc 573963e32ffac46d9891970ddebde2ac3212c5c0 +On the Alpha architecture before Linux 4.16 (and glibc before glibc 2.28), the +.B XTABS +value was different from +.B TAB3 +and it was ignored by the +.B N_TTY +line discipline code of the terminal driver as a result +(because as it wasn't part of the +.B TABDLY +mask). +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR tput (1), +.BR tset (1), +.BR tty (1), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR cc_t (3type), +.BR speed_t (3type), +.BR tcflag_t (3type), +.BR setserial (8) diff --git a/man/man3/tfind.3 b/man/man3/tfind.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tfind.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tgamma.3 b/man/man3/tgamma.3 new file mode 100644 index 0000000..01d86a9 --- /dev/null +++ b/man/man3/tgamma.3 @@ -0,0 +1,216 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" Modified 2004-11-15, fixed error noted by Fabian Kreutz +.\" <kreutz@dbs.uni-hannover.de> +.\" +.TH tgamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tgamma, tgammaf, tgammal \- true gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double tgamma(double " x ); +.BI "float tgammaf(float " x ); +.BI "long double tgammal(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tgamma (), +.BR tgammaf (), +.BR tgammal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions calculate the Gamma function of +.IR x . +.P +The Gamma function is defined by +.P +.RS +Gamma(x) = integral from 0 to infinity of t\[ha](x\-1) e\[ha]\-t dt +.RE +.P +It is defined for every real number except for nonpositive integers. +For nonnegative integral +.I m +one has +.P +.RS +Gamma(m+1) = m! +.RE +.P +and, more generally, for all +.IR x : +.P +.RS +Gamma(x+1) = x * Gamma(x) +.RE +.P +Furthermore, the following is valid for all values of +.I x +outside the poles: +.P +.RS +Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x) +.RE +.SH RETURN VALUE +On success, these functions return Gamma(x). +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is a negative integer, or is negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.P +If the result underflows, +a range error occurs, +and the functions return 0, with the correct mathematical sign. +.P +If +.I x +is \-0 or +0, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as the 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a negative integer, or negative infinity +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised (but see BUGS). +.TP +Pole error: \fIx\fP is +0 or \-0 +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.P +glibc also gives the following error which is not specified +in C99 or POSIX.1-2001. +.TP +Range error: result underflow +.\" e.g., tgamma(-172.5) on glibc 2.8/x86-32 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised, and +.I errno +is set to +.BR ERANGE . +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tgamma (), +.BR tgammaf (), +.BR tgammal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +This function had to be called "true gamma function" +since there is already a function +.BR gamma (3) +that returns something else (see +.BR gamma (3) +for details). +.SH BUGS +Before glibc 2.18, the glibc implementation of these functions did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6809 +.I errno +to +.B EDOM +when +.I x +is negative infinity. +.P +Before glibc 2.19, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810 +the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +on an underflow range error. +.P +.\" +In glibc versions 2.3.3 and earlier, +an argument of +0 or \-0 incorrectly produced a domain error +.RI ( errno +set to +.B EDOM +and an +.B FE_INVALID +exception raised), rather than a pole error. +.SH SEE ALSO +.BR gamma (3), +.BR lgamma (3) diff --git a/man/man3/tgammaf.3 b/man/man3/tgammaf.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man/man3/tgammaf.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man/man3/tgammal.3 b/man/man3/tgammal.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man/man3/tgammal.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man/man3/timegm.3 b/man/man3/timegm.3 new file mode 100644 index 0000000..7395d99 --- /dev/null +++ b/man/man3/timegm.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timegm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timegm, timelocal \- inverses of gmtime and localtime +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "[[deprecated]] time_t timelocal(struct tm *" tm ); +.BI "time_t timegm(struct tm *" tm ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timelocal (), +.BR timegm (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR timelocal () +and +.BR timegm () +are the inverses of +.BR localtime (3) +and +.BR gmtime (3). +Both functions take a broken-down time and convert it to calendar time +(seconds since the Epoch, 1970-01-01 00:00:00 +0000, UTC). +The difference between the two functions is that +.BR timelocal () +takes the local timezone into account when doing the conversion, while +.BR timegm () +takes the input value to be Coordinated Universal Time (UTC). +.SH RETURN VALUE +On success, +these functions return the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +On error, they return the value +.I (time_t)\ \-1 +and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR timelocal (), +.BR timegm () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +GNU, BSD. +.P +The +.BR timelocal () +function is equivalent to the POSIX standard function +.BR mktime (3). +There is no reason to ever use it. +.SH SEE ALSO +.BR gmtime (3), +.BR localtime (3), +.BR mktime (3), +.BR tzset (3) diff --git a/man/man3/timelocal.3 b/man/man3/timelocal.3 new file mode 100644 index 0000000..45d4c09 --- /dev/null +++ b/man/man3/timelocal.3 @@ -0,0 +1 @@ +.so man3/timegm.3 diff --git a/man/man3/timeradd.3 b/man/man3/timeradd.3 new file mode 100644 index 0000000..89002ec --- /dev/null +++ b/man/man3/timeradd.3 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-07-31, mtk, Created +.\" +.TH timeradd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/time.h> +.P +.BI "void timeradd(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.BI "void timersub(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.P +.BI "void timerclear(struct timeval *" tvp ); +.BI "int timerisset(struct timeval *" tvp ); +.P +.BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The macros are provided to operate on +.I timeval +structures, defined in +.I <sys/time.h> +as: +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +.BR timeradd () +adds the time values in +.I a +and +.IR b , +and places the sum in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.P +.BR timersub () +subtracts the time value in +.I b +from the time value in +.IR a , +and places the result in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.P +.BR timerclear () +zeros out the +.I timeval +structure pointed to by +.IR tvp , +so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC). +.P +.BR timerisset () +returns true (nonzero) if either field of the +.I timeval +structure pointed to by +.I tvp +contains a nonzero value. +.P +.BR timercmp () +compares the timer values in +.I a +and +.I b +using the comparison operator +.IR CMP , +and returns true (nonzero) or false (0) depending on +the result of the comparison. +Some systems (but not Linux/glibc), +have a broken +.BR timercmp () +implementation, +.\" HP-UX, Tru64, Irix have a definition like: +.\"#define timercmp(tvp, uvp, cmp) \ +.\" ((tvp)->tv_sec cmp (uvp)->tv_sec || \ +.\" (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec) +in which +.I CMP +of +.IR >= , +.IR <= , +and +.I == +do not work; +portable applications can instead use +.P +.in +4n +.EX +!timercmp(..., <) +!timercmp(..., >) +!timercmp(..., !=) +.EE +.in +.SH RETURN VALUE +.BR timerisset () +and +.BR timercmp () +return true (nonzero) or false (0). +.SH ERRORS +No errors are defined. +.SH STANDARDS +None. +.SH HISTORY +BSD. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (7) diff --git a/man/man3/timerclear.3 b/man/man3/timerclear.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timerclear.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timercmp.3 b/man/man3/timercmp.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timercmp.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timerisset.3 b/man/man3/timerisset.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timerisset.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timersub.3 b/man/man3/timersub.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timersub.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timezone.3 b/man/man3/timezone.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/timezone.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/tmpfile.3 b/man/man3/tmpfile.3 new file mode 100644 index 0000000..21d934b --- /dev/null +++ b/man/man3/tmpfile.3 @@ -0,0 +1,103 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-17, aeb +.TH tmpfile 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tmpfile \- create a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.B FILE *tmpfile(void); +.fi +.SH DESCRIPTION +The +.BR tmpfile () +function opens a unique temporary file +in binary read/write (w+b) mode. +The file will be automatically deleted when it is closed or the +program terminates. +.SH RETURN VALUE +The +.BR tmpfile () +function returns a stream descriptor, or NULL if +a unique filename cannot be generated or the unique file cannot be +opened. +In the latter case, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission denied for directory in file's path prefix. +.TP +.B EEXIST +Unable to generate a unique filename. +.TP +.B EINTR +The call was interrupted by a signal; see +.BR signal (7). +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOSPC +There was no room in the directory to add the new filename. +.TP +.B EROFS +Read-only filesystem. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tmpfile () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The standard does not specify the directory that +.BR tmpfile () +will use. +glibc will try the path prefix +.I P_tmpdir +defined +in +.IR <stdio.h> , +and if that fails, then the directory +.IR /tmp . +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD, SUSv2. +.SH NOTES +POSIX.1-2001 specifies: +an error message may be written to +.I stdout +if the stream +cannot be opened. +.SH SEE ALSO +.BR exit (3), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpnam (3) diff --git a/man/man3/tmpnam.3 b/man/man3/tmpnam.3 new file mode 100644 index 0000000..25161d6 --- /dev/null +++ b/man/man3/tmpnam.3 @@ -0,0 +1,168 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2003-11-15, aeb, added tmpnam_r +.\" +.TH tmpnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tmpnam, tmpnam_r \- create a name for a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "[[deprecated]] char *tmpnam(char *" s ); +.BI "[[deprecated]] char *tmpnam_r(char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tmpnam_r () +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + Up to and including glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.B Note: +avoid using these functions; use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.P +The +.BR tmpnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist at some point +in time, so that naive programmers may think it +a suitable name for a temporary file. +If the argument +.I s +is NULL, this name is generated in an internal static buffer +and may be overwritten by the next call to +.BR tmpnam (). +If +.I s +is not NULL, the name is copied to the character array (of length +at least +.IR L_tmpnam ) +pointed to by +.I s +and the value +.I s +is returned in case of success. +.P +The created pathname has a directory prefix +.IR P_tmpdir . +(Both +.I L_tmpnam +and +.I P_tmpdir +are defined in +.IR <stdio.h> , +just like the +.B TMP_MAX +mentioned below.) +.P +The +.BR tmpnam_r () +function performs the same task as +.BR tmpnam (), +but returns NULL (to indicate an error) if +.I s +is NULL. +.SH RETURN VALUE +These functions return a pointer to a unique temporary +filename, or NULL if a unique name cannot be generated. +.SH ERRORS +No errors are defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tmpnam () +T} Thread safety MT-Unsafe race:tmpnam/!s +T{ +.na +.nh +.BR tmpnam_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR tmpnam () +C11, POSIX.1-2008. +.TP +.BR tmpnam_r () +None. +.SH HISTORY +.TP +.BR tmpnam () +SVr4, 4.3BSD, C89, POSIX.1-2001. +Obsolete in POSIX.1-2008. +.TP +.BR tmpnam_r () +Solaris. +.SH NOTES +The +.BR tmpnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.P +Although these functions generate names that are difficult to guess, +it is nevertheless possible that between the time that +the pathname is returned and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.P +Portable applications that use threads cannot call +.BR tmpnam () +with a NULL argument if either +.B _POSIX_THREADS +or +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH BUGS +Never use these functions. +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3) diff --git a/man/man3/tmpnam_r.3 b/man/man3/tmpnam_r.3 new file mode 100644 index 0000000..c1bd6dc --- /dev/null +++ b/man/man3/tmpnam_r.3 @@ -0,0 +1 @@ +.so man3/tmpnam.3 diff --git a/man/man3/toascii.3 b/man/man3/toascii.3 new file mode 100644 index 0000000..e2e574a --- /dev/null +++ b/man/man3/toascii.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (c) 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Added BUGS section, aeb, 950919 +.\" +.TH toascii 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +toascii \- convert character to ASCII +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ctype.h> +.P +.BI "[[deprecated]] int toascii(int " c ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR toascii (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR toascii () +converts +.I c +to a 7-bit +.I "unsigned char" +value that fits into the ASCII character set, by clearing the +high-order bits. +.SH RETURN VALUE +The value returned is that of the converted character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR toascii () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, BSD, POSIX.1-2001. +Obsolete in POSIX.1-2008, +noting that it cannot be used portably in a localized application. +.SH BUGS +Many people will be unhappy if you use this function. +This function will convert accented letters into random characters. +.SH SEE ALSO +.BR isascii (3), +.BR tolower (3), +.BR toupper (3) diff --git a/man/man3/tolower.3 b/man/man3/tolower.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/tolower.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/tolower_l.3 b/man/man3/tolower_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/tolower_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/toupper.3 b/man/man3/toupper.3 new file mode 100644 index 0000000..c2ab04a --- /dev/null +++ b/man/man3/toupper.3 @@ -0,0 +1,185 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org> +.TH toupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ctype.h> +.P +.BI "int toupper(int " "c" ); +.BI "int tolower(int " "c" ); +.P +.BI "int toupper_l(int " c ", locale_t " locale ); +.BI "int tolower_l(int " c ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR toupper_l (), +.BR tolower_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions convert lowercase letters to uppercase, and vice versa. +.P +If +.I c +is a lowercase letter, +.BR toupper () +returns its uppercase equivalent, +if an uppercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR toupper_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.P +If +.I c +is an uppercase letter, +.BR tolower () +returns its lowercase equivalent, +if a lowercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR tolower_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.P +If +.I c +is neither an +.I "unsigned char" +value nor +.BR EOF , +the behavior of these functions +is undefined. +.P +The behavior of +.BR toupper_l () +and +.BR tolower_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.SH RETURN VALUE +The value returned is that of the converted letter, or +.I c +if the conversion was not possible. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR toupper (), +.BR tolower (), +.BR toupper_l (), +.BR tolower_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR toupper () +.TQ +.BR tolower () +C11, POSIX.1-2008. +.TP +.BR toupper_l () +.TQ +.BR tolower_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR toupper () +.TQ +.BR tolower () +C89, 4.3BSD, POSIX.1-2001. +.TP +.BR toupper_l () +.TQ +.BR tolower_l () +POSIX.1-2008. +.SH NOTES +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" . +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.P +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.P +This is necessary because +.I char +may be the equivalent +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.P +The details of what constitutes an uppercase or lowercase letter depend +on the locale. +For example, the default +.B \[dq]C\[dq] +locale does not know about umlauts, so no conversion is done for them. +.P +In some non-English locales, there are lowercase letters with no +corresponding uppercase equivalent; +.\" FIXME One day the statement about "sharp s" needs to be reworked, +.\" since there is nowadays a capital "sharp s" that has a codepoint +.\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E +the German sharp s is one example. +.SH SEE ALSO +.BR isalpha (3), +.BR newlocale (3), +.BR setlocale (3), +.BR towlower (3), +.BR towupper (3), +.BR uselocale (3), +.BR locale (7) diff --git a/man/man3/toupper_l.3 b/man/man3/toupper_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/toupper_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/towctrans.3 b/man/man3/towctrans.3 new file mode 100644 index 0000000..e18baa6 --- /dev/null +++ b/man/man3/towctrans.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towctrans 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towctrans \- wide-character transliteration +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character, then the +.BR towctrans () +function +translates it according to the transliteration descriptor +.IR desc . +If +.I wc +is +.BR WEOF , +.B WEOF +is returned. +.P +.I desc +must be a transliteration descriptor returned by +the +.BR wctrans (3) +function. +.SH RETURN VALUE +The +.BR towctrans () +function returns the translated wide character, +or +.B WEOF +if +.I wc +is +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towctrans () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR towctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towlower (3), +.BR towupper (3), +.BR wctrans (3) diff --git a/man/man3/towlower.3 b/man/man3/towlower.3 new file mode 100644 index 0000000..a136a59 --- /dev/null +++ b/man/man3/towlower.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towlower 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towlower, towlower_l \- convert a wide character to lowercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "wint_t towlower(wint_t " wc ); +.BI "wint_t towlower_l(wint_t " wc ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR towlower_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR towlower () +function is the wide-character equivalent of the +.BR tolower (3) +function. +If +.I wc +is an uppercase wide character, +and there exists a lowercase equivalent in the current locale, +it returns the lowercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.P +The +.BR towlower_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towlower_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The argument +.I wc +must be representable as a +.I wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to lowercase, +.BR towlower () +returns its lowercase equivalent; +otherwise it returns +.IR wc . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towlower () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR towlower_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR towlower () +C11, POSIX.1-2008 (XSI). +.TP +.BR towlower_l () +POSIX.1-2008. +.SH STANDARDS +.TP +.BR towlower () +C99, POSIX.1-2001 (XSI). +Obsolete in POSIX.1-2008 (XSI). +.TP +.BR towlower_l () +glibc 2.3. +POSIX.1-2008. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.P +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR iswlower (3), +.BR towctrans (3), +.BR towupper (3), +.BR locale (7) diff --git a/man/man3/towlower_l.3 b/man/man3/towlower_l.3 new file mode 100644 index 0000000..6135f86 --- /dev/null +++ b/man/man3/towlower_l.3 @@ -0,0 +1 @@ +.so man3/towlower.3 diff --git a/man/man3/towupper.3 b/man/man3/towupper.3 new file mode 100644 index 0000000..5d4fbf4 --- /dev/null +++ b/man/man3/towupper.3 @@ -0,0 +1,130 @@ +'\" t +.\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towupper, towupper_l \- convert a wide character to uppercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "wint_t towupper(wint_t " wc ); +.BI "wint_t towupper_l(wint_t " wc ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR towupper_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR towupper () +function is the wide-character equivalent of the +.BR toupper (3) +function. +If +.I wc +is a lowercase wide character, +and there exists an uppercase equivalent in the current locale, +it returns the uppercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.P +The +.BR towupper_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towupper_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The argument +.I wc +must be representable as a +.I wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to uppercase, +.BR towupper () +returns its uppercase equivalent; +otherwise it returns +.IR wc . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towupper () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR towupper_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR towupper () +C11, POSIX.1-2008 (XSI). +.TP +.BR towupper_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR towupper () +C99, POSIX.1-2001 (XSI). +Obsolete in POSIX.1-2008 (XSI). +.TP +.BR towupper_l () +POSIX.1-2008. +glibc 2.3. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.P +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR iswupper (3), +.BR towctrans (3), +.BR towlower (3), +.BR locale (7) diff --git a/man/man3/towupper_l.3 b/man/man3/towupper_l.3 new file mode 100644 index 0000000..a0b0e89 --- /dev/null +++ b/man/man3/towupper_l.3 @@ -0,0 +1 @@ +.so man3/towupper.3 diff --git a/man/man3/trunc.3 b/man/man3/trunc.3 new file mode 100644 index 0000000..17e5f14 --- /dev/null +++ b/man/man3/trunc.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH trunc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +trunc, truncf, truncl \- round to integer, toward zero +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double trunc(double " x ); +.BI "float truncf(float " x ); +.BI "long double truncl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR trunc (), +.BR truncf (), +.BR truncl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round +.I x +to the nearest integer value that is not larger in magnitude than +.IR x . +.SH RETURN VALUE +These functions return the rounded integer value, in floating format. +.P +If +.I x +is integral, infinite, or NaN, +.I x +itself is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR trunc (), +.BR truncf (), +.BR truncl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/truncf.3 b/man/man3/truncf.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man/man3/truncf.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man/man3/truncl.3 b/man/man3/truncl.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man/man3/truncl.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man/man3/tsearch.3 b/man/man3/tsearch.3 new file mode 100644 index 0000000..c4aaf18 --- /dev/null +++ b/man/man3/tsearch.3 @@ -0,0 +1,356 @@ +'\" t +.\" Copyright 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tsearch, tfind, tdelete, twalk, twalk_r, tdestroy \- manage a binary search tree +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <search.h> +.P +.B typedef enum { preorder, postorder, endorder, leaf } VISIT; +.P +.BI "void *tsearch(const void *" key ", void **" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void *tfind(const void *" key ", void *const *" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void *tdelete(const void *restrict " key ", void **restrict " rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void twalk(const void *" root , +.BI " void (*" action ")(const void *" nodep ", VISIT " which , +.BI " int " depth )); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <search.h> +.P +.BI "void twalk_r(const void *" root , +.BI " void (*" action ")(const void *" nodep ", VISIT " which , +.BI " void *" closure ), +.BI " void *" closure ); +.BI "void tdestroy(void *" root ", void (*" free_node ")(void *" nodep )); +.fi +.SH DESCRIPTION +.BR tsearch (), +.BR tfind (), +.BR twalk (), +and +.BR tdelete () +manage a +binary search tree. +They are generalized from Knuth (6.2.2) Algorithm T. +The first field in each node of the tree is a pointer to the +corresponding data item. +(The calling program must store the actual data.) +.I compar +points to a comparison routine, which takes +pointers to two items. +It should return an integer which is negative, +zero, or positive, depending on whether the first item is less than, +equal to, or greater than the second. +.P +.BR tsearch () +searches the tree for an item. +.I key +points to the item to be searched for. +.I rootp +points to a variable which points to the root of the tree. +If the tree is empty, +then the variable that +.I rootp +points to should be set to NULL. +If the item is found in the tree, then +.BR tsearch () +returns a pointer +to the corresponding tree node. +(In other words, +.BR tsearch () +returns a pointer to a pointer to the data item.) +If the item is not found, then +.BR tsearch () +adds it, and returns a +pointer to the corresponding tree node. +.P +.BR tfind () +is like +.BR tsearch (), +except that if the item is not +found, then +.BR tfind () +returns NULL. +.P +.BR tdelete () +deletes an item from the tree. +Its arguments are the same as for +.BR tsearch (). +.P +.BR twalk () +performs depth-first, left-to-right traversal of a binary +tree. +.I root +points to the starting node for the traversal. +If that node is not the root, then only part of the tree will be visited. +.BR twalk () +calls the user function +.I action +each time a node is +visited (that is, three times for an internal node, and once for a +leaf). +.IR action , +in turn, takes three arguments. +The first argument is a pointer to the node being visited. +The structure of the node is unspecified, +but it is possible to cast the pointer to a pointer-to-pointer-to-element +in order to access the element stored within the node. +The application must not modify the structure pointed to by this argument. +The second argument is an integer which +takes one of the values +.BR preorder , +.BR postorder , +or +.B endorder +depending on whether this is the first, second, or +third visit to the internal node, +or the value +.B leaf +if this is the single visit to a leaf node. +(These symbols are defined in +.IR <search.h> .) +The third argument is the depth of the node; +the root node has depth zero. +.P +(More commonly, +.BR preorder , +.BR postorder , +and +.B endorder +are known as +.BR preorder , +.BR inorder , +and +.BR postorder : +before visiting the children, after the first and before the second, +and after visiting the children. +Thus, the choice of name +.B post\%order +is rather confusing.) +.P +.BR twalk_r () +is similar to +.BR twalk (), +but instead of the +.I depth +argument, the +.I closure +argument pointer is passed to each invocation of the action callback, +unchanged. +This pointer can be used to pass information to and from +the callback function in a thread-safe fashion, without resorting +to global variables. +.P +.BR tdestroy () +removes the whole tree pointed to by +.IR root , +freeing all resources allocated by the +.BR tsearch () +function. +For the data in each tree node the function +.I free_node +is called. +The pointer to the data is passed as the argument to the function. +If no such work is necessary, +.I free_node +must point to a function +doing nothing. +.SH RETURN VALUE +.BR tsearch () +returns a pointer to a matching node in the tree, or to +the newly added node, or NULL if there was insufficient memory +to add the item. +.BR tfind () +returns a pointer to the node, or +NULL if no match is found. +If there are multiple items that match the key, +the item whose node is returned is unspecified. +.P +.BR tdelete () +returns a pointer to the parent of the node deleted, or +NULL if the item was not found. +If the deleted node was the root node, +.BR tdelete () +returns a dangling pointer that must not be accessed. +.P +.BR tsearch (), +.BR tfind (), +and +.BR tdelete () +also +return NULL if +.I rootp +was NULL on entry. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tsearch (), +.BR tfind (), +.BR tdelete () +T} Thread safety MT-Safe race:rootp +T{ +.na +.nh +.BR twalk () +T} Thread safety MT-Safe race:root +T{ +.na +.nh +.BR twalk_r () +T} Thread safety MT-Safe race:root +T{ +.na +.nh +.BR tdestroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR tsearch () +.TQ +.BR tfind () +.TQ +.BR tdelete () +.TQ +.BR twalk () +POSIX.1-2008. +.TP +.BR tdestroy () +.TQ +.BR twalk_r () +GNU. +.SH HISTORY +.TP +.BR tsearch () +.TQ +.BR tfind () +.TQ +.BR tdelete () +.TQ +.BR twalk () +POSIX.1-2001, POSIX.1-2008, SVr4. +.TP +.BR twalk_r () +glibc 2.30. +.SH NOTES +.BR twalk () +takes a pointer to the root, while the other functions +take a pointer to a variable which points to the root. +.P +.BR tdelete () +frees the memory required for the node in the tree. +The user is responsible for freeing the memory for the corresponding +data. +.P +The example program depends on the fact that +.BR twalk () +makes no +further reference to a node after calling the user function with +argument "endorder" or "leaf". +This works with the GNU library +implementation, but is not in the System V documentation. +.SH EXAMPLES +The following program inserts twelve random numbers into a binary +tree, where duplicate numbers are collapsed, then prints the numbers +in order. +.P +.\" SRC BEGIN (tsearch.c) +.EX +#define _GNU_SOURCE /* Expose declaration of tdestroy() */ +#include <search.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> +\& +static void *root = NULL; +\& +static void * +xmalloc(size_t n) +{ + void *p; +\& + p = malloc(n); + if (p) + return p; + fprintf(stderr, "insufficient memory\en"); + exit(EXIT_FAILURE); +} +\& +static int +compare(const void *pa, const void *pb) +{ + if (*(int *) pa < *(int *) pb) + return \-1; + if (*(int *) pa > *(int *) pb) + return 1; + return 0; +} +\& +static void +action(const void *nodep, VISIT which, int depth) +{ + int *datap; +\& + switch (which) { + case preorder: + break; + case postorder: + datap = *(int **) nodep; + printf("%6d\en", *datap); + break; + case endorder: + break; + case leaf: + datap = *(int **) nodep; + printf("%6d\en", *datap); + break; + } +} +\& +int +main(void) +{ + int *ptr; + int **val; +\& + srand(time(NULL)); + for (unsigned int i = 0; i < 12; i++) { + ptr = xmalloc(sizeof(*ptr)); + *ptr = rand() & 0xff; + val = tsearch(ptr, &root, compare); + if (val == NULL) + exit(EXIT_FAILURE); + if (*val != ptr) + free(ptr); + } + twalk(root, action); + tdestroy(root, free); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3) diff --git a/man/man3/ttyname.3 b/man/man3/ttyname.3 new file mode 100644 index 0000000..92ee3be --- /dev/null +++ b/man/man3/ttyname.3 @@ -0,0 +1,111 @@ +'\" t +.\" Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2001-12-13, Martin Schulze <joey@infodrom.org> +.\" Added ttyname_r, aeb, 2002-07-20 +.\" +.TH ttyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttyname, ttyname_r \- return name of a terminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "char *ttyname(int " fd ); +.BI "int ttyname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); +.fi +.SH DESCRIPTION +The function +.BR ttyname () +returns a pointer to the null-terminated pathname of the terminal device +that is open on the file descriptor \fIfd\fP, or NULL on error +(for example, if \fIfd\fP is not connected to a terminal). +The return value may point to static data, possibly overwritten by the +next call. +The function +.BR ttyname_r () +stores this pathname in the buffer +.I buf +of length +.IR buflen . +.SH RETURN VALUE +The function +.BR ttyname () +returns a pointer to a pathname on success. +On error, NULL is returned, and +.I errno +is set to indicate the error. +The function +.BR ttyname_r () +returns 0 on success, and an error number upon error. +.SH ERRORS +.TP +.B EBADF +Bad file descriptor. +.TP +.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23 +.B ENODEV +.I fd +refers to a slave pseudoterminal device +but the corresponding pathname could not be found (see NOTES). +.TP +.B ENOTTY +.I fd +does not refer to a terminal device. +.TP +.B ERANGE +.RB ( ttyname_r ()) +.I buflen +was too small to allow storing the pathname. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ttyname () +T} Thread safety MT-Unsafe race:ttyname +T{ +.na +.nh +.BR ttyname_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.2BSD. +.SH NOTES +A process that keeps a file descriptor that refers to a +.BR pts (4) +device open when switching to another mount namespace that uses a different +.I /dev/ptmx +instance may still accidentally find that a device path of the same name +for that file descriptor exists. +However, this device path refers to a different device and thus +can't be used to access the device that the file descriptor refers to. +Calling +.BR ttyname () +or +.BR ttyname_r () +on the file descriptor in the new mount namespace will cause these +functions to return NULL and set +.I errno +to +.BR ENODEV . +.SH SEE ALSO +.BR tty (1), +.BR fstat (2), +.BR ctermid (3), +.BR isatty (3), +.BR pts (4) diff --git a/man/man3/ttyname_r.3 b/man/man3/ttyname_r.3 new file mode 100644 index 0000000..aaa18ee --- /dev/null +++ b/man/man3/ttyname_r.3 @@ -0,0 +1 @@ +.so man3/ttyname.3 diff --git a/man/man3/ttyslot.3 b/man/man3/ttyslot.3 new file mode 100644 index 0000000..0548ea4 --- /dev/null +++ b/man/man3/ttyslot.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" <walter.harms@informatik.uni-oldenburg.de>. +.\" +.TH ttyslot 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttyslot \- find the slot of the current user's terminal in some file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <unistd.h>" " /* See NOTES */" +.P +.B "int ttyslot(void);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ttyslot (): +.nf + Since glibc 2.24: + _DEFAULT_SOURCE + From glibc 2.20 to glibc 2.23: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + glibc 2.19 and earlier: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The legacy function +.BR ttyslot () +returns the index of the current user's entry in some file. +.P +Now "What file?" you ask. +Well, let's first look at some history. +.SS Ancient history +There used to be a file +.I /etc/ttys +in UNIX\ V6, that was read by the +.BR init (1) +program to find out what to do with each terminal line. +Each line consisted of three characters. +The first character was either \[aq]0\[aq] or \[aq]1\[aq], +where \[aq]0\[aq] meant "ignore". +The second character denoted the terminal: \[aq]8\[aq] stood for "/dev/tty8". +The third character was an argument to +.BR getty (8) +indicating the sequence of line speeds to try (\[aq]\-\[aq] was: start trying +110 baud). +Thus a typical line was "18\-". +A hang on some line was solved by changing the \[aq]1\[aq] to a \[aq]0\[aq], +signaling init, changing back again, and signaling init again. +.P +In UNIX\ V7 the format was changed: here the second character +was the argument to +.BR getty (8) +indicating the sequence of line speeds to try (\[aq]0\[aq] was: cycle through +300-1200-150-110 baud; \[aq]4\[aq] was for the on-line console DECwriter) +while the rest of the line contained the name of the tty. +Thus a typical line was "14console". +.P +Later systems have more elaborate syntax. +System V-like systems have +.I /etc/inittab +instead. +.SS Ancient history (2) +On the other hand, there is the file +.I /etc/utmp +listing the people currently logged in. +It is maintained by +.BR login (1). +It has a fixed size, and the appropriate index in the file was +determined by +.BR login (1) +using the +.BR ttyslot () +call to find the number of the line in +.I /etc/ttys +(counting from 1). +.SS The semantics of ttyslot +Thus, the function +.BR ttyslot () +returns the index of the controlling terminal of the calling process +in the file +.IR /etc/ttys , +and that is (usually) the same as the index of the entry for the +current user in the file +.IR /etc/utmp . +BSD still has the +.I /etc/ttys +file, but System V-like systems do not, and hence cannot refer to it. +Thus, on such systems the documentation says that +.BR ttyslot () +returns the current user's index in the user accounting data base. +.SH RETURN VALUE +If successful, this function returns the slot number. +On error (e.g., if none of the file descriptors 0, 1, or 2 is +associated with a terminal that occurs in this data base) +it returns 0 on UNIX\ V6 and V7 and BSD-like systems, +but \-1 on System V-like systems. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ttyslot () +T} Thread safety MT-Unsafe +.TE +.SH VERSIONS +The utmp file is found in various places on various systems, such as +.IR /etc/utmp , +.IR /var/adm/utmp , +.IR /var/run/utmp . +.SH STANDARDS +None. +.SH HISTORY +SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001. +SUSv2 requires \-1 on error. +.P +The glibc2 implementation of this function reads the file +.BR _PATH_TTYS , +defined in +.I <ttyent.h> +as "/etc/ttys". +It returns 0 on error. +Since Linux systems do not usually have "/etc/ttys", it will +always return 0. +.P +On BSD-like systems and Linux, the declaration of +.BR ttyslot () +is provided by +.IR <unistd.h> . +On System V-like systems, the declaration is provided by +.IR <stdlib.h> . +Since glibc 2.24, +.I <stdlib.h> +also provides the declaration with the following +feature test macro definitions: +.P +.in +4n +.EX +(_XOPEN_SOURCE >= 500 || + (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)) + && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) +.EE +.in +.P +Minix also has +.IR fttyslot ( fd ). +.\" .SH HISTORY +.\" .BR ttyslot () +.\" appeared in UNIX V7. +.SH SEE ALSO +.BR getttyent (3), +.BR ttyname (3), +.BR utmp (5) diff --git a/man/man3/twalk.3 b/man/man3/twalk.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/twalk.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/twalk_r.3 b/man/man3/twalk_r.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/twalk_r.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tzname.3 b/man/man3/tzname.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/tzname.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/tzset.3 b/man/man3/tzset.3 new file mode 100644 index 0000000..bb7ad9f --- /dev/null +++ b/man/man3/tzset.3 @@ -0,0 +1,244 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-13, aeb +.\" Modified 2004-12-01 mtk and Martin Schulze <joey@infodrom.org> +.\" +.TH tzset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tzset, tzname, timezone, daylight \- initialize time conversion information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.B void tzset(void); +.P +.BI "extern char *" tzname [2]; +.BI "extern long " timezone ; +.BI "extern int " daylight ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tzset (): +.nf + _POSIX_C_SOURCE +.fi +.P +.IR tzname : +.nf + _POSIX_C_SOURCE +.fi +.P +.IR timezone , +.IR daylight : +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR tzset () +function initializes the \fItzname\fP variable from the +.B TZ +environment variable. +This function is automatically called by the +other time conversion functions that depend on the timezone. +In a System-V-like environment, it will also set the variables \fItimezone\fP +(seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not +have any daylight saving time rules, or to nonzero if there is a time, +past, present, or future when daylight saving time applies). +.P +If the +.B TZ +variable does not appear in the environment, the system timezone is used. +The system timezone is configured by copying, or linking, a file in the +.BR tzfile (5) +format to +.IR /etc/localtime . +A timezone database of these files may be located in the system +timezone directory (see the \fBFILES\fP section below). +.P +If the +.B TZ +variable does appear in the environment, but its value is empty, +or its value cannot be interpreted using any of the formats specified +below, then Coordinated Universal Time (UTC) is used. +.P +The value of +.B TZ +can be one of two formats. +The first format is a string of characters that directly represent the +timezone to be used: +.P +.in +4n +.EX +.IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]] +.EE +.in +.P +There are no spaces in the specification. +The \fIstd\fP string specifies an abbreviation for the timezone and must be +three or more alphabetic characters. +When enclosed between the less-than (<) and greater-than (>) signs, the +character set is expanded to include the plus (+) sign, the minus (\-) +sign, and digits. +The \fIoffset\fP string immediately +follows \fIstd\fP and specifies the time value to be added to the local +time to get Coordinated Universal Time (UTC). +The \fIoffset\fP is positive +if the local timezone is west of the Prime Meridian and negative if it is +east. +The hour must be between 0 and 24, and the minutes and seconds 00 and 59: +.P +.in +4n +.EX +.RI [ + | \- ] hh [ :mm [ :ss ]] +.EE +.in +.P +The \fIdst\fP string and \fIoffset\fP specify the name and offset for the +corresponding daylight saving timezone. +If the offset is omitted, +it defaults to one hour ahead of standard time. +.P +The \fIstart\fP field specifies when daylight saving time goes into +effect and the \fIend\fP field specifies when the change is made back to +standard time. +These fields may have the following formats: +.TP +J\fIn\fP +This specifies the Julian day with \fIn\fP between 1 and 365. +Leap days are not counted. +In this format, February 29 can't be represented; +February 28 is day 59, and March 1 is always day 60. +.TP +.I n +This specifies the zero-based Julian day with \fIn\fP between 0 and 365. +February 29 is counted in leap years. +.TP +M\fIm\fP.\fIw\fP.\fId\fP +This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP +(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). +Week 1 is +the first week in which day \fId\fP occurs and week 5 is the last week +in which day \fId\fP occurs. +Day 0 is a Sunday. +.P +The \fItime\fP fields specify when, in the local time currently in effect, +the change to the other time occurs. +If omitted, the default is 02:00:00. +.P +Here is an example for New Zealand, +where the standard time (NZST) is 12 hours ahead of UTC, +and daylight saving time (NZDT), 13 hours ahead of UTC, +runs from the first Sunday in October to the third Sunday in March, +and the changeovers happen at the default time of 02:00:00: +.P +.in +4n +.EX +TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0" +.EE +.in +.P +The second format specifies that the timezone information should be read +from a file: +.P +.in +4n +.EX +:[filespec] +.EE +.in +.P +If the file specification \fIfilespec\fP is omitted, or its value cannot +be interpreted, then Coordinated Universal Time (UTC) is used. +If \fIfilespec\fP is given, it specifies another +.BR tzfile (5)-format +file to read the timezone information from. +If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is +relative to the system timezone directory. +If the colon is omitted each +of the above \fBTZ\fP formats will be tried. +.P +Here's an example, once more for New Zealand: +.P +.in +4n +.EX +TZ=":Pacific/Auckland" +.EE +.in +.SH ENVIRONMENT +.TP +.B TZ +If this variable is set its value takes precedence over the system +configured timezone. +.TP +.B TZDIR +If this variable is set its value takes precedence over the system +configured timezone database directory path. +.SH FILES +.TP +.I /etc/localtime +The system timezone file. +.TP +.I /usr/share/zoneinfo/ +The system timezone database directory. +.TP +.I /usr/share/zoneinfo/posixrules +When a TZ string includes a dst timezone without anything following it, +then this file is used for the start/end rules. +It is in the +.BR tzfile (5) +format. +By default, the zoneinfo Makefile hard links it to the +.IR America/New_York " tzfile." +.P +Above are the current standard file locations, but they are +configurable when glibc is compiled. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tzset () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +4.3BSD had a function +.BI "char *timezone(" zone ", " dst ) +that returned the +name of the timezone corresponding to its first argument (minutes +West of UTC). +If the second argument was 0, the standard name was used, +otherwise the daylight saving time version. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR getenv (3), +.BR tzfile (5) diff --git a/man/man3/ualarm.3 b/man/man3/ualarm.3 new file mode 100644 index 0000000..66359dd --- /dev/null +++ b/man/man3/ualarm.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ualarm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ualarm \- schedule signal after given number of microseconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <unistd.h>" +.P +.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ualarm (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR ualarm () +function causes the signal +.B SIGALRM +to be sent to the invoking process after (not less than) +.I usecs +microseconds. +The delay may be lengthened slightly by any system activity +or by the time spent processing the call or by the +granularity of system timers. +.P +Unless caught or ignored, the +.B SIGALRM +signal will terminate the process. +.P +If the +.I interval +argument is nonzero, further +.B SIGALRM +signals will be sent every +.I interval +microseconds after the first. +.SH RETURN VALUE +This function returns the number of microseconds remaining for +any alarm that was previously set, or 0 if no alarm was pending. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusecs\fP or \fIinterval\fP is not smaller than 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ualarm () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +POSIX.1-2001 marks it as obsolete. +Removed in POSIX.1-2008. +.P +4.3BSD, SUSv2, and POSIX do not define any errors. +.P +POSIX.1-2001 does not specify what happens if the +.I usecs +argument is 0. +.\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD! +On Linux (and probably most other systems), +the effect is to cancel any pending alarm. +.P +The type +.I useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. +On the original BSD implementation, and in glibc before glibc 2.1, +the arguments to +.BR ualarm () +were instead typed as +.IR "unsigned int" . +Programs will be more portable if they never mention +.I useconds_t +explicitly. +.P +The interaction of this function with +other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR usleep (3) +is unspecified. +.P +This function is obsolete. +Use +.BR setitimer (2) +or POSIX interval timers +.RB ( timer_create (2), +etc.) +instead. +.SH SEE ALSO +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR usleep (3), +.BR time (7) diff --git a/man/man3/ulckpwdf.3 b/man/man3/ulckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/ulckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/ulimit.3 b/man/man3/ulimit.3 new file mode 100644 index 0000000..b143761 --- /dev/null +++ b/man/man3/ulimit.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Moved to man3, aeb, 980612 +.\" +.TH ulimit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ulimit \- get and set user limits +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <ulimit.h> +.P +.BI "[[deprecated]] long ulimit(int " cmd ", long " newlimit ); +.fi +.SH DESCRIPTION +Warning: this routine is obsolete. +Use +.BR getrlimit (2), +.BR setrlimit (2), +and +.BR sysconf (3) +instead. +For the shell command +.BR ulimit , +see +.BR bash (1). +.P +The +.BR ulimit () +call will get or set some limit for the calling process. +The +.I cmd +argument can have one of the following values. +.TP +.B UL_GETFSIZE +Return the limit on the size of a file, in units of 512 bytes. +.TP +.B UL_SETFSIZE +Set the limit on the size of a file. +.TP +.B 3 +(Not implemented for Linux.) +Return the maximum possible address of the data segment. +.TP +.B 4 +(Implemented but no symbolic constant provided.) +Return the maximum number of files that the calling process can open. +.SH RETURN VALUE +On success, +.BR ulimit () +returns a nonnegative value. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +An unprivileged process tried to increase a limit. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ulimit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.SH SEE ALSO +.BR bash (1), +.BR getrlimit (2), +.BR setrlimit (2), +.BR sysconf (3) diff --git a/man/man3/undocumented.3 b/man/man3/undocumented.3 new file mode 100644 index 0000000..09d85e5 --- /dev/null +++ b/man/man3/undocumented.3 @@ -0,0 +1,164 @@ +.\" Copyright 1995 Jim Van Zandt +.\" From jrv@vanzandt.mv.com Mon Sep 4 21:11:50 1995 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 1996-11-08, meem@sherilyn.wustl.edu, corrections +.\" 2004-10-31, aeb, changed maintainer address, updated list +.\" 2015-04-20, william@tuffbizz.com, updated list +.\" +.TH undocumented 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +undocumented \- undocumented library functions +.SH SYNOPSIS +.nf +Undocumented library functions +.fi +.SH DESCRIPTION +This man page mentions those library functions which are implemented in +the standard libraries but not yet documented in man pages. +.SS Solicitation +If you have information about these functions, +please look in the source code, write a man page (using a style +similar to that of the other Linux section 3 man pages), and send it to +.B mtk.manpages@gmail.com +for inclusion in the next man page release. +.SS The list +.BR authdes_create (3), +.BR authdes_getucred (3), +.BR authdes_pk_create (3), +.\" .BR chflags (3), +.BR clntunix_create (3), +.BR creat64 (3), +.BR dn_skipname (3), +.\" .BR fattach (3), +.\" .BR fchflags (3), +.\" .BR fclean (3), +.BR fcrypt (3), +.\" .BR fdetach (3), +.BR fp_nquery (3), +.BR fp_query (3), +.BR fp_resstat (3), +.BR freading (3), +.BR freopen64 (3), +.BR fseeko64 (3), +.BR ftello64 (3), +.BR ftw64 (3), +.BR fwscanf (3), +.BR get_avphys_pages (3), +.BR getdirentries64 (3), +.BR getmsg (3), +.BR getnetname (3), +.BR get_phys_pages (3), +.BR getpublickey (3), +.BR getsecretkey (3), +.BR h_errlist (3), +.BR host2netname (3), +.BR hostalias (3), +.BR inet_nsap_addr (3), +.BR inet_nsap_ntoa (3), +.BR init_des (3), +.BR libc_nls_init (3), +.BR mstats (3), +.BR netname2host (3), +.BR netname2user (3), +.BR nlist (3), +.BR obstack_free (3), +.\" .BR obstack stuff (3), +.BR parse_printf_format (3), +.BR p_cdname (3), +.BR p_cdnname (3), +.BR p_class (3), +.BR p_fqname (3), +.BR p_option (3), +.BR p_query (3), +.BR printf_size (3), +.BR printf_size_info (3), +.BR p_rr (3), +.BR p_time (3), +.BR p_type (3), +.BR putlong (3), +.BR putshort (3), +.BR re_compile_fastmap (3), +.BR re_compile_pattern (3), +.BR register_printf_function (3), +.BR re_match (3), +.BR re_match_2 (3), +.BR re_rx_search (3), +.BR re_search (3), +.BR re_search_2 (3), +.BR re_set_registers (3), +.BR re_set_syntax (3), +.BR res_send_setqhook (3), +.BR res_send_setrhook (3), +.BR ruserpass (3), +.BR setfileno (3), +.BR sethostfile (3), +.BR svc_exit (3), +.BR svcudp_enablecache (3), +.BR tell (3), +.BR thrd_create (3), +.BR thrd_current (3), +.BR thrd_equal (3), +.BR thrd_sleep (3), +.BR thrd_yield (3), +.BR tr_break (3), +.BR tzsetwall (3), +.BR ufc_dofinalperm (3), +.BR ufc_doit (3), +.BR user2netname (3), +.BR wcschrnul (3), +.BR wcsftime (3), +.BR wscanf (3), +.BR xdr_authdes_cred (3), +.BR xdr_authdes_verf (3), +.BR xdr_cryptkeyarg (3), +.BR xdr_cryptkeyres (3), +.BR xdr_datum (3), +.BR xdr_des_block (3), +.BR xdr_domainname (3), +.BR xdr_getcredres (3), +.BR xdr_keybuf (3), +.BR xdr_keystatus (3), +.BR xdr_mapname (3), +.BR xdr_netnamestr (3), +.BR xdr_netobj (3), +.BR xdr_passwd (3), +.BR xdr_peername (3), +.BR xdr_rmtcall_args (3), +.BR xdr_rmtcallres (3), +.BR xdr_unixcred (3), +.BR xdr_yp_buf (3), +.BR xdr_yp_inaddr (3), +.BR xdr_ypbind_binding (3), +.BR xdr_ypbind_resp (3), +.BR xdr_ypbind_resptype (3), +.BR xdr_ypbind_setdom (3), +.BR xdr_ypdelete_args (3), +.BR xdr_ypmaplist (3), +.BR xdr_ypmaplist_str (3), +.BR xdr_yppasswd (3), +.BR xdr_ypreq_key (3), +.BR xdr_ypreq_nokey (3), +.BR xdr_ypresp_all (3), +.BR xdr_ypresp_all_seq (3), +.BR xdr_ypresp_key_val (3), +.BR xdr_ypresp_maplist (3), +.BR xdr_ypresp_master (3), +.BR xdr_ypresp_order (3), +.BR xdr_ypresp_val (3), +.BR xdr_ypstat (3), +.BR xdr_ypupdate_args (3), +.BR yp_all (3), +.BR yp_bind (3), +.BR yperr_string (3), +.BR yp_first (3), +.BR yp_get_default_domain (3), +.BR yp_maplist (3), +.BR yp_master (3), +.BR yp_match (3), +.BR yp_next (3), +.BR yp_order (3), +.BR ypprot_err (3), +.BR yp_unbind (3), +.BR yp_update (3) diff --git a/man/man3/ungetc.3 b/man/man3/ungetc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/ungetc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/ungetwc.3 b/man/man3/ungetwc.3 new file mode 100644 index 0000000..8892e31 --- /dev/null +++ b/man/man3/ungetwc.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ungetwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ungetwc \- push back a wide character onto a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR ungetwc () +function is the wide-character equivalent of the +.BR ungetc (3) +function. +It pushes back a wide character onto +.I stream +and returns it. +.P +If +.I wc +is +.BR WEOF , +it returns +.BR WEOF . +If +.I wc +is an invalid wide character, +it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +.P +If +.I wc +is a valid wide character, it is pushed back onto the stream +and thus becomes available for future wide-character read operations. +The file-position indicator is decremented by one or more. +The end-of-file +indicator is cleared. +The backing storage of the file is not affected. +.P +Note: +.I wc +need not be the last wide-character read from the stream; +it can be any other valid wide character. +.P +If the implementation supports multiple push-back operations in a row, the +pushed-back wide characters will be read in reverse order; however, only one +level of push-back is guaranteed. +.SH RETURN VALUE +The +.BR ungetwc () +function returns +.I wc +when successful, or +.B WEOF +upon +failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ungetwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR ungetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR fgetwc (3) diff --git a/man/man3/unlocked_stdio.3 b/man/man3/unlocked_stdio.3 new file mode 100644 index 0000000..d0c1650 --- /dev/null +++ b/man/man3/unlocked_stdio.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH unlocked_stdio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getc_unlocked, getchar_unlocked, putc_unlocked, +putchar_unlocked \- nonlocking stdio functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int getc_unlocked(FILE *" stream ); +.B "int getchar_unlocked(void);" +.BI "int putc_unlocked(int " c ", FILE *" stream ); +.BI "int putchar_unlocked(int " c ); +.P +.BI "void clearerr_unlocked(FILE *" stream ); +.BI "int feof_unlocked(FILE *" stream ); +.BI "int ferror_unlocked(FILE *" stream ); +.BI "int fileno_unlocked(FILE *" stream ); +.BI "int fflush_unlocked(FILE *_Nullable " stream ); +.P +.BI "int fgetc_unlocked(FILE *" stream ); +.BI "int fputc_unlocked(int " c ", FILE *" stream ); +.P +.BI "size_t fread_unlocked(void " ptr "[restrict ." size " * ." n ], +.BI " size_t " size ", size_t " n , +.BI " FILE *restrict " stream ); +.BI "size_t fwrite_unlocked(const void " ptr "[restrict ." size " * ." n ], +.BI " size_t " size ", size_t " n , +.BI " FILE *restrict " stream ); +.P +.BI "char *fgets_unlocked(char " s "[restrict ." n "], int " n \ +", FILE *restrict " stream ); +.BI "int fputs_unlocked(const char *restrict " s ", FILE *restrict " stream ); +.P +.B #include <wchar.h> +.P +.BI "wint_t getwc_unlocked(FILE *" stream ); +.B "wint_t getwchar_unlocked(void);" +.BI "wint_t fgetwc_unlocked(FILE *" stream ); +.P +.BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwchar_unlocked(wchar_t " wc ); +.P +.BI "wchar_t *fgetws_unlocked(wchar_t " ws "[restrict ." n "], int " n , +.BI " FILE *restrict " stream ); +.BI "int fputws_unlocked(const wchar_t *restrict " ws , +.BI " FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR \%getc_unlocked (), +.BR \%getchar_unlocked (), +.BR \%putc_unlocked (), +.BR \%putchar_unlocked (): +.nf + /* glibc >= 2.24: */ _POSIX_C_SOURCE >= 199309L + || /* glibc <= 2.23: */ _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR \%clearerr_unlocked (), +.BR \%feof_unlocked (), +.BR \%ferror_unlocked (), +.BR \%fileno_unlocked (), +.BR \%fflush_unlocked (), +.BR \%fgetc_unlocked (), +.BR \%fputc_unlocked (), +.BR \%fread_unlocked (), +.BR \%fwrite_unlocked (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR \%fgets_unlocked (), +.BR \%fputs_unlocked (), +.BR \%getwc_unlocked (), +.BR \%getwchar_unlocked (), +.BR \%fgetwc_unlocked (), +.BR \%fputwc_unlocked (), +.BR \%putwchar_unlocked (), +.BR \%fgetws_unlocked (), +.BR \%fputws_unlocked (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +Each of these functions has the same behavior as its counterpart +without the "_unlocked" suffix, except that they do not use locking +(they do not set locks themselves, and do not test for the presence +of locks set by others) and hence are thread-unsafe. +See +.BR flockfile (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getc_unlocked (), +.BR putc_unlocked (), +.BR clearerr_unlocked (), +.BR fflush_unlocked (), +.BR fgetc_unlocked (), +.BR fputc_unlocked (), +.BR fread_unlocked (), +.BR fwrite_unlocked (), +.BR fgets_unlocked (), +.BR fputs_unlocked (), +.BR getwc_unlocked (), +.BR fgetwc_unlocked (), +.BR fputwc_unlocked (), +.BR putwc_unlocked (), +.BR fgetws_unlocked (), +.BR fputws_unlocked () +T} Thread safety T{ +.na +.nh +MT-Safe race:stream +T} +T{ +.na +.nh +.BR getchar_unlocked (), +.BR getwchar_unlocked () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:stdin +T} +T{ +.na +.nh +.BR putchar_unlocked (), +.BR putwchar_unlocked () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:stdout +T} +T{ +.na +.nh +.BR feof_unlocked (), +.BR ferror_unlocked (), +.BR fileno_unlocked () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR getc_unlocked () +.TQ +.BR getchar_unlocked () +.TQ +.BR putc_unlocked () +.TQ +.BR putchar_unlocked () +POSIX.1-2008. +.TP +Others: +None. +.SH HISTORY +.TP +.BR getc_unlocked () +.TQ +.BR getchar_unlocked () +.TQ +.BR putc_unlocked () +.TQ +.BR putchar_unlocked () +POSIX.1-2001. +.\" E.g., in HP-UX 10.0. In HP-UX 10.30 they are called obsolescent, and +.\" moved to a compatibility library. +.\" Available in HP-UX 10.0: clearerr_unlocked, fclose_unlocked, +.\" feof_unlocked, ferror_unlocked, fflush_unlocked, fgets_unlocked, +.\" fgetwc_unlocked, fgetws_unlocked, fileno_unlocked, fputs_unlocked, +.\" fputwc_unlocked, fputws_unlocked, fread_unlocked, fseek_unlocked, +.\" ftell_unlocked, fwrite_unlocked, getc_unlocked, getchar_unlocked, +.\" getw_unlocked, getwc_unlocked, getwchar_unlocked, putc_unlocked, +.\" putchar_unlocked, puts_unlocked, putws_unlocked, putw_unlocked, +.\" putwc_unlocked, putwchar_unlocked, rewind_unlocked, setvbuf_unlocked, +.\" ungetc_unlocked, ungetwc_unlocked. +.SH SEE ALSO +.BR flockfile (3), +.BR stdio (3) diff --git a/man/man3/unlockpt.3 b/man/man3/unlockpt.3 new file mode 100644 index 0000000..ccdbf4f --- /dev/null +++ b/man/man3/unlockpt.3 @@ -0,0 +1,84 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH unlockpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unlockpt \- unlock a pseudoterminal master/slave pair +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE +.B #include <stdlib.h> +.P +.BI "int unlockpt(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR unlockpt (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR unlockpt () +function unlocks the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by the file descriptor +.IR fd . +.P +.BR unlockpt () +should be called before opening the slave side of a pseudoterminal. +.SH RETURN VALUE +When successful, +.BR unlockpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I fd +argument is not a file descriptor open for writing. +.TP +.B EINVAL +The +.I fd +argument is not associated with a master pseudoterminal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR unlockpt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/unsetenv.3 b/man/man3/unsetenv.3 new file mode 100644 index 0000000..19ec56c --- /dev/null +++ b/man/man3/unsetenv.3 @@ -0,0 +1 @@ +.so man3/setenv.3 diff --git a/man/man3/updwtmp.3 b/man/man3/updwtmp.3 new file mode 100644 index 0000000..7a2c8f9 --- /dev/null +++ b/man/man3/updwtmp.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org> +.\" Created Wed Jul 2 23:27:34 ART 1997 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Added info on availability, aeb, 971207 +.\" Added -lutil remark, 030718 +.\" 2008-07-02, mtk, document updwtmpx() +.\" +.TH updwtmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +updwtmp, logwtmp \- append an entry to the wtmp file +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include <utmp.h> +.P +.BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut ); +.BI "void logwtmp(const char *" line ", const char *" name \ +", const char *" host ); +.fi +.SH DESCRIPTION +.BR updwtmp () +appends the utmp structure +.I ut +to the wtmp file. +.P +.BR logwtmp () +constructs a utmp structure using +.IR line ", " name ", " host , +current time, and current process ID. +Then it calls +.BR updwtmp () +to append the structure to the wtmp file. +.SH FILES +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR updwtmp (), +.BR logwtmp () +T} Thread safety MT-Unsafe sig:ALRM timer +.TE +.SH VERSIONS +For consistency with the other "utmpx" functions (see +.BR getutxent (3)), +glibc provides (since glibc 2.1): +.P +.in +4n +.EX +.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" +.B #include <utmpx.h> +.BI "void updwtmpx (const char *" wtmpx_file ", const struct utmpx *" utx ); +.EE +.in +.P +This function performs the same task as +.BR updwtmp (), +but differs in that it takes a +.I utmpx +structure as its last argument. +.SH STANDARDS +None. +.SH HISTORY +Solaris, NetBSD. +.SH SEE ALSO +.BR getutxent (3), +.BR wtmp (5) diff --git a/man/man3/updwtmpx.3 b/man/man3/updwtmpx.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man/man3/updwtmpx.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man/man3/uselocale.3 b/man/man3/uselocale.3 new file mode 100644 index 0000000..0856b9d --- /dev/null +++ b/man/man3/uselocale.3 @@ -0,0 +1,102 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH uselocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uselocale \- set/get the locale for the calling thread +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.BI "locale_t uselocale(locale_t " newloc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR uselocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR uselocale () +function sets the current locale for the calling thread, +and returns the thread's previously current locale. +After a successful call to +.BR uselocale (), +any calls by this thread to functions that depend on the locale +will operate as though the locale has been set to +.IR newloc . +.P +The +.I newloc +argument can have one of the following values: +.TP +A handle returned by a call to \fBnewlocale\fP(3) or \fBduplocale\fP(3) +The calling thread's current locale is set to the specified locale. +.TP +The special locale object handle \fBLC_GLOBAL_LOCALE\fP +The calling thread's current locale is set to the global locale determined by +.BR setlocale (3). +.TP +.I "(locale_t) 0" +The calling thread's current locale is left unchanged +(and the current locale is returned as the function result). +.SH RETURN VALUE +On success, +.BR uselocale () +returns the locale handle that was set by the previous call to +.BR uselocale () +in this thread, or +.B LC_GLOBAL_LOCALE +if there was no such previous call. +On error, it returns +.IR "(locale_t)\ 0" , +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I newloc +does not refer to a valid locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +POSIX.1-2008. +.SH NOTES +Unlike +.BR setlocale (3), +.BR uselocale () +does not allow selective replacement of individual locale categories. +To employ a locale that differs in only a few categories from the current +locale, use calls to +.BR duplocale (3) +and +.BR newlocale (3) +to obtain a locale object equivalent to the current locale and +modify the desired categories in that object. +.SH EXAMPLES +See +.BR newlocale (3) +and +.BR duplocale (3). +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/usleep.3 b/man/man3/usleep.3 new file mode 100644 index 0000000..fef133e --- /dev/null +++ b/man/man3/usleep.3 @@ -0,0 +1,123 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-04-01 by aeb +.\" Modified 2003-07-23 by aeb +.\" +.TH usleep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +usleep \- suspend execution for microsecond intervals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <unistd.h>" +.P +.BI "int usleep(useconds_t " usec ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR usleep (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR usleep () +function suspends execution of the calling thread for +(at least) \fIusec\fP microseconds. +The sleep may be lengthened slightly +by any system activity or by the time spent processing the call or by the +granularity of system timers. +.SH RETURN VALUE +The +.BR usleep () +function returns 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusec\fP is greater than or equal to 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR usleep () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +POSIX.1-2001 declares it obsolete, suggesting +.BR nanosleep (2) +instead. +Removed in POSIX.1-2008. +.P +On the original BSD implementation, +and before glibc 2.2.2, the return type of this function is +.IR void . +The POSIX version returns +.IR int , +and this is also the prototype used since glibc 2.2.2. +.P +Only the +.B EINVAL +error return is documented by SUSv2 and POSIX.1-2001. +.SH CAVEATS +The interaction of this function with the +.B SIGALRM +signal, and with other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR ualarm (3) +is unspecified. +.SH SEE ALSO +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR sleep (3), +.BR ualarm (3), +.BR useconds_t (3type), +.BR time (7) diff --git a/man/man3/utmpname.3 b/man/man3/utmpname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/utmpname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/utmpxname.3 b/man/man3/utmpxname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/utmpxname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/va_arg.3 b/man/man3/va_arg.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_arg.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_copy.3 b/man/man3/va_copy.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_copy.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_end.3 b/man/man3/va_end.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_end.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_start.3 b/man/man3/va_start.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_start.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/valloc.3 b/man/man3/valloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/valloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/vasprintf.3 b/man/man3/vasprintf.3 new file mode 100644 index 0000000..5a8753a --- /dev/null +++ b/man/man3/vasprintf.3 @@ -0,0 +1 @@ +.so man3/asprintf.3 diff --git a/man/man3/vdprintf.3 b/man/man3/vdprintf.3 new file mode 100644 index 0000000..fa36f35 --- /dev/null +++ b/man/man3/vdprintf.3 @@ -0,0 +1 @@ +.so man3/dprintf.3 diff --git a/man/man3/verr.3 b/man/man3/verr.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/verr.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/verrx.3 b/man/man3/verrx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/verrx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/versionsort.3 b/man/man3/versionsort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/versionsort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/vfprintf.3 b/man/man3/vfprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vfprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vfscanf.3 b/man/man3/vfscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/vfscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/vfwprintf.3 b/man/man3/vfwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vfwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/vlimit.3 b/man/man3/vlimit.3 new file mode 100644 index 0000000..58a817b --- /dev/null +++ b/man/man3/vlimit.3 @@ -0,0 +1,3 @@ +.so man2/getrlimit.2 +.\" No new programs should use vlimit(3). +.\" getrlimit(2) briefly discusses vlimit(3), so point the user there. diff --git a/man/man3/vprintf.3 b/man/man3/vprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vscanf.3 b/man/man3/vscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/vscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/vsnprintf.3 b/man/man3/vsnprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vsnprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vsprintf.3 b/man/man3/vsprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vsprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vsscanf.3 b/man/man3/vsscanf.3 new file mode 100644 index 0000000..8f5ebc1 --- /dev/null +++ b/man/man3/vsscanf.3 @@ -0,0 +1 @@ +.so man3/sscanf.3 diff --git a/man/man3/vswprintf.3 b/man/man3/vswprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vswprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/vsyslog.3 b/man/man3/vsyslog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/vsyslog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/vtimes.3 b/man/man3/vtimes.3 new file mode 100644 index 0000000..4097ab7 --- /dev/null +++ b/man/man3/vtimes.3 @@ -0,0 +1,3 @@ +.so man2/getrusage.2 +.\" No new programs should use vtimes(3). +.\" getrusage(2) briefly discusses vtimes(3), so point the user there. diff --git a/man/man3/vwarn.3 b/man/man3/vwarn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/vwarn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/vwarnx.3 b/man/man3/vwarnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/vwarnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/vwprintf.3 b/man/man3/vwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/warn.3 b/man/man3/warn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/warn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/warnx.3 b/man/man3/warnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/warnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/wcpcpy.3 b/man/man3/wcpcpy.3 new file mode 100644 index 0000000..8d80953 --- /dev/null +++ b/man/man3/wcpcpy.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcpcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcpcpy \- copy a wide-character string, returning a pointer to its end +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcpcpy(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcpcpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcpcpy () +function is the wide-character equivalent of the +.BR stpcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there +is room for at least +.I wcslen(src)+1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcpcpy () +returns a pointer to the end of the wide-character string +.IR dest , +that is, a pointer to the terminating null wide character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcpcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH SEE ALSO +.BR strcpy (3), +.BR wcscpy (3) diff --git a/man/man3/wcpncpy.3 b/man/man3/wcpncpy.3 new file mode 100644 index 0000000..b63d3d0 --- /dev/null +++ b/man/man3/wcpncpy.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcpncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcpncpy \- copy a fixed-size string of wide characters, +returning a pointer to its end +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcpncpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcpncpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcpncpy () +function is the wide-character equivalent +of the +.BR stpncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length +.I wcslen(src) +is smaller than +.IR n , +the remaining wide characters in the array pointed to +by +.I dest +are filled with L\[aq]\e0\[aq] characters. +If the length +.I wcslen(src) +is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will +not be L\[aq]\e0\[aq] terminated. +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcpncpy () +returns a pointer to the last wide character written, that is, +.IR dest + n \-1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcpncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH SEE ALSO +.BR stpncpy (3), +.BR wcsncpy (3) diff --git a/man/man3/wcrtomb.3 b/man/man3/wcrtomb.3 new file mode 100644 index 0000000..9e96b92 --- /dev/null +++ b/man/man3/wcrtomb.3 @@ -0,0 +1,144 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcrtomb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcrtomb \- convert a wide character to a multibyte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \ +", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is +not NULL and +.I wc +is not a null wide character (L\[aq]\e0\[aq]). +In this case, the +.BR wcrtomb () +function +converts the wide character +.I wc +to its multibyte representation and stores it +at the beginning of the character +array pointed to by +.IR s . +It updates the shift state +.IR *ps , +and +returns the length of said multibyte representation, +that is, the number of bytes +written at +.IR s . +.P +A different case is when +.I s +is not NULL, +but +.I wc +is a null wide character (L\[aq]\e0\[aq]). +In this case, the +.BR wcrtomb () +function stores at +the character array pointed to by +.I s +the shift sequence needed to +bring +.I *ps +back to the initial state, +followed by a \[aq]\e0\[aq] byte. +It updates the shift state +.I *ps +(i.e., brings +it into the initial state), +and returns the length of the shift sequence plus +one, that is, the number of bytes written at +.IR s . +.P +A third case is when +.I s +is NULL. +In this case, +.I wc +is ignored, +and the function effectively returns +.P +.in +4n +.EX +wcrtomb(buf, L\[aq]\e0\[aq], ps) +.EE +.in +.P +where +.I buf +is an internal anonymous buffer. +.P +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcrtomb () +function is used instead. +.SH RETURN VALUE +The +.BR wcrtomb () +function returns the number of +bytes that have been or would +have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according to the current locale), +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcrtomb () +T} Thread safety MT-Unsafe race:wcrtomb/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcrtomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR mbsinit (3), +.BR wcsrtombs (3) diff --git a/man/man3/wcscasecmp.3 b/man/man3/wcscasecmp.3 new file mode 100644 index 0000000..b9d4c21 --- /dev/null +++ b/man/man3/wcscasecmp.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcscasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscasecmp \- compare two wide-character strings, ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcscasecmp (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcscasecmp () +function is the wide-character equivalent of the +.BR strcasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string pointed to by +.IR s2 , +ignoring +case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcscasecmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal except for case distinctions. +It returns a +positive integer if +.I s1 +is greater than +.IR s2 , +ignoring case. +It +returns a negative integer if +.I s1 +is smaller +than +.IR s2 , +ignoring case. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH NOTES +The behavior of +.BR wcscasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strcasecmp (3), +.BR wcscmp (3) diff --git a/man/man3/wcscat.3 b/man/man3/wcscat.3 new file mode 100644 index 0000000..5aecad3 --- /dev/null +++ b/man/man3/wcscat.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscat \- concatenate two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcscat(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.SH DESCRIPTION +The +.BR wcscat () +function is the wide-character equivalent +of the +.BR strcat (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the end of the wide-character string pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.IR wcslen(dest) + wcslen(src) +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcat (3), +.BR wcpcpy (3), +.BR wcscpy (3), +.BR wcsncat (3) diff --git a/man/man3/wcschr.3 b/man/man3/wcschr.3 new file mode 100644 index 0000000..8b05e14 --- /dev/null +++ b/man/man3/wcschr.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcschr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcschr \- search a wide character in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcschr () +function is the wide-character equivalent +of the +.BR strchr (3) +function. +It searches the first occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcschr () +function returns a pointer to the first occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcschr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strchr (3), +.BR wcspbrk (3), +.BR wcsrchr (3), +.BR wcsstr (3), +.BR wmemchr (3) diff --git a/man/man3/wcscmp.3 b/man/man3/wcscmp.3 new file mode 100644 index 0000000..06c1f56 --- /dev/null +++ b/man/man3/wcscmp.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscmp \- compare two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.SH DESCRIPTION +The +.BR wcscmp () +function is the wide-character equivalent +of the +.BR strcmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 . +.SH RETURN VALUE +The +.BR wcscmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal. +It returns an integer greater than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcmp (3), +.BR wcscasecmp (3), +.BR wmemcmp (3) diff --git a/man/man3/wcscpy.3 b/man/man3/wcscpy.3 new file mode 100644 index 0000000..5607bd7 --- /dev/null +++ b/man/man3/wcscpy.3 @@ -0,0 +1,72 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscpy \- copy a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcscpy(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.SH DESCRIPTION +The +.BR wcscpy () +function is the wide-character equivalent +of the +.BR strcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there is +room for at least +.I wcslen(src)+1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcpy (3), +.BR wcpcpy (3), +.BR wcscat (3), +.BR wcsdup (3), +.BR wmemcpy (3) diff --git a/man/man3/wcscspn.3 b/man/man3/wcscspn.3 new file mode 100644 index 0000000..ddffa22 --- /dev/null +++ b/man/man3/wcscspn.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscspn \- search a wide-character string for any of a set of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); +.fi +.SH DESCRIPTION +The +.BR wcscspn () +function is the wide-character equivalent +of the +.BR strcspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters not listed in +.IR reject . +In +other words, it searches for the first occurrence in the wide-character +string +.I wcs +of any of the characters in the wide-character string +.IR reject . +.SH RETURN VALUE +The +.BR wcscspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters not +listed in +.IR reject . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of any of the characters in +the wide-character string +.IR reject , +or +.I wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcspn (3), +.BR wcspbrk (3), +.BR wcsspn (3) diff --git a/man/man3/wcsdup.3 b/man/man3/wcsdup.3 new file mode 100644 index 0000000..41131a1 --- /dev/null +++ b/man/man3/wcsdup.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsdup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsdup \- duplicate a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcsdup(const wchar_t *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsdup (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsdup () +function is the wide-character equivalent +of the +.BR strdup (3) +function. +It allocates and returns a new wide-character string whose initial +contents is a duplicate of the wide-character string pointed to by +.IR s . +.P +Memory for the new wide-character string is +obtained with +.BR malloc (3), +and should be freed with +.BR free (3). +.SH RETURN VALUE +On success, +.BR wcsdup () +returns a pointer to the new wide-character string. +On error, it returns NULL, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsdup () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +libc5, glibc 2.0. +.SH SEE ALSO +.BR strdup (3), +.BR wcscpy (3) diff --git a/man/man3/wcslen.3 b/man/man3/wcslen.3 new file mode 100644 index 0000000..4e96b94 --- /dev/null +++ b/man/man3/wcslen.3 @@ -0,0 +1,65 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcslen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcslen \- determine the length of a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcslen(const wchar_t *" s ); +.fi +.SH DESCRIPTION +The +.BR wcslen () +function is the wide-character equivalent +of the +.BR strlen (3) +function. +It determines the length of the wide-character string pointed to +by +.IR s , +excluding the terminating null wide character (L\[aq]\e0\[aq]). +.SH RETURN VALUE +The +.BR wcslen () +function returns the +number of wide characters in +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcslen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +In cases where the input buffer may not contain +a terminating null wide character, +.BR wcsnlen (3) +should be used instead. +.SH SEE ALSO +.BR strlen (3) diff --git a/man/man3/wcsncasecmp.3 b/man/man3/wcsncasecmp.3 new file mode 100644 index 0000000..dde8ec1 --- /dev/null +++ b/man/man3/wcsncasecmp.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsncasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wcsncasecmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], s\ +ize_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsncasecmp (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsncasecmp () +function is the wide-character equivalent of the +.BR strncasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string +pointed to by +.IR s2 , +but at most +.I n +wide characters from each string, ignoring case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcsncasecmp () +function returns zero +if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal except +for case distinctions. +It returns a positive integer if truncated +.I s1 +is +greater than truncated +.IR s2 , +ignoring case. +It returns a negative integer +if truncated +.I s1 +is smaller than truncated +.IR s2 , +ignoring case. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH NOTES +The behavior of +.BR wcsncasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strncasecmp (3), +.BR wcsncmp (3) diff --git a/man/man3/wcsncat.3 b/man/man3/wcsncat.3 new file mode 100644 index 0000000..77181d2 --- /dev/null +++ b/man/man3/wcsncat.3 @@ -0,0 +1,72 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncat \- concatenate two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcsncat(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncat () +function is the wide-character equivalent of the +.BR strncat (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.I src +to the end of the wide-character string pointed +to by +.IR dest , +and adds a terminating null wide character (L\[aq]\e0\[aq]). +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.IR wcslen(dest) + n +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncat (3), +.BR wcscat (3) diff --git a/man/man3/wcsncmp.3 b/man/man3/wcsncmp.3 new file mode 100644 index 0000000..2768894 --- /dev/null +++ b/man/man3/wcsncmp.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncmp \- compare two fixed-size wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wcsncmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncmp () +function is the wide-character equivalent of the +.BR strncmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 , +but at most +.I n +wide +characters from each string. +In each string, the comparison extends only up +to the first occurrence of a null wide character (L\[aq]\e0\[aq]), if any. +.SH RETURN VALUE +The +.BR wcsncmp () +function returns zero if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal. +It returns an integer greater than zero if at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding wide-character +.I s1[i] +is +greater than +.IR s2[i] . +It returns an integer less than zero if at the first +differing position +.I i +.RI ( i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncmp (3), +.BR wcsncasecmp (3) diff --git a/man/man3/wcsncpy.3 b/man/man3/wcsncpy.3 new file mode 100644 index 0000000..841f356 --- /dev/null +++ b/man/man3/wcsncpy.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncpy \- copy a fixed-size string of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcsncpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncpy () +function is the wide-character equivalent of the +.BR strncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length \fIwcslen(src)\fP is smaller than +.IR n , +the remaining wide characters in the array +pointed to by +.I dest +are filled +with null wide characters. +If the length \fIwcslen(src)\fP is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will not be terminated by a null wide character. +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncpy (3) diff --git a/man/man3/wcsnlen.3 b/man/man3/wcsnlen.3 new file mode 100644 index 0000000..e2c4116 --- /dev/null +++ b/man/man3/wcsnlen.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsnlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsnlen \- determine the length of a fixed-size wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcsnlen(const wchar_t " s [. maxlen "], size_t " maxlen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsnlen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsnlen () +function is the wide-character equivalent +of the +.BR strnlen (3) +function. +It returns the number of wide-characters in the string pointed to by +.IR s , +not including the terminating null wide character (L\[aq]\e0\[aq]), +but at most +.I maxlen +wide characters (note: this parameter is not a byte count). +In doing this, +.BR wcsnlen () +looks at only the first +.I maxlen +wide characters at +.I s +and never beyond +.IR s[maxlen\-1] . +.SH RETURN VALUE +The +.BR wcsnlen () +function returns +.IR wcslen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null wide character among the +first +.I maxlen +wide characters pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsnlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR strnlen (3), +.BR wcslen (3) diff --git a/man/man3/wcsnrtombs.3 b/man/man3/wcsnrtombs.3 new file mode 100644 index 0000000..1ef6581 --- /dev/null +++ b/man/man3/wcsnrtombs.3 @@ -0,0 +1,189 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsnrtombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsnrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcsnrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " nwc ", size_t " len ", \ +mbstate_t *restrict " ps ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsnrtombs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsnrtombs () +function is like the +.BR wcsrtombs (3) +function, +except that the number of wide characters to be converted, +starting at +.IR *src , +is limited to +.IR nwc . +.P +If +.I dest +is not NULL, +the +.BR wcsnrtombs () +function converts +at most +.I nwc +wide characters from +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +.I nwc +wide characters have been +converted without encountering a null wide character (L\[aq]\e0\[aq]), +or the length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, and the number of bytes written +to +.I dest +is returned. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (which has the side effect of bringing back +.I *ps +to the initial state). +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), is +returned. +.P +If +.I dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, +except that the converted bytes are not written out to memory, and that +no destination length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsnrtombs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsnrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which +could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsnrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsnrtombs/!ps +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR wcsnrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcsrtombs (3) diff --git a/man/man3/wcspbrk.3 b/man/man3/wcspbrk.3 new file mode 100644 index 0000000..2b3286e --- /dev/null +++ b/man/man3/wcspbrk.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcspbrk 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcspbrk \- search a wide-character string for any of a set of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcspbrk () +function is the wide-character equivalent +of the +.BR strpbrk (3) +function. +It searches for the first occurrence in the wide-character +string pointed to by +.I wcs +of any of the +characters in the wide-character +string pointed to by +.IR accept . +.SH RETURN VALUE +The +.BR wcspbrk () +function returns a pointer to the first occurrence in +.I wcs +of any of the characters listed in +.IR accept . +If +.I wcs +contains none of these characters, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcspbrk () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strpbrk (3), +.BR wcschr (3), +.BR wcscspn (3) diff --git a/man/man3/wcsrchr.3 b/man/man3/wcsrchr.3 new file mode 100644 index 0000000..05b0e38 --- /dev/null +++ b/man/man3/wcsrchr.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsrchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsrchr \- search a wide character in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcsrchr () +function is the wide-character equivalent +of the +.BR strrchr (3) +function. +It searches the last occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcsrchr () +function returns a pointer to the last occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsrchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strrchr (3), +.BR wcschr (3) diff --git a/man/man3/wcsrtombs.3 b/man/man3/wcsrtombs.3 new file mode 100644 index 0000000..9235dfb --- /dev/null +++ b/man/man3/wcsrtombs.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsrtombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcsrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " len ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +the +.BR wcsrtombs () +function converts +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +The length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, +and the number of bytes written to +.I dest +is returned. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (L\[aq]\e0\[aq]), +which has the side effect of bringing back +.I *ps +to the initial state. +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), +is returned. +.P +If +.I dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, except that the converted bytes +are not written out to memory, and that +no length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsrtombs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered +which could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsrtombs/!ps +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcsrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcrtomb (3), +.BR wcsnrtombs (3), +.BR wcstombs (3) diff --git a/man/man3/wcsspn.3 b/man/man3/wcsspn.3 new file mode 100644 index 0000000..1a66e09 --- /dev/null +++ b/man/man3/wcsspn.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsspn \- get length of a prefix wide-character substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "size_t wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcsspn () +function is the wide-character equivalent of the +.BR strspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters listed in +.IR accept . +In other +words, it searches for the first occurrence in the wide-character string +.I wcs +of a wide-character not contained in the wide-character string +.IR accept . +.SH RETURN VALUE +The +.BR wcsspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters listed +in +.IR accept . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of a wide-character not +contained in the wide-character string +.IR accept , +or +.I wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strspn (3), +.BR wcscspn (3) diff --git a/man/man3/wcsstr.3 b/man/man3/wcsstr.3 new file mode 100644 index 0000000..95e9359 --- /dev/null +++ b/man/man3/wcsstr.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsstr \- locate a substring in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); +.fi +.SH DESCRIPTION +The +.BR wcsstr () +function is the wide-character equivalent of the +.BR strstr (3) +function. +It searches for the first occurrence of the wide-character string +.I needle +(without its terminating null wide character (L\[aq]\e0\[aq])) +as a substring in the wide-character string +.IR haystack . +.SH RETURN VALUE +The +.BR wcsstr () +function returns a pointer to the first occurrence of +.I needle +in +.IR haystack . +It returns NULL if +.I needle +does not occur +as a substring in +.IR haystack . +.P +Note the special case: +If +.I needle +is the empty wide-character string, +the return value is always +.I haystack +itself. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsstr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strstr (3), +.BR wcschr (3) diff --git a/man/man3/wcstoimax.3 b/man/man3/wcstoimax.3 new file mode 100644 index 0000000..ebd8691 --- /dev/null +++ b/man/man3/wcstoimax.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH wcstoimax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstoimax, wcstoumax \- convert wide-character string to integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stddef.h> +.B #include <inttypes.h> +.P +.BI "intmax_t wcstoimax(const wchar_t *restrict " nptr , +.BI " wchar_t **restrict " endptr ", int " base ); +.BI "uintmax_t wcstoumax(const wchar_t *restrict " nptr , +.BI " wchar_t **restrict " endptr ", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR wcstol (3) +and +.BR wcstoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstoimax (), +.BR wcstoumax () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtoimax (3), +.BR strtoumax (3), +.\" FIXME . the pages referred to by the following xrefs are not yet written +.BR wcstol (3), +.BR wcstoul (3) diff --git a/man/man3/wcstok.3 b/man/man3/wcstok.3 new file mode 100644 index 0000000..f2d19c8 --- /dev/null +++ b/man/man3/wcstok.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcstok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstok \- split wide-character string into tokens +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wcstok(wchar_t *restrict " wcs \ +", const wchar_t *restrict " delim , +.BI " wchar_t **restrict " ptr ); +.fi +.SH DESCRIPTION +The +.BR wcstok () +function is the wide-character equivalent of the +.BR strtok (3) +function, +with an added argument to make it multithread-safe. +It can be used +to split a wide-character string +.I wcs +into tokens, where a token is +defined as a substring not containing any wide-characters from +.IR delim . +.P +The search starts at +.IR wcs , +if +.I wcs +is not NULL, +or at +.IR *ptr , +if +.I wcs +is NULL. +First, any delimiter wide-characters are skipped, that is, the +pointer is advanced beyond any wide-characters which occur in +.IR delim . +If the end of the wide-character string is now +reached, +.BR wcstok () +returns NULL, to indicate that no tokens +were found, and stores an appropriate value in +.IR *ptr , +so that subsequent calls to +.BR wcstok () +will continue to return NULL. +Otherwise, the +.BR wcstok () +function recognizes the beginning of a token +and returns a pointer to it, but before doing that, it zero-terminates the +token by replacing the next wide-character which occurs in +.I delim +with +a null wide character (L\[aq]\e0\[aq]), +and it updates +.I *ptr +so that subsequent calls will +continue searching after the end of recognized token. +.SH RETURN VALUE +The +.BR wcstok () +function returns a pointer to the next token, +or NULL if no further token was found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstok () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The original +.I wcs +wide-character string is destructively modified during +the operation. +.SH EXAMPLES +The following code loops over the tokens contained in a wide-character string. +.P +.EX +wchar_t *wcs = ...; +wchar_t *token; +wchar_t *state; +for (token = wcstok(wcs, L" \et\en", &state); + token != NULL; + token = wcstok(NULL, L" \et\en", &state)) { + ... +} +.EE +.SH SEE ALSO +.BR strtok (3), +.BR wcschr (3) diff --git a/man/man3/wcstombs.3 b/man/man3/wcstombs.3 new file mode 100644 index 0000000..4d3ef56 --- /dev/null +++ b/man/man3/wcstombs.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcstombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "size_t wcstombs(char " dest "[restrict ." n "], \ +const wchar_t *restrict " src , +.BI " size_t " n ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, the +.BR wcstombs () +function converts +the wide-character string +.I src +to a multibyte string starting at +.IR dest . +At most +.I n +bytes are written to +.IR dest . +The sequence of characters placed in +.I dest +begins in the initial shift state. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I (size_t)\ \-1 +is returned. +.IP \[bu] +The length limit forces a stop. +In this case, the number of bytes written to +.I dest +is returned, but the shift state at this point is lost. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (L\[aq]\e0\[aq]). +In this case, the conversion ends in the initial shift state. +The number of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), is returned. +.P +The programmer must ensure that there is room for at least +.I n +bytes +at +.IR dest . +.P +If +.I dest +is NULL, +.I n +is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, +and no length limit exists. +.P +In order to avoid the case 2 above, the programmer should make sure +.I n +is greater than or equal to +.IR "wcstombs(NULL,src,0)+1" . +.SH RETURN VALUE +The +.BR wcstombs () +function returns the number of bytes that make up the +converted part of a multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which could not be +converted, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstombs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The function +.BR wcsrtombs (3) +provides a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcstombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcsrtombs (3), +.BR wctomb (3) diff --git a/man/man3/wcstoumax.3 b/man/man3/wcstoumax.3 new file mode 100644 index 0000000..f3aa5d2 --- /dev/null +++ b/man/man3/wcstoumax.3 @@ -0,0 +1 @@ +.so man3/wcstoimax.3 diff --git a/man/man3/wcswidth.3 b/man/man3/wcswidth.3 new file mode 100644 index 0000000..b46fc52 --- /dev/null +++ b/man/man3/wcswidth.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcswidth 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcswidth \- determine columns needed for a fixed-size wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <wchar.h> +.P +.BI "int wcswidth(const wchar_t *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcswidth () +function returns the +number of columns needed to represent +the wide-character string pointed to by +.IR s , +but at most +.I n +wide +characters. +If a nonprintable wide character occurs among these characters, +\-1 is returned. +.SH RETURN VALUE +The +.BR wcswidth () +function +returns the number of column positions for the +wide-character string +.IR s , +truncated to at most length +.IR n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcswidth () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The behavior of +.BR wcswidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcwidth (3) diff --git a/man/man3/wctob.3 b/man/man3/wctob.3 new file mode 100644 index 0000000..b95ef37 --- /dev/null +++ b/man/man3/wctob.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctob \- try to represent a wide character as a single byte +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wctob(wint_t " c ); +.fi +.SH DESCRIPTION +The +.BR wctob () +function tests whether +the multibyte representation of the +wide character +.IR c , +starting in the initial state, consists of a single +byte. +If so, it is returned as an +.IR "unsigned char" . +.P +Never use this function. +It cannot help you in writing internationalized +programs. +Internationalized programs must never distinguish single-byte and +multibyte characters. +.SH RETURN VALUE +The +.BR wctob () +function returns the single-byte representation of +.IR c , +if it exists, or +.B EOF +otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctob () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctob () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function should never be used. +Internationalized programs must never +distinguish single-byte and multibyte characters. +Use either +.BR wctomb (3) +or the thread-safe +.BR wcrtomb (3) +instead. +.SH SEE ALSO +.BR btowc (3), +.BR wcrtomb (3), +.BR wctomb (3) diff --git a/man/man3/wctomb.3 b/man/man3/wctomb.3 new file mode 100644 index 0000000..33a688a --- /dev/null +++ b/man/man3/wctomb.3 @@ -0,0 +1,119 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctomb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctomb \- convert a wide character to a multibyte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int wctomb(char *" s ", wchar_t " wc ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, +the +.BR wctomb () +function converts the wide character +.I wc +to its multibyte representation and stores it at the beginning of +the character array pointed to by +.IR s . +It updates the shift state, which +is stored in a static anonymous variable +known only to the +.BR wctomb () +function, +and returns the length of said multibyte representation, +that is, the number of +bytes written at +.IR s . +.P +The programmer must ensure that there is +room for at least +.B MB_CUR_MAX +bytes at +.IR s . +.P +If +.I s +is NULL, the +.BR wctomb () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known only to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, +or zero if the encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR wctomb () +function +returns the number of bytes +that have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according +to the current locale), \-1 is returned. +.P +If +.I s +is NULL, the +.BR wctomb () +function returns nonzero if the +encoding has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctomb () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +The function +.BR wcrtomb (3) +provides +a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcrtomb (3), +.BR wcstombs (3) diff --git a/man/man3/wctrans.3 b/man/man3/wctrans.3 new file mode 100644 index 0000000..92a2409 --- /dev/null +++ b/man/man3/wctrans.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctrans 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctrans \- wide-character translation mapping +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "wctrans_t wctrans(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctrans_t +type represents a mapping +which can map a wide character to +another wide character. +Its nature is implementation-dependent, but the special +value +.I (wctrans_t)\ 0 +denotes an invalid mapping. +Nonzero +.I wctrans_t +values can be passed to the +.BR towctrans (3) +function to actually perform +the wide-character mapping. +.P +The +.BR wctrans () +function returns a mapping, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.P +.nf + "tolower" \- realizes the \fBtolower\fP(3) mapping + "toupper" \- realizes the \fBtoupper\fP(3) mapping +.fi +.SH RETURN VALUE +The +.BR wctrans () +function returns a mapping descriptor if the +.I name +is valid. +Otherwise, it returns +.IR "(wctrans_t)\ 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctrans () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towctrans (3) diff --git a/man/man3/wctype.3 b/man/man3/wctype.3 new file mode 100644 index 0000000..cf6ce26 --- /dev/null +++ b/man/man3/wctype.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctype \- wide-character classification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wctype.h> +.P +.BI "wctype_t wctype(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctype_t +type represents a property which a wide character may or +may not have. +In other words, it represents a class of wide characters. +This type's nature is implementation-dependent, but the special value +.I "(wctype_t) 0" +denotes an invalid property. +Nonzero +.I wctype_t +values +can be passed to the +.BR iswctype (3) +function +to actually test whether a given +wide character has the property. +.P +The +.BR wctype () +function returns a property, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.P +.nf + "alnum" \- realizes the \fBisalnum\fP(3) classification function + "alpha" \- realizes the \fBisalpha\fP(3) classification function + "blank" \- realizes the \fBisblank\fP(3) classification function + "cntrl" \- realizes the \fBiscntrl\fP(3) classification function + "digit" \- realizes the \fBisdigit\fP(3) classification function + "graph" \- realizes the \fBisgraph\fP(3) classification function + "lower" \- realizes the \fBislower\fP(3) classification function + "print" \- realizes the \fBisprint\fP(3) classification function + "punct" \- realizes the \fBispunct\fP(3) classification function + "space" \- realizes the \fBisspace\fP(3) classification function + "upper" \- realizes the \fBisupper\fP(3) classification function + "xdigit" \- realizes the \fBisxdigit\fP(3) classification function +.fi +.SH RETURN VALUE +The +.BR wctype () +function returns a property descriptor +if the +.I name +is valid. +Otherwise, it returns +.IR "(wctype_t) 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctype () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3) diff --git a/man/man3/wcwidth.3 b/man/man3/wcwidth.3 new file mode 100644 index 0000000..5aaba2b --- /dev/null +++ b/man/man3/wcwidth.3 @@ -0,0 +1,77 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcwidth 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcwidth \- determine columns needed for a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include <wchar.h> +.P +.BI "int wcwidth(wchar_t " c ); +.fi +.SH DESCRIPTION +The +.BR wcwidth () +function returns the number of columns +needed to represent the wide character +.IR c . +If +.I c +is a printable wide character, the value +is at least 0. +If +.I c +is null wide character (L\[aq]\e0\[aq]), the value is 0. +Otherwise, \-1 is returned. +.SH RETURN VALUE +The +.BR wcwidth () +function returns the number of +column positions for +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcwidth () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Note that before glibc 2.2.5, glibc used the prototype +.P +.nf +.BI "int wcwidth(wint_t " c ); +.fi +.SH NOTES +The behavior of +.BR wcwidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcswidth (3) diff --git a/man/man3/wmemchr.3 b/man/man3/wmemchr.3 new file mode 100644 index 0000000..d4cf541 --- /dev/null +++ b/man/man3/wmemchr.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemchr \- search a wide character in a wide-character array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wmemchr(const wchar_t " s [. n "], wchar_t " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemchr () +function is the wide-character equivalent of the +.BR memchr (3) +function. +It searches the +.I n +wide characters starting at +.I s +for +the first occurrence of the wide character +.IR c . +.SH RETURN VALUE +The +.BR wmemchr () +function returns a pointer to the first occurrence of +.I c +among the +.I n +wide characters starting at +.IR s , +or NULL if +.I c +does +not occur among these. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memchr (3), +.BR wcschr (3) diff --git a/man/man3/wmemcmp.3 b/man/man3/wmemcmp.3 new file mode 100644 index 0000000..f89e8a1 --- /dev/null +++ b/man/man3/wmemcmp.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wmemcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemcmp \- compare two arrays of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "int wmemcmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcmp () +function is the wide-character equivalent of the +.BR memcmp (3) +function. +It compares the +.I n +wide-characters starting at +.I s1 +and the +.I n +wide-characters starting at +.IR s2 . +.SH RETURN VALUE +The +.BR wmemcmp () +function returns +zero if the wide-character arrays of size +.I n +at +.I s1 +and +.I s2 +are equal. +It returns an integer greater than +zero if at the first differing position +.I i +.RI ( i " <" +.IR n ), +the +corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemcmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memcmp (3), +.BR wcscmp (3) diff --git a/man/man3/wmemcpy.3 b/man/man3/wmemcpy.3 new file mode 100644 index 0000000..808a6ae --- /dev/null +++ b/man/man3/wmemcpy.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemcpy \- copy an array of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wmemcpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcpy () +function is the wide-character equivalent of the +.BR memcpy (3) +function. +It copies +.I n +wide characters from the array starting at +.I src +to the array starting at +.IR dest . +.P +The arrays may not overlap; use +.BR wmemmove (3) +to copy between overlapping +arrays. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemcpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memcpy (3), +.BR wcscpy (3), +.BR wmemmove (3), +.BR wmempcpy (3) diff --git a/man/man3/wmemmove.3 b/man/man3/wmemmove.3 new file mode 100644 index 0000000..aff1bea --- /dev/null +++ b/man/man3/wmemmove.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemmove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemmove \- copy an array of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wmemmove(wchar_t " dest [. n "], const wchar_t " src [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemmove () +function is the wide-character equivalent of the +.BR memmove (3) +function. +It copies +.I n +wide characters from the array +starting at +.I src +to the array starting at +.IR dest . +The arrays may +overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemmove () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemmove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man/man3/wmempcpy.3 b/man/man3/wmempcpy.3 new file mode 100644 index 0000000..26750cb --- /dev/null +++ b/man/man3/wmempcpy.3 @@ -0,0 +1 @@ +.so man3/mempcpy.3 diff --git a/man/man3/wmemset.3 b/man/man3/wmemset.3 new file mode 100644 index 0000000..b4c4cb2 --- /dev/null +++ b/man/man3/wmemset.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemset \- fill an array of wide-characters with a constant wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.P +.BI "wchar_t *wmemset(wchar_t " wcs [. n "], wchar_t " wc ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemset () +function is the wide-character equivalent of the +.BR memset (3) +function. +It fills the array of +.I n +wide-characters starting at +.I wcs +with +.I n +copies of the wide character +.IR wc . +.SH RETURN VALUE +.BR wmemset () +returns +.IR wcs . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemset () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memset (3) diff --git a/man/man3/wordexp.3 b/man/man3/wordexp.3 new file mode 100644 index 0000000..945befc --- /dev/null +++ b/man/man3/wordexp.3 @@ -0,0 +1,245 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH wordexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wordexp, wordfree \- perform word expansion like a posix-shell +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <wordexp.h>" +.P +.BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \ +", int " flags ); +.BI "void wordfree(wordexp_t *" p ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wordexp (), +.BR wordfree (): +.nf + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The function +.BR wordexp () +performs a shell-like expansion of the string +.I s +and returns the result in the structure pointed to by +.IR p . +The data type +.I wordexp_t +is a structure that at least has the fields +.IR we_wordc , +.IR we_wordv , +and +.IR we_offs . +The field +.I we_wordc +is a +.I size_t +that gives the number of words in the expansion of +.IR s . +The field +.I we_wordv +is a +.I "char\ **" +that points to the array of words found. +The field +.I we_offs +of type +.I size_t +is sometimes (depending on +.IR flags , +see below) used to indicate the number of initial elements in the +.I we_wordv +array that should be filled with NULLs. +.P +The function +.BR wordfree () +frees the allocated memory again. +More precisely, it does not free +its argument, but it frees the array +.I we_wordv +and the strings that points to. +.SS The string argument +Since the expansion is the same as the expansion by the shell (see +.BR sh (1)) +of the parameters to a command, the string +.I s +must not contain characters that would be illegal in shell command +parameters. +In particular, there must not be any unescaped +newline or |, &, ;, <, >, (, ), {, } characters +outside a command substitution or parameter substitution context. +.P +If the argument +.I s +contains a word that starts with an unquoted comment character #, +then it is unspecified whether that word and all following words +are ignored, or the # is treated as a non-comment character. +.SS The expansion +The expansion done consists of the following stages: +tilde expansion (replacing \[ti]user by user's home directory), +variable substitution (replacing $FOO by the value of the environment +variable FOO), command substitution (replacing $(command) or \`command\` +by the output of command), arithmetic expansion, field splitting, +wildcard expansion, quote removal. +.P +The result of expansion of special parameters +($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. +.P +Field splitting is done using the environment variable $IFS. +If it is not set, the field separators are space, tab, and newline. +.SS The output array +The array +.I we_wordv +contains the words found, followed by a NULL. +.SS The flags argument +The +.I flag +argument is a bitwise inclusive OR of the following values: +.TP +.B WRDE_APPEND +Append the words found to the array resulting from a previous call. +.TP +.B WRDE_DOOFFS +Insert +.I we_offs +initial NULLs in the array +.IR we_wordv . +(These are not counted in the returned +.IR we_wordc .) +.TP +.B WRDE_NOCMD +Don't do command substitution. +.TP +.B WRDE_REUSE +The argument +.I p +resulted from a previous call to +.BR wordexp (), +and +.BR wordfree () +was not called. +Reuse the allocated storage. +.TP +.B WRDE_SHOWERR +Normally during command substitution +.I stderr +is redirected to +.IR /dev/null . +This flag specifies that +.I stderr +is not to be redirected. +.TP +.B WRDE_UNDEF +Consider it an error if an undefined shell variable is expanded. +.SH RETURN VALUE +On success, +.BR wordexp () +returns 0. +On failure, +.BR wordexp () +returns one of the following nonzero values: +.TP +.B WRDE_BADCHAR +Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. +.TP +.B WRDE_BADVAL +An undefined shell variable was referenced, and the +.B WRDE_UNDEF +flag +told us to consider this an error. +.TP +.B WRDE_CMDSUB +Command substitution requested, but the +.B WRDE_NOCMD +flag told us to consider this an error. +.TP +.B WRDE_NOSPACE +Out of memory. +.TP +.B WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or +unmatched quotes. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wordexp () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent const:env +env sig:ALRM timer locale +T} +T{ +.na +.nh +.BR wordfree () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR wordexp () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.1. +.SH EXAMPLES +The output of the following example program +is approximately that of "ls [a-c]*.c". +.P +.\" SRC BEGIN (wordexp.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <wordexp.h> +\& +int +main(void) +{ + wordexp_t p; + char **w; +\& + wordexp("[a\-c]*.c", &p, 0); + w = p.we_wordv; + for (size_t i = 0; i < p.we_wordc; i++) + printf("%s\en", w[i]); + wordfree(&p); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fnmatch (3), +.BR glob (3) diff --git a/man/man3/wordfree.3 b/man/man3/wordfree.3 new file mode 100644 index 0000000..f0035e0 --- /dev/null +++ b/man/man3/wordfree.3 @@ -0,0 +1 @@ +.so man3/wordexp.3 diff --git a/man/man3/wprintf.3 b/man/man3/wprintf.3 new file mode 100644 index 0000000..6aaf3b4 --- /dev/null +++ b/man/man3/wprintf.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wprintf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted +wide-character output conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.B #include <wchar.h> +.P +.BI "int wprintf(const wchar_t *restrict " format ", ...);" +.BI "int fwprintf(FILE *restrict " stream , +.BI " const wchar_t *restrict " format ", ...);" +.BI "int swprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , +.BI " const wchar_t *restrict " format ", ...);" +.P +.BI "int vwprintf(const wchar_t *restrict " format ", va_list " args ); +.BI "int vfwprintf(FILE *restrict " stream , +.BI " const wchar_t *restrict " format ", va_list " args ); +.BI "int vswprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , +.BI " const wchar_t *restrict " format ", va_list " args ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR wprintf (), +.\" .BR fwprintf (), +.\" .BR swprintf (), +.\" .BR vwprintf (), +.\" .BR vfwprintf (), +.\" .BR vswprintf (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR wprintf () +family of functions is +the wide-character equivalent of the +.BR printf (3) +family of functions. +It performs formatted output of wide +characters. +.P +The +.BR wprintf () +and +.BR vwprintf () +functions +perform wide-character output to +.IR stdout . +.I stdout +must not be byte oriented; see +.BR fwide (3) +for more information. +.P +The +.BR fwprintf () +and +.BR vfwprintf () +functions +perform wide-character output to +.IR stream . +.I stream +must not be byte oriented; see +.BR fwide (3) +for more information. +.P +The +.BR swprintf () +and +.BR vswprintf () +functions +perform wide-character output +to an array of wide characters. +The programmer must ensure that there is +room for at least +.I maxlen +wide +characters at +.IR wcs . +.P +These functions are like +the +.BR printf (3), +.BR vprintf (3), +.BR fprintf (3), +.BR vfprintf (3), +.BR sprintf (3), +.BR vsprintf (3) +functions except for the +following differences: +.TP +.B \[bu] +The +.I format +string is a wide-character string. +.TP +.B \[bu] +The output consists of wide characters, not bytes. +.TP +.B \[bu] +.BR swprintf () +and +.BR vswprintf () +take a +.I maxlen +argument, +.BR sprintf (3) +and +.BR vsprintf (3) +do not. +.RB ( snprintf (3) +and +.BR vsnprintf (3) +take a +.I maxlen +argument, but these functions do not return \-1 upon +buffer overflow on Linux.) +.P +The treatment of the conversion characters +.B c +and +.B s +is different: +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to a wide character by a call to the +.BR btowc (3) +function, and the resulting wide character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const\ char\ *" +argument is expected to be a pointer to an array of character type +(pointer to a string) containing a multibyte character sequence beginning +in the initial shift state. +Characters from the array are converted to +wide characters (each by a call to the +.BR mbrtowc (3) +function with a conversion state starting in the initial state before +the first byte). +The resulting wide characters are written up to +(but not including) the terminating null wide character (L\[aq]\e0\[aq]). +If a precision is +specified, no more wide characters than the number specified are written. +Note that the precision determines the number of +.I wide characters +written, not the number of +.I bytes +or +.IR "screen positions" . +The array must contain a terminating null byte (\[aq]\e0\[aq]), +unless a precision is given +and it is so small that the number of converted wide characters reaches it +before the end of the array is reached. +If an +.B l +modifier is present: the +.I "const\ wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are written up to (but not including) a +terminating null wide character. +If a precision is specified, no more than +the number specified are written. +The array must contain a terminating null +wide character, unless a precision is given and it is smaller than or equal +to the number of wide characters in the array. +.SH RETURN VALUE +The functions return the number of wide characters written, excluding the +terminating null wide character in +case of the functions +.BR swprintf () +and +.BR vswprintf (). +They return \-1 when an error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wprintf (), +.BR fwprintf (), +.BR swprintf (), +.BR vwprintf (), +.BR vfwprintf (), +.BR vswprintf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wprintf () +et al. depends +on the +.B LC_CTYPE +category of the +current locale. +.P +If the +.I format +string contains non-ASCII wide characters, the program +will work correctly only if the +.B LC_CTYPE +category of the current locale at +run time is the same as the +.B LC_CTYPE +category of the current locale at +compile time. +This is because the +.I wchar_t +representation is platform- and locale-dependent. +(The glibc represents +wide characters using their Unicode (ISO/IEC 10646) code point, but other +platforms don't do this. +Also, the use of C99 universal character names +of the form \eunnnn does not solve this problem.) +Therefore, in +internationalized programs, the +.I format +string should consist of ASCII +wide characters only, or should be constructed at run time in an +internationalized way (e.g., using +.BR gettext (3) +or +.BR iconv (3), +followed by +.BR mbstowcs (3)). +.SH SEE ALSO +.BR fprintf (3), +.BR fputwc (3), +.BR fwide (3), +.BR printf (3), +.BR snprintf (3) +.\" .BR wscanf (3) diff --git a/man/man3/xcrypt.3 b/man/man3/xcrypt.3 new file mode 100644 index 0000000..d00642a --- /dev/null +++ b/man/man3/xcrypt.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" this is the 3rd type of interface for cryptographic routines +.\" 1. encrypt() expects a bit field +.\" 2. cbc_crypt() byte values +.\" 3. xencrypt() a hexstring +.\" to bad to be true :( +.\" +.TH XCRYPT 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +xencrypt, xdecrypt, passwd2des \- RFS password encryption +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <rpc/des_crypt.h>" +.P +.BI "void passwd2des(char " *passwd ", char *" key ");" +.P +.BI "int xencrypt(char *" secret ", char *" passwd ");" +.BI "int xdecrypt(char *" secret ", char *" passwd ");" +.fi +.SH DESCRIPTION +.BR WARNING : +Do not use these functions in new code. +They do not achieve any type of acceptable cryptographic security guarantees. +.P +The function +.BR passwd2des () +takes a character string +.I passwd +of arbitrary length and fills a character array +.I key +of length 8. +The array +.I key +is suitable for use as DES key. +It has odd parity set in bit 0 of each byte. +Both other functions described here use this function to turn their +argument +.I passwd +into a DES key. +.P +The +.BR xencrypt () +function takes the ASCII character string +.I secret +given in hex, +.\" (over the alphabet 0123456789abcdefABCDEF), +which must have a length that is a multiple of 16, +encrypts it using the DES key derived from +.I passwd +by +.BR passwd2des (), +and outputs the result again in +.I secret +as a hex string +.\" (over the alphabet 0123456789abcdef) +of the same length. +.P +The +.BR xdecrypt () +function performs the converse operation. +.SH RETURN VALUE +The functions +.BR xencrypt () +and +.BR xdecrypt () +return 1 on success and 0 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR passwd2des (), +.BR xencrypt (), +.BR xdecrypt () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are available since glibc 2.1. +.SH BUGS +The prototypes are missing from the abovementioned include file. +.SH SEE ALSO +.BR cbc_crypt (3) diff --git a/man/man3/xdecrypt.3 b/man/man3/xdecrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/xdecrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/xdr.3 b/man/man3/xdr.3 new file mode 100644 index 0000000..9aa20c4 --- /dev/null +++ b/man/man3/xdr.3 @@ -0,0 +1,609 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH xdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +xdr \- library routines for external data representation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS AND DESCRIPTION +These routines allow C programmers to describe +arbitrary data structures in a machine-independent fashion. +Data for remote procedure calls are transmitted using these +routines. +.P +The prototypes below are declared in +.I <rpc/xdr.h> +and make use of the following types: +.P +.RS 4 +.EX +.BI "typedef int " bool_t ; +.P +.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);" +.EE +.RE +.P +For the declaration of the +.I XDR +type, see +.IR <rpc/xdr.h> . +.P +.nf +.BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ", unsigned int " elsize , +.BI " xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between variable-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I sizep +is the address of the element count of the array; +this element count cannot exceed +.IR maxsize . +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp ); +.fi +.IP +A filter primitive that translates between booleans (C +integers) +and their external representations. +When encoding data, this +filter produces values of either one or zero. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between counted byte +strings and their external representations. +The argument +.I sp +is the address of the string pointer. +The length of the +string is located at address +.IR sizep ; +strings cannot be longer than +.IR maxsize . +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_char(XDR *" xdrs ", char *" cp ); +.fi +.IP +A filter primitive that translates between C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to +consider +.BR xdr_bytes (), +.BR xdr_opaque (), +or +.BR xdr_string (). +.P +.nf +.BI "void xdr_destroy(XDR *" xdrs ); +.fi +.IP +A macro that invokes the destroy routine associated with the XDR stream, +.IR xdrs . +Destruction usually involves freeing private data structures +associated with the stream. +Using +.I xdrs +after invoking +.BR xdr_destroy () +is undefined. +.P +.nf +.BI "bool_t xdr_double(XDR *" xdrs ", double *" dp ); +.fi +.IP +A filter primitive that translates between C +.I double +precision numbers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep ); +.fi +.IP +A filter primitive that translates between C +.IR enum s +(actually integers) and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_float(XDR *" xdrs ", float *" fp ); +.fi +.IP +A filter primitive that translates between C +.IR float s +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdr_free(xdrproc_t " proc ", char *" objp ); +.fi +.IP +Generic freeing routine. +The first argument is the XDR routine for the object being freed. +The second argument is a pointer to the object itself. +Note: the pointer passed to this routine is +.I not +freed, but what it points to +.I is +freed (recursively). +.P +.nf +.BI "unsigned int xdr_getpos(XDR *" xdrs ); +.fi +.IP +A macro that invokes the get-position routine +associated with the XDR stream, +.IR xdrs . +The routine returns an unsigned integer, +which indicates the position of the XDR byte stream. +A desirable feature of XDR +streams is that simple arithmetic works with this number, +although the XDR stream instances need not guarantee this. +.P +.nf +.BI "long *xdr_inline(XDR *" xdrs ", int " len ); +.fi +.IP +A macro that invokes the inline routine associated with the XDR stream, +.IR xdrs . +The routine returns a pointer +to a contiguous piece of the stream's buffer; +.I len +is the byte length of the desired buffer. +Note: pointer is cast to +.IR "long\ *" . +.IP +Warning: +.BR xdr_inline () +may return NULL (0) +if it cannot allocate a contiguous piece of a buffer. +Therefore the behavior may vary among stream instances; +it exists for the sake of efficiency. +.P +.nf +.BI "bool_t xdr_int(XDR *" xdrs ", int *" ip ); +.fi +.IP +A filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_long(XDR *" xdrs ", long *" lp ); +.fi +.IP +A filter primitive that translates between C +.I long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size , +.BI " enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to, or read from, +a chunk of memory at location +.I addr +whose length is no more than +.I size +bytes long. +The +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.P +.nf +.BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt ); +.fi +.IP +A filter primitive that translates between fixed size opaque data +and its external representation. +The argument +.I cp +is the address of the opaque object, and +.I cnt +is its size in bytes. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp , +.BI " unsigned int " objsize ", xdrproc_t " xdrobj ); +.fi +.IP +Like +.BR xdr_reference () +except that it serializes null pointers, whereas +.BR xdr_reference () +does not. +Thus, +.BR xdr_pointer () +can represent +recursive data structures, such as binary trees or +linked lists. +.P +.nf +.BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize , +.BI " unsigned int " recvsize ", char *" handle , +.BI " int (*" readit ")(char *, char *, int)," +.BI " int (*" writeit ")(char *, char *, int));" +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to a buffer of size +.IR sendsize ; +a value of zero indicates the system should use a suitable default. +The stream's data is read from a buffer of size +.IR recvsize ; +it too can be set to a suitable default by passing a zero value. +When a stream's output buffer is full, +.I writeit +is called. +Similarly, when a stream's input buffer is empty, +.I readit +is called. +The behavior of these two routines is similar to +the system calls +.BR read (2) +and +.BR write (2), +except that +.I handle +is passed to the former routines as the first argument. +Note: the XDR stream's +.I op +field must be set by the caller. +.IP +Warning: to read from an XDR stream created by this API, +you'll need to call +.BR xdrrec_skiprecord () +first before calling any other XDR APIs. +This inserts additional bytes in the stream to provide +record boundary information. +Also, XDR streams created with different +.B xdr*_create +APIs are not compatible for the same reason. +.P +.nf +.BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +The data in the output buffer is marked as a completed record, +and the output buffer is optionally written out if +.I sendnow +is nonzero. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdrrec_eof(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +After consuming the rest of the current record in the stream, +this routine returns one if the stream has no more input, +zero otherwise. +.P +.nf +.BI "bool_t xdrrec_skiprecord(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create (). +It tells the XDR implementation that the rest of the current record +in the stream's input buffer should be discarded. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size , +.BI " xdrproc_t " proc ); +.fi +.IP +A primitive that provides pointer chasing within structures. +The argument +.I pp +is the address of the pointer; +.I size +is the +.I sizeof +the structure that +.I *pp +points to; and +.I proc +is an XDR procedure that filters the structure +between its C form and its external representation. +This routine returns one if it succeeds, zero otherwise. +.IP +Warning: this routine does not understand null pointers. +Use +.BR xdr_pointer () +instead. +.P +.nf +.BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos ); +.fi +.IP +A macro that invokes the set position routine associated with +the XDR stream +.IR xdrs . +The argument +.I pos +is a position value obtained from +.BR xdr_getpos (). +This routine returns one if the XDR stream could be repositioned, +and zero otherwise. +.IP +Warning: it is difficult to reposition some types of XDR +streams, so this routine may fail with one +type of stream and succeed with another. +.P +.nf +.BI "bool_t xdr_short(XDR *" xdrs ", short *" sp ); +.fi +.IP +A filter primitive that translates between C +.I short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The XDR stream data is written to, or read from, the +.I stdio +stream +.IR file . +The argument +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.IP +Warning: the destroy routine associated with such XDR streams calls +.BR fflush (3) +on the +.I file +stream, but never +.BR fclose (3). +.P +.nf +.BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between C strings and +their corresponding external representations. +Strings cannot be longer than +.IR maxsize . +Note: +.I sp +is the address of the string's pointer. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp ); +.fi +.IP +A filter primitive that translates between +.I unsigned +C characters and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up ); +.fi +.IP +A filter primitive that translates between C +.I unsigned +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned long" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned short" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp , +.BI " const struct xdr_discrim *" choices , +.BI " xdrproc_t " defaultarm "); /* may equal NULL */" +.fi +.IP +A filter primitive that translates between a discriminated C +.I union +and its corresponding external representation. +It first +translates the discriminant of the union located at +.IR dscmp . +This discriminant is always an +.IR enum_t . +Next the union located at +.I unp +is translated. +The argument +.I choices +is a pointer to an array of +.BR xdr_discrim () +structures. +Each structure contains an ordered pair of +.RI [ value , proc ]. +If the union's discriminant is equal to the associated +.IR value , +then the +.I proc +is called to translate the union. +The end of the +.BR xdr_discrim () +structure array is denoted by a routine of value NULL. +If the discriminant is not found in the +.I choices +array, then the +.I defaultarm +procedure is called (if it is not NULL). +Returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size , +.BI " unsigned int " elsize ", xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between fixed-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I size +is the element count of the array. +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.B bool_t xdr_void(void); +.fi +.IP +This routine always returns one. +It may be passed to RPC routines that require a function argument, +where nothing is to be done. +.P +.nf +.BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp ); +.fi +.IP +A primitive that calls +.B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );" +where +.B MAXUN.UNSIGNED +is the maximum value of an unsigned integer. +.BR xdr_wrapstring () +is handy because the RPC package passes a maximum of two XDR +routines as arguments, and +.BR xdr_string (), +one of the most frequently used primitives, requires three. +Returns one if it succeeds, zero otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR xdr_array (), +.BR xdr_bool (), +.BR xdr_bytes (), +.BR xdr_char (), +.BR xdr_destroy (), +.BR xdr_double (), +.BR xdr_enum (), +.BR xdr_float (), +.BR xdr_free (), +.BR xdr_getpos (), +.BR xdr_inline (), +.BR xdr_int (), +.BR xdr_long (), +.BR xdrmem_create (), +.BR xdr_opaque (), +.BR xdr_pointer (), +.BR xdrrec_create (), +.BR xdrrec_eof (), +.BR xdrrec_endofrecord (), +.BR xdrrec_skiprecord (), +.BR xdr_reference (), +.BR xdr_setpos (), +.BR xdr_short (), +.BR xdrstdio_create (), +.BR xdr_string (), +.BR xdr_u_char (), +.BR xdr_u_int (), +.BR xdr_u_long (), +.BR xdr_u_short (), +.BR xdr_union (), +.BR xdr_vector (), +.BR xdr_void (), +.BR xdr_wrapstring () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR rpc (3) +.P +The following manuals: +.RS +eXternal Data Representation Standard: Protocol Specification +.br +eXternal Data Representation: Sun Technical Notes +.br +.IR "XDR: External Data Representation Standard" , +RFC\ 1014, Sun Microsystems, Inc., +USC-ISI. +.RE diff --git a/man/man3/xdr_accepted_reply.3 b/man/man3/xdr_accepted_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_accepted_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_array.3 b/man/man3/xdr_array.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_array.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_authunix_parms.3 b/man/man3/xdr_authunix_parms.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_authunix_parms.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_bool.3 b/man/man3/xdr_bool.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_bool.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_bytes.3 b/man/man3/xdr_bytes.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_bytes.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_callhdr.3 b/man/man3/xdr_callhdr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_callhdr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_callmsg.3 b/man/man3/xdr_callmsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_callmsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_char.3 b/man/man3/xdr_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_destroy.3 b/man/man3/xdr_destroy.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_destroy.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_double.3 b/man/man3/xdr_double.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_double.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_enum.3 b/man/man3/xdr_enum.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_enum.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_float.3 b/man/man3/xdr_float.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_float.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_free.3 b/man/man3/xdr_free.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_free.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_getpos.3 b/man/man3/xdr_getpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_getpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_inline.3 b/man/man3/xdr_inline.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_inline.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_int.3 b/man/man3/xdr_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_long.3 b/man/man3/xdr_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_opaque.3 b/man/man3/xdr_opaque.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_opaque.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_opaque_auth.3 b/man/man3/xdr_opaque_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_opaque_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pmap.3 b/man/man3/xdr_pmap.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_pmap.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pmaplist.3 b/man/man3/xdr_pmaplist.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_pmaplist.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pointer.3 b/man/man3/xdr_pointer.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_pointer.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_reference.3 b/man/man3/xdr_reference.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_reference.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_rejected_reply.3 b/man/man3/xdr_rejected_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_rejected_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_replymsg.3 b/man/man3/xdr_replymsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_replymsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_setpos.3 b/man/man3/xdr_setpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_setpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_short.3 b/man/man3/xdr_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_string.3 b/man/man3/xdr_string.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_string.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_char.3 b/man/man3/xdr_u_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_int.3 b/man/man3/xdr_u_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_long.3 b/man/man3/xdr_u_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_short.3 b/man/man3/xdr_u_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_union.3 b/man/man3/xdr_union.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_union.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_vector.3 b/man/man3/xdr_vector.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_vector.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_void.3 b/man/man3/xdr_void.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_void.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_wrapstring.3 b/man/man3/xdr_wrapstring.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_wrapstring.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrmem_create.3 b/man/man3/xdrmem_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrmem_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_create.3 b/man/man3/xdrrec_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_endofrecord.3 b/man/man3/xdrrec_endofrecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_endofrecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_eof.3 b/man/man3/xdrrec_eof.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_eof.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_skiprecord.3 b/man/man3/xdrrec_skiprecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_skiprecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrstdio_create.3 b/man/man3/xdrstdio_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrstdio_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xencrypt.3 b/man/man3/xencrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/xencrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/xprt_register.3 b/man/man3/xprt_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xprt_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xprt_unregister.3 b/man/man3/xprt_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xprt_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/y0.3 b/man/man3/y0.3 new file mode 100644 index 0000000..af9628f --- /dev/null +++ b/man/man3/y0.3 @@ -0,0 +1,276 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, created this page, based on material from j0.3. +.\" +.TH y0 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- +Bessel functions of the second kind +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include <math.h> +.P +.BI "double y0(double " x ); +.BI "double y1(double " x ); +.BI "double yn(int " n ", double " x ); +.P +.BI "float y0f(float " x ); +.BI "float y1f(float " x ); +.BI "float ynf(int " n ", float " x ); +.P +.BI "long double y0l(long double " x ); +.BI "long double y1l(long double " x ); +.BI "long double ynl(int " n ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR y0 (), +.BR y1 (), +.BR yn (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR y0f (), +.BR y0l (), +.BR y1f (), +.BR y1l (), +.BR ynf (), +.BR ynl (): +.nf + _XOPEN_SOURCE >= 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR y0 () +and +.BR y1 () +functions return Bessel functions of +.I x +of the second kind of orders 0 and 1, respectively. +The +.BR yn () +function +returns the Bessel function of +.I x +of the second kind of order +.IR n . +.P +The value of +.I x +must be positive. +.P +The +.BR y0f (), +.BR y1f (), +and +.BR ynf () +functions are versions that take and return +.I float +values. +The +.BR y0l (), +.BR y1l (), +and +.BR ynl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the second kind for +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is negative, +a domain error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a NaN return for this case.) +.P +If +.I x +is 0.0, +a pole error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If the result underflows, +a range error occurs, +and the functions return 0.0 +.P +If the result overflows, +a range error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a 0.0 return for this case.) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is 0.0 +.\" Before POSIX.1-2001 TC2, this was (inconsistently) specified +.\" as a range error. +.I errno +is set to +.B ERANGE +and an +.B FE_DIVBYZERO +exception is raised +(but see BUGS). +.TP +Range error: result underflow +.\" e.g., y0(1e33) on glibc 2.8/x86-32 +.I errno +is set to +.BR ERANGE . +No +.B FE_UNDERFLOW +exception is returned by +.\" This is intended behavior +.\" See https://www.sourceware.org/bugzilla/show_bug.cgi?id=6806 +.BR fetestexcept (3) +for this case. +.TP +Range error: result overflow +.\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32 +.I errno +is set to +.B ERANGE +(but see BUGS). +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR y0 (), +.BR y0f (), +.BR y0l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR y1 (), +.BR y1f (), +.BR y1l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR yn (), +.BR ynf (), +.BR ynl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR y0 () +.TQ +.BR y1 () +.TQ +.BR yn () +POSIX.1-2008. +.TP +Others: +BSD. +.SH HISTORY +.TP +.BR y0 () +.TQ +.BR y1 () +.TQ +.BR yn () +SVr4, 4.3BSD, +POSIX.1-2001. +.TP +Others: +BSD. +.SH BUGS +Before glibc 2.19, +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6807 +these functions misdiagnosed pole errors: +.I errno +was set to +.BR EDOM , +instead of +.B ERANGE +and no +.B FE_DIVBYZERO +exception was raised. +.P +Before glibc 2.17, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6808 +did not set +.I errno +for "range error: result underflow". +.P +In glibc 2.3.2 and earlier, +.\" Actually, 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in glibc 2.3.2. +these functions do not raise an invalid floating-point exception +.RB ( FE_INVALID ) +when a domain error occurs. +.SH SEE ALSO +.BR j0 (3) diff --git a/man/man3/y0f.3 b/man/man3/y0f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y0f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y0l.3 b/man/man3/y0l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y0l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1.3 b/man/man3/y1.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1f.3 b/man/man3/y1f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1l.3 b/man/man3/y1l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/yn.3 b/man/man3/yn.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/yn.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/ynf.3 b/man/man3/ynf.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/ynf.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/ynl.3 b/man/man3/ynl.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/ynl.3 @@ -0,0 +1 @@ +.so man3/y0.3 |