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