<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="Linux-filesystems-API">
<bookinfo>
<title>Linux Filesystems API</title>
<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 program 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>
<chapter id="vfs">
<title>The Linux VFS</title>
<sect1 id="the_filesystem_types"><title>The Filesystem types</title>
<!-- include/linux/fs.h -->
<refentry id="API-enum-positive-aop-returns">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum positive_aop_returns</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum positive_aop_returns</refname>
<refpurpose>
aop return codes with specific semantics
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum positive_aop_returns {
AOP_WRITEPAGE_ACTIVATE,
AOP_TRUNCATED_PAGE
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>AOP_WRITEPAGE_ACTIVATE</term>
<listitem><para>
Informs the caller that page writeback has
completed, that the page is still locked, and
should be considered active. The VM uses this hint
to return the page to the active list -- it won't
be a candidate for writeback again in the near
future. Other callers must be careful to unlock
the page if they get this return. Returned by
<function>writepage</function>;
</para></listitem>
</varlistentry>
<varlistentry> <term>AOP_TRUNCATED_PAGE</term>
<listitem><para>
The AOP method that was handed a locked page has
unlocked it and the page might have been truncated.
The caller should back up to acquiring a new page and
trying again. The aop will be taking reasonable
precautions not to livelock. If the caller held a page
reference, it should drop it before retrying. Returned
by <function>readpage</function>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
address_space_operation functions return these large constants to indicate
special semantics to the caller. These are much larger than the bytes in a
page to allow for functions that return the number of bytes operated on in a
given page.
</para>
</refsect1>
</refentry>
<refentry id="API-inc-nlink">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>inc_nlink</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inc_nlink</refname>
<refpurpose>
directly increment an inode's link count
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>inc_nlink </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is a low-level filesystem helper to replace any
direct filesystem manipulation of i_nlink. Currently,
it is only here for parity with <function>dec_nlink</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-drop-nlink">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>drop_nlink</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>drop_nlink</refname>
<refpurpose>
directly drop an inode's link count
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>drop_nlink </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is a low-level filesystem helper to replace any
direct filesystem manipulation of i_nlink. In cases
where we are attempting to track writes to the
filesystem, a decrement to zero means an imminent
write when the file is truncated and actually unlinked
on the filesystem.
</para>
</refsect1>
</refentry>
<refentry id="API-clear-nlink">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>clear_nlink</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>clear_nlink</refname>
<refpurpose>
directly zero an inode's link count
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>clear_nlink </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is a low-level filesystem helper to replace any
direct filesystem manipulation of i_nlink. See
<function>drop_nlink</function> for why we care about i_nlink hitting zero.
</para>
</refsect1>
</refentry>
<refentry id="API-inode-inc-iversion">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>inode_inc_iversion</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inode_inc_iversion</refname>
<refpurpose>
increments i_version
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>inode_inc_iversion </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode that need to be updated
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Every time the inode is modified, the i_version field will be incremented.
The filesystem has to be mounted with i_version flag
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="the_directory_cache"><title>The Directory Cache</title>
<!-- fs/dcache.c -->
<refentry id="API-d-invalidate">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_invalidate</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_invalidate</refname>
<refpurpose>
invalidate a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>d_invalidate </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
dentry to invalidate
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Try to invalidate the dentry if it turns out to be
possible. If there are other dentries that can be
reached through this one we can't delete it and we
return -EBUSY. On success we return 0.
</para><para>
no dcache lock.
</para>
</refsect1>
</refentry>
<refentry id="API-shrink-dcache-sb">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>shrink_dcache_sb</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>shrink_dcache_sb</refname>
<refpurpose>
shrink dcache for a superblock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>shrink_dcache_sb </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Shrink the dcache for the specified super block. This
is used to free the dcache before unmounting a file
system
</para>
</refsect1>
</refentry>
<refentry id="API-have-submounts">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>have_submounts</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>have_submounts</refname>
<refpurpose>
check for mounts over a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>have_submounts </function></funcdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
dentry to check.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return true if the parent or its subdirectories contain
a mount point
</para>
</refsect1>
</refentry>
<refentry id="API-shrink-dcache-parent">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>shrink_dcache_parent</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>shrink_dcache_parent</refname>
<refpurpose>
prune dcache
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>shrink_dcache_parent </function></funcdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
parent of entries to prune
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Prune the dcache to remove unused children of the parent dentry.
</para>
</refsect1>
</refentry>
<refentry id="API-d-alloc">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_alloc</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_alloc</refname>
<refpurpose>
allocate a dcache entry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_alloc </function></funcdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>const struct qstr * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
parent of entry to allocate
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
qstr of the name
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Allocates a dentry. It returns <constant>NULL</constant> if there is insufficient memory
available. On a success the dentry is returned. The name passed in is
copied and the copy passed in may be reused after this call.
</para>
</refsect1>
</refentry>
<refentry id="API-d-instantiate">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_instantiate</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_instantiate</refname>
<refpurpose>
fill in inode information for a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>d_instantiate </function></funcdef>
<paramdef>struct dentry * <parameter>entry</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>entry</parameter></term>
<listitem>
<para>
dentry to complete
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to attach to this dentry
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Fill in inode information in the entry.
</para><para>
This turns negative dentries into productive full members
of society.
</para><para>
NOTE! This assumes that the inode count has been incremented
(or otherwise set) by the caller to indicate that it is now
in use by the dcache.
</para>
</refsect1>
</refentry>
<refentry id="API-d-alloc-root">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_alloc_root</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_alloc_root</refname>
<refpurpose>
allocate root dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_alloc_root </function></funcdef>
<paramdef>struct inode * <parameter>root_inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>root_inode</parameter></term>
<listitem>
<para>
inode to allocate the root for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Allocate a root (<quote>/</quote>) dentry for the inode given. The inode is
instantiated and returned. <constant>NULL</constant> is returned if there is insufficient
memory or the inode passed is <constant>NULL</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-d-obtain-alias">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_obtain_alias</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_obtain_alias</refname>
<refpurpose>
find or allocate a dentry for a given inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_obtain_alias </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to allocate the dentry for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Obtain a dentry for an inode resulting from NFS filehandle conversion or
similar open by handle operations. The returned dentry may be anonymous,
or may have a full name (if the inode was already in the cache).
</para><para>
When called on a directory inode, we must ensure that the inode only ever
has one dentry. If a dentry is found, that is returned instead of
allocating a new one.
</para><para>
On successful return, the reference to the inode has been transferred
to the dentry. In case of an error the reference on the inode is released.
To make it easier to use in export operations a <constant>NULL</constant> or IS_ERR inode may
be passed in and will be the error will be propagate to the return value,
with a <constant>NULL</constant> <parameter>inode</parameter> replaced by ERR_PTR(-ESTALE).
</para>
</refsect1>
</refentry>
<refentry id="API-d-splice-alias">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_splice_alias</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_splice_alias</refname>
<refpurpose>
splice a disconnected dentry into the tree if one exists
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_splice_alias </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode which may have a disconnected dentry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
a negative dentry which we want to point to the inode.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If inode is a directory and has a 'disconnected' dentry (i.e. IS_ROOT and
DCACHE_DISCONNECTED), then d_move that in place of the given dentry
and return it, else simply d_add the inode to the dentry and return NULL.
</para><para>
This is needed in the lookup routine of any filesystem that is exportable
(via knfsd) so that we can build dcache paths to directories effectively.
</para><para>
If a dentry was found and moved, then it is returned. Otherwise NULL
is returned. This matches the expected return value of ->lookup.
</para>
</refsect1>
</refentry>
<refentry id="API-d-add-ci">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_add_ci</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_add_ci</refname>
<refpurpose>
lookup or allocate new dentry with case-exact name
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_add_ci </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct qstr * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
the negative dentry that was passed to the parent's lookup func
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode case-insensitive lookup has found
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
the case-exact name to be associated with the returned dentry
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is to avoid filling the dcache with case-insensitive names to the
same inode, only the actual correct case is stored in the dcache for
case-insensitive filesystems.
</para><para>
For a case-insensitive lookup match and if the the case-exact dentry
already exists in in the dcache, use it and return it.
</para><para>
If no entry exists with the exact case name, allocate new dentry with
the exact case, and return the spliced entry.
</para>
</refsect1>
</refentry>
<refentry id="API-d-lookup">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_lookup</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_lookup</refname>
<refpurpose>
search for a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_lookup </function></funcdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>struct qstr * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
parent dentry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
qstr of name we wish to find
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Searches the children of the parent dentry for the name in question. If
the dentry is found its reference count is incremented and the dentry
is returned. The caller must use dput to free the entry when it has
finished using it. <constant>NULL</constant> is returned on failure.
</para><para>
__d_lookup is dcache_lock free. The hash list is protected using RCU.
Memory barriers are used while updating and doing lockless traversal.
To avoid races with d_move while rename is happening, d_lock is used.
</para><para>
Overflows in <function>memcmp</function>, while d_move, are avoided by keeping the length
and name pointer in one structure pointed by d_qstr.
</para><para>
<function>rcu_read_lock</function> and <function>rcu_read_unlock</function> are used to disable preemption while
lookup is going on.
</para><para>
The dentry unused LRU is not updated even if lookup finds the required dentry
in there. It is updated in places such as prune_dcache, shrink_dcache_sb,
select_parent and __dget_locked. This laziness saves lookup from dcache_lock
acquisition.
</para><para>
<function>d_lookup</function> is protected against the concurrent renames in some unrelated
directory using the seqlockt_t rename_lock.
</para>
</refsect1>
</refentry>
<refentry id="API-d-validate">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_validate</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_validate</refname>
<refpurpose>
verify dentry provided from insecure source
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>d_validate </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
<paramdef>struct dentry * <parameter>dparent</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
The dentry alleged to be valid child of <parameter>dparent</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dparent</parameter></term>
<listitem>
<para>
The parent dentry (known to be valid)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
An insecure source has sent us a dentry, here we verify it and <function>dget</function> it.
This is used by ncpfs in its readdir implementation.
Zero is returned in the dentry is invalid.
</para>
</refsect1>
</refentry>
<refentry id="API-d-delete">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_delete</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_delete</refname>
<refpurpose>
delete a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>d_delete </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
The dentry to delete
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Turn the dentry into a negative dentry if possible, otherwise
remove it from the hash queues so it can be deleted later
</para>
</refsect1>
</refentry>
<refentry id="API-d-rehash">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_rehash</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_rehash</refname>
<refpurpose>
add an entry back to the hash
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>d_rehash </function></funcdef>
<paramdef>struct dentry * <parameter>entry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>entry</parameter></term>
<listitem>
<para>
dentry to add to the hash
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Adds a dentry to the hash according to its name.
</para>
</refsect1>
</refentry>
<refentry id="API-d-move">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_move</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_move</refname>
<refpurpose>
move a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>d_move </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
<paramdef>struct dentry * <parameter>target</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
entry to move
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
new dentry
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Update the dcache to reflect the move of a file name. Negative
dcache entries should not be moved in this way.
</para>
</refsect1>
</refentry>
<refentry id="API-d-materialise-unique">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_materialise_unique</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_materialise_unique</refname>
<refpurpose>
introduce an inode into the tree
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_materialise_unique </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
candidate dentry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to bind to the dentry, to which aliases may be attached
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Introduces an dentry into the tree, substituting an extant disconnected
root directory alias in its place if there is one
</para>
</refsect1>
</refentry>
<refentry id="API-d-path">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_path</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_path</refname>
<refpurpose>
return the path of a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>d_path </function></funcdef>
<paramdef>const struct path * <parameter>path</parameter></paramdef>
<paramdef>char * <parameter>buf</parameter></paramdef>
<paramdef>int <parameter>buflen</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
path to report
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
buffer to return value in
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buflen</parameter></term>
<listitem>
<para>
buffer length
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Convert a dentry into an ASCII path name. If the entry has been deleted
the string <quote> (deleted)</quote> is appended. Note that this is ambiguous.
</para><para>
Returns a pointer into the buffer or an error code if the path was
too long. Note: Callers should use the returned pointer, not the passed
in buffer, to use the name! The implementation often starts at an offset
into the buffer, and may leave 0 bytes at the start.
</para><para>
<quote>buflen</quote> should be positive.
</para>
</refsect1>
</refentry>
<refentry id="API-find-inode-number">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>find_inode_number</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>find_inode_number</refname>
<refpurpose>
check for dentry with name
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ino_t <function>find_inode_number </function></funcdef>
<paramdef>struct dentry * <parameter>dir</parameter></paramdef>
<paramdef>struct qstr * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dir</parameter></term>
<listitem>
<para>
directory to check
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
Name to find.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Check whether a dentry already exists for the given name,
and return the inode number if it has an inode. Otherwise
0 is returned.
</para><para>
This routine is used to post-process directory listings for
filesystems using synthetic inode numbers, and is necessary
to keep <function>getcwd</function> working.
</para>
</refsect1>
</refentry>
<!-- include/linux/dcache.h -->
<refentry id="API---d-drop">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__d_drop</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__d_drop</refname>
<refpurpose>
drop a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>__d_drop </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
dentry to drop
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>d_drop</function> unhashes the entry from the parent dentry hashes, so that it won't
be found through a VFS lookup any more. Note that this is different from
deleting the dentry - d_delete will try to mark the dentry negative if
possible, giving a successful _negative_ lookup, while d_drop will
just make the cache lookup fail.
</para><para>
<function>d_drop</function> is used mainly for stuff that wants to invalidate a dentry for some
reason (NFS timeouts or autofs deletes).
</para><para>
__d_drop requires dentry->d_lock.
</para>
</refsect1>
</refentry>
<refentry id="API-d-add">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_add</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_add</refname>
<refpurpose>
add dentry to hash queues
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>d_add </function></funcdef>
<paramdef>struct dentry * <parameter>entry</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>entry</parameter></term>
<listitem>
<para>
dentry to add
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
The inode to attach to this dentry
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This adds the entry to the hash queues and initializes <parameter>inode</parameter>.
The entry was actually filled in earlier during <function>d_alloc</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-d-add-unique">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_add_unique</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_add_unique</refname>
<refpurpose>
add dentry to hash queues without aliasing
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>d_add_unique </function></funcdef>
<paramdef>struct dentry * <parameter>entry</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>entry</parameter></term>
<listitem>
<para>
dentry to add
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
The inode to attach to this dentry
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This adds the entry to the hash queues and initializes <parameter>inode</parameter>.
The entry was actually filled in earlier during <function>d_alloc</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-dget">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>dget</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>dget</refname>
<refpurpose>
get a reference to a dentry
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>dget </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
dentry to get a reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given a dentry or <constant>NULL</constant> pointer increment the reference count
if appropriate and return the dentry. A dentry will not be
destroyed when it has references. <function>dget</function> should never be
called for dentries with zero reference counter. For these cases
(preferably none, functions in dcache.c are sufficient for normal
needs and they take necessary precautions) you should hold dcache_lock
and call <function>dget_locked</function> instead of <function>dget</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-d-unhashed">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>d_unhashed</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>d_unhashed</refname>
<refpurpose>
is dentry hashed
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>d_unhashed </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
entry to check
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns true if the dentry passed is not currently hashed.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="inode_handling"><title>Inode Handling</title>
<!-- fs/inode.c -->
<refentry id="API-inode-init-always">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>inode_init_always</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inode_init_always</refname>
<refpurpose>
perform inode structure intialisation
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>inode_init_always </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock inode belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to initialise
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
These are initializations that need to be done on every inode
allocation as the fields are not initialised by slab allocation.
</para>
</refsect1>
</refentry>
<refentry id="API-clear-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>clear_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>clear_inode</refname>
<refpurpose>
clear an inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>clear_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to clear
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called by the filesystem to tell us
that the inode is no longer useful. We just
terminate it with extreme prejudice.
</para>
</refsect1>
</refentry>
<refentry id="API-invalidate-inodes">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>invalidate_inodes</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>invalidate_inodes</refname>
<refpurpose>
discard the inodes on a device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>invalidate_inodes </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Discard all of the inodes for a given superblock. If the discard
fails because there are busy inodes then a non zero value is returned.
If the discard is successful all the inodes have been discarded.
</para>
</refsect1>
</refentry>
<refentry id="API-inode-add-to-lists">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>inode_add_to_lists</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inode_add_to_lists</refname>
<refpurpose>
add a new inode to relevant lists
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>inode_add_to_lists </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock inode belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to mark in use
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
When an inode is allocated it needs to be accounted for, added to the in use
list, the owning superblock and the inode hash. This needs to be done under
the inode_lock, so export a function to do this rather than the inode lock
itself. We calculate the hash list to add to here so it is all internal
which requires the caller to have already set up the inode number in the
inode to add.
</para>
</refsect1>
</refentry>
<refentry id="API-new-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>new_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>new_inode</refname>
<refpurpose>
obtain an inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>new_inode </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Allocates a new inode for given superblock. The default gfp_mask
for allocations related to inode->i_mapping is GFP_HIGHUSER_MOVABLE.
If HIGHMEM pages are unsuitable or it is known that pages allocated
for the page cache are not reclaimable or migratable,
<function>mapping_set_gfp_mask</function> must be called with suitable flags on the
newly created inode's mapping
</para>
</refsect1>
</refentry>
<refentry id="API-iunique">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>iunique</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iunique</refname>
<refpurpose>
get a unique inode number
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ino_t <function>iunique </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>ino_t <parameter>max_reserved</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>max_reserved</parameter></term>
<listitem>
<para>
highest reserved inode number
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Obtain an inode number that is unique on the system for a given
superblock. This is used by file systems that have no natural
permanent inode numbering system. An inode number is returned that
is higher than the reserved limit but unique.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
With a large number of inodes live on the file system this function
currently becomes quite slow.
</para>
</refsect1>
</refentry>
<refentry id="API-ilookup5-nowait">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ilookup5_nowait</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ilookup5_nowait</refname>
<refpurpose>
search for an inode in the inode cache
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>ilookup5_nowait </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>unsigned long <parameter>hashval</parameter></paramdef>
<paramdef>int (*<parameter>test</parameter>)
<funcparams>struct inode *, void *</funcparams></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
super block of file system to search
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>hashval</parameter></term>
<listitem>
<para>
hash value (usually inode number) to search for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>test</parameter></term>
<listitem>
<para>
callback used for comparisons between inodes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
opaque data pointer to pass to <parameter>test</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>ilookup5</function> uses <function>ifind</function> to search for the inode specified by <parameter>hashval</parameter> and
<parameter>data</parameter> in the inode cache. This is a generalized version of <function>ilookup</function> for
file systems where the inode number is not sufficient for unique
identification of an inode.
</para><para>
If the inode is in the cache, the inode is returned with an incremented
reference count. Note, the inode lock is not waited upon so you have to be
very careful what you do with the returned inode. You probably should be
using <function>ilookup5</function> instead.
</para><para>
Otherwise NULL is returned.
</para><para>
Note, <parameter>test</parameter> is called with the inode_lock held, so can't sleep.
</para>
</refsect1>
</refentry>
<refentry id="API-ilookup5">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ilookup5</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ilookup5</refname>
<refpurpose>
search for an inode in the inode cache
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>ilookup5 </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>unsigned long <parameter>hashval</parameter></paramdef>
<paramdef>int (*<parameter>test</parameter>)
<funcparams>struct inode *, void *</funcparams></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
super block of file system to search
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>hashval</parameter></term>
<listitem>
<para>
hash value (usually inode number) to search for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>test</parameter></term>
<listitem>
<para>
callback used for comparisons between inodes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
opaque data pointer to pass to <parameter>test</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>ilookup5</function> uses <function>ifind</function> to search for the inode specified by <parameter>hashval</parameter> and
<parameter>data</parameter> in the inode cache. This is a generalized version of <function>ilookup</function> for
file systems where the inode number is not sufficient for unique
identification of an inode.
</para><para>
If the inode is in the cache, the inode lock is waited upon and the inode is
returned with an incremented reference count.
</para><para>
Otherwise NULL is returned.
</para><para>
Note, <parameter>test</parameter> is called with the inode_lock held, so can't sleep.
</para>
</refsect1>
</refentry>
<refentry id="API-ilookup">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ilookup</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ilookup</refname>
<refpurpose>
search for an inode in the inode cache
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>ilookup </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>unsigned long <parameter>ino</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
super block of file system to search
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ino</parameter></term>
<listitem>
<para>
inode number to search for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>ilookup</function> uses <function>ifind_fast</function> to search for the inode <parameter>ino</parameter> in the inode cache.
This is for file systems where the inode number is sufficient for unique
identification of an inode.
</para><para>
If the inode is in the cache, the inode is returned with an incremented
reference count.
</para><para>
Otherwise NULL is returned.
</para>
</refsect1>
</refentry>
<refentry id="API-iget5-locked">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>iget5_locked</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iget5_locked</refname>
<refpurpose>
obtain an inode from a mounted file system
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>iget5_locked </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>unsigned long <parameter>hashval</parameter></paramdef>
<paramdef>int (*<parameter>test</parameter>)
<funcparams>struct inode *, void *</funcparams></paramdef>
<paramdef>int (*<parameter>set</parameter>)
<funcparams>struct inode *, void *</funcparams></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
super block of file system
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>hashval</parameter></term>
<listitem>
<para>
hash value (usually inode number) to get
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>test</parameter></term>
<listitem>
<para>
callback used for comparisons between inodes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>set</parameter></term>
<listitem>
<para>
callback used to initialize a new struct inode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
opaque data pointer to pass to <parameter>test</parameter> and <parameter>set</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>iget5_locked</function> uses <function>ifind</function> to search for the inode specified by <parameter>hashval</parameter>
and <parameter>data</parameter> in the inode cache and if present it is returned with an increased
reference count. This is a generalized version of <function>iget_locked</function> for file
systems where the inode number is not sufficient for unique identification
of an inode.
</para><para>
If the inode is not in cache, <function>get_new_inode</function> is called to allocate a new
inode and this is returned locked, hashed, and with the I_NEW flag set. The
file system gets to fill it in before unlocking it via <function>unlock_new_inode</function>.
</para><para>
Note both <parameter>test</parameter> and <parameter>set</parameter> are called with the inode_lock held, so can't sleep.
</para>
</refsect1>
</refentry>
<refentry id="API-iget-locked">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>iget_locked</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iget_locked</refname>
<refpurpose>
obtain an inode from a mounted file system
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct inode * <function>iget_locked </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
<paramdef>unsigned long <parameter>ino</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
super block of file system
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ino</parameter></term>
<listitem>
<para>
inode number to get
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>iget_locked</function> uses <function>ifind_fast</function> to search for the inode specified by <parameter>ino</parameter> in
the inode cache and if present it is returned with an increased reference
count. This is for file systems where the inode number is sufficient for
unique identification of an inode.
</para><para>
If the inode is not in cache, <function>get_new_inode_fast</function> is called to allocate a
new inode and this is returned locked, hashed, and with the I_NEW flag set.
The file system gets to fill it in before unlocking it via
<function>unlock_new_inode</function>.
</para>
</refsect1>
</refentry>
<refentry id="API---insert-inode-hash">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__insert_inode_hash</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__insert_inode_hash</refname>
<refpurpose>
hash an inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>__insert_inode_hash </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>unsigned long <parameter>hashval</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
unhashed inode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>hashval</parameter></term>
<listitem>
<para>
unsigned long value used to locate this object in the
inode_hashtable.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Add an inode to the inode hash for this superblock.
</para>
</refsect1>
</refentry>
<refentry id="API-remove-inode-hash">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>remove_inode_hash</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>remove_inode_hash</refname>
<refpurpose>
remove an inode from the hash
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>remove_inode_hash </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to unhash
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Remove an inode from the superblock.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-detach-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_detach_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_detach_inode</refname>
<refpurpose>
remove inode from inode lists
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>generic_detach_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to remove
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Remove inode from inode lists, write it if it's dirty. This is just an
internal VFS helper exported for hugetlbfs. Do not use!
</para><para>
Returns 1 if inode should be completely destroyed.
</para>
</refsect1>
</refentry>
<refentry id="API-iput">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>iput</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iput</refname>
<refpurpose>
put an inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>iput </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to put
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Puts an inode, dropping its usage count. If the inode use count hits
zero, the inode is then freed and may also be destroyed.
</para><para>
Consequently, <function>iput</function> can sleep.
</para>
</refsect1>
</refentry>
<refentry id="API-bmap">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bmap</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bmap</refname>
<refpurpose>
find a block number in a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>sector_t <function>bmap </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>sector_t <parameter>block</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode of file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>block</parameter></term>
<listitem>
<para>
block to find
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns the block number on the device holding the inode that
is the disk block number for the block of the file requested.
That is, asked for block 4 of inode 1 the function will return the
disk block relative to the disk start that holds that block of the
file.
</para>
</refsect1>
</refentry>
<refentry id="API-touch-atime">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>touch_atime</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>touch_atime</refname>
<refpurpose>
update the access time
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>touch_atime </function></funcdef>
<paramdef>struct vfsmount * <parameter>mnt</parameter></paramdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>mnt</parameter></term>
<listitem>
<para>
mount the inode is accessed on
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
dentry accessed
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Update the accessed time on an inode and mark it for writeback.
This function automatically handles read only file systems and media,
as well as the <quote>noatime</quote> flag and inode specific <quote>noatime</quote> markers.
</para>
</refsect1>
</refentry>
<refentry id="API-file-update-time">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>file_update_time</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>file_update_time</refname>
<refpurpose>
update mtime and ctime time
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>file_update_time </function></funcdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
file accessed
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Update the mtime and ctime members of an inode and mark the inode
for writeback. Note that this function is meant exclusively for
usage in the file write path of filesystems, and filesystems may
choose to explicitly ignore update via this function with the
S_NOCMTIME inode flag, e.g. for network filesystem where these
timestamps are handled by the server.
</para>
</refsect1>
</refentry>
<!-- fs/bad_inode.c -->
<refentry id="API-make-bad-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>make_bad_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>make_bad_inode</refname>
<refpurpose>
mark an inode bad due to an I/O error
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>make_bad_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
Inode to mark bad
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
When an inode cannot be read due to a media or remote network
failure this function makes the inode <quote>bad</quote> and causes I/O operations
on it to fail from this point on.
</para>
</refsect1>
</refentry>
<refentry id="API-is-bad-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>is_bad_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>is_bad_inode</refname>
<refpurpose>
is an inode errored
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>is_bad_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to test
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns true if the inode in question has been marked as bad.
</para>
</refsect1>
</refentry>
<refentry id="API-iget-failed">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>iget_failed</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iget_failed</refname>
<refpurpose>
Mark an under-construction inode as dead and release it
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>iget_failed </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
The inode to discard
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Mark an under-construction inode as dead and release it.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title>
<!-- fs/super.c -->
<refentry id="API-deactivate-super">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>deactivate_super</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>deactivate_super</refname>
<refpurpose>
drop an active reference to superblock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>deactivate_super </function></funcdef>
<paramdef>struct super_block * <parameter>s</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>s</parameter></term>
<listitem>
<para>
superblock to deactivate
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Drops an active reference to superblock, acquiring a temprory one if
there is no active references left. In that case we lock superblock,
tell fs driver to shut it down and drop the temporary reference we
had just acquired.
</para>
</refsect1>
</refentry>
<refentry id="API-deactivate-locked-super">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>deactivate_locked_super</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>deactivate_locked_super</refname>
<refpurpose>
drop an active reference to superblock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>deactivate_locked_super </function></funcdef>
<paramdef>struct super_block * <parameter>s</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>s</parameter></term>
<listitem>
<para>
superblock to deactivate
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Equivalent of up_write(<structname>s</structname>->s_umount); deactivate_super(s);, except that
it does not unlock it until it's all over. As the result, it's safe to
use to dispose of new superblock on -><function>get_sb</function> failure exits - nobody
will see the sucker until it's all over. Equivalent using up_write +
deactivate_super is safe for that purpose only if superblock is either
safe to use or has NULL ->s_root when we unlock.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-shutdown-super">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_shutdown_super</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_shutdown_super</refname>
<refpurpose>
common helper for -><function>kill_sb</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>generic_shutdown_super </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
superblock to kill
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>generic_shutdown_super</function> does all fs-independent work on superblock
shutdown. Typical -><function>kill_sb</function> should pick all fs-specific objects
that need destruction out of superblock, call <function>generic_shutdown_super</function>
and release aforementioned objects. Note: dentries and inodes _are_
taken care of and do not need specific handling.
</para><para>
Upon calling this function, the filesystem may no longer alter or
rearrange the set of dentries belonging to this super_block, nor may it
change the attachments of dentries to inodes.
</para>
</refsect1>
</refentry>
<refentry id="API-sget">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sget</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sget</refname>
<refpurpose>
find or create a superblock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct super_block * <function>sget </function></funcdef>
<paramdef>struct file_system_type * <parameter>type</parameter></paramdef>
<paramdef>int (*<parameter>test</parameter>)
<funcparams>struct super_block *,void *</funcparams></paramdef>
<paramdef>int (*<parameter>set</parameter>)
<funcparams>struct super_block *,void *</funcparams></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
filesystem type superblock should belong to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>test</parameter></term>
<listitem>
<para>
comparison callback
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>set</parameter></term>
<listitem>
<para>
setup callback
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
argument to each of them
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-get-super">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>get_super</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>get_super</refname>
<refpurpose>
get the superblock of a device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct super_block * <function>get_super </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
device to get the superblock for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Scans the superblock list and finds the superblock of the file system
mounted on the device given. <constant>NULL</constant> is returned if no match is found.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="file_locks"><title>File Locks</title>
<!-- fs/locks.c -->
<refentry id="API-posix-lock-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>posix_lock_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>posix_lock_file</refname>
<refpurpose>
Apply a POSIX-style lock to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>posix_lock_file </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
<paramdef>struct file_lock * <parameter>conflock</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to apply the lock to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to be applied
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>conflock</parameter></term>
<listitem>
<para>
Place to return a copy of the conflicting lock, if found.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Add a POSIX style lock to a file.
We merge adjacent & overlapping locks whenever possible.
POSIX locks are sorted by owner task, then by starting address
</para><para>
Note that if called with an FL_EXISTS argument, the caller may determine
whether or not a lock was successfully freed by testing the return
value for -ENOENT.
</para>
</refsect1>
</refentry>
<refentry id="API-posix-lock-file-wait">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>posix_lock_file_wait</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>posix_lock_file_wait</refname>
<refpurpose>
Apply a POSIX-style lock to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>posix_lock_file_wait </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to apply the lock to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to be applied
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Add a POSIX style lock to a file.
We merge adjacent & overlapping locks whenever possible.
POSIX locks are sorted by owner task, then by starting address
</para>
</refsect1>
</refentry>
<refentry id="API-locks-mandatory-area">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>locks_mandatory_area</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>locks_mandatory_area</refname>
<refpurpose>
Check for a conflicting lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>locks_mandatory_area </function></funcdef>
<paramdef>int <parameter>read_write</parameter></paramdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>loff_t <parameter>offset</parameter></paramdef>
<paramdef>size_t <parameter>count</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>read_write</parameter></term>
<listitem>
<para>
<constant>FLOCK_VERIFY_WRITE</constant> for exclusive access, <constant>FLOCK_VERIFY_READ</constant>
for shared
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the file to check
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
how the file was opened (if it was)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
start of area to check
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
length of area to check
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Searches the inode's list of locks to find any POSIX locks which conflict.
This function is called from <function>rw_verify_area</function> and
<function>locks_verify_truncate</function>.
</para>
</refsect1>
</refentry>
<refentry id="API---break-lease">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__break_lease</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__break_lease</refname>
<refpurpose>
revoke all outstanding leases on file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>__break_lease </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>unsigned int <parameter>mode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode of the file to return
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the open mode (read or write)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
break_lease (inlined for speed) has checked there already is at least
some kind of lock (maybe a lease) on this file. Leases are broken on
a call to <function>open</function> or <function>truncate</function>. This function can sleep unless you
specified <constant>O_NONBLOCK</constant> to your <function>open</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-lease-get-mtime">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lease_get_mtime</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lease_get_mtime</refname>
<refpurpose>
get the last modified time of an inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>lease_get_mtime </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct timespec * <parameter>time</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>time</parameter></term>
<listitem>
<para>
pointer to a timespec which will contain the last modified time
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is to force NFS clients to flush their caches for files with
exclusive leases. The justification is that if someone has an
exclusive lease, then they could be modifying it.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-setlease">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_setlease</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_setlease</refname>
<refpurpose>
sets a lease on an open file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>generic_setlease </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>long <parameter>arg</parameter></paramdef>
<paramdef>struct file_lock ** <parameter>flp</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
file pointer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>arg</parameter></term>
<listitem>
<para>
type of lease to obtain
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flp</parameter></term>
<listitem>
<para>
input - file_lock to use, output - file_lock inserted
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The (input) flp->fl_lmops->fl_break function is required
by <function>break_lease</function>.
</para><para>
Called with kernel lock held.
</para>
</refsect1>
</refentry>
<refentry id="API-flock-lock-file-wait">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>flock_lock_file_wait</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>flock_lock_file_wait</refname>
<refpurpose>
Apply a FLOCK-style lock to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>flock_lock_file_wait </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to apply the lock to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to be applied
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Add a FLOCK style lock to a file.
</para>
</refsect1>
</refentry>
<refentry id="API-vfs-test-lock">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>vfs_test_lock</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vfs_test_lock</refname>
<refpurpose>
test file byte range lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>vfs_test_lock </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to test lock for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to test; also used to hold result
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns -ERRNO on failure. Indicates presence of conflicting lock by
setting conf->fl_type to something other than F_UNLCK.
</para>
</refsect1>
</refentry>
<refentry id="API-vfs-lock-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>vfs_lock_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vfs_lock_file</refname>
<refpurpose>
file byte range lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>vfs_lock_file </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>unsigned int <parameter>cmd</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
<paramdef>struct file_lock * <parameter>conf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to apply the lock to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cmd</parameter></term>
<listitem>
<para>
type of locking operation (F_SETLK, F_GETLK, etc.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to be applied
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>conf</parameter></term>
<listitem>
<para>
Place to return a copy of the conflicting lock, if found.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
A caller that doesn't care about the conflicting lock may pass NULL
as the final argument.
</para><para>
If the filesystem defines a private -><function>lock</function> method, then <parameter>conf</parameter> will
be left unchanged; so a caller that cares should initialize it to
some acceptable default.
</para><para>
To avoid blocking kernel daemons, such as lockd, that need to acquire POSIX
locks, the -><function>lock</function> interface may return asynchronously, before the lock has
been granted or denied by the underlying filesystem, if (and only if)
fl_grant is set. Callers expecting -><function>lock</function> to return asynchronously
will only use F_SETLK, not F_SETLKW; they will set FL_SLEEP if (and only if)
the request is for a blocking lock. When -><function>lock</function> does return asynchronously,
it must return FILE_LOCK_DEFERRED, and call -><function>fl_grant</function> when the lock
request completes.
If the request is for non-blocking lock the file system should return
FILE_LOCK_DEFERRED then try to get the lock and call the callback routine
with the result. If the request timed out the callback routine will return a
nonzero return code and the file system should release the lock. The file
system is also responsible to keep a corresponding posix lock when it
grants a lock so the VFS can find out which locks are locally held and do
the correct lock cleanup when required.
The underlying filesystem must not drop the kernel lock or call
-><function>fl_grant</function> before returning to the caller with a FILE_LOCK_DEFERRED
return code.
</para>
</refsect1>
</refentry>
<refentry id="API-posix-unblock-lock">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>posix_unblock_lock</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>posix_unblock_lock</refname>
<refpurpose>
stop waiting for a file lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>posix_unblock_lock </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>waiter</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
how the file was opened
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>waiter</parameter></term>
<listitem>
<para>
the lock which was waiting
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
lockd needs to block waiting for locks.
</para>
</refsect1>
</refentry>
<refentry id="API-vfs-cancel-lock">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>vfs_cancel_lock</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vfs_cancel_lock</refname>
<refpurpose>
file byte range unblock lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>vfs_cancel_lock </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>struct file_lock * <parameter>fl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
The file to apply the unblock to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fl</parameter></term>
<listitem>
<para>
The lock to be unblocked
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Used by lock managers to cancel blocked requests
</para>
</refsect1>
</refentry>
<refentry id="API-lock-may-read">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lock_may_read</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lock_may_read</refname>
<refpurpose>
checks that the region is free of locks
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>lock_may_read </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>loff_t <parameter>start</parameter></paramdef>
<paramdef>unsigned long <parameter>len</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode that is being read
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
the first byte to read
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
the number of bytes to read
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Emulates Windows locking requirements. Whole-file
mandatory locks (share modes) can prohibit a read and
byte-range POSIX locks can prohibit a read if they overlap.
</para><para>
N.B. this function is only ever called
from knfsd and ownership of locks is never checked.
</para>
</refsect1>
</refentry>
<refentry id="API-lock-may-write">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lock_may_write</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lock_may_write</refname>
<refpurpose>
checks that the region is free of locks
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>lock_may_write </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>loff_t <parameter>start</parameter></paramdef>
<paramdef>unsigned long <parameter>len</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode that is being written
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
the first byte to write
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
the number of bytes to write
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Emulates Windows locking requirements. Whole-file
mandatory locks (share modes) can prohibit a write and
byte-range POSIX locks can prohibit a write if they overlap.
</para><para>
N.B. this function is only ever called
from knfsd and ownership of locks is never checked.
</para>
</refsect1>
</refentry>
<!-- fs/locks.c -->
<refentry id="API-locks-mandatory-locked">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>locks_mandatory_locked</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>locks_mandatory_locked</refname>
<refpurpose>
Check for an active lock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>locks_mandatory_locked </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the file to check
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Searches the inode's list of locks to find any POSIX locks which conflict.
This function is called from <function>locks_verify_locked</function> only.
</para>
</refsect1>
</refentry>
<refentry id="API-fcntl-getlease">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>fcntl_getlease</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>fcntl_getlease</refname>
<refpurpose>
Enquire what lease is currently active
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>fcntl_getlease </function></funcdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
the file
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The value returned by this function will be one of
(if no lease break is pending):
</para><para>
<constant>F_RDLCK</constant> to indicate a shared lease is held.
</para><para>
<constant>F_WRLCK</constant> to indicate an exclusive lease is held.
</para><para>
<constant>F_UNLCK</constant> to indicate no lease is held.
</para><para>
(if a lease break is pending):
</para><para>
<constant>F_RDLCK</constant> to indicate an exclusive lease needs to be
changed to a shared lease (or removed).
</para><para>
<constant>F_UNLCK</constant> to indicate the lease needs to be removed.
</para>
</refsect1>
<refsect1>
<title>XXX</title>
<para>
sfr & willy disagree over whether F_INPROGRESS
should be returned to userspace.
</para>
</refsect1>
</refentry>
<refentry id="API-fcntl-setlease">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>fcntl_setlease</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>fcntl_setlease</refname>
<refpurpose>
sets a lease on an open file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>fcntl_setlease </function></funcdef>
<paramdef>unsigned int <parameter>fd</parameter></paramdef>
<paramdef>struct file * <parameter>filp</parameter></paramdef>
<paramdef>long <parameter>arg</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>
open file descriptor
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>filp</parameter></term>
<listitem>
<para>
file pointer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>arg</parameter></term>
<listitem>
<para>
type of lease to obtain
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Call this fcntl to establish a lease on the file.
Note that you also need to call <constant>F_SETSIG</constant> to
receive a signal when the lease is broken.
</para>
</refsect1>
</refentry>
<refentry id="API-sys-flock">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sys_flock</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sys_flock</refname>
<refpurpose>
<function>flock</function> system call.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>long <function>sys_flock </function></funcdef>
<paramdef>unsigned int <parameter>fd</parameter></paramdef>
<paramdef>unsigned int <parameter>cmd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>
the file descriptor to lock.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cmd</parameter></term>
<listitem>
<para>
the type of lock to apply.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Apply a <constant>FL_FLOCK</constant> style lock to an open file descriptor.
The <parameter>cmd</parameter> can be one of
</para><para>
<constant>LOCK_SH</constant> -- a shared lock.
</para><para>
<constant>LOCK_EX</constant> -- an exclusive lock.
</para><para>
<constant>LOCK_UN</constant> -- remove an existing lock.
</para><para>
<constant>LOCK_MAND</constant> -- a `mandatory' flock. This exists to emulate Windows Share Modes.
</para><para>
<constant>LOCK_MAND</constant> can be combined with <constant>LOCK_READ</constant> or <constant>LOCK_WRITE</constant> to allow other
processes read and write access respectively.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="other_functions"><title>Other Functions</title>
<!-- fs/mpage.c -->
<refentry id="API-mpage-readpages">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>mpage_readpages</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mpage_readpages</refname>
<refpurpose>
populate an address space with some pages & start reads against them
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>mpage_readpages </function></funcdef>
<paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
<paramdef>struct list_head * <parameter>pages</parameter></paramdef>
<paramdef>unsigned <parameter>nr_pages</parameter></paramdef>
<paramdef>get_block_t <parameter>get_block</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>mapping</parameter></term>
<listitem>
<para>
the address_space
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pages</parameter></term>
<listitem>
<para>
The address of a list_head which contains the target pages. These
pages have their ->index populated and are otherwise uninitialised.
The page at <parameter>pages</parameter>->prev has the lowest file offset, and reads should be
issued in <parameter>pages</parameter>->prev to <parameter>pages</parameter>->next order.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nr_pages</parameter></term>
<listitem>
<para>
The number of pages at *<parameter>pages</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>get_block</parameter></term>
<listitem>
<para>
The filesystem's block mapper function.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function walks the pages and the blocks within each page, building and
emitting large BIOs.
</para><para>
If anything unusual happens, such as:
</para><para>
- encountering a page which has buffers
- encountering a page which has a non-hole after a hole
- encountering a page with non-contiguous blocks
</para><para>
then this code just gives up and calls the buffer_head-based read function.
It does handle a page which has holes at the end - that is a common case:
the end-of-file on blocksize < PAGE_CACHE_SIZE setups.
</para>
</refsect1>
<refsect1>
<title>BH_Boundary explanation</title>
<para>
</para><para>
There is a problem. The mpage read code assembles several pages, gets all
their disk mappings, and then submits them all. That's fine, but obtaining
the disk mappings may require I/O. Reads of indirect blocks, for example.
</para><para>
So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be
</para>
</refsect1>
<refsect1>
<title>submitted in the following order</title>
<para>
12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16
</para><para>
because the indirect block has to be read to get the mappings of blocks
13,14,15,16. Obviously, this impacts performance.
</para><para>
So what we do it to allow the filesystem's <function>get_block</function> function to set
BH_Boundary when it maps block 11. BH_Boundary says: mapping of the block
after this one will require I/O against a block which is probably close to
this one. So you should push what I/O you have currently accumulated.
</para><para>
This all causes the disk requests to be issued in the correct order.
</para>
</refsect1>
</refentry>
<refentry id="API-mpage-writepages">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>mpage_writepages</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mpage_writepages</refname>
<refpurpose>
walk the list of dirty pages of the given address space & <function>writepage</function> all of them
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>mpage_writepages </function></funcdef>
<paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
<paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef>
<paramdef>get_block_t <parameter>get_block</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>mapping</parameter></term>
<listitem>
<para>
address space structure to write
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>wbc</parameter></term>
<listitem>
<para>
subtract the number of written pages from *<parameter>wbc</parameter>->nr_to_write
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>get_block</parameter></term>
<listitem>
<para>
the filesystem's block mapper function.
If this is NULL then use a_ops->writepage. Otherwise, go
direct-to-BIO.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is a library function, which implements the <function>writepages</function>
address_space_operation.
</para><para>
If a page is already under I/O, <function>generic_writepages</function> skips it, even
if it's dirty. This is desirable behaviour for memory-cleaning writeback,
but it is INCORRECT for data-integrity system calls such as <function>fsync</function>. <function>fsync</function>
and <function>msync</function> need to guarantee that all the data which was dirty at the time
the call was made get new I/O started against them. If wbc->sync_mode is
WB_SYNC_ALL then we were called for data integrity and we must wait for
existing IO to complete.
</para>
</refsect1>
</refentry>
<!-- fs/namei.c -->
<refentry id="API-generic-permission">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_permission</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_permission</refname>
<refpurpose>
check for access rights on a Posix-like filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>generic_permission </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>int <parameter>mask</parameter></paramdef>
<paramdef>int (*<parameter>check_acl</parameter>)
<funcparams>struct inode *inode, int mask</funcparams></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to check access rights for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mask</parameter></term>
<listitem>
<para>
right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>check_acl</parameter></term>
<listitem>
<para>
optional callback to check for Posix ACLs
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Used to check for read/write/execute permissions on a file.
We use <quote>fsuid</quote> for this, letting us set arbitrary permissions
for filesystem access without changing the <quote>normal</quote> uids which
are used for other things..
</para>
</refsect1>
</refentry>
<refentry id="API-inode-permission">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>inode_permission</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inode_permission</refname>
<refpurpose>
check for access rights to a given inode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>inode_permission </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>int <parameter>mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to check permission on
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mask</parameter></term>
<listitem>
<para>
right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Used to check for read/write/execute permissions on an inode.
We use <quote>fsuid</quote> for this, letting us set arbitrary permissions
for filesystem access without changing the <quote>normal</quote> uids which
are used for other things.
</para>
</refsect1>
</refentry>
<refentry id="API-file-permission">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>file_permission</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>file_permission</refname>
<refpurpose>
check for additional access rights to a given file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>file_permission </function></funcdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
<paramdef>int <parameter>mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
file to check access rights for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mask</parameter></term>
<listitem>
<para>
right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Used to check for read/write/execute permissions on an already opened
file.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
Do not use this function in new code. All access checks should
be done using <function>inode_permission</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-path-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>path_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>path_get</refname>
<refpurpose>
get a reference to a path
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>path_get </function></funcdef>
<paramdef>struct path * <parameter>path</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
path to get the reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given a path increment the reference count to the dentry and the vfsmount.
</para>
</refsect1>
</refentry>
<refentry id="API-path-put">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>path_put</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>path_put</refname>
<refpurpose>
put a reference to a path
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>path_put </function></funcdef>
<paramdef>struct path * <parameter>path</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
path to put the reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given a path decrement the reference count to the dentry and the vfsmount.
</para>
</refsect1>
</refentry>
<refentry id="API-vfs-path-lookup">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>vfs_path_lookup</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vfs_path_lookup</refname>
<refpurpose>
lookup a file path relative to a dentry-vfsmount pair
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>vfs_path_lookup </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
<paramdef>struct vfsmount * <parameter>mnt</parameter></paramdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
<paramdef>struct nameidata * <parameter>nd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
pointer to dentry of the base directory
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mnt</parameter></term>
<listitem>
<para>
pointer to vfs mount of the base directory
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
pointer to file name
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
lookup flags
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nd</parameter></term>
<listitem>
<para>
pointer to nameidata
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-lookup-one-len">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lookup_one_len</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lookup_one_len</refname>
<refpurpose>
filesystem helper to lookup single pathname component
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>lookup_one_len </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>struct dentry * <parameter>base</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
pathname component to lookup
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>base</parameter></term>
<listitem>
<para>
base directory to lookup from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
maximum length <parameter>len</parameter> should be interpreted to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Note that this routine is purely a helper for filesystem usage and should
not be called by generic code. Also note that by using this function the
nameidata argument is passed to the filesystem methods and a filesystem
using this helper needs to be prepared for that.
</para>
</refsect1>
</refentry>
<refentry id="API-filp-open">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>filp_open</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>filp_open</refname>
<refpurpose>
open file and return file pointer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct file * <function>filp_open </function></funcdef>
<paramdef>const char * <parameter>filename</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
path to open
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
open flags as per the open(2) second argument
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
mode for the new file if O_CREAT is set, else ignored
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the helper to open a file from kernelspace if you really
have to. But in generally you should not do this, so please move
along, nothing to see here..
</para>
</refsect1>
</refentry>
<refentry id="API-lookup-create">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lookup_create</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lookup_create</refname>
<refpurpose>
lookup a dentry, creating it if it doesn't exist
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>lookup_create </function></funcdef>
<paramdef>struct nameidata * <parameter>nd</parameter></paramdef>
<paramdef>int <parameter>is_dir</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>nd</parameter></term>
<listitem>
<para>
nameidata info
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>is_dir</parameter></term>
<listitem>
<para>
directory flag
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Simple function to lookup and return a dentry and create it
if it doesn't exist. Is SMP-safe.
</para><para>
Returns with nd->path.dentry->d_inode->i_mutex locked.
</para>
</refsect1>
</refentry>
<!-- fs/buffer.c -->
<refentry id="API-sync-mapping-buffers">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sync_mapping_buffers</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sync_mapping_buffers</refname>
<refpurpose>
write out & wait upon a mapping's <quote>associated</quote> buffers
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sync_mapping_buffers </function></funcdef>
<paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>mapping</parameter></term>
<listitem>
<para>
the mapping which wants those buffers written
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Starts I/O against the buffers at mapping->private_list, and waits upon
that I/O.
</para><para>
Basically, this is a convenience function for <function>fsync</function>.
<parameter>mapping</parameter> is a file or directory which needs those buffers to be written for
a successful <function>fsync</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-mark-buffer-dirty">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>mark_buffer_dirty</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mark_buffer_dirty</refname>
<refpurpose>
mark a buffer_head as needing writeout
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>mark_buffer_dirty </function></funcdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
the buffer_head to mark dirty
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>mark_buffer_dirty</function> will set the dirty bit against the buffer, then set its
backing page dirty, then tag the page as dirty in its address_space's radix
tree and then attach the address_space's inode to its superblock's dirty
inode list.
</para><para>
<function>mark_buffer_dirty</function> is atomic. It takes bh->b_page->mapping->private_lock,
mapping->tree_lock and the global inode_lock.
</para>
</refsect1>
</refentry>
<refentry id="API---bread">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__bread</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__bread</refname>
<refpurpose>
reads a specified block and returns the bh
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct buffer_head * <function>__bread </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>sector_t <parameter>block</parameter></paramdef>
<paramdef>unsigned <parameter>size</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
the block_device to read from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>block</parameter></term>
<listitem>
<para>
number of block
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
size (in bytes) to read
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads a specified block, and returns buffer head that contains it.
It returns NULL if the block was unreadable.
</para>
</refsect1>
</refentry>
<refentry id="API-block-invalidatepage">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>block_invalidatepage</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>block_invalidatepage</refname>
<refpurpose>
invalidate part of all of a buffer-backed page
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>block_invalidatepage </function></funcdef>
<paramdef>struct page * <parameter>page</parameter></paramdef>
<paramdef>unsigned long <parameter>offset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>page</parameter></term>
<listitem>
<para>
the page which is affected
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
the index of the truncation point
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>block_invalidatepage</function> is called when all or part of the page has become
invalidatedby a truncate operation.
</para><para>
<function>block_invalidatepage</function> does not have to release all buffers, but it must
ensure that no dirty buffer is left outside <parameter>offset</parameter> and that no I/O
is underway against any of the blocks which are outside the truncation
point. Because the caller is about to free (and possibly reuse) those
blocks on-disk.
</para>
</refsect1>
</refentry>
<refentry id="API-ll-rw-block">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ll_rw_block</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ll_rw_block</refname>
<refpurpose>
level access to block devices (DEPRECATED)
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ll_rw_block </function></funcdef>
<paramdef>int <parameter>rw</parameter></paramdef>
<paramdef>int <parameter>nr</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bhs[]</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>rw</parameter></term>
<listitem>
<para>
whether to <constant>READ</constant> or <constant>WRITE</constant> or <constant>SWRITE</constant> or maybe <constant>READA</constant> (readahead)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nr</parameter></term>
<listitem>
<para>
number of <structname>struct buffer_heads</structname> in the array
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bhs[]</parameter></term>
<listitem>
<para>
array of pointers to <structname>struct buffer_head</structname>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>ll_rw_block</function> takes an array of pointers to <structname>struct buffer_heads</structname>, and
requests an I/O operation on them, either a <constant>READ</constant> or a <constant>WRITE</constant>. The third
<constant>SWRITE</constant> is like <constant>WRITE</constant> only we make sure that the *current* data in buffers
are sent to disk. The fourth <constant>READA</constant> option is described in the documentation
for <function>generic_make_request</function> which <function>ll_rw_block</function> calls.
</para><para>
This function drops any buffer that it cannot get a lock on (with the
BH_Lock state bit) unless SWRITE is required, any buffer that appears to be
clean when doing a write request, and any buffer that appears to be
up-to-date when doing read request. Further it marks as clean buffers that
are processed for writing (the buffer cache won't assume that they are
actually clean until the buffer gets unlocked).
</para><para>
ll_rw_block sets b_end_io to simple completion handler that marks
the buffer up-to-date (if approriate), unlocks the buffer and wakes
any waiters.
</para><para>
All of the buffers must be for the same device, and must also be a
multiple of the current approved size for the device.
</para>
</refsect1>
</refentry>
<refentry id="API-bh-uptodate-or-lock">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bh_uptodate_or_lock</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bh_uptodate_or_lock</refname>
<refpurpose>
Test whether the buffer is uptodate
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bh_uptodate_or_lock </function></funcdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
struct buffer_head
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return true if the buffer is up-to-date and false,
with the buffer locked, if not.
</para>
</refsect1>
</refentry>
<refentry id="API-bh-submit-read">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bh_submit_read</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bh_submit_read</refname>
<refpurpose>
Submit a locked buffer for reading
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bh_submit_read </function></funcdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
struct buffer_head
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns zero on success and -EIO on error.
</para>
</refsect1>
</refentry>
<!-- fs/bio.c -->
<refentry id="API-bio-alloc-bioset">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_alloc_bioset</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_alloc_bioset</refname>
<refpurpose>
allocate a bio for I/O
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_alloc_bioset </function></funcdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
<paramdef>int <parameter>nr_iovecs</parameter></paramdef>
<paramdef>struct bio_set * <parameter>bs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
the GFP_ mask given to the slab allocator
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nr_iovecs</parameter></term>
<listitem>
<para>
number of iovecs to pre-allocate
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bs</parameter></term>
<listitem>
<para>
the bio_set to allocate from. If <constant>NULL</constant>, just use kmalloc
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
bio_alloc_bioset will first try its own mempool to satisfy the allocation.
If <constant>__GFP_WAIT</constant> is set then we will block on the internal pool waiting
for a <structname>struct bio</structname> to become free. If a <constant>NULL</constant> <parameter>bs</parameter> is passed in, we will
fall back to just using <parameter>kmalloc</parameter> to allocate the required memory.
</para><para>
Note that the caller must set ->bi_destructor on succesful return
of a bio, to do the appropriate freeing of the bio once the reference
count drops to zero.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-alloc">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_alloc</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_alloc</refname>
<refpurpose>
allocate a new bio, memory pool backed
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_alloc </function></funcdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
<paramdef>int <parameter>nr_iovecs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
allocation mask to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nr_iovecs</parameter></term>
<listitem>
<para>
number of iovecs
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
bio_alloc will allocate a bio and associated bio_vec array that can hold
at least <parameter>nr_iovecs</parameter> entries. Allocations will be done from the
fs_bio_set. Also see <parameter>bio_alloc_bioset</parameter> and <parameter>bio_kmalloc</parameter>.
</para><para>
If <constant>__GFP_WAIT</constant> is set, then bio_alloc will always be able to allocate
a bio. This is due to the mempool guarantees. To make this work, callers
must never allocate more than 1 bio at a time from this pool. Callers
that need to allocate more than 1 bio must always submit the previously
allocated bio for IO before attempting to allocate a new one. Failure to
do so can cause livelocks under memory pressure.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
Pointer to new bio on success, NULL on failure.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-kmalloc">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_kmalloc</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_kmalloc</refname>
<refpurpose>
allocate a bio for I/O using <function>kmalloc</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_kmalloc </function></funcdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
<paramdef>int <parameter>nr_iovecs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
the GFP_ mask given to the slab allocator
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nr_iovecs</parameter></term>
<listitem>
<para>
number of iovecs to pre-allocate
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Allocate a new bio with <parameter>nr_iovecs</parameter> bvecs. If <parameter>gfp_mask</parameter> contains
<constant>__GFP_WAIT</constant>, the allocation is guaranteed to succeed.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-put">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_put</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_put</refname>
<refpurpose>
release a reference to a bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>bio_put </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
bio to release reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Put a reference to a <structname>struct bio</structname>, either one you have gotten with
bio_alloc, bio_get or bio_clone. The last put of a bio will free it.
</para>
</refsect1>
</refentry>
<refentry id="API---bio-clone">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__bio_clone</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__bio_clone</refname>
<refpurpose>
clone a bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>__bio_clone </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>struct bio * <parameter>bio_src</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
destination bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bio_src</parameter></term>
<listitem>
<para>
bio to clone
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Clone a <structname>bio</structname>. Caller will own the returned bio, but not
the actual data it points to. Reference count of returned
bio will be one.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-clone">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_clone</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_clone</refname>
<refpurpose>
clone a bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_clone </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
bio to clone
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
allocation priority
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Like __bio_clone, only also allocates the returned bio
</para>
</refsect1>
</refentry>
<refentry id="API-bio-get-nr-vecs">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_get_nr_vecs</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_get_nr_vecs</refname>
<refpurpose>
return approx number of vecs
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bio_get_nr_vecs </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
I/O target
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return the approximate number of pages we can send to this target.
There's no guarantee that you will be able to fit this number of pages
into a bio, it does not account for dynamic restrictions that vary
on offset.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-add-pc-page">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_add_pc_page</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_add_pc_page</refname>
<refpurpose>
attempt to add page to bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bio_add_pc_page </function></funcdef>
<paramdef>struct request_queue * <parameter>q</parameter></paramdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>struct page * <parameter>page</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>offset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>q</parameter></term>
<listitem>
<para>
the target queue
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
destination bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>page</parameter></term>
<listitem>
<para>
page to add
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
vec entry length
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
vec entry offset
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Attempt to add a page to the bio_vec maplist. This can fail for a
number of reasons, such as the bio being full or target block
device limitations. The target block device must allow bio's
smaller than PAGE_SIZE, so it is always possible to add a single
page to an empty bio. This should only be used by REQ_PC bios.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-add-page">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_add_page</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_add_page</refname>
<refpurpose>
attempt to add page to bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bio_add_page </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>struct page * <parameter>page</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>offset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
destination bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>page</parameter></term>
<listitem>
<para>
page to add
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
vec entry length
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
vec entry offset
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Attempt to add a page to the bio_vec maplist. This can fail for a
number of reasons, such as the bio being full or target block
device limitations. The target block device must allow bio's
smaller than PAGE_SIZE, so it is always possible to add a single
page to an empty bio.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-uncopy-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_uncopy_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_uncopy_user</refname>
<refpurpose>
finish previously mapped bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bio_uncopy_user </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
bio being terminated
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Free pages allocated from <function>bio_copy_user</function> and write back data
to user space in case of a read.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-copy-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_copy_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_copy_user</refname>
<refpurpose>
copy user data to bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_copy_user </function></funcdef>
<paramdef>struct request_queue * <parameter>q</parameter></paramdef>
<paramdef>struct rq_map_data * <parameter>map_data</parameter></paramdef>
<paramdef>unsigned long <parameter>uaddr</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>int <parameter>write_to_vm</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>q</parameter></term>
<listitem>
<para>
destination block queue
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>map_data</parameter></term>
<listitem>
<para>
pointer to the rq_map_data holding pages (if necessary)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>uaddr</parameter></term>
<listitem>
<para>
start of user address
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
length in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write_to_vm</parameter></term>
<listitem>
<para>
bool indicating writing to pages or not
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
memory allocation flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Prepares and returns a bio for indirect user io, bouncing data
to/from kernel pages as necessary. Must be paired with
call <function>bio_uncopy_user</function> on io completion.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-map-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_map_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_map_user</refname>
<refpurpose>
map user address into bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_map_user </function></funcdef>
<paramdef>struct request_queue * <parameter>q</parameter></paramdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>unsigned long <parameter>uaddr</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>int <parameter>write_to_vm</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>q</parameter></term>
<listitem>
<para>
the struct request_queue for the bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
destination block device
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>uaddr</parameter></term>
<listitem>
<para>
start of user address
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
length in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write_to_vm</parameter></term>
<listitem>
<para>
bool indicating writing to pages or not
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
memory allocation flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Map the user space address into a bio suitable for io to a block
device. Returns an error pointer in case of error.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-unmap-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_unmap_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_unmap_user</refname>
<refpurpose>
unmap a bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>bio_unmap_user </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
the bio being unmapped
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Unmap a bio previously mapped by <function>bio_map_user</function>. Must be called with
a process context.
</para><para>
<function>bio_unmap_user</function> may sleep.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-map-kern">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_map_kern</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_map_kern</refname>
<refpurpose>
map kernel address into bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_map_kern </function></funcdef>
<paramdef>struct request_queue * <parameter>q</parameter></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>q</parameter></term>
<listitem>
<para>
the struct request_queue for the bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
pointer to buffer to map
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
length in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
allocation flags for bio allocation
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Map the kernel address into a bio suitable for io to a block
device. Returns an error pointer in case of error.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-copy-kern">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_copy_kern</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_copy_kern</refname>
<refpurpose>
copy kernel address into bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio * <function>bio_copy_kern </function></funcdef>
<paramdef>struct request_queue * <parameter>q</parameter></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
<paramdef>unsigned int <parameter>len</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
<paramdef>int <parameter>reading</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>q</parameter></term>
<listitem>
<para>
the struct request_queue for the bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
pointer to buffer to copy
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
length in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
allocation flags for bio and page allocation
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>reading</parameter></term>
<listitem>
<para>
data direction is READ
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
copy the kernel address into a bio suitable for io to a block
device. Returns an error pointer in case of error.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-endio">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_endio</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_endio</refname>
<refpurpose>
end I/O on a bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>bio_endio </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>int <parameter>error</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
bio
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>error</parameter></term>
<listitem>
<para>
error, if any
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>bio_endio</function> will end I/O on the whole bio. <function>bio_endio</function> is the
preferred way to end I/O on a bio, it takes care of clearing
BIO_UPTODATE on error. <parameter>error</parameter> is 0 on success, and and one of the
established -Exxxx (-EIO, for instance) error values in case
something went wrong. Noone should call <function>bi_end_io</function> directly on a
bio unless they own it and thus know that it has an end_io
function.
</para>
</refsect1>
</refentry>
<refentry id="API-bio-sector-offset">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bio_sector_offset</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bio_sector_offset</refname>
<refpurpose>
Find hardware sector offset in bio
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>sector_t <function>bio_sector_offset </function></funcdef>
<paramdef>struct bio * <parameter>bio</parameter></paramdef>
<paramdef>unsigned short <parameter>index</parameter></paramdef>
<paramdef>unsigned int <parameter>offset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bio</parameter></term>
<listitem>
<para>
bio to inspect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>index</parameter></term>
<listitem>
<para>
bio_vec index
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
offset in bv_page
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return the number of hardware sectors between beginning of bio
and an end point indicated by a bio_vec index and an offset
within that vector's page.
</para>
</refsect1>
</refentry>
<refentry id="API-bioset-create">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bioset_create</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bioset_create</refname>
<refpurpose>
Create a bio_set
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct bio_set * <function>bioset_create </function></funcdef>
<paramdef>unsigned int <parameter>pool_size</parameter></paramdef>
<paramdef>unsigned int <parameter>front_pad</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pool_size</parameter></term>
<listitem>
<para>
Number of bio and bio_vecs to cache in the mempool
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>front_pad</parameter></term>
<listitem>
<para>
Number of bytes to allocate in front of the returned bio
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Set up a bio_set to be used with <parameter>bio_alloc_bioset</parameter>. Allows the caller
to ask for a number of bytes to be allocated in front of the bio.
Front pad allocation is useful for embedding the bio inside
another structure, to avoid allocating extra data to go with the bio.
Note that the bio must be embedded at the END of that structure always,
or things will break badly.
</para>
</refsect1>
</refentry>
<!-- fs/seq_file.c -->
<refentry id="API-seq-open">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_open</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_open</refname>
<refpurpose>
initialize sequential file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>seq_open </function></funcdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
<paramdef>const struct seq_operations * <parameter>op</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
file we initialize
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>op</parameter></term>
<listitem>
<para>
method table describing the sequence
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>seq_open</function> sets <parameter>file</parameter>, associating it with a sequence described
by <parameter>op</parameter>. <parameter>op</parameter>-><function>start</function> sets the iterator up and returns the first
element of sequence. <parameter>op</parameter>-><function>stop</function> shuts it down. <parameter>op</parameter>-><function>next</function>
returns the next element of sequence. <parameter>op</parameter>-><function>show</function> prints element
into the buffer. In case of error -><function>start</function> and -><function>next</function> return
ERR_PTR(error). In the end of sequence they return <constant>NULL</constant>. -><function>show</function>
returns 0 in case of success and negative number in case of error.
Returning SEQ_SKIP means <quote>discard this element and move on</quote>.
</para>
</refsect1>
</refentry>
<refentry id="API-seq-read">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_read</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_read</refname>
<refpurpose>
-><function>read</function> method for sequential files.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>seq_read </function></funcdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
<paramdef>char __user * <parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
the file to read from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer to read to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
the maximum number of bytes to read
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
the current position in the file
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Ready-made ->f_op-><function>read</function>
</para>
</refsect1>
</refentry>
<refentry id="API-seq-lseek">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_lseek</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_lseek</refname>
<refpurpose>
-><function>llseek</function> method for sequential files.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>loff_t <function>seq_lseek </function></funcdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
<paramdef>loff_t <parameter>offset</parameter></paramdef>
<paramdef>int <parameter>origin</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
the file in question
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
new position
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>origin</parameter></term>
<listitem>
<para>
0 for absolute, 1 for relative position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Ready-made ->f_op-><function>llseek</function>
</para>
</refsect1>
</refentry>
<refentry id="API-seq-release">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_release</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_release</refname>
<refpurpose>
free the structures associated with sequential file.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>seq_release </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct file * <parameter>file</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
file->f_path.dentry->d_inode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem>
<para>
file in question
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Frees the structures associated with sequential file; can be used
as ->f_op-><function>release</function> if you don't have private data to destroy.
</para>
</refsect1>
</refentry>
<refentry id="API-seq-escape">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_escape</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_escape</refname>
<refpurpose>
print string into buffer, escaping some characters
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>seq_escape </function></funcdef>
<paramdef>struct seq_file * <parameter>m</parameter></paramdef>
<paramdef>const char * <parameter>s</parameter></paramdef>
<paramdef>const char * <parameter>esc</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>m</parameter></term>
<listitem>
<para>
target buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>s</parameter></term>
<listitem>
<para>
string
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>esc</parameter></term>
<listitem>
<para>
set of characters that need escaping
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Puts string into buffer, replacing each occurrence of character from
<parameter>esc</parameter> with usual octal escape. Returns 0 in case of success, -1 - in
case of overflow.
</para>
</refsect1>
</refentry>
<refentry id="API-mangle-path">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>mangle_path</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mangle_path</refname>
<refpurpose>
mangle and copy path to buffer beginning
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>mangle_path </function></funcdef>
<paramdef>char * <parameter>s</parameter></paramdef>
<paramdef>char * <parameter>p</parameter></paramdef>
<paramdef>char * <parameter>esc</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>s</parameter></term>
<listitem>
<para>
buffer start
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>p</parameter></term>
<listitem>
<para>
beginning of path in above buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>esc</parameter></term>
<listitem>
<para>
set of characters that need escaping
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Copy the path from <parameter>p</parameter> to <parameter>s</parameter>, replacing each occurrence of character from
<parameter>esc</parameter> with usual octal escape.
Returns pointer past last written character in <parameter>s</parameter>, or NULL in case of
failure.
</para>
</refsect1>
</refentry>
<refentry id="API-seq-path">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_path</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_path</refname>
<refpurpose>
seq_file interface to print a pathname
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>seq_path </function></funcdef>
<paramdef>struct seq_file * <parameter>m</parameter></paramdef>
<paramdef>struct path * <parameter>path</parameter></paramdef>
<paramdef>char * <parameter>esc</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>m</parameter></term>
<listitem>
<para>
the seq_file handle
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
the struct path to print
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>esc</parameter></term>
<listitem>
<para>
set of characters to escape in the output
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
return the absolute path of 'path', as represented by the
dentry / mnt pair in the path parameter.
</para>
</refsect1>
</refentry>
<refentry id="API-seq-write">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>seq_write</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>seq_write</refname>
<refpurpose>
write arbitrary data to buffer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>seq_write </function></funcdef>
<paramdef>struct seq_file * <parameter>seq</parameter></paramdef>
<paramdef>const void * <parameter>data</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>seq</parameter></term>
<listitem>
<para>
seq_file identifying the buffer to which data should be written
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
data address
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
number of bytes
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return 0 on success, non-zero otherwise.
</para>
</refsect1>
</refentry>
<!-- fs/filesystems.c -->
<refentry id="API-register-filesystem">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>register_filesystem</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>register_filesystem</refname>
<refpurpose>
register a new filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>register_filesystem </function></funcdef>
<paramdef>struct file_system_type * <parameter>fs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fs</parameter></term>
<listitem>
<para>
the file system structure
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Adds the file system passed to the list of file systems the kernel
is aware of for mount and other syscalls. Returns 0 on success,
or a negative errno code on an error.
</para><para>
The <structname>struct file_system_type</structname> that is passed is linked into the kernel
structures and must not be freed until the file system has been
unregistered.
</para>
</refsect1>
</refentry>
<refentry id="API-unregister-filesystem">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>unregister_filesystem</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>unregister_filesystem</refname>
<refpurpose>
unregister a file system
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>unregister_filesystem </function></funcdef>
<paramdef>struct file_system_type * <parameter>fs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fs</parameter></term>
<listitem>
<para>
filesystem to unregister
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Remove a file system that was previously successfully registered
with the kernel. An error is returned if the file system is not found.
Zero is returned on a success.
</para><para>
Once this function has returned the <structname>struct file_system_type</structname> structure
may be freed or reused.
</para>
</refsect1>
</refentry>
<!-- fs/fs-writeback.c -->
<refentry id="API---mark-inode-dirty">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__mark_inode_dirty</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__mark_inode_dirty</refname>
<refpurpose>
internal function
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>__mark_inode_dirty </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to mark
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
what kind of dirty (i.e. I_DIRTY_SYNC)
Mark an inode as dirty. Callers should use mark_inode_dirty or
mark_inode_dirty_sync.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Put the inode on the super block's dirty list.
</para><para>
CAREFUL! We mark it dirty unconditionally, but move it onto the
dirty list only if it is hashed or if it refers to a blockdev.
If it was not hashed, it will never be added to the dirty list
even if it is later hashed, as it will have been marked dirty already.
</para><para>
In short, make sure you hash any inodes _before_ you start marking
them dirty.
</para><para>
This function *must* be atomic for the I_DIRTY_PAGES case -
<function>set_page_dirty</function> is called under spinlock in several places.
</para><para>
Note that for blockdevs, inode->dirtied_when represents the dirtying time of
the block-special inode (/dev/hda1) itself. And the ->dirtied_when field of
the kernel-internal blockdev inode represents the dirtying time of the
blockdev's pages. This is why for I_DIRTY_PAGES we always use
page->mapping->host, so the page-dirtying time is recorded in the internal
blockdev inode.
</para>
</refsect1>
</refentry>
<refentry id="API-writeback-inodes-sb">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>writeback_inodes_sb</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>writeback_inodes_sb</refname>
<refpurpose>
writeback dirty inodes from given super_block
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>writeback_inodes_sb </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
the superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Start writeback on some inodes on this super_block. No guarantees are made
on how many (if any) will be written, and this function does not wait
for IO completion of submitted IO. The number of pages submitted is
returned.
</para>
</refsect1>
</refentry>
<refentry id="API-writeback-inodes-sb-if-idle">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>writeback_inodes_sb_if_idle</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>writeback_inodes_sb_if_idle</refname>
<refpurpose>
start writeback if none underway
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>writeback_inodes_sb_if_idle </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
the superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Invoke writeback_inodes_sb if no writeback is currently underway.
Returns 1 if writeback was started, 0 if not.
</para>
</refsect1>
</refentry>
<refentry id="API-sync-inodes-sb">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sync_inodes_sb</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sync_inodes_sb</refname>
<refpurpose>
sync sb inode pages
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>sync_inodes_sb </function></funcdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
the superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function writes and waits on any dirty inode belonging to this
super_block. The number of pages synced is returned.
</para>
</refsect1>
</refentry>
<refentry id="API-write-inode-now">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>write_inode_now</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>write_inode_now</refname>
<refpurpose>
write an inode to disk
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>write_inode_now </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>int <parameter>sync</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
inode to write to disk
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sync</parameter></term>
<listitem>
<para>
whether the write should be synchronous or not
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function commits an inode to disk immediately if it is dirty. This is
primarily needed by knfsd.
</para><para>
The caller must either have a ref on the inode or must have set I_WILL_FREE.
</para>
</refsect1>
</refentry>
<refentry id="API-sync-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sync_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sync_inode</refname>
<refpurpose>
write an inode and its pages to disk.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sync_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
<paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
the inode to sync
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>wbc</parameter></term>
<listitem>
<para>
controls the writeback mode
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>sync_inode</function> will write an inode and its pages to disk. It will also
correctly update the inode on its superblock's dirty inode lists and will
update inode->i_state.
</para><para>
The caller must have a ref on the inode.
</para>
</refsect1>
</refentry>
<!-- fs/block_dev.c -->
<refentry id="API-freeze-bdev">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>freeze_bdev</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>freeze_bdev</refname>
<refpurpose>
- lock a filesystem and force it into a consistent state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct super_block * <function>freeze_bdev </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
blockdevice to lock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If a superblock is found on this device, we take the s_umount semaphore
on it to make sure nobody unmounts until the snapshot creation is done.
The reference counter (bd_fsfreeze_count) guarantees that only the last
unfreeze process can unfreeze the frozen filesystem actually when multiple
freeze requests arrive simultaneously. It counts up in <function>freeze_bdev</function> and
count down in <function>thaw_bdev</function>. When it becomes 0, <function>thaw_bdev</function> will unfreeze
actually.
</para>
</refsect1>
</refentry>
<refentry id="API-thaw-bdev">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>thaw_bdev</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>thaw_bdev</refname>
<refpurpose>
- unlock filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>thaw_bdev </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>struct super_block * <parameter>sb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
blockdevice to unlock
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sb</parameter></term>
<listitem>
<para>
associated superblock
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Unlocks the filesystem and marks it writeable again after <function>freeze_bdev</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-bd-claim-by-disk">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bd_claim_by_disk</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bd_claim_by_disk</refname>
<refpurpose>
wrapper function for <function>bd_claim_by_kobject</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>bd_claim_by_disk </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>void * <parameter>holder</parameter></paramdef>
<paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
block device to be claimed
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>holder</parameter></term>
<listitem>
<para>
holder's signature
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>disk</parameter></term>
<listitem>
<para>
holder's gendisk
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Call <function>bd_claim_by_kobject</function> with getting <parameter>disk</parameter>->slave_dir.
</para>
</refsect1>
</refentry>
<refentry id="API-bd-release-from-disk">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>bd_release_from_disk</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>bd_release_from_disk</refname>
<refpurpose>
wrapper function for <function>bd_release_from_kobject</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>bd_release_from_disk </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
block device to be claimed
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>disk</parameter></term>
<listitem>
<para>
holder's gendisk
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Call <function>bd_release_from_kobject</function> and put <parameter>disk</parameter>->slave_dir.
</para>
</refsect1>
</refentry>
<refentry id="API-check-disk-size-change">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>check_disk_size_change</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>check_disk_size_change</refname>
<refpurpose>
checks for disk size change and adjusts bdev size.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>check_disk_size_change </function></funcdef>
<paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>disk</parameter></term>
<listitem>
<para>
struct gendisk to check
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
struct bdev to adjust.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This routine checks to see if the bdev size does not match the disk size
and adjusts it if it differs.
</para>
</refsect1>
</refentry>
<refentry id="API-revalidate-disk">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>revalidate_disk</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>revalidate_disk</refname>
<refpurpose>
wrapper for lower-level driver's revalidate_disk call-back
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>revalidate_disk </function></funcdef>
<paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>disk</parameter></term>
<listitem>
<para>
struct gendisk to be revalidated
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This routine is a wrapper for lower-level driver's revalidate_disk
call-backs. It is used to do common pre and post operations needed
for all revalidate_disk operations.
</para>
</refsect1>
</refentry>
<refentry id="API-lookup-bdev">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>lookup_bdev</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lookup_bdev</refname>
<refpurpose>
lookup a struct block_device by name
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct block_device * <function>lookup_bdev </function></funcdef>
<paramdef>const char * <parameter>pathname</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pathname</parameter></term>
<listitem>
<para>
special file representing the block device
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Get a reference to the blockdevice at <parameter>pathname</parameter> in the current
namespace if possible and return it. Return ERR_PTR(error)
otherwise.
</para>
</refsect1>
</refentry>
<refentry id="API-open-bdev-exclusive">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>open_bdev_exclusive</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>open_bdev_exclusive</refname>
<refpurpose>
open a block device by name and set it up for use
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct block_device * <function>open_bdev_exclusive </function></funcdef>
<paramdef>const char * <parameter>path</parameter></paramdef>
<paramdef>fmode_t <parameter>mode</parameter></paramdef>
<paramdef>void * <parameter>holder</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
special file representing the block device
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
FMODE_... combination to pass be used
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>holder</parameter></term>
<listitem>
<para>
owner for exclusion
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Open the blockdevice described by the special file at <parameter>path</parameter>, claim it
for the <parameter>holder</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="API-close-bdev-exclusive">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>close_bdev_exclusive</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>close_bdev_exclusive</refname>
<refpurpose>
close a blockdevice opened by <function>open_bdev_exclusive</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>close_bdev_exclusive </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>fmode_t <parameter>mode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
blockdevice to close
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
mode, must match that used to open.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the counterpart to <function>open_bdev_exclusive</function>.
</para>
</refsect1>
</refentry>
</sect1>
</chapter>
<chapter id="proc">
<title>The proc filesystem</title>
<sect1 id="sysctl_interface"><title>sysctl interface</title>
<!-- kernel/sysctl.c -->
<refentry id="API-register-sysctl-paths">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>register_sysctl_paths</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>register_sysctl_paths</refname>
<refpurpose>
register a sysctl table hierarchy
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct ctl_table_header * <function>register_sysctl_paths </function></funcdef>
<paramdef>const struct ctl_path * <parameter>path</parameter></paramdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
The path to the directory the sysctl table is in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the top-level table structure
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Register a sysctl table hierarchy. <parameter>table</parameter> should be a filled in ctl_table
array. A completely 0 filled entry terminates the table.
</para><para>
See __register_sysctl_paths for more details.
</para>
</refsect1>
</refentry>
<refentry id="API-register-sysctl-table">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>register_sysctl_table</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>register_sysctl_table</refname>
<refpurpose>
register a sysctl table hierarchy
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct ctl_table_header * <function>register_sysctl_table </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the top-level table structure
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Register a sysctl table hierarchy. <parameter>table</parameter> should be a filled in ctl_table
array. A completely 0 filled entry terminates the table.
</para><para>
See register_sysctl_paths for more details.
</para>
</refsect1>
</refentry>
<refentry id="API-unregister-sysctl-table">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>unregister_sysctl_table</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>unregister_sysctl_table</refname>
<refpurpose>
unregister a sysctl table hierarchy
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>unregister_sysctl_table </function></funcdef>
<paramdef>struct ctl_table_header * <parameter>header</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>header</parameter></term>
<listitem>
<para>
the header returned from register_sysctl_table
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Unregisters the sysctl table and all children. proc entries may not
actually be removed until they are no longer used by anyone.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dostring">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dostring</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dostring</refname>
<refpurpose>
read a string sysctl
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dostring </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes a string from/to the user buffer. If the kernel
buffer provided is not large enough to hold the string, the
string is truncated. The copied string is <constant>NULL-terminated</constant>.
If the string is being read by the user process, it is copied
and a newline '\n' is added. It is truncated if the buffer is
not large enough.
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dointvec">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dointvec</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dointvec</refname>
<refpurpose>
read a vector of integers
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dointvec </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned int) integer
values from/to the user buffer, treated as an ASCII string.
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dointvec-minmax">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dointvec_minmax</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dointvec_minmax</refname>
<refpurpose>
read a vector of integers with min/max values
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dointvec_minmax </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned int) integer
values from/to the user buffer, treated as an ASCII string.
</para><para>
This routine will ensure the values are within the range specified by
table->extra1 (min) and table->extra2 (max).
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-doulongvec-minmax">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_doulongvec_minmax</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_doulongvec_minmax</refname>
<refpurpose>
read a vector of long integers with min/max values
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_doulongvec_minmax </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long
values from/to the user buffer, treated as an ASCII string.
</para><para>
This routine will ensure the values are within the range specified by
table->extra1 (min) and table->extra2 (max).
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-doulongvec-ms-jiffies-minmax">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_doulongvec_ms_jiffies_minmax</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_doulongvec_ms_jiffies_minmax</refname>
<refpurpose>
read a vector of millisecond values with min/max values
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_doulongvec_ms_jiffies_minmax </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long
values from/to the user buffer, treated as an ASCII string. The values
are treated as milliseconds, and converted to jiffies when they are stored.
</para><para>
This routine will ensure the values are within the range specified by
table->extra1 (min) and table->extra2 (max).
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dointvec-jiffies">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dointvec_jiffies</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dointvec_jiffies</refname>
<refpurpose>
read a vector of integers as seconds
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dointvec_jiffies </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned int) integer
values from/to the user buffer, treated as an ASCII string.
The values read are assumed to be in seconds, and are converted into
jiffies.
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dointvec-userhz-jiffies">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dointvec_userhz_jiffies</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dointvec_userhz_jiffies</refname>
<refpurpose>
read a vector of integers as 1/USER_HZ seconds
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dointvec_userhz_jiffies </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
pointer to the file position
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned int) integer
values from/to the user buffer, treated as an ASCII string.
The values read are assumed to be in 1/USER_HZ seconds, and
are converted into jiffies.
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-proc-dointvec-ms-jiffies">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_dointvec_ms_jiffies</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_dointvec_ms_jiffies</refname>
<refpurpose>
read a vector of integers as 1 milliseconds
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>proc_dointvec_ms_jiffies </function></funcdef>
<paramdef>struct ctl_table * <parameter>table</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
<paramdef>void __user * <parameter>buffer</parameter></paramdef>
<paramdef>size_t * <parameter>lenp</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>table</parameter></term>
<listitem>
<para>
the sysctl table
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
<constant>TRUE</constant> if this is a write to the sysctl file
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lenp</parameter></term>
<listitem>
<para>
the size of the user buffer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
the current position in the file
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reads/writes up to table->maxlen/sizeof(unsigned int) integer
values from/to the user buffer, treated as an ASCII string.
The values read are assumed to be in 1/1000 seconds, and
are converted into jiffies.
</para><para>
Returns 0 on success.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title>
<!-- fs/proc/base.c -->
<refentry id="API-proc-flush-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>proc_flush_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>proc_flush_task</refname>
<refpurpose>
Remove dcache entries for <parameter>task</parameter> from the /proc dcache.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>proc_flush_task </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task that should be flushed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
When flushing dentries from proc, one needs to flush them from global
proc (proc_mnt) and from all the namespaces' procs this task was seen
in. This call is supposed to do all of this job.
</para><para>
Looks in the dcache for
/proc/<parameter>pid</parameter>
/proc/<parameter>tgid</parameter>/task/<parameter>pid</parameter>
if either directory is present flushes it and all of it'ts children
from the dcache.
</para><para>
It is safe and reasonable to cache /proc entries for a task until
that task exits. After that they just clog up the dcache with
useless entries, possibly causing useful dcache entries to be
flushed instead. This routine is proved to flush those useless
dcache entries at process exit time.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
This routine is just an optimization so it does not guarantee
that no dcache entries will exist at process exit time it
just makes it very unlikely that any will persist.
</para>
</refsect1>
</refentry>
</sect1>
</chapter>
<chapter id="sysfs">
<title>The Filesystem for Exporting Kernel Objects</title>
<!-- fs/sysfs/file.c -->
<refentry id="API-sysfs-create-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_create_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_create_file</refname>
<refpurpose>
create an attribute file for an object.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_create_file </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>const struct attribute * <parameter>attr</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're creating for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-add-file-to-group">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_add_file_to_group</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_add_file_to_group</refname>
<refpurpose>
add an attribute file to a pre-existing group.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_add_file_to_group </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>const struct attribute * <parameter>attr</parameter></paramdef>
<paramdef>const char * <parameter>group</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group</parameter></term>
<listitem>
<para>
group name.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-chmod-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_chmod_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_chmod_file</refname>
<refpurpose>
update the modified mode value on an object attribute.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_chmod_file </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>struct attribute * <parameter>attr</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
file permissions.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-remove-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_remove_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_remove_file</refname>
<refpurpose>
remove an object attribute.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>sysfs_remove_file </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>const struct attribute * <parameter>attr</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Hash the attribute name and kill the victim.
</para>
</refsect1>
</refentry>
<refentry id="API-sysfs-remove-file-from-group">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_remove_file_from_group</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_remove_file_from_group</refname>
<refpurpose>
remove an attribute file from a group.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>sysfs_remove_file_from_group </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>const struct attribute * <parameter>attr</parameter></paramdef>
<paramdef>const char * <parameter>group</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group</parameter></term>
<listitem>
<para>
group name.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-schedule-callback">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_schedule_callback</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_schedule_callback</refname>
<refpurpose>
helper to schedule a callback for a kobject
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_schedule_callback </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>void (*<parameter>func</parameter>)
<funcparams>void *</funcparams></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
<paramdef>struct module * <parameter>owner</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>func</parameter></term>
<listitem>
<para>
callback function to invoke later.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
argument to pass to <parameter>func</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>owner</parameter></term>
<listitem>
<para>
module owning the callback code
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
sysfs attribute methods must not unregister themselves or their parent
kobject (which would amount to the same thing). Attempts to do so will
deadlock, since unregistration is mutually exclusive with driver
callbacks.
</para><para>
Instead methods can call this routine, which will attempt to allocate
and schedule a workqueue request to call back <parameter>func</parameter> with <parameter>data</parameter> as its
argument in the workqueue's process context. <parameter>kobj</parameter> will be pinned
until <parameter>func</parameter> returns.
</para><para>
Returns 0 if the request was submitted, -ENOMEM if storage could not
be allocated, -ENODEV if a reference to <parameter>owner</parameter> isn't available,
-EAGAIN if a callback has already been scheduled for <parameter>kobj</parameter>.
</para>
</refsect1>
</refentry>
<!-- fs/sysfs/symlink.c -->
<refentry id="API-sysfs-create-link">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_create_link</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_create_link</refname>
<refpurpose>
create symlink between two objects.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_create_link </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>struct kobject * <parameter>target</parameter></paramdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object whose directory we're creating the link in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
object we're pointing to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
name of the symlink.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-remove-link">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_remove_link</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_remove_link</refname>
<refpurpose>
remove symlink in object's directory.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>sysfs_remove_link </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object we're acting for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
name of the symlink to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!-- fs/sysfs/bin.c -->
<refentry id="API-sysfs-create-bin-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_create_bin_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_create_bin_file</refname>
<refpurpose>
create binary file for object.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>sysfs_create_bin_file </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>struct bin_attribute * <parameter>attr</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-sysfs-remove-bin-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>sysfs_remove_bin_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sysfs_remove_bin_file</refname>
<refpurpose>
remove binary file for object.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>sysfs_remove_bin_file </function></funcdef>
<paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
<paramdef>struct bin_attribute * <parameter>attr</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>kobj</parameter></term>
<listitem>
<para>
object.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attr</parameter></term>
<listitem>
<para>
attribute descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</chapter>
<chapter id="debugfs">
<title>The debugfs filesystem</title>
<sect1 id="debugfs_interface"><title>debugfs interface</title>
<!-- fs/debugfs/inode.c -->
<refentry id="API-debugfs-create-file">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_file</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_file</refname>
<refpurpose>
create a file in the debugfs filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_file </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
<paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this paramater is NULL, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
a pointer to something that the caller will want to get to later
on. The inode.i_private pointer will point to this value on
the <function>open</function> call.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fops</parameter></term>
<listitem>
<para>
a pointer to a struct file_operations that should be used for
this file.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the basic <quote>create a file</quote> function for debugfs. It allows for a
wide range of flexibility in createing a file, or a directory (if you
want to create a directory, the <function>debugfs_create_dir</function> function is
recommended to be used instead.)
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-dir">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_dir</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_dir</refname>
<refpurpose>
create a directory in the debugfs filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_dir </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the directory to
create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this paramater is NULL, then the
directory will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a directory in debugfs with the given name.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-symlink">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_symlink</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_symlink</refname>
<refpurpose>
create a symbolic link in the debugfs filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_symlink </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>const char * <parameter>target</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the symbolic link to
create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this symbolic link. This
should be a directory dentry if set. If this paramater is NULL,
then the symbolic link will be created in the root of the debugfs
filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
a pointer to a string containing the path to the target of the
symbolic link.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a symbolic link with the given name in debugfs that
links to the given target path.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the symbolic
link is to be removed (no automatic cleanup happens if your module is
unloaded, you are responsible here.) If an error occurs, <constant>NULL</constant> will be
returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-remove">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_remove</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_remove</refname>
<refpurpose>
removes a file or directory from the debugfs filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>debugfs_remove </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
a pointer to a the dentry of the file or directory to be
removed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function removes a file or directory in debugfs that was previously
created with a call to another debugfs function (like
<function>debugfs_create_file</function> or variants thereof.)
</para><para>
This function is required to be called in order for the file to be
removed, no automatic cleanup of files will happen when a module is
removed, you are responsible here.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-remove-recursive">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_remove_recursive</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_remove_recursive</refname>
<refpurpose>
recursively removes a directory
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>debugfs_remove_recursive </function></funcdef>
<paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>dentry</parameter></term>
<listitem>
<para>
a pointer to a the dentry of the directory to be removed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function recursively removes a directory tree in debugfs that
was previously created with a call to another debugfs function
(like <function>debugfs_create_file</function> or variants thereof.)
</para><para>
This function is required to be called in order for the file to be
removed, no automatic cleanup of files will happen when a module is
removed, you are responsible here.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-rename">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_rename</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_rename</refname>
<refpurpose>
rename a file/directory in the debugfs filesystem
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_rename </function></funcdef>
<paramdef>struct dentry * <parameter>old_dir</parameter></paramdef>
<paramdef>struct dentry * <parameter>old_dentry</parameter></paramdef>
<paramdef>struct dentry * <parameter>new_dir</parameter></paramdef>
<paramdef>const char * <parameter>new_name</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>old_dir</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for the renamed object. This
should be a directory dentry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>old_dentry</parameter></term>
<listitem>
<para>
dentry of an object to be renamed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>new_dir</parameter></term>
<listitem>
<para>
a pointer to the parent dentry where the object should be
moved. This should be a directory dentry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>new_name</parameter></term>
<listitem>
<para>
a pointer to a string containing the target name.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function renames a file/directory in debugfs. The target must not
exist for rename to succeed.
</para><para>
This function will return a pointer to old_dentry (which is updated to
reflect renaming) if it succeeds. If an error occurs, <constant>NULL</constant> will be
returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-initialized">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_initialized</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_initialized</refname>
<refpurpose>
Tells whether debugfs has been registered
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>bool <function>debugfs_initialized </function></funcdef>
<paramdef> <parameter>void</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>void</parameter></term>
<listitem>
<para>
no arguments
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!-- fs/debugfs/file.c -->
<refentry id="API-debugfs-create-u8">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_u8</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_u8</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 8-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_u8 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u8 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that
contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so
set, it can be read from, and written to.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-u16">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_u16</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_u16</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 16-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_u16 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u16 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that
contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so
set, it can be read from, and written to.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-u32">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_u32</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_u32</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 32-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_u32 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u32 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that
contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so
set, it can be read from, and written to.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-u64">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_u64</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_u64</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 64-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_u64 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u64 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that
contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so
set, it can be read from, and written to.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-x8">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_x8</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_x8</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 8-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_x8 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u8 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-x16">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_x16</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_x16</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 16-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_x16 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u16 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-x32">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_x32</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_x32</refname>
<refpurpose>
create a debugfs file that is used to read and write an unsigned 32-bit value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_x32 </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u32 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-size-t">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_size_t</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_size_t</refname>
<refpurpose>
create a debugfs file that is used to read and write an size_t value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_size_t </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>size_t * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-bool">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_bool</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_bool</refname>
<refpurpose>
create a debugfs file that is used to read and write a boolean value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_bool </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>u32 * <parameter>value</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
a pointer to the variable that the file should read to and write
from.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that
contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so
set, it can be read from, and written to.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
<refentry id="API-debugfs-create-blob">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>debugfs_create_blob</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>debugfs_create_blob</refname>
<refpurpose>
create a debugfs file that is used to read a binary blob
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct dentry * <function>debugfs_create_blob </function></funcdef>
<paramdef>const char * <parameter>name</parameter></paramdef>
<paramdef>mode_t <parameter>mode</parameter></paramdef>
<paramdef>struct dentry * <parameter>parent</parameter></paramdef>
<paramdef>struct debugfs_blob_wrapper * <parameter>blob</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
a pointer to a string containing the name of the file to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
the permission that the file should have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>parent</parameter></term>
<listitem>
<para>
a pointer to the parent dentry for this file. This should be a
directory dentry if set. If this parameter is <constant>NULL</constant>, then the
file will be created in the root of the debugfs filesystem.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>blob</parameter></term>
<listitem>
<para>
a pointer to a struct debugfs_blob_wrapper which contains a pointer
to the blob data and the size of the data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file in debugfs with the given name that exports
<parameter>blob</parameter>->data as a binary blob. If the <parameter>mode</parameter> variable is so set it can be
read from. Writing is not supported.
</para><para>
This function will return a pointer to a dentry if it succeeds. This
pointer must be passed to the <function>debugfs_remove</function> function when the file is
to be removed (no automatic cleanup happens if your module is unloaded,
you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned.
</para><para>
If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be
returned. It is not wise to check for this value, but rather, check for
<constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
code.
</para>
</refsect1>
</refentry>
</sect1>
</chapter>
<chapter id="LinuxJDBAPI">
<chapterinfo>
<title>The Linux Journalling API</title>
<authorgroup>
<author>
<firstname>Roger</firstname>
<surname>Gammans</surname>
<affiliation>
<address>
<email>rgammans@computer-surgery.co.uk</email>
</address>
</affiliation>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Stephen</firstname>
<surname>Tweedie</surname>
<affiliation>
<address>
<email>sct@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2002</year>
<holder>Roger Gammans</holder>
</copyright>
</chapterinfo>
<title>The Linux Journalling API</title>
<sect1 id="journaling_overview">
<title>Overview</title>
<sect2 id="journaling_details">
<title>Details</title>
<para>
The journalling layer is easy to use. You need to
first of all create a journal_t data structure. There are
two calls to do this dependent on how you decide to allocate the physical
media on which the journal resides. The journal_init_inode() call
is for journals stored in filesystem inodes, or the journal_init_dev()
call can be use for journal stored on a raw device (in a continuous range
of blocks). A journal_t is a typedef for a struct pointer, so when
you are finally finished make sure you call journal_destroy() on it
to free up any used kernel memory.
</para>
<para>
Once you have got your journal_t object you need to 'mount' or load the journal
file, unless of course you haven't initialised it yet - in which case you
need to call journal_create().
</para>
<para>
Most of the time however your journal file will already have been created, but
before you load it you must call journal_wipe() to empty the journal file.
Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the
job of the client file system to detect this and skip the call to journal_wipe().
</para>
<para>
In either case the next call should be to journal_load() which prepares the
journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery()
for you if it detects any outstanding transactions in the journal and similarly
journal_load() will call journal_recover() if necessary.
I would advise reading fs/ext3/super.c for examples on this stage.
[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly
complicate the API. Or isn't a good idea for the journal layer to hide
dirty mounts from the client fs]
</para>
<para>
Now you can go ahead and start modifying the underlying
filesystem. Almost.
</para>
<para>
You still need to actually journal your filesystem changes, this
is done by wrapping them into transactions. Additionally you
also need to wrap the modification of each of the buffers
with calls to the journal layer, so it knows what the modifications
you are actually making are. To do this use journal_start() which
returns a transaction handle.
</para>
<para>
journal_start()
and its counterpart journal_stop(), which indicates the end of a transaction
are nestable calls, so you can reenter a transaction if necessary,
but remember you must call journal_stop() the same number of times as
journal_start() before the transaction is completed (or more accurately
leaves the update phase). Ext3/VFS makes use of this feature to simplify
quota support.
</para>
<para>
Inside each transaction you need to wrap the modifications to the
individual buffers (blocks). Before you start to modify a buffer you
need to call journal_get_{create,write,undo}_access() as appropriate,
this allows the journalling layer to copy the unmodified data if it
needs to. After all the buffer may be part of a previously uncommitted
transaction.
At this point you are at last ready to modify a buffer, and once
you are have done so you need to call journal_dirty_{meta,}data().
Or if you've asked for access to a buffer you now know is now longer
required to be pushed back on the device you can call journal_forget()
in much the same way as you might have used bforget() in the past.
</para>
<para>
A journal_flush() may be called at any time to commit and checkpoint
all your transactions.
</para>
<para>
Then at umount time , in your put_super() (2.4) or write_super() (2.5)
you can then call journal_destroy() to clean up your in-core journal object.
</para>
<para>
Unfortunately there a couple of ways the journal layer can cause a deadlock.
The first thing to note is that each task can only have
a single outstanding transaction at any one time, remember nothing
commits until the outermost journal_stop(). This means
you must complete the transaction at the end of each file/inode/address
etc. operation you perform, so that the journalling system isn't re-entered
on another journal. Since transactions can't be nested/batched
across differing journals, and another filesystem other than
yours (say ext3) may be modified in a later syscall.
</para>
<para>
The second case to bear in mind is that journal_start() can
block if there isn't enough space in the journal for your transaction
(based on the passed nblocks param) - when it blocks it merely(!) needs to
wait for transactions to complete and be committed from other tasks,
so essentially we are waiting for journal_stop(). So to avoid
deadlocks you must treat journal_start/stop() as if they
were semaphores and include them in your semaphore ordering rules to prevent
deadlocks. Note that journal_extend() has similar blocking behaviour to
journal_start() so you can deadlock here just as easily as on journal_start().
</para>
<para>
Try to reserve the right number of blocks the first time. ;-). This will
be the maximum number of blocks you are going to touch in this transaction.
I advise having a look at at least ext3_jbd.h to see the basis on which
ext3 uses to make these decisions.
</para>
<para>
Another wriggle to watch out for is your on-disk block allocation strategy.
why? Because, if you undo a delete, you need to ensure you haven't reused any
of the freed blocks in a later transaction. One simple way of doing this
is make sure any blocks you allocate only have checkpointed transactions
listed against them. Ext3 does this in ext3_test_allocatable().
</para>
<para>
Lock is also providing through journal_{un,}lock_updates(),
ext3 uses this when it wants a window with a clean and stable fs for a moment.
eg.
</para>
<programlisting>
journal_lock_updates() //stop new stuff happening..
journal_flush() // checkpoint everything.
..do stuff on stable fs
journal_unlock_updates() // carry on with filesystem use.
</programlisting>
<para>
The opportunities for abuse and DOS attacks with this should be obvious,
if you allow unprivileged userspace to trigger codepaths containing these
calls.
</para>
<para>
A new feature of jbd since 2.5.25 is commit callbacks with the new
journal_callback_set() function you can now ask the journalling layer
to call you back when the transaction is finally committed to disk, so that
you can do some of your own management. The key to this is the journal_callback
struct, this maintains the internal callback information but you can
extend it like this:-
</para>
<programlisting>
struct myfs_callback_s {
//Data structure element required by jbd..
struct journal_callback for_jbd;
// Stuff for myfs allocated together.
myfs_inode* i_commited;
}
</programlisting>
<para>
this would be useful if you needed to know when data was committed to a
particular inode.
</para>
</sect2>
<sect2 id="jbd_summary">
<title>Summary</title>
<para>
Using the journal is a matter of wrapping the different context changes,
being each mount, each modification (transaction) and each changed buffer
to tell the journalling layer about them.
</para>
<para>
Here is a some pseudo code to give you an idea of how it works, as
an example.
</para>
<programlisting>
journal_t* my_jnrl = journal_create();
journal_init_{dev,inode}(jnrl,...)
if (clean) journal_wipe();
journal_load();
foreach(transaction) { /*transactions must be
completed before
a syscall returns to
userspace*/
handle_t * xct=journal_start(my_jnrl);
foreach(bh) {
journal_get_{create,write,undo}_access(xact,bh);
if ( myfs_modify(bh) ) { /* returns true
if makes changes */
journal_dirty_{meta,}data(xact,bh);
} else {
journal_forget(bh);
}
}
journal_stop(xct);
}
journal_destroy(my_jrnl);
</programlisting>
</sect2>
</sect1>
<sect1 id="data_types">
<title>Data Types</title>
<para>
The journalling layer uses typedefs to 'hide' the concrete definitions
of the structures used. As a client of the JBD layer you can
just rely on the using the pointer as a magic cookie of some sort.
Obviously the hiding is not enforced as this is 'C'.
</para>
<sect2 id="structures"><title>Structures</title>
<!-- include/linux/jbd.h -->
<refentry id="API-typedef-handle-t">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>typedef handle_t</phrase></refentrytitle>
<manvolnum>9</manvolnum>
</refmeta>
<refnamediv>
<refname>typedef handle_t</refname>
<refpurpose>
The handle_t type represents a single atomic update being performed by some process.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<synopsis>typedef handle_t;</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
</para><para>
All filesystem modifications made by the process go
through this handle. Recursive operations (such as quota operations)
are gathered into a single update.
</para><para>
The buffer credits field is used to account for journaled buffers
being modified by the running process. To ensure that there is
enough log space for all outstanding operations, we need to limit the
number of outstanding buffers possible at any time. When the
operation completes, any buffer credits not used are credited back to
the transaction, so that at all times we know how many buffers the
outstanding updates on a transaction might possibly touch.
</para><para>
This is an opaque datatype.
</para>
</refsect1>
</refentry>
<refentry id="API-typedef-journal-t">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>typedef journal_t</phrase></refentrytitle>
<manvolnum>9</manvolnum>
</refmeta>
<refnamediv>
<refname>typedef journal_t</refname>
<refpurpose>
The journal_t maintains all of the journaling state information for a single filesystem.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<synopsis>typedef journal_t;</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
</para><para>
journal_t is linked to from the fs superblock structure.
</para><para>
We use the journal_t to keep track of all outstanding transaction
activity on the filesystem, and to manage the state of the log
writing process.
</para><para>
This is an opaque datatype.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-handle-s">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct handle_s</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct handle_s</refname>
<refpurpose>
this is the concrete type associated with handle_t.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct handle_s {
transaction_t * h_transaction;
int h_buffer_credits;
int h_ref;
int h_err;
unsigned int h_sync:1;
unsigned int h_jdata:1;
unsigned int h_aborted:1;
#ifdef CONFIG_DEBUG_LOCK_ALLOC
struct lockdep_map h_lockdep_map;
#endif
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>h_transaction</term>
<listitem><para>
Which compound transaction is this update a part of?
</para></listitem>
</varlistentry>
<varlistentry> <term>h_buffer_credits</term>
<listitem><para>
Number of remaining buffers we are allowed to dirty.
</para></listitem>
</varlistentry>
<varlistentry> <term>h_ref</term>
<listitem><para>
Reference count on this handle
</para></listitem>
</varlistentry>
<varlistentry> <term>h_err</term>
<listitem><para>
Field for caller's use to track errors through large fs operations
</para></listitem>
</varlistentry>
<varlistentry> <term>h_sync</term>
<listitem><para>
flag for sync-on-close
</para></listitem>
</varlistentry>
<varlistentry> <term>h_jdata</term>
<listitem><para>
flag to force data journaling
</para></listitem>
</varlistentry>
<varlistentry> <term>h_aborted</term>
<listitem><para>
flag indicating fatal error on handle
</para></listitem>
</varlistentry>
<varlistentry> <term>h_lockdep_map</term>
<listitem><para>
lockdep info for debugging lock problems
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-struct-journal-s">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct journal_s</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct journal_s</refname>
<refpurpose>
this is the concrete type associated with journal_t.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct journal_s {
unsigned long j_flags;
int j_errno;
struct buffer_head * j_sb_buffer;
journal_superblock_t * j_superblock;
int j_format_version;
spinlock_t j_state_lock;
int j_barrier_count;
struct mutex j_barrier;
transaction_t * j_running_transaction;
transaction_t * j_committing_transaction;
transaction_t * j_checkpoint_transactions;
wait_queue_head_t j_wait_transaction_locked;
wait_queue_head_t j_wait_logspace;
wait_queue_head_t j_wait_done_commit;
wait_queue_head_t j_wait_checkpoint;
wait_queue_head_t j_wait_commit;
wait_queue_head_t j_wait_updates;
struct mutex j_checkpoint_mutex;
unsigned int j_head;
unsigned int j_tail;
unsigned int j_free;
unsigned int j_first;
unsigned int j_last;
struct block_device * j_dev;
int j_blocksize;
unsigned int j_blk_offset;
struct block_device * j_fs_dev;
unsigned int j_maxlen;
spinlock_t j_list_lock;
struct inode * j_inode;
tid_t j_tail_sequence;
tid_t j_transaction_sequence;
tid_t j_commit_sequence;
tid_t j_commit_request;
__u8 j_uuid[16];
struct task_struct * j_task;
int j_max_transaction_buffers;
unsigned long j_commit_interval;
struct timer_list j_commit_timer;
spinlock_t j_revoke_lock;
struct jbd_revoke_table_s * j_revoke;
struct jbd_revoke_table_s * j_revoke_table[2];
struct buffer_head ** j_wbuf;
int j_wbufsize;
pid_t j_last_sync_writer;
u64 j_average_commit_time;
void * j_private;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>j_flags</term>
<listitem><para>
General journaling state flags
</para></listitem>
</varlistentry>
<varlistentry> <term>j_errno</term>
<listitem><para>
Is there an outstanding uncleared error on the journal (from a
prior abort)?
</para></listitem>
</varlistentry>
<varlistentry> <term>j_sb_buffer</term>
<listitem><para>
First part of superblock buffer
</para></listitem>
</varlistentry>
<varlistentry> <term>j_superblock</term>
<listitem><para>
Second part of superblock buffer
</para></listitem>
</varlistentry>
<varlistentry> <term>j_format_version</term>
<listitem><para>
Version of the superblock format
</para></listitem>
</varlistentry>
<varlistentry> <term>j_state_lock</term>
<listitem><para>
Protect the various scalars in the journal
</para></listitem>
</varlistentry>
<varlistentry> <term>j_barrier_count</term>
<listitem><para>
Number of processes waiting to create a barrier lock
</para></listitem>
</varlistentry>
<varlistentry> <term>j_barrier</term>
<listitem><para>
The barrier lock itself
</para></listitem>
</varlistentry>
<varlistentry> <term>j_running_transaction</term>
<listitem><para>
The current running transaction..
</para></listitem>
</varlistentry>
<varlistentry> <term>j_committing_transaction</term>
<listitem><para>
the transaction we are pushing to disk
</para></listitem>
</varlistentry>
<varlistentry> <term>j_checkpoint_transactions</term>
<listitem><para>
a linked circular list of all transactions
waiting for checkpointing
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_transaction_locked</term>
<listitem><para>
Wait queue for waiting for a locked transaction
to start committing, or for a barrier lock to be released
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_logspace</term>
<listitem><para>
Wait queue for waiting for checkpointing to complete
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_done_commit</term>
<listitem><para>
Wait queue for waiting for commit to complete
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_checkpoint</term>
<listitem><para>
Wait queue to trigger checkpointing
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_commit</term>
<listitem><para>
Wait queue to trigger commit
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wait_updates</term>
<listitem><para>
Wait queue to wait for updates to complete
</para></listitem>
</varlistentry>
<varlistentry> <term>j_checkpoint_mutex</term>
<listitem><para>
Mutex for locking against concurrent checkpoints
</para></listitem>
</varlistentry>
<varlistentry> <term>j_head</term>
<listitem><para>
Journal head - identifies the first unused block in the journal
</para></listitem>
</varlistentry>
<varlistentry> <term>j_tail</term>
<listitem><para>
Journal tail - identifies the oldest still-used block in the
journal.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_free</term>
<listitem><para>
Journal free - how many free blocks are there in the journal?
</para></listitem>
</varlistentry>
<varlistentry> <term>j_first</term>
<listitem><para>
The block number of the first usable block
</para></listitem>
</varlistentry>
<varlistentry> <term>j_last</term>
<listitem><para>
The block number one beyond the last usable block
</para></listitem>
</varlistentry>
<varlistentry> <term>j_dev</term>
<listitem><para>
Device where we store the journal
</para></listitem>
</varlistentry>
<varlistentry> <term>j_blocksize</term>
<listitem><para>
blocksize for the location where we store the journal.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_blk_offset</term>
<listitem><para>
starting block offset for into the device where we store the
journal
</para></listitem>
</varlistentry>
<varlistentry> <term>j_fs_dev</term>
<listitem><para>
Device which holds the client fs. For internal journal this will
be equal to j_dev
</para></listitem>
</varlistentry>
<varlistentry> <term>j_maxlen</term>
<listitem><para>
Total maximum capacity of the journal region on disk.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_list_lock</term>
<listitem><para>
Protects the buffer lists and internal buffer state.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_inode</term>
<listitem><para>
Optional inode where we store the journal. If present, all journal
block numbers are mapped into this inode via <function>bmap</function>.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_tail_sequence</term>
<listitem><para>
Sequence number of the oldest transaction in the log
</para></listitem>
</varlistentry>
<varlistentry> <term>j_transaction_sequence</term>
<listitem><para>
Sequence number of the next transaction to grant
</para></listitem>
</varlistentry>
<varlistentry> <term>j_commit_sequence</term>
<listitem><para>
Sequence number of the most recently committed
transaction
</para></listitem>
</varlistentry>
<varlistentry> <term>j_commit_request</term>
<listitem><para>
Sequence number of the most recent transaction wanting
commit
</para></listitem>
</varlistentry>
<varlistentry> <term>j_uuid[16]</term>
<listitem><para>
Uuid of client object.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_task</term>
<listitem><para>
Pointer to the current commit thread for this journal
</para></listitem>
</varlistentry>
<varlistentry> <term>j_max_transaction_buffers</term>
<listitem><para>
Maximum number of metadata buffers to allow in a
single compound commit transaction
</para></listitem>
</varlistentry>
<varlistentry> <term>j_commit_interval</term>
<listitem><para>
What is the maximum transaction lifetime before we begin
a commit?
</para></listitem>
</varlistentry>
<varlistentry> <term>j_commit_timer</term>
<listitem><para>
The timer used to wakeup the commit thread
</para></listitem>
</varlistentry>
<varlistentry> <term>j_revoke_lock</term>
<listitem><para>
Protect the revoke table
</para></listitem>
</varlistentry>
<varlistentry> <term>j_revoke</term>
<listitem><para>
The revoke table - maintains the list of revoked blocks in the
current transaction.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_revoke_table[2]</term>
<listitem><para>
alternate revoke tables for j_revoke
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wbuf</term>
<listitem><para>
array of buffer_heads for journal_commit_transaction
</para></listitem>
</varlistentry>
<varlistentry> <term>j_wbufsize</term>
<listitem><para>
maximum number of buffer_heads allowed in j_wbuf, the
number that will fit in j_blocksize
</para></listitem>
</varlistentry>
<varlistentry> <term>j_last_sync_writer</term>
<listitem><para>
most recent pid which did a synchronous write
</para></listitem>
</varlistentry>
<varlistentry> <term>j_average_commit_time</term>
<listitem><para>
the average amount of time in nanoseconds it
takes to commit a transaction to the disk.
</para></listitem>
</varlistentry>
<varlistentry> <term>j_private</term>
<listitem><para>
An opaque pointer to fs-private information.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</sect2>
</sect1>
<sect1 id="functions">
<title>Functions</title>
<para>
The functions here are split into two groups those that
affect a journal as a whole, and those which are used to
manage transactions
</para>
<sect2 id="journal_level"><title>Journal Level</title>
<!-- fs/jbd/journal.c -->
<refentry id="API-journal-init-dev">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_init_dev</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_init_dev</refname>
<refpurpose>
creates and initialises a journal structure
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>journal_t * <function>journal_init_dev </function></funcdef>
<paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
<paramdef>struct block_device * <parameter>fs_dev</parameter></paramdef>
<paramdef>int <parameter>start</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
<paramdef>int <parameter>blocksize</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>bdev</parameter></term>
<listitem>
<para>
Block device on which to create the journal
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fs_dev</parameter></term>
<listitem>
<para>
Device which hold journalled filesystem for this journal.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
Block nr Start of journal.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
Length of the journal in blocks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>blocksize</parameter></term>
<listitem>
<para>
blocksize of journalling device
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
a newly created journal_t *
</para><para>
journal_init_dev creates a journal which maps a fixed contiguous
range of blocks on an arbitrary block device.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-init-inode">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_init_inode</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_init_inode</refname>
<refpurpose>
creates a journal which maps to a inode.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>journal_t * <function>journal_init_inode </function></funcdef>
<paramdef>struct inode * <parameter>inode</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>inode</parameter></term>
<listitem>
<para>
An inode to create the journal in
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
journal_init_inode creates a journal which maps an on-disk inode as
the journal. The inode must exist already, must support <function>bmap</function> and
must have all data blocks preallocated.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-create">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_create</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_create</refname>
<refpurpose>
Initialise the new journal file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_create </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to create. This structure must have been initialised
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given a journal_t structure which tells us which disk blocks we can
use, create a new journal superblock and initialise all of the
journal fields from scratch.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-load">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_load</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_load</refname>
<refpurpose>
Read journal from disk.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_load </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given a journal_t structure which tells us which disk blocks contain
a journal, read the journal from disk to initialise the in-memory
structures.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-destroy">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_destroy</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_destroy</refname>
<refpurpose>
Release a journal_t structure.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_destroy </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Release a journal_t structure once it is no longer in use by the
journaled object.
Return <0 if we couldn't clean up the journal.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-check-used-features">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_check_used_features</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_check_used_features</refname>
<refpurpose>
Check if features specified are used.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_check_used_features </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>unsigned long <parameter>compat</parameter></paramdef>
<paramdef>unsigned long <parameter>ro</parameter></paramdef>
<paramdef>unsigned long <parameter>incompat</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to check.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>compat</parameter></term>
<listitem>
<para>
bitmask of compatible features
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ro</parameter></term>
<listitem>
<para>
bitmask of features that force read-only mount
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>incompat</parameter></term>
<listitem>
<para>
bitmask of incompatible features
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Check whether the journal uses all of a given set of
features. Return true (non-zero) if it does.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-check-available-features">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_check_available_features</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_check_available_features</refname>
<refpurpose>
Check feature set in journalling layer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_check_available_features </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>unsigned long <parameter>compat</parameter></paramdef>
<paramdef>unsigned long <parameter>ro</parameter></paramdef>
<paramdef>unsigned long <parameter>incompat</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to check.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>compat</parameter></term>
<listitem>
<para>
bitmask of compatible features
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ro</parameter></term>
<listitem>
<para>
bitmask of features that force read-only mount
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>incompat</parameter></term>
<listitem>
<para>
bitmask of incompatible features
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Check whether the journaling code supports the use of
all of a given set of features on this journal. Return true
</para>
</refsect1>
</refentry>
<refentry id="API-journal-set-features">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_set_features</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_set_features</refname>
<refpurpose>
Mark a given journal feature in the superblock
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_set_features </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>unsigned long <parameter>compat</parameter></paramdef>
<paramdef>unsigned long <parameter>ro</parameter></paramdef>
<paramdef>unsigned long <parameter>incompat</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>compat</parameter></term>
<listitem>
<para>
bitmask of compatible features
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ro</parameter></term>
<listitem>
<para>
bitmask of features that force read-only mount
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>incompat</parameter></term>
<listitem>
<para>
bitmask of incompatible features
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Mark a given journal feature as present on the
superblock. Returns true if the requested features could be set.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-update-format">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_update_format</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_update_format</refname>
<refpurpose>
Update on-disk journal structure.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_update_format </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Given an initialised but unloaded journal struct, poke about in the
on-disk structure to update it to the most recent supported version.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-flush">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_flush</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_flush</refname>
<refpurpose>
Flush journal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_flush </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Flush all data for a given journal to disk and empty the journal.
Filesystems can use this when remounting readonly to ensure that
recovery does not need to happen on remount.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-wipe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_wipe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_wipe</refname>
<refpurpose>
Wipe journal contents
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_wipe </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>int <parameter>write</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to act on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
flag (see below)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Wipe out all of the contents of a journal, safely. This will produce
a warning if the journal contains any valid recovery information.
Must be called between journal_init_*() and <function>journal_load</function>.
</para><para>
If 'write' is non-zero, then we wipe out the journal on disk; otherwise
we merely suppress recovery.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-abort">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_abort</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_abort</refname>
<refpurpose>
Shutdown the journal immediately.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>journal_abort </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>int <parameter>errno</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
the journal to shutdown.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errno</parameter></term>
<listitem>
<para>
an error number to record in the journal indicating
the reason for the shutdown.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Perform a complete, immediate shutdown of the ENTIRE
journal (not of a single transaction). This operation cannot be
undone without closing and reopening the journal.
</para><para>
The journal_abort function is intended to support higher level error
recovery mechanisms such as the ext2/ext3 remount-readonly error
mode.
</para><para>
Journal abort has very specific semantics. Any existing dirty,
unjournaled buffers in the main filesystem will still be written to
disk by bdflush, but the journaling mechanism will be suspended
immediately and no further transaction commits will be honoured.
</para><para>
Any dirty, journaled buffers will be written back to disk without
hitting the journal. Atomicity cannot be guaranteed on an aborted
filesystem, but we _do_ attempt to leave as much data as possible
behind for fsck to use for cleanup.
</para><para>
Any attempt to get a new transaction handle on a journal which is in
ABORT state will just result in an -EROFS error return. A
journal_stop on an existing handle will return -EIO if we have
entered abort state during the update.
</para><para>
Recursive transactions are not disturbed by journal abort until the
final journal_stop, which will receive the -EIO error.
</para><para>
Finally, the journal_abort call allows the caller to supply an errno
which will be recorded (if possible) in the journal superblock. This
allows a client to record failure conditions in the middle of a
transaction without having to complete the transaction to record the
failure to disk. ext3_error, for example, now uses this
functionality.
</para><para>
Errors which originate from within the journaling layer will NOT
supply an errno; a null errno implies that absolutely no further
writes are done to the journal (unless there are any already in
progress).
</para>
</refsect1>
</refentry>
<refentry id="API-journal-errno">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_errno</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_errno</refname>
<refpurpose>
returns the journal's error state.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_errno </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to examine.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the errno numbet set with <function>journal_abort</function>, the last
time the journal was mounted - if the journal was stopped
without calling abort this will be 0.
</para><para>
If the journal has been aborted on this mount time -EROFS will
be returned.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-clear-err">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_clear_err</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_clear_err</refname>
<refpurpose>
clears the journal's error state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_clear_err </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
An error must be cleared or Acked to take a FS out of readonly
mode.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-ack-err">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_ack_err</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_ack_err</refname>
<refpurpose>
Ack journal err.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>journal_ack_err </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to act on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
An error must be cleared or Acked to take a FS out of readonly
mode.
</para>
</refsect1>
</refentry>
<!-- fs/jbd/recovery.c -->
<refentry id="API-journal-recover">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_recover</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_recover</refname>
<refpurpose>
recovers a on-disk journal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_recover </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
the journal to recover
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The primary function for recovering the log contents when mounting a
journaled device.
</para><para>
Recovery is done in three passes. In the first pass, we look for the
end of the log. In the second, we assemble the list of revoke
blocks. In the third and final pass, we replay any un-revoked blocks
in the log.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-skip-recovery">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_skip_recovery</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_skip_recovery</refname>
<refpurpose>
Start journal and wipe exiting records
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_skip_recovery </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to startup
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Locate any valid recovery information from the journal and set up the
journal structures in memory to ignore it (presumably because the
caller has evidence that it is out of date).
This function does'nt appear to be exorted..
</para><para>
We perform one pass over the journal to allow us to tell the user how
much recovery information is being erased, and to let us initialise
the journal transaction sequence numbers to the next unused ID.
</para>
</refsect1>
</refentry>
</sect2>
<sect2 id="transaction_level"><title>Transasction Level</title>
<!-- fs/jbd/transaction.c -->
<refentry id="API-journal-start">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_start</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_start</refname>
<refpurpose>
Obtain a new handle.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>handle_t * <function>journal_start </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>int <parameter>nblocks</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to start transaction on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nblocks</parameter></term>
<listitem>
<para>
number of block buffer we might modify
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
We make sure that the transaction can guarantee at least nblocks of
modified buffers in the log. We block until the log can guarantee
that much space.
</para><para>
This function is visible to journal users (like ext3fs), so is not
called with the journal already locked.
</para><para>
Return a pointer to a newly allocated handle, or NULL on failure
</para>
</refsect1>
</refentry>
<refentry id="API-journal-extend">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_extend</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_extend</refname>
<refpurpose>
extend buffer credits.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_extend </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>int <parameter>nblocks</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
handle to 'extend'
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nblocks</parameter></term>
<listitem>
<para>
nr blocks to try to extend by.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Some transactions, such as large extends and truncates, can be done
atomically all at once or in several stages. The operation requests
a credit for a number of buffer modications in advance, but can
extend its credit if it needs more.
</para><para>
journal_extend tries to give the running handle more buffer credits.
It does not guarantee that allocation - this is a best-effort only.
The calling process MUST be able to deal cleanly with a failure to
extend here.
</para><para>
Return 0 on success, non-zero on failure.
</para><para>
return code < 0 implies an error
return code > 0 implies normal transaction-full status.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-restart">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_restart</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_restart</refname>
<refpurpose>
restart a handle.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_restart </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>int <parameter>nblocks</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
handle to restart
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nblocks</parameter></term>
<listitem>
<para>
nr credits requested
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Restart a handle for a multi-transaction filesystem
operation.
</para><para>
If the <function>journal_extend</function> call above fails to grant new buffer credits
to a running handle, a call to journal_restart will commit the
handle's transaction so far and reattach the handle to a new
transaction capabable of guaranteeing the requested number of
credits.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-lock-updates">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_lock_updates</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_lock_updates</refname>
<refpurpose>
establish a transaction barrier.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>journal_lock_updates </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to establish a barrier on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This locks out any further updates from being started, and blocks
until all existing updates have completed, returning only once the
journal is in a quiescent state with no updates running.
</para><para>
The journal lock should not be held on entry.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-unlock-updates">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_unlock_updates</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_unlock_updates</refname>
<refpurpose>
release barrier
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>journal_unlock_updates </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
Journal to release the barrier on.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Release a transaction barrier obtained with <function>journal_lock_updates</function>.
</para><para>
Should be called without the journal lock held.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-get-write-access">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_get_write_access</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_get_write_access</refname>
<refpurpose>
notify intent to modify a buffer for metadata (not data) update.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_get_write_access </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction to add buffer modifications to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
bh to be used for metadata writes
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns an error code or 0 on success.
</para><para>
In full data journalling mode the buffer may be of type BJ_AsyncData,
because we're <function>write</function>ing a buffer which is also part of a shared mapping.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-get-create-access">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_get_create_access</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_get_create_access</refname>
<refpurpose>
notify intent to use newly created bh
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_get_create_access </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction to new buffer to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
new buffer.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Call this if you create a new bh.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-get-undo-access">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_get_undo_access</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_get_undo_access</refname>
<refpurpose>
Notify intent to modify metadata with non-rewindable consequences
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_get_undo_access </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
buffer to undo
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Sometimes there is a need to distinguish between metadata which has
been committed to disk and that which has not. The ext3fs code uses
this for freeing and allocating space, we have to make sure that we
do not reuse freed space until the deallocation has been committed,
since if we overwrote that space we would make the delete
un-rewindable in case of a crash.
</para><para>
To deal with that, journal_get_undo_access requests write access to a
buffer for parts of non-rewindable operations such as delete
operations on the bitmaps. The journaling code must keep a copy of
the buffer's contents prior to the undo_access call until such time
as we know that the buffer has definitely been committed to disk.
</para><para>
We never need to know which transaction the committed data is part
of, buffers touched here are guaranteed to be dirtied later and so
will be committed to a new transaction in due course, at which point
we can discard the old committed data pointer.
</para><para>
Returns error number or 0 on success.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-dirty-data">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_dirty_data</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_dirty_data</refname>
<refpurpose>
mark a buffer as containing dirty data to be flushed
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_dirty_data </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
bufferhead to mark
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Mark a buffer as containing dirty data which needs to be flushed before
we can commit the current transaction.
</para><para>
The buffer is placed on the transaction's data list and is marked as
belonging to the transaction.
</para><para>
Returns error number or 0 on success.
</para><para>
<function>journal_dirty_data</function> can be called via page_launder->ext3_writepage
by kswapd.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-dirty-metadata">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_dirty_metadata</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_dirty_metadata</refname>
<refpurpose>
mark a buffer as containing dirty metadata
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_dirty_metadata </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction to add buffer to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
buffer to mark
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Mark dirty metadata which needs to be journaled as part of the current
transaction.
</para><para>
The buffer is placed on the transaction's metadata list and is marked
as belonging to the transaction.
</para><para>
Returns error number or 0 on success.
</para><para>
Special care needs to be taken if the buffer already belongs to the
current committing transaction (in which case we should have frozen
data present for that commit). In that case, we don't relink the
</para>
</refsect1>
<refsect1>
<title>buffer</title>
<para>
that only gets done when the old transaction finally
completes its commit.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-forget">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_forget</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_forget</refname>
<refpurpose>
<function>bforget</function> for potentially-journaled buffers.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_forget </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
<paramdef>struct buffer_head * <parameter>bh</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
transaction handle
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bh</parameter></term>
<listitem>
<para>
bh to 'forget'
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
We can only do the bforget if there are no commits pending against the
buffer. If the buffer is dirty in the current running transaction we
can safely unlink it.
</para><para>
bh may not be a journalled buffer at all - it may be a non-JBD
buffer which came off the hashtable. Check for this.
</para><para>
Decrements bh->b_count by one.
</para><para>
Allow this call even if the handle has aborted --- it may be part of
the caller's cleanup after an abort.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-stop">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_stop</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_stop</refname>
<refpurpose>
complete a transaction
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_stop </function></funcdef>
<paramdef>handle_t * <parameter>handle</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<para>
tranaction to complete.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
All done for a particular handle.
</para><para>
There is not much action needed here. We just return any remaining
buffer credits to the transaction and remove the handle. The only
complication is that we need to start a commit operation if the
filesystem is marked for synchronous update.
</para><para>
journal_stop itself will not usually return an error, but it may
do so in unusual circumstances. In particular, expect it to
return -EIO if a journal_abort has been executed since the
transaction began.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-force-commit">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_force_commit</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_force_commit</refname>
<refpurpose>
force any uncommitted transactions
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_force_commit </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to force
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>For synchronous operations</title>
<para>
force any uncommitted transactions
to disk. May seem kludgy, but it reuses all the handle batching
code in a very simple manner.
</para>
</refsect1>
</refentry>
<refentry id="API-journal-try-to-free-buffers">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_try_to_free_buffers</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_try_to_free_buffers</refname>
<refpurpose>
try to free page buffers.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>journal_try_to_free_buffers </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>struct page * <parameter>page</parameter></paramdef>
<paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal for operation
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>page</parameter></term>
<listitem>
<para>
to try and free
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>gfp_mask</parameter></term>
<listitem>
<para>
we use the mask to detect how hard should we try to release
buffers. If __GFP_WAIT and __GFP_FS is set, we wait for commit code to
release the buffers.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
For all the buffers on this page,
if they are fully written out ordered data, move them onto BUF_CLEAN
so <function>try_to_free_buffers</function> can reap them.
</para><para>
This function returns non-zero if we wish <function>try_to_free_buffers</function>
to be called. We do this if the page is releasable by <function>try_to_free_buffers</function>.
We also do it if the page has locked or dirty buffers and the caller wants
us to perform sync or async writeout.
</para><para>
This complicates JBD locking somewhat. We aren't protected by the
BKL here. We wish to remove the buffer from its committing or
running transaction's ->t_datalist via __journal_unfile_buffer.
</para><para>
This may *change* the value of transaction_t->t_datalist, so anyone
who looks at t_datalist needs to lock against this function.
</para><para>
Even worse, someone may be doing a journal_dirty_data on this
buffer. So we need to lock against that. <function>journal_dirty_data</function>
will come out of the lock with the buffer dirty, which makes it
ineligible for release here.
</para><para>
Who else is affected by this? hmm... Really the only contender
is <function>do_get_write_access</function> - it could be looking at the buffer while
<function>journal_try_to_free_buffer</function> is changing its state. But that
cannot happen because we never reallocate freed data as metadata
while the data is part of a transaction. Yes?
</para><para>
Return 0 on failure, 1 on success
</para>
</refsect1>
</refentry>
<refentry id="API-journal-invalidatepage">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>journal_invalidatepage</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>journal_invalidatepage</refname>
<refpurpose>
invalidate a journal page
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>journal_invalidatepage </function></funcdef>
<paramdef>journal_t * <parameter>journal</parameter></paramdef>
<paramdef>struct page * <parameter>page</parameter></paramdef>
<paramdef>unsigned long <parameter>offset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>journal</parameter></term>
<listitem>
<para>
journal to use for flush
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>page</parameter></term>
<listitem>
<para>
page to flush
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
length of page to invalidate.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Reap page buffers containing data after offset in page.
</para>
</refsect1>
</refentry>
</sect2>
</sect1>
<sect1 id="see_also">
<title>See also</title>
<para>
<citation>
<ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz">
Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie
</ulink>
</citation>
</para>
<para>
<citation>
<ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie
</ulink>
</citation>
</para>
</sect1>
</chapter>
<chapter id="splice">
<title>splice API</title>
<para>
splice is a method for moving blocks of data around inside the
kernel, without continually transferring them between the kernel
and user space.
</para>
<refentry id="API-splice-to-pipe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_to_pipe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_to_pipe</refname>
<refpurpose>
fill passed data into a pipe
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>splice_to_pipe </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct splice_pipe_desc * <parameter>spd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to fill
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>spd</parameter></term>
<listitem>
<para>
data to fill
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<parameter>spd</parameter> contains a map of pages and len/offset tuples, along with
the struct pipe_buf_operations associated with these pages. This
function will link that data to the pipe.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-file-splice-read">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_file_splice_read</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_file_splice_read</refname>
<refpurpose>
splice data from file to a pipe
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>generic_file_splice_read </function></funcdef>
<paramdef>struct file * <parameter>in</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>in</parameter></term>
<listitem>
<para>
file to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
position in <parameter>in</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
number of bytes to splice
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
splice modifier flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Will read pages from given file and fill them into a pipe. Can be
used as long as the address_space operations for the source implements
a <function>readpage</function> hook.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-from-pipe-feed">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_from_pipe_feed</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_from_pipe_feed</refname>
<refpurpose>
feed available data from a pipe to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>splice_from_pipe_feed </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
<paramdef>splice_actor * <parameter>actor</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
information to <parameter>actor</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>actor</parameter></term>
<listitem>
<para>
handler that splices the data
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function loops over the pipe and calls <parameter>actor</parameter> to do the
actual moving of a single struct pipe_buffer to the desired
destination. It returns when there's no more buffers left in
the pipe or if the requested number of bytes (<parameter>sd</parameter>->total_len)
have been copied. It returns a positive number (one) if the
pipe needs to be filled with more data, zero if the required
number of bytes have been copied and -errno on error.
</para><para>
This, together with splice_from_pipe_{begin,end,next}, may be
used to implement the functionality of <function>__splice_from_pipe</function> when
locking is required around copying the pipe buffers to the
destination.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-from-pipe-next">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_from_pipe_next</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_from_pipe_next</refname>
<refpurpose>
wait for some data to splice from
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>splice_from_pipe_next </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
information about the splice operation
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function will wait for some data and return a positive
value (one) if pipe buffers are available. It will return zero
or -errno if no more data needs to be spliced.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-from-pipe-begin">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_from_pipe_begin</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_from_pipe_begin</refname>
<refpurpose>
start splicing from pipe
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>splice_from_pipe_begin </function></funcdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
information about the splice operation
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function should be called before a loop containing
<function>splice_from_pipe_next</function> and <function>splice_from_pipe_feed</function> to
initialize the necessary fields of <parameter>sd</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-from-pipe-end">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_from_pipe_end</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_from_pipe_end</refname>
<refpurpose>
finish splicing from pipe
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>splice_from_pipe_end </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
information about the splice operation
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function will wake up pipe writers if necessary. It should
be called after a loop containing <function>splice_from_pipe_next</function> and
<function>splice_from_pipe_feed</function>.
</para>
</refsect1>
</refentry>
<refentry id="API---splice-from-pipe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>__splice_from_pipe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>__splice_from_pipe</refname>
<refpurpose>
splice data from a pipe to given actor
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>__splice_from_pipe </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
<paramdef>splice_actor * <parameter>actor</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
information to <parameter>actor</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>actor</parameter></term>
<listitem>
<para>
handler that splices the data
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function does little more than loop over the pipe and call
<parameter>actor</parameter> to do the actual moving of a single struct pipe_buffer to
the desired destination. See pipe_to_file, pipe_to_sendpage, or
pipe_to_user.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-from-pipe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_from_pipe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_from_pipe</refname>
<refpurpose>
splice data from a pipe to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>splice_from_pipe </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct file * <parameter>out</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
<paramdef>splice_actor * <parameter>actor</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>out</parameter></term>
<listitem>
<para>
file to splice to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
position in <parameter>out</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
how many bytes to splice
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
splice modifier flags
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>actor</parameter></term>
<listitem>
<para>
handler that splices the data
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
See __splice_from_pipe. This function locks the pipe inode,
otherwise it's identical to <function>__splice_from_pipe</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-file-splice-write">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_file_splice_write</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_file_splice_write</refname>
<refpurpose>
splice data from a pipe to a file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>generic_file_splice_write </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct file * <parameter>out</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe info
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>out</parameter></term>
<listitem>
<para>
file to write to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
position in <parameter>out</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
number of bytes to splice
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
splice modifier flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Will either move or copy pages (determined by <parameter>flags</parameter> options) from
the given pipe inode to the given file.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-splice-sendpage">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_splice_sendpage</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_splice_sendpage</refname>
<refpurpose>
splice data from a pipe to a socket
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>generic_splice_sendpage </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct file * <parameter>out</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
pipe to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>out</parameter></term>
<listitem>
<para>
socket to write to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
position in <parameter>out</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
number of bytes to splice
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
splice modifier flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Will send <parameter>len</parameter> bytes from the pipe to a network socket. No data copying
is involved.
</para>
</refsect1>
</refentry>
<refentry id="API-splice-direct-to-actor">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>splice_direct_to_actor</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>splice_direct_to_actor</refname>
<refpurpose>
splices data directly between two non-pipes
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>ssize_t <function>splice_direct_to_actor </function></funcdef>
<paramdef>struct file * <parameter>in</parameter></paramdef>
<paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
<paramdef>splice_direct_actor * <parameter>actor</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>in</parameter></term>
<listitem>
<para>
file to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sd</parameter></term>
<listitem>
<para>
actor information on where to splice to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>actor</parameter></term>
<listitem>
<para>
handles the data splicing
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is a special case helper to splice directly between two
points, without requiring an explicit pipe. Internally an allocated
pipe is cached in the process, and reused during the lifetime of
that process.
</para>
</refsect1>
</refentry>
<refentry id="API-do-splice-direct">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>do_splice_direct</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>do_splice_direct</refname>
<refpurpose>
splices data directly between two files
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>long <function>do_splice_direct </function></funcdef>
<paramdef>struct file * <parameter>in</parameter></paramdef>
<paramdef>loff_t * <parameter>ppos</parameter></paramdef>
<paramdef>struct file * <parameter>out</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>in</parameter></term>
<listitem>
<para>
file to splice from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ppos</parameter></term>
<listitem>
<para>
input file offset
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>out</parameter></term>
<listitem>
<para>
file to splice to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>len</parameter></term>
<listitem>
<para>
number of bytes to splice
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
splice modifier flags
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
For use by <function>do_sendfile</function>. splice can easily emulate sendfile, but
doing it in the application would incur an extra system call
(splice in + splice out, as compared to just <function>sendfile</function>). So this helper
can splice directly through a process-private pipe.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="pipes">
<title>pipes API</title>
<para>
Pipe interfaces are all for in-kernel (builtin image) use.
They are not exported for use by modules.
</para>
<!-- include/linux/pipe_fs_i.h -->
<refentry id="API-struct-pipe-buffer">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct pipe_buffer</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct pipe_buffer</refname>
<refpurpose>
a linux kernel pipe buffer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct pipe_buffer {
struct page * page;
unsigned int offset;
unsigned int len;
const struct pipe_buf_operations * ops;
unsigned int flags;
unsigned long private;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>page</term>
<listitem><para>
the page containing the data for the pipe buffer
</para></listitem>
</varlistentry>
<varlistentry> <term>offset</term>
<listitem><para>
offset of data inside the <parameter>page</parameter>
</para></listitem>
</varlistentry>
<varlistentry> <term>len</term>
<listitem><para>
length of data inside the <parameter>page</parameter>
</para></listitem>
</varlistentry>
<varlistentry> <term>ops</term>
<listitem><para>
operations associated with this buffer. See <parameter>pipe_buf_operations</parameter>.
</para></listitem>
</varlistentry>
<varlistentry> <term>flags</term>
<listitem><para>
pipe buffer flags. See above.
</para></listitem>
</varlistentry>
<varlistentry> <term>private</term>
<listitem><para>
private data owned by the ops.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-struct-pipe-inode-info">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct pipe_inode_info</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct pipe_inode_info</refname>
<refpurpose>
a linux kernel pipe
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct pipe_inode_info {
wait_queue_head_t wait;
unsigned int nrbufs;
unsigned int curbuf;
struct page * tmp_page;
unsigned int readers;
unsigned int writers;
unsigned int waiting_writers;
unsigned int r_counter;
unsigned int w_counter;
struct fasync_struct * fasync_readers;
struct fasync_struct * fasync_writers;
struct inode * inode;
struct pipe_buffer bufs[PIPE_BUFFERS];
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>wait</term>
<listitem><para>
reader/writer wait point in case of empty/full pipe
</para></listitem>
</varlistentry>
<varlistentry> <term>nrbufs</term>
<listitem><para>
the number of non-empty pipe buffers in this pipe
</para></listitem>
</varlistentry>
<varlistentry> <term>curbuf</term>
<listitem><para>
the current pipe buffer entry
</para></listitem>
</varlistentry>
<varlistentry> <term>tmp_page</term>
<listitem><para>
cached released page
</para></listitem>
</varlistentry>
<varlistentry> <term>readers</term>
<listitem><para>
number of current readers of this pipe
</para></listitem>
</varlistentry>
<varlistentry> <term>writers</term>
<listitem><para>
number of current writers of this pipe
</para></listitem>
</varlistentry>
<varlistentry> <term>waiting_writers</term>
<listitem><para>
number of writers blocked waiting for room
</para></listitem>
</varlistentry>
<varlistentry> <term>r_counter</term>
<listitem><para>
reader counter
</para></listitem>
</varlistentry>
<varlistentry> <term>w_counter</term>
<listitem><para>
writer counter
</para></listitem>
</varlistentry>
<varlistentry> <term>fasync_readers</term>
<listitem><para>
reader side fasync
</para></listitem>
</varlistentry>
<varlistentry> <term>fasync_writers</term>
<listitem><para>
writer side fasync
</para></listitem>
</varlistentry>
<varlistentry> <term>inode</term>
<listitem><para>
inode this pipe is attached to
</para></listitem>
</varlistentry>
<varlistentry> <term>bufs[PIPE_BUFFERS]</term>
<listitem><para>
the circular array of pipe buffers
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-map">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_map</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_map</refname>
<refpurpose>
virtually map a pipe buffer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void * <function>generic_pipe_buf_map </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
<paramdef>int <parameter>atomic</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer that should be mapped
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>atomic</parameter></term>
<listitem>
<para>
whether to use an atomic map
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function returns a kernel virtual address mapping for the
pipe_buffer passed in <parameter>buf</parameter>. If <parameter>atomic</parameter> is set, an atomic map is provided
and the caller has to be careful not to fault before calling
the unmap function.
</para><para>
Note that this function occupies KM_USER0 if <parameter>atomic</parameter> != 0.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-unmap">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_unmap</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_unmap</refname>
<refpurpose>
unmap a previously mapped pipe buffer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>generic_pipe_buf_unmap </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
<paramdef>void * <parameter>map_data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer that should be unmapped
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>map_data</parameter></term>
<listitem>
<para>
the data that the mapping function returned
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function undoes the mapping that -><function>map</function> provided.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-steal">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_steal</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_steal</refname>
<refpurpose>
attempt to take ownership of a <structname>pipe_buffer</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>generic_pipe_buf_steal </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer to attempt to steal
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function attempts to steal the <structname>struct page</structname> attached to
<parameter>buf</parameter>. If successful, this function returns 0 and returns with
the page locked. The caller may then reuse the page for whatever
he wishes; the typical use is insertion into a different file
page cache.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_get</refname>
<refpurpose>
get a reference to a <structname>struct pipe_buffer</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>generic_pipe_buf_get </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer to get a reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function grabs an extra reference to <parameter>buf</parameter>. It's used in
in the <function>tee</function> system call, when we duplicate the buffers in one
pipe into another.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-confirm">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_confirm</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_confirm</refname>
<refpurpose>
verify contents of the pipe buffer
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>generic_pipe_buf_confirm </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>info</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer to confirm
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function does nothing, because the generic pipe code uses
pages that are always good when inserted into the pipe.
</para>
</refsect1>
</refentry>
<refentry id="API-generic-pipe-buf-release">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>generic_pipe_buf_release</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generic_pipe_buf_release</refname>
<refpurpose>
put a reference to a <structname>struct pipe_buffer</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>generic_pipe_buf_release </function></funcdef>
<paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
<paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pipe</parameter></term>
<listitem>
<para>
the pipe that the buffer belongs to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para>
the buffer to put a reference to
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function releases a reference to <parameter>buf</parameter>.
</para>
</refsect1>
</refentry>
</chapter>
</book>
