1 | /* |
2 | * Copyright (c) 2015-2018, Intel Corporation |
3 | * |
4 | * Redistribution and use in source and binary forms, with or without |
5 | * modification, are permitted provided that the following conditions are met: |
6 | * |
7 | * * Redistributions of source code must retain the above copyright notice, |
8 | * this list of conditions and the following disclaimer. |
9 | * * Redistributions in binary form must reproduce the above copyright |
10 | * notice, this list of conditions and the following disclaimer in the |
11 | * documentation and/or other materials provided with the distribution. |
12 | * * Neither the name of Intel Corporation nor the names of its contributors |
13 | * may be used to endorse or promote products derived from this software |
14 | * without specific prior written permission. |
15 | * |
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
26 | * POSSIBILITY OF SUCH DAMAGE. |
27 | */ |
28 | |
29 | #ifndef HS_RUNTIME_H_ |
30 | #define HS_RUNTIME_H_ |
31 | |
32 | #include <stdlib.h> |
33 | |
34 | /** |
35 | * @file |
36 | * @brief The Hyperscan runtime API definition. |
37 | * |
38 | * Hyperscan is a high speed regular expression engine. |
39 | * |
40 | * This header contains functions for using compiled Hyperscan databases for |
41 | * scanning data at runtime. |
42 | */ |
43 | |
44 | #include "hs_common.h" |
45 | |
46 | #ifdef __cplusplus |
47 | extern "C" |
48 | { |
49 | #endif |
50 | |
51 | /** |
52 | * Definition of the stream identifier type. |
53 | */ |
54 | struct hs_stream; |
55 | |
56 | /** |
57 | * The stream identifier returned by @ref hs_open_stream(). |
58 | */ |
59 | typedef struct hs_stream hs_stream_t; |
60 | |
61 | struct hs_scratch; |
62 | |
63 | /** |
64 | * A Hyperscan scratch space. |
65 | */ |
66 | typedef struct hs_scratch hs_scratch_t; |
67 | |
68 | /** |
69 | * Definition of the match event callback function type. |
70 | * |
71 | * A callback function matching the defined type must be provided by the |
72 | * application calling the @ref hs_scan(), @ref hs_scan_vector() or @ref |
73 | * hs_scan_stream() functions (or other streaming calls which can produce |
74 | * matches). |
75 | * |
76 | * This callback function will be invoked whenever a match is located in the |
77 | * target data during the execution of a scan. The details of the match are |
78 | * passed in as parameters to the callback function, and the callback function |
79 | * should return a value indicating whether or not matching should continue on |
80 | * the target data. If no callbacks are desired from a scan call, NULL may be |
81 | * provided in order to suppress match production. |
82 | * |
83 | * This callback function should not attempt to call Hyperscan API functions on |
84 | * the same stream nor should it attempt to reuse the scratch space allocated |
85 | * for the API calls that caused it to be triggered. Making another call to the |
86 | * Hyperscan library with completely independent parameters should work (for |
87 | * example, scanning a different database in a new stream and with new scratch |
88 | * space), but reusing data structures like stream state and/or scratch space |
89 | * will produce undefined behavior. |
90 | * |
91 | * @param id |
92 | * The ID number of the expression that matched. If the expression was a |
93 | * single expression compiled with @ref hs_compile(), this value will be |
94 | * zero. |
95 | * |
96 | * @param from |
97 | * - If a start of match flag is enabled for the current pattern, this |
98 | * argument will be set to the start of match for the pattern assuming |
99 | * that that start of match value lies within the current 'start of match |
100 | * horizon' chosen by one of the SOM_HORIZON mode flags. |
101 | |
102 | * - If the start of match value lies outside this horizon (possible only |
103 | * when the SOM_HORIZON value is not @ref HS_MODE_SOM_HORIZON_LARGE), |
104 | * the @p from value will be set to @ref HS_OFFSET_PAST_HORIZON. |
105 | |
106 | * - This argument will be set to zero if the Start of Match flag is not |
107 | * enabled for the given pattern. |
108 | * |
109 | * @param to |
110 | * The offset after the last byte that matches the expression. |
111 | * |
112 | * @param flags |
113 | * This is provided for future use and is unused at present. |
114 | * |
115 | * @param context |
116 | * The pointer supplied by the user to the @ref hs_scan(), @ref |
117 | * hs_scan_vector() or @ref hs_scan_stream() function. |
118 | * |
119 | * @return |
120 | * Non-zero if the matching should cease, else zero. If scanning is |
121 | * performed in streaming mode and a non-zero value is returned, any |
122 | * subsequent calls to @ref hs_scan_stream() for that stream will |
123 | * immediately return with @ref HS_SCAN_TERMINATED. |
124 | */ |
125 | typedef int (HS_CDECL *match_event_handler)(unsigned int id, |
126 | unsigned long long from, |
127 | unsigned long long to, |
128 | unsigned int flags, |
129 | void *context); |
130 | |
131 | /** |
132 | * Open and initialise a stream. |
133 | * |
134 | * @param db |
135 | * A compiled pattern database. |
136 | * |
137 | * @param flags |
138 | * Flags modifying the behaviour of the stream. This parameter is provided |
139 | * for future use and is unused at present. |
140 | * |
141 | * @param stream |
142 | * On success, a pointer to the generated @ref hs_stream_t will be |
143 | * returned; NULL on failure. |
144 | * |
145 | * @return |
146 | * @ref HS_SUCCESS on success, other values on failure. |
147 | */ |
148 | hs_error_t HS_CDECL hs_open_stream(const hs_database_t *db, unsigned int flags, |
149 | hs_stream_t **stream); |
150 | |
151 | /** |
152 | * Write data to be scanned to the opened stream. |
153 | * |
154 | * This is the function call in which the actual pattern matching takes place |
155 | * as data is written to the stream. Matches will be returned via the @ref |
156 | * match_event_handler callback supplied. |
157 | * |
158 | * @param id |
159 | * The stream ID (returned by @ref hs_open_stream()) to which the data |
160 | * will be written. |
161 | * |
162 | * @param data |
163 | * Pointer to the data to be scanned. |
164 | * |
165 | * @param length |
166 | * The number of bytes to scan. |
167 | * |
168 | * @param flags |
169 | * Flags modifying the behaviour of the stream. This parameter is provided |
170 | * for future use and is unused at present. |
171 | * |
172 | * @param scratch |
173 | * A per-thread scratch space allocated by @ref hs_alloc_scratch(). |
174 | * |
175 | * @param onEvent |
176 | * Pointer to a match event callback function. If a NULL pointer is given, |
177 | * no matches will be returned. |
178 | * |
179 | * @param ctxt |
180 | * The user defined pointer which will be passed to the callback function |
181 | * when a match occurs. |
182 | * |
183 | * @return |
184 | * Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the |
185 | * match callback indicated that scanning should stop; other values on |
186 | * error. |
187 | */ |
188 | hs_error_t HS_CDECL hs_scan_stream(hs_stream_t *id, const char *data, |
189 | unsigned int length, unsigned int flags, |
190 | hs_scratch_t *scratch, |
191 | match_event_handler onEvent, void *ctxt); |
192 | |
193 | /** |
194 | * Close a stream. |
195 | * |
196 | * This function completes matching on the given stream and frees the memory |
197 | * associated with the stream state. After this call, the stream pointed to by |
198 | * @p id is invalid and can no longer be used. To reuse the stream state after |
199 | * completion, rather than closing it, the @ref hs_reset_stream function can be |
200 | * used. |
201 | * |
202 | * This function must be called for any stream created with @ref |
203 | * hs_open_stream(), even if scanning has been terminated by a non-zero return |
204 | * from the match callback function. |
205 | * |
206 | * Note: This operation may result in matches being returned (via calls to the |
207 | * match event callback) for expressions anchored to the end of the data stream |
208 | * (for example, via the use of the `$` meta-character). If these matches are |
209 | * not desired, NULL may be provided as the @ref match_event_handler callback. |
210 | * |
211 | * If NULL is provided as the @ref match_event_handler callback, it is |
212 | * permissible to provide a NULL scratch. |
213 | * |
214 | * @param id |
215 | * The stream ID returned by @ref hs_open_stream(). |
216 | * |
217 | * @param scratch |
218 | * A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is |
219 | * allowed to be NULL only if the @p onEvent callback is also NULL. |
220 | * |
221 | * @param onEvent |
222 | * Pointer to a match event callback function. If a NULL pointer is given, |
223 | * no matches will be returned. |
224 | * |
225 | * @param ctxt |
226 | * The user defined pointer which will be passed to the callback function |
227 | * when a match occurs. |
228 | * |
229 | * @return |
230 | * Returns @ref HS_SUCCESS on success, other values on failure. |
231 | */ |
232 | hs_error_t HS_CDECL hs_close_stream(hs_stream_t *id, hs_scratch_t *scratch, |
233 | match_event_handler onEvent, void *ctxt); |
234 | |
235 | /** |
236 | * Reset a stream to an initial state. |
237 | * |
238 | * Conceptually, this is equivalent to performing @ref hs_close_stream() on the |
239 | * given stream, followed by a @ref hs_open_stream(). This new stream replaces |
240 | * the original stream in memory, avoiding the overhead of freeing the old |
241 | * stream and allocating the new one. |
242 | * |
243 | * Note: This operation may result in matches being returned (via calls to the |
244 | * match event callback) for expressions anchored to the end of the original |
245 | * data stream (for example, via the use of the `$` meta-character). If these |
246 | * matches are not desired, NULL may be provided as the @ref match_event_handler |
247 | * callback. |
248 | * |
249 | * Note: the stream will also be tied to the same database. |
250 | * |
251 | * @param id |
252 | * The stream (as created by @ref hs_open_stream()) to be replaced. |
253 | * |
254 | * @param flags |
255 | * Flags modifying the behaviour of the stream. This parameter is provided |
256 | * for future use and is unused at present. |
257 | * |
258 | * @param scratch |
259 | * A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is |
260 | * allowed to be NULL only if the @p onEvent callback is also NULL. |
261 | * |
262 | * @param onEvent |
263 | * Pointer to a match event callback function. If a NULL pointer is given, |
264 | * no matches will be returned. |
265 | * |
266 | * @param context |
267 | * The user defined pointer which will be passed to the callback function |
268 | * when a match occurs. |
269 | * |
270 | * @return |
271 | * @ref HS_SUCCESS on success, other values on failure. |
272 | */ |
273 | hs_error_t HS_CDECL hs_reset_stream(hs_stream_t *id, unsigned int flags, |
274 | hs_scratch_t *scratch, |
275 | match_event_handler onEvent, void *context); |
276 | |
277 | /** |
278 | * Duplicate the given stream. The new stream will have the same state as the |
279 | * original including the current stream offset. |
280 | * |
281 | * @param to_id |
282 | * On success, a pointer to the new, copied @ref hs_stream_t will be |
283 | * returned; NULL on failure. |
284 | * |
285 | * @param from_id |
286 | * The stream (as created by @ref hs_open_stream()) to be copied. |
287 | * |
288 | * @return |
289 | * @ref HS_SUCCESS on success, other values on failure. |
290 | */ |
291 | hs_error_t HS_CDECL hs_copy_stream(hs_stream_t **to_id, |
292 | const hs_stream_t *from_id); |
293 | |
294 | /** |
295 | * Duplicate the given 'from' stream state onto the 'to' stream. The 'to' stream |
296 | * will first be reset (reporting any EOD matches if a non-NULL @p onEvent |
297 | * callback handler is provided). |
298 | * |
299 | * Note: the 'to' stream and the 'from' stream must be open against the same |
300 | * database. |
301 | * |
302 | * @param to_id |
303 | * On success, a pointer to the new, copied @ref hs_stream_t will be |
304 | * returned; NULL on failure. |
305 | * |
306 | * @param from_id |
307 | * The stream (as created by @ref hs_open_stream()) to be copied. |
308 | * |
309 | * @param scratch |
310 | * A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is |
311 | * allowed to be NULL only if the @p onEvent callback is also NULL. |
312 | * |
313 | * @param onEvent |
314 | * Pointer to a match event callback function. If a NULL pointer is given, |
315 | * no matches will be returned. |
316 | * |
317 | * @param context |
318 | * The user defined pointer which will be passed to the callback function |
319 | * when a match occurs. |
320 | * |
321 | * @return |
322 | * @ref HS_SUCCESS on success, other values on failure. |
323 | */ |
324 | hs_error_t HS_CDECL hs_reset_and_copy_stream(hs_stream_t *to_id, |
325 | const hs_stream_t *from_id, |
326 | hs_scratch_t *scratch, |
327 | match_event_handler onEvent, |
328 | void *context); |
329 | |
330 | /** |
331 | * Creates a compressed representation of the provided stream in the buffer |
332 | * provided. This compressed representation can be converted back into a stream |
333 | * state by using @ref hs_expand_stream() or @ref hs_reset_and_expand_stream(). |
334 | * The size of the compressed representation will be placed into @p used_space. |
335 | * |
336 | * If there is not sufficient space in the buffer to hold the compressed |
337 | * representation, @ref HS_INSUFFICIENT_SPACE will be returned and @p used_space |
338 | * will be populated with the amount of space required. |
339 | * |
340 | * Note: this function does not close the provided stream, you may continue to |
341 | * use the stream or to free it with @ref hs_close_stream(). |
342 | * |
343 | * @param stream |
344 | * The stream (as created by @ref hs_open_stream()) to be compressed. |
345 | * |
346 | * @param buf |
347 | * Buffer to write the compressed representation into. Note: if the call is |
348 | * just being used to determine the amount of space required, it is allowed |
349 | * to pass NULL here and @p buf_space as 0. |
350 | * |
351 | * @param buf_space |
352 | * The number of bytes in @p buf. If buf_space is too small, the call will |
353 | * fail with @ref HS_INSUFFICIENT_SPACE. |
354 | * |
355 | * @param used_space |
356 | * Pointer to where the amount of used space will be written to. The used |
357 | * buffer space is always less than or equal to @p buf_space. If the call |
358 | * fails with @ref HS_INSUFFICIENT_SPACE, this pointer will be used to |
359 | * write out the amount of buffer space required. |
360 | * |
361 | * @return |
362 | * @ref HS_SUCCESS on success, @ref HS_INSUFFICIENT_SPACE if the provided |
363 | * buffer is too small. |
364 | */ |
365 | hs_error_t HS_CDECL hs_compress_stream(const hs_stream_t *stream, char *buf, |
366 | size_t buf_space, size_t *used_space); |
367 | |
368 | /** |
369 | * Decompresses a compressed representation created by @ref hs_compress_stream() |
370 | * into a new stream. |
371 | * |
372 | * Note: @p buf must correspond to a complete compressed representation created |
373 | * by @ref hs_compress_stream() of a stream that was opened against @p db. It is |
374 | * not always possible to detect misuse of this API and behaviour is undefined |
375 | * if these properties are not satisfied. |
376 | * |
377 | * @param db |
378 | * The compiled pattern database that the compressed stream was opened |
379 | * against. |
380 | * |
381 | * @param stream |
382 | * On success, a pointer to the expanded @ref hs_stream_t will be |
383 | * returned; NULL on failure. |
384 | * |
385 | * @param buf |
386 | * A compressed representation of a stream. These compressed forms are |
387 | * created by @ref hs_compress_stream(). |
388 | * |
389 | * @param buf_size |
390 | * The size in bytes of the compressed representation. |
391 | * |
392 | * @return |
393 | * @ref HS_SUCCESS on success, other values on failure. |
394 | */ |
395 | hs_error_t HS_CDECL hs_expand_stream(const hs_database_t *db, |
396 | hs_stream_t **stream, const char *buf, |
397 | size_t buf_size); |
398 | |
399 | /** |
400 | * Decompresses a compressed representation created by @ref hs_compress_stream() |
401 | * on top of the 'to' stream. The 'to' stream will first be reset (reporting |
402 | * any EOD matches if a non-NULL @p onEvent callback handler is provided). |
403 | * |
404 | * Note: the 'to' stream must be opened against the same database as the |
405 | * compressed stream. |
406 | * |
407 | * Note: @p buf must correspond to a complete compressed representation created |
408 | * by @ref hs_compress_stream() of a stream that was opened against @p db. It is |
409 | * not always possible to detect misuse of this API and behaviour is undefined |
410 | * if these properties are not satisfied. |
411 | * |
412 | * @param to_stream |
413 | * A pointer to a valid stream state. A pointer to the expanded @ref |
414 | * hs_stream_t will be returned; NULL on failure. |
415 | * |
416 | * @param buf |
417 | * A compressed representation of a stream. These compressed forms are |
418 | * created by @ref hs_compress_stream(). |
419 | * |
420 | * @param buf_size |
421 | * The size in bytes of the compressed representation. |
422 | * |
423 | * @param scratch |
424 | * A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is |
425 | * allowed to be NULL only if the @p onEvent callback is also NULL. |
426 | * |
427 | * @param onEvent |
428 | * Pointer to a match event callback function. If a NULL pointer is given, |
429 | * no matches will be returned. |
430 | * |
431 | * @param context |
432 | * The user defined pointer which will be passed to the callback function |
433 | * when a match occurs. |
434 | * |
435 | * @return |
436 | * @ref HS_SUCCESS on success, other values on failure. |
437 | */ |
438 | hs_error_t HS_CDECL hs_reset_and_expand_stream(hs_stream_t *to_stream, |
439 | const char *buf, size_t buf_size, |
440 | hs_scratch_t *scratch, |
441 | match_event_handler onEvent, |
442 | void *context); |
443 | |
444 | /** |
445 | * The block (non-streaming) regular expression scanner. |
446 | * |
447 | * This is the function call in which the actual pattern matching takes place |
448 | * for block-mode pattern databases. |
449 | * |
450 | * @param db |
451 | * A compiled pattern database. |
452 | * |
453 | * @param data |
454 | * Pointer to the data to be scanned. |
455 | * |
456 | * @param length |
457 | * The number of bytes to scan. |
458 | * |
459 | * @param flags |
460 | * Flags modifying the behaviour of this function. This parameter is |
461 | * provided for future use and is unused at present. |
462 | * |
463 | * @param scratch |
464 | * A per-thread scratch space allocated by @ref hs_alloc_scratch() for this |
465 | * database. |
466 | * |
467 | * @param onEvent |
468 | * Pointer to a match event callback function. If a NULL pointer is given, |
469 | * no matches will be returned. |
470 | * |
471 | * @param context |
472 | * The user defined pointer which will be passed to the callback function. |
473 | * |
474 | * @return |
475 | * Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the |
476 | * match callback indicated that scanning should stop; other values on |
477 | * error. |
478 | */ |
479 | hs_error_t HS_CDECL hs_scan(const hs_database_t *db, const char *data, |
480 | unsigned int length, unsigned int flags, |
481 | hs_scratch_t *scratch, match_event_handler onEvent, |
482 | void *context); |
483 | |
484 | /** |
485 | * The vectored regular expression scanner. |
486 | * |
487 | * This is the function call in which the actual pattern matching takes place |
488 | * for vectoring-mode pattern databases. |
489 | * |
490 | * @param db |
491 | * A compiled pattern database. |
492 | * |
493 | * @param data |
494 | * An array of pointers to the data blocks to be scanned. |
495 | * |
496 | * @param length |
497 | * An array of lengths (in bytes) of each data block to scan. |
498 | * |
499 | * @param count |
500 | * Number of data blocks to scan. This should correspond to the size of |
501 | * of the @p data and @p length arrays. |
502 | * |
503 | * @param flags |
504 | * Flags modifying the behaviour of this function. This parameter is |
505 | * provided for future use and is unused at present. |
506 | * |
507 | * @param scratch |
508 | * A per-thread scratch space allocated by @ref hs_alloc_scratch() for |
509 | * this database. |
510 | * |
511 | * @param onEvent |
512 | * Pointer to a match event callback function. If a NULL pointer is given, |
513 | * no matches will be returned. |
514 | * |
515 | * @param context |
516 | * The user defined pointer which will be passed to the callback function. |
517 | * |
518 | * @return |
519 | * Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the match |
520 | * callback indicated that scanning should stop; other values on error. |
521 | */ |
522 | hs_error_t HS_CDECL hs_scan_vector(const hs_database_t *db, |
523 | const char *const *data, |
524 | const unsigned int *length, |
525 | unsigned int count, unsigned int flags, |
526 | hs_scratch_t *scratch, |
527 | match_event_handler onEvent, void *context); |
528 | |
529 | /** |
530 | * Allocate a "scratch" space for use by Hyperscan. |
531 | * |
532 | * This is required for runtime use, and one scratch space per thread, or |
533 | * concurrent caller, is required. Any allocator callback set by @ref |
534 | * hs_set_scratch_allocator() or @ref hs_set_allocator() will be used by this |
535 | * function. |
536 | * |
537 | * @param db |
538 | * The database, as produced by @ref hs_compile(). |
539 | * |
540 | * @param scratch |
541 | * On first allocation, a pointer to NULL should be provided so a new |
542 | * scratch can be allocated. If a scratch block has been previously |
543 | * allocated, then a pointer to it should be passed back in to see if it |
544 | * is valid for this database block. If a new scratch block is required, |
545 | * the original will be freed and the new one returned, otherwise the |
546 | * previous scratch block will be returned. On success, the scratch block |
547 | * will be suitable for use with the provided database in addition to any |
548 | * databases that original scratch space was suitable for. |
549 | * |
550 | * @return |
551 | * @ref HS_SUCCESS on successful allocation; @ref HS_NOMEM if the |
552 | * allocation fails. Other errors may be returned if invalid parameters |
553 | * are specified. |
554 | */ |
555 | hs_error_t HS_CDECL hs_alloc_scratch(const hs_database_t *db, |
556 | hs_scratch_t **scratch); |
557 | |
558 | /** |
559 | * Allocate a scratch space that is a clone of an existing scratch space. |
560 | * |
561 | * This is useful when multiple concurrent threads will be using the same set |
562 | * of compiled databases, and another scratch space is required. Any allocator |
563 | * callback set by @ref hs_set_scratch_allocator() or @ref hs_set_allocator() |
564 | * will be used by this function. |
565 | * |
566 | * @param src |
567 | * The existing @ref hs_scratch_t to be cloned. |
568 | * |
569 | * @param dest |
570 | * A pointer to the new scratch space will be returned here. |
571 | * |
572 | * @return |
573 | * @ref HS_SUCCESS on success; @ref HS_NOMEM if the allocation fails. |
574 | * Other errors may be returned if invalid parameters are specified. |
575 | */ |
576 | hs_error_t HS_CDECL hs_clone_scratch(const hs_scratch_t *src, |
577 | hs_scratch_t **dest); |
578 | |
579 | /** |
580 | * Provides the size of the given scratch space. |
581 | * |
582 | * @param scratch |
583 | * A per-thread scratch space allocated by @ref hs_alloc_scratch() or @ref |
584 | * hs_clone_scratch(). |
585 | * |
586 | * @param scratch_size |
587 | * On success, the size of the scratch space in bytes is placed in this |
588 | * parameter. |
589 | * |
590 | * @return |
591 | * @ref HS_SUCCESS on success, other values on failure. |
592 | */ |
593 | hs_error_t HS_CDECL hs_scratch_size(const hs_scratch_t *scratch, |
594 | size_t *scratch_size); |
595 | |
596 | /** |
597 | * Free a scratch block previously allocated by @ref hs_alloc_scratch() or @ref |
598 | * hs_clone_scratch(). |
599 | * |
600 | * The free callback set by @ref hs_set_scratch_allocator() or @ref |
601 | * hs_set_allocator() will be used by this function. |
602 | * |
603 | * @param scratch |
604 | * The scratch block to be freed. NULL may also be safely provided. |
605 | * |
606 | * @return |
607 | * @ref HS_SUCCESS on success, other values on failure. |
608 | */ |
609 | hs_error_t HS_CDECL hs_free_scratch(hs_scratch_t *scratch); |
610 | |
611 | /** |
612 | * Callback 'from' return value, indicating that the start of this match was |
613 | * too early to be tracked with the requested SOM_HORIZON precision. |
614 | */ |
615 | #define HS_OFFSET_PAST_HORIZON (~0ULL) |
616 | |
617 | #ifdef __cplusplus |
618 | } /* extern "C" */ |
619 | #endif |
620 | |
621 | #endif /* HS_RUNTIME_H_ */ |
622 | |