diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:24 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:24 +0000 |
commit | 100d1b33f088fd38f69129afff7f9c2a1e084a57 (patch) | |
tree | 5bf6b0bb14f22ecf0a5e9439fdd4c4758402400c /man3head | |
parent | Releasing progress-linux version 6.7-2~progress7.99u1. (diff) | |
download | manpages-100d1b33f088fd38f69129afff7f9c2a1e084a57.tar.xz manpages-100d1b33f088fd38f69129afff7f9c2a1e084a57.zip |
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man3head')
l--------- | man3head | 1 | ||||
-rw-r--r-- | man3head/printf.h.3head | 582 | ||||
-rw-r--r-- | man3head/sysexits.h.3head | 200 |
3 files changed, 1 insertions, 782 deletions
diff --git a/man3head b/man3head new file mode 120000 index 0000000..a9b276b --- /dev/null +++ b/man3head @@ -0,0 +1 @@ +man/man3head
\ No newline at end of file diff --git a/man3head/printf.h.3head b/man3head/printf.h.3head deleted file mode 100644 index 8f1b9a0..0000000 --- a/man3head/printf.h.3head +++ /dev/null @@ -1,582 +0,0 @@ -.\" Copyright (C) 2022 Alejandro Colomar <alx.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH printf.h 3head 2024-03-14 "Linux man-pages 6.7" -.SH NAME -printf.h, -\%register_printf_specifier, -\%register_printf_modifier, -\%register_printf_type, -\%printf_function, -\%printf_arginfo_size_function, -\%printf_va_arg_function, -\%printf_info, -\%PA_INT, -\%PA_CHAR, -\%PA_WCHAR, -\%PA_STRING, -\%PA_WSTRING, -\%PA_POINTER, -\%PA_FLOAT, -\%PA_DOUBLE, -\%PA_LAST, -\%PA_FLAG_LONG_LONG, -\%PA_FLAG_LONG_DOUBLE, -\%PA_FLAG_LONG, -\%PA_FLAG_SHORT, -\%PA_FLAG_PTR -\- define custom behavior for printf-like functions -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <printf.h> -.P -.BI "int register_printf_specifier(int " spec ", printf_function " func , -.BI " printf_arginfo_size_function " arginfo ); -.BI "int register_printf_modifier(const wchar_t *" str ); -.BI "int register_printf_type(printf_va_arg_function " fct ); -.fi -.SS Callbacks -.nf -.BI "typedef int printf_function(FILE *" stream ", const struct printf_info *" info , -.BI " const void *const " args []); -.BI "typedef int printf_arginfo_size_function(const struct printf_info *" info , -.BI " size_t " n ", int " argtypes [ n "], int " size [ n ]); -.BI "typedef void printf_va_arg_function(void *" mem ", va_list *" ap ); -.fi -.SS Types -.EX -.B struct printf_info { -.BR " int prec; " "// Precision" -.BR " int width; " "// Width" -.BR " wchar_t spec; " "// Format letter" -.BR " unsigned int is_long_double:1;" "// " L " or " ll " flag" -.BR " unsigned int is_short:1; " "// " h " flag" -.BR " unsigned int is_long:1; " "// " l " flag" -.BR " unsigned int alt:1; " "// " # " flag" -.BR " unsigned int space:1; " "// Space flag" -.BR " unsigned int left:1; " "// " - " flag" -.BR " unsigned int showsign:1; " "// " + " flag" -.BR " unsigned int group:1; " "// " \[aq] " flag" -.BR " unsigned int extra:1; " "// For special use" -.BR " unsigned int is_char:1; " "// " hh " flag" -.BR " unsigned int wide:1; " "// True for wide character streams" -.BR " unsigned int i18n:1; " "// " I " flag" -.BR " unsigned int is_binary128:1; " "/* Floating-point argument is" -.BR " " " ABI-compatible with" -.BR " " " IEC 60559 binary128 */" -.BR " unsigned short user; " "// Bits for user-installed modifiers" -.BR " wchar_t pad; " "// Padding character" -.B }; -.EE -.SS Constants -.EX -.BR "#define PA_FLAG_LONG_LONG " "/* ... */" -.BR "#define PA_FLAG_LONG_DOUBLE " "/* ... */" -.BR "#define PA_FLAG_LONG " "/* ... */" -.BR "#define PA_FLAG_SHORT " "/* ... */" -.BR "#define PA_FLAG_PTR " "/* ... */" -.EE -.SH DESCRIPTION -These functions serve to extend and/or modify the behavior of the -.BR printf (3) -family of functions. -.SS register_printf_specifier() -This function registers a custom conversion specifier for the -.BR printf (3) -family of functions. -.TP -.I spec -The character which will be used as a conversion specifier in the format string. -.TP -.I func -Callback function that will be executed by the -.BR printf (3) -family of functions -to format the input arguments into the output -.IR stream . -.RS -.TP -.I stream -Output stream where the formatted output should be printed. -This stream transparently represents the output, -even in the case of functions that write to a string. -.TP -.I info -Structure that holds context information, -including the modifiers specified in the format string. -This holds the same contents as in -.IR arginfo . -.TP -.I args -Array of pointers to the arguments to the -.BR printf (3)\c --like function. -.RE -.TP -.I arginfo -Callback function that will be executed by the -.BR printf (3) -family of functions -to know how many arguments should be parsed for the custom specifier -and also their types. -.RS -.TP -.I info -Structure that holds context information, -including the modifiers specified in the format string. -This holds the same contents as in -.IR func . -.TP -.I n -Number of arguments remaining to be parsed. -.TP -.I argtypes -This array should be set to -define the type of each of the arguments that will be parsed. -Each element in the array represents one of the arguments to be parsed, -in the same order that they are passed to the -.BR printf (3)\c --like function. -Each element should be set to a base type -.RB ( PA_ *) -from the enum above, -or a custom one, -and optionally ORed with an appropriate length modifier -.RB ( PA_FLAG_ *). -.RS -.P -The type is determined by using one of the following constants: -.TP -.B PA_INT -.IR int . -.TP -.B PA_CHAR -.IR int , -cast to -.IR char . -.TP -.B PA_WCHAR -.IR wchar_t . -.TP -.B PA_STRING -.IR "const char\~*" , -a \(aq\e0\(aq-terminated string. -.TP -.B PA_WSTRING -.IR "const wchar_t\~*" , -a wide character L\(aq\e0\(aq-terminated string. -.TP -.B PA_POINTER -.IR void\~* . -.TP -.B PA_FLOAT -.IR float . -.TP -.B PA_DOUBLE -.IR double . -.TP -.B PA_LAST -TODO. -.RE -.TP -.I size -For user-defined types, -the size of the type (in bytes) should also be specified through this array. -Otherwise, leave it unused. -.RE -.P -.I arginfo -is called before -.IR func , -and prepares some information needed to call -.IR func . -.SS register_printf_modifier() -TODO -.SS register_printf_type() -TODO -.SH RETURN VALUE -.BR \%register_printf_specifier (), -.BR \%register_printf_modifier (), -and -.BR \%register_printf_type () -return zero on success, or \-1 on error. -.SS Callbacks -The callback of type -.I printf_function -should return the number of characters written, -or \-1 on error. -.P -The callback of type -.I \%printf_arginfo_size_function -should return the number of arguments to be parsed by this specifier. -It also passes information about the type of those arguments -to the caller through -.IR argtypes . -On error, it should return \-1. -.SH ERRORS -.TP -.B EINVAL -The specifier was not a valid character. -.SH STANDARDS -GNU. -.SH HISTORY -.BR \%register_printf_function (3) -is an older function similar to -.BR \%register_printf_specifier (), -and is now deprecated. -That function can't handle user-defined types. -.P -.BR \%register_printf_specifier () -supersedes -.BR \%register_printf_function (3). -.SH EXAMPLES -The following example program registers the 'b' and 'B' specifiers -to print integers in binary format, -mirroring rules for other unsigned conversion specifiers like 'x' and 'u'. -This can be used to print in binary prior to C23. -.P -.\" SRC BEGIN (register_printf_specifier.c) -.EX -/* This code is in the public domain */ -\& -#include <err.h> -#include <limits.h> -#include <stddef.h> -#include <stdint.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <sys/param.h> -\& -#include <printf.h> -\& -#define GROUP_SEP \[aq]\e\[aq]\[aq] -\& -struct Printf_Pad { - char ch; - size_t len; -}; -\& -static int b_printf(FILE *stream, const struct printf_info *info, - const void *const args[]); -static int b_arginf_sz(const struct printf_info *info, - size_t n, int argtypes[n], int size[n]); -\& -static uintmax_t b_value(const struct printf_info *info, - const void *arg); -static size_t b_bin_repr(char bin[UINTMAX_WIDTH], - const struct printf_info *info, const void *arg); -static size_t b_bin_len(const struct printf_info *info, - ptrdiff_t min_len); -static size_t b_pad_len(const struct printf_info *info, - ptrdiff_t bin_len); -static ssize_t b_print_prefix(FILE *stream, - const struct printf_info *info); -static ssize_t b_pad_zeros(FILE *stream, const struct printf_info *info, - ptrdiff_t min_len); -static ssize_t b_print_number(FILE *stream, - const struct printf_info *info, - const char bin[UINTMAX_WIDTH], - size_t min_len, size_t bin_len); -static char pad_ch(const struct printf_info *info); -static ssize_t pad_spaces(FILE *stream, size_t pad_len); -\& -int -main(void) -{ - if (register_printf_specifier(\[aq]b\[aq], b_printf, b_arginf_sz) == \-1) - err(EXIT_FAILURE, "register_printf_specifier(\[aq]b\[aq], ...)"); - if (register_printf_specifier(\[aq]B\[aq], b_printf, b_arginf_sz) == \-1) - err(EXIT_FAILURE, "register_printf_specifier(\[aq]B\[aq], ...)"); -\& - printf("....----....----....----....----\en"); - printf("%llb;\en", 0x5Ellu); - printf("%lB;\en", 0x5Elu); - printf("%b;\en", 0x5Eu); - printf("%hB;\en", 0x5Eu); - printf("%hhb;\en", 0x5Eu); - printf("%jb;\en", (uintmax_t)0x5E); - printf("%zb;\en", (size_t)0x5E); - printf("....----....----....----....----\en"); - printf("%#b;\en", 0x5Eu); - printf("%#B;\en", 0x5Eu); - printf("....----....----....----....----\en"); - printf("%10b;\en", 0x5Eu); - printf("%010b;\en", 0x5Eu); - printf("%.10b;\en", 0x5Eu); - printf("....----....----....----....----\en"); - printf("%\-10B;\en", 0x5Eu); - printf("....----....----....----....----\en"); - printf("%\[aq]B;\en", 0x5Eu); - printf("....----....----....----....----\en"); - printf("....----....----....----....----\en"); - printf("%#16.12b;\en", 0xAB); - printf("%\-#\[aq]20.12b;\en", 0xAB); - printf("%#\[aq]020B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%#020B;\en", 0xAB); - printf("%\[aq]020B;\en", 0xAB); - printf("%020B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%#021B;\en", 0xAB); - printf("%\[aq]021B;\en", 0xAB); - printf("%021B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%#022B;\en", 0xAB); - printf("%\[aq]022B;\en", 0xAB); - printf("%022B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%#023B;\en", 0xAB); - printf("%\[aq]023B;\en", 0xAB); - printf("%023B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%\-#\[aq]19.11b;\en", 0xAB); - printf("%#\[aq]019B;\en", 0xAB); - printf("%#019B;\en", 0xAB); - printf("....----....----....----....----\en"); - printf("%\[aq]019B;\en", 0xAB); - printf("%019B;\en", 0xAB); - printf("%#016b;\en", 0xAB); - printf("....----....----....----....----\en"); -\& - return 0; -} -\& -static int -b_printf(FILE *stream, const struct printf_info *info, - const void *const args[]) -{ - char bin[UINTMAX_WIDTH]; - size_t min_len, bin_len; - ssize_t len, tmp; - struct Printf_Pad pad = {0}; -\& - len = 0; -\& - min_len = b_bin_repr(bin, info, args[0]); - bin_len = b_bin_len(info, min_len); -\& - pad.ch = pad_ch(info); - if (pad.ch == \[aq] \[aq]) - pad.len = b_pad_len(info, bin_len); -\& - /* Padding with \[aq] \[aq] (right aligned) */ - if ((pad.ch == \[aq] \[aq]) && !info->left) { - tmp = pad_spaces(stream, pad.len); - if (tmp == EOF) - return EOF; - len += tmp; - } -\& - /* "0b"/"0B" prefix */ - if (info->alt) { - tmp = b_print_prefix(stream, info); - if (tmp == EOF) - return EOF; - len += tmp; - } -\& - /* Padding with \[aq]0\[aq] */ - if (pad.ch == \[aq]0\[aq]) { - tmp = b_pad_zeros(stream, info, min_len); - if (tmp == EOF) - return EOF; - len += tmp; - } -\& - /* Print number (including leading 0s to fill precision) */ - tmp = b_print_number(stream, info, bin, min_len, bin_len); - if (tmp == EOF) - return EOF; - len += tmp; -\& - /* Padding with \[aq] \[aq] (left aligned) */ - if (info\->left) { - tmp = pad_spaces(stream, pad.len); - if (tmp == EOF) - return EOF; - len += tmp; - } -\& - return len; -} -\& -static int -b_arginf_sz(const struct printf_info *info, size_t n, int argtypes[n], - [[maybe_unused]] int size[n]) -{ - if (n < 1) - return \-1; -\& - if (info\->is_long_double) - argtypes[0] = PA_INT | PA_FLAG_LONG_LONG; - else if (info\->is_long) - argtypes[0] = PA_INT | PA_FLAG_LONG; - else - argtypes[0] = PA_INT; -\& - return 1; -} -\& -static uintmax_t -b_value(const struct printf_info *info, const void *arg) -{ - if (info\->is_long_double) - return *(const unsigned long long *)arg; - if (info\->is_long) - return *(const unsigned long *)arg; -\& - /* short and char are both promoted to int */ - return *(const unsigned int *)arg; -} -\& -static size_t -b_bin_repr(char bin[UINTMAX_WIDTH], - const struct printf_info *info, const void *arg) -{ - size_t min_len; - uintmax_t val; -\& - val = b_value(info, arg); -\& - bin[0] = \[aq]0\[aq]; - for (min_len = 0; val; min_len++) { - bin[min_len] = \[aq]0\[aq] + (val % 2); - val >>= 1; - } -\& - return MAX(min_len, 1); -} -\& -static size_t -b_bin_len(const struct printf_info *info, ptrdiff_t min_len) -{ - return MAX(info\->prec, min_len); -} -\& -static size_t -b_pad_len(const struct printf_info *info, ptrdiff_t bin_len) -{ - ptrdiff_t pad_len; -\& - pad_len = info\->width \- bin_len; - if (info\->alt) - pad_len \-= 2; - if (info\->group) - pad_len \-= (bin_len \- 1) / 4; -\& - return MAX(pad_len, 0); -} -\& -static ssize_t -b_print_prefix(FILE *stream, const struct printf_info *info) -{ - ssize_t len; -\& - len = 0; - if (fputc(\[aq]0\[aq], stream) == EOF) - return EOF; - len++; - if (fputc(info\->spec, stream) == EOF) - return EOF; - len++; -\& - return len; -} -\& -static ssize_t -b_pad_zeros(FILE *stream, const struct printf_info *info, - ptrdiff_t min_len) -{ - ssize_t len; - ptrdiff_t tmp; -\& - len = 0; - tmp = info\->width \- (info\->alt * 2); - if (info\->group) - tmp \-= tmp / 5 \- !(tmp % 5); - for (ptrdiff_t i = tmp \- 1; i > min_len \- 1; i\-\-) { - if (fputc(\[aq]0\[aq], stream) == EOF) - return EOF; - len++; -\& - if (!info\->group || (i % 4)) - continue; - if (fputc(GROUP_SEP, stream) == EOF) - return EOF; - len++; - } -\& - return len; -} -\& -static ssize_t -b_print_number(FILE *stream, const struct printf_info *info, - const char bin[UINTMAX_WIDTH], - size_t min_len, size_t bin_len) -{ - ssize_t len; -\& - len = 0; -\& - /* Print leading zeros to fill precision */ - for (size_t i = bin_len \- 1; i > min_len \- 1; i\-\-) { - if (fputc(\[aq]0\[aq], stream) == EOF) - return EOF; - len++; -\& - if (!info\->group || (i % 4)) - continue; - if (fputc(GROUP_SEP, stream) == EOF) - return EOF; - len++; - } -\& - /* Print number */ - for (size_t i = min_len \- 1; i < min_len; i\-\-) { - if (fputc(bin[i], stream) == EOF) - return EOF; - len++; -\& - if (!info\->group || (i % 4) || !i) - continue; - if (fputc(GROUP_SEP, stream) == EOF) - return EOF; - len++; - } -\& - return len; -} -\& -static char -pad_ch(const struct printf_info *info) -{ - if ((info\->prec != \-1) || (info\->pad == \[aq] \[aq]) || info\->left) - return \[aq] \[aq]; - return \[aq]0\[aq]; -} -\& -static ssize_t -pad_spaces(FILE *stream, size_t pad_len) -{ - ssize_t len; -\& - len = 0; - for (size_t i = pad_len - 1; i < pad_len; i\-\-) { - if (fputc(\[aq] \[aq], stream) == EOF) - return EOF; - len++; - } -\& - return len; -} -.EE -.\" SRC END -.SH SEE ALSO -.BR asprintf (3), -.BR printf (3), -.BR wprintf (3) diff --git a/man3head/sysexits.h.3head b/man3head/sysexits.h.3head deleted file mode 100644 index f373234..0000000 --- a/man3head/sysexits.h.3head +++ /dev/null @@ -1,200 +0,0 @@ -'\" t -.\" Copyright (c) 1996 Joerg Wunsch -.\" Copyright (c) 2022 Alejandro Colomar <alx@kernel.org> -.\" -.\" All rights reserved. -.\" -.\" SPDX-License-Identifier: BSD-2-Clause -.\" -.\" Rewritten for the Linux man-pages by Alejandro Colomar -.\" -.TH sysexits.h 3head 2023-10-31 "Linux man-pages 6.7" -.SH NAME -sysexits.h \- exit codes for programs -.SH LIBRARY -Standard C library -.RI ( libc ) -.SH SYNOPSIS -.nf -.B #include <sysexits.h> -.fi -.TS -lB2 lB2 l1 lX. -#define EX_OK 0 /* T{ -successful termination */ -T} -.P -#define EX__BASE 64 /* T{ -base value for error messages */ -T} -.P -#define EX_USAGE 64 /* T{ -command line usage error */ -T} -#define EX_DATAERR 65 /* T{ -data format error */ -T} -#define EX_NOINPUT 66 /* T{ -cannot open input */ -T} -#define EX_NOUSER 67 /* T{ -addressee unknown */ -T} -#define EX_NOHOST 68 /* T{ -host name unknown */ -T} -#define EX_UNAVAILABLE 69 /* T{ -service unavailable */ -T} -#define EX_SOFTWARE 70 /* T{ -internal software error */ -T} -#define EX_OSERR 71 /* T{ -system error (e.g., can't fork) */ -T} -#define EX_OSFILE 72 /* T{ -critical OS file missing */ -T} -#define EX_CANTCREAT 73 /* T{ -can't create (user) output file */ -T} -#define EX_IOERR 74 /* T{ -input/output error */ -T} -#define EX_TEMPFAIL 75 /* T{ -temp failure; user is invited to retry */ -T} -#define EX_PROTOCOL 76 /* T{ -remote error in protocol */ -T} -#define EX_NOPERM 77 /* T{ -permission denied */ -T} -#define EX_CONFIG 78 /* T{ -configuration error */ -T} -.P -.T& -lB2 l2 l1 lX. -#define EX__MAX ... /* T{ -maximum listed value */ -T} -.TE -.SH DESCRIPTION -A few programs exit with the following error codes. -.P -The successful exit is always indicated by a status of -.BR 0 , -or -.B EX_OK -(equivalent to -.B EXIT_SUCCESS -from -.IR <stdlib.h> ). -Error numbers begin at -.B EX__BASE -to reduce the possibility of clashing with other exit statuses -that random programs may already return. -The meaning of the code is approximately as follows: -.TP -.B EX_USAGE -The command was used incorrectly, -e.g., -with the wrong number of arguments, -a bad flag, -bad syntax in a parameter, -or whatever. -.TP -.B EX_DATAERR -The input data was incorrect in some way. -This should only be used for user's data and not system files. -.TP -.B EX_NOINPUT -An input file (not a system file) did not exist or was not readable. -This could also include errors like "No message" to a mailer -(if it cared to catch it). -.TP -.B EX_NOUSER -The user specified did not exist. -This might be used for mail addresses or remote logins. -.TP -.B EX_NOHOST -The host specified did not exist. -This is used in mail addresses or network requests. -.TP -.B EX_UNAVAILABLE -A service is unavailable. -This can occur if a support program or file does not exist. -This can also be used as a catch-all message -when something you wanted to do doesn't work, but you don't know why. -.TP -.B EX_SOFTWARE -An internal software error has been detected. -This should be limited to non-operating system related errors if possible. -.TP -.B EX_OSERR -An operating system error has been detected. -This is intended to be used for such things as -"cannot fork", -"cannot create pipe", -or the like. -It includes things like -.BR getuid (2) -returning a user that does not exist in the -.BR passwd (5) -file. -.TP -.B EX_OSFILE -Some system file -(e.g., -.IR /etc/passwd , -.IR /etc/utmp , -etc.) -does not exist, -cannot be opened, -or has some sort of error (e.g., syntax error). -.TP -.B EX_CANTCREAT -A (user specified) output file cannot be created. -.TP -.B EX_IOERR -An error occurred while doing I/O on some file. -.TP -.B EX_TEMPFAIL -Temporary failure, -indicating something that is not really an error. -For example that a mailer could not create a connection, -and the request should be reattempted later. -.TP -.B EX_PROTOCOL -The remote system returned something that -was "not possible" during a protocol exchange. -.TP -.B EX_OSFILE -You did not have sufficient permission to perform the operation. -This is not intended for file system problems, -which should use -.B EX_NOINPUT -or -.BR EX_CANTCREAT , -but rather for higher level permissions. -.TP -.B EX_CONFIG -Something was found in an unconfigured or misconfigured state. -.P -The numerical values corresponding to the symbolical ones -are given in parenthesis for easy reference. -.SH STANDARDS -BSD. -.SH HISTORY -The -.I <sysexits.h> -file appeared in 4.0BSD for use by the deliverymail utility, -later renamed to -.BR sendmail (8). -.SH CAVEATS -The choice of an appropriate exit value is often ambiguous. -.SH SEE ALSO -.BR err (3), -.BR error (3), -.BR exit (3) |