github.com/kubiko/snapd@v0.0.0-20201013125620-d4f3094d9ddf/cmd/libsnap-confine-private/string-utils.h (about)

     1  /*
     2   * Copyright (C) 2016-2017 Canonical Ltd
     3   *
     4   * This program is free software: you can redistribute it and/or modify
     5   * it under the terms of the GNU General Public License version 3 as
     6   * published by the Free Software Foundation.
     7   *
     8   * This program is distributed in the hope that it will be useful,
     9   * but WITHOUT ANY WARRANTY; without even the implied warranty of
    10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    11   * GNU General Public License for more details.
    12   *
    13   * You should have received a copy of the GNU General Public License
    14   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    15   *
    16   */
    17  
    18  #ifndef SNAP_CONFINE_STRING_UTILS_H
    19  #define SNAP_CONFINE_STRING_UTILS_H
    20  
    21  #include <stdbool.h>
    22  #include <stddef.h>
    23  
    24  /**
    25   * Check if two strings are equal.
    26   **/
    27  bool sc_streq(const char *a, const char *b);
    28  
    29  /**
    30   * Check if a string has a given suffix.
    31   **/
    32  bool sc_endswith(const char *str, const char *suffix);
    33  
    34  /**
    35   * Check if a string has a given prefix.
    36   **/
    37  bool sc_startswith(const char *str, const char *prefix);
    38  
    39  /**
    40   * Allocate and return a copy of a string.
    41  **/
    42  char *sc_strdup(const char *str);
    43  
    44  /**
    45   * Safer version of snprintf.
    46   *
    47   * This version dies on any error condition.
    48   **/
    49  __attribute__((format(printf, 3, 4)))
    50  int sc_must_snprintf(char *str, size_t size, const char *format, ...);
    51  
    52  /**
    53   * Append a string to a buffer containing a string.
    54   *
    55   * This version is fully aware of the destination buffer and is extra careful
    56   * not to overflow it. If any argument is NULL or a buffer overflow is detected
    57   * then the function dies.
    58   *
    59   * The buffers cannot overlap.
    60   **/
    61  size_t sc_string_append(char *dst, size_t dst_size, const char *str);
    62  
    63  /**
    64   * Append a single character to a buffer containing a string.
    65   *
    66   * This version is fully aware of the destination buffer and is extra careful
    67   * not to overflow it. If any argument is NULL or a buffer overflow is detected
    68   * then the function dies.
    69   *
    70   * The character cannot be the string terminator.
    71   *
    72   * The return value is the new length of the string.
    73   **/
    74  size_t sc_string_append_char(char *dst, size_t dst_size, char c);
    75  
    76  /**
    77   * Append a pair of characters to a buffer containing a string.
    78   *
    79   * This version is fully aware of the destination buffer and is extra careful
    80   * not to overflow it. If any argument is NULL or a buffer overflow is detected
    81   * then the function dies.
    82   *
    83   * Neither character can be the string terminator.
    84   *
    85   * The return value is the new length of the string.
    86   **/
    87  size_t sc_string_append_char_pair(char *dst, size_t dst_size, char c1, char c2);
    88  
    89  /**
    90   * Initialize a string (make it empty).
    91   *
    92   * Initialize a string as empty, ensuring buf is non-NULL buf_size is > 0.
    93   **/
    94  void sc_string_init(char *buf, size_t buf_size);
    95  
    96  /**
    97   * Quote a string so it is safe for printing.
    98   *
    99   * This function is fully aware of the destination buffer and is extra careful
   100   * not to overflow it. If any argument is NULL or a buffer overflow is detected
   101   * then the function dies.
   102   *
   103   * The function "quotes" the content of the given string into the given buffer.
   104   * The buffer must be of sufficient size. Apart from letters and digits and
   105   * some punctuation all characters are escaped using their hexadecimal escape
   106   * codes.
   107   *
   108   * As a practical consideration the buffer should be of the following capacity:
   109   * strlen(str) * 4 + 2 + 1; This corresponds to the most pessimistic escape
   110   * process (each character is escaped to a hexadecimal value like \x05, two
   111   * double-quote characters (one front, one rear) and the final string
   112   * terminator character.
   113   **/
   114  void sc_string_quote(char *buf, size_t buf_size, const char *str);
   115  
   116  #endif