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