Code Coverage: vinyl-cache/include/vapi/vsl.h
 
82217aa4fc7094b3610340078afaf78cd95a8ec9
 
0
/*-
1
 * Copyright (c) 2006 Verdens Gang AS
2
 * Copyright (c) 2006-2015 Varnish Software AS
3
 * All rights reserved.
4
 *
5
 * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
6
 * Author: Martin Blix Grydeland <martin@varnish-software.com>
7
 *
8
 * SPDX-License-Identifier: BSD-2-Clause
9
 *
10
 * Redistribution and use in source and binary forms, with or without
11
 * modification, are permitted provided that the following conditions
12
 * are met:
13
 * 1. Redistributions of source code must retain the above copyright
14
 *    notice, this list of conditions and the following disclaimer.
15
 * 2. Redistributions in binary form must reproduce the above copyright
16
 *    notice, this list of conditions and the following disclaimer in the
17
 *    documentation and/or other materials provided with the distribution.
18
 *
19
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
20
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22
 * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
23
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29
 * SUCH DAMAGE.
30
 *
31
 * This is the public API for the VSL access.
32
 *
33
 */
34
35
#ifndef VAPI_VSL_H_INCLUDED
36
#define VAPI_VSL_H_INCLUDED
37
38
#include <stdint.h>
39
40
#include "vapi/vsl_int.h"
41
42
struct vsm;
43
44
/*
45
 * enum VSL_tag_e enumerates the SHM log tags, where the identifiers are
46
 * "SLT_" + XML tag, as defined in tbl/vsl_tags.h. Use the macro SLT__MAX
47
 * for the highest possible value of the enum.
48
 * (VSL_tag_e and SLT__MAX included from vsl_int.h)
49
 */
50
51
struct VSL_data;
52
struct VSLQ;
53
54
struct VSLC_ptr {
55
        const uint32_t          *ptr; /* Record pointer */
56
        unsigned                priv;
57
};
58
        /*
59
         * Use these macros to access fields of a VSLC_ptr record
60
         * (included from vsl_int.h):
61
         *
62
         * VSL_TAG(ptr)
63
         *   SLT tag (enum VSL_tag_e)
64
         *
65
         * VSL_ID(ptr)
66
         *   VXID
67
         *
68
         * VSL_CDATA(ptr)
69
         *   Payload (as const char *)
70
         *
71
         * VSL_LEN(ptr)
72
         *   Length of the payload in bytes
73
         *
74
         * VSL_CLIENT(ptr)
75
         *   Non-zero if this is a client transaction
76
         *
77
         * VSL_BACKEND(ptr)
78
         *   Non-zero if this is a backend transaction
79
         */
80
81
struct VSL_cursor {
82
        /* The record this cursor points to */
83
        struct VSLC_ptr         rec;
84
85
        /* Private data */
86
        const void              *priv_tbl;
87
        void                    *priv_data;
88
};
89
90
enum VSL_transaction_e {
91
        VSL_t_unknown,
92
        VSL_t_sess,
93
        VSL_t_req,
94
        VSL_t_bereq,
95
        VSL_t_raw,
96
        VSL_t__MAX,
97
};
98
99
enum VSL_reason_e {
100
        VSL_r_unknown,
101
        VSL_r_http_1,
102
        VSL_r_rxreq,
103
        VSL_r_esi,
104
        VSL_r_restart,
105
        VSL_r_pass,
106
        VSL_r_fetch,
107
        VSL_r_bgfetch,
108
        VSL_r_pipe,
109
        VSL_r__MAX,
110
};
111
112
struct VSL_transaction {
113
        int                     level;
114
        int64_t                 vxid;
115
        int64_t                 vxid_parent;
116
        enum VSL_transaction_e  type;
117
        enum VSL_reason_e       reason;
118
        struct VSL_cursor       *c;
119
};
120
121
enum VSL_grouping_e {
122
        VSL_g_raw,
123
        VSL_g_vxid,
124
        VSL_g_request,
125
        VSL_g_session,
126
        VSL_g__MAX,
127
};
128
129
typedef int VSLQ_dispatch_f(struct VSL_data *vsl,
130
    struct VSL_transaction * const trans[], void *priv);
131
        /*
132
         * The callback function type for use with VSLQ_Dispatch.
133
         *
134
         * Arguments:
135
         *      vsl: The VSL_data context
136
         *  trans[]: A NULL terminated array of pointers to VSL_transaction.
137
         *     priv: The priv argument from VSL_Dispatch
138
         *
139
         * Return value:
140
         *     0: OK - continue
141
         *   !=0: Makes VSLQ_Dispatch return with this return value immediatly
142
         *
143
         * Return values of the callback function should be distinct from the
144
         * values of enum vsl_status except for 0
145
         */
146
147
typedef void VSL_tagfind_f(int tag, void *priv);
148
        /*
149
         * The callback function type for use with VSL_Glob2Tags and
150
         * VSL_List2Tags..
151
         *
152
         * Arguments:
153
         *    tag: Tag number (= enum VSL_tag_e)
154
         *   priv: The priv argument
155
         */
156
157
extern const char * const VSL_tags[SLT__MAX];
158
        /*
159
         * Tag to string array.  Contains NULL for invalid tags.
160
         */
161
162
extern const unsigned VSL_tagflags[SLT__MAX];
163
        /*
164
         * Tag flags array.
165
         * Use these macros with VSL_tagflags (included from vsl_int.h):
166
         *
167
         * VSL_tagflags[tag] & SLT_F_BINARY
168
         *   Non-zero if the payload is binary data
169
         *
170
         * VSL_tagflags[tag] & SLT_F_UNSAFE
171
         *   Non-zero if the payload with this tag may include
172
         *   non-printable characters
173
         *
174
         * VSL_tagflags[tag] & SLT_F_UNUSED
175
         *   Non-zero if this tag is reserved for future use
176
         */
177
178
int VSL_Name2Tag(const char *name, int l);
179
        /*
180
         * Convert string to tag number (= enum VSL_tag_e). Name can be a
181
         * substring from the beginning of a tag when that substring is
182
         * unique. Matching is case-insensitive.
183
         *
184
         * Arguments:
185
         *    name:     A tag name (or substring) to match against
186
         *       l:     The length of name, or -1 to use strlen.
187
         *
188
         * Return values:
189
         *      >=0:    Tag number
190
         *      -1:     No tag matches
191
         *      -2:     Multiple tags match substring
192
         */
193
194
int VSL_Glob2Tags(const char *glob, int l, VSL_tagfind_f *func, void *priv);
195
        /*
196
         * Convert a string to multiple tag matches. The string can have
197
         * either a prefix or postfix wildcard (*) character. For each
198
         * matching tag func is called. Matching is done case-insensitive.
199
         *
200
         * Arguments:
201
         *   glob: The string to match
202
         *      l: The length of glob. -1 to use strlen.
203
         *   func: The function to call (can be NULL)
204
         *   priv: An argument that will be passed to func.
205
         *
206
         * Return values:
207
         *     >0: Number of times func was called for matching tags.
208
         *     -1: No tag matches
209
         *     -2: Multiple tags match non-glob input
210
         *     -3: Syntax error
211
         */
212
213
int VSL_List2Tags(const char *list, int l, VSL_tagfind_f *func, void *priv);
214
        /*
215
         * Convert a comma-separated list of tag globs to tag
216
         * matches. Calls VSL_Glob2Tags for each comma-separated part of
217
         * list.
218
         *
219
         * Arguments:
220
         *   list: The list of globs
221
         *      l: The length of list. -1 to use strlen
222
         *   func: The function to call (can be NULL)
223
         *   priv: An argument that will be passed to func.
224
         *
225
         * Return values:
226
         *     >0: Number of times func was called for matching tags.
227
         *     -1: No tag matches for list element
228
         *     -2: Multiple tags match non-glob list element
229
         *     -3: Syntax error
230
         */
231
232
extern const char *const VSLQ_grouping[VSL_g__MAX];
233
        /*
234
         * Grouping mode to string array.
235
         */
236
237
int VSLQ_Name2Grouping(const char *name, int l);
238
        /*
239
         * Convert string to grouping (= enum VSL_grouping_e)
240
         *
241
         * Return values:
242
         *      >=0:    Grouping value
243
         *      -1:     No grouping type matches
244
         *      -2:     Multiple grouping types match substring
245
         */
246
247
248
struct VSL_data *VSL_New(void);
249
int VSL_Arg(struct VSL_data *vsl, int opt, const char *arg);
250
        /*
251
         * Handle standard log-presenter arguments
252
         * Return:
253
         *      -1 error, VSL_Error() returns diagnostic string
254
         *       0 not handled
255
         *       1 Handled.
256
         */
257
258
void VSL_Delete(struct VSL_data *vsl);
259
        /*
260
         * Delete a VSL context, freeing up the resources
261
         */
262
263
const char *VSL_Error(const struct VSL_data *vsl);
264
        /*
265
         * Return the latest error message.
266
         */
267
268
void VSL_ResetError(struct VSL_data *vsl);
269
        /*
270
         * Reset any error message.
271
         */
272
273 28819
#define VSL_COPT_TAIL           (1 << 0)
274 80559
#define VSL_COPT_BATCH          (1 << 1)
275 47217
#define VSL_COPT_TAILSTOP       (1 << 2)
276
struct VSL_cursor *VSL_CursorVSM(struct VSL_data *vsl, struct vsm *vsm,
277
    unsigned options);
278
       /*
279
        * Set the cursor pointed to by cursor up as a raw cursor in the
280
        * log. Cursor points at the current log head.
281
        *
282
        * Options:
283
        *   VSL_COPT_TAIL       Start cursor at log tail
284
        *   VSL_COPT_BATCH      Return batch records
285
        *   VSL_COPT_TAILSTOP   Return EOF when reaching the log tail
286
        *
287
        * Return values:
288
        * non-NULL: Pointer to cursor
289
        *     NULL: Error, see VSL_Error
290
        */
291
292
struct VSL_cursor *VSL_CursorFile(struct VSL_data *vsl, const char *name,
293
    unsigned options);
294
        /*
295
         * Create a cursor pointing to the beginning of the binary VSL log
296
         * in file name. If name is '-' reads from stdin.
297
         *
298
         * Options:
299
         *   NONE
300
         *
301
         * Return values:
302
         * non-NULL: Pointer to cursor
303
         *     NULL: Error, see VSL_Error
304
         */
305
306
void VSL_DeleteCursor(const struct VSL_cursor *c);
307
        /*
308
         * Delete the cursor pointed to by c
309
         */
310
311
enum vsl_status
312
VSL_ResetCursor(const struct VSL_cursor *c);
313
        /*
314
         * Reset the cursor position to the head, so that the next call to
315
         * VSL_Next returns the first record. For VSM cursor, it will
316
         * point close to the head of the log, but at least 2 segments away
317
         * from the tail.
318
         *
319
         * Return values:
320
         * - vsl_end == success
321
         * - and see enum vsl_status
322
         *
323
         */
324
325
enum vsl_check {
326
        vsl_check_e_notsupp     = -1,
327
        vsl_check_e_inval       =  0,
328
        vsl_check_warn          =  1,
329
        vsl_check_valid         =  2
330
};
331
332
enum vsl_check
333
VSL_Check(const struct VSL_cursor *c, const struct VSLC_ptr *ptr);
334
        /*
335
         * Check if the VSLC_ptr structure points to a value that is still
336
         * valid:
337
         *
338
         * Return values:
339
         *    -1: Operation not supported
340
         *     0: Not valid
341
         *     1: Valid - warning level
342
         *     2: Valid
343
         */
344
345
enum vsl_status {
346
        vsl_e_write     = -5,   // Error from VSL_Write etc.
347
        vsl_e_io        = -4,   // I/O read error - see errno
348
        vsl_e_overrun   = -3,   // Overrun
349
        vsl_e_abandon   = -2,   // Remote abandoned or closed
350
        vsl_e_eof       = -1,   // End of file
351
        vsl_end         =  0,   // End of log/cursor
352
        vsl_more        =  1    // Cursor points to next log record
353
};
354
355
enum vsl_status
356
VSL_Next(const struct VSL_cursor *c);
357
        /*
358
         * Return raw pointer to next VSL record.
359
         *
360
         * Return values: see enum vsl_status
361
         */
362
363
int VSL_Match(struct VSL_data *vsl, const struct VSL_cursor *c);
364
        /*
365
         * Returns true if the record pointed to by cursor matches the
366
         * record current record selectors
367
         *
368
         * Return value:
369
         *      1:      Match
370
         *      0:      No match
371
         */
372
373
int VSL_Print(const struct VSL_data *vsl, const struct VSL_cursor *c, void *fo);
374
        /*
375
         * Print the log record pointed to by cursor to stream.
376
         *
377
         * Format: (t=type)
378
         * 1234567890 12345678901234 1 ...
379
         *       vxid tag            t content
380
         *
381
         * Arguments:
382
         *   vsl: The VSL_data context
383
         *     c: A VSL_cursor
384
         *    fo: A FILE* pointer
385
         *
386
         * Return values:
387
         *      0:      OK
388
         *     -5:      I/O write error - see errno
389
         */
390
391
int VSL_PrintTerse(const struct VSL_data *vsl, const struct VSL_cursor *c,
392
    void *fo);
393
        /*
394
         * Print the log record pointed to by cursor to stream.
395
         *
396
         * Format:
397
         * 12345678901234 ...
398
         * tag            content
399
         *
400
         * Arguments:
401
         *   vsl: The VSL_data context
402
         *     c: A VSL_cursor
403
         *    fo: A FILE* pointer
404
         *
405
         * Return values:
406
         *      0:      OK
407
         *     -5:      I/O write error - see errno
408
         */
409
410
int VSL_PrintAll(struct VSL_data *vsl, const struct VSL_cursor *c, void *fo);
411
        /*
412
         * Calls VSL_Next on c until c is exhausted. In turn calls
413
         * VSL_Print on all records where VSL_Match returns true.
414
         *
415
         * Arguments:
416
         *   vsl: The VSL_data context
417
         *     c: A VSL_cursor
418
         *    fo: A FILE* pointer, stdout if NULL
419
         *
420
         * Return values:
421
         *      0:      OK
422
         *    !=0:      Return value from either VSL_Next or VSL_Print
423
         */
424
425
VSLQ_dispatch_f VSL_PrintTransactions;
426
        /*
427
         * Prints out each transaction in the array ptrans. For
428
         * transactions of level > 0 it will print a header before the log
429
         * records. The records will for level == 0 (single records) or if
430
         * v_opt is set, be printed by VSL_Print. Else VSL_PrintTerse is
431
         * used.
432
         *
433
         * Arguments:
434
         *   vsl: The VSL_data context
435
         *    cp: A NULL-terminated array of VSL_cursor pointers
436
         *    fo: A FILE* pointer, stdout if NULL
437
         *
438
         * Return values:
439
         *      0:      OK
440
         *    !=0:      Return value from either VSL_Next or VSL_Print
441
         */
442
443
FILE *VSL_WriteOpen(struct VSL_data *vsl, const char *name, int append,
444
                    int unbuffered);
445
        /*
446
         * Open file name for writing using the VSL_Write* functions. If
447
         * append is true, the file will be opened for appending.
448
         *
449
         * Arguments:
450
         *     vsl: The VSL data context
451
         *    name: The file name
452
         *  append: If true, the file will be appended instead of truncated
453
         *   unbuf: If true, use unbuffered mode
454
         *
455
         * Return values:
456
         *     NULL: Error - see VSL_Error
457
         * non-NULL: Success
458
         */
459
460
461
int VSL_Write(const struct VSL_data *vsl, const struct VSL_cursor *c, void *fo);
462
        /*
463
         * Write the current record pointed to be c to the FILE* fo
464
         *
465
         * Return values:
466
         *    0: Success
467
         *   -5: I/O error - see VSL_Error
468
         */
469
470
int VSL_WriteAll(struct VSL_data *vsl, const struct VSL_cursor *c, void *fo);
471
        /*
472
         * Calls VSL_Next on c until c is exhausted. In turn calls
473
         * VSL_Write on all records where VSL_Match returns true.
474
         *
475
         * Return values:
476
         *      0:      OK
477
         *    !=0:      Return value from either VSL_Next or VSL_Write
478
         */
479
480
VSLQ_dispatch_f VSL_WriteTransactions;
481
        /*
482
         * Write all transactions in ptrans using VSL_WriteAll
483
         * Return values:
484
         *      0:      OK
485
         *    !=0:      Return value from either VSL_Next or VSL_Write
486
         */
487
488
struct VSLQ *VSLQ_New(struct VSL_data *vsl, struct VSL_cursor **cp,
489
    enum VSL_grouping_e grouping, const char *query);
490
        /*
491
         * Create a new query context.
492
         *
493
         * If cp is not NULL, the cursor pointed to by cp will be
494
         * transferred to the query, and *cp set to NULL.
495
         *
496
         * Arguments:
497
         *       vsl: The VSL_data context
498
         *        cp: Pointer to the cursor to use or NULL
499
         *  grouping: VXID grouping to report on
500
         *     query: Query match expression
501
         *
502
         * Return values:
503
         *  non-NULL: OK
504
         *      NULL: Error - see VSL_Error
505
         */
506
507
void VSLQ_Delete(struct VSLQ **pvslq);
508
        /*
509
         * Delete the query pointed to by pvslq, freeing up the resources.
510
         *
511
         * Any cursor owned by the query will be deleted.
512
         */
513
514
void VSLQ_SetCursor(struct VSLQ *vslq, struct VSL_cursor **cp);
515
        /*
516
         * Set the cursor to use.
517
         *
518
         * Any previous cursor owned by the query will be deleted. Will
519
         * call VSLQ_Flush.
520
         *
521
         * Arguments:
522
         *      vslq: The VSLQ query
523
         *        cp: Pointer to the cursor to use or NULL
524
         */
525
526
int VSLQ_Dispatch(struct VSLQ *vslq, VSLQ_dispatch_f *func, void *priv);
527
        /*
528
         * Process log and call func for each set matching the specified
529
         * query
530
         *
531
         * Arguments:
532
         *  vslq: The VSLQ query
533
         *  func: The callback function to call. Can be NULL to ignore records.
534
         *  priv: An argument passed to func
535
         *
536
         * Return values:
537
         *     1: Call again
538
         *     0: No more log records available
539
         *   !=0: func returned non-zero or enum vsl_status
540
         */
541
542
int VSLQ_Flush(struct VSLQ *vslq, VSLQ_dispatch_f *func, void *priv);
543
        /*
544
         * Flush any pending record sets from the query until func
545
         * (if given) returns non-zero.
546
         *
547
         * Arguments:
548
         *  vslq: The VSL context
549
         *  func: The callback function to call. Pass NULL to discard the
550
         *        pending messages or call repeatedly until 0 is returned.
551
         *  priv: An argument passed to func
552
         *
553
         * Return values:
554
         *     0: OK
555
         *   !=0: The return value from func
556
         */
557
558
#endif /* VAPI_VSL_H_INCLUDED */