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