include/linux/seq_buf.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_SEQ_BUF_H
   3 #define _LINUX_SEQ_BUF_H
   4
   5 #include <linux/bug.h>
   6 #include <linux/minmax.h>
   7 #include <linux/seq_file.h>
   8 #include <linux/types.h>
   9
  10 /*
  11  * Trace sequences are used to allow a function to call several other functions
  12  * to create a string of data to use.
  13  */
  14
  15 /**
  16  * struct seq_buf - seq buffer structure
  17  * @buffer:     pointer to the buffer
  18  * @size:       size of the buffer
  19  * @len:        the amount of data inside the buffer
  20  */
  21 struct seq_buf {
  22         char                    *buffer;
  23         size_t                  size;
  24         size_t                  len;
  25 };
  26
  27 #define DECLARE_SEQ_BUF(NAME, SIZE)                     \
  28         struct seq_buf NAME = {                         \
  29                 .buffer = (char[SIZE]) { 0 },           \
  30                 .size = SIZE,                           \
  31         }
  32
  33 static inline void seq_buf_clear(struct seq_buf *s)
  34 {
  35         s->len = 0;
  36         if (s->size)
  37                 s->buffer[0] = '\0';
  38 }
  39
  40 static inline void
  41 seq_buf_init(struct seq_buf *s, char *buf, unsigned int size)
  42 {
  43         s->buffer = buf;
  44         s->size = size;
  45         seq_buf_clear(s);
  46 }
  47
  48 /*
  49  * seq_buf have a buffer that might overflow. When this happens
  50  * len is set to be greater than size.
  51  */
  52 static inline bool
  53 seq_buf_has_overflowed(struct seq_buf *s)
  54 {
  55         return s->len > s->size;
  56 }
  57
  58 static inline void
  59 seq_buf_set_overflow(struct seq_buf *s)
  60 {
  61         s->len = s->size + 1;
  62 }
  63
  64 /*
  65  * How much buffer is left on the seq_buf?
  66  */
  67 static inline unsigned int
  68 seq_buf_buffer_left(struct seq_buf *s)
  69 {
  70         if (seq_buf_has_overflowed(s))
  71                 return 0;
  72
  73         return s->size - s->len;
  74 }
  75
  76 /* How much buffer was written? */
  77 static inline unsigned int seq_buf_used(struct seq_buf *s)
  78 {
  79         return min(s->len, s->size);
  80 }
  81
  82 /**
  83  * seq_buf_str - get NUL-terminated C string from seq_buf
  84  * @s: the seq_buf handle
  85  *
  86  * This makes sure that the buffer in @s is NUL-terminated and
  87  * safe to read as a string.
  88  *
  89  * Note, if this is called when the buffer has overflowed, then
  90  * the last byte of the buffer is zeroed, and the len will still
  91  * point passed it.
  92  *
  93  * After this function is called, s->buffer is safe to use
  94  * in string operations.
  95  *
  96  * Returns: @s->buf after making sure it is terminated.
  97  */
  98 static inline const char *seq_buf_str(struct seq_buf *s)
  99 {
 100         if (WARN_ON(s->size == 0))
 101                 return "";
 102
 103         if (seq_buf_buffer_left(s))
 104                 s->buffer[s->len] = 0;
 105         else
 106                 s->buffer[s->size - 1] = 0;
 107
 108         return s->buffer;
 109 }
 110
 111 /**
 112  * seq_buf_get_buf - get buffer to write arbitrary data to
 113  * @s: the seq_buf handle
 114  * @bufp: the beginning of the buffer is stored here
 115  *
 116  * Returns: the number of bytes available in the buffer, or zero if
 117  * there's no space.
 118  */
 119 static inline size_t seq_buf_get_buf(struct seq_buf *s, char **bufp)
 120 {
 121         WARN_ON(s->len > s->size + 1);
 122
 123         if (s->len < s->size) {
 124                 *bufp = s->buffer + s->len;
 125                 return s->size - s->len;
 126         }
 127
 128         *bufp = NULL;
 129         return 0;
 130 }
 131
 132 /**
 133  * seq_buf_commit - commit data to the buffer
 134  * @s: the seq_buf handle
 135  * @num: the number of bytes to commit
 136  *
 137  * Commit @num bytes of data written to a buffer previously acquired
 138  * by seq_buf_get_buf(). To signal an error condition, or that the data
 139  * didn't fit in the available space, pass a negative @num value.
 140  */
 141 static inline void seq_buf_commit(struct seq_buf *s, int num)
 142 {
 143         if (num < 0) {
 144                 seq_buf_set_overflow(s);
 145         } else {
 146                 /* num must be negative on overflow */
 147                 BUG_ON(s->len + num > s->size);
 148                 s->len += num;
 149         }
 150 }
 151
 152 extern __printf(2, 3)
 153 int seq_buf_printf(struct seq_buf *s, const char *fmt, ...);
 154 extern __printf(2, 0)
 155 int seq_buf_vprintf(struct seq_buf *s, const char *fmt, va_list args);
 156 extern int seq_buf_print_seq(struct seq_file *m, struct seq_buf *s);
 157 extern int seq_buf_to_user(struct seq_buf *s, char __user *ubuf,
 158                            size_t start, int cnt);
 159 extern int seq_buf_puts(struct seq_buf *s, const char *str);
 160 extern int seq_buf_putc(struct seq_buf *s, unsigned char c);
 161 extern int seq_buf_putmem(struct seq_buf *s, const void *mem, unsigned int len);
 162 extern int seq_buf_putmem_hex(struct seq_buf *s, const void *mem,
 163                               unsigned int len);
 164 extern int seq_buf_path(struct seq_buf *s, const struct path *path, const char *esc);
 165 extern int seq_buf_hex_dump(struct seq_buf *s, const char *prefix_str,
 166                             int prefix_type, int rowsize, int groupsize,
 167                             const void *buf, size_t len, bool ascii);
 168
 169 #ifdef CONFIG_BINARY_PRINTF
 170 extern int
 171 seq_buf_bprintf(struct seq_buf *s, const char *fmt, const u32 *binary);
 172 #endif
 173
 174 void seq_buf_do_printk(struct seq_buf *s, const char *lvl);
 175
 176 #endif /* _LINUX_SEQ_BUF_H */