Documentation/DocBook/procfs-guide.tmpl

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