/** * slibc — Yet another C library * Copyright © 2015 Mattias Andrée (maandree@member.fsf.org) * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. */ #ifndef _SLIBC_PRINT_H #define _SLIBC_PRINT_H #include <slibc/version.h> #include <slibc/features.h> #ifndef __PORTABLE #define __NEED_size_t #define __NEED_ssize_t #define __NEED_wchar_t #define __NEED_intmax_t #define __NEED_va_list #include <bits/types.h> /** * Structure used by extensions to `generic_printf`-function * to request that additionally arguments be added before the * function is called again. * * @etymology (`generic_printf`)-subsystem: (ext)ension (queue). * * @since Always. */ struct generic_printf_ext_queue { /** * Sizes, in bytes, of the missing arguments. * Only 1, 2, 4 and 8 are allowed. * * @since Always. */ char sizes[4]; /** * The indices of the missing arguments. * * @since Always. */ size_t indices[4]; /** * The amount of missing arguments. * `sizes` and `indices` can only hold up to * 4 arguments, the function will be later * again to retrieve information about the * omitted arguments. To avoid a deadlock, * add arguments in the order of their index * if there are more than 4 missing arguments. * * @since Always. */ size_t count; }; /** * Function-type used by `generic_printf` and `vgeneric_wprintf` * to write a string. * * @etymology (`generic_printf`)-subsystem: (write-func)tion, `(t)ypedef`. * * @param text The text segment to print, it will only contain * a NUL byte if that NUL byte shall be printed. * @param length The length of `text`. * @param data The value passed to `generic_printf` or * `vgeneric_wprintf` via the parameter `data`. * @return Zero on success, -1 on error. `errno` shall * be set on error. * * @since Always. */ typedef int (* generic_printf_write_func_t)(const char*, size_t, void*); /** * Variant of `generic_printf_write_func_t` used for * `generic_wprintf` and `vgeneric_wprintf`. * * @etymology (`generic_wprintf`)-subsystem: (write-func)tion, `(t)ypedef`. * * @since Always. */ typedef int (* generic_wprintf_write_func_t)(const wchar_t*, size_t, void*); /** * Function-type used by `generic_printf` and `vgeneric_wprintf` * to write a string if a custom formatting code was encountered. * * @etymology (`generic_printf`)-subsystem: (ext)ension(-func)tion, `(t)ypedef`. * * @param code The %-code, excluding the %. * @param args Formatting arguments cased to `intmax`. * @param argn The number of formatting arguments in `args`. * @param silent Non-zero if the function must not perform a write. * @param data The value passed to `generic_printf` or * `vgeneric_wprintf` via the parameter `data`. * @param queue_data Used to send information to the calling function * about missing arguments. * @return The number of written characters, -1 on error. * `errno` shall be set on error. -2 shall be returned * if argument index equal to or greater than the * value of `argn`, if `queue_data` must be set. * * @throws EINVAL If `code` could not be recognised. * * @since Always. */ typedef ssize_t (* generic_printf_ext_func_t)(const char*, intmax_t*, size_t, int, void*, struct generic_printf_ext_queue*); /** * Variant of `generic_printf_ext_func_t` used for * `generic_wprintf` and `vgeneric_wprintf`. * * @etymology (`generic_wprintf`)-subsystem: (ext)ension(-func)tion, `(t)ypedef`. * * @since Always. */ typedef ssize_t (* generic_wprintf_ext_func_t)(const wchar_t*, intmax_t*, size_t, int, void*, struct generic_printf_ext_queue*); /** * An almost fully generic `printf`-function. * * @etymology (Generic) (`wprintf`)-function. * * @param write_function Function used to write the string. `NULL` if * it shall not be printed but only measured. * @param extension_function Function used to extend the functions formatting codes. * `NULL` if not extensions are to be used. * @param maximum_length The maximum amount of bytes to write, including the * NUL byte, ignored if `limited_length` is zero. * @param limited_length Whether `maximum_length` shall be used. * @param actual_length Output parameter for the length of the printed string, * this includes any text that was truncated but not the * NUL character. Must not be `NULL`. * @param terminate Whether a NUL character shall be printed at the end. * @param data Data to pass to `write_function` and * `extension_function`, it should contain * the print-sink, and any state data neccessary * since the functions may be called multiple times. * @param format The formatting-string, see `fprintf` for details. * @param ... The formatting-arguments. * @return Zero on success, -1 on error. On error, `errno` * is set to indicate the error. * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. * * @since Always. */ int generic_printf(generic_printf_write_func_t, generic_printf_ext_func_t, size_t, int, size_t* restrict, int, void*, const char*, ...) __GCC_ONLY(__attribute__((__nonnull__(5, 8), __format__(__slibc_printf__, 8, 9), __warn_unused_result__))); /** * Variant of `generic_printf` that uses `va_list` * instead of variadic arguments. * * @etymology (V)ariadic version of (`generic_printf`). * * @param write_function Function used to write the string. `NULL` if * it shall not be printed but only measured. * @param extension_function Function used to extend the functions formatting codes. * `NULL` if not extensions are to be used. * @param maximum_length The maximum amount of bytes to write, including the * NUL byte, ignored if `limited_length` is zero. * @param limited_length Whether `maximum_length` shall be used. * @param actual_length Output parameter for the length of the printed string, * this includes any text that was truncated but not the * NUL character. Must not be `NULL`. * @param terminate Whether a NUL character shall be printed at the end. * @param data Data to pass to `write_function` and * `extension_function`, it should contain * the print-sink, and any state data neccessary * since the functions may be called multiple times. * @param format The formatting-string, see `fprintf` for details. * @param args The formatting-arguments. * @return Zero on success, -1 on error. On error, `errno` * is set to indicate the error. * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. * * @since Always. */ int vgeneric_printf(generic_printf_write_func_t, generic_printf_ext_func_t, size_t, int, size_t* restrict, int, void*, const char*, va_list) __GCC_ONLY(__attribute__((__nonnull__(5, 8), __warn_unused_result__))); /** * Variant of `generic_printf` uses `wchar_t` instead of `char`; * * @etymology (Generic) (`printf`)-function. * * @param write_function Function used to write the string. `NULL` if * it shall not be printed but only measured. * @param extension_function Function used to extend the functions formatting codes. * `NULL` if not extensions are to be used. * @param maximum_length The maximum amount of wide characters to write, * including the NUL wide character, ignored if * `limited_length` is zero. * @param limited_length Whether `maximum_length` shall be used. * @param actual_length Output parameter for the length of the printed string, * this includes any text that was truncated but not the * NUL character. Must not be `NULL`. * @param terminate Whether a NUL character shall be printed at the end. * @param data Data to pass to `write_function` and * `extension_function`, it should contain * the print-sink, and any state data neccessary * since the functions may be called multiple times. * @param format The formatting-string, see `fprintf` for details. * @param ... The formatting-arguments. * @return Zero on success, -1 on error. On error, `errno` * is set to indicate the error. * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. * * @since Always. */ int generic_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t, size_t, int, size_t* restrict, int, void*, const wchar_t*, ...) __GCC_ONLY(__attribute__((__nonnull__(5, 8), __warn_unused_result__))); /** * Variant of `generic_wprintf` that uses `va_list` * instead of variadic arguments. * * @etymology (V)ariadic version of (`generic_wprintf`). * * @param write_function Function used to write the string. `NULL` if * it shall not be printed but only measured. * @param extension_function Function used to extend the functions formatting codes. * `NULL` if not extensions are to be used. * @param maximum_length The maximum amount of wide characters to write, * including the NUL wide character, ignored if * `limited_length` is zero. * @param limited_length Whether `maximum_length` shall be used. * @param actual_length Output parameter for the length of the printed string, * this includes any text that was truncated but not the * NUL character. Must not be `NULL`. * @param terminate Whether a NUL character shall be printed at the end. * @param data Data to pass to `write_function` and * `extension_function`, it should contain * the print-sink, and any state data neccessary * since the functions may be called multiple times. * @param format The formatting-string, see `fprintf` for details. * @param ... The formatting-arguments. * @return Zero on success, -1 on error. On error, `errno` * is set to indicate the error. * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. * * @since Always. */ int vgeneric_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t, size_t, int, size_t* restrict, int, void*, const wchar_t*, va_list) __GCC_ONLY(__attribute__((__nonnull__(5, 8), __warn_unused_result__))); #endif #endif