Documentation/DocBook/procfs-guide.tmpl

   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>
 318 struct proc_dir_entry* entry;
 319
 320 entry->read_proc = read_proc_foo;
 321 entry->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>
 495 struct proc_dir_entry* entry;
 496 struct my_file_data *file_data;
 497
 498 file_data = kmalloc(sizeof(struct my_file_data), GFP_KERNEL);
 499 entry->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>
 516 int 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>
 584 struct proc_dir_entry* entry;
 585
 586 entry->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>
 603 struct proc_dir_entry* entry;
 604
 605 entry->mode =  S_IWUSR |S_IRUSR | S_IRGRP | S_IROTH;
 606 entry->uid = 0;
 607 entry->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>