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