1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================
4 The seq_file Interface
5 ======================
6
7 Copyright 2003 Jonathan Corbet <corbet@
8
9 This file is originally from the LWN.n
10 https://lwn.net/Articles/driver-portin
11
12
13 There are numerous ways for a device driver (o
14 provide information to the user or system admi
15 technique is the creation of virtual files, in
16 Virtual files can provide human-readable outpu
17 without any special utility programs; they can
18 script writers. It is not surprising that the
19 grown over the years.
20
21 Creating those files correctly has always been
22 however. It is not that hard to make a virtual
23 string. But life gets trickier if the output i
24 than an application is likely to read in a sin
25 multiple reads (and seeks) requires careful at
26 position within the virtual file - that positi
27 middle of a line of output. The kernel has tra
28 implementations that got this wrong.
29
30 The 2.6 kernel contains a set of functions (im
31 which are designed to make it easy for virtual
32 right.
33
34 The seq_file interface is available via <linux
35 three aspects to seq_file:
36
37 * An iterator interface which lets a virt
38 step through the objects it is presenti
39
40 * Some utility functions for formatting o
41 needing to worry about things like outp
42
43 * A set of canned file_operations which i
44 the virtual file.
45
46 We'll look at the seq_file interface via an ex
47 loadable module which creates a file called /p
48 read, simply produces a set of increasing inte
49 sequence will continue until the user loses pa
50 better to do. The file is seekable, in that on
51 following::
52
53 dd if=/proc/sequence of=out1 count=1
54 dd if=/proc/sequence skip=1 of=out2 count=
55
56 Then concatenate the output files out1 and out
57 result. Yes, it is a thoroughly useless module
58 how the mechanism works without getting lost i
59 wanting to see the full source for this module
60 https://lwn.net/Articles/22359/).
61
62 Deprecated create_proc_entry
63 ============================
64
65 Note that the above article uses create_proc_e
66 kernel 3.10. Current versions require the foll
67
68 - entry = create_proc_entry("sequence",
69 - if (entry)
70 - entry->proc_fops = &ct_file_op
71 + entry = proc_create("sequence", 0, NUL
72
73 The iterator interface
74 ======================
75
76 Modules implementing a virtual file with seq_f
77 iterator object that allows stepping through t
78 during a "session" (roughly one read() system
79 is able to move to a specific position - like
80 though with freedom to map the position number
81 in whatever way is convenient - the iterator n
82 transiently during a session. If the iterator
83 numerical position but works well with a first
84 iterator can be stored in the private data are
85 session to the next.
86
87 A seq_file implementation that is formatting f
88 table, for example, could provide a simple ite
89 position N as the Nth rule in the chain. A se
90 that presents the content of a, potentially vo
91 might record a pointer into that list, providi
92 without risk of the current location being rem
93
94 Positioning can thus be done in whatever way m
95 the generator of the data, which need not be a
96 translates to an offset in the virtual file. T
97 is that a position of zero should indicate the
98
99 The /proc/sequence iterator just uses the coun
100 will output as its position.
101
102 Four functions must be implemented to make the
103 first, called start(), starts a session and ta
104 argument, returning an iterator which will sta
105 position. The pos passed to start() will alwa
106 the most recent pos used in the previous sessi
107
108 For our simple sequence example,
109 the start() function looks like::
110
111 static void *ct_seq_start(struct seq_f
112 {
113 loff_t *spos = kmalloc(sizeof(
114 if (! spos)
115 return NULL;
116 *spos = *pos;
117 return spos;
118 }
119
120 The entire data structure for this iterator is
121 holding the current position. There is no uppe
122 iterator, but that will not be the case for mo
123 implementations; in most cases the start() fun
124 "past end of file" condition and return NULL i
125
126 For more complicated applications, the private
127 structure can be used to hold state from sessi
128 also a special value which can be returned by
129 called SEQ_START_TOKEN; it can be used if you
130 show() function (described below) to print a h
131 output. SEQ_START_TOKEN should only be used if
132 however. SEQ_START_TOKEN has no special meani
133 code. It is provided as a convenience for a s
134 communicate with the next() and show() functio
135
136 The next function to implement is called, amaz
137 move the iterator forward to the next position
138 example module can simply increment the positi
139 modules will do what is needed to step through
140 next() function returns a new iterator, or NUL
141 complete. Here's the example version::
142
143 static void *ct_seq_next(struct seq_fi
144 {
145 loff_t *spos = v;
146 *pos = ++*spos;
147 return spos;
148 }
149
150 The next() function should set ``*pos`` to a v
151 to find the new location in the sequence. Whe
152 stored in the private data area, rather than b
153 start(), it might seem sufficient to simply se
154 value (zero always tells start() to restart th
155 sufficient due to historical problems.
156
157 Historically, many next() functions have *not*
158 end-of-file. If the value is then used by sta
159 iterator, this can result in corner cases wher
160 sequence is reported twice in the file. In or
161 from being resurrected, the core seq_file code
162 a next() function does not change the value of
163 next() function *must* change the value of ``*
164 set it to a non-zero value.
165
166 The stop() function closes a session; its job,
167 up. If dynamic memory is allocated for the ite
168 place to free it; if a lock was taken by start
169 that lock. The value that ``*pos`` was set to
170 before stop() is remembered, and used for the
171 the next session unless lseek() has been calle
172 case next start() will be asked to start at po
173
174 static void ct_seq_stop(struct seq_fil
175 {
176 kfree(v);
177 }
178
179 Finally, the show() function should format the
180 by the iterator for output. The example modul
181
182 static int ct_seq_show(struct seq_file
183 {
184 loff_t *spos = v;
185 seq_printf(s, "%lld\n", (long
186 return 0;
187 }
188
189 If all is well, the show() function should ret
190 code in the usual manner indicates that someth
191 passed back to user space. This function can
192 causes the current item to be skipped; if the
193 generated output before returning SEQ_SKIP, th
194
195 We will look at seq_printf() in a moment. But
196 seq_file iterator is finished by creating a se
197 the four functions we have just defined::
198
199 static const struct seq_operations ct_
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 itera
207 a little bit.
208
209 It's worth noting that the iterator value retu
210 manipulated by the other functions is consider
211 the seq_file code. It can thus be anything tha
212 through the data to be output. Counters can be
213 a direct pointer into an array or linked list.
214 the programmer is aware that things can happen
215 iterator function. However, the seq_file code
216 between the calls to start() and stop(), so ho
217 is a reasonable thing to do. The seq_file code
218 other locks while the iterator is active.
219
220 The iterator value returned by start() or next
221 passed to a subsequent next() or stop() call.
222 such as locks that were taken to be reliably r
223 guarantee that the iterator will be passed to
224 it often will be.
225
226
227 Formatted output
228 ================
229
230 The seq_file code manages positioning within t
231 iterator and getting it into the user's buffer
232 output must be passed to the seq_file code. So
233 been defined which make this task easy.
234
235 Most code will simply use seq_printf(), which
236 printk(), but which requires the seq_file poin
237
238 For straight character output, the following f
239
240 seq_putc(struct seq_file *m, char c);
241 seq_puts(struct seq_file *m, const cha
242 seq_escape(struct seq_file *m, const c
243
244 The first two output a single character and a
245 expect. seq_escape() is like seq_puts(), excep
246 which is in the string esc will be represented
247
248 There are also a pair of functions for printin
249
250 int seq_path(struct seq_file *m, const
251 const char *esc);
252 int seq_path_root(struct seq_file *m,
253 const struct path *r
254
255 Here, path indicates the file of interest, and
256 which should be escaped in the output. A call
257 the path relative to the current process's fil
258 root is desired, it can be used with seq_path_
259 path cannot be reached from root, seq_path_roo
260
261 A function producing complicated output may wa
262
263 bool seq_has_overflowed(struct seq_fil
264
265 and avoid further seq_<output> calls if true i
266
267 A true return from seq_has_overflowed means th
268 be discarded and the seq_show function will at
269 buffer and retry printing.
270
271
272 Making it all work
273 ==================
274
275 So far, we have a nice set of functions which
276 seq_file system, but we have not yet turned th
277 can see. Creating a file within the kernel req
278 creation of a set of file_operations which imp
279 file. The seq_file interface provides a set of
280 most of the work. The virtual file author stil
281 method, however, to hook everything up. The op
282 line, as in the example module::
283
284 static int ct_open(struct inode *inode
285 {
286 return seq_open(file, &ct_seq_
287 }
288
289 Here, the call to seq_open() takes the seq_ope
290 before, and gets set up to iterate through the
291
292 On a successful open, seq_open() stores the st
293 file->private_data. If you have an application
294 be used for more than one file, you can store
295 private field of the seq_file structure; that
296 by the iterator functions.
297
298 There is also a wrapper function to seq_open()
299 kmallocs a zero filled block of memory and sto
300 private field of the seq_file structure, retur
301 block size is specified in a third parameter t
302
303 static int ct_open(struct inode *inode
304 {
305 return seq_open_private(file,
306 sizeof
307 }
308
309 There is also a variant function, __seq_open_p
310 identical except that, if successful, it retur
311 memory block, allowing further initialisation
312
313 static int ct_open(struct inode *inode
314 {
315 struct mystruct *p =
316 __seq_open_private(fil
317
318 if (!p)
319 return -ENOMEM;
320
321 p->foo = bar; /* initialize my
322 ...
323 p->baz = true;
324
325 return 0;
326 }
327
328 A corresponding close function, seq_release_pr
329 frees the memory allocated in the correspondin
330
331 The other operations of interest - read(), lls
332 all implemented by the seq_file code itself. S
333 file_operations structure will look like::
334
335 static const struct file_operations ct
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 pa
344 seq_file private field to kfree() before relea
345
346 The final step is the creation of the /proc fi
347 code, that is done in the initialization code
348
349 static int ct_init(void)
350 {
351 struct proc_dir_entry *entry;
352
353 proc_create("sequence", 0, NUL
354 return 0;
355 }
356
357 module_init(ct_init);
358
359 And that is pretty much it.
360
361
362 seq_list
363 ========
364
365 If your file will be iterating through a linke
366 routines useful::
367
368 struct list_head *seq_list_start(struc
369 loff_
370 struct list_head *seq_list_start_head(
371
372 struct list_head *seq_list_next(void *
373 loff_t
374
375 These helpers will interpret pos as a position
376 accordingly. Your start() and next() function
377 ``seq_list_*`` helpers with a pointer to the a
378
379
380 The extra-simple version
381 ========================
382
383 For extremely simple virtual files, there is a
384 module can define only the show() function, wh
385 output that the virtual file will contain. The
386 calls::
387
388 int single_open(struct file *file,
389 int (*show)(struct seq
390 void *data);
391
392 When output time comes, the show() function wi
393 value given to single_open() can be found in t
394 seq_file structure. When using single_open(),
395 single_release() instead of seq_release() in t
396 to avoid a memory leak.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.