procfs-guide.tmpl

嵌入式系统设计与实例开发实验教材二源码 多线程应用程序设计 串行端口程序设计 AD接口实验 CAN总线通信实验 GPS通信实验 Linux内核移植与编译实验 IC卡读写实验 SD驱动使

<!-- -*- sgml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
<!ENTITY procfsexample SYSTEM "procfs_example.sgml">
]>

<book id="LKProcfsGuide">
  <bookinfo>
    <title>Linux Kernel Procfs Guide</title>

    <authorgroup>
      <author>
	<firstname>Erik</firstname>
	<othername>(J.A.K.)</othername>
	<surname>Mouw</surname>
	<affiliation>
	  <orgname>Delft University of Technology</orgname>
	  <orgdiv>Faculty of Information Technology and Systems</orgdiv>
	  <address>
            <email>[e-mail]</email>
            <pob>PO BOX 5031</pob>
            <postcode>2600 GA</postcode>
            <city>Delft</city>
            <country>The Netherlands</country>
          </address>
	</affiliation>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
	<revnumber>1.0&nbsp;</revnumber>
	<date>May 30, 2001</date>
	<revremark>Initial revision posted to linux-kernel</revremark>
      </revision>
      <revision>
	<revnumber>1.1&nbsp;</revnumber>
	<date>June 3, 2001</date>
	<revremark>Revised after comments from linux-kernel</revremark>
      </revision>
    </revhistory>

    <copyright>
      <year>2001</year>
      <holder>Erik Mouw</holder>
    </copyright>


    <legalnotice>
      <para>
        This documentation is free software; you can redistribute it
        and/or modify it under the terms of the GNU General Public
        License as published by the Free Software Foundation; either
        version 2 of the License, or (at your option) any later
        version.
      </para>
      
      <para>
        This documentation is distributed in the hope that it will be
        useful, but WITHOUT ANY WARRANTY; without even the implied
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
        PURPOSE.  See the GNU General Public License for more details.
      </para>
      
      <para>
        You should have received a copy of the GNU General Public
        License along with this program; if not, write to the Free
        Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
        MA 02111-1307 USA
      </para>
      
      <para>
        For more details see the file COPYING in the source
        distribution of Linux.
      </para>
    </legalnotice>
  </bookinfo>




  <toc>
  </toc>




  <preface>
    <title>Preface</title>

    <para>
      This guide describes the use of the procfs file system from
      within the Linux kernel. The idea to write this guide came up on
      the #kernelnewbies IRC channel (see <ulink
      url="http://www.kernelnewbies.org/">http://www.kernelnewbies.org/</ulink>),
      when Jeff Garzik explained the use of procfs and forwarded me a
      message Alexander Viro wrote to the linux-kernel mailing list. I
      agreed to write it up nicely, so here it is.
    </para>

    <para>
      I'd like to thank Jeff Garzik
      <email>[e-mail]</email> and Alexander Viro
      <email>[e-mail]</email> for their input, Tim Waugh
      <email>[e-mail]</email> for his <ulink
      url="http://people.redhat.com/twaugh/docbook/selfdocbook/">Selfdocbook</ulink>,
      and Marc Joosen <email>[e-mail]</email> for
      proofreading.
    </para>

    <para>
      This documentation was written while working on the LART
      computing board (<ulink
      url="http://www.lart.tudelft.nl/">http://www.lart.tudelft.nl/</ulink>),
      which is sponsored by the Mobile Multi-media Communications
      (<ulink
      url="http://www.mmc.tudelft.nl/">http://www.mmc.tudelft.nl/</ulink>)
      and Ubiquitous Communications (<ulink
      url="http://www.ubicom.tudelft.nl/">http://www.ubicom.tudelft.nl/</ulink>)
      projects.
    </para>

    <para>
      Erik
    </para>
  </preface>




  <chapter id="intro">
    <title>Introduction</title>

    <para>
      The <filename class="directory">/proc</filename> file system
      (procfs) is a special file system in the linux kernel. It's a
      virtual file system: it is not associated with a block device
      but exists only in memory. The files in the procfs are there to
      allow userland programs access to certain information from the
      kernel (like process information in <filename
      class="directory">/proc/[0-9]+/</filename>), but also for debug
      purposes (like <filename>/proc/ksyms</filename>).
    </para>

    <para>
      This guide describes the use of the procfs file system from
      within the Linux kernel. It starts by introducing all relevant
      functions to manage the files within the file system. After that
      it shows how to communicate with userland, and some tips and
      tricks will be pointed out. Finally a complete example will be
      shown.
    </para>

    <para>
      Note that the files in <filename
      class="directory">/proc/sys</filename> are sysctl files: they
      don't belong to procfs and are governed by a completely
      different API described in the Kernel API book.
    </para>
  </chapter>




  <chapter id="managing">
    <title>Managing procfs entries</title>
    
    <para>
      This chapter describes the functions that various kernel
      components use to populate the procfs with files, symlinks,
      device nodes, and directories.
    </para>

    <para>
      A minor note before we start: if you want to use any of the
      procfs functions, be sure to include the correct header file! 
      This should be one of the first lines in your code:
    </para>

    <programlisting>
#include &lt;linux/proc_fs.h&gt;
    </programlisting>




    <sect1 id="regularfile">
      <title>Creating a regular file</title>
      
      <funcsynopsis>
	<funcprototype>
	  <funcdef>struct proc_dir_entry* <function>create_proc_entry</function></funcdef>
	  <paramdef>const char* <parameter>name</parameter></paramdef>
	  <paramdef>mode_t <parameter>mode</parameter></paramdef>
	  <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <para>
        This function creates a regular file with the name
        <parameter>name</parameter>, file mode
        <parameter>mode</parameter> in the directory
        <parameter>parent</parameter>. To create a file in the root of
        the procfs, use <constant>NULL</constant> as
        <parameter>parent</parameter> parameter. When successful, the
        function will return a pointer to the freshly created
        <structname>struct proc_dir_entry</structname>; otherwise it
        will return <constant>NULL</constant>. <xref
        linkend="userland"> describes how to do something useful with
        regular files.
      </para>

      <para>
        Note that it is specifically supported that you can pass a
        path that spans multiple directories. For example
        <function>create_proc_entry</function>(<parameter>"drivers/via0/info"</parameter>)
        will create the <filename class="directory">via0</filename>
        directory if necessary, with standard
        <constant>0755</constant> permissions.
      </para>

    <para>
      If you only want to be able to read the file, the function
      <function>create_proc_read_entry</function> described in <xref
      linkend="convenience"> may be used to create and initialise
      the procfs entry in one single call.
    </para>
    </sect1>




    <sect1>
      <title>Creating a symlink</title>

      <funcsynopsis>
	<funcprototype>
	  <funcdef>struct proc_dir_entry*
	  <function>proc_symlink</function></funcdef> <paramdef>const
	  char* <parameter>name</parameter></paramdef>
	  <paramdef>struct proc_dir_entry*
	  <parameter>parent</parameter></paramdef> <paramdef>const
	  char* <parameter>dest</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
      
      <para>
        This creates a symlink in the procfs directory
        <parameter>parent</parameter> that points from
        <parameter>name</parameter> to
        <parameter>dest</parameter>. This translates in userland to
        <literal>ln -s</literal> <parameter>dest</parameter>
        <parameter>name</parameter>.
      </para>
    </sect1>




    <sect1>
      <title>Creating a device</title>

      <funcsynopsis>
	<funcprototype>
	  <funcdef>struct proc_dir_entry* <function>proc_mknod</function></funcdef>
	  <paramdef>const char* <parameter>name</parameter></paramdef>
	  <paramdef>mode_t <parameter>mode</parameter></paramdef>
	  <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
	  <paramdef>kdev_t <parameter>rdev</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
      
      <para>
        Creates a device file <parameter>name</parameter> with mode
        <parameter>mode</parameter> in the procfs directory
        <parameter>parent</parameter>. The device file will work on
        the device <parameter>rdev</parameter>, which can be generated
        by using the <literal>MKDEV</literal> macro from
        <literal>linux/kdev_t.h</literal>. The
        <parameter>mode</parameter> parameter
        <emphasis>must</emphasis> contain <constant>S_IFBLK</constant>
        or <constant>S_IFCHR</constant> to create a device
        node. Compare with userland <literal>mknod
        --mode=</literal><parameter>mode</parameter>
        <parameter>name</parameter> <parameter>rdev</parameter>.
      </para>
    </sect1>




    <sect1>
      <title>Creating a directory</title>
      
      <funcsynopsis>
	<funcprototype>
	  <funcdef>struct proc_dir_entry* <function>proc_mkdir</function></funcdef>
	  <paramdef>const char* <parameter>name</parameter></paramdef>
	  <paramdef>struct proc_dir_entry* <parameter>parent</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <para>
        Create a directory <parameter>name</parameter> in the procfs
        directory <parameter>parent</parameter>.
      </para>
    </sect1>




    <sect1>
      <title>Removing an entry</title>