aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/procfs-guide.tmpl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/procfs-guide.tmpl')
-rw-r--r--Documentation/DocBook/procfs-guide.tmpl626
1 files changed, 0 insertions, 626 deletions
diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl
deleted file mode 100644
index 9eba4b7af73d..000000000000
--- a/Documentation/DocBook/procfs-guide.tmpl
+++ /dev/null
@@ -1,626 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4<!ENTITY procfsexample SYSTEM "procfs_example.xml">
5]>
6
7<book id="LKProcfsGuide">
8 <bookinfo>
9 <title>Linux Kernel Procfs Guide</title>
10
11 <authorgroup>
12 <author>
13 <firstname>Erik</firstname>
14 <othername>(J.A.K.)</othername>
15 <surname>Mouw</surname>
16 <affiliation>
17 <address>
18 <email>mouw@nl.linux.org</email>
19 </address>
20 </affiliation>
21 </author>
22 <othercredit>
23 <contrib>
24 This software and documentation were written while working on the
25 LART computing board
26 (<ulink url="http://www.lartmaker.nl/">http://www.lartmaker.nl/</ulink>),
27 which was sponsored by the Delt University of Technology projects
28 Mobile Multi-media Communications and Ubiquitous Communications.
29 </contrib>
30 </othercredit>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.0</revnumber>
36 <date>May 30, 2001</date>
37 <revremark>Initial revision posted to linux-kernel</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.1</revnumber>
41 <date>June 3, 2001</date>
42 <revremark>Revised after comments from linux-kernel</revremark>
43 </revision>
44 </revhistory>
45
46 <copyright>
47 <year>2001</year>
48 <holder>Erik Mouw</holder>
49 </copyright>
50
51
52 <legalnotice>
53 <para>
54 This documentation is free software; you can redistribute it
55 and/or modify it under the terms of the GNU General Public
56 License as published by the Free Software Foundation; either
57 version 2 of the License, or (at your option) any later
58 version.
59 </para>
60
61 <para>
62 This documentation is distributed in the hope that it will be
63 useful, but WITHOUT ANY WARRANTY; without even the implied
64 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
65 PURPOSE. See the GNU General Public License for more details.
66 </para>
67
68 <para>
69 You should have received a copy of the GNU General Public
70 License along with this program; if not, write to the Free
71 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
72 MA 02111-1307 USA
73 </para>
74
75 <para>
76 For more details see the file COPYING in the source
77 distribution of Linux.
78 </para>
79 </legalnotice>
80 </bookinfo>
81
82
83
84
85 <toc>
86 </toc>
87
88
89
90
91 <preface id="Preface">
92 <title>Preface</title>
93
94 <para>
95 This guide describes the use of the procfs file system from
96 within the Linux kernel. The idea to write this guide came up on
97 the #kernelnewbies IRC channel (see <ulink
98 url="http://www.kernelnewbies.org/">http://www.kernelnewbies.org/</ulink>),
99 when Jeff Garzik explained the use of procfs and forwarded me a
100 message Alexander Viro wrote to the linux-kernel mailing list. I
101 agreed to write it up nicely, so here it is.
102 </para>
103
104 <para>
105 I'd like to thank Jeff Garzik
106 <email>jgarzik@pobox.com</email> and Alexander Viro
107 <email>viro@parcelfarce.linux.theplanet.co.uk</email> for their input,
108 Tim Waugh <email>twaugh@redhat.com</email> for his <ulink
109 url="http://people.redhat.com/twaugh/docbook/selfdocbook/">Selfdocbook</ulink>,
110 and Marc Joosen <email>marcj@historia.et.tudelft.nl</email> for
111 proofreading.
112 </para>
113
114 <para>
115 Erik
116 </para>
117 </preface>
118
119
120
121
122 <chapter id="intro">
123 <title>Introduction</title>
124
125 <para>
126 The <filename class="directory">/proc</filename> file system
127 (procfs) is a special file system in the linux kernel. It's a
128 virtual file system: it is not associated with a block device
129 but exists only in memory. The files in the procfs are there to
130 allow userland programs access to certain information from the
131 kernel (like process information in <filename
132 class="directory">/proc/[0-9]+/</filename>), but also for debug
133 purposes (like <filename>/proc/ksyms</filename>).
134 </para>
135
136 <para>
137 This guide describes the use of the procfs file system from
138 within the Linux kernel. It starts by introducing all relevant
139 functions to manage the files within the file system. After that
140 it shows how to communicate with userland, and some tips and
141 tricks will be pointed out. Finally a complete example will be
142 shown.
143 </para>
144
145 <para>
146 Note that the files in <filename
147 class="directory">/proc/sys</filename> are sysctl files: they
148 don't belong to procfs and are governed by a completely
149 different API described in the Kernel API book.
150 </para>
151 </chapter>
152
153
154
155
156 <chapter id="managing">
157 <title>Managing procfs entries</title>
158
159 <para>
160 This chapter describes the functions that various kernel
161 components use to populate the procfs with files, symlinks,
162 device nodes, and directories.
163 </para>
164
165 <para>
166 A minor note before we start: if you want to use any of the
167 procfs functions, be sure to include the correct header file!
168 This should be one of the first lines in your code:
169 </para>
170
171 <programlisting>
172#include &lt;linux/proc_fs.h&gt;
173 </programlisting>
174
175
176
177
178 <sect1 id="regularfile">
179 <title>Creating a regular file</title>
180
181 <funcsynopsis>
182 <funcprototype>
183 <funcdef>struct proc_dir_entry* <function>create_proc_entry</function></funcdef>
184 <paramdef>const char* <parameter>name</parameter></paramdef>
185 <paramdef>mode_t <parameter>mode</parameter></paramdef>
186 <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
187 </funcprototype>
188 </funcsynopsis>
189
190 <para>
191 This function creates a regular file with the name
192 <parameter>name</parameter>, file mode
193 <parameter>mode</parameter> in the directory
194 <parameter>parent</parameter>. To create a file in the root of
195 the procfs, use <constant>NULL</constant> as
196 <parameter>parent</parameter> parameter. When successful, the
197 function will return a pointer to the freshly created
198 <structname>struct proc_dir_entry</structname>; otherwise it
199 will return <constant>NULL</constant>. <xref
200 linkend="userland"/> describes how to do something useful with
201 regular files.
202 </para>
203
204 <para>
205 Note that it is specifically supported that you can pass a
206 path that spans multiple directories. For example
207 <function>create_proc_entry</function>(<parameter>"drivers/via0/info"</parameter>)
208 will create the <filename class="directory">via0</filename>
209 directory if necessary, with standard
210 <constant>0755</constant> permissions.
211 </para>
212
213 <para>
214 If you only want to be able to read the file, the function
215 <function>create_proc_read_entry</function> described in <xref
216 linkend="convenience"/> may be used to create and initialise
217 the procfs entry in one single call.
218 </para>
219 </sect1>
220
221
222
223
224 <sect1 id="Creating_a_symlink">
225 <title>Creating a symlink</title>
226
227 <funcsynopsis>
228 <funcprototype>
229 <funcdef>struct proc_dir_entry*
230 <function>proc_symlink</function></funcdef> <paramdef>const
231 char* <parameter>name</parameter></paramdef>
232 <paramdef>struct proc_dir_entry*
233 <parameter>parent</parameter></paramdef> <paramdef>const
234 char* <parameter>dest</parameter></paramdef>
235 </funcprototype>
236 </funcsynopsis>
237
238 <para>
239 This creates a symlink in the procfs directory
240 <parameter>parent</parameter> that points from
241 <parameter>name</parameter> to
242 <parameter>dest</parameter>. This translates in userland to
243 <literal>ln -s</literal> <parameter>dest</parameter>
244 <parameter>name</parameter>.
245 </para>
246 </sect1>
247
248 <sect1 id="Creating_a_directory">
249 <title>Creating a directory</title>
250
251 <funcsynopsis>
252 <funcprototype>
253 <funcdef>struct proc_dir_entry* <function>proc_mkdir</function></funcdef>
254 <paramdef>const char* <parameter>name</parameter></paramdef>
255 <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
256 </funcprototype>
257 </funcsynopsis>
258
259 <para>
260 Create a directory <parameter>name</parameter> in the procfs
261 directory <parameter>parent</parameter>.
262 </para>
263 </sect1>
264
265
266
267
268 <sect1 id="Removing_an_entry">
269 <title>Removing an entry</title>
270
271 <funcsynopsis>
272 <funcprototype>
273 <funcdef>void <function>remove_proc_entry</function></funcdef>
274 <paramdef>const char* <parameter>name</parameter></paramdef>
275 <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
276 </funcprototype>
277 </funcsynopsis>
278
279 <para>
280 Removes the entry <parameter>name</parameter> in the directory
281 <parameter>parent</parameter> from the procfs. Entries are
282 removed by their <emphasis>name</emphasis>, not by the
283 <structname>struct proc_dir_entry</structname> returned by the
284 various create functions. Note that this function doesn't
285 recursively remove entries.
286 </para>
287
288 <para>
289 Be sure to free the <structfield>data</structfield> entry from
290 the <structname>struct proc_dir_entry</structname> before
291 <function>remove_proc_entry</function> is called (that is: if
292 there was some <structfield>data</structfield> allocated, of
293 course). See <xref linkend="usingdata"/> for more information
294 on using the <structfield>data</structfield> entry.
295 </para>
296 </sect1>
297 </chapter>
298
299
300
301
302 <chapter id="userland">
303 <title>Communicating with userland</title>
304
305 <para>
306 Instead of reading (or writing) information directly from
307 kernel memory, procfs works with <emphasis>call back
308 functions</emphasis> for files: functions that are called when
309 a specific file is being read or written. Such functions have
310 to be initialised after the procfs file is created by setting
311 the <structfield>read_proc</structfield> and/or
312 <structfield>write_proc</structfield> fields in the
313 <structname>struct proc_dir_entry*</structname> that the
314 function <function>create_proc_entry</function> returned:
315 </para>
316
317 <programlisting>
318struct proc_dir_entry* entry;
319
320entry->read_proc = read_proc_foo;
321entry->write_proc = write_proc_foo;
322 </programlisting>
323
324 <para>
325 If you only want to use a the
326 <structfield>read_proc</structfield>, the function
327 <function>create_proc_read_entry</function> described in <xref
328 linkend="convenience"/> may be used to create and initialise the
329 procfs entry in one single call.
330 </para>
331
332
333
334 <sect1 id="Reading_data">
335 <title>Reading data</title>
336
337 <para>
338 The read function is a call back function that allows userland
339 processes to read data from the kernel. The read function
340 should have the following format:
341 </para>
342
343 <funcsynopsis>
344 <funcprototype>
345 <funcdef>int <function>read_func</function></funcdef>
346 <paramdef>char* <parameter>buffer</parameter></paramdef>
347 <paramdef>char** <parameter>start</parameter></paramdef>
348 <paramdef>off_t <parameter>off</parameter></paramdef>
349 <paramdef>int <parameter>count</parameter></paramdef>
350 <paramdef>int* <parameter>peof</parameter></paramdef>
351 <paramdef>void* <parameter>data</parameter></paramdef>
352 </funcprototype>
353 </funcsynopsis>
354
355 <para>
356 The read function should write its information into the
357 <parameter>buffer</parameter>, which will be exactly
358 <literal>PAGE_SIZE</literal> bytes long.
359 </para>
360
361 <para>
362 The parameter
363 <parameter>peof</parameter> should be used to signal that the
364 end of the file has been reached by writing
365 <literal>1</literal> to the memory location
366 <parameter>peof</parameter> points to.
367 </para>
368
369 <para>
370 The <parameter>data</parameter>
371 parameter can be used to create a single call back function for
372 several files, see <xref linkend="usingdata"/>.
373 </para>
374
375 <para>
376 The rest of the parameters and the return value are described
377 by a comment in <filename>fs/proc/generic.c</filename> as follows:
378 </para>
379
380 <blockquote>
381 <para>
382 You have three ways to return data:
383 </para>
384 <orderedlist>
385 <listitem>
386 <para>
387 Leave <literal>*start = NULL</literal>. (This is the default.)
388 Put the data of the requested offset at that
389 offset within the buffer. Return the number (<literal>n</literal>)
390 of bytes there are from the beginning of the
391 buffer up to the last byte of data. If the
392 number of supplied bytes (<literal>= n - offset</literal>) is
393 greater than zero and you didn't signal eof
394 and the reader is prepared to take more data
395 you will be called again with the requested
396 offset advanced by the number of bytes
397 absorbed. This interface is useful for files
398 no larger than the buffer.
399 </para>
400 </listitem>
401 <listitem>
402 <para>
403 Set <literal>*start</literal> to an unsigned long value less than
404 the buffer address but greater than zero.
405 Put the data of the requested offset at the
406 beginning of the buffer. Return the number of
407 bytes of data placed there. If this number is
408 greater than zero and you didn't signal eof
409 and the reader is prepared to take more data
410 you will be called again with the requested
411 offset advanced by <literal>*start</literal>. This interface is
412 useful when you have a large file consisting
413 of a series of blocks which you want to count
414 and return as wholes.
415 (Hack by Paul.Russell@rustcorp.com.au)
416 </para>
417 </listitem>
418 <listitem>
419 <para>
420 Set <literal>*start</literal> to an address within the buffer.
421 Put the data of the requested offset at <literal>*start</literal>.
422 Return the number of bytes of data placed there.
423 If this number is greater than zero and you
424 didn't signal eof and the reader is prepared to
425 take more data you will be called again with the
426 requested offset advanced by the number of bytes
427 absorbed.
428 </para>
429 </listitem>
430 </orderedlist>
431 </blockquote>
432
433 <para>
434 <xref linkend="example"/> shows how to use a read call back
435 function.
436 </para>
437 </sect1>
438
439
440
441
442 <sect1 id="Writing_data">
443 <title>Writing data</title>
444
445 <para>
446 The write call back function allows a userland process to write
447 data to the kernel, so it has some kind of control over the
448 kernel. The write function should have the following format:
449 </para>
450
451 <funcsynopsis>
452 <funcprototype>
453 <funcdef>int <function>write_func</function></funcdef>
454 <paramdef>struct file* <parameter>file</parameter></paramdef>
455 <paramdef>const char* <parameter>buffer</parameter></paramdef>
456 <paramdef>unsigned long <parameter>count</parameter></paramdef>
457 <paramdef>void* <parameter>data</parameter></paramdef>
458 </funcprototype>
459 </funcsynopsis>
460
461 <para>
462 The write function should read <parameter>count</parameter>
463 bytes at maximum from the <parameter>buffer</parameter>. Note
464 that the <parameter>buffer</parameter> doesn't live in the
465 kernel's memory space, so it should first be copied to kernel
466 space with <function>copy_from_user</function>. The
467 <parameter>file</parameter> parameter is usually
468 ignored. <xref linkend="usingdata"/> shows how to use the
469 <parameter>data</parameter> parameter.
470 </para>
471
472 <para>
473 Again, <xref linkend="example"/> shows how to use this call back
474 function.
475 </para>
476 </sect1>
477
478
479
480
481 <sect1 id="usingdata">
482 <title>A single call back for many files</title>
483
484 <para>
485 When a large number of almost identical files is used, it's
486 quite inconvenient to use a separate call back function for
487 each file. A better approach is to have a single call back
488 function that distinguishes between the files by using the
489 <structfield>data</structfield> field in <structname>struct
490 proc_dir_entry</structname>. First of all, the
491 <structfield>data</structfield> field has to be initialised:
492 </para>
493
494 <programlisting>
495struct proc_dir_entry* entry;
496struct my_file_data *file_data;
497
498file_data = kmalloc(sizeof(struct my_file_data), GFP_KERNEL);
499entry->data = file_data;
500 </programlisting>
501
502 <para>
503 The <structfield>data</structfield> field is a <type>void
504 *</type>, so it can be initialised with anything.
505 </para>
506
507 <para>
508 Now that the <structfield>data</structfield> field is set, the
509 <function>read_proc</function> and
510 <function>write_proc</function> can use it to distinguish
511 between files because they get it passed into their
512 <parameter>data</parameter> parameter:
513 </para>
514
515 <programlisting>
516int foo_read_func(char *page, char **start, off_t off,
517 int count, int *eof, void *data)
518{
519 int len;
520
521 if(data == file_data) {
522 /* special case for this file */
523 } else {
524 /* normal processing */
525 }
526
527 return len;
528}
529 </programlisting>
530
531 <para>
532 Be sure to free the <structfield>data</structfield> data field
533 when removing the procfs entry.
534 </para>
535 </sect1>
536 </chapter>
537
538
539
540
541 <chapter id="tips">
542 <title>Tips and tricks</title>
543
544
545
546
547 <sect1 id="convenience">
548 <title>Convenience functions</title>
549
550 <funcsynopsis>
551 <funcprototype>
552 <funcdef>struct proc_dir_entry* <function>create_proc_read_entry</function></funcdef>
553 <paramdef>const char* <parameter>name</parameter></paramdef>
554 <paramdef>mode_t <parameter>mode</parameter></paramdef>
555 <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
556 <paramdef>read_proc_t* <parameter>read_proc</parameter></paramdef>
557 <paramdef>void* <parameter>data</parameter></paramdef>
558 </funcprototype>
559 </funcsynopsis>
560
561 <para>
562 This function creates a regular file in exactly the same way
563 as <function>create_proc_entry</function> from <xref
564 linkend="regularfile"/> does, but also allows to set the read
565 function <parameter>read_proc</parameter> in one call. This
566 function can set the <parameter>data</parameter> as well, like
567 explained in <xref linkend="usingdata"/>.
568 </para>
569 </sect1>
570
571
572
573 <sect1 id="Modules">
574 <title>Modules</title>
575
576 <para>
577 If procfs is being used from within a module, be sure to set
578 the <structfield>owner</structfield> field in the
579 <structname>struct proc_dir_entry</structname> to
580 <constant>THIS_MODULE</constant>.
581 </para>
582
583 <programlisting>
584struct proc_dir_entry* entry;
585
586entry->owner = THIS_MODULE;
587 </programlisting>
588 </sect1>
589
590
591
592
593 <sect1 id="Mode_and_ownership">
594 <title>Mode and ownership</title>
595
596 <para>
597 Sometimes it is useful to change the mode and/or ownership of
598 a procfs entry. Here is an example that shows how to achieve
599 that:
600 </para>
601
602 <programlisting>
603struct proc_dir_entry* entry;
604
605entry->mode = S_IWUSR |S_IRUSR | S_IRGRP | S_IROTH;
606entry->uid = 0;
607entry->gid = 100;
608 </programlisting>
609
610 </sect1>
611 </chapter>
612
613
614
615
616 <chapter id="example">
617 <title>Example</title>
618
619 <!-- be careful with the example code: it shouldn't be wider than
620 approx. 60 columns, or otherwise it won't fit properly on a page
621 -->
622
623&procfsexample;
624
625 </chapter>
626</book>
generated by cgit v1.2.2 (git 2.25.0) at 2024-12-03 22:28:28 -0500