mem.h (13362B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUAC_PRIVATE_MEM_H 21#define GUAC_PRIVATE_MEM_H 22 23/** 24 * Provides functions used internally for allocating memory. 25 * 26 * WARNING: SYMBOLS DEFINED HERE ARE NOT INTENDED TO BE USED DIRECTLY BY 27 * ANYTHING OUTSIDE LIBGUAC! This header is used internally to define private 28 * symbols that are only intended for indirect public use through some other, 29 * non-private mechanism, such as a macro defined in the public API. 30 * 31 * @file mem.h 32 */ 33 34#include <stddef.h> 35 36/** 37 * Allocates a contiguous block of memory with the specified size, returning a 38 * pointer to the first byte of that block of memory. If multiple sizes are 39 * provided, these sizes are multiplied together to produce the final size of 40 * the new block. If memory of the specified size cannot be allocated, or if 41 * multiplying the sizes would result in integer overflow, guac_error is set 42 * appropriately and NULL is returned. 43 * 44 * This function is analogous to the standard malloc(), but accepts a list of 45 * size factors instead of a single integer size. 46 * 47 * The pointer returned by PRIV_guac_mem_alloc() SHOULD be freed with a 48 * subsequent call to guac_mem_free() or PRIV_guac_mem_free(), but MAY instead 49 * be freed with a subsequent call to free(). 50 * 51 * @param factor_count 52 * The number of factors to multiply together to produce the desired block 53 * size. 54 * 55 * @param factors 56 * An array of one or more size_t values that should be multiplied together 57 * to produce the desired block size. At least one value MUST be provided. 58 * 59 * @returns 60 * A pointer to the first byte of the allocated block of memory, or NULL if 61 * such a block could not be allocated. If a block of memory could not be 62 * allocated, guac_error is set appropriately. 63 */ 64void* PRIV_guac_mem_alloc(size_t factor_count, const size_t* factors); 65 66/** 67 * Allocates a contiguous block of memory with the specified size and with all 68 * bytes initialized to zero, returning a pointer to the first byte of that 69 * block of memory. If multiple sizes are provided, these sizes are multiplied 70 * together to produce the final size of the new block. If memory of the 71 * specified size cannot be allocated, or if multiplying the sizes would result 72 * in integer overflow, guac_error is set appropriately and NULL is returned. 73 * 74 * This function is analogous to the standard calloc(), but accepts a list of 75 * size factors instead of a requiring exactly two integer sizes. 76 * 77 * The pointer returned by PRIV_guac_mem_zalloc() SHOULD be freed with a 78 * subsequent call to guac_mem_free() or PRIV_guac_mem_free(), but MAY instead 79 * be freed with a subsequent call to free(). 80 * 81 * @param factor_count 82 * The number of factors to multiply together to produce the desired block 83 * size. 84 * 85 * @param factors 86 * An array of one or more size_t values that should be multiplied together 87 * to produce the desired block size. At least one value MUST be provided. 88 * 89 * @returns 90 * A pointer to the first byte of the allocated block of memory, or NULL if 91 * such a block could not be allocated. If a block of memory could not be 92 * allocated, guac_error is set appropriately. 93 */ 94void* PRIV_guac_mem_zalloc(size_t factor_count, const size_t* factors); 95 96/** 97 * Multiplies together each of the given values, storing the result in a size_t 98 * variable via the provided pointer. If the result of the multiplication 99 * overflows the limits of a size_t, non-zero is returned to signal failure. 100 * 101 * If the multiplication operation fails, the nature of any result stored in 102 * the provided pointer is undefined, as is whether a result is stored at all. 103 * 104 * @param result 105 * A pointer to the size_t variable that should receive the result of 106 * multiplying the given values. 107 * 108 * @param factor_count 109 * The number of factors to multiply together. 110 * 111 * @param factors 112 * An array of one or more size_t values that should be multiplied 113 * together. At least one value MUST be provided. 114 * 115 * @returns 116 * Zero if the multiplication was successful and did not overflow the 117 * limits of a size_t, non-zero otherwise. 118 */ 119int PRIV_guac_mem_ckd_mul(size_t* result, size_t factor_count, const size_t* factors); 120 121/** 122 * Adds together each of the given values, storing the result in a size_t 123 * variable via the provided pointer. If the result of the addition overflows 124 * the limits of a size_t, non-zero is returned to signal failure. 125 * 126 * If the addition operation fails, the nature of any result stored in the 127 * provided pointer is undefined, as is whether a result is stored at all. 128 * 129 * @param result 130 * A pointer to the size_t variable that should receive the result of 131 * adding the given values. 132 * 133 * @param term_count 134 * The number of terms to be added together. 135 * 136 * @param terms 137 * An array of one or more size_t values that should be added together. At 138 * least one value MUST be provided. 139 * 140 * @returns 141 * Zero if the addition was successful and did not overflow the limits of a 142 * size_t, non-zero otherwise. 143 */ 144int PRIV_guac_mem_ckd_add(size_t* result, size_t term_count, const size_t* terms); 145 146/** 147 * Subtracts each of the given values from each other, storing the result in a 148 * size_t variable via the provided pointer. If the result of the subtraction 149 * overflows the limits of a size_t (goes below zero), non-zero is returned to 150 * signal failure. 151 * 152 * If the subtraction operation fails, the nature of any result stored in the 153 * provided pointer is undefined, as is whether a result is stored at all. 154 * 155 * @param result 156 * A pointer to the size_t variable that should receive the result of 157 * subtracting the given values from each other. 158 * 159 * @param term_count 160 * The number of terms to be subtracted from each other. 161 * 162 * @param terms 163 * An array of one or more size_t values that should be subtracted from 164 * each other. At least one value MUST be provided. 165 * 166 * @returns 167 * Zero if the subtraction was successful and did not overflow the limits 168 * of a size_t (did not go below zero), non-zero otherwise. 169 */ 170int PRIV_guac_mem_ckd_sub(size_t* result, size_t term_count, const size_t* terms); 171 172/** 173 * Multiplies together each of the given values, returning the result directly. 174 * If the result of the multiplication overflows the limits of a size_t, 175 * execution of the current process is aborted entirely, and this function does 176 * not return. 177 * 178 * @param factor_count 179 * The number of factors to multiply together. 180 * 181 * @param factors 182 * An array of one or more size_t values that should be multiplied 183 * together. At least one value MUST be provided. 184 * 185 * @returns 186 * The result of the multiplication. If the multiplication operation would 187 * overflow the limits of a size_t, execution of the current process is 188 * aborted, and this function does not return. 189 */ 190size_t PRIV_guac_mem_ckd_mul_or_die(size_t factor_count, const size_t* factors); 191 192/** 193 * Adds together each of the given values, returning the result directly. If 194 * the result of the addition overflows the limits of a size_t, execution of 195 * the current process is aborted entirely, and this function does not return. 196 * 197 * @param term_count 198 * The number of terms to be added together. 199 * 200 * @param terms 201 * An array of one or more size_t values that should be added together. At 202 * least one value MUST be provided. 203 * 204 * @returns 205 * The result of the addition. If the addition operation would overflow the 206 * limits of a size_t, execution of the current process is aborted, and 207 * this function does not return. 208 */ 209size_t PRIV_guac_mem_ckd_add_or_die(size_t term_count, const size_t* terms); 210 211/** 212 * Subtracts each of the given values from each other, returning the result 213 * directly. If the result of the subtraction overflows the limits of a size_t 214 * (goes below zero), execution of the current process is aborted entirely, and 215 * this function does not return. 216 * 217 * @param term_count 218 * The number of terms to be subtracted from each other. 219 * 220 * @param terms 221 * An array of one or more size_t values that should be subtracted from 222 * each other. At least one value MUST be provided. 223 * 224 * @returns 225 * The result of the subtraction. If the subtraction operation would 226 * overflow the limits of a size_t (go below zero), execution of the 227 * current process is aborted, and this function does not return. 228 */ 229size_t PRIV_guac_mem_ckd_sub_or_die(size_t term_count, const size_t* terms); 230 231/** 232 * Reallocates a contiguous block of memory that was previously allocated with 233 * guac_mem_alloc(), guac_mem_zalloc(), guac_mem_realloc(), or one of their 234 * PRIV_guac_*() or *_or_die() variants, returning a pointer to the first byte 235 * of that reallocated block of memory. If multiple sizes are provided, these 236 * sizes are multiplied together to produce the final size of the new block. If 237 * memory of the specified size cannot be allocated, or if multiplying the 238 * sizes would result in integer overflow, guac_error is set appropriately, the 239 * original block of memory is left untouched, and NULL is returned. 240 * 241 * This function is analogous to the standard realloc(), but accepts a list of 242 * size factors instead of a requiring exactly one integer size. 243 * 244 * The returned pointer may be the same as the original pointer, but this is 245 * not guaranteed. If the returned pointer is different, the original pointer 246 * is automatically freed. 247 * 248 * The pointer returned by guac_mem_realloc() SHOULD be freed with a subsequent 249 * call to guac_mem_free() or PRIV_guac_mem_free(), but MAY instead be freed 250 * with a subsequent call to free(). 251 * 252 * @param factor_count 253 * The number of factors to multiply together to produce the desired block 254 * size. 255 * 256 * @param factors 257 * An array of one or more size_t values that should be multiplied together 258 * to produce the desired block size. At least one value MUST be provided. 259 * 260 * @returns 261 * A pointer to the first byte of the reallocated block of memory, or NULL 262 * if such a block could not be allocated. If a block of memory could not 263 * be allocated, guac_error is set appropriately and the original block of 264 * memory is left untouched. 265 */ 266void* PRIV_guac_mem_realloc(void* mem, size_t factor_count, const size_t* factors); 267 268/** 269 * Reallocates a contiguous block of memory that was previously allocated with 270 * guac_mem_alloc(), guac_mem_zalloc(), guac_mem_realloc(), or one of their 271 * PRIV_guac_*() or *_or_die() variants, returning a pointer to the first byte 272 * of that reallocated block of memory. If multiple sizes are provided, these 273 * sizes are multiplied together to produce the final size of the new block. If 274 * memory of the specified size cannot be allocated, or if multiplying the 275 * sizes would result in integer overflow, execution of the current process is 276 * aborted entirely, and this function does not return. 277 * 278 * This function is analogous to the standard realloc(), but accepts a list of 279 * size factors instead of a requiring exactly one integer size and does not 280 * return in the event a block cannot be allocated. 281 * 282 * The returned pointer may be the same as the original pointer, but this is 283 * not guaranteed. If the returned pointer is different, the original pointer 284 * is automatically freed. 285 * 286 * The pointer returned by guac_mem_realloc() SHOULD be freed with a subsequent 287 * call to guac_mem_free() or PRIV_guac_mem_free(), but MAY instead be freed 288 * with a subsequent call to free(). 289 * 290 * @param factor_count 291 * The number of factors to multiply together to produce the desired block 292 * size. 293 * 294 * @param factors 295 * An array of one or more size_t values that should be multiplied together 296 * to produce the desired block size. At least one value MUST be provided. 297 * 298 * @returns 299 * A pointer to the first byte of the reallocated block of memory. If a 300 * block of memory could not be allocated, execution of the current process 301 * is aborted, and this function does not return. 302 */ 303void* PRIV_guac_mem_realloc_or_die(void* mem, size_t factor_count, const size_t* factors); 304 305/** 306 * Frees the memory block at the given pointer, which MUST have been allocated 307 * with guac_mem_alloc(), guac_mem_zalloc(), guac_mem_realloc(), or one of 308 * their PRIV_guac_*() or *_or_die() variants. If the provided pointer is NULL, 309 * this function has no effect. 310 * 311 * @param mem 312 * A pointer to the memory to be freed. 313 */ 314void PRIV_guac_mem_free(void* mem); 315 316#endif 317