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);
 130void seq_escape_mem_ascii(struct seq_file *m, const char *src, size_t isz);
 131
 132void seq_hex_dump(struct seq_file *m, const char *prefix_str, int prefix_type,
 133                  int rowsize, int groupsize, const void *buf, size_t len,
 134                  bool ascii);
 135
 136int seq_path(struct seq_file *, const struct path *, const char *);
 137int seq_file_path(struct seq_file *, struct file *, const char *);
 138int seq_dentry(struct seq_file *, struct dentry *, const char *);
 139int seq_path_root(struct seq_file *m, const struct path *path,
 140                  const struct path *root, const char *esc);
 141
 142int single_open(struct file *, int (*)(struct seq_file *, void *), void *);
 143int single_open_size(struct file *, int (*)(struct seq_file *, void *), void *, size_t);
 144int single_release(struct inode *, struct file *);
 145void *__seq_open_private(struct file *, const struct seq_operations *, int);
 146int seq_open_private(struct file *, const struct seq_operations *, int);
 147int seq_release_private(struct inode *, struct file *);
 148
 149#define DEFINE_SHOW_ATTRIBUTE(__name)                                   \
 150static int __name ## _open(struct inode *inode, struct file *file)      \
 151{                                                                       \
 152        return single_open(file, __name ## _show, inode->i_private);    \
 153}                                                                       \
 154                                                                        \
 155static const struct file_operations __name ## _fops = {                 \
 156        .owner          = THIS_MODULE,                                  \
 157        .open           = __name ## _open,                              \
 158        .read           = seq_read,                                     \
 159        .llseek         = seq_lseek,                                    \
 160        .release        = single_release,                               \
 161}
 162
 163#define DEFINE_PROC_SHOW_ATTRIBUTE(__name)                              \
 164static int __name ## _open(struct inode *inode, struct file *file)      \
 165{                                                                       \
 166        return single_open(file, __name ## _show, inode->i_private);    \
 167}                                                                       \
 168                                                                        \
 169static const struct proc_ops __name ## _proc_ops = {                    \
 170        .proc_open      = __name ## _open,                              \
 171        .proc_read      = seq_read,                                     \
 172        .proc_lseek     = seq_lseek,                                    \
 173        .proc_release   = single_release,                               \
 174}
 175
 176static inline struct user_namespace *seq_user_ns(struct seq_file *seq)
 177{
 178#ifdef CONFIG_USER_NS
 179        return seq->file->f_cred->user_ns;
 180#else
 181        extern struct user_namespace init_user_ns;
 182        return &init_user_ns;
 183#endif
 184}
 185
 186/**
 187 * seq_show_options - display mount options with appropriate escapes.
 188 * @m: the seq_file handle
 189 * @name: the mount option name
 190 * @value: the mount option name's value, can be NULL
 191 */
 192static inline void seq_show_option(struct seq_file *m, const char *name,
 193                                   const char *value)
 194{
 195        seq_putc(m, ',');
 196        seq_escape(m, name, ",= \t\n\\");
 197        if (value) {
 198                seq_putc(m, '=');
 199                seq_escape(m, value, ", \t\n\\");
 200        }
 201}
 202
 203/**
 204 * seq_show_option_n - display mount options with appropriate escapes
 205 *                     where @value must be a specific length.
 206 * @m: the seq_file handle
 207 * @name: the mount option name
 208 * @value: the mount option name's value, cannot be NULL
 209 * @length: the length of @value to display
 210 *
 211 * This is a macro since this uses "length" to define the size of the
 212 * stack buffer.
 213 */
 214#define seq_show_option_n(m, name, value, length) {     \
 215        char val_buf[length + 1];                       \
 216        strncpy(val_buf, value, length);                \
 217        val_buf[length] = '\0';                         \
 218        seq_show_option(m, name, val_buf);              \
 219}
 220
 221#define SEQ_START_TOKEN ((void *)1)
 222/*
 223 * Helpers for iteration over list_head-s in seq_files
 224 */
 225
 226extern struct list_head *seq_list_start(struct list_head *head,
 227                loff_t pos);
 228extern struct list_head *seq_list_start_head(struct list_head *head,
 229                loff_t pos);
 230extern struct list_head *seq_list_next(void *v, struct list_head *head,
 231                loff_t *ppos);
 232
 233/*
 234 * Helpers for iteration over hlist_head-s in seq_files
 235 */
 236
 237extern struct hlist_node *seq_hlist_start(struct hlist_head *head,
 238                                          loff_t pos);
 239extern struct hlist_node *seq_hlist_start_head(struct hlist_head *head,
 240                                               loff_t pos);
 241extern struct hlist_node *seq_hlist_next(void *v, struct hlist_head *head,
 242                                         loff_t *ppos);
 243
 244extern struct hlist_node *seq_hlist_start_rcu(struct hlist_head *head,
 245                                              loff_t pos);
 246extern struct hlist_node *seq_hlist_start_head_rcu(struct hlist_head *head,
 247                                                   loff_t pos);
 248extern struct hlist_node *seq_hlist_next_rcu(void *v,
 249                                                   struct hlist_head *head,
 250                                                   loff_t *ppos);
 251
 252/* Helpers for iterating over per-cpu hlist_head-s in seq_files */
 253extern struct hlist_node *seq_hlist_start_percpu(struct hlist_head __percpu *head, int *cpu, loff_t pos);
 254
 255extern struct hlist_node *seq_hlist_next_percpu(void *v, struct hlist_head __percpu *head, int *cpu, loff_t *pos);
 256
 257void seq_file_init(void);
 258#endif
 259