Fix typos

[TortoiseGit.git] / src / TortoisePlink / MISC.H

/*\r
 * Header for miscellaneous helper functions, mostly defined in the\r
 * utils subdirectory.\r
 */\r
\r
#ifndef PUTTY_MISC_H\r
#define PUTTY_MISC_H\r
\r
#include "defs.h"\r
#include "puttymem.h"\r
#include "marshal.h"\r
\r
#include <stdio.h>                     /* for FILE * */\r
#include <stdarg.h>                    /* for va_list */\r
#include <stdlib.h>                    /* for abort */\r
#include <time.h>                      /* for struct tm */\r
#include <limits.h>                    /* for INT_MAX/MIN */\r
#include <assert.h>                    /* for assert (obviously) */\r
\r
unsigned long parse_blocksize(const char *bs);\r
char ctrlparse(char *s, char **next);\r
\r
size_t host_strcspn(const char *s, const char *set);\r
char *host_strchr(const char *s, int c);\r
char *host_strrchr(const char *s, int c);\r
char *host_strduptrim(const char *s);\r
\r
char *dupstr(const char *s);\r
char *dupcat_fn(const char *s1, ...);\r
#define dupcat(...) dupcat_fn(__VA_ARGS__, (const char *)NULL)\r
char *dupprintf(const char *fmt, ...) PRINTF_LIKE(1, 2);\r
char *dupvprintf(const char *fmt, va_list ap);\r
void burnstr(char *string);\r
\r
/*\r
 * The visible part of a strbuf structure. There's a surrounding\r
 * implementation struct in strbuf.c, which isn't exposed to client\r
 * code.\r
 */\r
struct strbuf {\r
    char *s;\r
    unsigned char *u;\r
    size_t len;\r
    BinarySink_IMPLEMENTATION;\r
};\r
\r
/* strbuf constructors: strbuf_new_nm and strbuf_new differ in that a\r
 * strbuf constructed using the _nm version will resize itself by\r
 * alloc/copy/smemclr/free instead of realloc. Use that version for\r
 * data sensitive enough that it's worth costing performance to\r
 * avoid copies of it lingering in process memory. */\r
strbuf *strbuf_new(void);\r
strbuf *strbuf_new_nm(void);\r
\r
/* Helpers to allocate a strbuf containing an existing string */\r
strbuf *strbuf_dup(ptrlen string);\r
strbuf *strbuf_dup_nm(ptrlen string);\r
\r
void strbuf_free(strbuf *buf);\r
void *strbuf_append(strbuf *buf, size_t len);\r
void strbuf_shrink_to(strbuf *buf, size_t new_len);\r
void strbuf_shrink_by(strbuf *buf, size_t amount_to_remove);\r
char *strbuf_to_str(strbuf *buf); /* does free buf, but you must free result */\r
static inline void strbuf_clear(strbuf *buf) { strbuf_shrink_to(buf, 0); }\r
bool strbuf_chomp(strbuf *buf, char char_to_remove);\r
\r
strbuf *strbuf_new_for_agent_query(void);\r
void strbuf_finalise_agent_query(strbuf *buf);\r
\r
/* String-to-Unicode converters that auto-allocate the destination and\r
 * work around the rather deficient interface of mb_to_wc. */\r
wchar_t *dup_mb_to_wc_c(int codepage, int flags, const char *string, int len);\r
wchar_t *dup_mb_to_wc(int codepage, int flags, const char *string);\r
char *dup_wc_to_mb_c(int codepage, int flags, const wchar_t *string, int len,\r
                     const char *defchr);\r
char *dup_wc_to_mb(int codepage, int flags, const wchar_t *string,\r
                   const char *defchr);\r
\r
static inline int toint(unsigned u)\r
{\r
    /*\r
     * Convert an unsigned to an int, without running into the\r
     * undefined behaviour which happens by the strict C standard if\r
     * the value overflows. You'd hope that sensible compilers would\r
     * do the sensible thing in response to a cast, but actually I\r
     * don't trust modern compilers not to do silly things like\r
     * assuming that _obviously_ you wouldn't have caused an overflow\r
     * and so they can elide an 'if (i < 0)' test immediately after\r
     * the cast.\r
     *\r
     * Sensible compilers ought of course to optimise this entire\r
     * function into 'just return the input value', and since it's\r
     * also declared inline, elide it completely in their output.\r
     */\r
    if (u <= (unsigned)INT_MAX)\r
        return (int)u;\r
    else if (u >= (unsigned)INT_MIN)   /* wrap in cast _to_ unsigned is OK */\r
        return INT_MIN + (int)(u - (unsigned)INT_MIN);\r
    else\r
        return INT_MIN; /* fallback; should never occur on binary machines */\r
}\r
\r
char *fgetline(FILE *fp);\r
bool read_file_into(BinarySink *bs, FILE *fp);\r
char *chomp(char *str);\r
bool strstartswith(const char *s, const char *t);\r
bool strendswith(const char *s, const char *t);\r
\r
void base64_encode_atom(const unsigned char *data, int n, char *out);\r
int base64_decode_atom(const char *atom, unsigned char *out);\r
void base64_decode_bs(BinarySink *bs, ptrlen data);\r
void base64_decode_fp(FILE *fp, ptrlen data);\r
strbuf *base64_decode_sb(ptrlen data);\r
void base64_encode_bs(BinarySink *bs, ptrlen data, int cpl);\r
void base64_encode_fp(FILE *fp, ptrlen data, int cpl);\r
strbuf *base64_encode_sb(ptrlen data, int cpl);\r
bool base64_valid(ptrlen data);\r
\r
void percent_encode_bs(BinarySink *bs, ptrlen data, const char *badchars);\r
void percent_encode_fp(FILE *fp, ptrlen data, const char *badchars);\r
strbuf *percent_encode_sb(ptrlen data, const char *badchars);\r
void percent_decode_bs(BinarySink *bs, ptrlen data);\r
void percent_decode_fp(FILE *fp, ptrlen data);\r
strbuf *percent_decode_sb(ptrlen data);\r
\r
struct bufchain_granule;\r
struct bufchain_tag {\r
    struct bufchain_granule *head, *tail;\r
    size_t buffersize;           /* current amount of buffered data */\r
\r
    void (*queue_idempotent_callback)(IdempotentCallback *ic);\r
    IdempotentCallback *ic;\r
};\r
\r
void bufchain_init(bufchain *ch);\r
void bufchain_clear(bufchain *ch);\r
size_t bufchain_size(bufchain *ch);\r
void bufchain_add(bufchain *ch, const void *data, size_t len);\r
ptrlen bufchain_prefix(bufchain *ch);\r
void bufchain_consume(bufchain *ch, size_t len);\r
void bufchain_fetch(bufchain *ch, void *data, size_t len);\r
void bufchain_fetch_consume(bufchain *ch, void *data, size_t len);\r
bool bufchain_try_consume(bufchain *ch, size_t len);\r
bool bufchain_try_fetch(bufchain *ch, void *data, size_t len);\r
bool bufchain_try_fetch_consume(bufchain *ch, void *data, size_t len);\r
size_t bufchain_fetch_consume_up_to(bufchain *ch, void *data, size_t len);\r
void bufchain_set_callback_inner(\r
    bufchain *ch, IdempotentCallback *ic,\r
    void (*queue_idempotent_callback)(IdempotentCallback *ic));\r
static inline void bufchain_set_callback(bufchain *ch, IdempotentCallback *ic)\r
{\r
    extern void queue_idempotent_callback(struct IdempotentCallback *ic);\r
    /* Wrapper that puts in the standard queue_idempotent_callback\r
     * function. Lives here rather than in bufchain.c so that\r
     * standalone programs can use the bufchain facility without this\r
     * optional callback feature and not need to provide a stub of\r
     * queue_idempotent_callback. */\r
    bufchain_set_callback_inner(ch, ic, queue_idempotent_callback);\r
}\r
\r
bool validate_manual_hostkey(char *key);\r
\r
struct tm ltime(void);\r
\r
/*\r
 * Special form of strcmp which can cope with NULL inputs. NULL is\r
 * defined to sort before even the empty string.\r
 */\r
int nullstrcmp(const char *a, const char *b);\r
\r
static inline ptrlen make_ptrlen(const void *ptr, size_t len)\r
{\r
    ptrlen pl;\r
    pl.ptr = ptr;\r
    pl.len = len;\r
    return pl;\r
}\r
\r
static inline const void *ptrlen_end(ptrlen pl)\r
{\r
    return (const char *)pl.ptr + pl.len;\r
}\r
\r
static inline ptrlen make_ptrlen_startend(const void *startv, const void *endv)\r
{\r
    const char *start = (const char *)startv, *end = (const char *)endv;\r
    assert(end >= start);\r
    ptrlen pl;\r
    pl.ptr = start;\r
    pl.len = end - start;\r
    return pl;\r
}\r
\r
static inline ptrlen ptrlen_from_asciz(const char *str)\r
{\r
    return make_ptrlen(str, strlen(str));\r
}\r
\r
static inline ptrlen ptrlen_from_strbuf(strbuf *sb)\r
{\r
    return make_ptrlen(sb->u, sb->len);\r
}\r
\r
bool ptrlen_eq_string(ptrlen pl, const char *str);\r
bool ptrlen_eq_ptrlen(ptrlen pl1, ptrlen pl2);\r
int ptrlen_strcmp(ptrlen pl1, ptrlen pl2);\r
/* ptrlen_startswith and ptrlen_endswith write through their 'tail'\r
 * argument if and only if it is non-NULL and they return true. Hence\r
 * you can write ptrlen_startswith(thing, prefix, &thing), writing\r
 * back to the same ptrlen it read from, to remove a prefix if present\r
 * and say whether it did so. */\r
bool ptrlen_startswith(ptrlen whole, ptrlen prefix, ptrlen *tail);\r
bool ptrlen_endswith(ptrlen whole, ptrlen suffix, ptrlen *tail);\r
ptrlen ptrlen_get_word(ptrlen *input, const char *separators);\r
bool ptrlen_contains(ptrlen input, const char *characters);\r
bool ptrlen_contains_only(ptrlen input, const char *characters);\r
char *mkstr(ptrlen pl);\r
int string_length_for_printf(size_t);\r
/* Derive two printf arguments from a ptrlen, suitable for "%.*s" */\r
#define PTRLEN_PRINTF(pl) \\r
    string_length_for_printf((pl).len), (const char *)(pl).ptr\r
/* Make a ptrlen out of a compile-time string literal. We try to\r
 * enforce that it _is_ a string literal by token-pasting "" on to it,\r
 * which should provoke a compile error if it's any other kind of\r
 * string. */\r
#define PTRLEN_LITERAL(stringlit) \\r
    TYPECHECK("" stringlit "", make_ptrlen(stringlit, sizeof(stringlit)-1))\r
/* Make a ptrlen out of a compile-time string literal in a way that\r
 * allows you to declare the ptrlen itself as a compile-time initialiser. */\r
#define PTRLEN_DECL_LITERAL(stringlit) \\r
    { TYPECHECK("" stringlit "", stringlit), sizeof(stringlit)-1 }\r
/* Make a ptrlen out of a constant byte array. */\r
#define PTRLEN_FROM_CONST_BYTES(a) make_ptrlen(a, sizeof(a))\r
\r
void wordwrap(BinarySink *bs, ptrlen input, size_t maxwid);\r
\r
/* Wipe sensitive data out of memory that's about to be freed. Simpler\r
 * than memset because we don't need the fill char parameter; also\r
 * attempts (by fiddly use of volatile) to inhibit the compiler from\r
 * over-cleverly trying to optimise the memset away because it knows\r
 * the variable is going out of scope. */\r
void smemclr(void *b, size_t len);\r
\r
/* Compare two fixed-length chunks of memory for equality, without\r
 * data-dependent control flow (so an attacker with a very accurate\r
 * stopwatch can't try to guess where the first mismatching byte was).\r
 * Returns 0 for mismatch or 1 for equality (unlike memcmp), hinted at\r
 * by the 'eq' in the name. */\r
unsigned smemeq(const void *av, const void *bv, size_t len);\r
\r
/* Encode a single UTF-8 character. Assumes that illegal characters\r
 * (such as things in the surrogate range, or > 0x10FFFF) have already\r
 * been removed. */\r
size_t encode_utf8(void *output, unsigned long ch);\r
\r
/* Encode a wide-character string into UTF-8. Tolerates surrogates if\r
 * sizeof(wchar_t) == 2, assuming that in that case the wide string is\r
 * encoded in UTF-16. */\r
char *encode_wide_string_as_utf8(const wchar_t *wstr);\r
\r
/* Decode a single UTF-8 character. Returns U+FFFD for any of the\r
 * illegal cases. */\r
unsigned long decode_utf8(const char **utf8);\r
\r
/* Decode a single UTF-8 character to an output buffer of the\r
 * platform's wchar_t. May write a pair of surrogates if\r
 * sizeof(wchar_t) == 2, assuming that in that case the wide string is\r
 * encoded in UTF-16. Otherwise, writes one character. Returns the\r
 * number written. */\r
size_t decode_utf8_to_wchar(const char **utf8, wchar_t *out);\r
\r
/* Write a string out in C string-literal format. */\r
void write_c_string_literal(FILE *fp, ptrlen str);\r
\r
char *buildinfo(const char *newline);\r
\r
/*\r
 * A function you can put at points in the code where execution should\r
 * never reach in the first place. Better than assert(false), or even\r
 * assert(false && "some explanatory message"), because some compilers\r
 * don't interpret assert(false) as a declaration of unreachability,\r
 * so they may still warn about pointless things like some variable\r
 * not being initialised on the unreachable code path.\r
 *\r
 * I follow the assertion with a call to abort() just in case someone\r
 * compiles with -DNDEBUG, and I wrap that abort inside my own\r
 * function labelled NORETURN just in case some unusual kind of system\r
 * header wasn't foresighted enough to label abort() itself that way.\r
 */\r
static inline NORETURN void unreachable_internal(void) { abort(); }\r
#define unreachable(msg) (assert(false && msg), unreachable_internal())\r
\r
/*\r
 * Debugging functions.\r
 *\r
 * Output goes to debug.log\r
 *\r
 * debug() is like printf().\r
 *\r
 * dmemdump() and dmemdumpl() both do memory dumps.  The difference\r
 * is that dmemdumpl() is more suited for when the memory address is\r
 * important (say because you'll be recording pointer values later\r
 * on).  dmemdump() is more concise.\r
 */\r
\r
#ifdef DEBUG\r
void debug_printf(const char *fmt, ...) PRINTF_LIKE(1, 2);\r
void debug_memdump(const void *buf, int len, bool L);\r
#define debug(...) (debug_printf(__VA_ARGS__))\r
#define dmemdump(buf,len) (debug_memdump(buf, len, false))\r
#define dmemdumpl(buf,len) (debug_memdump(buf, len, true))\r
#else\r
#define debug(...) ((void)0)\r
#define dmemdump(buf,len) ((void)0)\r
#define dmemdumpl(buf,len) ((void)0)\r
#endif\r
\r
#ifndef lenof\r
#define lenof(x) ( (sizeof((x))) / (sizeof(*(x))))\r
#endif\r
\r
#ifndef min\r
#define min(x,y) ( (x) < (y) ? (x) : (y) )\r
#endif\r
#ifndef max\r
#define max(x,y) ( (x) > (y) ? (x) : (y) )\r
#endif\r
\r
static inline uint64_t GET_64BIT_LSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint64_t)p[0]      ) | ((uint64_t)p[1] <<  8) |\r
            ((uint64_t)p[2] << 16) | ((uint64_t)p[3] << 24) |\r
            ((uint64_t)p[4] << 32) | ((uint64_t)p[5] << 40) |\r
            ((uint64_t)p[6] << 48) | ((uint64_t)p[7] << 56));\r
}\r
\r
static inline void PUT_64BIT_LSB_FIRST(void *vp, uint64_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[0] = (uint8_t)(value);\r
    p[1] = (uint8_t)(value >> 8);\r
    p[2] = (uint8_t)(value >> 16);\r
    p[3] = (uint8_t)(value >> 24);\r
    p[4] = (uint8_t)(value >> 32);\r
    p[5] = (uint8_t)(value >> 40);\r
    p[6] = (uint8_t)(value >> 48);\r
    p[7] = (uint8_t)(value >> 56);\r
}\r
\r
static inline uint32_t GET_32BIT_LSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint32_t)p[0]      ) | ((uint32_t)p[1] <<  8) |\r
            ((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24));\r
}\r
\r
static inline void PUT_32BIT_LSB_FIRST(void *vp, uint32_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[0] = (uint8_t)(value);\r
    p[1] = (uint8_t)(value >> 8);\r
    p[2] = (uint8_t)(value >> 16);\r
    p[3] = (uint8_t)(value >> 24);\r
}\r
\r
static inline uint16_t GET_16BIT_LSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint16_t)p[0]      ) | ((uint16_t)p[1] <<  8));\r
}\r
\r
static inline void PUT_16BIT_LSB_FIRST(void *vp, uint16_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[0] = (uint8_t)(value);\r
    p[1] = (uint8_t)(value >> 8);\r
}\r
\r
static inline uint64_t GET_64BIT_MSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint64_t)p[7]      ) | ((uint64_t)p[6] <<  8) |\r
            ((uint64_t)p[5] << 16) | ((uint64_t)p[4] << 24) |\r
            ((uint64_t)p[3] << 32) | ((uint64_t)p[2] << 40) |\r
            ((uint64_t)p[1] << 48) | ((uint64_t)p[0] << 56));\r
}\r
\r
static inline void PUT_64BIT_MSB_FIRST(void *vp, uint64_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[7] = (uint8_t)(value);\r
    p[6] = (uint8_t)(value >> 8);\r
    p[5] = (uint8_t)(value >> 16);\r
    p[4] = (uint8_t)(value >> 24);\r
    p[3] = (uint8_t)(value >> 32);\r
    p[2] = (uint8_t)(value >> 40);\r
    p[1] = (uint8_t)(value >> 48);\r
    p[0] = (uint8_t)(value >> 56);\r
}\r
\r
static inline uint32_t GET_32BIT_MSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint32_t)p[3]      ) | ((uint32_t)p[2] <<  8) |\r
            ((uint32_t)p[1] << 16) | ((uint32_t)p[0] << 24));\r
}\r
\r
static inline void PUT_32BIT_MSB_FIRST(void *vp, uint32_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[3] = (uint8_t)(value);\r
    p[2] = (uint8_t)(value >> 8);\r
    p[1] = (uint8_t)(value >> 16);\r
    p[0] = (uint8_t)(value >> 24);\r
}\r
\r
static inline uint16_t GET_16BIT_MSB_FIRST(const void *vp)\r
{\r
    const uint8_t *p = (const uint8_t *)vp;\r
    return (((uint16_t)p[1]      ) | ((uint16_t)p[0] <<  8));\r
}\r
\r
static inline void PUT_16BIT_MSB_FIRST(void *vp, uint16_t value)\r
{\r
    uint8_t *p = (uint8_t *)vp;\r
    p[1] = (uint8_t)(value);\r
    p[0] = (uint8_t)(value >> 8);\r
}\r
\r
/* For use in X11-related applications, an endianness-variable form of\r
 * {GET,PUT}_16BIT which expects 'endian' to be either 'B' or 'l' */\r
\r
static inline uint16_t GET_16BIT_X11(char endian, const void *p)\r
{\r
    return endian == 'B' ? GET_16BIT_MSB_FIRST(p) : GET_16BIT_LSB_FIRST(p);\r
}\r
\r
static inline void PUT_16BIT_X11(char endian, void *p, uint16_t value)\r
{\r
    if (endian == 'B')\r
        PUT_16BIT_MSB_FIRST(p, value);\r
    else\r
        PUT_16BIT_LSB_FIRST(p, value);\r
}\r
\r
/* Replace NULL with the empty string, permitting an idiom in which we\r
 * get a string (pointer,length) pair that might be NULL,0 and can\r
 * then safely say things like printf("%.*s", length, NULLTOEMPTY(ptr)) */\r
static inline const char *NULLTOEMPTY(const char *s)\r
{\r
    return s ? s : "";\r
}\r
\r
/* StripCtrlChars, defined in stripctrl.c: an adapter you can put on\r
 * the front of one BinarySink and which functions as one in turn.\r
 * Interprets its input as a stream of multibyte characters in the\r
 * system locale, and removes any that are not either printable\r
 * characters or newlines. */\r
struct StripCtrlChars {\r
    BinarySink_IMPLEMENTATION;\r
    /* and this is contained in a larger structure */\r
};\r
StripCtrlChars *stripctrl_new(\r
    BinarySink *bs_out, bool permit_cr, wchar_t substitution);\r
StripCtrlChars *stripctrl_new_term_fn(\r
    BinarySink *bs_out, bool permit_cr, wchar_t substitution,\r
    Terminal *term, unsigned long (*translate)(\r
        Terminal *, term_utf8_decode *, unsigned char));\r
#define stripctrl_new_term(bs, cr, sub, term) \\r
    stripctrl_new_term_fn(bs, cr, sub, term, term_translate)\r
void stripctrl_retarget(StripCtrlChars *sccpub, BinarySink *new_bs_out);\r
void stripctrl_reset(StripCtrlChars *sccpub);\r
void stripctrl_free(StripCtrlChars *sanpub);\r
void stripctrl_enable_line_limiting(StripCtrlChars *sccpub);\r
char *stripctrl_string_ptrlen(StripCtrlChars *sccpub, ptrlen str);\r
static inline char *stripctrl_string(StripCtrlChars *sccpub, const char *str)\r
{\r
    return stripctrl_string_ptrlen(sccpub, ptrlen_from_asciz(str));\r
}\r
\r
/*\r
 * A mechanism for loading a file from disk into a memory buffer where\r
 * it can be picked apart as a BinarySource.\r
 */\r
struct LoadedFile {\r
    char *data;\r
    size_t len, max_size;\r
    BinarySource_IMPLEMENTATION;\r
};\r
typedef enum {\r
    LF_OK,      /* file loaded successfully */\r
    LF_TOO_BIG, /* file didn't fit in buffer */\r
    LF_ERROR,   /* error from stdio layer */\r
} LoadFileStatus;\r
LoadedFile *lf_new(size_t max_size);\r
void lf_free(LoadedFile *lf);\r
LoadFileStatus lf_load_fp(LoadedFile *lf, FILE *fp);\r
LoadFileStatus lf_load(LoadedFile *lf, const Filename *filename);\r
static inline ptrlen ptrlen_from_lf(LoadedFile *lf)\r
{ return make_ptrlen(lf->data, lf->len); }\r
\r
/* Set the memory block of 'size' bytes at 'out' to the bitwise XOR of\r
 * the two blocks of the same size at 'in1' and 'in2'.\r
 *\r
 * 'out' may point to exactly the same address as one of the inputs,\r
 * but if the input and output blocks overlap in any other way, the\r
 * result of this function is not guaranteed. No memmove-style effort\r
 * is made to handle difficult overlap cases. */\r
void memxor(uint8_t *out, const uint8_t *in1, const uint8_t *in2, size_t size);\r
\r
/* Boolean expressions used in OpenSSH certificate configuration */\r
bool cert_expr_valid(const char *expression,\r
                     char **error_msg, ptrlen *error_loc);\r
bool cert_expr_match_str(const char *expression,\r
                         const char *hostname, unsigned port);\r
/* Build a certificate expression out of hostname wildcards. Required\r
 * to handle legacy configuration from early in development, when\r
 * multiple wildcards were stored separately in config, implicitly\r
 * ORed together. */\r
CertExprBuilder *cert_expr_builder_new(void);\r
void cert_expr_builder_free(CertExprBuilder *eb);\r
void cert_expr_builder_add(CertExprBuilder *eb, const char *wildcard);\r
char *cert_expr_expression(CertExprBuilder *eb);\r
\r
#endif\r