^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) The seq_file Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Copyright 2003 Jonathan Corbet <corbet@lwn.net>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) This file is originally from the LWN.net Driver Porting series at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) https://lwn.net/Articles/driver-porting/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) There are numerous ways for a device driver (or other kernel component) to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) provide information to the user or system administrator. One useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) technique is the creation of virtual files, in debugfs, /proc or elsewhere.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Virtual files can provide human-readable output that is easy to get at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) without any special utility programs; they can also make life easier for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) script writers. It is not surprising that the use of virtual files has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) grown over the years.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Creating those files correctly has always been a bit of a challenge,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) however. It is not that hard to make a virtual file which returns a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) string. But life gets trickier if the output is long - anything greater
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) than an application is likely to read in a single operation. Handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) multiple reads (and seeks) requires careful attention to the reader's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) position within the virtual file - that position is, likely as not, in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) middle of a line of output. The kernel has traditionally had a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) implementations that got this wrong.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) The 2.6 kernel contains a set of functions (implemented by Alexander Viro)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) which are designed to make it easy for virtual file creators to get it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) right.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The seq_file interface is available via <linux/seq_file.h>. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) three aspects to seq_file:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) * An iterator interface which lets a virtual file implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) step through the objects it is presenting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * Some utility functions for formatting objects for output without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) needing to worry about things like output buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) * A set of canned file_operations which implement most operations on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) the virtual file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) We'll look at the seq_file interface via an extremely simple example: a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) loadable module which creates a file called /proc/sequence. The file, when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) read, simply produces a set of increasing integer values, one per line. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) sequence will continue until the user loses patience and finds something
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) better to do. The file is seekable, in that one can do something like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) dd if=/proc/sequence of=out1 count=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) dd if=/proc/sequence skip=1 of=out2 count=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Then concatenate the output files out1 and out2 and get the right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) result. Yes, it is a thoroughly useless module, but the point is to show
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) how the mechanism works without getting lost in other details. (Those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) wanting to see the full source for this module can find it at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) https://lwn.net/Articles/22359/).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Deprecated create_proc_entry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Note that the above article uses create_proc_entry which was removed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) kernel 3.10. Current versions require the following update::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) - entry = create_proc_entry("sequence", 0, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) - if (entry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) - entry->proc_fops = &ct_file_ops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) + entry = proc_create("sequence", 0, NULL, &ct_file_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) The iterator interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Modules implementing a virtual file with seq_file must implement an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) iterator object that allows stepping through the data of interest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) during a "session" (roughly one read() system call). If the iterator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) is able to move to a specific position - like the file they implement,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) though with freedom to map the position number to a sequence location
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) in whatever way is convenient - the iterator need only exist
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) transiently during a session. If the iterator cannot easily find a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) numerical position but works well with a first/next interface, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) iterator can be stored in the private data area and continue from one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) session to the next.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) A seq_file implementation that is formatting firewall rules from a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) table, for example, could provide a simple iterator that interprets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) position N as the Nth rule in the chain. A seq_file implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) that presents the content of a, potentially volatile, linked list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) might record a pointer into that list, providing that can be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) without risk of the current location being removed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Positioning can thus be done in whatever way makes the most sense for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) the generator of the data, which need not be aware of how a position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) translates to an offset in the virtual file. The one obvious exception
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) is that a position of zero should indicate the beginning of the file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) The /proc/sequence iterator just uses the count of the next number it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) will output as its position.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Four functions must be implemented to make the iterator work. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) first, called start(), starts a session and takes a position as an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) argument, returning an iterator which will start reading at that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) position. The pos passed to start() will always be either zero, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) the most recent pos used in the previous session.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) For our simple sequence example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) the start() function looks like::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) static void *ct_seq_start(struct seq_file *s, loff_t *pos)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) loff_t *spos = kmalloc(sizeof(loff_t), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) if (! spos)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) return NULL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) *spos = *pos;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) return spos;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) The entire data structure for this iterator is a single loff_t value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) holding the current position. There is no upper bound for the sequence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) iterator, but that will not be the case for most other seq_file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) implementations; in most cases the start() function should check for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) "past end of file" condition and return NULL if need be.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) For more complicated applications, the private field of the seq_file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) structure can be used to hold state from session to session. There is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) also a special value which can be returned by the start() function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) called SEQ_START_TOKEN; it can be used if you wish to instruct your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) show() function (described below) to print a header at the top of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) output. SEQ_START_TOKEN should only be used if the offset is zero,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) however. SEQ_START_TOKEN has no special meaning to the core seq_file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) code. It is provided as a convenience for a start() funciton to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) communicate with the next() and show() functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) The next function to implement is called, amazingly, next(); its job is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) move the iterator forward to the next position in the sequence. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) example module can simply increment the position by one; more useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) modules will do what is needed to step through some data structure. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) next() function returns a new iterator, or NULL if the sequence is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) complete. Here's the example version::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) static void *ct_seq_next(struct seq_file *s, void *v, loff_t *pos)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) loff_t *spos = v;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) *pos = ++*spos;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) return spos;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) The next() function should set ``*pos`` to a value that start() can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) to find the new location in the sequence. When the iterator is being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) stored in the private data area, rather than being reinitialized on each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) start(), it might seem sufficient to simply set ``*pos`` to any non-zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) value (zero always tells start() to restart the sequence). This is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) sufficient due to historical problems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Historically, many next() functions have *not* updated ``*pos`` at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) end-of-file. If the value is then used by start() to initialise the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) iterator, this can result in corner cases where the last entry in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) sequence is reported twice in the file. In order to discourage this bug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) from being resurrected, the core seq_file code now produces a warning if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) a next() function does not change the value of ``*pos``. Consequently a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) next() function *must* change the value of ``*pos``, and of course must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) set it to a non-zero value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) The stop() function closes a session; its job, of course, is to clean
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) up. If dynamic memory is allocated for the iterator, stop() is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) place to free it; if a lock was taken by start(), stop() must release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) that lock. The value that ``*pos`` was set to by the last next() call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) before stop() is remembered, and used for the first start() call of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) the next session unless lseek() has been called on the file; in that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) case next start() will be asked to start at position zero::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) static void ct_seq_stop(struct seq_file *s, void *v)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) kfree(v);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) Finally, the show() function should format the object currently pointed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) by the iterator for output. The example module's show() function is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) static int ct_seq_show(struct seq_file *s, void *v)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) loff_t *spos = v;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) seq_printf(s, "%lld\n", (long long)*spos);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) If all is well, the show() function should return zero. A negative error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) code in the usual manner indicates that something went wrong; it will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) passed back to user space. This function can also return SEQ_SKIP, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) causes the current item to be skipped; if the show() function has already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) generated output before returning SEQ_SKIP, that output will be dropped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) We will look at seq_printf() in a moment. But first, the definition of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) seq_file iterator is finished by creating a seq_operations structure with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) the four functions we have just defined::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) static const struct seq_operations ct_seq_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) .start = ct_seq_start,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) .next = ct_seq_next,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) .stop = ct_seq_stop,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) .show = ct_seq_show
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) This structure will be needed to tie our iterator to the /proc file in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) a little bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) It's worth noting that the iterator value returned by start() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) manipulated by the other functions is considered to be completely opaque by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) the seq_file code. It can thus be anything that is useful in stepping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) through the data to be output. Counters can be useful, but it could also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) a direct pointer into an array or linked list. Anything goes, as long as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) the programmer is aware that things can happen between calls to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) iterator function. However, the seq_file code (by design) will not sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) between the calls to start() and stop(), so holding a lock during that time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) is a reasonable thing to do. The seq_file code will also avoid taking any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) other locks while the iterator is active.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) The iterater value returned by start() or next() is guaranteed to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) passed to a subsequent next() or stop() call. This allows resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) such as locks that were taken to be reliably released. There is *no*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) guarantee that the iterator will be passed to show(), though in practice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) it often will be.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) Formatted output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) The seq_file code manages positioning within the output created by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) iterator and getting it into the user's buffer. But, for that to work, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) output must be passed to the seq_file code. Some utility functions have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) been defined which make this task easy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Most code will simply use seq_printf(), which works pretty much like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) printk(), but which requires the seq_file pointer as an argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) For straight character output, the following functions may be used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) seq_putc(struct seq_file *m, char c);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) seq_puts(struct seq_file *m, const char *s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) seq_escape(struct seq_file *m, const char *s, const char *esc);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) The first two output a single character and a string, just like one would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) expect. seq_escape() is like seq_puts(), except that any character in s
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) which is in the string esc will be represented in octal form in the output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) There are also a pair of functions for printing filenames::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) int seq_path(struct seq_file *m, const struct path *path,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) const char *esc);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) int seq_path_root(struct seq_file *m, const struct path *path,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) const struct path *root, const char *esc)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Here, path indicates the file of interest, and esc is a set of characters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) which should be escaped in the output. A call to seq_path() will output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) the path relative to the current process's filesystem root. If a different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) root is desired, it can be used with seq_path_root(). If it turns out that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) path cannot be reached from root, seq_path_root() returns SEQ_SKIP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) A function producing complicated output may want to check::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) bool seq_has_overflowed(struct seq_file *m);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) and avoid further seq_<output> calls if true is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) A true return from seq_has_overflowed means that the seq_file buffer will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) be discarded and the seq_show function will attempt to allocate a larger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) buffer and retry printing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) Making it all work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) So far, we have a nice set of functions which can produce output within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) seq_file system, but we have not yet turned them into a file that a user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) can see. Creating a file within the kernel requires, of course, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) creation of a set of file_operations which implement the operations on that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) file. The seq_file interface provides a set of canned operations which do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) most of the work. The virtual file author still must implement the open()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) method, however, to hook everything up. The open function is often a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) line, as in the example module::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) static int ct_open(struct inode *inode, struct file *file)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) return seq_open(file, &ct_seq_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) Here, the call to seq_open() takes the seq_operations structure we created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) before, and gets set up to iterate through the virtual file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) On a successful open, seq_open() stores the struct seq_file pointer in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) file->private_data. If you have an application where the same iterator can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) be used for more than one file, you can store an arbitrary pointer in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) private field of the seq_file structure; that value can then be retrieved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) by the iterator functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) There is also a wrapper function to seq_open() called seq_open_private(). It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) kmallocs a zero filled block of memory and stores a pointer to it in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) private field of the seq_file structure, returning 0 on success. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) block size is specified in a third parameter to the function, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) static int ct_open(struct inode *inode, struct file *file)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) return seq_open_private(file, &ct_seq_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) sizeof(struct mystruct));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) There is also a variant function, __seq_open_private(), which is functionally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) identical except that, if successful, it returns the pointer to the allocated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) memory block, allowing further initialisation e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) static int ct_open(struct inode *inode, struct file *file)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) struct mystruct *p =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) __seq_open_private(file, &ct_seq_ops, sizeof(*p));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) if (!p)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) p->foo = bar; /* initialize my stuff */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) p->baz = true;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) A corresponding close function, seq_release_private() is available which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) frees the memory allocated in the corresponding open.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) The other operations of interest - read(), llseek(), and release() - are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) all implemented by the seq_file code itself. So a virtual file's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) file_operations structure will look like::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) static const struct file_operations ct_file_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) .owner = THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) .open = ct_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) .read = seq_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) .llseek = seq_lseek,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) .release = seq_release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) There is also a seq_release_private() which passes the contents of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) seq_file private field to kfree() before releasing the structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) The final step is the creation of the /proc file itself. In the example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) code, that is done in the initialization code in the usual way::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) static int ct_init(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) struct proc_dir_entry *entry;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) proc_create("sequence", 0, NULL, &ct_file_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) module_init(ct_init);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) And that is pretty much it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) seq_list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) If your file will be iterating through a linked list, you may find these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) routines useful::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) struct list_head *seq_list_start(struct list_head *head,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) loff_t pos);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) struct list_head *seq_list_start_head(struct list_head *head,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) loff_t pos);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) struct list_head *seq_list_next(void *v, struct list_head *head,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) loff_t *ppos);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) These helpers will interpret pos as a position within the list and iterate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) accordingly. Your start() and next() functions need only invoke the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) ``seq_list_*`` helpers with a pointer to the appropriate list_head structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) The extra-simple version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) For extremely simple virtual files, there is an even easier interface. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) module can define only the show() function, which should create all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) output that the virtual file will contain. The file's open() method then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) calls::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) int single_open(struct file *file,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) int (*show)(struct seq_file *m, void *p),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) void *data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) When output time comes, the show() function will be called once. The data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) value given to single_open() can be found in the private field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) seq_file structure. When using single_open(), the programmer should use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) single_release() instead of seq_release() in the file_operations structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) to avoid a memory leak.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags