src/hash.h

   1 // Copyright (C) 2018 Joel Rosdahl
   2 //
   3 // This program is free software; you can redistribute it and/or modify it
   4 // under the terms of the GNU General Public License as published by the Free
   5 // Software Foundation; either version 3 of the License, or (at your option)
   6 // any later version.
   7 //
   8 // This program is distributed in the hope that it will be useful, but WITHOUT
   9 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  11 // more details.
  12 //
  13 // You should have received a copy of the GNU General Public License along with
  14 // this program; if not, write to the Free Software Foundation, Inc., 51
  15 // Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16
  17 #ifndef HASH_H
  18 #define HASH_H
  19
  20 #include "system.h"
  21
  22 struct hash;
  23
  24 // Create a new hash.
  25 struct hash *hash_init(void);
  26
  27 // Create a new hash from an existing hash state.
  28 struct hash *hash_copy(struct hash *hash);
  29
  30 // Free a hash created by hash_init or hash_copy.
  31 void hash_free(struct hash *hash);
  32
  33 // Enable debug logging of hashed input to a binary and a text file.
  34 void hash_enable_debug(
  35         struct hash *hash, const char *section_name, FILE *debug_binary,
  36         FILE *debug_text);
  37
  38 // Return how many bytes have been hashed.
  39 size_t hash_input_size(struct hash *hash);
  40
  41 // Return the hash result as a hex string. Caller frees.
  42 char *hash_result(struct hash *hash);
  43
  44 // Return the hash result as 16 binary bytes.
  45 void hash_result_as_bytes(struct hash *hash, unsigned char *out);
  46
  47 // Return whether hash1 and hash2 are equal.
  48 bool hash_equal(struct hash *hash1, struct hash *hash2);
  49
  50 // Hash some data that is unlikely to occur in the input. The idea is twofold:
  51 //
  52 // - Delimit things like arguments from each other (e.g., so that -I -O2 and
  53 //   -I-O2 hash differently).
  54 // - Tag different types of hashed information so that it's possible to do
  55 //   conditional hashing of information in a safe way (e.g., if we want to hash
  56 //   information X if CCACHE_A is set and information Y if CCACHE_B is set,
  57 //   there should never be a hash collision risk).
  58 void hash_delimiter(struct hash *hash, const char *type);
  59
  60 // Hash bytes in a buffer.
  61 //
  62 // If hash debugging is enabled, the bytes are written verbatim to the text
  63 // input file.
  64 void hash_buffer(struct hash *hash, const void *s, size_t len);
  65
  66 // Hash a string.
  67 //
  68 // If hash debugging is enabled, the string is written to the text input file
  69 // followed by a newline.
  70 void hash_string(struct hash *hash, const char *s);
  71
  72 // Hash a string with a known size.
  73 //
  74 // If hash debugging is enabled, the string is written to the text input file
  75 // followed by a newline.
  76 void hash_string_buffer(struct hash *hash, const char *s, int length);
  77
  78 // Hash an integer.
  79 //
  80 // If hash debugging is enabled, the integer is written in text form to the
  81 // text input file followed by a newline.
  82 void hash_int(struct hash *hash, int x);
  83
  84 // Add contents of an open file to the hash.
  85 //
  86 // If hash debugging is enabled, the data is written verbatim to the text input
  87 // file.
  88 //
  89 // Returns true on success, otherwise false.
  90 bool hash_fd(struct hash *hash, int fd);
  91
  92 // Add contents of a file to the hash.
  93 //
  94 // If hash debugging is enabled, the data is written verbatim to the text input
  95 // file.
  96 //
  97 // Returns true on success, otherwise false.
  98 bool hash_file(struct hash *hash, const char *fname);
  99
 100 #endif