1*128836d3SXin LI // SPDX-License-Identifier: 0BSD 2*128836d3SXin LI 3*128836d3SXin LI /////////////////////////////////////////////////////////////////////////////// 4*128836d3SXin LI // 5*128836d3SXin LI /// \file tuklib_mbstr_nonprint.h 6*128836d3SXin LI /// \brief Find and replace non-printable characters with question marks 7*128836d3SXin LI /// 8*128836d3SXin LI /// If mbrtowc(3) is available, it and iswprint(3) is used to check if all 9*128836d3SXin LI /// characters are printable. Otherwise single-byte character set is assumed 10*128836d3SXin LI /// and isprint(3) is used. 11*128836d3SXin LI // 12*128836d3SXin LI // Author: Lasse Collin 13*128836d3SXin LI // 14*128836d3SXin LI /////////////////////////////////////////////////////////////////////////////// 15*128836d3SXin LI 16*128836d3SXin LI #ifndef TUKLIB_MBSTR_NONPRINT_H 17*128836d3SXin LI #define TUKLIB_MBSTR_NONPRINT_H 18*128836d3SXin LI 19*128836d3SXin LI #include "tuklib_common.h" 20*128836d3SXin LI TUKLIB_DECLS_BEGIN 21*128836d3SXin LI 22*128836d3SXin LI #define tuklib_has_nonprint TUKLIB_SYMBOL(tuklib_has_nonprint) 23*128836d3SXin LI extern bool tuklib_has_nonprint(const char *str); 24*128836d3SXin LI ///< 25*128836d3SXin LI /// \brief Check if a string contains any non-printable characters 26*128836d3SXin LI /// 27*128836d3SXin LI /// \return false if str contains only valid multibyte characters and 28*128836d3SXin LI /// iswprint(3) returns non-zero for all of them; true otherwise. 29*128836d3SXin LI /// The value of errno is preserved. 30*128836d3SXin LI /// 31*128836d3SXin LI /// \note In case mbrtowc(3) isn't available, single-byte character set 32*128836d3SXin LI /// is assumed and isprint(3) is used instead of iswprint(3). 33*128836d3SXin LI 34*128836d3SXin LI #define tuklib_mask_nonprint_r TUKLIB_SYMBOL(tuklib_mask_nonprint_r) 35*128836d3SXin LI extern const char *tuklib_mask_nonprint_r(const char *str, char **mem); 36*128836d3SXin LI ///< 37*128836d3SXin LI /// \brief Replace non-printable characters with question marks 38*128836d3SXin LI /// 39*128836d3SXin LI /// \param str Untrusted string, for example, a filename 40*128836d3SXin LI /// \param mem This function always calls free(*mem) to free the old 41*128836d3SXin LI /// allocation and then sets *mem = NULL. Before the first 42*128836d3SXin LI /// call, *mem should be initialized to NULL. If this 43*128836d3SXin LI /// function needs to allocate memory for a modified 44*128836d3SXin LI /// string, a pointer to the allocated memory will be 45*128836d3SXin LI /// stored to *mem. Otherwise *mem will remain NULL. 46*128836d3SXin LI /// 47*128836d3SXin LI /// \return If tuklib_has_nonprint(str) returns false, this function 48*128836d3SXin LI /// returns str. Otherwise memory is allocated to hold a modified 49*128836d3SXin LI /// string and a pointer to that is returned. The pointer to the 50*128836d3SXin LI /// allocated memory is also stored to *mem. A modified string 51*128836d3SXin LI /// has the problematic characters replaced by '?'. If memory 52*128836d3SXin LI /// allocation fails, "???" is returned and *mem is NULL. 53*128836d3SXin LI /// The value of errno is preserved. 54*128836d3SXin LI 55*128836d3SXin LI #define tuklib_mask_nonprint TUKLIB_SYMBOL(tuklib_mask_nonprint) 56*128836d3SXin LI extern const char *tuklib_mask_nonprint(const char *str); 57*128836d3SXin LI ///< 58*128836d3SXin LI /// \brief Replace non-printable characters with question marks 59*128836d3SXin LI /// 60*128836d3SXin LI /// This is a convenience function for single-threaded use. This calls 61*128836d3SXin LI /// tuklib_mask_nonprint_r() using an internal static variable to hold 62*128836d3SXin LI /// the possible allocation. 63*128836d3SXin LI /// 64*128836d3SXin LI /// \param str Untrusted string, for example, a filename 65*128836d3SXin LI /// 66*128836d3SXin LI /// \return See tuklib_mask_nonprint_r(). 67*128836d3SXin LI /// 68*128836d3SXin LI /// \note This function is not thread safe! 69*128836d3SXin LI 70*128836d3SXin LI TUKLIB_DECLS_END 71*128836d3SXin LI #endif 72