path: root/include/linux/seq_buf.h

/* SPDX-License-Identifier: GPL-2.0 */
#ifndef _LINUX_SEQ_BUF_H
#define _LINUX_SEQ_BUF_H

#include <linux/bug.h>
#include <linux/minmax.h>
#include <linux/seq_file.h>
#include <linux/string.h>
#include <linux/types.h>

/*
 * Trace sequences are used to allow a function to call several other functions
 * to create a string of data to use.
 */

/**
 * struct seq_buf - seq buffer structure
 * @buffer:	pointer to the buffer
 * @size:	size of the buffer
 * @len:	the amount of data inside the buffer
 */
struct seq_buf {
	char			*buffer;
	size_t			size;
	size_t			len;
};

#define DECLARE_SEQ_BUF(NAME, SIZE)			\
	struct seq_buf NAME = {				\
		.buffer = (char[SIZE]) { 0 },		\
		.size = SIZE,				\
	}

/**
 * seq_buf_clear - reset the seq_buf to be read / appended from the beginning
 * @s: the seq_buf handle
 */
static inline void seq_buf_clear(struct seq_buf *s)
{
	s->len = 0;
	if (s->size)
		s->buffer[0] = '\0';
}

/**
 * seq_buf_init - initialize a seq_buf
 * @s: the seq_buf handle
 * @buf: pointer to the buffer
 * @size: total size of @buf
 *
 * The contents of the buffer are ignored.
 */
static inline void
seq_buf_init(struct seq_buf *s, char *buf, unsigned int size)
{
	s->buffer = buf;
	s->size = size;
	seq_buf_clear(s);
}

/*
 * seq_buf have a buffer that might overflow. When this happens
 * len is set to be greater than size.
 */
static inline bool
seq_buf_has_overflowed(struct seq_buf *s)
{
	return s->len > s->size;
}

/*
 * Mark @s as overflowed, which discards the length of what it holds. The
 * bytes up to its last one are the string from then on, as that is where
 * seq_buf_str() terminates it, so clear whatever was not written: a writer
 * sets len to how much it filled, and anything past that was never adopted.
 */
static inline void
seq_buf_set_overflow(struct seq_buf *s)
{
	if (s->len < s->size)
		memset(s->buffer + s->len, 0, s->size - s->len);

	s->len = s->size + 1;
}

/**
 * seq_buf_init_append - initialize a seq_buf over a buffer that may
 *			 already hold NUL-terminated content
 * @s: the seq_buf handle
 * @buf: pointer to the (possibly non-empty) buffer
 * @size: total size of @buf
 *
 * Unlike seq_buf_init(), which always starts @buf at len=0, this
 * preserves whatever NUL-terminated content @buf already holds and
 * positions @s to append after it. Useful for converting code that used
 * to append to an existing buffer with strlcat()/scnprintf() and friends.
 *
 * If @buf holds no NUL within @size, @s starts out overflowed, as
 * strlcat() treats such a buffer as already truncated.
 */
static inline void
seq_buf_init_append(struct seq_buf *s, char *buf, unsigned int size)
{
	s->buffer = buf;
	s->size = size;
	s->len = strnlen(buf, size);
	if (s->len == size)
		seq_buf_set_overflow(s);
}

/*
 * How much buffer is left on the seq_buf?
 */
static inline unsigned int
seq_buf_buffer_left(struct seq_buf *s)
{
	if (seq_buf_has_overflowed(s))
		return 0;

	return s->size - s->len;
}

/* How much buffer was written? */
static inline unsigned int seq_buf_used(struct seq_buf *s)
{
	return min(s->len, s->size);
}

/*
 * NUL-terminate the buffer in @s: directly after the data when there is
 * room for it, otherwise in the last byte of the buffer. @s->size must not
 * be zero.
 *
 * Returns: the offset of the NUL.
 */
static inline size_t __seq_buf_terminate(struct seq_buf *s)
{
	size_t end;

	if (seq_buf_buffer_left(s))
		end = s->len;
	else
		end = s->size - 1;

	s->buffer[end] = 0;

	return end;
}

/**
 * seq_buf_str - get NUL-terminated C string from seq_buf
 * @s: the seq_buf handle
 *
 * This makes sure that the buffer in @s is NUL-terminated and
 * safe to read as a string.
 *
 * Note, if this is called when the buffer has overflowed, then
 * the last byte of the buffer is zeroed, and the len will still
 * point passed it. The same happens when the buffer is exactly
 * full: the NUL takes the place of the last byte written, which is
 * lost, though seq_buf_used() still counts it.
 *
 * A zero-sized seq_buf has nowhere to put a NUL, so the empty string
 * is returned instead of writing to @s->buffer. Any other seq_buf
 * returns @s->buffer, even when it holds an empty string, so callers
 * always get their own buffer back.
 *
 * After this function is called, s->buffer is safe to use
 * in string operations.
 *
 * Returns: @s->buf after making sure it is terminated.
 */
static inline const char *seq_buf_str(struct seq_buf *s)
{
	if (s->size == 0)
		return "";

	__seq_buf_terminate(s);

	return s->buffer;
}

/**
 * seq_buf_strlen - get the length of the NUL-terminated C string in seq_buf
 * @s: the seq_buf handle
 *
 * This makes sure that the buffer in @s is NUL-terminated, exactly as
 * seq_buf_str() does, and returns the length of the resulting string
 * without walking it. Unlike seq_buf_used(), this does not count the byte
 * given up to the NUL when the buffer is full or has overflowed. When the
 * buffer is exactly full, that byte is the last one written, and calling
 * either function loses it.
 *
 * A zero-sized seq_buf holds no string, so 0 is returned without writing
 * to @s->buffer, matching what seq_buf_str() returns for one.
 *
 * After this function is called, s->buffer is safe to use
 * in string operations.
 *
 * Returns: the offset of the NUL that terminates @s->buffer. That is the
 * length of the string unless an earlier NUL is in the way, either one the
 * data written to @s carried itself, or one seq_buf_set_overflow() left
 * behind when it cleared what no writer had claimed.
 */
static inline size_t seq_buf_strlen(struct seq_buf *s)
{
	if (s->size == 0)
		return 0;

	return __seq_buf_terminate(s);
}

/**
 * seq_buf_terminate - NUL-terminate the string in a seq_buf
 * @s: the seq_buf handle
 *
 * Terminate @s->buffer exactly as seq_buf_str() and seq_buf_strlen() do,
 * for callers that want neither the pointer nor the length and only need
 * the buffer to be safe to read as a C string. A zero-sized seq_buf has
 * nowhere to put a NUL and is left untouched.
 *
 * Nothing is returned on purpose: a caller that wants the length should
 * use seq_buf_strlen(), which says so.
 *
 * After this function is called, s->buffer is safe to use
 * in string operations.
 */
static inline void seq_buf_terminate(struct seq_buf *s)
{
	if (s->size == 0)
		return;

	__seq_buf_terminate(s);
}

/**
 * seq_buf_get_buf - get buffer to write arbitrary data to
 * @s: the seq_buf handle
 * @bufp: the beginning of the buffer is stored here
 *
 * Returns: the number of bytes available in the buffer, or zero if
 * there's no space.
 */
static inline size_t seq_buf_get_buf(struct seq_buf *s, char **bufp)
{
	WARN_ON(s->len > s->size + 1);

	if (s->len < s->size) {
		*bufp = s->buffer + s->len;
		return s->size - s->len;
	}

	*bufp = NULL;
	return 0;
}

/**
 * seq_buf_commit - commit data to the buffer
 * @s: the seq_buf handle
 * @num: the number of bytes to commit
 *
 * Commit @num bytes of data written to a buffer previously acquired
 * by seq_buf_get_buf(). To signal an error condition, or that the data
 * didn't fit in the available space, pass a negative @num value.
 */
static inline void seq_buf_commit(struct seq_buf *s, int num)
{
	if (num < 0) {
		seq_buf_set_overflow(s);
	} else {
		/* num must be negative on overflow */
		BUG_ON(s->len + num > s->size);
		s->len += num;
	}
}

/**
 * seq_buf_pop - pop off the last written character
 * @s: the seq_buf handle
 *
 * Removes the last written character to the seq_buf @s.
 *
 * Returns the last character, or -1 if @s is empty or has overflowed.
 */
static inline int seq_buf_pop(struct seq_buf *s)
{
	if (!s->len || seq_buf_has_overflowed(s))
		return -1;

	s->len--;
	return (unsigned int)s->buffer[s->len];
}

extern __printf(2, 3)
int seq_buf_printf(struct seq_buf *s, const char *fmt, ...);
extern __printf(2, 0)
int seq_buf_vprintf(struct seq_buf *s, const char *fmt, va_list args);
extern int seq_buf_print_seq(struct seq_file *m, struct seq_buf *s);
extern int seq_buf_to_user(struct seq_buf *s, char __user *ubuf,
			   size_t start, int cnt);
extern int seq_buf_puts(struct seq_buf *s, const char *str);
extern int seq_buf_putc(struct seq_buf *s, unsigned char c);
extern int seq_buf_putmem(struct seq_buf *s, const void *mem, unsigned int len);
extern int seq_buf_putmem_hex(struct seq_buf *s, const void *mem,
			      unsigned int len);
extern int seq_buf_path(struct seq_buf *s, const struct path *path, const char *esc);
extern int seq_buf_hex_dump(struct seq_buf *s, const char *prefix_str,
			    int prefix_type, int rowsize, int groupsize,
			    const void *buf, size_t len, bool ascii);

#ifdef CONFIG_BINARY_PRINTF
__printf(2, 0)
int seq_buf_bprintf(struct seq_buf *s, const char *fmt, const u32 *binary);
#endif

void seq_buf_do_printk(struct seq_buf *s, const char *lvl);

#endif /* _LINUX_SEQ_BUF_H */