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