LXR linux/include/linux/seq

   1/* SPDX-License-Identifier: GPL-2.0 */
   2#ifndef _LINUX_SEQ_FILE_H
   3#define _LINUX_SEQ_FILE_H
   4
   5#include <linux/types.h>
   6#include <linux/string.h>
   7#include <linux/bug.h>
   8#include <linux/mutex.h>
   9#include <linux/cpumask.h>
  10#include <linux/nodemask.h>
  11#include <linux/fs.h>
  12#include <linux/cred.h>
  13
  14struct seq_operations;
  15
  16struct seq_file {
  17        char *buf;
  18        size_t size;
  19        size_t from;
  20        size_t count;
  21        size_t pad_until;
  22        loff_t index;
  23        loff_t read_pos;
  24        u64 version;
  25        struct mutex lock;
  26        const struct seq_operations *op;
  27        int poll_event;
  28        const struct file *file;
  29        void *private;
  30};
  31
  32struct seq_operations {
  33        void * (*start) (struct seq_file *m, loff_t *pos);
  34        void (*stop) (struct seq_file *m, void *v);
  35        void * (*next) (struct seq_file *m, void *v, loff_t *pos);
  36        int (*show) (struct seq_file *m, void *v);
  37};
  38
  39#define SEQ_SKIP 1
  40
  41/**
  42 * seq_has_overflowed - check if the buffer has overflowed
  43 * @m: the seq_file handle
  44 *
  45 * seq_files have a buffer which may overflow. When this happens a larger
  46 * buffer is reallocated and all the data will be printed again.
  47 * The overflow state is true when m->count == m->size.
  48 *
  49 * Returns true if the buffer received more than it can hold.
  50 */
  51static inline bool seq_has_overflowed(struct seq_file *m)
  52{
  53        return m->count == m->size;
  54}
  55
  56/**
  57 * seq_get_buf - get buffer to write arbitrary data to
  58 * @m: the seq_file handle
  59 * @bufp: the beginning of the buffer is stored here
  60 *
  61 * Return the number of bytes available in the buffer, or zero if
  62 * there's no space.
  63 */
  64static inline size_t seq_get_buf(struct seq_file *m, char **bufp)
  65{
  66        BUG_ON(m->count > m->size);
  67        if (m->count < m->size)
  68                *bufp = m->buf + m->count;
  69        else
  70                *bufp = NULL;
  71
  72        return m->size - m->count;
  73}
  74
  75/**
  76 * seq_commit - commit data to the buffer
  77 * @m: the seq_file handle
  78 * @num: the number of bytes to commit
  79 *
  80 * Commit @num bytes of data written to a buffer previously acquired
  81 * by seq_buf_get.  To signal an error condition, or that the data
  82 * didn't fit in the available space, pass a negative @num value.
  83 */
  84static inline void seq_commit(struct seq_file *m, int num)
  85{
  86        if (num < 0) {
  87                m->count = m->size;
  88        } else {
  89                BUG_ON(m->count + num > m->size);
  90                m->count += num;
  91        }
  92}
  93
  94/**
  95 * seq_setwidth - set padding width
  96 * @m: the seq_file handle
  97 * @size: the max number of bytes to pad.
  98 *
  99 * Call seq_setwidth() for setting max width, then call seq_printf() etc. and
 100 * finally call seq_pad() to pad the remaining bytes.
 101 */
 102static inline void seq_setwidth(struct seq_file *m, size_t size)
 103{
 104        m->pad_until = m->count + size;
 105}
 106void seq_pad(struct seq_file *m, char c);
 107
 108char *mangle_path(char *s, const char *p, const char *esc);
 109int seq_open(struct file *, const struct seq_operations *);
 110ssize_t seq_read(struct file *, char __user *, size_t, loff_t *);
 111loff_t seq_lseek(struct file *, loff_t, int);
 112int seq_release(struct inode *, struct file *);
 113int seq_write(struct seq_file *seq, const void *data, size_t len);
 114
 115__printf(2, 0)
 116void seq_vprintf(struct seq_file *m, const char *fmt, va_list args);
 117__printf(2, 3)
 118void seq_printf(struct seq_file *m, const char *fmt, ...);
 119void seq_putc(struct seq_file *m, char c);
 120void seq_puts(struct seq_file *m, const char *s);
 121void seq_put_decimal_ull_width(struct seq_file *m, const char *delimiter,
 122                               unsigned long long num, unsigned int width);
 123void seq_put_decimal_ull(struct seq_file *m, const char *delimiter,
 124                         unsigned long long num);
 125void seq_put_decimal_ll(struct seq_file *m, const char *delimiter, long long num);
 126void seq_put_hex_ll(struct seq_file *m, const char *delimiter,
 127                    unsigned long long v, unsigned int width);
 128
 129void seq_escape(struct seq_file *m, const char *s, const char *esc);
 130
 131void seq_hex_dump(struct seq_file *m, const char *prefix_str, int prefix_type,
 132                  int rowsize, int groupsize, const void *buf, size_t len,
 133                  bool ascii);
 134
 135int seq_path(struct seq_file *, const struct path *, const char *);
 136int seq_file_path(struct seq_file *, struct file *, const char *);
 137int seq_dentry(struct seq_file *, struct dentry *, const char *);
 138int seq_path_root(struct seq_file *m, const struct path *path,
 139                  const struct path *root, const char *esc);
 140
 141int single_open(struct file *, int (*)(struct seq_file *, void *), void *);
 142int single_open_size(struct file *, int (*)(struct seq_file *, void *), void *, size_t);
 143int single_release(struct inode *, struct file *);
 144void *__seq_open_private(struct file *, const struct seq_operations *, int);
 145int seq_open_private(struct file *, const struct seq_operations *, int);
 146int seq_release_private(struct inode *, struct file *);
 147
 148#define DEFINE_SHOW_ATTRIBUTE(__name)                                   \
 149static int __name ## _open(struct inode *inode, struct file *file)      \
 150{                                                                       \
 151        return single_open(file, __name ## _show, inode->i_private);    \
 152}                                                                       \
 153                                                                        \
 154static const struct file_operations __name ## _fops = {                 \
 155        .owner          = THIS_MODULE,                                  \
 156        .open           = __name ## _open,                              \
 157        .read           = seq_read,                                     \
 158        .llseek         = seq_lseek,                                    \
 159        .release        = single_release,                               \
 160}
 161
 162static inline struct user_namespace *seq_user_ns(struct seq_file *seq)
 163{
 164#ifdef CONFIG_USER_NS
 165        return seq->file->f_cred->user_ns;
 166#else
 167        extern struct user_namespace init_user_ns;
 168        return &init_user_ns;
 169#endif
 170}
 171
 172/**
 173 * seq_show_options - display mount options with appropriate escapes.
 174 * @m: the seq_file handle
 175 * @name: the mount option name
 176 * @value: the mount option name's value, can be NULL
 177 */
 178static inline void seq_show_option(struct seq_file *m, const char *name,
 179                                   const char *value)
 180{
 181        seq_putc(m, ',');
 182        seq_escape(m, name, ",= \t\n\\");
 183        if (value) {
 184                seq_putc(m, '=');
 185                seq_escape(m, value, ", \t\n\\");
 186        }
 187}
 188
 189/**
 190 * seq_show_option_n - display mount options with appropriate escapes
 191 *                     where @value must be a specific length.
 192 * @m: the seq_file handle
 193 * @name: the mount option name
 194 * @value: the mount option name's value, cannot be NULL
 195 * @length: the length of @value to display
 196 *
 197 * This is a macro since this uses "length" to define the size of the
 198 * stack buffer.
 199 */
 200#define seq_show_option_n(m, name, value, length) {     \
 201        char val_buf[length + 1];                       \
 202        strncpy(val_buf, value, length);                \
 203        val_buf[length] = '\0';                         \
 204        seq_show_option(m, name, val_buf);              \
 205}
 206
 207#define SEQ_START_TOKEN ((void *)1)
 208/*
 209 * Helpers for iteration over list_head-s in seq_files
 210 */
 211
 212extern struct list_head *seq_list_start(struct list_head *head,
 213                loff_t pos);
 214extern struct list_head *seq_list_start_head(struct list_head *head,
 215                loff_t pos);
 216extern struct list_head *seq_list_next(void *v, struct list_head *head,
 217                loff_t *ppos);
 218
 219/*
 220 * Helpers for iteration over hlist_head-s in seq_files
 221 */
 222
 223extern struct hlist_node *seq_hlist_start(struct hlist_head *head,
 224                                          loff_t pos);
 225extern struct hlist_node *seq_hlist_start_head(struct hlist_head *head,
 226                                               loff_t pos);
 227extern struct hlist_node *seq_hlist_next(void *v, struct hlist_head *head,
 228                                         loff_t *ppos);
 229
 230extern struct hlist_node *seq_hlist_start_rcu(struct hlist_head *head,
 231                                              loff_t pos);
 232extern struct hlist_node *seq_hlist_start_head_rcu(struct hlist_head *head,
 233                                                   loff_t pos);
 234extern struct hlist_node *seq_hlist_next_rcu(void *v,
 235                                                   struct hlist_head *head,
 236                                                   loff_t *ppos);
 237
 238/* Helpers for iterating over per-cpu hlist_head-s in seq_files */
 239extern struct hlist_node *seq_hlist_start_percpu(struct hlist_head __percpu *head, int *cpu, loff_t pos);
 240
 241extern struct hlist_node *seq_hlist_next_percpu(void *v, struct hlist_head __percpu *head, int *cpu, loff_t *pos);
 242
 243void seq_file_init(void);
 244#endif
 245