1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="Linux-filesystems-API"> 6 <bookinfo> 7 <title>Linux Filesystems API</title> 8 9 <legalnotice> 10 <para> 11 This documentation is free software; you can redistribute 12 it and/or modify it under the terms of the GNU General Public 13 License as published by the Free Software Foundation; either 14 version 2 of the License, or (at your option) any later 15 version. 16 </para> 17 18 <para> 19 This program is distributed in the hope that it will be 20 useful, but WITHOUT ANY WARRANTY; without even the implied 21 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 22 See the GNU General Public License for more details. 23 </para> 24 25 <para> 26 You should have received a copy of the GNU General Public 27 License along with this program; if not, write to the Free 28 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 29 MA 02111-1307 USA 30 </para> 31 32 <para> 33 For more details see the file COPYING in the source 34 distribution of Linux. 35 </para> 36 </legalnotice> 37 </bookinfo> 38 39<toc></toc> 40 41 <chapter id="vfs"> 42 <title>The Linux VFS</title> 43 <sect1 id="the_filesystem_types"><title>The Filesystem types</title> 44<!-- include/linux/fs.h --> 45<refentry id="API-enum-positive-aop-returns"> 46<refentryinfo> 47 <title>LINUX</title> 48 <productname>Kernel Hackers Manual</productname> 49 <date>July 2017</date> 50</refentryinfo> 51<refmeta> 52 <refentrytitle><phrase>enum positive_aop_returns</phrase></refentrytitle> 53 <manvolnum>9</manvolnum> 54 <refmiscinfo class="version">4.1.27</refmiscinfo> 55</refmeta> 56<refnamediv> 57 <refname>enum positive_aop_returns</refname> 58 <refpurpose> 59 aop return codes with specific semantics 60 </refpurpose> 61</refnamediv> 62<refsynopsisdiv> 63 <title>Synopsis</title> 64 <programlisting> 65enum positive_aop_returns { 66 AOP_WRITEPAGE_ACTIVATE, 67 AOP_TRUNCATED_PAGE 68}; </programlisting> 69</refsynopsisdiv> 70<refsect1> 71 <title>Constants</title> 72 <variablelist> 73 <varlistentry> <term>AOP_WRITEPAGE_ACTIVATE</term> 74 <listitem><para> 75Informs the caller that page writeback has 76completed, that the page is still locked, and 77should be considered active. The VM uses this hint 78to return the page to the active list -- it won't 79be a candidate for writeback again in the near 80future. Other callers must be careful to unlock 81the page if they get this return. Returned by 82<function>writepage</function>; 83 </para></listitem> 84 </varlistentry> 85 <varlistentry> <term>AOP_TRUNCATED_PAGE</term> 86 <listitem><para> 87The AOP method that was handed a locked page has 88unlocked it and the page might have been truncated. 89The caller should back up to acquiring a new page and 90trying again. The aop will be taking reasonable 91precautions not to livelock. If the caller held a page 92reference, it should drop it before retrying. Returned 93by <function>readpage</function>. 94 </para></listitem> 95 </varlistentry> 96 </variablelist> 97</refsect1> 98<refsect1> 99<title>Description</title> 100<para> 101 address_space_operation functions return these large constants to indicate 102 special semantics to the caller. These are much larger than the bytes in a 103 page to allow for functions that return the number of bytes operated on in a 104 given page. 105</para> 106</refsect1> 107</refentry> 108 109<refentry id="API-sb-end-write"> 110<refentryinfo> 111 <title>LINUX</title> 112 <productname>Kernel Hackers Manual</productname> 113 <date>July 2017</date> 114</refentryinfo> 115<refmeta> 116 <refentrytitle><phrase>sb_end_write</phrase></refentrytitle> 117 <manvolnum>9</manvolnum> 118 <refmiscinfo class="version">4.1.27</refmiscinfo> 119</refmeta> 120<refnamediv> 121 <refname>sb_end_write</refname> 122 <refpurpose> 123 drop write access to a superblock 124 </refpurpose> 125</refnamediv> 126<refsynopsisdiv> 127 <title>Synopsis</title> 128 <funcsynopsis><funcprototype> 129 <funcdef>void <function>sb_end_write </function></funcdef> 130 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 131 </funcprototype></funcsynopsis> 132</refsynopsisdiv> 133<refsect1> 134 <title>Arguments</title> 135 <variablelist> 136 <varlistentry> 137 <term><parameter>sb</parameter></term> 138 <listitem> 139 <para> 140 the super we wrote to 141 </para> 142 </listitem> 143 </varlistentry> 144 </variablelist> 145</refsect1> 146<refsect1> 147<title>Description</title> 148<para> 149 Decrement number of writers to the filesystem. Wake up possible waiters 150 wanting to freeze the filesystem. 151</para> 152</refsect1> 153</refentry> 154 155<refentry id="API-sb-end-pagefault"> 156<refentryinfo> 157 <title>LINUX</title> 158 <productname>Kernel Hackers Manual</productname> 159 <date>July 2017</date> 160</refentryinfo> 161<refmeta> 162 <refentrytitle><phrase>sb_end_pagefault</phrase></refentrytitle> 163 <manvolnum>9</manvolnum> 164 <refmiscinfo class="version">4.1.27</refmiscinfo> 165</refmeta> 166<refnamediv> 167 <refname>sb_end_pagefault</refname> 168 <refpurpose> 169 drop write access to a superblock from a page fault 170 </refpurpose> 171</refnamediv> 172<refsynopsisdiv> 173 <title>Synopsis</title> 174 <funcsynopsis><funcprototype> 175 <funcdef>void <function>sb_end_pagefault </function></funcdef> 176 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 177 </funcprototype></funcsynopsis> 178</refsynopsisdiv> 179<refsect1> 180 <title>Arguments</title> 181 <variablelist> 182 <varlistentry> 183 <term><parameter>sb</parameter></term> 184 <listitem> 185 <para> 186 the super we wrote to 187 </para> 188 </listitem> 189 </varlistentry> 190 </variablelist> 191</refsect1> 192<refsect1> 193<title>Description</title> 194<para> 195 Decrement number of processes handling write page fault to the filesystem. 196 Wake up possible waiters wanting to freeze the filesystem. 197</para> 198</refsect1> 199</refentry> 200 201<refentry id="API-sb-end-intwrite"> 202<refentryinfo> 203 <title>LINUX</title> 204 <productname>Kernel Hackers Manual</productname> 205 <date>July 2017</date> 206</refentryinfo> 207<refmeta> 208 <refentrytitle><phrase>sb_end_intwrite</phrase></refentrytitle> 209 <manvolnum>9</manvolnum> 210 <refmiscinfo class="version">4.1.27</refmiscinfo> 211</refmeta> 212<refnamediv> 213 <refname>sb_end_intwrite</refname> 214 <refpurpose> 215 drop write access to a superblock for internal fs purposes 216 </refpurpose> 217</refnamediv> 218<refsynopsisdiv> 219 <title>Synopsis</title> 220 <funcsynopsis><funcprototype> 221 <funcdef>void <function>sb_end_intwrite </function></funcdef> 222 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 223 </funcprototype></funcsynopsis> 224</refsynopsisdiv> 225<refsect1> 226 <title>Arguments</title> 227 <variablelist> 228 <varlistentry> 229 <term><parameter>sb</parameter></term> 230 <listitem> 231 <para> 232 the super we wrote to 233 </para> 234 </listitem> 235 </varlistentry> 236 </variablelist> 237</refsect1> 238<refsect1> 239<title>Description</title> 240<para> 241 Decrement fs-internal number of writers to the filesystem. Wake up possible 242 waiters wanting to freeze the filesystem. 243</para> 244</refsect1> 245</refentry> 246 247<refentry id="API-sb-start-write"> 248<refentryinfo> 249 <title>LINUX</title> 250 <productname>Kernel Hackers Manual</productname> 251 <date>July 2017</date> 252</refentryinfo> 253<refmeta> 254 <refentrytitle><phrase>sb_start_write</phrase></refentrytitle> 255 <manvolnum>9</manvolnum> 256 <refmiscinfo class="version">4.1.27</refmiscinfo> 257</refmeta> 258<refnamediv> 259 <refname>sb_start_write</refname> 260 <refpurpose> 261 get write access to a superblock 262 </refpurpose> 263</refnamediv> 264<refsynopsisdiv> 265 <title>Synopsis</title> 266 <funcsynopsis><funcprototype> 267 <funcdef>void <function>sb_start_write </function></funcdef> 268 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 269 </funcprototype></funcsynopsis> 270</refsynopsisdiv> 271<refsect1> 272 <title>Arguments</title> 273 <variablelist> 274 <varlistentry> 275 <term><parameter>sb</parameter></term> 276 <listitem> 277 <para> 278 the super we write to 279 </para> 280 </listitem> 281 </varlistentry> 282 </variablelist> 283</refsect1> 284<refsect1> 285<title>Description</title> 286<para> 287 When a process wants to write data or metadata to a file system (i.e. dirty 288 a page or an inode), it should embed the operation in a <function>sb_start_write</function> - 289 <function>sb_end_write</function> pair to get exclusion against file system freezing. This 290 function increments number of writers preventing freezing. If the file 291 system is already frozen, the function waits until the file system is 292 thawed. 293 </para><para> 294 295 Since freeze protection behaves as a lock, users have to preserve 296 ordering of freeze protection and other filesystem locks. Generally, 297 freeze protection should be the outermost lock. In particular, we have: 298 </para><para> 299 300 sb_start_write 301 -> i_mutex (write path, truncate, directory ops, ...) 302 -> s_umount (freeze_super, thaw_super) 303</para> 304</refsect1> 305</refentry> 306 307<refentry id="API-sb-start-pagefault"> 308<refentryinfo> 309 <title>LINUX</title> 310 <productname>Kernel Hackers Manual</productname> 311 <date>July 2017</date> 312</refentryinfo> 313<refmeta> 314 <refentrytitle><phrase>sb_start_pagefault</phrase></refentrytitle> 315 <manvolnum>9</manvolnum> 316 <refmiscinfo class="version">4.1.27</refmiscinfo> 317</refmeta> 318<refnamediv> 319 <refname>sb_start_pagefault</refname> 320 <refpurpose> 321 get write access to a superblock from a page fault 322 </refpurpose> 323</refnamediv> 324<refsynopsisdiv> 325 <title>Synopsis</title> 326 <funcsynopsis><funcprototype> 327 <funcdef>void <function>sb_start_pagefault </function></funcdef> 328 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 329 </funcprototype></funcsynopsis> 330</refsynopsisdiv> 331<refsect1> 332 <title>Arguments</title> 333 <variablelist> 334 <varlistentry> 335 <term><parameter>sb</parameter></term> 336 <listitem> 337 <para> 338 the super we write to 339 </para> 340 </listitem> 341 </varlistentry> 342 </variablelist> 343</refsect1> 344<refsect1> 345<title>Description</title> 346<para> 347 When a process starts handling write page fault, it should embed the 348 operation into <function>sb_start_pagefault</function> - <function>sb_end_pagefault</function> pair to get 349 exclusion against file system freezing. This is needed since the page fault 350 is going to dirty a page. This function increments number of running page 351 faults preventing freezing. If the file system is already frozen, the 352 function waits until the file system is thawed. 353 </para><para> 354 355 Since page fault freeze protection behaves as a lock, users have to preserve 356 ordering of freeze protection and other filesystem locks. It is advised to 357 put <function>sb_start_pagefault</function> close to mmap_sem in lock ordering. Page fault 358</para> 359</refsect1> 360<refsect1> 361<title>handling code implies lock dependency</title> 362<para> 363 </para><para> 364 365 mmap_sem 366 -> sb_start_pagefault 367</para> 368</refsect1> 369</refentry> 370 371<refentry id="API-inode-inc-iversion"> 372<refentryinfo> 373 <title>LINUX</title> 374 <productname>Kernel Hackers Manual</productname> 375 <date>July 2017</date> 376</refentryinfo> 377<refmeta> 378 <refentrytitle><phrase>inode_inc_iversion</phrase></refentrytitle> 379 <manvolnum>9</manvolnum> 380 <refmiscinfo class="version">4.1.27</refmiscinfo> 381</refmeta> 382<refnamediv> 383 <refname>inode_inc_iversion</refname> 384 <refpurpose> 385 increments i_version 386 </refpurpose> 387</refnamediv> 388<refsynopsisdiv> 389 <title>Synopsis</title> 390 <funcsynopsis><funcprototype> 391 <funcdef>void <function>inode_inc_iversion </function></funcdef> 392 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 393 </funcprototype></funcsynopsis> 394</refsynopsisdiv> 395<refsect1> 396 <title>Arguments</title> 397 <variablelist> 398 <varlistentry> 399 <term><parameter>inode</parameter></term> 400 <listitem> 401 <para> 402 inode that need to be updated 403 </para> 404 </listitem> 405 </varlistentry> 406 </variablelist> 407</refsect1> 408<refsect1> 409<title>Description</title> 410<para> 411 Every time the inode is modified, the i_version field will be incremented. 412 The filesystem has to be mounted with i_version flag 413</para> 414</refsect1> 415</refentry> 416 417 </sect1> 418 <sect1 id="the_directory_cache"><title>The Directory Cache</title> 419<!-- fs/dcache.c --> 420<refentry id="API---d-drop"> 421<refentryinfo> 422 <title>LINUX</title> 423 <productname>Kernel Hackers Manual</productname> 424 <date>July 2017</date> 425</refentryinfo> 426<refmeta> 427 <refentrytitle><phrase>__d_drop</phrase></refentrytitle> 428 <manvolnum>9</manvolnum> 429 <refmiscinfo class="version">4.1.27</refmiscinfo> 430</refmeta> 431<refnamediv> 432 <refname>__d_drop</refname> 433 <refpurpose> 434 drop a dentry 435 </refpurpose> 436</refnamediv> 437<refsynopsisdiv> 438 <title>Synopsis</title> 439 <funcsynopsis><funcprototype> 440 <funcdef>void <function>__d_drop </function></funcdef> 441 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 442 </funcprototype></funcsynopsis> 443</refsynopsisdiv> 444<refsect1> 445 <title>Arguments</title> 446 <variablelist> 447 <varlistentry> 448 <term><parameter>dentry</parameter></term> 449 <listitem> 450 <para> 451 dentry to drop 452 </para> 453 </listitem> 454 </varlistentry> 455 </variablelist> 456</refsect1> 457<refsect1> 458<title>Description</title> 459<para> 460 <function>d_drop</function> unhashes the entry from the parent dentry hashes, so that it won't 461 be found through a VFS lookup any more. Note that this is different from 462 deleting the dentry - d_delete will try to mark the dentry negative if 463 possible, giving a successful _negative_ lookup, while d_drop will 464 just make the cache lookup fail. 465 </para><para> 466 467 <function>d_drop</function> is used mainly for stuff that wants to invalidate a dentry for some 468 reason (NFS timeouts or autofs deletes). 469 </para><para> 470 471 __d_drop requires dentry->d_lock. 472</para> 473</refsect1> 474</refentry> 475 476<refentry id="API-shrink-dcache-sb"> 477<refentryinfo> 478 <title>LINUX</title> 479 <productname>Kernel Hackers Manual</productname> 480 <date>July 2017</date> 481</refentryinfo> 482<refmeta> 483 <refentrytitle><phrase>shrink_dcache_sb</phrase></refentrytitle> 484 <manvolnum>9</manvolnum> 485 <refmiscinfo class="version">4.1.27</refmiscinfo> 486</refmeta> 487<refnamediv> 488 <refname>shrink_dcache_sb</refname> 489 <refpurpose> 490 shrink dcache for a superblock 491 </refpurpose> 492</refnamediv> 493<refsynopsisdiv> 494 <title>Synopsis</title> 495 <funcsynopsis><funcprototype> 496 <funcdef>void <function>shrink_dcache_sb </function></funcdef> 497 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 498 </funcprototype></funcsynopsis> 499</refsynopsisdiv> 500<refsect1> 501 <title>Arguments</title> 502 <variablelist> 503 <varlistentry> 504 <term><parameter>sb</parameter></term> 505 <listitem> 506 <para> 507 superblock 508 </para> 509 </listitem> 510 </varlistentry> 511 </variablelist> 512</refsect1> 513<refsect1> 514<title>Description</title> 515<para> 516 Shrink the dcache for the specified super block. This is used to free 517 the dcache before unmounting a file system. 518</para> 519</refsect1> 520</refentry> 521 522<refentry id="API-have-submounts"> 523<refentryinfo> 524 <title>LINUX</title> 525 <productname>Kernel Hackers Manual</productname> 526 <date>July 2017</date> 527</refentryinfo> 528<refmeta> 529 <refentrytitle><phrase>have_submounts</phrase></refentrytitle> 530 <manvolnum>9</manvolnum> 531 <refmiscinfo class="version">4.1.27</refmiscinfo> 532</refmeta> 533<refnamediv> 534 <refname>have_submounts</refname> 535 <refpurpose> 536 check for mounts over a dentry 537 </refpurpose> 538</refnamediv> 539<refsynopsisdiv> 540 <title>Synopsis</title> 541 <funcsynopsis><funcprototype> 542 <funcdef>int <function>have_submounts </function></funcdef> 543 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 544 </funcprototype></funcsynopsis> 545</refsynopsisdiv> 546<refsect1> 547 <title>Arguments</title> 548 <variablelist> 549 <varlistentry> 550 <term><parameter>parent</parameter></term> 551 <listitem> 552 <para> 553 dentry to check. 554 </para> 555 </listitem> 556 </varlistentry> 557 </variablelist> 558</refsect1> 559<refsect1> 560<title>Description</title> 561<para> 562 Return true if the parent or its subdirectories contain 563 a mount point 564</para> 565</refsect1> 566</refentry> 567 568<refentry id="API-shrink-dcache-parent"> 569<refentryinfo> 570 <title>LINUX</title> 571 <productname>Kernel Hackers Manual</productname> 572 <date>July 2017</date> 573</refentryinfo> 574<refmeta> 575 <refentrytitle><phrase>shrink_dcache_parent</phrase></refentrytitle> 576 <manvolnum>9</manvolnum> 577 <refmiscinfo class="version">4.1.27</refmiscinfo> 578</refmeta> 579<refnamediv> 580 <refname>shrink_dcache_parent</refname> 581 <refpurpose> 582 prune dcache 583 </refpurpose> 584</refnamediv> 585<refsynopsisdiv> 586 <title>Synopsis</title> 587 <funcsynopsis><funcprototype> 588 <funcdef>void <function>shrink_dcache_parent </function></funcdef> 589 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 590 </funcprototype></funcsynopsis> 591</refsynopsisdiv> 592<refsect1> 593 <title>Arguments</title> 594 <variablelist> 595 <varlistentry> 596 <term><parameter>parent</parameter></term> 597 <listitem> 598 <para> 599 parent of entries to prune 600 </para> 601 </listitem> 602 </varlistentry> 603 </variablelist> 604</refsect1> 605<refsect1> 606<title>Description</title> 607<para> 608 Prune the dcache to remove unused children of the parent dentry. 609</para> 610</refsect1> 611</refentry> 612 613<refentry id="API-d-invalidate"> 614<refentryinfo> 615 <title>LINUX</title> 616 <productname>Kernel Hackers Manual</productname> 617 <date>July 2017</date> 618</refentryinfo> 619<refmeta> 620 <refentrytitle><phrase>d_invalidate</phrase></refentrytitle> 621 <manvolnum>9</manvolnum> 622 <refmiscinfo class="version">4.1.27</refmiscinfo> 623</refmeta> 624<refnamediv> 625 <refname>d_invalidate</refname> 626 <refpurpose> 627 detach submounts, prune dcache, and drop 628 </refpurpose> 629</refnamediv> 630<refsynopsisdiv> 631 <title>Synopsis</title> 632 <funcsynopsis><funcprototype> 633 <funcdef>void <function>d_invalidate </function></funcdef> 634 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 635 </funcprototype></funcsynopsis> 636</refsynopsisdiv> 637<refsect1> 638 <title>Arguments</title> 639 <variablelist> 640 <varlistentry> 641 <term><parameter>dentry</parameter></term> 642 <listitem> 643 <para> 644 dentry to invalidate (aka detach, prune and drop) 645 </para> 646 </listitem> 647 </varlistentry> 648 </variablelist> 649</refsect1> 650<refsect1> 651<title>Description</title> 652<para> 653 no dcache lock. 654 </para><para> 655 656 The final d_drop is done as an atomic operation relative to 657 rename_lock ensuring there are no races with d_set_mounted. This 658 ensures there are no unhashed dentries on the path to a mountpoint. 659</para> 660</refsect1> 661</refentry> 662 663<refentry id="API-d-alloc"> 664<refentryinfo> 665 <title>LINUX</title> 666 <productname>Kernel Hackers Manual</productname> 667 <date>July 2017</date> 668</refentryinfo> 669<refmeta> 670 <refentrytitle><phrase>d_alloc</phrase></refentrytitle> 671 <manvolnum>9</manvolnum> 672 <refmiscinfo class="version">4.1.27</refmiscinfo> 673</refmeta> 674<refnamediv> 675 <refname>d_alloc</refname> 676 <refpurpose> 677 allocate a dcache entry 678 </refpurpose> 679</refnamediv> 680<refsynopsisdiv> 681 <title>Synopsis</title> 682 <funcsynopsis><funcprototype> 683 <funcdef>struct dentry * <function>d_alloc </function></funcdef> 684 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 685 <paramdef>const struct qstr * <parameter>name</parameter></paramdef> 686 </funcprototype></funcsynopsis> 687</refsynopsisdiv> 688<refsect1> 689 <title>Arguments</title> 690 <variablelist> 691 <varlistentry> 692 <term><parameter>parent</parameter></term> 693 <listitem> 694 <para> 695 parent of entry to allocate 696 </para> 697 </listitem> 698 </varlistentry> 699 <varlistentry> 700 <term><parameter>name</parameter></term> 701 <listitem> 702 <para> 703 qstr of the name 704 </para> 705 </listitem> 706 </varlistentry> 707 </variablelist> 708</refsect1> 709<refsect1> 710<title>Description</title> 711<para> 712 Allocates a dentry. It returns <constant>NULL</constant> if there is insufficient memory 713 available. On a success the dentry is returned. The name passed in is 714 copied and the copy passed in may be reused after this call. 715</para> 716</refsect1> 717</refentry> 718 719<refentry id="API-d-alloc-pseudo"> 720<refentryinfo> 721 <title>LINUX</title> 722 <productname>Kernel Hackers Manual</productname> 723 <date>July 2017</date> 724</refentryinfo> 725<refmeta> 726 <refentrytitle><phrase>d_alloc_pseudo</phrase></refentrytitle> 727 <manvolnum>9</manvolnum> 728 <refmiscinfo class="version">4.1.27</refmiscinfo> 729</refmeta> 730<refnamediv> 731 <refname>d_alloc_pseudo</refname> 732 <refpurpose> 733 allocate a dentry (for lookup-less filesystems) 734 </refpurpose> 735</refnamediv> 736<refsynopsisdiv> 737 <title>Synopsis</title> 738 <funcsynopsis><funcprototype> 739 <funcdef>struct dentry * <function>d_alloc_pseudo </function></funcdef> 740 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 741 <paramdef>const struct qstr * <parameter>name</parameter></paramdef> 742 </funcprototype></funcsynopsis> 743</refsynopsisdiv> 744<refsect1> 745 <title>Arguments</title> 746 <variablelist> 747 <varlistentry> 748 <term><parameter>sb</parameter></term> 749 <listitem> 750 <para> 751 the superblock 752 </para> 753 </listitem> 754 </varlistentry> 755 <varlistentry> 756 <term><parameter>name</parameter></term> 757 <listitem> 758 <para> 759 qstr of the name 760 </para> 761 </listitem> 762 </varlistentry> 763 </variablelist> 764</refsect1> 765<refsect1> 766<title>Description</title> 767<para> 768 For a filesystem that just pins its dentries in memory and never 769 performs lookups at all, return an unhashed IS_ROOT dentry. 770</para> 771</refsect1> 772</refentry> 773 774<refentry id="API-d-instantiate"> 775<refentryinfo> 776 <title>LINUX</title> 777 <productname>Kernel Hackers Manual</productname> 778 <date>July 2017</date> 779</refentryinfo> 780<refmeta> 781 <refentrytitle><phrase>d_instantiate</phrase></refentrytitle> 782 <manvolnum>9</manvolnum> 783 <refmiscinfo class="version">4.1.27</refmiscinfo> 784</refmeta> 785<refnamediv> 786 <refname>d_instantiate</refname> 787 <refpurpose> 788 fill in inode information for a dentry 789 </refpurpose> 790</refnamediv> 791<refsynopsisdiv> 792 <title>Synopsis</title> 793 <funcsynopsis><funcprototype> 794 <funcdef>void <function>d_instantiate </function></funcdef> 795 <paramdef>struct dentry * <parameter>entry</parameter></paramdef> 796 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 797 </funcprototype></funcsynopsis> 798</refsynopsisdiv> 799<refsect1> 800 <title>Arguments</title> 801 <variablelist> 802 <varlistentry> 803 <term><parameter>entry</parameter></term> 804 <listitem> 805 <para> 806 dentry to complete 807 </para> 808 </listitem> 809 </varlistentry> 810 <varlistentry> 811 <term><parameter>inode</parameter></term> 812 <listitem> 813 <para> 814 inode to attach to this dentry 815 </para> 816 </listitem> 817 </varlistentry> 818 </variablelist> 819</refsect1> 820<refsect1> 821<title>Description</title> 822<para> 823 Fill in inode information in the entry. 824 </para><para> 825 826 This turns negative dentries into productive full members 827 of society. 828 </para><para> 829 830 NOTE! This assumes that the inode count has been incremented 831 (or otherwise set) by the caller to indicate that it is now 832 in use by the dcache. 833</para> 834</refsect1> 835</refentry> 836 837<refentry id="API-d-instantiate-no-diralias"> 838<refentryinfo> 839 <title>LINUX</title> 840 <productname>Kernel Hackers Manual</productname> 841 <date>July 2017</date> 842</refentryinfo> 843<refmeta> 844 <refentrytitle><phrase>d_instantiate_no_diralias</phrase></refentrytitle> 845 <manvolnum>9</manvolnum> 846 <refmiscinfo class="version">4.1.27</refmiscinfo> 847</refmeta> 848<refnamediv> 849 <refname>d_instantiate_no_diralias</refname> 850 <refpurpose> 851 instantiate a non-aliased dentry 852 </refpurpose> 853</refnamediv> 854<refsynopsisdiv> 855 <title>Synopsis</title> 856 <funcsynopsis><funcprototype> 857 <funcdef>int <function>d_instantiate_no_diralias </function></funcdef> 858 <paramdef>struct dentry * <parameter>entry</parameter></paramdef> 859 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 860 </funcprototype></funcsynopsis> 861</refsynopsisdiv> 862<refsect1> 863 <title>Arguments</title> 864 <variablelist> 865 <varlistentry> 866 <term><parameter>entry</parameter></term> 867 <listitem> 868 <para> 869 dentry to complete 870 </para> 871 </listitem> 872 </varlistentry> 873 <varlistentry> 874 <term><parameter>inode</parameter></term> 875 <listitem> 876 <para> 877 inode to attach to this dentry 878 </para> 879 </listitem> 880 </varlistentry> 881 </variablelist> 882</refsect1> 883<refsect1> 884<title>Description</title> 885<para> 886 Fill in inode information in the entry. If a directory alias is found, then 887 return an error (and drop inode). Together with <function>d_materialise_unique</function> this 888 guarantees that a directory inode may never have more than one alias. 889</para> 890</refsect1> 891</refentry> 892 893<refentry id="API-d-find-any-alias"> 894<refentryinfo> 895 <title>LINUX</title> 896 <productname>Kernel Hackers Manual</productname> 897 <date>July 2017</date> 898</refentryinfo> 899<refmeta> 900 <refentrytitle><phrase>d_find_any_alias</phrase></refentrytitle> 901 <manvolnum>9</manvolnum> 902 <refmiscinfo class="version">4.1.27</refmiscinfo> 903</refmeta> 904<refnamediv> 905 <refname>d_find_any_alias</refname> 906 <refpurpose> 907 find any alias for a given inode 908 </refpurpose> 909</refnamediv> 910<refsynopsisdiv> 911 <title>Synopsis</title> 912 <funcsynopsis><funcprototype> 913 <funcdef>struct dentry * <function>d_find_any_alias </function></funcdef> 914 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 915 </funcprototype></funcsynopsis> 916</refsynopsisdiv> 917<refsect1> 918 <title>Arguments</title> 919 <variablelist> 920 <varlistentry> 921 <term><parameter>inode</parameter></term> 922 <listitem> 923 <para> 924 inode to find an alias for 925 </para> 926 </listitem> 927 </varlistentry> 928 </variablelist> 929</refsect1> 930<refsect1> 931<title>Description</title> 932<para> 933 If any aliases exist for the given inode, take and return a 934 reference for one of them. If no aliases exist, return <constant>NULL</constant>. 935</para> 936</refsect1> 937</refentry> 938 939<refentry id="API-d-obtain-alias"> 940<refentryinfo> 941 <title>LINUX</title> 942 <productname>Kernel Hackers Manual</productname> 943 <date>July 2017</date> 944</refentryinfo> 945<refmeta> 946 <refentrytitle><phrase>d_obtain_alias</phrase></refentrytitle> 947 <manvolnum>9</manvolnum> 948 <refmiscinfo class="version">4.1.27</refmiscinfo> 949</refmeta> 950<refnamediv> 951 <refname>d_obtain_alias</refname> 952 <refpurpose> 953 find or allocate a DISCONNECTED dentry for a given inode 954 </refpurpose> 955</refnamediv> 956<refsynopsisdiv> 957 <title>Synopsis</title> 958 <funcsynopsis><funcprototype> 959 <funcdef>struct dentry * <function>d_obtain_alias </function></funcdef> 960 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 961 </funcprototype></funcsynopsis> 962</refsynopsisdiv> 963<refsect1> 964 <title>Arguments</title> 965 <variablelist> 966 <varlistentry> 967 <term><parameter>inode</parameter></term> 968 <listitem> 969 <para> 970 inode to allocate the dentry for 971 </para> 972 </listitem> 973 </varlistentry> 974 </variablelist> 975</refsect1> 976<refsect1> 977<title>Description</title> 978<para> 979 Obtain a dentry for an inode resulting from NFS filehandle conversion or 980 similar open by handle operations. The returned dentry may be anonymous, 981 or may have a full name (if the inode was already in the cache). 982 </para><para> 983 984 When called on a directory inode, we must ensure that the inode only ever 985 has one dentry. If a dentry is found, that is returned instead of 986 allocating a new one. 987 </para><para> 988 989 On successful return, the reference to the inode has been transferred 990 to the dentry. In case of an error the reference on the inode is released. 991 To make it easier to use in export operations a <constant>NULL</constant> or IS_ERR inode may 992 be passed in and the error will be propagated to the return value, 993 with a <constant>NULL</constant> <parameter>inode</parameter> replaced by ERR_PTR(-ESTALE). 994</para> 995</refsect1> 996</refentry> 997 998<refentry id="API-d-obtain-root"> 999<refentryinfo> 1000 <title>LINUX</title> 1001 <productname>Kernel Hackers Manual</productname> 1002 <date>July 2017</date> 1003</refentryinfo> 1004<refmeta> 1005 <refentrytitle><phrase>d_obtain_root</phrase></refentrytitle> 1006 <manvolnum>9</manvolnum> 1007 <refmiscinfo class="version">4.1.27</refmiscinfo> 1008</refmeta> 1009<refnamediv> 1010 <refname>d_obtain_root</refname> 1011 <refpurpose> 1012 find or allocate a dentry for a given inode 1013 </refpurpose> 1014</refnamediv> 1015<refsynopsisdiv> 1016 <title>Synopsis</title> 1017 <funcsynopsis><funcprototype> 1018 <funcdef>struct dentry * <function>d_obtain_root </function></funcdef> 1019 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 1020 </funcprototype></funcsynopsis> 1021</refsynopsisdiv> 1022<refsect1> 1023 <title>Arguments</title> 1024 <variablelist> 1025 <varlistentry> 1026 <term><parameter>inode</parameter></term> 1027 <listitem> 1028 <para> 1029 inode to allocate the dentry for 1030 </para> 1031 </listitem> 1032 </varlistentry> 1033 </variablelist> 1034</refsect1> 1035<refsect1> 1036<title>Description</title> 1037<para> 1038 Obtain an IS_ROOT dentry for the root of a filesystem. 1039 </para><para> 1040 1041 We must ensure that directory inodes only ever have one dentry. If a 1042 dentry is found, that is returned instead of allocating a new one. 1043 </para><para> 1044 1045 On successful return, the reference to the inode has been transferred 1046 to the dentry. In case of an error the reference on the inode is 1047 released. A <constant>NULL</constant> or IS_ERR inode may be passed in and will be the 1048 error will be propagate to the return value, with a <constant>NULL</constant> <parameter>inode</parameter> 1049 replaced by ERR_PTR(-ESTALE). 1050</para> 1051</refsect1> 1052</refentry> 1053 1054<refentry id="API-d-add-ci"> 1055<refentryinfo> 1056 <title>LINUX</title> 1057 <productname>Kernel Hackers Manual</productname> 1058 <date>July 2017</date> 1059</refentryinfo> 1060<refmeta> 1061 <refentrytitle><phrase>d_add_ci</phrase></refentrytitle> 1062 <manvolnum>9</manvolnum> 1063 <refmiscinfo class="version">4.1.27</refmiscinfo> 1064</refmeta> 1065<refnamediv> 1066 <refname>d_add_ci</refname> 1067 <refpurpose> 1068 lookup or allocate new dentry with case-exact name 1069 </refpurpose> 1070</refnamediv> 1071<refsynopsisdiv> 1072 <title>Synopsis</title> 1073 <funcsynopsis><funcprototype> 1074 <funcdef>struct dentry * <function>d_add_ci </function></funcdef> 1075 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 1076 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 1077 <paramdef>struct qstr * <parameter>name</parameter></paramdef> 1078 </funcprototype></funcsynopsis> 1079</refsynopsisdiv> 1080<refsect1> 1081 <title>Arguments</title> 1082 <variablelist> 1083 <varlistentry> 1084 <term><parameter>dentry</parameter></term> 1085 <listitem> 1086 <para> 1087 the negative dentry that was passed to the parent's lookup func 1088 </para> 1089 </listitem> 1090 </varlistentry> 1091 <varlistentry> 1092 <term><parameter>inode</parameter></term> 1093 <listitem> 1094 <para> 1095 the inode case-insensitive lookup has found 1096 </para> 1097 </listitem> 1098 </varlistentry> 1099 <varlistentry> 1100 <term><parameter>name</parameter></term> 1101 <listitem> 1102 <para> 1103 the case-exact name to be associated with the returned dentry 1104 </para> 1105 </listitem> 1106 </varlistentry> 1107 </variablelist> 1108</refsect1> 1109<refsect1> 1110<title>Description</title> 1111<para> 1112 This is to avoid filling the dcache with case-insensitive names to the 1113 same inode, only the actual correct case is stored in the dcache for 1114 case-insensitive filesystems. 1115 </para><para> 1116 1117 For a case-insensitive lookup match and if the the case-exact dentry 1118 already exists in in the dcache, use it and return it. 1119 </para><para> 1120 1121 If no entry exists with the exact case name, allocate new dentry with 1122 the exact case, and return the spliced entry. 1123</para> 1124</refsect1> 1125</refentry> 1126 1127<refentry id="API-d-lookup"> 1128<refentryinfo> 1129 <title>LINUX</title> 1130 <productname>Kernel Hackers Manual</productname> 1131 <date>July 2017</date> 1132</refentryinfo> 1133<refmeta> 1134 <refentrytitle><phrase>d_lookup</phrase></refentrytitle> 1135 <manvolnum>9</manvolnum> 1136 <refmiscinfo class="version">4.1.27</refmiscinfo> 1137</refmeta> 1138<refnamediv> 1139 <refname>d_lookup</refname> 1140 <refpurpose> 1141 search for a dentry 1142 </refpurpose> 1143</refnamediv> 1144<refsynopsisdiv> 1145 <title>Synopsis</title> 1146 <funcsynopsis><funcprototype> 1147 <funcdef>struct dentry * <function>d_lookup </function></funcdef> 1148 <paramdef>const struct dentry * <parameter>parent</parameter></paramdef> 1149 <paramdef>const struct qstr * <parameter>name</parameter></paramdef> 1150 </funcprototype></funcsynopsis> 1151</refsynopsisdiv> 1152<refsect1> 1153 <title>Arguments</title> 1154 <variablelist> 1155 <varlistentry> 1156 <term><parameter>parent</parameter></term> 1157 <listitem> 1158 <para> 1159 parent dentry 1160 </para> 1161 </listitem> 1162 </varlistentry> 1163 <varlistentry> 1164 <term><parameter>name</parameter></term> 1165 <listitem> 1166 <para> 1167 qstr of name we wish to find 1168 </para> 1169 </listitem> 1170 </varlistentry> 1171 </variablelist> 1172</refsect1> 1173<refsect1> 1174<title>Returns</title> 1175<para> 1176 dentry, or NULL 1177 </para><para> 1178 1179 d_lookup searches the children of the parent dentry for the name in 1180 question. If the dentry is found its reference count is incremented and the 1181 dentry is returned. The caller must use dput to free the entry when it has 1182 finished using it. <constant>NULL</constant> is returned if the dentry does not exist. 1183</para> 1184</refsect1> 1185</refentry> 1186 1187<refentry id="API-d-hash-and-lookup"> 1188<refentryinfo> 1189 <title>LINUX</title> 1190 <productname>Kernel Hackers Manual</productname> 1191 <date>July 2017</date> 1192</refentryinfo> 1193<refmeta> 1194 <refentrytitle><phrase>d_hash_and_lookup</phrase></refentrytitle> 1195 <manvolnum>9</manvolnum> 1196 <refmiscinfo class="version">4.1.27</refmiscinfo> 1197</refmeta> 1198<refnamediv> 1199 <refname>d_hash_and_lookup</refname> 1200 <refpurpose> 1201 hash the qstr then search for a dentry 1202 </refpurpose> 1203</refnamediv> 1204<refsynopsisdiv> 1205 <title>Synopsis</title> 1206 <funcsynopsis><funcprototype> 1207 <funcdef>struct dentry * <function>d_hash_and_lookup </function></funcdef> 1208 <paramdef>struct dentry * <parameter>dir</parameter></paramdef> 1209 <paramdef>struct qstr * <parameter>name</parameter></paramdef> 1210 </funcprototype></funcsynopsis> 1211</refsynopsisdiv> 1212<refsect1> 1213 <title>Arguments</title> 1214 <variablelist> 1215 <varlistentry> 1216 <term><parameter>dir</parameter></term> 1217 <listitem> 1218 <para> 1219 Directory to search in 1220 </para> 1221 </listitem> 1222 </varlistentry> 1223 <varlistentry> 1224 <term><parameter>name</parameter></term> 1225 <listitem> 1226 <para> 1227 qstr of name we wish to find 1228 </para> 1229 </listitem> 1230 </varlistentry> 1231 </variablelist> 1232</refsect1> 1233<refsect1> 1234<title>Description</title> 1235<para> 1236 On lookup failure NULL is returned; on bad name - ERR_PTR(-error) 1237</para> 1238</refsect1> 1239</refentry> 1240 1241<refentry id="API-d-delete"> 1242<refentryinfo> 1243 <title>LINUX</title> 1244 <productname>Kernel Hackers Manual</productname> 1245 <date>July 2017</date> 1246</refentryinfo> 1247<refmeta> 1248 <refentrytitle><phrase>d_delete</phrase></refentrytitle> 1249 <manvolnum>9</manvolnum> 1250 <refmiscinfo class="version">4.1.27</refmiscinfo> 1251</refmeta> 1252<refnamediv> 1253 <refname>d_delete</refname> 1254 <refpurpose> 1255 delete a dentry 1256 </refpurpose> 1257</refnamediv> 1258<refsynopsisdiv> 1259 <title>Synopsis</title> 1260 <funcsynopsis><funcprototype> 1261 <funcdef>void <function>d_delete </function></funcdef> 1262 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 1263 </funcprototype></funcsynopsis> 1264</refsynopsisdiv> 1265<refsect1> 1266 <title>Arguments</title> 1267 <variablelist> 1268 <varlistentry> 1269 <term><parameter>dentry</parameter></term> 1270 <listitem> 1271 <para> 1272 The dentry to delete 1273 </para> 1274 </listitem> 1275 </varlistentry> 1276 </variablelist> 1277</refsect1> 1278<refsect1> 1279<title>Description</title> 1280<para> 1281 Turn the dentry into a negative dentry if possible, otherwise 1282 remove it from the hash queues so it can be deleted later 1283</para> 1284</refsect1> 1285</refentry> 1286 1287<refentry id="API-d-rehash"> 1288<refentryinfo> 1289 <title>LINUX</title> 1290 <productname>Kernel Hackers Manual</productname> 1291 <date>July 2017</date> 1292</refentryinfo> 1293<refmeta> 1294 <refentrytitle><phrase>d_rehash</phrase></refentrytitle> 1295 <manvolnum>9</manvolnum> 1296 <refmiscinfo class="version">4.1.27</refmiscinfo> 1297</refmeta> 1298<refnamediv> 1299 <refname>d_rehash</refname> 1300 <refpurpose> 1301 add an entry back to the hash 1302 </refpurpose> 1303</refnamediv> 1304<refsynopsisdiv> 1305 <title>Synopsis</title> 1306 <funcsynopsis><funcprototype> 1307 <funcdef>void <function>d_rehash </function></funcdef> 1308 <paramdef>struct dentry * <parameter>entry</parameter></paramdef> 1309 </funcprototype></funcsynopsis> 1310</refsynopsisdiv> 1311<refsect1> 1312 <title>Arguments</title> 1313 <variablelist> 1314 <varlistentry> 1315 <term><parameter>entry</parameter></term> 1316 <listitem> 1317 <para> 1318 dentry to add to the hash 1319 </para> 1320 </listitem> 1321 </varlistentry> 1322 </variablelist> 1323</refsect1> 1324<refsect1> 1325<title>Description</title> 1326<para> 1327 Adds a dentry to the hash according to its name. 1328</para> 1329</refsect1> 1330</refentry> 1331 1332<refentry id="API-dentry-update-name-case"> 1333<refentryinfo> 1334 <title>LINUX</title> 1335 <productname>Kernel Hackers Manual</productname> 1336 <date>July 2017</date> 1337</refentryinfo> 1338<refmeta> 1339 <refentrytitle><phrase>dentry_update_name_case</phrase></refentrytitle> 1340 <manvolnum>9</manvolnum> 1341 <refmiscinfo class="version">4.1.27</refmiscinfo> 1342</refmeta> 1343<refnamediv> 1344 <refname>dentry_update_name_case</refname> 1345 <refpurpose> 1346 update case insensitive dentry with a new name 1347 </refpurpose> 1348</refnamediv> 1349<refsynopsisdiv> 1350 <title>Synopsis</title> 1351 <funcsynopsis><funcprototype> 1352 <funcdef>void <function>dentry_update_name_case </function></funcdef> 1353 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 1354 <paramdef>struct qstr * <parameter>name</parameter></paramdef> 1355 </funcprototype></funcsynopsis> 1356</refsynopsisdiv> 1357<refsect1> 1358 <title>Arguments</title> 1359 <variablelist> 1360 <varlistentry> 1361 <term><parameter>dentry</parameter></term> 1362 <listitem> 1363 <para> 1364 dentry to be updated 1365 </para> 1366 </listitem> 1367 </varlistentry> 1368 <varlistentry> 1369 <term><parameter>name</parameter></term> 1370 <listitem> 1371 <para> 1372 new name 1373 </para> 1374 </listitem> 1375 </varlistentry> 1376 </variablelist> 1377</refsect1> 1378<refsect1> 1379<title>Description</title> 1380<para> 1381 Update a case insensitive dentry with new case of name. 1382 </para><para> 1383 1384 dentry must have been returned by d_lookup with name <parameter>name</parameter>. Old and new 1385 name lengths must match (ie. no d_compare which allows mismatched name 1386 lengths). 1387 </para><para> 1388 1389 Parent inode i_mutex must be held over d_lookup and into this call (to 1390 keep renames and concurrent inserts, and readdir(2) away). 1391</para> 1392</refsect1> 1393</refentry> 1394 1395<refentry id="API-d-splice-alias"> 1396<refentryinfo> 1397 <title>LINUX</title> 1398 <productname>Kernel Hackers Manual</productname> 1399 <date>July 2017</date> 1400</refentryinfo> 1401<refmeta> 1402 <refentrytitle><phrase>d_splice_alias</phrase></refentrytitle> 1403 <manvolnum>9</manvolnum> 1404 <refmiscinfo class="version">4.1.27</refmiscinfo> 1405</refmeta> 1406<refnamediv> 1407 <refname>d_splice_alias</refname> 1408 <refpurpose> 1409 splice a disconnected dentry into the tree if one exists 1410 </refpurpose> 1411</refnamediv> 1412<refsynopsisdiv> 1413 <title>Synopsis</title> 1414 <funcsynopsis><funcprototype> 1415 <funcdef>struct dentry * <function>d_splice_alias </function></funcdef> 1416 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 1417 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 1418 </funcprototype></funcsynopsis> 1419</refsynopsisdiv> 1420<refsect1> 1421 <title>Arguments</title> 1422 <variablelist> 1423 <varlistentry> 1424 <term><parameter>inode</parameter></term> 1425 <listitem> 1426 <para> 1427 the inode which may have a disconnected dentry 1428 </para> 1429 </listitem> 1430 </varlistentry> 1431 <varlistentry> 1432 <term><parameter>dentry</parameter></term> 1433 <listitem> 1434 <para> 1435 a negative dentry which we want to point to the inode. 1436 </para> 1437 </listitem> 1438 </varlistentry> 1439 </variablelist> 1440</refsect1> 1441<refsect1> 1442<title>Description</title> 1443<para> 1444 If inode is a directory and has an IS_ROOT alias, then d_move that in 1445 place of the given dentry and return it, else simply d_add the inode 1446 to the dentry and return NULL. 1447 </para><para> 1448 1449 If a non-IS_ROOT directory is found, the filesystem is corrupt, and 1450</para> 1451</refsect1> 1452<refsect1> 1453<title>we should error out</title> 1454<para> 1455 directories can't have multiple aliases. 1456 </para><para> 1457 1458 This is needed in the lookup routine of any filesystem that is exportable 1459 (via knfsd) so that we can build dcache paths to directories effectively. 1460 </para><para> 1461 1462 If a dentry was found and moved, then it is returned. Otherwise NULL 1463 is returned. This matches the expected return value of ->lookup. 1464 </para><para> 1465 1466 Cluster filesystems may call this function with a negative, hashed dentry. 1467 In that case, we know that the inode will be a regular file, and also this 1468 will only occur during atomic_open. So we need to check for the dentry 1469 being already hashed only in the final case. 1470</para> 1471</refsect1> 1472</refentry> 1473 1474<refentry id="API-d-path"> 1475<refentryinfo> 1476 <title>LINUX</title> 1477 <productname>Kernel Hackers Manual</productname> 1478 <date>July 2017</date> 1479</refentryinfo> 1480<refmeta> 1481 <refentrytitle><phrase>d_path</phrase></refentrytitle> 1482 <manvolnum>9</manvolnum> 1483 <refmiscinfo class="version">4.1.27</refmiscinfo> 1484</refmeta> 1485<refnamediv> 1486 <refname>d_path</refname> 1487 <refpurpose> 1488 return the path of a dentry 1489 </refpurpose> 1490</refnamediv> 1491<refsynopsisdiv> 1492 <title>Synopsis</title> 1493 <funcsynopsis><funcprototype> 1494 <funcdef>char * <function>d_path </function></funcdef> 1495 <paramdef>const struct path * <parameter>path</parameter></paramdef> 1496 <paramdef>char * <parameter>buf</parameter></paramdef> 1497 <paramdef>int <parameter>buflen</parameter></paramdef> 1498 </funcprototype></funcsynopsis> 1499</refsynopsisdiv> 1500<refsect1> 1501 <title>Arguments</title> 1502 <variablelist> 1503 <varlistentry> 1504 <term><parameter>path</parameter></term> 1505 <listitem> 1506 <para> 1507 path to report 1508 </para> 1509 </listitem> 1510 </varlistentry> 1511 <varlistentry> 1512 <term><parameter>buf</parameter></term> 1513 <listitem> 1514 <para> 1515 buffer to return value in 1516 </para> 1517 </listitem> 1518 </varlistentry> 1519 <varlistentry> 1520 <term><parameter>buflen</parameter></term> 1521 <listitem> 1522 <para> 1523 buffer length 1524 </para> 1525 </listitem> 1526 </varlistentry> 1527 </variablelist> 1528</refsect1> 1529<refsect1> 1530<title>Description</title> 1531<para> 1532 Convert a dentry into an ASCII path name. If the entry has been deleted 1533 the string <quote> (deleted)</quote> is appended. Note that this is ambiguous. 1534 </para><para> 1535 1536 Returns a pointer into the buffer or an error code if the path was 1537 too long. Note: Callers should use the returned pointer, not the passed 1538 in buffer, to use the name! The implementation often starts at an offset 1539 into the buffer, and may leave 0 bytes at the start. 1540 </para><para> 1541 1542 <quote>buflen</quote> should be positive. 1543</para> 1544</refsect1> 1545</refentry> 1546 1547<!-- include/linux/dcache.h --> 1548<refentry id="API-d-add"> 1549<refentryinfo> 1550 <title>LINUX</title> 1551 <productname>Kernel Hackers Manual</productname> 1552 <date>July 2017</date> 1553</refentryinfo> 1554<refmeta> 1555 <refentrytitle><phrase>d_add</phrase></refentrytitle> 1556 <manvolnum>9</manvolnum> 1557 <refmiscinfo class="version">4.1.27</refmiscinfo> 1558</refmeta> 1559<refnamediv> 1560 <refname>d_add</refname> 1561 <refpurpose> 1562 add dentry to hash queues 1563 </refpurpose> 1564</refnamediv> 1565<refsynopsisdiv> 1566 <title>Synopsis</title> 1567 <funcsynopsis><funcprototype> 1568 <funcdef>void <function>d_add </function></funcdef> 1569 <paramdef>struct dentry * <parameter>entry</parameter></paramdef> 1570 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 1571 </funcprototype></funcsynopsis> 1572</refsynopsisdiv> 1573<refsect1> 1574 <title>Arguments</title> 1575 <variablelist> 1576 <varlistentry> 1577 <term><parameter>entry</parameter></term> 1578 <listitem> 1579 <para> 1580 dentry to add 1581 </para> 1582 </listitem> 1583 </varlistentry> 1584 <varlistentry> 1585 <term><parameter>inode</parameter></term> 1586 <listitem> 1587 <para> 1588 The inode to attach to this dentry 1589 </para> 1590 </listitem> 1591 </varlistentry> 1592 </variablelist> 1593</refsect1> 1594<refsect1> 1595<title>Description</title> 1596<para> 1597 This adds the entry to the hash queues and initializes <parameter>inode</parameter>. 1598 The entry was actually filled in earlier during <function>d_alloc</function>. 1599</para> 1600</refsect1> 1601</refentry> 1602 1603<refentry id="API-d-add-unique"> 1604<refentryinfo> 1605 <title>LINUX</title> 1606 <productname>Kernel Hackers Manual</productname> 1607 <date>July 2017</date> 1608</refentryinfo> 1609<refmeta> 1610 <refentrytitle><phrase>d_add_unique</phrase></refentrytitle> 1611 <manvolnum>9</manvolnum> 1612 <refmiscinfo class="version">4.1.27</refmiscinfo> 1613</refmeta> 1614<refnamediv> 1615 <refname>d_add_unique</refname> 1616 <refpurpose> 1617 add dentry to hash queues without aliasing 1618 </refpurpose> 1619</refnamediv> 1620<refsynopsisdiv> 1621 <title>Synopsis</title> 1622 <funcsynopsis><funcprototype> 1623 <funcdef>struct dentry * <function>d_add_unique </function></funcdef> 1624 <paramdef>struct dentry * <parameter>entry</parameter></paramdef> 1625 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 1626 </funcprototype></funcsynopsis> 1627</refsynopsisdiv> 1628<refsect1> 1629 <title>Arguments</title> 1630 <variablelist> 1631 <varlistentry> 1632 <term><parameter>entry</parameter></term> 1633 <listitem> 1634 <para> 1635 dentry to add 1636 </para> 1637 </listitem> 1638 </varlistentry> 1639 <varlistentry> 1640 <term><parameter>inode</parameter></term> 1641 <listitem> 1642 <para> 1643 The inode to attach to this dentry 1644 </para> 1645 </listitem> 1646 </varlistentry> 1647 </variablelist> 1648</refsect1> 1649<refsect1> 1650<title>Description</title> 1651<para> 1652 This adds the entry to the hash queues and initializes <parameter>inode</parameter>. 1653 The entry was actually filled in earlier during <function>d_alloc</function>. 1654</para> 1655</refsect1> 1656</refentry> 1657 1658<refentry id="API-dget-dlock"> 1659<refentryinfo> 1660 <title>LINUX</title> 1661 <productname>Kernel Hackers Manual</productname> 1662 <date>July 2017</date> 1663</refentryinfo> 1664<refmeta> 1665 <refentrytitle><phrase>dget_dlock</phrase></refentrytitle> 1666 <manvolnum>9</manvolnum> 1667 <refmiscinfo class="version">4.1.27</refmiscinfo> 1668</refmeta> 1669<refnamediv> 1670 <refname>dget_dlock</refname> 1671 <refpurpose> 1672 get a reference to a dentry 1673 </refpurpose> 1674</refnamediv> 1675<refsynopsisdiv> 1676 <title>Synopsis</title> 1677 <funcsynopsis><funcprototype> 1678 <funcdef>struct dentry * <function>dget_dlock </function></funcdef> 1679 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 1680 </funcprototype></funcsynopsis> 1681</refsynopsisdiv> 1682<refsect1> 1683 <title>Arguments</title> 1684 <variablelist> 1685 <varlistentry> 1686 <term><parameter>dentry</parameter></term> 1687 <listitem> 1688 <para> 1689 dentry to get a reference to 1690 </para> 1691 </listitem> 1692 </varlistentry> 1693 </variablelist> 1694</refsect1> 1695<refsect1> 1696<title>Description</title> 1697<para> 1698 Given a dentry or <constant>NULL</constant> pointer increment the reference count 1699 if appropriate and return the dentry. A dentry will not be 1700 destroyed when it has references. 1701</para> 1702</refsect1> 1703</refentry> 1704 1705<refentry id="API-d-unhashed"> 1706<refentryinfo> 1707 <title>LINUX</title> 1708 <productname>Kernel Hackers Manual</productname> 1709 <date>July 2017</date> 1710</refentryinfo> 1711<refmeta> 1712 <refentrytitle><phrase>d_unhashed</phrase></refentrytitle> 1713 <manvolnum>9</manvolnum> 1714 <refmiscinfo class="version">4.1.27</refmiscinfo> 1715</refmeta> 1716<refnamediv> 1717 <refname>d_unhashed</refname> 1718 <refpurpose> 1719 is dentry hashed 1720 </refpurpose> 1721</refnamediv> 1722<refsynopsisdiv> 1723 <title>Synopsis</title> 1724 <funcsynopsis><funcprototype> 1725 <funcdef>int <function>d_unhashed </function></funcdef> 1726 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 1727 </funcprototype></funcsynopsis> 1728</refsynopsisdiv> 1729<refsect1> 1730 <title>Arguments</title> 1731 <variablelist> 1732 <varlistentry> 1733 <term><parameter>dentry</parameter></term> 1734 <listitem> 1735 <para> 1736 entry to check 1737 </para> 1738 </listitem> 1739 </varlistentry> 1740 </variablelist> 1741</refsect1> 1742<refsect1> 1743<title>Description</title> 1744<para> 1745 Returns true if the dentry passed is not currently hashed. 1746</para> 1747</refsect1> 1748</refentry> 1749 1750<refentry id="API-d-really-is-negative"> 1751<refentryinfo> 1752 <title>LINUX</title> 1753 <productname>Kernel Hackers Manual</productname> 1754 <date>July 2017</date> 1755</refentryinfo> 1756<refmeta> 1757 <refentrytitle><phrase>d_really_is_negative</phrase></refentrytitle> 1758 <manvolnum>9</manvolnum> 1759 <refmiscinfo class="version">4.1.27</refmiscinfo> 1760</refmeta> 1761<refnamediv> 1762 <refname>d_really_is_negative</refname> 1763 <refpurpose> 1764 Determine if a dentry is really negative (ignoring fallthroughs) 1765 </refpurpose> 1766</refnamediv> 1767<refsynopsisdiv> 1768 <title>Synopsis</title> 1769 <funcsynopsis><funcprototype> 1770 <funcdef>bool <function>d_really_is_negative </function></funcdef> 1771 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 1772 </funcprototype></funcsynopsis> 1773</refsynopsisdiv> 1774<refsect1> 1775 <title>Arguments</title> 1776 <variablelist> 1777 <varlistentry> 1778 <term><parameter>dentry</parameter></term> 1779 <listitem> 1780 <para> 1781 The dentry in question 1782 </para> 1783 </listitem> 1784 </varlistentry> 1785 </variablelist> 1786</refsect1> 1787<refsect1> 1788<title>Description</title> 1789<para> 1790 Returns true if the dentry represents either an absent name or a name that 1791 doesn't map to an inode (ie. ->d_inode is NULL). The dentry could represent 1792 a true miss, a whiteout that isn't represented by a 0,0 chardev or a 1793 fallthrough marker in an opaque directory. 1794 </para><para> 1795 1796 Note! (1) This should be used *only* by a filesystem to examine its own 1797 dentries. It should not be used to look at some other filesystem's 1798 dentries. (2) It should also be used in combination with <function>d_inode</function> to get 1799 the inode. (3) The dentry may have something attached to ->d_lower and the 1800 type field of the flags may be set to something other than miss or whiteout. 1801</para> 1802</refsect1> 1803</refentry> 1804 1805<refentry id="API-d-really-is-positive"> 1806<refentryinfo> 1807 <title>LINUX</title> 1808 <productname>Kernel Hackers Manual</productname> 1809 <date>July 2017</date> 1810</refentryinfo> 1811<refmeta> 1812 <refentrytitle><phrase>d_really_is_positive</phrase></refentrytitle> 1813 <manvolnum>9</manvolnum> 1814 <refmiscinfo class="version">4.1.27</refmiscinfo> 1815</refmeta> 1816<refnamediv> 1817 <refname>d_really_is_positive</refname> 1818 <refpurpose> 1819 Determine if a dentry is really positive (ignoring fallthroughs) 1820 </refpurpose> 1821</refnamediv> 1822<refsynopsisdiv> 1823 <title>Synopsis</title> 1824 <funcsynopsis><funcprototype> 1825 <funcdef>bool <function>d_really_is_positive </function></funcdef> 1826 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 1827 </funcprototype></funcsynopsis> 1828</refsynopsisdiv> 1829<refsect1> 1830 <title>Arguments</title> 1831 <variablelist> 1832 <varlistentry> 1833 <term><parameter>dentry</parameter></term> 1834 <listitem> 1835 <para> 1836 The dentry in question 1837 </para> 1838 </listitem> 1839 </varlistentry> 1840 </variablelist> 1841</refsect1> 1842<refsect1> 1843<title>Description</title> 1844<para> 1845 Returns true if the dentry represents a name that maps to an inode 1846 (ie. ->d_inode is not NULL). The dentry might still represent a whiteout if 1847 that is represented on medium as a 0,0 chardev. 1848 </para><para> 1849 1850 Note! (1) This should be used *only* by a filesystem to examine its own 1851 dentries. It should not be used to look at some other filesystem's 1852 dentries. (2) It should also be used in combination with <function>d_inode</function> to get 1853 the inode. 1854</para> 1855</refsect1> 1856</refentry> 1857 1858<refentry id="API-d-inode"> 1859<refentryinfo> 1860 <title>LINUX</title> 1861 <productname>Kernel Hackers Manual</productname> 1862 <date>July 2017</date> 1863</refentryinfo> 1864<refmeta> 1865 <refentrytitle><phrase>d_inode</phrase></refentrytitle> 1866 <manvolnum>9</manvolnum> 1867 <refmiscinfo class="version">4.1.27</refmiscinfo> 1868</refmeta> 1869<refnamediv> 1870 <refname>d_inode</refname> 1871 <refpurpose> 1872 Get the actual inode of this dentry 1873 </refpurpose> 1874</refnamediv> 1875<refsynopsisdiv> 1876 <title>Synopsis</title> 1877 <funcsynopsis><funcprototype> 1878 <funcdef>struct inode * <function>d_inode </function></funcdef> 1879 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 1880 </funcprototype></funcsynopsis> 1881</refsynopsisdiv> 1882<refsect1> 1883 <title>Arguments</title> 1884 <variablelist> 1885 <varlistentry> 1886 <term><parameter>dentry</parameter></term> 1887 <listitem> 1888 <para> 1889 The dentry to query 1890 </para> 1891 </listitem> 1892 </varlistentry> 1893 </variablelist> 1894</refsect1> 1895<refsect1> 1896<title>Description</title> 1897<para> 1898 This is the helper normal filesystems should use to get at their own inodes 1899 in their own dentries and ignore the layering superimposed upon them. 1900</para> 1901</refsect1> 1902</refentry> 1903 1904<refentry id="API-d-inode-rcu"> 1905<refentryinfo> 1906 <title>LINUX</title> 1907 <productname>Kernel Hackers Manual</productname> 1908 <date>July 2017</date> 1909</refentryinfo> 1910<refmeta> 1911 <refentrytitle><phrase>d_inode_rcu</phrase></refentrytitle> 1912 <manvolnum>9</manvolnum> 1913 <refmiscinfo class="version">4.1.27</refmiscinfo> 1914</refmeta> 1915<refnamediv> 1916 <refname>d_inode_rcu</refname> 1917 <refpurpose> 1918 Get the actual inode of this dentry with <function>ACCESS_ONCE</function> 1919 </refpurpose> 1920</refnamediv> 1921<refsynopsisdiv> 1922 <title>Synopsis</title> 1923 <funcsynopsis><funcprototype> 1924 <funcdef>struct inode * <function>d_inode_rcu </function></funcdef> 1925 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 1926 </funcprototype></funcsynopsis> 1927</refsynopsisdiv> 1928<refsect1> 1929 <title>Arguments</title> 1930 <variablelist> 1931 <varlistentry> 1932 <term><parameter>dentry</parameter></term> 1933 <listitem> 1934 <para> 1935 The dentry to query 1936 </para> 1937 </listitem> 1938 </varlistentry> 1939 </variablelist> 1940</refsect1> 1941<refsect1> 1942<title>Description</title> 1943<para> 1944 This is the helper normal filesystems should use to get at their own inodes 1945 in their own dentries and ignore the layering superimposed upon them. 1946</para> 1947</refsect1> 1948</refentry> 1949 1950<refentry id="API-d-backing-inode"> 1951<refentryinfo> 1952 <title>LINUX</title> 1953 <productname>Kernel Hackers Manual</productname> 1954 <date>July 2017</date> 1955</refentryinfo> 1956<refmeta> 1957 <refentrytitle><phrase>d_backing_inode</phrase></refentrytitle> 1958 <manvolnum>9</manvolnum> 1959 <refmiscinfo class="version">4.1.27</refmiscinfo> 1960</refmeta> 1961<refnamediv> 1962 <refname>d_backing_inode</refname> 1963 <refpurpose> 1964 Get upper or lower inode we should be using 1965 </refpurpose> 1966</refnamediv> 1967<refsynopsisdiv> 1968 <title>Synopsis</title> 1969 <funcsynopsis><funcprototype> 1970 <funcdef>struct inode * <function>d_backing_inode </function></funcdef> 1971 <paramdef>const struct dentry * <parameter>upper</parameter></paramdef> 1972 </funcprototype></funcsynopsis> 1973</refsynopsisdiv> 1974<refsect1> 1975 <title>Arguments</title> 1976 <variablelist> 1977 <varlistentry> 1978 <term><parameter>upper</parameter></term> 1979 <listitem> 1980 <para> 1981 The upper layer 1982 </para> 1983 </listitem> 1984 </varlistentry> 1985 </variablelist> 1986</refsect1> 1987<refsect1> 1988<title>Description</title> 1989<para> 1990 This is the helper that should be used to get at the inode that will be used 1991 if this dentry were to be opened as a file. The inode may be on the upper 1992 dentry or it may be on a lower dentry pinned by the upper. 1993 </para><para> 1994 1995 Normal filesystems should not use this to access their own inodes. 1996</para> 1997</refsect1> 1998</refentry> 1999 2000<refentry id="API-d-backing-dentry"> 2001<refentryinfo> 2002 <title>LINUX</title> 2003 <productname>Kernel Hackers Manual</productname> 2004 <date>July 2017</date> 2005</refentryinfo> 2006<refmeta> 2007 <refentrytitle><phrase>d_backing_dentry</phrase></refentrytitle> 2008 <manvolnum>9</manvolnum> 2009 <refmiscinfo class="version">4.1.27</refmiscinfo> 2010</refmeta> 2011<refnamediv> 2012 <refname>d_backing_dentry</refname> 2013 <refpurpose> 2014 Get upper or lower dentry we should be using 2015 </refpurpose> 2016</refnamediv> 2017<refsynopsisdiv> 2018 <title>Synopsis</title> 2019 <funcsynopsis><funcprototype> 2020 <funcdef>struct dentry * <function>d_backing_dentry </function></funcdef> 2021 <paramdef>struct dentry * <parameter>upper</parameter></paramdef> 2022 </funcprototype></funcsynopsis> 2023</refsynopsisdiv> 2024<refsect1> 2025 <title>Arguments</title> 2026 <variablelist> 2027 <varlistentry> 2028 <term><parameter>upper</parameter></term> 2029 <listitem> 2030 <para> 2031 The upper layer 2032 </para> 2033 </listitem> 2034 </varlistentry> 2035 </variablelist> 2036</refsect1> 2037<refsect1> 2038<title>Description</title> 2039<para> 2040 This is the helper that should be used to get the dentry of the inode that 2041 will be used if this dentry were opened as a file. It may be the upper 2042 dentry or it may be a lower dentry pinned by the upper. 2043 </para><para> 2044 2045 Normal filesystems should not use this to access their own dentries. 2046</para> 2047</refsect1> 2048</refentry> 2049 2050 </sect1> 2051 <sect1 id="inode_handling"><title>Inode Handling</title> 2052<!-- fs/inode.c --> 2053<refentry id="API-inode-init-always"> 2054<refentryinfo> 2055 <title>LINUX</title> 2056 <productname>Kernel Hackers Manual</productname> 2057 <date>July 2017</date> 2058</refentryinfo> 2059<refmeta> 2060 <refentrytitle><phrase>inode_init_always</phrase></refentrytitle> 2061 <manvolnum>9</manvolnum> 2062 <refmiscinfo class="version">4.1.27</refmiscinfo> 2063</refmeta> 2064<refnamediv> 2065 <refname>inode_init_always</refname> 2066 <refpurpose> 2067 perform inode structure intialisation 2068 </refpurpose> 2069</refnamediv> 2070<refsynopsisdiv> 2071 <title>Synopsis</title> 2072 <funcsynopsis><funcprototype> 2073 <funcdef>int <function>inode_init_always </function></funcdef> 2074 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2075 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2076 </funcprototype></funcsynopsis> 2077</refsynopsisdiv> 2078<refsect1> 2079 <title>Arguments</title> 2080 <variablelist> 2081 <varlistentry> 2082 <term><parameter>sb</parameter></term> 2083 <listitem> 2084 <para> 2085 superblock inode belongs to 2086 </para> 2087 </listitem> 2088 </varlistentry> 2089 <varlistentry> 2090 <term><parameter>inode</parameter></term> 2091 <listitem> 2092 <para> 2093 inode to initialise 2094 </para> 2095 </listitem> 2096 </varlistentry> 2097 </variablelist> 2098</refsect1> 2099<refsect1> 2100<title>Description</title> 2101<para> 2102 These are initializations that need to be done on every inode 2103 allocation as the fields are not initialised by slab allocation. 2104</para> 2105</refsect1> 2106</refentry> 2107 2108<refentry id="API-drop-nlink"> 2109<refentryinfo> 2110 <title>LINUX</title> 2111 <productname>Kernel Hackers Manual</productname> 2112 <date>July 2017</date> 2113</refentryinfo> 2114<refmeta> 2115 <refentrytitle><phrase>drop_nlink</phrase></refentrytitle> 2116 <manvolnum>9</manvolnum> 2117 <refmiscinfo class="version">4.1.27</refmiscinfo> 2118</refmeta> 2119<refnamediv> 2120 <refname>drop_nlink</refname> 2121 <refpurpose> 2122 directly drop an inode's link count 2123 </refpurpose> 2124</refnamediv> 2125<refsynopsisdiv> 2126 <title>Synopsis</title> 2127 <funcsynopsis><funcprototype> 2128 <funcdef>void <function>drop_nlink </function></funcdef> 2129 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2130 </funcprototype></funcsynopsis> 2131</refsynopsisdiv> 2132<refsect1> 2133 <title>Arguments</title> 2134 <variablelist> 2135 <varlistentry> 2136 <term><parameter>inode</parameter></term> 2137 <listitem> 2138 <para> 2139 inode 2140 </para> 2141 </listitem> 2142 </varlistentry> 2143 </variablelist> 2144</refsect1> 2145<refsect1> 2146<title>Description</title> 2147<para> 2148 This is a low-level filesystem helper to replace any 2149 direct filesystem manipulation of i_nlink. In cases 2150 where we are attempting to track writes to the 2151 filesystem, a decrement to zero means an imminent 2152 write when the file is truncated and actually unlinked 2153 on the filesystem. 2154</para> 2155</refsect1> 2156</refentry> 2157 2158<refentry id="API-clear-nlink"> 2159<refentryinfo> 2160 <title>LINUX</title> 2161 <productname>Kernel Hackers Manual</productname> 2162 <date>July 2017</date> 2163</refentryinfo> 2164<refmeta> 2165 <refentrytitle><phrase>clear_nlink</phrase></refentrytitle> 2166 <manvolnum>9</manvolnum> 2167 <refmiscinfo class="version">4.1.27</refmiscinfo> 2168</refmeta> 2169<refnamediv> 2170 <refname>clear_nlink</refname> 2171 <refpurpose> 2172 directly zero an inode's link count 2173 </refpurpose> 2174</refnamediv> 2175<refsynopsisdiv> 2176 <title>Synopsis</title> 2177 <funcsynopsis><funcprototype> 2178 <funcdef>void <function>clear_nlink </function></funcdef> 2179 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2180 </funcprototype></funcsynopsis> 2181</refsynopsisdiv> 2182<refsect1> 2183 <title>Arguments</title> 2184 <variablelist> 2185 <varlistentry> 2186 <term><parameter>inode</parameter></term> 2187 <listitem> 2188 <para> 2189 inode 2190 </para> 2191 </listitem> 2192 </varlistentry> 2193 </variablelist> 2194</refsect1> 2195<refsect1> 2196<title>Description</title> 2197<para> 2198 This is a low-level filesystem helper to replace any 2199 direct filesystem manipulation of i_nlink. See 2200 <function>drop_nlink</function> for why we care about i_nlink hitting zero. 2201</para> 2202</refsect1> 2203</refentry> 2204 2205<refentry id="API-set-nlink"> 2206<refentryinfo> 2207 <title>LINUX</title> 2208 <productname>Kernel Hackers Manual</productname> 2209 <date>July 2017</date> 2210</refentryinfo> 2211<refmeta> 2212 <refentrytitle><phrase>set_nlink</phrase></refentrytitle> 2213 <manvolnum>9</manvolnum> 2214 <refmiscinfo class="version">4.1.27</refmiscinfo> 2215</refmeta> 2216<refnamediv> 2217 <refname>set_nlink</refname> 2218 <refpurpose> 2219 directly set an inode's link count 2220 </refpurpose> 2221</refnamediv> 2222<refsynopsisdiv> 2223 <title>Synopsis</title> 2224 <funcsynopsis><funcprototype> 2225 <funcdef>void <function>set_nlink </function></funcdef> 2226 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2227 <paramdef>unsigned int <parameter>nlink</parameter></paramdef> 2228 </funcprototype></funcsynopsis> 2229</refsynopsisdiv> 2230<refsect1> 2231 <title>Arguments</title> 2232 <variablelist> 2233 <varlistentry> 2234 <term><parameter>inode</parameter></term> 2235 <listitem> 2236 <para> 2237 inode 2238 </para> 2239 </listitem> 2240 </varlistentry> 2241 <varlistentry> 2242 <term><parameter>nlink</parameter></term> 2243 <listitem> 2244 <para> 2245 new nlink (should be non-zero) 2246 </para> 2247 </listitem> 2248 </varlistentry> 2249 </variablelist> 2250</refsect1> 2251<refsect1> 2252<title>Description</title> 2253<para> 2254 This is a low-level filesystem helper to replace any 2255 direct filesystem manipulation of i_nlink. 2256</para> 2257</refsect1> 2258</refentry> 2259 2260<refentry id="API-inc-nlink"> 2261<refentryinfo> 2262 <title>LINUX</title> 2263 <productname>Kernel Hackers Manual</productname> 2264 <date>July 2017</date> 2265</refentryinfo> 2266<refmeta> 2267 <refentrytitle><phrase>inc_nlink</phrase></refentrytitle> 2268 <manvolnum>9</manvolnum> 2269 <refmiscinfo class="version">4.1.27</refmiscinfo> 2270</refmeta> 2271<refnamediv> 2272 <refname>inc_nlink</refname> 2273 <refpurpose> 2274 directly increment an inode's link count 2275 </refpurpose> 2276</refnamediv> 2277<refsynopsisdiv> 2278 <title>Synopsis</title> 2279 <funcsynopsis><funcprototype> 2280 <funcdef>void <function>inc_nlink </function></funcdef> 2281 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2282 </funcprototype></funcsynopsis> 2283</refsynopsisdiv> 2284<refsect1> 2285 <title>Arguments</title> 2286 <variablelist> 2287 <varlistentry> 2288 <term><parameter>inode</parameter></term> 2289 <listitem> 2290 <para> 2291 inode 2292 </para> 2293 </listitem> 2294 </varlistentry> 2295 </variablelist> 2296</refsect1> 2297<refsect1> 2298<title>Description</title> 2299<para> 2300 This is a low-level filesystem helper to replace any 2301 direct filesystem manipulation of i_nlink. Currently, 2302 it is only here for parity with <function>dec_nlink</function>. 2303</para> 2304</refsect1> 2305</refentry> 2306 2307<refentry id="API-inode-sb-list-add"> 2308<refentryinfo> 2309 <title>LINUX</title> 2310 <productname>Kernel Hackers Manual</productname> 2311 <date>July 2017</date> 2312</refentryinfo> 2313<refmeta> 2314 <refentrytitle><phrase>inode_sb_list_add</phrase></refentrytitle> 2315 <manvolnum>9</manvolnum> 2316 <refmiscinfo class="version">4.1.27</refmiscinfo> 2317</refmeta> 2318<refnamediv> 2319 <refname>inode_sb_list_add</refname> 2320 <refpurpose> 2321 add inode to the superblock list of inodes 2322 </refpurpose> 2323</refnamediv> 2324<refsynopsisdiv> 2325 <title>Synopsis</title> 2326 <funcsynopsis><funcprototype> 2327 <funcdef>void <function>inode_sb_list_add </function></funcdef> 2328 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2329 </funcprototype></funcsynopsis> 2330</refsynopsisdiv> 2331<refsect1> 2332 <title>Arguments</title> 2333 <variablelist> 2334 <varlistentry> 2335 <term><parameter>inode</parameter></term> 2336 <listitem> 2337 <para> 2338 inode to add 2339 </para> 2340 </listitem> 2341 </varlistentry> 2342 </variablelist> 2343</refsect1> 2344</refentry> 2345 2346<refentry id="API---insert-inode-hash"> 2347<refentryinfo> 2348 <title>LINUX</title> 2349 <productname>Kernel Hackers Manual</productname> 2350 <date>July 2017</date> 2351</refentryinfo> 2352<refmeta> 2353 <refentrytitle><phrase>__insert_inode_hash</phrase></refentrytitle> 2354 <manvolnum>9</manvolnum> 2355 <refmiscinfo class="version">4.1.27</refmiscinfo> 2356</refmeta> 2357<refnamediv> 2358 <refname>__insert_inode_hash</refname> 2359 <refpurpose> 2360 hash an inode 2361 </refpurpose> 2362</refnamediv> 2363<refsynopsisdiv> 2364 <title>Synopsis</title> 2365 <funcsynopsis><funcprototype> 2366 <funcdef>void <function>__insert_inode_hash </function></funcdef> 2367 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2368 <paramdef>unsigned long <parameter>hashval</parameter></paramdef> 2369 </funcprototype></funcsynopsis> 2370</refsynopsisdiv> 2371<refsect1> 2372 <title>Arguments</title> 2373 <variablelist> 2374 <varlistentry> 2375 <term><parameter>inode</parameter></term> 2376 <listitem> 2377 <para> 2378 unhashed inode 2379 </para> 2380 </listitem> 2381 </varlistentry> 2382 <varlistentry> 2383 <term><parameter>hashval</parameter></term> 2384 <listitem> 2385 <para> 2386 unsigned long value used to locate this object in the 2387 inode_hashtable. 2388 </para> 2389 </listitem> 2390 </varlistentry> 2391 </variablelist> 2392</refsect1> 2393<refsect1> 2394<title>Description</title> 2395<para> 2396 Add an inode to the inode hash for this superblock. 2397</para> 2398</refsect1> 2399</refentry> 2400 2401<refentry id="API---remove-inode-hash"> 2402<refentryinfo> 2403 <title>LINUX</title> 2404 <productname>Kernel Hackers Manual</productname> 2405 <date>July 2017</date> 2406</refentryinfo> 2407<refmeta> 2408 <refentrytitle><phrase>__remove_inode_hash</phrase></refentrytitle> 2409 <manvolnum>9</manvolnum> 2410 <refmiscinfo class="version">4.1.27</refmiscinfo> 2411</refmeta> 2412<refnamediv> 2413 <refname>__remove_inode_hash</refname> 2414 <refpurpose> 2415 remove an inode from the hash 2416 </refpurpose> 2417</refnamediv> 2418<refsynopsisdiv> 2419 <title>Synopsis</title> 2420 <funcsynopsis><funcprototype> 2421 <funcdef>void <function>__remove_inode_hash </function></funcdef> 2422 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2423 </funcprototype></funcsynopsis> 2424</refsynopsisdiv> 2425<refsect1> 2426 <title>Arguments</title> 2427 <variablelist> 2428 <varlistentry> 2429 <term><parameter>inode</parameter></term> 2430 <listitem> 2431 <para> 2432 inode to unhash 2433 </para> 2434 </listitem> 2435 </varlistentry> 2436 </variablelist> 2437</refsect1> 2438<refsect1> 2439<title>Description</title> 2440<para> 2441 Remove an inode from the superblock. 2442</para> 2443</refsect1> 2444</refentry> 2445 2446<refentry id="API-new-inode"> 2447<refentryinfo> 2448 <title>LINUX</title> 2449 <productname>Kernel Hackers Manual</productname> 2450 <date>July 2017</date> 2451</refentryinfo> 2452<refmeta> 2453 <refentrytitle><phrase>new_inode</phrase></refentrytitle> 2454 <manvolnum>9</manvolnum> 2455 <refmiscinfo class="version">4.1.27</refmiscinfo> 2456</refmeta> 2457<refnamediv> 2458 <refname>new_inode</refname> 2459 <refpurpose> 2460 obtain an inode 2461 </refpurpose> 2462</refnamediv> 2463<refsynopsisdiv> 2464 <title>Synopsis</title> 2465 <funcsynopsis><funcprototype> 2466 <funcdef>struct inode * <function>new_inode </function></funcdef> 2467 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2468 </funcprototype></funcsynopsis> 2469</refsynopsisdiv> 2470<refsect1> 2471 <title>Arguments</title> 2472 <variablelist> 2473 <varlistentry> 2474 <term><parameter>sb</parameter></term> 2475 <listitem> 2476 <para> 2477 superblock 2478 </para> 2479 </listitem> 2480 </varlistentry> 2481 </variablelist> 2482</refsect1> 2483<refsect1> 2484<title>Description</title> 2485<para> 2486 Allocates a new inode for given superblock. The default gfp_mask 2487 for allocations related to inode->i_mapping is GFP_HIGHUSER_MOVABLE. 2488 If HIGHMEM pages are unsuitable or it is known that pages allocated 2489 for the page cache are not reclaimable or migratable, 2490 <function>mapping_set_gfp_mask</function> must be called with suitable flags on the 2491 newly created inode's mapping 2492</para> 2493</refsect1> 2494</refentry> 2495 2496<refentry id="API-unlock-new-inode"> 2497<refentryinfo> 2498 <title>LINUX</title> 2499 <productname>Kernel Hackers Manual</productname> 2500 <date>July 2017</date> 2501</refentryinfo> 2502<refmeta> 2503 <refentrytitle><phrase>unlock_new_inode</phrase></refentrytitle> 2504 <manvolnum>9</manvolnum> 2505 <refmiscinfo class="version">4.1.27</refmiscinfo> 2506</refmeta> 2507<refnamediv> 2508 <refname>unlock_new_inode</refname> 2509 <refpurpose> 2510 clear the I_NEW state and wake up any waiters 2511 </refpurpose> 2512</refnamediv> 2513<refsynopsisdiv> 2514 <title>Synopsis</title> 2515 <funcsynopsis><funcprototype> 2516 <funcdef>void <function>unlock_new_inode </function></funcdef> 2517 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 2518 </funcprototype></funcsynopsis> 2519</refsynopsisdiv> 2520<refsect1> 2521 <title>Arguments</title> 2522 <variablelist> 2523 <varlistentry> 2524 <term><parameter>inode</parameter></term> 2525 <listitem> 2526 <para> 2527 new inode to unlock 2528 </para> 2529 </listitem> 2530 </varlistentry> 2531 </variablelist> 2532</refsect1> 2533<refsect1> 2534<title>Description</title> 2535<para> 2536 Called when the inode is fully initialised to clear the new state of the 2537 inode and wake up anyone waiting for the inode to finish initialisation. 2538</para> 2539</refsect1> 2540</refentry> 2541 2542<refentry id="API-lock-two-nondirectories"> 2543<refentryinfo> 2544 <title>LINUX</title> 2545 <productname>Kernel Hackers Manual</productname> 2546 <date>July 2017</date> 2547</refentryinfo> 2548<refmeta> 2549 <refentrytitle><phrase>lock_two_nondirectories</phrase></refentrytitle> 2550 <manvolnum>9</manvolnum> 2551 <refmiscinfo class="version">4.1.27</refmiscinfo> 2552</refmeta> 2553<refnamediv> 2554 <refname>lock_two_nondirectories</refname> 2555 <refpurpose> 2556 take two i_mutexes on non-directory objects 2557 </refpurpose> 2558</refnamediv> 2559<refsynopsisdiv> 2560 <title>Synopsis</title> 2561 <funcsynopsis><funcprototype> 2562 <funcdef>void <function>lock_two_nondirectories </function></funcdef> 2563 <paramdef>struct inode * <parameter>inode1</parameter></paramdef> 2564 <paramdef>struct inode * <parameter>inode2</parameter></paramdef> 2565 </funcprototype></funcsynopsis> 2566</refsynopsisdiv> 2567<refsect1> 2568 <title>Arguments</title> 2569 <variablelist> 2570 <varlistentry> 2571 <term><parameter>inode1</parameter></term> 2572 <listitem> 2573 <para> 2574 first inode to lock 2575 </para> 2576 </listitem> 2577 </varlistentry> 2578 <varlistentry> 2579 <term><parameter>inode2</parameter></term> 2580 <listitem> 2581 <para> 2582 second inode to lock 2583 </para> 2584 </listitem> 2585 </varlistentry> 2586 </variablelist> 2587</refsect1> 2588<refsect1> 2589<title>Description</title> 2590<para> 2591 </para><para> 2592 2593 Lock any non-NULL argument that is not a directory. 2594 Zero, one or two objects may be locked by this function. 2595</para> 2596</refsect1> 2597</refentry> 2598 2599<refentry id="API-unlock-two-nondirectories"> 2600<refentryinfo> 2601 <title>LINUX</title> 2602 <productname>Kernel Hackers Manual</productname> 2603 <date>July 2017</date> 2604</refentryinfo> 2605<refmeta> 2606 <refentrytitle><phrase>unlock_two_nondirectories</phrase></refentrytitle> 2607 <manvolnum>9</manvolnum> 2608 <refmiscinfo class="version">4.1.27</refmiscinfo> 2609</refmeta> 2610<refnamediv> 2611 <refname>unlock_two_nondirectories</refname> 2612 <refpurpose> 2613 release locks from <function>lock_two_nondirectories</function> 2614 </refpurpose> 2615</refnamediv> 2616<refsynopsisdiv> 2617 <title>Synopsis</title> 2618 <funcsynopsis><funcprototype> 2619 <funcdef>void <function>unlock_two_nondirectories </function></funcdef> 2620 <paramdef>struct inode * <parameter>inode1</parameter></paramdef> 2621 <paramdef>struct inode * <parameter>inode2</parameter></paramdef> 2622 </funcprototype></funcsynopsis> 2623</refsynopsisdiv> 2624<refsect1> 2625 <title>Arguments</title> 2626 <variablelist> 2627 <varlistentry> 2628 <term><parameter>inode1</parameter></term> 2629 <listitem> 2630 <para> 2631 first inode to unlock 2632 </para> 2633 </listitem> 2634 </varlistentry> 2635 <varlistentry> 2636 <term><parameter>inode2</parameter></term> 2637 <listitem> 2638 <para> 2639 second inode to unlock 2640 </para> 2641 </listitem> 2642 </varlistentry> 2643 </variablelist> 2644</refsect1> 2645</refentry> 2646 2647<refentry id="API-iget5-locked"> 2648<refentryinfo> 2649 <title>LINUX</title> 2650 <productname>Kernel Hackers Manual</productname> 2651 <date>July 2017</date> 2652</refentryinfo> 2653<refmeta> 2654 <refentrytitle><phrase>iget5_locked</phrase></refentrytitle> 2655 <manvolnum>9</manvolnum> 2656 <refmiscinfo class="version">4.1.27</refmiscinfo> 2657</refmeta> 2658<refnamediv> 2659 <refname>iget5_locked</refname> 2660 <refpurpose> 2661 obtain an inode from a mounted file system 2662 </refpurpose> 2663</refnamediv> 2664<refsynopsisdiv> 2665 <title>Synopsis</title> 2666 <funcsynopsis><funcprototype> 2667 <funcdef>struct inode * <function>iget5_locked </function></funcdef> 2668 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2669 <paramdef>unsigned long <parameter>hashval</parameter></paramdef> 2670 <paramdef>int (*<parameter>test</parameter>) 2671 <funcparams>struct inode *, void *</funcparams></paramdef> 2672 <paramdef>int (*<parameter>set</parameter>) 2673 <funcparams>struct inode *, void *</funcparams></paramdef> 2674 <paramdef>void * <parameter>data</parameter></paramdef> 2675 </funcprototype></funcsynopsis> 2676</refsynopsisdiv> 2677<refsect1> 2678 <title>Arguments</title> 2679 <variablelist> 2680 <varlistentry> 2681 <term><parameter>sb</parameter></term> 2682 <listitem> 2683 <para> 2684 super block of file system 2685 </para> 2686 </listitem> 2687 </varlistentry> 2688 <varlistentry> 2689 <term><parameter>hashval</parameter></term> 2690 <listitem> 2691 <para> 2692 hash value (usually inode number) to get 2693 </para> 2694 </listitem> 2695 </varlistentry> 2696 <varlistentry> 2697 <term><parameter>test</parameter></term> 2698 <listitem> 2699 <para> 2700 callback used for comparisons between inodes 2701 </para> 2702 </listitem> 2703 </varlistentry> 2704 <varlistentry> 2705 <term><parameter>set</parameter></term> 2706 <listitem> 2707 <para> 2708 callback used to initialize a new struct inode 2709 </para> 2710 </listitem> 2711 </varlistentry> 2712 <varlistentry> 2713 <term><parameter>data</parameter></term> 2714 <listitem> 2715 <para> 2716 opaque data pointer to pass to <parameter>test</parameter> and <parameter>set</parameter> 2717 </para> 2718 </listitem> 2719 </varlistentry> 2720 </variablelist> 2721</refsect1> 2722<refsect1> 2723<title>Description</title> 2724<para> 2725 Search for the inode specified by <parameter>hashval</parameter> and <parameter>data</parameter> in the inode cache, 2726 and if present it is return it with an increased reference count. This is 2727 a generalized version of <function>iget_locked</function> for file systems where the inode 2728 number is not sufficient for unique identification of an inode. 2729 </para><para> 2730 2731 If the inode is not in cache, allocate a new inode and return it locked, 2732 hashed, and with the I_NEW flag set. The file system gets to fill it in 2733 before unlocking it via <function>unlock_new_inode</function>. 2734 </para><para> 2735 2736 Note both <parameter>test</parameter> and <parameter>set</parameter> are called with the inode_hash_lock held, so can't 2737 sleep. 2738</para> 2739</refsect1> 2740</refentry> 2741 2742<refentry id="API-iget-locked"> 2743<refentryinfo> 2744 <title>LINUX</title> 2745 <productname>Kernel Hackers Manual</productname> 2746 <date>July 2017</date> 2747</refentryinfo> 2748<refmeta> 2749 <refentrytitle><phrase>iget_locked</phrase></refentrytitle> 2750 <manvolnum>9</manvolnum> 2751 <refmiscinfo class="version">4.1.27</refmiscinfo> 2752</refmeta> 2753<refnamediv> 2754 <refname>iget_locked</refname> 2755 <refpurpose> 2756 obtain an inode from a mounted file system 2757 </refpurpose> 2758</refnamediv> 2759<refsynopsisdiv> 2760 <title>Synopsis</title> 2761 <funcsynopsis><funcprototype> 2762 <funcdef>struct inode * <function>iget_locked </function></funcdef> 2763 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2764 <paramdef>unsigned long <parameter>ino</parameter></paramdef> 2765 </funcprototype></funcsynopsis> 2766</refsynopsisdiv> 2767<refsect1> 2768 <title>Arguments</title> 2769 <variablelist> 2770 <varlistentry> 2771 <term><parameter>sb</parameter></term> 2772 <listitem> 2773 <para> 2774 super block of file system 2775 </para> 2776 </listitem> 2777 </varlistentry> 2778 <varlistentry> 2779 <term><parameter>ino</parameter></term> 2780 <listitem> 2781 <para> 2782 inode number to get 2783 </para> 2784 </listitem> 2785 </varlistentry> 2786 </variablelist> 2787</refsect1> 2788<refsect1> 2789<title>Description</title> 2790<para> 2791 Search for the inode specified by <parameter>ino</parameter> in the inode cache and if present 2792 return it with an increased reference count. This is for file systems 2793 where the inode number is sufficient for unique identification of an inode. 2794 </para><para> 2795 2796 If the inode is not in cache, allocate a new inode and return it locked, 2797 hashed, and with the I_NEW flag set. The file system gets to fill it in 2798 before unlocking it via <function>unlock_new_inode</function>. 2799</para> 2800</refsect1> 2801</refentry> 2802 2803<refentry id="API-iunique"> 2804<refentryinfo> 2805 <title>LINUX</title> 2806 <productname>Kernel Hackers Manual</productname> 2807 <date>July 2017</date> 2808</refentryinfo> 2809<refmeta> 2810 <refentrytitle><phrase>iunique</phrase></refentrytitle> 2811 <manvolnum>9</manvolnum> 2812 <refmiscinfo class="version">4.1.27</refmiscinfo> 2813</refmeta> 2814<refnamediv> 2815 <refname>iunique</refname> 2816 <refpurpose> 2817 get a unique inode number 2818 </refpurpose> 2819</refnamediv> 2820<refsynopsisdiv> 2821 <title>Synopsis</title> 2822 <funcsynopsis><funcprototype> 2823 <funcdef>ino_t <function>iunique </function></funcdef> 2824 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2825 <paramdef>ino_t <parameter>max_reserved</parameter></paramdef> 2826 </funcprototype></funcsynopsis> 2827</refsynopsisdiv> 2828<refsect1> 2829 <title>Arguments</title> 2830 <variablelist> 2831 <varlistentry> 2832 <term><parameter>sb</parameter></term> 2833 <listitem> 2834 <para> 2835 superblock 2836 </para> 2837 </listitem> 2838 </varlistentry> 2839 <varlistentry> 2840 <term><parameter>max_reserved</parameter></term> 2841 <listitem> 2842 <para> 2843 highest reserved inode number 2844 </para> 2845 </listitem> 2846 </varlistentry> 2847 </variablelist> 2848</refsect1> 2849<refsect1> 2850<title>Description</title> 2851<para> 2852 Obtain an inode number that is unique on the system for a given 2853 superblock. This is used by file systems that have no natural 2854 permanent inode numbering system. An inode number is returned that 2855 is higher than the reserved limit but unique. 2856</para> 2857</refsect1> 2858<refsect1> 2859<title>BUGS</title> 2860<para> 2861 With a large number of inodes live on the file system this function 2862 currently becomes quite slow. 2863</para> 2864</refsect1> 2865</refentry> 2866 2867<refentry id="API-ilookup5-nowait"> 2868<refentryinfo> 2869 <title>LINUX</title> 2870 <productname>Kernel Hackers Manual</productname> 2871 <date>July 2017</date> 2872</refentryinfo> 2873<refmeta> 2874 <refentrytitle><phrase>ilookup5_nowait</phrase></refentrytitle> 2875 <manvolnum>9</manvolnum> 2876 <refmiscinfo class="version">4.1.27</refmiscinfo> 2877</refmeta> 2878<refnamediv> 2879 <refname>ilookup5_nowait</refname> 2880 <refpurpose> 2881 search for an inode in the inode cache 2882 </refpurpose> 2883</refnamediv> 2884<refsynopsisdiv> 2885 <title>Synopsis</title> 2886 <funcsynopsis><funcprototype> 2887 <funcdef>struct inode * <function>ilookup5_nowait </function></funcdef> 2888 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2889 <paramdef>unsigned long <parameter>hashval</parameter></paramdef> 2890 <paramdef>int (*<parameter>test</parameter>) 2891 <funcparams>struct inode *, void *</funcparams></paramdef> 2892 <paramdef>void * <parameter>data</parameter></paramdef> 2893 </funcprototype></funcsynopsis> 2894</refsynopsisdiv> 2895<refsect1> 2896 <title>Arguments</title> 2897 <variablelist> 2898 <varlistentry> 2899 <term><parameter>sb</parameter></term> 2900 <listitem> 2901 <para> 2902 super block of file system to search 2903 </para> 2904 </listitem> 2905 </varlistentry> 2906 <varlistentry> 2907 <term><parameter>hashval</parameter></term> 2908 <listitem> 2909 <para> 2910 hash value (usually inode number) to search for 2911 </para> 2912 </listitem> 2913 </varlistentry> 2914 <varlistentry> 2915 <term><parameter>test</parameter></term> 2916 <listitem> 2917 <para> 2918 callback used for comparisons between inodes 2919 </para> 2920 </listitem> 2921 </varlistentry> 2922 <varlistentry> 2923 <term><parameter>data</parameter></term> 2924 <listitem> 2925 <para> 2926 opaque data pointer to pass to <parameter>test</parameter> 2927 </para> 2928 </listitem> 2929 </varlistentry> 2930 </variablelist> 2931</refsect1> 2932<refsect1> 2933<title>Description</title> 2934<para> 2935 Search for the inode specified by <parameter>hashval</parameter> and <parameter>data</parameter> in the inode cache. 2936 If the inode is in the cache, the inode is returned with an incremented 2937 reference count. 2938</para> 2939</refsect1> 2940<refsect1> 2941<title>Note</title> 2942<para> 2943 I_NEW is not waited upon so you have to be very careful what you do 2944 with the returned inode. You probably should be using <function>ilookup5</function> instead. 2945</para> 2946</refsect1> 2947<refsect1> 2948<title>Note2</title> 2949<para> 2950 <parameter>test</parameter> is called with the inode_hash_lock held, so can't sleep. 2951</para> 2952</refsect1> 2953</refentry> 2954 2955<refentry id="API-ilookup5"> 2956<refentryinfo> 2957 <title>LINUX</title> 2958 <productname>Kernel Hackers Manual</productname> 2959 <date>July 2017</date> 2960</refentryinfo> 2961<refmeta> 2962 <refentrytitle><phrase>ilookup5</phrase></refentrytitle> 2963 <manvolnum>9</manvolnum> 2964 <refmiscinfo class="version">4.1.27</refmiscinfo> 2965</refmeta> 2966<refnamediv> 2967 <refname>ilookup5</refname> 2968 <refpurpose> 2969 search for an inode in the inode cache 2970 </refpurpose> 2971</refnamediv> 2972<refsynopsisdiv> 2973 <title>Synopsis</title> 2974 <funcsynopsis><funcprototype> 2975 <funcdef>struct inode * <function>ilookup5 </function></funcdef> 2976 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 2977 <paramdef>unsigned long <parameter>hashval</parameter></paramdef> 2978 <paramdef>int (*<parameter>test</parameter>) 2979 <funcparams>struct inode *, void *</funcparams></paramdef> 2980 <paramdef>void * <parameter>data</parameter></paramdef> 2981 </funcprototype></funcsynopsis> 2982</refsynopsisdiv> 2983<refsect1> 2984 <title>Arguments</title> 2985 <variablelist> 2986 <varlistentry> 2987 <term><parameter>sb</parameter></term> 2988 <listitem> 2989 <para> 2990 super block of file system to search 2991 </para> 2992 </listitem> 2993 </varlistentry> 2994 <varlistentry> 2995 <term><parameter>hashval</parameter></term> 2996 <listitem> 2997 <para> 2998 hash value (usually inode number) to search for 2999 </para> 3000 </listitem> 3001 </varlistentry> 3002 <varlistentry> 3003 <term><parameter>test</parameter></term> 3004 <listitem> 3005 <para> 3006 callback used for comparisons between inodes 3007 </para> 3008 </listitem> 3009 </varlistentry> 3010 <varlistentry> 3011 <term><parameter>data</parameter></term> 3012 <listitem> 3013 <para> 3014 opaque data pointer to pass to <parameter>test</parameter> 3015 </para> 3016 </listitem> 3017 </varlistentry> 3018 </variablelist> 3019</refsect1> 3020<refsect1> 3021<title>Description</title> 3022<para> 3023 Search for the inode specified by <parameter>hashval</parameter> and <parameter>data</parameter> in the inode cache, 3024 and if the inode is in the cache, return the inode with an incremented 3025 reference count. Waits on I_NEW before returning the inode. 3026 returned with an incremented reference count. 3027 </para><para> 3028 3029 This is a generalized version of <function>ilookup</function> for file systems where the 3030 inode number is not sufficient for unique identification of an inode. 3031</para> 3032</refsect1> 3033<refsect1> 3034<title>Note</title> 3035<para> 3036 <parameter>test</parameter> is called with the inode_hash_lock held, so can't sleep. 3037</para> 3038</refsect1> 3039</refentry> 3040 3041<refentry id="API-ilookup"> 3042<refentryinfo> 3043 <title>LINUX</title> 3044 <productname>Kernel Hackers Manual</productname> 3045 <date>July 2017</date> 3046</refentryinfo> 3047<refmeta> 3048 <refentrytitle><phrase>ilookup</phrase></refentrytitle> 3049 <manvolnum>9</manvolnum> 3050 <refmiscinfo class="version">4.1.27</refmiscinfo> 3051</refmeta> 3052<refnamediv> 3053 <refname>ilookup</refname> 3054 <refpurpose> 3055 search for an inode in the inode cache 3056 </refpurpose> 3057</refnamediv> 3058<refsynopsisdiv> 3059 <title>Synopsis</title> 3060 <funcsynopsis><funcprototype> 3061 <funcdef>struct inode * <function>ilookup </function></funcdef> 3062 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 3063 <paramdef>unsigned long <parameter>ino</parameter></paramdef> 3064 </funcprototype></funcsynopsis> 3065</refsynopsisdiv> 3066<refsect1> 3067 <title>Arguments</title> 3068 <variablelist> 3069 <varlistentry> 3070 <term><parameter>sb</parameter></term> 3071 <listitem> 3072 <para> 3073 super block of file system to search 3074 </para> 3075 </listitem> 3076 </varlistentry> 3077 <varlistentry> 3078 <term><parameter>ino</parameter></term> 3079 <listitem> 3080 <para> 3081 inode number to search for 3082 </para> 3083 </listitem> 3084 </varlistentry> 3085 </variablelist> 3086</refsect1> 3087<refsect1> 3088<title>Description</title> 3089<para> 3090 Search for the inode <parameter>ino</parameter> in the inode cache, and if the inode is in the 3091 cache, the inode is returned with an incremented reference count. 3092</para> 3093</refsect1> 3094</refentry> 3095 3096<refentry id="API-find-inode-nowait"> 3097<refentryinfo> 3098 <title>LINUX</title> 3099 <productname>Kernel Hackers Manual</productname> 3100 <date>July 2017</date> 3101</refentryinfo> 3102<refmeta> 3103 <refentrytitle><phrase>find_inode_nowait</phrase></refentrytitle> 3104 <manvolnum>9</manvolnum> 3105 <refmiscinfo class="version">4.1.27</refmiscinfo> 3106</refmeta> 3107<refnamediv> 3108 <refname>find_inode_nowait</refname> 3109 <refpurpose> 3110 find an inode in the inode cache 3111 </refpurpose> 3112</refnamediv> 3113<refsynopsisdiv> 3114 <title>Synopsis</title> 3115 <funcsynopsis><funcprototype> 3116 <funcdef>struct inode * <function>find_inode_nowait </function></funcdef> 3117 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 3118 <paramdef>unsigned long <parameter>hashval</parameter></paramdef> 3119 <paramdef>int (*<parameter>match</parameter>) 3120 <funcparams>struct inode *, unsigned long, void *</funcparams></paramdef> 3121 <paramdef>void * <parameter>data</parameter></paramdef> 3122 </funcprototype></funcsynopsis> 3123</refsynopsisdiv> 3124<refsect1> 3125 <title>Arguments</title> 3126 <variablelist> 3127 <varlistentry> 3128 <term><parameter>sb</parameter></term> 3129 <listitem> 3130 <para> 3131 super block of file system to search 3132 </para> 3133 </listitem> 3134 </varlistentry> 3135 <varlistentry> 3136 <term><parameter>hashval</parameter></term> 3137 <listitem> 3138 <para> 3139 hash value (usually inode number) to search for 3140 </para> 3141 </listitem> 3142 </varlistentry> 3143 <varlistentry> 3144 <term><parameter>match</parameter></term> 3145 <listitem> 3146 <para> 3147 callback used for comparisons between inodes 3148 </para> 3149 </listitem> 3150 </varlistentry> 3151 <varlistentry> 3152 <term><parameter>data</parameter></term> 3153 <listitem> 3154 <para> 3155 opaque data pointer to pass to <parameter>match</parameter> 3156 </para> 3157 </listitem> 3158 </varlistentry> 3159 </variablelist> 3160</refsect1> 3161<refsect1> 3162<title>Description</title> 3163<para> 3164 Search for the inode specified by <parameter>hashval</parameter> and <parameter>data</parameter> in the inode 3165 cache, where the helper function <parameter>match</parameter> will return 0 if the inode 3166 does not match, 1 if the inode does match, and -1 if the search 3167 should be stopped. The <parameter>match</parameter> function must be responsible for 3168 taking the i_lock spin_lock and checking i_state for an inode being 3169 freed or being initialized, and incrementing the reference count 3170 before returning 1. It also must not sleep, since it is called with 3171 the inode_hash_lock spinlock held. 3172 </para><para> 3173 3174 This is a even more generalized version of <function>ilookup5</function> when the 3175 function must never block --- <function>find_inode</function> can block in 3176 <function>__wait_on_freeing_inode</function> --- or when the caller can not increment 3177 the reference count because the resulting <function>iput</function> might cause an 3178 inode eviction. The tradeoff is that the <parameter>match</parameter> funtion must be 3179 very carefully implemented. 3180</para> 3181</refsect1> 3182</refentry> 3183 3184<refentry id="API-iput"> 3185<refentryinfo> 3186 <title>LINUX</title> 3187 <productname>Kernel Hackers Manual</productname> 3188 <date>July 2017</date> 3189</refentryinfo> 3190<refmeta> 3191 <refentrytitle><phrase>iput</phrase></refentrytitle> 3192 <manvolnum>9</manvolnum> 3193 <refmiscinfo class="version">4.1.27</refmiscinfo> 3194</refmeta> 3195<refnamediv> 3196 <refname>iput</refname> 3197 <refpurpose> 3198 put an inode 3199 </refpurpose> 3200</refnamediv> 3201<refsynopsisdiv> 3202 <title>Synopsis</title> 3203 <funcsynopsis><funcprototype> 3204 <funcdef>void <function>iput </function></funcdef> 3205 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3206 </funcprototype></funcsynopsis> 3207</refsynopsisdiv> 3208<refsect1> 3209 <title>Arguments</title> 3210 <variablelist> 3211 <varlistentry> 3212 <term><parameter>inode</parameter></term> 3213 <listitem> 3214 <para> 3215 inode to put 3216 </para> 3217 </listitem> 3218 </varlistentry> 3219 </variablelist> 3220</refsect1> 3221<refsect1> 3222<title>Description</title> 3223<para> 3224 Puts an inode, dropping its usage count. If the inode use count hits 3225 zero, the inode is then freed and may also be destroyed. 3226 </para><para> 3227 3228 Consequently, <function>iput</function> can sleep. 3229</para> 3230</refsect1> 3231</refentry> 3232 3233<refentry id="API-bmap"> 3234<refentryinfo> 3235 <title>LINUX</title> 3236 <productname>Kernel Hackers Manual</productname> 3237 <date>July 2017</date> 3238</refentryinfo> 3239<refmeta> 3240 <refentrytitle><phrase>bmap</phrase></refentrytitle> 3241 <manvolnum>9</manvolnum> 3242 <refmiscinfo class="version">4.1.27</refmiscinfo> 3243</refmeta> 3244<refnamediv> 3245 <refname>bmap</refname> 3246 <refpurpose> 3247 find a block number in a file 3248 </refpurpose> 3249</refnamediv> 3250<refsynopsisdiv> 3251 <title>Synopsis</title> 3252 <funcsynopsis><funcprototype> 3253 <funcdef>sector_t <function>bmap </function></funcdef> 3254 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3255 <paramdef>sector_t <parameter>block</parameter></paramdef> 3256 </funcprototype></funcsynopsis> 3257</refsynopsisdiv> 3258<refsect1> 3259 <title>Arguments</title> 3260 <variablelist> 3261 <varlistentry> 3262 <term><parameter>inode</parameter></term> 3263 <listitem> 3264 <para> 3265 inode of file 3266 </para> 3267 </listitem> 3268 </varlistentry> 3269 <varlistentry> 3270 <term><parameter>block</parameter></term> 3271 <listitem> 3272 <para> 3273 block to find 3274 </para> 3275 </listitem> 3276 </varlistentry> 3277 </variablelist> 3278</refsect1> 3279<refsect1> 3280<title>Description</title> 3281<para> 3282 Returns the block number on the device holding the inode that 3283 is the disk block number for the block of the file requested. 3284 That is, asked for block 4 of inode 1 the function will return the 3285 disk block relative to the disk start that holds that block of the 3286 file. 3287</para> 3288</refsect1> 3289</refentry> 3290 3291<refentry id="API-touch-atime"> 3292<refentryinfo> 3293 <title>LINUX</title> 3294 <productname>Kernel Hackers Manual</productname> 3295 <date>July 2017</date> 3296</refentryinfo> 3297<refmeta> 3298 <refentrytitle><phrase>touch_atime</phrase></refentrytitle> 3299 <manvolnum>9</manvolnum> 3300 <refmiscinfo class="version">4.1.27</refmiscinfo> 3301</refmeta> 3302<refnamediv> 3303 <refname>touch_atime</refname> 3304 <refpurpose> 3305 update the access time 3306 </refpurpose> 3307</refnamediv> 3308<refsynopsisdiv> 3309 <title>Synopsis</title> 3310 <funcsynopsis><funcprototype> 3311 <funcdef>void <function>touch_atime </function></funcdef> 3312 <paramdef>const struct path * <parameter>path</parameter></paramdef> 3313 </funcprototype></funcsynopsis> 3314</refsynopsisdiv> 3315<refsect1> 3316 <title>Arguments</title> 3317 <variablelist> 3318 <varlistentry> 3319 <term><parameter>path</parameter></term> 3320 <listitem> 3321 <para> 3322 the <structname>struct path</structname> to update 3323 </para> 3324 </listitem> 3325 </varlistentry> 3326 </variablelist> 3327</refsect1> 3328<refsect1> 3329<title>Description</title> 3330<para> 3331 Update the accessed time on an inode and mark it for writeback. 3332 This function automatically handles read only file systems and media, 3333 as well as the <quote>noatime</quote> flag and inode specific <quote>noatime</quote> markers. 3334</para> 3335</refsect1> 3336</refentry> 3337 3338<refentry id="API-file-update-time"> 3339<refentryinfo> 3340 <title>LINUX</title> 3341 <productname>Kernel Hackers Manual</productname> 3342 <date>July 2017</date> 3343</refentryinfo> 3344<refmeta> 3345 <refentrytitle><phrase>file_update_time</phrase></refentrytitle> 3346 <manvolnum>9</manvolnum> 3347 <refmiscinfo class="version">4.1.27</refmiscinfo> 3348</refmeta> 3349<refnamediv> 3350 <refname>file_update_time</refname> 3351 <refpurpose> 3352 update mtime and ctime time 3353 </refpurpose> 3354</refnamediv> 3355<refsynopsisdiv> 3356 <title>Synopsis</title> 3357 <funcsynopsis><funcprototype> 3358 <funcdef>int <function>file_update_time </function></funcdef> 3359 <paramdef>struct file * <parameter>file</parameter></paramdef> 3360 </funcprototype></funcsynopsis> 3361</refsynopsisdiv> 3362<refsect1> 3363 <title>Arguments</title> 3364 <variablelist> 3365 <varlistentry> 3366 <term><parameter>file</parameter></term> 3367 <listitem> 3368 <para> 3369 file accessed 3370 </para> 3371 </listitem> 3372 </varlistentry> 3373 </variablelist> 3374</refsect1> 3375<refsect1> 3376<title>Description</title> 3377<para> 3378 Update the mtime and ctime members of an inode and mark the inode 3379 for writeback. Note that this function is meant exclusively for 3380 usage in the file write path of filesystems, and filesystems may 3381 choose to explicitly ignore update via this function with the 3382 S_NOCMTIME inode flag, e.g. for network filesystem where these 3383 timestamps are handled by the server. This can return an error for 3384 file systems who need to allocate space in order to update an inode. 3385</para> 3386</refsect1> 3387</refentry> 3388 3389<refentry id="API-inode-init-owner"> 3390<refentryinfo> 3391 <title>LINUX</title> 3392 <productname>Kernel Hackers Manual</productname> 3393 <date>July 2017</date> 3394</refentryinfo> 3395<refmeta> 3396 <refentrytitle><phrase>inode_init_owner</phrase></refentrytitle> 3397 <manvolnum>9</manvolnum> 3398 <refmiscinfo class="version">4.1.27</refmiscinfo> 3399</refmeta> 3400<refnamediv> 3401 <refname>inode_init_owner</refname> 3402 <refpurpose> 3403 Init uid,gid,mode for new inode according to posix standards 3404 </refpurpose> 3405</refnamediv> 3406<refsynopsisdiv> 3407 <title>Synopsis</title> 3408 <funcsynopsis><funcprototype> 3409 <funcdef>void <function>inode_init_owner </function></funcdef> 3410 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3411 <paramdef>const struct inode * <parameter>dir</parameter></paramdef> 3412 <paramdef>umode_t <parameter>mode</parameter></paramdef> 3413 </funcprototype></funcsynopsis> 3414</refsynopsisdiv> 3415<refsect1> 3416 <title>Arguments</title> 3417 <variablelist> 3418 <varlistentry> 3419 <term><parameter>inode</parameter></term> 3420 <listitem> 3421 <para> 3422 New inode 3423 </para> 3424 </listitem> 3425 </varlistentry> 3426 <varlistentry> 3427 <term><parameter>dir</parameter></term> 3428 <listitem> 3429 <para> 3430 Directory inode 3431 </para> 3432 </listitem> 3433 </varlistentry> 3434 <varlistentry> 3435 <term><parameter>mode</parameter></term> 3436 <listitem> 3437 <para> 3438 mode of the new inode 3439 </para> 3440 </listitem> 3441 </varlistentry> 3442 </variablelist> 3443</refsect1> 3444</refentry> 3445 3446<refentry id="API-inode-owner-or-capable"> 3447<refentryinfo> 3448 <title>LINUX</title> 3449 <productname>Kernel Hackers Manual</productname> 3450 <date>July 2017</date> 3451</refentryinfo> 3452<refmeta> 3453 <refentrytitle><phrase>inode_owner_or_capable</phrase></refentrytitle> 3454 <manvolnum>9</manvolnum> 3455 <refmiscinfo class="version">4.1.27</refmiscinfo> 3456</refmeta> 3457<refnamediv> 3458 <refname>inode_owner_or_capable</refname> 3459 <refpurpose> 3460 check current task permissions to inode 3461 </refpurpose> 3462</refnamediv> 3463<refsynopsisdiv> 3464 <title>Synopsis</title> 3465 <funcsynopsis><funcprototype> 3466 <funcdef>bool <function>inode_owner_or_capable </function></funcdef> 3467 <paramdef>const struct inode * <parameter>inode</parameter></paramdef> 3468 </funcprototype></funcsynopsis> 3469</refsynopsisdiv> 3470<refsect1> 3471 <title>Arguments</title> 3472 <variablelist> 3473 <varlistentry> 3474 <term><parameter>inode</parameter></term> 3475 <listitem> 3476 <para> 3477 inode being checked 3478 </para> 3479 </listitem> 3480 </varlistentry> 3481 </variablelist> 3482</refsect1> 3483<refsect1> 3484<title>Description</title> 3485<para> 3486 Return true if current either has CAP_FOWNER in a namespace with the 3487 inode owner uid mapped, or owns the file. 3488</para> 3489</refsect1> 3490</refentry> 3491 3492<refentry id="API-inode-dio-wait"> 3493<refentryinfo> 3494 <title>LINUX</title> 3495 <productname>Kernel Hackers Manual</productname> 3496 <date>July 2017</date> 3497</refentryinfo> 3498<refmeta> 3499 <refentrytitle><phrase>inode_dio_wait</phrase></refentrytitle> 3500 <manvolnum>9</manvolnum> 3501 <refmiscinfo class="version">4.1.27</refmiscinfo> 3502</refmeta> 3503<refnamediv> 3504 <refname>inode_dio_wait</refname> 3505 <refpurpose> 3506 wait for outstanding DIO requests to finish 3507 </refpurpose> 3508</refnamediv> 3509<refsynopsisdiv> 3510 <title>Synopsis</title> 3511 <funcsynopsis><funcprototype> 3512 <funcdef>void <function>inode_dio_wait </function></funcdef> 3513 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3514 </funcprototype></funcsynopsis> 3515</refsynopsisdiv> 3516<refsect1> 3517 <title>Arguments</title> 3518 <variablelist> 3519 <varlistentry> 3520 <term><parameter>inode</parameter></term> 3521 <listitem> 3522 <para> 3523 inode to wait for 3524 </para> 3525 </listitem> 3526 </varlistentry> 3527 </variablelist> 3528</refsect1> 3529<refsect1> 3530<title>Description</title> 3531<para> 3532 Waits for all pending direct I/O requests to finish so that we can 3533 proceed with a truncate or equivalent operation. 3534 </para><para> 3535 3536 Must be called under a lock that serializes taking new references 3537 to i_dio_count, usually by inode->i_mutex. 3538</para> 3539</refsect1> 3540</refentry> 3541 3542<!-- fs/bad_inode.c --> 3543<refentry id="API-make-bad-inode"> 3544<refentryinfo> 3545 <title>LINUX</title> 3546 <productname>Kernel Hackers Manual</productname> 3547 <date>July 2017</date> 3548</refentryinfo> 3549<refmeta> 3550 <refentrytitle><phrase>make_bad_inode</phrase></refentrytitle> 3551 <manvolnum>9</manvolnum> 3552 <refmiscinfo class="version">4.1.27</refmiscinfo> 3553</refmeta> 3554<refnamediv> 3555 <refname>make_bad_inode</refname> 3556 <refpurpose> 3557 mark an inode bad due to an I/O error 3558 </refpurpose> 3559</refnamediv> 3560<refsynopsisdiv> 3561 <title>Synopsis</title> 3562 <funcsynopsis><funcprototype> 3563 <funcdef>void <function>make_bad_inode </function></funcdef> 3564 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3565 </funcprototype></funcsynopsis> 3566</refsynopsisdiv> 3567<refsect1> 3568 <title>Arguments</title> 3569 <variablelist> 3570 <varlistentry> 3571 <term><parameter>inode</parameter></term> 3572 <listitem> 3573 <para> 3574 Inode to mark bad 3575 </para> 3576 </listitem> 3577 </varlistentry> 3578 </variablelist> 3579</refsect1> 3580<refsect1> 3581<title>Description</title> 3582<para> 3583 When an inode cannot be read due to a media or remote network 3584 failure this function makes the inode <quote>bad</quote> and causes I/O operations 3585 on it to fail from this point on. 3586</para> 3587</refsect1> 3588</refentry> 3589 3590<refentry id="API-is-bad-inode"> 3591<refentryinfo> 3592 <title>LINUX</title> 3593 <productname>Kernel Hackers Manual</productname> 3594 <date>July 2017</date> 3595</refentryinfo> 3596<refmeta> 3597 <refentrytitle><phrase>is_bad_inode</phrase></refentrytitle> 3598 <manvolnum>9</manvolnum> 3599 <refmiscinfo class="version">4.1.27</refmiscinfo> 3600</refmeta> 3601<refnamediv> 3602 <refname>is_bad_inode</refname> 3603 <refpurpose> 3604 is an inode errored 3605 </refpurpose> 3606</refnamediv> 3607<refsynopsisdiv> 3608 <title>Synopsis</title> 3609 <funcsynopsis><funcprototype> 3610 <funcdef>int <function>is_bad_inode </function></funcdef> 3611 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3612 </funcprototype></funcsynopsis> 3613</refsynopsisdiv> 3614<refsect1> 3615 <title>Arguments</title> 3616 <variablelist> 3617 <varlistentry> 3618 <term><parameter>inode</parameter></term> 3619 <listitem> 3620 <para> 3621 inode to test 3622 </para> 3623 </listitem> 3624 </varlistentry> 3625 </variablelist> 3626</refsect1> 3627<refsect1> 3628<title>Description</title> 3629<para> 3630 Returns true if the inode in question has been marked as bad. 3631</para> 3632</refsect1> 3633</refentry> 3634 3635<refentry id="API-iget-failed"> 3636<refentryinfo> 3637 <title>LINUX</title> 3638 <productname>Kernel Hackers Manual</productname> 3639 <date>July 2017</date> 3640</refentryinfo> 3641<refmeta> 3642 <refentrytitle><phrase>iget_failed</phrase></refentrytitle> 3643 <manvolnum>9</manvolnum> 3644 <refmiscinfo class="version">4.1.27</refmiscinfo> 3645</refmeta> 3646<refnamediv> 3647 <refname>iget_failed</refname> 3648 <refpurpose> 3649 Mark an under-construction inode as dead and release it 3650 </refpurpose> 3651</refnamediv> 3652<refsynopsisdiv> 3653 <title>Synopsis</title> 3654 <funcsynopsis><funcprototype> 3655 <funcdef>void <function>iget_failed </function></funcdef> 3656 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 3657 </funcprototype></funcsynopsis> 3658</refsynopsisdiv> 3659<refsect1> 3660 <title>Arguments</title> 3661 <variablelist> 3662 <varlistentry> 3663 <term><parameter>inode</parameter></term> 3664 <listitem> 3665 <para> 3666 The inode to discard 3667 </para> 3668 </listitem> 3669 </varlistentry> 3670 </variablelist> 3671</refsect1> 3672<refsect1> 3673<title>Description</title> 3674<para> 3675 Mark an under-construction inode as dead and release it. 3676</para> 3677</refsect1> 3678</refentry> 3679 3680 </sect1> 3681 <sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title> 3682<!-- fs/super.c --> 3683<refentry id="API-deactivate-locked-super"> 3684<refentryinfo> 3685 <title>LINUX</title> 3686 <productname>Kernel Hackers Manual</productname> 3687 <date>July 2017</date> 3688</refentryinfo> 3689<refmeta> 3690 <refentrytitle><phrase>deactivate_locked_super</phrase></refentrytitle> 3691 <manvolnum>9</manvolnum> 3692 <refmiscinfo class="version">4.1.27</refmiscinfo> 3693</refmeta> 3694<refnamediv> 3695 <refname>deactivate_locked_super</refname> 3696 <refpurpose> 3697 drop an active reference to superblock 3698 </refpurpose> 3699</refnamediv> 3700<refsynopsisdiv> 3701 <title>Synopsis</title> 3702 <funcsynopsis><funcprototype> 3703 <funcdef>void <function>deactivate_locked_super </function></funcdef> 3704 <paramdef>struct super_block * <parameter>s</parameter></paramdef> 3705 </funcprototype></funcsynopsis> 3706</refsynopsisdiv> 3707<refsect1> 3708 <title>Arguments</title> 3709 <variablelist> 3710 <varlistentry> 3711 <term><parameter>s</parameter></term> 3712 <listitem> 3713 <para> 3714 superblock to deactivate 3715 </para> 3716 </listitem> 3717 </varlistentry> 3718 </variablelist> 3719</refsect1> 3720<refsect1> 3721<title>Description</title> 3722<para> 3723 Drops an active reference to superblock, converting it into a temprory 3724 one if there is no other active references left. In that case we 3725 tell fs driver to shut it down and drop the temporary reference we 3726 had just acquired. 3727 </para><para> 3728 3729 Caller holds exclusive lock on superblock; that lock is released. 3730</para> 3731</refsect1> 3732</refentry> 3733 3734<refentry id="API-deactivate-super"> 3735<refentryinfo> 3736 <title>LINUX</title> 3737 <productname>Kernel Hackers Manual</productname> 3738 <date>July 2017</date> 3739</refentryinfo> 3740<refmeta> 3741 <refentrytitle><phrase>deactivate_super</phrase></refentrytitle> 3742 <manvolnum>9</manvolnum> 3743 <refmiscinfo class="version">4.1.27</refmiscinfo> 3744</refmeta> 3745<refnamediv> 3746 <refname>deactivate_super</refname> 3747 <refpurpose> 3748 drop an active reference to superblock 3749 </refpurpose> 3750</refnamediv> 3751<refsynopsisdiv> 3752 <title>Synopsis</title> 3753 <funcsynopsis><funcprototype> 3754 <funcdef>void <function>deactivate_super </function></funcdef> 3755 <paramdef>struct super_block * <parameter>s</parameter></paramdef> 3756 </funcprototype></funcsynopsis> 3757</refsynopsisdiv> 3758<refsect1> 3759 <title>Arguments</title> 3760 <variablelist> 3761 <varlistentry> 3762 <term><parameter>s</parameter></term> 3763 <listitem> 3764 <para> 3765 superblock to deactivate 3766 </para> 3767 </listitem> 3768 </varlistentry> 3769 </variablelist> 3770</refsect1> 3771<refsect1> 3772<title>Description</title> 3773<para> 3774 Variant of <function>deactivate_locked_super</function>, except that superblock is *not* 3775 locked by caller. If we are going to drop the final active reference, 3776 lock will be acquired prior to that. 3777</para> 3778</refsect1> 3779</refentry> 3780 3781<refentry id="API-generic-shutdown-super"> 3782<refentryinfo> 3783 <title>LINUX</title> 3784 <productname>Kernel Hackers Manual</productname> 3785 <date>July 2017</date> 3786</refentryinfo> 3787<refmeta> 3788 <refentrytitle><phrase>generic_shutdown_super</phrase></refentrytitle> 3789 <manvolnum>9</manvolnum> 3790 <refmiscinfo class="version">4.1.27</refmiscinfo> 3791</refmeta> 3792<refnamediv> 3793 <refname>generic_shutdown_super</refname> 3794 <refpurpose> 3795 common helper for -><function>kill_sb</function> 3796 </refpurpose> 3797</refnamediv> 3798<refsynopsisdiv> 3799 <title>Synopsis</title> 3800 <funcsynopsis><funcprototype> 3801 <funcdef>void <function>generic_shutdown_super </function></funcdef> 3802 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 3803 </funcprototype></funcsynopsis> 3804</refsynopsisdiv> 3805<refsect1> 3806 <title>Arguments</title> 3807 <variablelist> 3808 <varlistentry> 3809 <term><parameter>sb</parameter></term> 3810 <listitem> 3811 <para> 3812 superblock to kill 3813 </para> 3814 </listitem> 3815 </varlistentry> 3816 </variablelist> 3817</refsect1> 3818<refsect1> 3819<title>Description</title> 3820<para> 3821 <function>generic_shutdown_super</function> does all fs-independent work on superblock 3822 shutdown. Typical -><function>kill_sb</function> should pick all fs-specific objects 3823 that need destruction out of superblock, call <function>generic_shutdown_super</function> 3824 and release aforementioned objects. Note: dentries and inodes _are_ 3825 taken care of and do not need specific handling. 3826 </para><para> 3827 3828 Upon calling this function, the filesystem may no longer alter or 3829 rearrange the set of dentries belonging to this super_block, nor may it 3830 change the attachments of dentries to inodes. 3831</para> 3832</refsect1> 3833</refentry> 3834 3835<refentry id="API-sget"> 3836<refentryinfo> 3837 <title>LINUX</title> 3838 <productname>Kernel Hackers Manual</productname> 3839 <date>July 2017</date> 3840</refentryinfo> 3841<refmeta> 3842 <refentrytitle><phrase>sget</phrase></refentrytitle> 3843 <manvolnum>9</manvolnum> 3844 <refmiscinfo class="version">4.1.27</refmiscinfo> 3845</refmeta> 3846<refnamediv> 3847 <refname>sget</refname> 3848 <refpurpose> 3849 find or create a superblock 3850 </refpurpose> 3851</refnamediv> 3852<refsynopsisdiv> 3853 <title>Synopsis</title> 3854 <funcsynopsis><funcprototype> 3855 <funcdef>struct super_block * <function>sget </function></funcdef> 3856 <paramdef>struct file_system_type * <parameter>type</parameter></paramdef> 3857 <paramdef>int (*<parameter>test</parameter>) 3858 <funcparams>struct super_block *,void *</funcparams></paramdef> 3859 <paramdef>int (*<parameter>set</parameter>) 3860 <funcparams>struct super_block *,void *</funcparams></paramdef> 3861 <paramdef>int <parameter>flags</parameter></paramdef> 3862 <paramdef>void * <parameter>data</parameter></paramdef> 3863 </funcprototype></funcsynopsis> 3864</refsynopsisdiv> 3865<refsect1> 3866 <title>Arguments</title> 3867 <variablelist> 3868 <varlistentry> 3869 <term><parameter>type</parameter></term> 3870 <listitem> 3871 <para> 3872 filesystem type superblock should belong to 3873 </para> 3874 </listitem> 3875 </varlistentry> 3876 <varlistentry> 3877 <term><parameter>test</parameter></term> 3878 <listitem> 3879 <para> 3880 comparison callback 3881 </para> 3882 </listitem> 3883 </varlistentry> 3884 <varlistentry> 3885 <term><parameter>set</parameter></term> 3886 <listitem> 3887 <para> 3888 setup callback 3889 </para> 3890 </listitem> 3891 </varlistentry> 3892 <varlistentry> 3893 <term><parameter>flags</parameter></term> 3894 <listitem> 3895 <para> 3896 mount flags 3897 </para> 3898 </listitem> 3899 </varlistentry> 3900 <varlistentry> 3901 <term><parameter>data</parameter></term> 3902 <listitem> 3903 <para> 3904 argument to each of them 3905 </para> 3906 </listitem> 3907 </varlistentry> 3908 </variablelist> 3909</refsect1> 3910</refentry> 3911 3912<refentry id="API-iterate-supers-type"> 3913<refentryinfo> 3914 <title>LINUX</title> 3915 <productname>Kernel Hackers Manual</productname> 3916 <date>July 2017</date> 3917</refentryinfo> 3918<refmeta> 3919 <refentrytitle><phrase>iterate_supers_type</phrase></refentrytitle> 3920 <manvolnum>9</manvolnum> 3921 <refmiscinfo class="version">4.1.27</refmiscinfo> 3922</refmeta> 3923<refnamediv> 3924 <refname>iterate_supers_type</refname> 3925 <refpurpose> 3926 call function for superblocks of given type 3927 </refpurpose> 3928</refnamediv> 3929<refsynopsisdiv> 3930 <title>Synopsis</title> 3931 <funcsynopsis><funcprototype> 3932 <funcdef>void <function>iterate_supers_type </function></funcdef> 3933 <paramdef>struct file_system_type * <parameter>type</parameter></paramdef> 3934 <paramdef>void (*<parameter>f</parameter>) 3935 <funcparams>struct super_block *, void *</funcparams></paramdef> 3936 <paramdef>void * <parameter>arg</parameter></paramdef> 3937 </funcprototype></funcsynopsis> 3938</refsynopsisdiv> 3939<refsect1> 3940 <title>Arguments</title> 3941 <variablelist> 3942 <varlistentry> 3943 <term><parameter>type</parameter></term> 3944 <listitem> 3945 <para> 3946 fs type 3947 </para> 3948 </listitem> 3949 </varlistentry> 3950 <varlistentry> 3951 <term><parameter>f</parameter></term> 3952 <listitem> 3953 <para> 3954 function to call 3955 </para> 3956 </listitem> 3957 </varlistentry> 3958 <varlistentry> 3959 <term><parameter>arg</parameter></term> 3960 <listitem> 3961 <para> 3962 argument to pass to it 3963 </para> 3964 </listitem> 3965 </varlistentry> 3966 </variablelist> 3967</refsect1> 3968<refsect1> 3969<title>Description</title> 3970<para> 3971 Scans the superblock list and calls given function, passing it 3972 locked superblock and given argument. 3973</para> 3974</refsect1> 3975</refentry> 3976 3977<refentry id="API-get-super"> 3978<refentryinfo> 3979 <title>LINUX</title> 3980 <productname>Kernel Hackers Manual</productname> 3981 <date>July 2017</date> 3982</refentryinfo> 3983<refmeta> 3984 <refentrytitle><phrase>get_super</phrase></refentrytitle> 3985 <manvolnum>9</manvolnum> 3986 <refmiscinfo class="version">4.1.27</refmiscinfo> 3987</refmeta> 3988<refnamediv> 3989 <refname>get_super</refname> 3990 <refpurpose> 3991 get the superblock of a device 3992 </refpurpose> 3993</refnamediv> 3994<refsynopsisdiv> 3995 <title>Synopsis</title> 3996 <funcsynopsis><funcprototype> 3997 <funcdef>struct super_block * <function>get_super </function></funcdef> 3998 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 3999 </funcprototype></funcsynopsis> 4000</refsynopsisdiv> 4001<refsect1> 4002 <title>Arguments</title> 4003 <variablelist> 4004 <varlistentry> 4005 <term><parameter>bdev</parameter></term> 4006 <listitem> 4007 <para> 4008 device to get the superblock for 4009 </para><para> 4010 4011 Scans the superblock list and finds the superblock of the file system 4012 mounted on the device given. <constant>NULL</constant> is returned if no match is found. 4013 </para> 4014 </listitem> 4015 </varlistentry> 4016 </variablelist> 4017</refsect1> 4018</refentry> 4019 4020<refentry id="API-get-super-thawed"> 4021<refentryinfo> 4022 <title>LINUX</title> 4023 <productname>Kernel Hackers Manual</productname> 4024 <date>July 2017</date> 4025</refentryinfo> 4026<refmeta> 4027 <refentrytitle><phrase>get_super_thawed</phrase></refentrytitle> 4028 <manvolnum>9</manvolnum> 4029 <refmiscinfo class="version">4.1.27</refmiscinfo> 4030</refmeta> 4031<refnamediv> 4032 <refname>get_super_thawed</refname> 4033 <refpurpose> 4034 get thawed superblock of a device 4035 </refpurpose> 4036</refnamediv> 4037<refsynopsisdiv> 4038 <title>Synopsis</title> 4039 <funcsynopsis><funcprototype> 4040 <funcdef>struct super_block * <function>get_super_thawed </function></funcdef> 4041 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 4042 </funcprototype></funcsynopsis> 4043</refsynopsisdiv> 4044<refsect1> 4045 <title>Arguments</title> 4046 <variablelist> 4047 <varlistentry> 4048 <term><parameter>bdev</parameter></term> 4049 <listitem> 4050 <para> 4051 device to get the superblock for 4052 </para> 4053 </listitem> 4054 </varlistentry> 4055 </variablelist> 4056</refsect1> 4057<refsect1> 4058<title>Description</title> 4059<para> 4060 Scans the superblock list and finds the superblock of the file system 4061 mounted on the device. The superblock is returned once it is thawed 4062 (or immediately if it was not frozen). <constant>NULL</constant> is returned if no match 4063 is found. 4064</para> 4065</refsect1> 4066</refentry> 4067 4068<refentry id="API-freeze-super"> 4069<refentryinfo> 4070 <title>LINUX</title> 4071 <productname>Kernel Hackers Manual</productname> 4072 <date>July 2017</date> 4073</refentryinfo> 4074<refmeta> 4075 <refentrytitle><phrase>freeze_super</phrase></refentrytitle> 4076 <manvolnum>9</manvolnum> 4077 <refmiscinfo class="version">4.1.27</refmiscinfo> 4078</refmeta> 4079<refnamediv> 4080 <refname>freeze_super</refname> 4081 <refpurpose> 4082 lock the filesystem and force it into a consistent state 4083 </refpurpose> 4084</refnamediv> 4085<refsynopsisdiv> 4086 <title>Synopsis</title> 4087 <funcsynopsis><funcprototype> 4088 <funcdef>int <function>freeze_super </function></funcdef> 4089 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 4090 </funcprototype></funcsynopsis> 4091</refsynopsisdiv> 4092<refsect1> 4093 <title>Arguments</title> 4094 <variablelist> 4095 <varlistentry> 4096 <term><parameter>sb</parameter></term> 4097 <listitem> 4098 <para> 4099 the super to lock 4100 </para> 4101 </listitem> 4102 </varlistentry> 4103 </variablelist> 4104</refsect1> 4105<refsect1> 4106<title>Description</title> 4107<para> 4108 Syncs the super to make sure the filesystem is consistent and calls the fs's 4109 freeze_fs. Subsequent calls to this without first thawing the fs will return 4110 -EBUSY. 4111 </para><para> 4112 4113 During this function, sb->s_writers.frozen goes through these values: 4114</para> 4115</refsect1> 4116<refsect1> 4117<title>SB_UNFROZEN</title> 4118<para> 4119 File system is normal, all writes progress as usual. 4120</para> 4121</refsect1> 4122<refsect1> 4123<title>SB_FREEZE_WRITE</title> 4124<para> 4125 The file system is in the process of being frozen. New 4126 writes should be blocked, though page faults are still allowed. We wait for 4127 all writes to complete and then proceed to the next stage. 4128</para> 4129</refsect1> 4130<refsect1> 4131<title>SB_FREEZE_PAGEFAULT</title> 4132<para> 4133 Freezing continues. Now also page faults are blocked 4134 but internal fs threads can still modify the filesystem (although they 4135 should not dirty new pages or inodes), writeback can run etc. After waiting 4136 for all running page faults we sync the filesystem which will clean all 4137 dirty pages and inodes (no new dirty pages or inodes can be created when 4138 sync is running). 4139</para> 4140</refsect1> 4141<refsect1> 4142<title>SB_FREEZE_FS</title> 4143<para> 4144 The file system is frozen. Now all internal sources of fs 4145 modification are blocked (e.g. XFS preallocation truncation on inode 4146 reclaim). This is usually implemented by blocking new transactions for 4147 filesystems that have them and need this additional guard. After all 4148 internal writers are finished we call -><function>freeze_fs</function> to finish filesystem 4149 freezing. Then we transition to SB_FREEZE_COMPLETE state. This state is 4150 mostly auxiliary for filesystems to verify they do not modify frozen fs. 4151 </para><para> 4152 4153 sb->s_writers.frozen is protected by sb->s_umount. 4154</para> 4155</refsect1> 4156</refentry> 4157 4158<refentry id="API-thaw-super"> 4159<refentryinfo> 4160 <title>LINUX</title> 4161 <productname>Kernel Hackers Manual</productname> 4162 <date>July 2017</date> 4163</refentryinfo> 4164<refmeta> 4165 <refentrytitle><phrase>thaw_super</phrase></refentrytitle> 4166 <manvolnum>9</manvolnum> 4167 <refmiscinfo class="version">4.1.27</refmiscinfo> 4168</refmeta> 4169<refnamediv> 4170 <refname>thaw_super</refname> 4171 <refpurpose> 4172 - unlock filesystem 4173 </refpurpose> 4174</refnamediv> 4175<refsynopsisdiv> 4176 <title>Synopsis</title> 4177 <funcsynopsis><funcprototype> 4178 <funcdef>int <function>thaw_super </function></funcdef> 4179 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 4180 </funcprototype></funcsynopsis> 4181</refsynopsisdiv> 4182<refsect1> 4183 <title>Arguments</title> 4184 <variablelist> 4185 <varlistentry> 4186 <term><parameter>sb</parameter></term> 4187 <listitem> 4188 <para> 4189 the super to thaw 4190 </para> 4191 </listitem> 4192 </varlistentry> 4193 </variablelist> 4194</refsect1> 4195<refsect1> 4196<title>Description</title> 4197<para> 4198 Unlocks the filesystem and marks it writeable again after <function>freeze_super</function>. 4199</para> 4200</refsect1> 4201</refentry> 4202 4203 </sect1> 4204 <sect1 id="file_locks"><title>File Locks</title> 4205<!-- fs/locks.c --> 4206<refentry id="API-posix-lock-file"> 4207<refentryinfo> 4208 <title>LINUX</title> 4209 <productname>Kernel Hackers Manual</productname> 4210 <date>July 2017</date> 4211</refentryinfo> 4212<refmeta> 4213 <refentrytitle><phrase>posix_lock_file</phrase></refentrytitle> 4214 <manvolnum>9</manvolnum> 4215 <refmiscinfo class="version">4.1.27</refmiscinfo> 4216</refmeta> 4217<refnamediv> 4218 <refname>posix_lock_file</refname> 4219 <refpurpose> 4220 Apply a POSIX-style lock to a file 4221 </refpurpose> 4222</refnamediv> 4223<refsynopsisdiv> 4224 <title>Synopsis</title> 4225 <funcsynopsis><funcprototype> 4226 <funcdef>int <function>posix_lock_file </function></funcdef> 4227 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4228 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4229 <paramdef>struct file_lock * <parameter>conflock</parameter></paramdef> 4230 </funcprototype></funcsynopsis> 4231</refsynopsisdiv> 4232<refsect1> 4233 <title>Arguments</title> 4234 <variablelist> 4235 <varlistentry> 4236 <term><parameter>filp</parameter></term> 4237 <listitem> 4238 <para> 4239 The file to apply the lock to 4240 </para> 4241 </listitem> 4242 </varlistentry> 4243 <varlistentry> 4244 <term><parameter>fl</parameter></term> 4245 <listitem> 4246 <para> 4247 The lock to be applied 4248 </para> 4249 </listitem> 4250 </varlistentry> 4251 <varlistentry> 4252 <term><parameter>conflock</parameter></term> 4253 <listitem> 4254 <para> 4255 Place to return a copy of the conflicting lock, if found. 4256 </para> 4257 </listitem> 4258 </varlistentry> 4259 </variablelist> 4260</refsect1> 4261<refsect1> 4262<title>Description</title> 4263<para> 4264 Add a POSIX style lock to a file. 4265 We merge adjacent & overlapping locks whenever possible. 4266 POSIX locks are sorted by owner task, then by starting address 4267 </para><para> 4268 4269 Note that if called with an FL_EXISTS argument, the caller may determine 4270 whether or not a lock was successfully freed by testing the return 4271 value for -ENOENT. 4272</para> 4273</refsect1> 4274</refentry> 4275 4276<refentry id="API-posix-lock-inode-wait"> 4277<refentryinfo> 4278 <title>LINUX</title> 4279 <productname>Kernel Hackers Manual</productname> 4280 <date>July 2017</date> 4281</refentryinfo> 4282<refmeta> 4283 <refentrytitle><phrase>posix_lock_inode_wait</phrase></refentrytitle> 4284 <manvolnum>9</manvolnum> 4285 <refmiscinfo class="version">4.1.27</refmiscinfo> 4286</refmeta> 4287<refnamediv> 4288 <refname>posix_lock_inode_wait</refname> 4289 <refpurpose> 4290 Apply a POSIX-style lock to a file 4291 </refpurpose> 4292</refnamediv> 4293<refsynopsisdiv> 4294 <title>Synopsis</title> 4295 <funcsynopsis><funcprototype> 4296 <funcdef>int <function>posix_lock_inode_wait </function></funcdef> 4297 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 4298 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4299 </funcprototype></funcsynopsis> 4300</refsynopsisdiv> 4301<refsect1> 4302 <title>Arguments</title> 4303 <variablelist> 4304 <varlistentry> 4305 <term><parameter>inode</parameter></term> 4306 <listitem> 4307 <para> 4308 inode of file to which lock request should be applied 4309 </para> 4310 </listitem> 4311 </varlistentry> 4312 <varlistentry> 4313 <term><parameter>fl</parameter></term> 4314 <listitem> 4315 <para> 4316 The lock to be applied 4317 </para> 4318 </listitem> 4319 </varlistentry> 4320 </variablelist> 4321</refsect1> 4322<refsect1> 4323<title>Description</title> 4324<para> 4325 Variant of posix_lock_file_wait that does not take a filp, and so can be 4326 used after the filp has already been torn down. 4327</para> 4328</refsect1> 4329</refentry> 4330 4331<refentry id="API-locks-mandatory-area"> 4332<refentryinfo> 4333 <title>LINUX</title> 4334 <productname>Kernel Hackers Manual</productname> 4335 <date>July 2017</date> 4336</refentryinfo> 4337<refmeta> 4338 <refentrytitle><phrase>locks_mandatory_area</phrase></refentrytitle> 4339 <manvolnum>9</manvolnum> 4340 <refmiscinfo class="version">4.1.27</refmiscinfo> 4341</refmeta> 4342<refnamediv> 4343 <refname>locks_mandatory_area</refname> 4344 <refpurpose> 4345 Check for a conflicting lock 4346 </refpurpose> 4347</refnamediv> 4348<refsynopsisdiv> 4349 <title>Synopsis</title> 4350 <funcsynopsis><funcprototype> 4351 <funcdef>int <function>locks_mandatory_area </function></funcdef> 4352 <paramdef>int <parameter>read_write</parameter></paramdef> 4353 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 4354 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4355 <paramdef>loff_t <parameter>offset</parameter></paramdef> 4356 <paramdef>size_t <parameter>count</parameter></paramdef> 4357 </funcprototype></funcsynopsis> 4358</refsynopsisdiv> 4359<refsect1> 4360 <title>Arguments</title> 4361 <variablelist> 4362 <varlistentry> 4363 <term><parameter>read_write</parameter></term> 4364 <listitem> 4365 <para> 4366 <constant>FLOCK_VERIFY_WRITE</constant> for exclusive access, <constant>FLOCK_VERIFY_READ</constant> 4367 for shared 4368 </para> 4369 </listitem> 4370 </varlistentry> 4371 <varlistentry> 4372 <term><parameter>inode</parameter></term> 4373 <listitem> 4374 <para> 4375 the file to check 4376 </para> 4377 </listitem> 4378 </varlistentry> 4379 <varlistentry> 4380 <term><parameter>filp</parameter></term> 4381 <listitem> 4382 <para> 4383 how the file was opened (if it was) 4384 </para> 4385 </listitem> 4386 </varlistentry> 4387 <varlistentry> 4388 <term><parameter>offset</parameter></term> 4389 <listitem> 4390 <para> 4391 start of area to check 4392 </para> 4393 </listitem> 4394 </varlistentry> 4395 <varlistentry> 4396 <term><parameter>count</parameter></term> 4397 <listitem> 4398 <para> 4399 length of area to check 4400 </para> 4401 </listitem> 4402 </varlistentry> 4403 </variablelist> 4404</refsect1> 4405<refsect1> 4406<title>Description</title> 4407<para> 4408 Searches the inode's list of locks to find any POSIX locks which conflict. 4409 This function is called from <function>rw_verify_area</function> and 4410 <function>locks_verify_truncate</function>. 4411</para> 4412</refsect1> 4413</refentry> 4414 4415<refentry id="API---break-lease"> 4416<refentryinfo> 4417 <title>LINUX</title> 4418 <productname>Kernel Hackers Manual</productname> 4419 <date>July 2017</date> 4420</refentryinfo> 4421<refmeta> 4422 <refentrytitle><phrase>__break_lease</phrase></refentrytitle> 4423 <manvolnum>9</manvolnum> 4424 <refmiscinfo class="version">4.1.27</refmiscinfo> 4425</refmeta> 4426<refnamediv> 4427 <refname>__break_lease</refname> 4428 <refpurpose> 4429 revoke all outstanding leases on file 4430 </refpurpose> 4431</refnamediv> 4432<refsynopsisdiv> 4433 <title>Synopsis</title> 4434 <funcsynopsis><funcprototype> 4435 <funcdef>int <function>__break_lease </function></funcdef> 4436 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 4437 <paramdef>unsigned int <parameter>mode</parameter></paramdef> 4438 <paramdef>unsigned int <parameter>type</parameter></paramdef> 4439 </funcprototype></funcsynopsis> 4440</refsynopsisdiv> 4441<refsect1> 4442 <title>Arguments</title> 4443 <variablelist> 4444 <varlistentry> 4445 <term><parameter>inode</parameter></term> 4446 <listitem> 4447 <para> 4448 the inode of the file to return 4449 </para> 4450 </listitem> 4451 </varlistentry> 4452 <varlistentry> 4453 <term><parameter>mode</parameter></term> 4454 <listitem> 4455 <para> 4456 O_RDONLY: break only write leases; O_WRONLY or O_RDWR: 4457 break all leases 4458 </para> 4459 </listitem> 4460 </varlistentry> 4461 <varlistentry> 4462 <term><parameter>type</parameter></term> 4463 <listitem> 4464 <para> 4465 FL_LEASE: break leases and delegations; FL_DELEG: break 4466 only delegations 4467 </para> 4468 </listitem> 4469 </varlistentry> 4470 </variablelist> 4471</refsect1> 4472<refsect1> 4473<title>Description</title> 4474<para> 4475 break_lease (inlined for speed) has checked there already is at least 4476 some kind of lock (maybe a lease) on this file. Leases are broken on 4477 a call to <function>open</function> or <function>truncate</function>. This function can sleep unless you 4478 specified <constant>O_NONBLOCK</constant> to your <function>open</function>. 4479</para> 4480</refsect1> 4481</refentry> 4482 4483<refentry id="API-lease-get-mtime"> 4484<refentryinfo> 4485 <title>LINUX</title> 4486 <productname>Kernel Hackers Manual</productname> 4487 <date>July 2017</date> 4488</refentryinfo> 4489<refmeta> 4490 <refentrytitle><phrase>lease_get_mtime</phrase></refentrytitle> 4491 <manvolnum>9</manvolnum> 4492 <refmiscinfo class="version">4.1.27</refmiscinfo> 4493</refmeta> 4494<refnamediv> 4495 <refname>lease_get_mtime</refname> 4496 <refpurpose> 4497 get the last modified time of an inode 4498 </refpurpose> 4499</refnamediv> 4500<refsynopsisdiv> 4501 <title>Synopsis</title> 4502 <funcsynopsis><funcprototype> 4503 <funcdef>void <function>lease_get_mtime </function></funcdef> 4504 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 4505 <paramdef>struct timespec * <parameter>time</parameter></paramdef> 4506 </funcprototype></funcsynopsis> 4507</refsynopsisdiv> 4508<refsect1> 4509 <title>Arguments</title> 4510 <variablelist> 4511 <varlistentry> 4512 <term><parameter>inode</parameter></term> 4513 <listitem> 4514 <para> 4515 the inode 4516 </para> 4517 </listitem> 4518 </varlistentry> 4519 <varlistentry> 4520 <term><parameter>time</parameter></term> 4521 <listitem> 4522 <para> 4523 pointer to a timespec which will contain the last modified time 4524 </para> 4525 </listitem> 4526 </varlistentry> 4527 </variablelist> 4528</refsect1> 4529<refsect1> 4530<title>Description</title> 4531<para> 4532 This is to force NFS clients to flush their caches for files with 4533 exclusive leases. The justification is that if someone has an 4534 exclusive lease, then they could be modifying it. 4535</para> 4536</refsect1> 4537</refentry> 4538 4539<refentry id="API-generic-setlease"> 4540<refentryinfo> 4541 <title>LINUX</title> 4542 <productname>Kernel Hackers Manual</productname> 4543 <date>July 2017</date> 4544</refentryinfo> 4545<refmeta> 4546 <refentrytitle><phrase>generic_setlease</phrase></refentrytitle> 4547 <manvolnum>9</manvolnum> 4548 <refmiscinfo class="version">4.1.27</refmiscinfo> 4549</refmeta> 4550<refnamediv> 4551 <refname>generic_setlease</refname> 4552 <refpurpose> 4553 sets a lease on an open file 4554 </refpurpose> 4555</refnamediv> 4556<refsynopsisdiv> 4557 <title>Synopsis</title> 4558 <funcsynopsis><funcprototype> 4559 <funcdef>int <function>generic_setlease </function></funcdef> 4560 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4561 <paramdef>long <parameter>arg</parameter></paramdef> 4562 <paramdef>struct file_lock ** <parameter>flp</parameter></paramdef> 4563 <paramdef>void ** <parameter>priv</parameter></paramdef> 4564 </funcprototype></funcsynopsis> 4565</refsynopsisdiv> 4566<refsect1> 4567 <title>Arguments</title> 4568 <variablelist> 4569 <varlistentry> 4570 <term><parameter>filp</parameter></term> 4571 <listitem> 4572 <para> 4573 file pointer 4574 </para> 4575 </listitem> 4576 </varlistentry> 4577 <varlistentry> 4578 <term><parameter>arg</parameter></term> 4579 <listitem> 4580 <para> 4581 type of lease to obtain 4582 </para> 4583 </listitem> 4584 </varlistentry> 4585 <varlistentry> 4586 <term><parameter>flp</parameter></term> 4587 <listitem> 4588 <para> 4589 input - file_lock to use, output - file_lock inserted 4590 </para> 4591 </listitem> 4592 </varlistentry> 4593 <varlistentry> 4594 <term><parameter>priv</parameter></term> 4595 <listitem> 4596 <para> 4597 private data for lm_setup (may be NULL if lm_setup 4598 doesn't require it) 4599 </para> 4600 </listitem> 4601 </varlistentry> 4602 </variablelist> 4603</refsect1> 4604<refsect1> 4605<title>Description</title> 4606<para> 4607 The (input) flp->fl_lmops->lm_break function is required 4608 by <function>break_lease</function>. 4609</para> 4610</refsect1> 4611</refentry> 4612 4613<refentry id="API-vfs-setlease"> 4614<refentryinfo> 4615 <title>LINUX</title> 4616 <productname>Kernel Hackers Manual</productname> 4617 <date>July 2017</date> 4618</refentryinfo> 4619<refmeta> 4620 <refentrytitle><phrase>vfs_setlease</phrase></refentrytitle> 4621 <manvolnum>9</manvolnum> 4622 <refmiscinfo class="version">4.1.27</refmiscinfo> 4623</refmeta> 4624<refnamediv> 4625 <refname>vfs_setlease</refname> 4626 <refpurpose> 4627 sets a lease on an open file 4628 </refpurpose> 4629</refnamediv> 4630<refsynopsisdiv> 4631 <title>Synopsis</title> 4632 <funcsynopsis><funcprototype> 4633 <funcdef>int <function>vfs_setlease </function></funcdef> 4634 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4635 <paramdef>long <parameter>arg</parameter></paramdef> 4636 <paramdef>struct file_lock ** <parameter>lease</parameter></paramdef> 4637 <paramdef>void ** <parameter>priv</parameter></paramdef> 4638 </funcprototype></funcsynopsis> 4639</refsynopsisdiv> 4640<refsect1> 4641 <title>Arguments</title> 4642 <variablelist> 4643 <varlistentry> 4644 <term><parameter>filp</parameter></term> 4645 <listitem> 4646 <para> 4647 file pointer 4648 </para> 4649 </listitem> 4650 </varlistentry> 4651 <varlistentry> 4652 <term><parameter>arg</parameter></term> 4653 <listitem> 4654 <para> 4655 type of lease to obtain 4656 </para> 4657 </listitem> 4658 </varlistentry> 4659 <varlistentry> 4660 <term><parameter>lease</parameter></term> 4661 <listitem> 4662 <para> 4663 file_lock to use when adding a lease 4664 </para> 4665 </listitem> 4666 </varlistentry> 4667 <varlistentry> 4668 <term><parameter>priv</parameter></term> 4669 <listitem> 4670 <para> 4671 private info for lm_setup when adding a lease (may be 4672 NULL if lm_setup doesn't require it) 4673 </para> 4674 </listitem> 4675 </varlistentry> 4676 </variablelist> 4677</refsect1> 4678<refsect1> 4679<title>Description</title> 4680<para> 4681 Call this to establish a lease on the file. The <quote>lease</quote> argument is not 4682 used for F_UNLCK requests and may be NULL. For commands that set or alter 4683 an existing lease, the (*lease)->fl_lmops->lm_break operation must be set; 4684 if not, this function will return -ENOLCK (and generate a scary-looking 4685 stack trace). 4686 </para><para> 4687 4688 The <quote>priv</quote> pointer is passed directly to the lm_setup function as-is. It 4689 may be NULL if the lm_setup operation doesn't require it. 4690</para> 4691</refsect1> 4692</refentry> 4693 4694<refentry id="API-flock-lock-inode-wait"> 4695<refentryinfo> 4696 <title>LINUX</title> 4697 <productname>Kernel Hackers Manual</productname> 4698 <date>July 2017</date> 4699</refentryinfo> 4700<refmeta> 4701 <refentrytitle><phrase>flock_lock_inode_wait</phrase></refentrytitle> 4702 <manvolnum>9</manvolnum> 4703 <refmiscinfo class="version">4.1.27</refmiscinfo> 4704</refmeta> 4705<refnamediv> 4706 <refname>flock_lock_inode_wait</refname> 4707 <refpurpose> 4708 Apply a FLOCK-style lock to a file 4709 </refpurpose> 4710</refnamediv> 4711<refsynopsisdiv> 4712 <title>Synopsis</title> 4713 <funcsynopsis><funcprototype> 4714 <funcdef>int <function>flock_lock_inode_wait </function></funcdef> 4715 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 4716 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4717 </funcprototype></funcsynopsis> 4718</refsynopsisdiv> 4719<refsect1> 4720 <title>Arguments</title> 4721 <variablelist> 4722 <varlistentry> 4723 <term><parameter>inode</parameter></term> 4724 <listitem> 4725 <para> 4726 inode of the file to apply to 4727 </para> 4728 </listitem> 4729 </varlistentry> 4730 <varlistentry> 4731 <term><parameter>fl</parameter></term> 4732 <listitem> 4733 <para> 4734 The lock to be applied 4735 </para> 4736 </listitem> 4737 </varlistentry> 4738 </variablelist> 4739</refsect1> 4740<refsect1> 4741<title>Description</title> 4742<para> 4743 Apply a FLOCK style lock request to an inode. 4744</para> 4745</refsect1> 4746</refentry> 4747 4748<refentry id="API-vfs-test-lock"> 4749<refentryinfo> 4750 <title>LINUX</title> 4751 <productname>Kernel Hackers Manual</productname> 4752 <date>July 2017</date> 4753</refentryinfo> 4754<refmeta> 4755 <refentrytitle><phrase>vfs_test_lock</phrase></refentrytitle> 4756 <manvolnum>9</manvolnum> 4757 <refmiscinfo class="version">4.1.27</refmiscinfo> 4758</refmeta> 4759<refnamediv> 4760 <refname>vfs_test_lock</refname> 4761 <refpurpose> 4762 test file byte range lock 4763 </refpurpose> 4764</refnamediv> 4765<refsynopsisdiv> 4766 <title>Synopsis</title> 4767 <funcsynopsis><funcprototype> 4768 <funcdef>int <function>vfs_test_lock </function></funcdef> 4769 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4770 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4771 </funcprototype></funcsynopsis> 4772</refsynopsisdiv> 4773<refsect1> 4774 <title>Arguments</title> 4775 <variablelist> 4776 <varlistentry> 4777 <term><parameter>filp</parameter></term> 4778 <listitem> 4779 <para> 4780 The file to test lock for 4781 </para> 4782 </listitem> 4783 </varlistentry> 4784 <varlistentry> 4785 <term><parameter>fl</parameter></term> 4786 <listitem> 4787 <para> 4788 The lock to test; also used to hold result 4789 </para> 4790 </listitem> 4791 </varlistentry> 4792 </variablelist> 4793</refsect1> 4794<refsect1> 4795<title>Description</title> 4796<para> 4797 Returns -ERRNO on failure. Indicates presence of conflicting lock by 4798 setting conf->fl_type to something other than F_UNLCK. 4799</para> 4800</refsect1> 4801</refentry> 4802 4803<refentry id="API-vfs-lock-file"> 4804<refentryinfo> 4805 <title>LINUX</title> 4806 <productname>Kernel Hackers Manual</productname> 4807 <date>July 2017</date> 4808</refentryinfo> 4809<refmeta> 4810 <refentrytitle><phrase>vfs_lock_file</phrase></refentrytitle> 4811 <manvolnum>9</manvolnum> 4812 <refmiscinfo class="version">4.1.27</refmiscinfo> 4813</refmeta> 4814<refnamediv> 4815 <refname>vfs_lock_file</refname> 4816 <refpurpose> 4817 file byte range lock 4818 </refpurpose> 4819</refnamediv> 4820<refsynopsisdiv> 4821 <title>Synopsis</title> 4822 <funcsynopsis><funcprototype> 4823 <funcdef>int <function>vfs_lock_file </function></funcdef> 4824 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4825 <paramdef>unsigned int <parameter>cmd</parameter></paramdef> 4826 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4827 <paramdef>struct file_lock * <parameter>conf</parameter></paramdef> 4828 </funcprototype></funcsynopsis> 4829</refsynopsisdiv> 4830<refsect1> 4831 <title>Arguments</title> 4832 <variablelist> 4833 <varlistentry> 4834 <term><parameter>filp</parameter></term> 4835 <listitem> 4836 <para> 4837 The file to apply the lock to 4838 </para> 4839 </listitem> 4840 </varlistentry> 4841 <varlistentry> 4842 <term><parameter>cmd</parameter></term> 4843 <listitem> 4844 <para> 4845 type of locking operation (F_SETLK, F_GETLK, etc.) 4846 </para> 4847 </listitem> 4848 </varlistentry> 4849 <varlistentry> 4850 <term><parameter>fl</parameter></term> 4851 <listitem> 4852 <para> 4853 The lock to be applied 4854 </para> 4855 </listitem> 4856 </varlistentry> 4857 <varlistentry> 4858 <term><parameter>conf</parameter></term> 4859 <listitem> 4860 <para> 4861 Place to return a copy of the conflicting lock, if found. 4862 </para> 4863 </listitem> 4864 </varlistentry> 4865 </variablelist> 4866</refsect1> 4867<refsect1> 4868<title>Description</title> 4869<para> 4870 A caller that doesn't care about the conflicting lock may pass NULL 4871 as the final argument. 4872 </para><para> 4873 4874 If the filesystem defines a private -><function>lock</function> method, then <parameter>conf</parameter> will 4875 be left unchanged; so a caller that cares should initialize it to 4876 some acceptable default. 4877 </para><para> 4878 4879 To avoid blocking kernel daemons, such as lockd, that need to acquire POSIX 4880 locks, the -><function>lock</function> interface may return asynchronously, before the lock has 4881 been granted or denied by the underlying filesystem, if (and only if) 4882 lm_grant is set. Callers expecting -><function>lock</function> to return asynchronously 4883 will only use F_SETLK, not F_SETLKW; they will set FL_SLEEP if (and only if) 4884 the request is for a blocking lock. When -><function>lock</function> does return asynchronously, 4885 it must return FILE_LOCK_DEFERRED, and call -><function>lm_grant</function> when the lock 4886 request completes. 4887 If the request is for non-blocking lock the file system should return 4888 FILE_LOCK_DEFERRED then try to get the lock and call the callback routine 4889 with the result. If the request timed out the callback routine will return a 4890 nonzero return code and the file system should release the lock. The file 4891 system is also responsible to keep a corresponding posix lock when it 4892 grants a lock so the VFS can find out which locks are locally held and do 4893 the correct lock cleanup when required. 4894 The underlying filesystem must not drop the kernel lock or call 4895 -><function>lm_grant</function> before returning to the caller with a FILE_LOCK_DEFERRED 4896 return code. 4897</para> 4898</refsect1> 4899</refentry> 4900 4901<refentry id="API-posix-unblock-lock"> 4902<refentryinfo> 4903 <title>LINUX</title> 4904 <productname>Kernel Hackers Manual</productname> 4905 <date>July 2017</date> 4906</refentryinfo> 4907<refmeta> 4908 <refentrytitle><phrase>posix_unblock_lock</phrase></refentrytitle> 4909 <manvolnum>9</manvolnum> 4910 <refmiscinfo class="version">4.1.27</refmiscinfo> 4911</refmeta> 4912<refnamediv> 4913 <refname>posix_unblock_lock</refname> 4914 <refpurpose> 4915 stop waiting for a file lock 4916 </refpurpose> 4917</refnamediv> 4918<refsynopsisdiv> 4919 <title>Synopsis</title> 4920 <funcsynopsis><funcprototype> 4921 <funcdef>int <function>posix_unblock_lock </function></funcdef> 4922 <paramdef>struct file_lock * <parameter>waiter</parameter></paramdef> 4923 </funcprototype></funcsynopsis> 4924</refsynopsisdiv> 4925<refsect1> 4926 <title>Arguments</title> 4927 <variablelist> 4928 <varlistentry> 4929 <term><parameter>waiter</parameter></term> 4930 <listitem> 4931 <para> 4932 the lock which was waiting 4933 </para> 4934 </listitem> 4935 </varlistentry> 4936 </variablelist> 4937</refsect1> 4938<refsect1> 4939<title>Description</title> 4940<para> 4941 lockd needs to block waiting for locks. 4942</para> 4943</refsect1> 4944</refentry> 4945 4946<refentry id="API-vfs-cancel-lock"> 4947<refentryinfo> 4948 <title>LINUX</title> 4949 <productname>Kernel Hackers Manual</productname> 4950 <date>July 2017</date> 4951</refentryinfo> 4952<refmeta> 4953 <refentrytitle><phrase>vfs_cancel_lock</phrase></refentrytitle> 4954 <manvolnum>9</manvolnum> 4955 <refmiscinfo class="version">4.1.27</refmiscinfo> 4956</refmeta> 4957<refnamediv> 4958 <refname>vfs_cancel_lock</refname> 4959 <refpurpose> 4960 file byte range unblock lock 4961 </refpurpose> 4962</refnamediv> 4963<refsynopsisdiv> 4964 <title>Synopsis</title> 4965 <funcsynopsis><funcprototype> 4966 <funcdef>int <function>vfs_cancel_lock </function></funcdef> 4967 <paramdef>struct file * <parameter>filp</parameter></paramdef> 4968 <paramdef>struct file_lock * <parameter>fl</parameter></paramdef> 4969 </funcprototype></funcsynopsis> 4970</refsynopsisdiv> 4971<refsect1> 4972 <title>Arguments</title> 4973 <variablelist> 4974 <varlistentry> 4975 <term><parameter>filp</parameter></term> 4976 <listitem> 4977 <para> 4978 The file to apply the unblock to 4979 </para> 4980 </listitem> 4981 </varlistentry> 4982 <varlistentry> 4983 <term><parameter>fl</parameter></term> 4984 <listitem> 4985 <para> 4986 The lock to be unblocked 4987 </para> 4988 </listitem> 4989 </varlistentry> 4990 </variablelist> 4991</refsect1> 4992<refsect1> 4993<title>Description</title> 4994<para> 4995 Used by lock managers to cancel blocked requests 4996</para> 4997</refsect1> 4998</refentry> 4999 5000<!-- fs/locks.c --> 5001<refentry id="API-locks-mandatory-locked"> 5002<refentryinfo> 5003 <title>LINUX</title> 5004 <productname>Kernel Hackers Manual</productname> 5005 <date>July 2017</date> 5006</refentryinfo> 5007<refmeta> 5008 <refentrytitle><phrase>locks_mandatory_locked</phrase></refentrytitle> 5009 <manvolnum>9</manvolnum> 5010 <refmiscinfo class="version">4.1.27</refmiscinfo> 5011</refmeta> 5012<refnamediv> 5013 <refname>locks_mandatory_locked</refname> 5014 <refpurpose> 5015 Check for an active lock 5016 </refpurpose> 5017</refnamediv> 5018<refsynopsisdiv> 5019 <title>Synopsis</title> 5020 <funcsynopsis><funcprototype> 5021 <funcdef>int <function>locks_mandatory_locked </function></funcdef> 5022 <paramdef>struct file * <parameter>file</parameter></paramdef> 5023 </funcprototype></funcsynopsis> 5024</refsynopsisdiv> 5025<refsect1> 5026 <title>Arguments</title> 5027 <variablelist> 5028 <varlistentry> 5029 <term><parameter>file</parameter></term> 5030 <listitem> 5031 <para> 5032 the file to check 5033 </para> 5034 </listitem> 5035 </varlistentry> 5036 </variablelist> 5037</refsect1> 5038<refsect1> 5039<title>Description</title> 5040<para> 5041 Searches the inode's list of locks to find any POSIX locks which conflict. 5042 This function is called from <function>locks_verify_locked</function> only. 5043</para> 5044</refsect1> 5045</refentry> 5046 5047<refentry id="API-fcntl-getlease"> 5048<refentryinfo> 5049 <title>LINUX</title> 5050 <productname>Kernel Hackers Manual</productname> 5051 <date>July 2017</date> 5052</refentryinfo> 5053<refmeta> 5054 <refentrytitle><phrase>fcntl_getlease</phrase></refentrytitle> 5055 <manvolnum>9</manvolnum> 5056 <refmiscinfo class="version">4.1.27</refmiscinfo> 5057</refmeta> 5058<refnamediv> 5059 <refname>fcntl_getlease</refname> 5060 <refpurpose> 5061 Enquire what lease is currently active 5062 </refpurpose> 5063</refnamediv> 5064<refsynopsisdiv> 5065 <title>Synopsis</title> 5066 <funcsynopsis><funcprototype> 5067 <funcdef>int <function>fcntl_getlease </function></funcdef> 5068 <paramdef>struct file * <parameter>filp</parameter></paramdef> 5069 </funcprototype></funcsynopsis> 5070</refsynopsisdiv> 5071<refsect1> 5072 <title>Arguments</title> 5073 <variablelist> 5074 <varlistentry> 5075 <term><parameter>filp</parameter></term> 5076 <listitem> 5077 <para> 5078 the file 5079 </para> 5080 </listitem> 5081 </varlistentry> 5082 </variablelist> 5083</refsect1> 5084<refsect1> 5085<title>Description</title> 5086<para> 5087 The value returned by this function will be one of 5088 (if no lease break is pending): 5089 </para><para> 5090 5091 <constant>F_RDLCK</constant> to indicate a shared lease is held. 5092 </para><para> 5093 5094 <constant>F_WRLCK</constant> to indicate an exclusive lease is held. 5095 </para><para> 5096 5097 <constant>F_UNLCK</constant> to indicate no lease is held. 5098 </para><para> 5099 5100 (if a lease break is pending): 5101 </para><para> 5102 5103 <constant>F_RDLCK</constant> to indicate an exclusive lease needs to be 5104 changed to a shared lease (or removed). 5105 </para><para> 5106 5107 <constant>F_UNLCK</constant> to indicate the lease needs to be removed. 5108</para> 5109</refsect1> 5110<refsect1> 5111<title>XXX</title> 5112<para> 5113 sfr & willy disagree over whether F_INPROGRESS 5114 should be returned to userspace. 5115</para> 5116</refsect1> 5117</refentry> 5118 5119<refentry id="API-check-conflicting-open"> 5120<refentryinfo> 5121 <title>LINUX</title> 5122 <productname>Kernel Hackers Manual</productname> 5123 <date>July 2017</date> 5124</refentryinfo> 5125<refmeta> 5126 <refentrytitle><phrase>check_conflicting_open</phrase></refentrytitle> 5127 <manvolnum>9</manvolnum> 5128 <refmiscinfo class="version">4.1.27</refmiscinfo> 5129</refmeta> 5130<refnamediv> 5131 <refname>check_conflicting_open</refname> 5132 <refpurpose> 5133 see if the given dentry points to a file that has an existing open that would conflict with the desired lease. 5134 </refpurpose> 5135</refnamediv> 5136<refsynopsisdiv> 5137 <title>Synopsis</title> 5138 <funcsynopsis><funcprototype> 5139 <funcdef>int <function>check_conflicting_open </function></funcdef> 5140 <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef> 5141 <paramdef>const long <parameter>arg</parameter></paramdef> 5142 <paramdef>int <parameter>flags</parameter></paramdef> 5143 </funcprototype></funcsynopsis> 5144</refsynopsisdiv> 5145<refsect1> 5146 <title>Arguments</title> 5147 <variablelist> 5148 <varlistentry> 5149 <term><parameter>dentry</parameter></term> 5150 <listitem> 5151 <para> 5152 dentry to check 5153 </para> 5154 </listitem> 5155 </varlistentry> 5156 <varlistentry> 5157 <term><parameter>arg</parameter></term> 5158 <listitem> 5159 <para> 5160 type of lease that we're trying to acquire 5161 </para> 5162 </listitem> 5163 </varlistentry> 5164 <varlistentry> 5165 <term><parameter>flags</parameter></term> 5166 <listitem> 5167 <para> 5168 -- undescribed -- 5169 </para> 5170 </listitem> 5171 </varlistentry> 5172 </variablelist> 5173</refsect1> 5174<refsect1> 5175<title>Description</title> 5176<para> 5177 Check to see if there's an existing open fd on this file that would 5178 conflict with the lease we're trying to set. 5179</para> 5180</refsect1> 5181</refentry> 5182 5183<refentry id="API-fcntl-setlease"> 5184<refentryinfo> 5185 <title>LINUX</title> 5186 <productname>Kernel Hackers Manual</productname> 5187 <date>July 2017</date> 5188</refentryinfo> 5189<refmeta> 5190 <refentrytitle><phrase>fcntl_setlease</phrase></refentrytitle> 5191 <manvolnum>9</manvolnum> 5192 <refmiscinfo class="version">4.1.27</refmiscinfo> 5193</refmeta> 5194<refnamediv> 5195 <refname>fcntl_setlease</refname> 5196 <refpurpose> 5197 sets a lease on an open file 5198 </refpurpose> 5199</refnamediv> 5200<refsynopsisdiv> 5201 <title>Synopsis</title> 5202 <funcsynopsis><funcprototype> 5203 <funcdef>int <function>fcntl_setlease </function></funcdef> 5204 <paramdef>unsigned int <parameter>fd</parameter></paramdef> 5205 <paramdef>struct file * <parameter>filp</parameter></paramdef> 5206 <paramdef>long <parameter>arg</parameter></paramdef> 5207 </funcprototype></funcsynopsis> 5208</refsynopsisdiv> 5209<refsect1> 5210 <title>Arguments</title> 5211 <variablelist> 5212 <varlistentry> 5213 <term><parameter>fd</parameter></term> 5214 <listitem> 5215 <para> 5216 open file descriptor 5217 </para> 5218 </listitem> 5219 </varlistentry> 5220 <varlistentry> 5221 <term><parameter>filp</parameter></term> 5222 <listitem> 5223 <para> 5224 file pointer 5225 </para> 5226 </listitem> 5227 </varlistentry> 5228 <varlistentry> 5229 <term><parameter>arg</parameter></term> 5230 <listitem> 5231 <para> 5232 type of lease to obtain 5233 </para> 5234 </listitem> 5235 </varlistentry> 5236 </variablelist> 5237</refsect1> 5238<refsect1> 5239<title>Description</title> 5240<para> 5241 Call this fcntl to establish a lease on the file. 5242 Note that you also need to call <constant>F_SETSIG</constant> to 5243 receive a signal when the lease is broken. 5244</para> 5245</refsect1> 5246</refentry> 5247 5248<refentry id="API-sys-flock"> 5249<refentryinfo> 5250 <title>LINUX</title> 5251 <productname>Kernel Hackers Manual</productname> 5252 <date>July 2017</date> 5253</refentryinfo> 5254<refmeta> 5255 <refentrytitle><phrase>sys_flock</phrase></refentrytitle> 5256 <manvolnum>9</manvolnum> 5257 <refmiscinfo class="version">4.1.27</refmiscinfo> 5258</refmeta> 5259<refnamediv> 5260 <refname>sys_flock</refname> 5261 <refpurpose> 5262 <function>flock</function> system call. 5263 </refpurpose> 5264</refnamediv> 5265<refsynopsisdiv> 5266 <title>Synopsis</title> 5267 <funcsynopsis><funcprototype> 5268 <funcdef>long <function>sys_flock </function></funcdef> 5269 <paramdef>unsigned int <parameter>fd</parameter></paramdef> 5270 <paramdef>unsigned int <parameter>cmd</parameter></paramdef> 5271 </funcprototype></funcsynopsis> 5272</refsynopsisdiv> 5273<refsect1> 5274 <title>Arguments</title> 5275 <variablelist> 5276 <varlistentry> 5277 <term><parameter>fd</parameter></term> 5278 <listitem> 5279 <para> 5280 the file descriptor to lock. 5281 </para> 5282 </listitem> 5283 </varlistentry> 5284 <varlistentry> 5285 <term><parameter>cmd</parameter></term> 5286 <listitem> 5287 <para> 5288 the type of lock to apply. 5289 </para> 5290 </listitem> 5291 </varlistentry> 5292 </variablelist> 5293</refsect1> 5294<refsect1> 5295<title>Description</title> 5296<para> 5297 Apply a <constant>FL_FLOCK</constant> style lock to an open file descriptor. 5298 The <parameter>cmd</parameter> can be one of 5299 </para><para> 5300 5301 <constant>LOCK_SH</constant> -- a shared lock. 5302 </para><para> 5303 5304 <constant>LOCK_EX</constant> -- an exclusive lock. 5305 </para><para> 5306 5307 <constant>LOCK_UN</constant> -- remove an existing lock. 5308 </para><para> 5309 5310 <constant>LOCK_MAND</constant> -- a `mandatory' flock. This exists to emulate Windows Share Modes. 5311 </para><para> 5312 5313 <constant>LOCK_MAND</constant> can be combined with <constant>LOCK_READ</constant> or <constant>LOCK_WRITE</constant> to allow other 5314 processes read and write access respectively. 5315</para> 5316</refsect1> 5317</refentry> 5318 5319 </sect1> 5320 <sect1 id="other_functions"><title>Other Functions</title> 5321<!-- fs/mpage.c --> 5322<refentry id="API-mpage-readpages"> 5323<refentryinfo> 5324 <title>LINUX</title> 5325 <productname>Kernel Hackers Manual</productname> 5326 <date>July 2017</date> 5327</refentryinfo> 5328<refmeta> 5329 <refentrytitle><phrase>mpage_readpages</phrase></refentrytitle> 5330 <manvolnum>9</manvolnum> 5331 <refmiscinfo class="version">4.1.27</refmiscinfo> 5332</refmeta> 5333<refnamediv> 5334 <refname>mpage_readpages</refname> 5335 <refpurpose> 5336 populate an address space with some pages & start reads against them 5337 </refpurpose> 5338</refnamediv> 5339<refsynopsisdiv> 5340 <title>Synopsis</title> 5341 <funcsynopsis><funcprototype> 5342 <funcdef>int <function>mpage_readpages </function></funcdef> 5343 <paramdef>struct address_space * <parameter>mapping</parameter></paramdef> 5344 <paramdef>struct list_head * <parameter>pages</parameter></paramdef> 5345 <paramdef>unsigned <parameter>nr_pages</parameter></paramdef> 5346 <paramdef>get_block_t <parameter>get_block</parameter></paramdef> 5347 </funcprototype></funcsynopsis> 5348</refsynopsisdiv> 5349<refsect1> 5350 <title>Arguments</title> 5351 <variablelist> 5352 <varlistentry> 5353 <term><parameter>mapping</parameter></term> 5354 <listitem> 5355 <para> 5356 the address_space 5357 </para> 5358 </listitem> 5359 </varlistentry> 5360 <varlistentry> 5361 <term><parameter>pages</parameter></term> 5362 <listitem> 5363 <para> 5364 The address of a list_head which contains the target pages. These 5365 pages have their ->index populated and are otherwise uninitialised. 5366 The page at <parameter>pages</parameter>->prev has the lowest file offset, and reads should be 5367 issued in <parameter>pages</parameter>->prev to <parameter>pages</parameter>->next order. 5368 </para> 5369 </listitem> 5370 </varlistentry> 5371 <varlistentry> 5372 <term><parameter>nr_pages</parameter></term> 5373 <listitem> 5374 <para> 5375 The number of pages at *<parameter>pages</parameter> 5376 </para> 5377 </listitem> 5378 </varlistentry> 5379 <varlistentry> 5380 <term><parameter>get_block</parameter></term> 5381 <listitem> 5382 <para> 5383 The filesystem's block mapper function. 5384 </para> 5385 </listitem> 5386 </varlistentry> 5387 </variablelist> 5388</refsect1> 5389<refsect1> 5390<title>Description</title> 5391<para> 5392 This function walks the pages and the blocks within each page, building and 5393 emitting large BIOs. 5394 </para><para> 5395 5396 If anything unusual happens, such as: 5397 </para><para> 5398 5399 - encountering a page which has buffers 5400 - encountering a page which has a non-hole after a hole 5401 - encountering a page with non-contiguous blocks 5402 </para><para> 5403 5404 then this code just gives up and calls the buffer_head-based read function. 5405 It does handle a page which has holes at the end - that is a common case: 5406 the end-of-file on blocksize < PAGE_CACHE_SIZE setups. 5407</para> 5408</refsect1> 5409<refsect1> 5410<title>BH_Boundary explanation</title> 5411<para> 5412 </para><para> 5413 5414 There is a problem. The mpage read code assembles several pages, gets all 5415 their disk mappings, and then submits them all. That's fine, but obtaining 5416 the disk mappings may require I/O. Reads of indirect blocks, for example. 5417 </para><para> 5418 5419 So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be 5420</para> 5421</refsect1> 5422<refsect1> 5423<title>submitted in the following order</title> 5424<para> 5425 12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16 5426 </para><para> 5427 5428 because the indirect block has to be read to get the mappings of blocks 5429 13,14,15,16. Obviously, this impacts performance. 5430 </para><para> 5431 5432 So what we do it to allow the filesystem's <function>get_block</function> function to set 5433 BH_Boundary when it maps block 11. BH_Boundary says: mapping of the block 5434 after this one will require I/O against a block which is probably close to 5435 this one. So you should push what I/O you have currently accumulated. 5436 </para><para> 5437 5438 This all causes the disk requests to be issued in the correct order. 5439</para> 5440</refsect1> 5441</refentry> 5442 5443<refentry id="API-mpage-writepages"> 5444<refentryinfo> 5445 <title>LINUX</title> 5446 <productname>Kernel Hackers Manual</productname> 5447 <date>July 2017</date> 5448</refentryinfo> 5449<refmeta> 5450 <refentrytitle><phrase>mpage_writepages</phrase></refentrytitle> 5451 <manvolnum>9</manvolnum> 5452 <refmiscinfo class="version">4.1.27</refmiscinfo> 5453</refmeta> 5454<refnamediv> 5455 <refname>mpage_writepages</refname> 5456 <refpurpose> 5457 walk the list of dirty pages of the given address space & <function>writepage</function> all of them 5458 </refpurpose> 5459</refnamediv> 5460<refsynopsisdiv> 5461 <title>Synopsis</title> 5462 <funcsynopsis><funcprototype> 5463 <funcdef>int <function>mpage_writepages </function></funcdef> 5464 <paramdef>struct address_space * <parameter>mapping</parameter></paramdef> 5465 <paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef> 5466 <paramdef>get_block_t <parameter>get_block</parameter></paramdef> 5467 </funcprototype></funcsynopsis> 5468</refsynopsisdiv> 5469<refsect1> 5470 <title>Arguments</title> 5471 <variablelist> 5472 <varlistentry> 5473 <term><parameter>mapping</parameter></term> 5474 <listitem> 5475 <para> 5476 address space structure to write 5477 </para> 5478 </listitem> 5479 </varlistentry> 5480 <varlistentry> 5481 <term><parameter>wbc</parameter></term> 5482 <listitem> 5483 <para> 5484 subtract the number of written pages from *<parameter>wbc</parameter>->nr_to_write 5485 </para> 5486 </listitem> 5487 </varlistentry> 5488 <varlistentry> 5489 <term><parameter>get_block</parameter></term> 5490 <listitem> 5491 <para> 5492 the filesystem's block mapper function. 5493 If this is NULL then use a_ops->writepage. Otherwise, go 5494 direct-to-BIO. 5495 </para> 5496 </listitem> 5497 </varlistentry> 5498 </variablelist> 5499</refsect1> 5500<refsect1> 5501<title>Description</title> 5502<para> 5503 This is a library function, which implements the <function>writepages</function> 5504 address_space_operation. 5505 </para><para> 5506 5507 If a page is already under I/O, <function>generic_writepages</function> skips it, even 5508 if it's dirty. This is desirable behaviour for memory-cleaning writeback, 5509 but it is INCORRECT for data-integrity system calls such as <function>fsync</function>. <function>fsync</function> 5510 and <function>msync</function> need to guarantee that all the data which was dirty at the time 5511 the call was made get new I/O started against them. If wbc->sync_mode is 5512 WB_SYNC_ALL then we were called for data integrity and we must wait for 5513 existing IO to complete. 5514</para> 5515</refsect1> 5516</refentry> 5517 5518<!-- fs/namei.c --> 5519<refentry id="API-generic-permission"> 5520<refentryinfo> 5521 <title>LINUX</title> 5522 <productname>Kernel Hackers Manual</productname> 5523 <date>July 2017</date> 5524</refentryinfo> 5525<refmeta> 5526 <refentrytitle><phrase>generic_permission</phrase></refentrytitle> 5527 <manvolnum>9</manvolnum> 5528 <refmiscinfo class="version">4.1.27</refmiscinfo> 5529</refmeta> 5530<refnamediv> 5531 <refname>generic_permission</refname> 5532 <refpurpose> 5533 check for access rights on a Posix-like filesystem 5534 </refpurpose> 5535</refnamediv> 5536<refsynopsisdiv> 5537 <title>Synopsis</title> 5538 <funcsynopsis><funcprototype> 5539 <funcdef>int <function>generic_permission </function></funcdef> 5540 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 5541 <paramdef>int <parameter>mask</parameter></paramdef> 5542 </funcprototype></funcsynopsis> 5543</refsynopsisdiv> 5544<refsect1> 5545 <title>Arguments</title> 5546 <variablelist> 5547 <varlistentry> 5548 <term><parameter>inode</parameter></term> 5549 <listitem> 5550 <para> 5551 inode to check access rights for 5552 </para> 5553 </listitem> 5554 </varlistentry> 5555 <varlistentry> 5556 <term><parameter>mask</parameter></term> 5557 <listitem> 5558 <para> 5559 right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>, ...) 5560 </para> 5561 </listitem> 5562 </varlistentry> 5563 </variablelist> 5564</refsect1> 5565<refsect1> 5566<title>Description</title> 5567<para> 5568 Used to check for read/write/execute permissions on a file. 5569 We use <quote>fsuid</quote> for this, letting us set arbitrary permissions 5570 for filesystem access without changing the <quote>normal</quote> uids which 5571 are used for other things. 5572 </para><para> 5573 5574 generic_permission is rcu-walk aware. It returns -ECHILD in case an rcu-walk 5575 request cannot be satisfied (eg. requires blocking or too much complexity). 5576 It would then be called again in ref-walk mode. 5577</para> 5578</refsect1> 5579</refentry> 5580 5581<refentry id="API---inode-permission"> 5582<refentryinfo> 5583 <title>LINUX</title> 5584 <productname>Kernel Hackers Manual</productname> 5585 <date>July 2017</date> 5586</refentryinfo> 5587<refmeta> 5588 <refentrytitle><phrase>__inode_permission</phrase></refentrytitle> 5589 <manvolnum>9</manvolnum> 5590 <refmiscinfo class="version">4.1.27</refmiscinfo> 5591</refmeta> 5592<refnamediv> 5593 <refname>__inode_permission</refname> 5594 <refpurpose> 5595 Check for access rights to a given inode 5596 </refpurpose> 5597</refnamediv> 5598<refsynopsisdiv> 5599 <title>Synopsis</title> 5600 <funcsynopsis><funcprototype> 5601 <funcdef>int <function>__inode_permission </function></funcdef> 5602 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 5603 <paramdef>int <parameter>mask</parameter></paramdef> 5604 </funcprototype></funcsynopsis> 5605</refsynopsisdiv> 5606<refsect1> 5607 <title>Arguments</title> 5608 <variablelist> 5609 <varlistentry> 5610 <term><parameter>inode</parameter></term> 5611 <listitem> 5612 <para> 5613 Inode to check permission on 5614 </para> 5615 </listitem> 5616 </varlistentry> 5617 <varlistentry> 5618 <term><parameter>mask</parameter></term> 5619 <listitem> 5620 <para> 5621 Right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>) 5622 </para> 5623 </listitem> 5624 </varlistentry> 5625 </variablelist> 5626</refsect1> 5627<refsect1> 5628<title>Description</title> 5629<para> 5630 Check for read/write/execute permissions on an inode. 5631 </para><para> 5632 5633 When checking for MAY_APPEND, MAY_WRITE must also be set in <parameter>mask</parameter>. 5634 </para><para> 5635 5636 This does not check for a read-only file system. You probably want 5637 <function>inode_permission</function>. 5638</para> 5639</refsect1> 5640</refentry> 5641 5642<refentry id="API-inode-permission"> 5643<refentryinfo> 5644 <title>LINUX</title> 5645 <productname>Kernel Hackers Manual</productname> 5646 <date>July 2017</date> 5647</refentryinfo> 5648<refmeta> 5649 <refentrytitle><phrase>inode_permission</phrase></refentrytitle> 5650 <manvolnum>9</manvolnum> 5651 <refmiscinfo class="version">4.1.27</refmiscinfo> 5652</refmeta> 5653<refnamediv> 5654 <refname>inode_permission</refname> 5655 <refpurpose> 5656 Check for access rights to a given inode 5657 </refpurpose> 5658</refnamediv> 5659<refsynopsisdiv> 5660 <title>Synopsis</title> 5661 <funcsynopsis><funcprototype> 5662 <funcdef>int <function>inode_permission </function></funcdef> 5663 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 5664 <paramdef>int <parameter>mask</parameter></paramdef> 5665 </funcprototype></funcsynopsis> 5666</refsynopsisdiv> 5667<refsect1> 5668 <title>Arguments</title> 5669 <variablelist> 5670 <varlistentry> 5671 <term><parameter>inode</parameter></term> 5672 <listitem> 5673 <para> 5674 Inode to check permission on 5675 </para> 5676 </listitem> 5677 </varlistentry> 5678 <varlistentry> 5679 <term><parameter>mask</parameter></term> 5680 <listitem> 5681 <para> 5682 Right to check for (<constant>MAY_READ</constant>, <constant>MAY_WRITE</constant>, <constant>MAY_EXEC</constant>) 5683 </para> 5684 </listitem> 5685 </varlistentry> 5686 </variablelist> 5687</refsect1> 5688<refsect1> 5689<title>Description</title> 5690<para> 5691 Check for read/write/execute permissions on an inode. We use fs[ug]id for 5692 this, letting us set arbitrary permissions for filesystem access without 5693 changing the <quote>normal</quote> UIDs which are used for other things. 5694 </para><para> 5695 5696 When checking for MAY_APPEND, MAY_WRITE must also be set in <parameter>mask</parameter>. 5697</para> 5698</refsect1> 5699</refentry> 5700 5701<refentry id="API-path-get"> 5702<refentryinfo> 5703 <title>LINUX</title> 5704 <productname>Kernel Hackers Manual</productname> 5705 <date>July 2017</date> 5706</refentryinfo> 5707<refmeta> 5708 <refentrytitle><phrase>path_get</phrase></refentrytitle> 5709 <manvolnum>9</manvolnum> 5710 <refmiscinfo class="version">4.1.27</refmiscinfo> 5711</refmeta> 5712<refnamediv> 5713 <refname>path_get</refname> 5714 <refpurpose> 5715 get a reference to a path 5716 </refpurpose> 5717</refnamediv> 5718<refsynopsisdiv> 5719 <title>Synopsis</title> 5720 <funcsynopsis><funcprototype> 5721 <funcdef>void <function>path_get </function></funcdef> 5722 <paramdef>const struct path * <parameter>path</parameter></paramdef> 5723 </funcprototype></funcsynopsis> 5724</refsynopsisdiv> 5725<refsect1> 5726 <title>Arguments</title> 5727 <variablelist> 5728 <varlistentry> 5729 <term><parameter>path</parameter></term> 5730 <listitem> 5731 <para> 5732 path to get the reference to 5733 </para> 5734 </listitem> 5735 </varlistentry> 5736 </variablelist> 5737</refsect1> 5738<refsect1> 5739<title>Description</title> 5740<para> 5741 Given a path increment the reference count to the dentry and the vfsmount. 5742</para> 5743</refsect1> 5744</refentry> 5745 5746<refentry id="API-path-put"> 5747<refentryinfo> 5748 <title>LINUX</title> 5749 <productname>Kernel Hackers Manual</productname> 5750 <date>July 2017</date> 5751</refentryinfo> 5752<refmeta> 5753 <refentrytitle><phrase>path_put</phrase></refentrytitle> 5754 <manvolnum>9</manvolnum> 5755 <refmiscinfo class="version">4.1.27</refmiscinfo> 5756</refmeta> 5757<refnamediv> 5758 <refname>path_put</refname> 5759 <refpurpose> 5760 put a reference to a path 5761 </refpurpose> 5762</refnamediv> 5763<refsynopsisdiv> 5764 <title>Synopsis</title> 5765 <funcsynopsis><funcprototype> 5766 <funcdef>void <function>path_put </function></funcdef> 5767 <paramdef>const struct path * <parameter>path</parameter></paramdef> 5768 </funcprototype></funcsynopsis> 5769</refsynopsisdiv> 5770<refsect1> 5771 <title>Arguments</title> 5772 <variablelist> 5773 <varlistentry> 5774 <term><parameter>path</parameter></term> 5775 <listitem> 5776 <para> 5777 path to put the reference to 5778 </para> 5779 </listitem> 5780 </varlistentry> 5781 </variablelist> 5782</refsect1> 5783<refsect1> 5784<title>Description</title> 5785<para> 5786 Given a path decrement the reference count to the dentry and the vfsmount. 5787</para> 5788</refsect1> 5789</refentry> 5790 5791<refentry id="API-vfs-path-lookup"> 5792<refentryinfo> 5793 <title>LINUX</title> 5794 <productname>Kernel Hackers Manual</productname> 5795 <date>July 2017</date> 5796</refentryinfo> 5797<refmeta> 5798 <refentrytitle><phrase>vfs_path_lookup</phrase></refentrytitle> 5799 <manvolnum>9</manvolnum> 5800 <refmiscinfo class="version">4.1.27</refmiscinfo> 5801</refmeta> 5802<refnamediv> 5803 <refname>vfs_path_lookup</refname> 5804 <refpurpose> 5805 lookup a file path relative to a dentry-vfsmount pair 5806 </refpurpose> 5807</refnamediv> 5808<refsynopsisdiv> 5809 <title>Synopsis</title> 5810 <funcsynopsis><funcprototype> 5811 <funcdef>int <function>vfs_path_lookup </function></funcdef> 5812 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 5813 <paramdef>struct vfsmount * <parameter>mnt</parameter></paramdef> 5814 <paramdef>const char * <parameter>name</parameter></paramdef> 5815 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 5816 <paramdef>struct path * <parameter>path</parameter></paramdef> 5817 </funcprototype></funcsynopsis> 5818</refsynopsisdiv> 5819<refsect1> 5820 <title>Arguments</title> 5821 <variablelist> 5822 <varlistentry> 5823 <term><parameter>dentry</parameter></term> 5824 <listitem> 5825 <para> 5826 pointer to dentry of the base directory 5827 </para> 5828 </listitem> 5829 </varlistentry> 5830 <varlistentry> 5831 <term><parameter>mnt</parameter></term> 5832 <listitem> 5833 <para> 5834 pointer to vfs mount of the base directory 5835 </para> 5836 </listitem> 5837 </varlistentry> 5838 <varlistentry> 5839 <term><parameter>name</parameter></term> 5840 <listitem> 5841 <para> 5842 pointer to file name 5843 </para> 5844 </listitem> 5845 </varlistentry> 5846 <varlistentry> 5847 <term><parameter>flags</parameter></term> 5848 <listitem> 5849 <para> 5850 lookup flags 5851 </para> 5852 </listitem> 5853 </varlistentry> 5854 <varlistentry> 5855 <term><parameter>path</parameter></term> 5856 <listitem> 5857 <para> 5858 pointer to struct path to fill 5859 </para> 5860 </listitem> 5861 </varlistentry> 5862 </variablelist> 5863</refsect1> 5864</refentry> 5865 5866<refentry id="API-lookup-one-len"> 5867<refentryinfo> 5868 <title>LINUX</title> 5869 <productname>Kernel Hackers Manual</productname> 5870 <date>July 2017</date> 5871</refentryinfo> 5872<refmeta> 5873 <refentrytitle><phrase>lookup_one_len</phrase></refentrytitle> 5874 <manvolnum>9</manvolnum> 5875 <refmiscinfo class="version">4.1.27</refmiscinfo> 5876</refmeta> 5877<refnamediv> 5878 <refname>lookup_one_len</refname> 5879 <refpurpose> 5880 filesystem helper to lookup single pathname component 5881 </refpurpose> 5882</refnamediv> 5883<refsynopsisdiv> 5884 <title>Synopsis</title> 5885 <funcsynopsis><funcprototype> 5886 <funcdef>struct dentry * <function>lookup_one_len </function></funcdef> 5887 <paramdef>const char * <parameter>name</parameter></paramdef> 5888 <paramdef>struct dentry * <parameter>base</parameter></paramdef> 5889 <paramdef>int <parameter>len</parameter></paramdef> 5890 </funcprototype></funcsynopsis> 5891</refsynopsisdiv> 5892<refsect1> 5893 <title>Arguments</title> 5894 <variablelist> 5895 <varlistentry> 5896 <term><parameter>name</parameter></term> 5897 <listitem> 5898 <para> 5899 pathname component to lookup 5900 </para> 5901 </listitem> 5902 </varlistentry> 5903 <varlistentry> 5904 <term><parameter>base</parameter></term> 5905 <listitem> 5906 <para> 5907 base directory to lookup from 5908 </para> 5909 </listitem> 5910 </varlistentry> 5911 <varlistentry> 5912 <term><parameter>len</parameter></term> 5913 <listitem> 5914 <para> 5915 maximum length <parameter>len</parameter> should be interpreted to 5916 </para> 5917 </listitem> 5918 </varlistentry> 5919 </variablelist> 5920</refsect1> 5921<refsect1> 5922<title>Description</title> 5923<para> 5924 Note that this routine is purely a helper for filesystem usage and should 5925 not be called by generic code. 5926</para> 5927</refsect1> 5928</refentry> 5929 5930<refentry id="API-vfs-unlink"> 5931<refentryinfo> 5932 <title>LINUX</title> 5933 <productname>Kernel Hackers Manual</productname> 5934 <date>July 2017</date> 5935</refentryinfo> 5936<refmeta> 5937 <refentrytitle><phrase>vfs_unlink</phrase></refentrytitle> 5938 <manvolnum>9</manvolnum> 5939 <refmiscinfo class="version">4.1.27</refmiscinfo> 5940</refmeta> 5941<refnamediv> 5942 <refname>vfs_unlink</refname> 5943 <refpurpose> 5944 unlink a filesystem object 5945 </refpurpose> 5946</refnamediv> 5947<refsynopsisdiv> 5948 <title>Synopsis</title> 5949 <funcsynopsis><funcprototype> 5950 <funcdef>int <function>vfs_unlink </function></funcdef> 5951 <paramdef>struct inode * <parameter>dir</parameter></paramdef> 5952 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 5953 <paramdef>struct inode ** <parameter>delegated_inode</parameter></paramdef> 5954 </funcprototype></funcsynopsis> 5955</refsynopsisdiv> 5956<refsect1> 5957 <title>Arguments</title> 5958 <variablelist> 5959 <varlistentry> 5960 <term><parameter>dir</parameter></term> 5961 <listitem> 5962 <para> 5963 parent directory 5964 </para> 5965 </listitem> 5966 </varlistentry> 5967 <varlistentry> 5968 <term><parameter>dentry</parameter></term> 5969 <listitem> 5970 <para> 5971 victim 5972 </para> 5973 </listitem> 5974 </varlistentry> 5975 <varlistentry> 5976 <term><parameter>delegated_inode</parameter></term> 5977 <listitem> 5978 <para> 5979 returns victim inode, if the inode is delegated. 5980 </para> 5981 </listitem> 5982 </varlistentry> 5983 </variablelist> 5984</refsect1> 5985<refsect1> 5986<title>Description</title> 5987<para> 5988 The caller must hold dir->i_mutex. 5989 </para><para> 5990 5991 If vfs_unlink discovers a delegation, it will return -EWOULDBLOCK and 5992 return a reference to the inode in delegated_inode. The caller 5993 should then break the delegation on that inode and retry. Because 5994 breaking a delegation may take a long time, the caller should drop 5995 dir->i_mutex before doing so. 5996 </para><para> 5997 5998 Alternatively, a caller may pass NULL for delegated_inode. This may 5999 be appropriate for callers that expect the underlying filesystem not 6000 to be NFS exported. 6001</para> 6002</refsect1> 6003</refentry> 6004 6005<refentry id="API-vfs-link"> 6006<refentryinfo> 6007 <title>LINUX</title> 6008 <productname>Kernel Hackers Manual</productname> 6009 <date>July 2017</date> 6010</refentryinfo> 6011<refmeta> 6012 <refentrytitle><phrase>vfs_link</phrase></refentrytitle> 6013 <manvolnum>9</manvolnum> 6014 <refmiscinfo class="version">4.1.27</refmiscinfo> 6015</refmeta> 6016<refnamediv> 6017 <refname>vfs_link</refname> 6018 <refpurpose> 6019 create a new link 6020 </refpurpose> 6021</refnamediv> 6022<refsynopsisdiv> 6023 <title>Synopsis</title> 6024 <funcsynopsis><funcprototype> 6025 <funcdef>int <function>vfs_link </function></funcdef> 6026 <paramdef>struct dentry * <parameter>old_dentry</parameter></paramdef> 6027 <paramdef>struct inode * <parameter>dir</parameter></paramdef> 6028 <paramdef>struct dentry * <parameter>new_dentry</parameter></paramdef> 6029 <paramdef>struct inode ** <parameter>delegated_inode</parameter></paramdef> 6030 </funcprototype></funcsynopsis> 6031</refsynopsisdiv> 6032<refsect1> 6033 <title>Arguments</title> 6034 <variablelist> 6035 <varlistentry> 6036 <term><parameter>old_dentry</parameter></term> 6037 <listitem> 6038 <para> 6039 object to be linked 6040 </para> 6041 </listitem> 6042 </varlistentry> 6043 <varlistentry> 6044 <term><parameter>dir</parameter></term> 6045 <listitem> 6046 <para> 6047 new parent 6048 </para> 6049 </listitem> 6050 </varlistentry> 6051 <varlistentry> 6052 <term><parameter>new_dentry</parameter></term> 6053 <listitem> 6054 <para> 6055 where to create the new link 6056 </para> 6057 </listitem> 6058 </varlistentry> 6059 <varlistentry> 6060 <term><parameter>delegated_inode</parameter></term> 6061 <listitem> 6062 <para> 6063 returns inode needing a delegation break 6064 </para> 6065 </listitem> 6066 </varlistentry> 6067 </variablelist> 6068</refsect1> 6069<refsect1> 6070<title>Description</title> 6071<para> 6072 The caller must hold dir->i_mutex 6073 </para><para> 6074 6075 If vfs_link discovers a delegation on the to-be-linked file in need 6076 of breaking, it will return -EWOULDBLOCK and return a reference to the 6077 inode in delegated_inode. The caller should then break the delegation 6078 and retry. Because breaking a delegation may take a long time, the 6079 caller should drop the i_mutex before doing so. 6080 </para><para> 6081 6082 Alternatively, a caller may pass NULL for delegated_inode. This may 6083 be appropriate for callers that expect the underlying filesystem not 6084 to be NFS exported. 6085</para> 6086</refsect1> 6087</refentry> 6088 6089<refentry id="API-vfs-rename"> 6090<refentryinfo> 6091 <title>LINUX</title> 6092 <productname>Kernel Hackers Manual</productname> 6093 <date>July 2017</date> 6094</refentryinfo> 6095<refmeta> 6096 <refentrytitle><phrase>vfs_rename</phrase></refentrytitle> 6097 <manvolnum>9</manvolnum> 6098 <refmiscinfo class="version">4.1.27</refmiscinfo> 6099</refmeta> 6100<refnamediv> 6101 <refname>vfs_rename</refname> 6102 <refpurpose> 6103 rename a filesystem object 6104 </refpurpose> 6105</refnamediv> 6106<refsynopsisdiv> 6107 <title>Synopsis</title> 6108 <funcsynopsis><funcprototype> 6109 <funcdef>int <function>vfs_rename </function></funcdef> 6110 <paramdef>struct inode * <parameter>old_dir</parameter></paramdef> 6111 <paramdef>struct dentry * <parameter>old_dentry</parameter></paramdef> 6112 <paramdef>struct inode * <parameter>new_dir</parameter></paramdef> 6113 <paramdef>struct dentry * <parameter>new_dentry</parameter></paramdef> 6114 <paramdef>struct inode ** <parameter>delegated_inode</parameter></paramdef> 6115 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 6116 </funcprototype></funcsynopsis> 6117</refsynopsisdiv> 6118<refsect1> 6119 <title>Arguments</title> 6120 <variablelist> 6121 <varlistentry> 6122 <term><parameter>old_dir</parameter></term> 6123 <listitem> 6124 <para> 6125 parent of source 6126 </para> 6127 </listitem> 6128 </varlistentry> 6129 <varlistentry> 6130 <term><parameter>old_dentry</parameter></term> 6131 <listitem> 6132 <para> 6133 source 6134 </para> 6135 </listitem> 6136 </varlistentry> 6137 <varlistentry> 6138 <term><parameter>new_dir</parameter></term> 6139 <listitem> 6140 <para> 6141 parent of destination 6142 </para> 6143 </listitem> 6144 </varlistentry> 6145 <varlistentry> 6146 <term><parameter>new_dentry</parameter></term> 6147 <listitem> 6148 <para> 6149 destination 6150 </para> 6151 </listitem> 6152 </varlistentry> 6153 <varlistentry> 6154 <term><parameter>delegated_inode</parameter></term> 6155 <listitem> 6156 <para> 6157 returns an inode needing a delegation break 6158 </para> 6159 </listitem> 6160 </varlistentry> 6161 <varlistentry> 6162 <term><parameter>flags</parameter></term> 6163 <listitem> 6164 <para> 6165 rename flags 6166 </para> 6167 </listitem> 6168 </varlistentry> 6169 </variablelist> 6170</refsect1> 6171<refsect1> 6172<title>Description</title> 6173<para> 6174 The caller must hold multiple mutexes--see <function>lock_rename</function>). 6175 </para><para> 6176 6177 If vfs_rename discovers a delegation in need of breaking at either 6178 the source or destination, it will return -EWOULDBLOCK and return a 6179 reference to the inode in delegated_inode. The caller should then 6180 break the delegation and retry. Because breaking a delegation may 6181 take a long time, the caller should drop all locks before doing 6182 so. 6183 </para><para> 6184 6185 Alternatively, a caller may pass NULL for delegated_inode. This may 6186 be appropriate for callers that expect the underlying filesystem not 6187 to be NFS exported. 6188 </para><para> 6189 6190 The worst of all namespace operations - renaming directory. <quote>Perverted</quote> 6191 doesn't even start to describe it. Somebody in UCB had a heck of a trip... 6192</para> 6193</refsect1> 6194<refsect1> 6195<title>Problems</title> 6196<para> 6197 a) we can get into loop creation. 6198 b) race potential - two innocent renames can create a loop together. 6199 That's where 4.4 screws up. Current fix: serialization on 6200 sb->s_vfs_rename_mutex. We might be more accurate, but that's another 6201 story. 6202 c) we have to lock _four_ objects - parents and victim (if it exists), 6203 and source (if it is not a directory). 6204 And that - after we got ->i_mutex on parents (until then we don't know 6205 whether the target exists). Solution: try to be smart with locking 6206 order for inodes. We rely on the fact that tree topology may change 6207 only under ->s_vfs_rename_mutex _and_ that parent of the object we 6208 move will be locked. Thus we can rank directories by the tree 6209 (ancestors first) and rank all non-directories after them. 6210 That works since everybody except rename does <quote>lock parent, lookup, 6211 lock child</quote> and rename is under ->s_vfs_rename_mutex. 6212 HOWEVER, it relies on the assumption that any object with -><function>lookup</function> 6213 has no more than 1 dentry. If <quote>hybrid</quote> objects will ever appear, 6214 we'd better make sure that there's no link(2) for them. 6215 d) conversion from fhandle to dentry may come in the wrong moment - when 6216 we are removing the target. Solution: we will have to grab ->i_mutex 6217 in the fhandle_to_dentry code. [FIXME - current nfsfh.c relies on 6218 ->i_mutex on parents, which works but leads to some truly excessive 6219 locking]. 6220</para> 6221</refsect1> 6222</refentry> 6223 6224<!-- fs/buffer.c --> 6225<refentry id="API-sync-mapping-buffers"> 6226<refentryinfo> 6227 <title>LINUX</title> 6228 <productname>Kernel Hackers Manual</productname> 6229 <date>July 2017</date> 6230</refentryinfo> 6231<refmeta> 6232 <refentrytitle><phrase>sync_mapping_buffers</phrase></refentrytitle> 6233 <manvolnum>9</manvolnum> 6234 <refmiscinfo class="version">4.1.27</refmiscinfo> 6235</refmeta> 6236<refnamediv> 6237 <refname>sync_mapping_buffers</refname> 6238 <refpurpose> 6239 write out & wait upon a mapping's <quote>associated</quote> buffers 6240 </refpurpose> 6241</refnamediv> 6242<refsynopsisdiv> 6243 <title>Synopsis</title> 6244 <funcsynopsis><funcprototype> 6245 <funcdef>int <function>sync_mapping_buffers </function></funcdef> 6246 <paramdef>struct address_space * <parameter>mapping</parameter></paramdef> 6247 </funcprototype></funcsynopsis> 6248</refsynopsisdiv> 6249<refsect1> 6250 <title>Arguments</title> 6251 <variablelist> 6252 <varlistentry> 6253 <term><parameter>mapping</parameter></term> 6254 <listitem> 6255 <para> 6256 the mapping which wants those buffers written 6257 </para> 6258 </listitem> 6259 </varlistentry> 6260 </variablelist> 6261</refsect1> 6262<refsect1> 6263<title>Description</title> 6264<para> 6265 Starts I/O against the buffers at mapping->private_list, and waits upon 6266 that I/O. 6267 </para><para> 6268 6269 Basically, this is a convenience function for <function>fsync</function>. 6270 <parameter>mapping</parameter> is a file or directory which needs those buffers to be written for 6271 a successful <function>fsync</function>. 6272</para> 6273</refsect1> 6274</refentry> 6275 6276<refentry id="API-mark-buffer-dirty"> 6277<refentryinfo> 6278 <title>LINUX</title> 6279 <productname>Kernel Hackers Manual</productname> 6280 <date>July 2017</date> 6281</refentryinfo> 6282<refmeta> 6283 <refentrytitle><phrase>mark_buffer_dirty</phrase></refentrytitle> 6284 <manvolnum>9</manvolnum> 6285 <refmiscinfo class="version">4.1.27</refmiscinfo> 6286</refmeta> 6287<refnamediv> 6288 <refname>mark_buffer_dirty</refname> 6289 <refpurpose> 6290 mark a buffer_head as needing writeout 6291 </refpurpose> 6292</refnamediv> 6293<refsynopsisdiv> 6294 <title>Synopsis</title> 6295 <funcsynopsis><funcprototype> 6296 <funcdef>void <function>mark_buffer_dirty </function></funcdef> 6297 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 6298 </funcprototype></funcsynopsis> 6299</refsynopsisdiv> 6300<refsect1> 6301 <title>Arguments</title> 6302 <variablelist> 6303 <varlistentry> 6304 <term><parameter>bh</parameter></term> 6305 <listitem> 6306 <para> 6307 the buffer_head to mark dirty 6308 </para> 6309 </listitem> 6310 </varlistentry> 6311 </variablelist> 6312</refsect1> 6313<refsect1> 6314<title>Description</title> 6315<para> 6316 <function>mark_buffer_dirty</function> will set the dirty bit against the buffer, then set its 6317 backing page dirty, then tag the page as dirty in its address_space's radix 6318 tree and then attach the address_space's inode to its superblock's dirty 6319 inode list. 6320 </para><para> 6321 6322 <function>mark_buffer_dirty</function> is atomic. It takes bh->b_page->mapping->private_lock, 6323 mapping->tree_lock and mapping->host->i_lock. 6324</para> 6325</refsect1> 6326</refentry> 6327 6328<refentry id="API---bread-gfp"> 6329<refentryinfo> 6330 <title>LINUX</title> 6331 <productname>Kernel Hackers Manual</productname> 6332 <date>July 2017</date> 6333</refentryinfo> 6334<refmeta> 6335 <refentrytitle><phrase>__bread_gfp</phrase></refentrytitle> 6336 <manvolnum>9</manvolnum> 6337 <refmiscinfo class="version">4.1.27</refmiscinfo> 6338</refmeta> 6339<refnamediv> 6340 <refname>__bread_gfp</refname> 6341 <refpurpose> 6342 reads a specified block and returns the bh 6343 </refpurpose> 6344</refnamediv> 6345<refsynopsisdiv> 6346 <title>Synopsis</title> 6347 <funcsynopsis><funcprototype> 6348 <funcdef>struct buffer_head * <function>__bread_gfp </function></funcdef> 6349 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 6350 <paramdef>sector_t <parameter>block</parameter></paramdef> 6351 <paramdef>unsigned <parameter>size</parameter></paramdef> 6352 <paramdef>gfp_t <parameter>gfp</parameter></paramdef> 6353 </funcprototype></funcsynopsis> 6354</refsynopsisdiv> 6355<refsect1> 6356 <title>Arguments</title> 6357 <variablelist> 6358 <varlistentry> 6359 <term><parameter>bdev</parameter></term> 6360 <listitem> 6361 <para> 6362 the block_device to read from 6363 </para> 6364 </listitem> 6365 </varlistentry> 6366 <varlistentry> 6367 <term><parameter>block</parameter></term> 6368 <listitem> 6369 <para> 6370 number of block 6371 </para> 6372 </listitem> 6373 </varlistentry> 6374 <varlistentry> 6375 <term><parameter>size</parameter></term> 6376 <listitem> 6377 <para> 6378 size (in bytes) to read 6379 </para> 6380 </listitem> 6381 </varlistentry> 6382 <varlistentry> 6383 <term><parameter>gfp</parameter></term> 6384 <listitem> 6385 <para> 6386 page allocation flag 6387 </para> 6388 </listitem> 6389 </varlistentry> 6390 </variablelist> 6391</refsect1> 6392<refsect1> 6393<title>Description</title> 6394<para> 6395 Reads a specified block, and returns buffer head that contains it. 6396 The page cache can be allocated from non-movable area 6397 not to prevent page migration if you set gfp to zero. 6398 It returns NULL if the block was unreadable. 6399</para> 6400</refsect1> 6401</refentry> 6402 6403<refentry id="API-block-invalidatepage"> 6404<refentryinfo> 6405 <title>LINUX</title> 6406 <productname>Kernel Hackers Manual</productname> 6407 <date>July 2017</date> 6408</refentryinfo> 6409<refmeta> 6410 <refentrytitle><phrase>block_invalidatepage</phrase></refentrytitle> 6411 <manvolnum>9</manvolnum> 6412 <refmiscinfo class="version">4.1.27</refmiscinfo> 6413</refmeta> 6414<refnamediv> 6415 <refname>block_invalidatepage</refname> 6416 <refpurpose> 6417 invalidate part or all of a buffer-backed page 6418 </refpurpose> 6419</refnamediv> 6420<refsynopsisdiv> 6421 <title>Synopsis</title> 6422 <funcsynopsis><funcprototype> 6423 <funcdef>void <function>block_invalidatepage </function></funcdef> 6424 <paramdef>struct page * <parameter>page</parameter></paramdef> 6425 <paramdef>unsigned int <parameter>offset</parameter></paramdef> 6426 <paramdef>unsigned int <parameter>length</parameter></paramdef> 6427 </funcprototype></funcsynopsis> 6428</refsynopsisdiv> 6429<refsect1> 6430 <title>Arguments</title> 6431 <variablelist> 6432 <varlistentry> 6433 <term><parameter>page</parameter></term> 6434 <listitem> 6435 <para> 6436 the page which is affected 6437 </para> 6438 </listitem> 6439 </varlistentry> 6440 <varlistentry> 6441 <term><parameter>offset</parameter></term> 6442 <listitem> 6443 <para> 6444 start of the range to invalidate 6445 </para> 6446 </listitem> 6447 </varlistentry> 6448 <varlistentry> 6449 <term><parameter>length</parameter></term> 6450 <listitem> 6451 <para> 6452 length of the range to invalidate 6453 </para> 6454 </listitem> 6455 </varlistentry> 6456 </variablelist> 6457</refsect1> 6458<refsect1> 6459<title>Description</title> 6460<para> 6461 <function>block_invalidatepage</function> is called when all or part of the page has become 6462 invalidated by a truncate operation. 6463 </para><para> 6464 6465 <function>block_invalidatepage</function> does not have to release all buffers, but it must 6466 ensure that no dirty buffer is left outside <parameter>offset</parameter> and that no I/O 6467 is underway against any of the blocks which are outside the truncation 6468 point. Because the caller is about to free (and possibly reuse) those 6469 blocks on-disk. 6470</para> 6471</refsect1> 6472</refentry> 6473 6474<refentry id="API-ll-rw-block"> 6475<refentryinfo> 6476 <title>LINUX</title> 6477 <productname>Kernel Hackers Manual</productname> 6478 <date>July 2017</date> 6479</refentryinfo> 6480<refmeta> 6481 <refentrytitle><phrase>ll_rw_block</phrase></refentrytitle> 6482 <manvolnum>9</manvolnum> 6483 <refmiscinfo class="version">4.1.27</refmiscinfo> 6484</refmeta> 6485<refnamediv> 6486 <refname>ll_rw_block</refname> 6487 <refpurpose> 6488 level access to block devices (DEPRECATED) 6489 </refpurpose> 6490</refnamediv> 6491<refsynopsisdiv> 6492 <title>Synopsis</title> 6493 <funcsynopsis><funcprototype> 6494 <funcdef>void <function>ll_rw_block </function></funcdef> 6495 <paramdef>int <parameter>rw</parameter></paramdef> 6496 <paramdef>int <parameter>nr</parameter></paramdef> 6497 <paramdef>struct buffer_head * <parameter>bhs[]</parameter></paramdef> 6498 </funcprototype></funcsynopsis> 6499</refsynopsisdiv> 6500<refsect1> 6501 <title>Arguments</title> 6502 <variablelist> 6503 <varlistentry> 6504 <term><parameter>rw</parameter></term> 6505 <listitem> 6506 <para> 6507 whether to <constant>READ</constant> or <constant>WRITE</constant> or maybe <constant>READA</constant> (readahead) 6508 </para> 6509 </listitem> 6510 </varlistentry> 6511 <varlistentry> 6512 <term><parameter>nr</parameter></term> 6513 <listitem> 6514 <para> 6515 number of <structname>struct buffer_heads</structname> in the array 6516 </para> 6517 </listitem> 6518 </varlistentry> 6519 <varlistentry> 6520 <term><parameter>bhs[]</parameter></term> 6521 <listitem> 6522 <para> 6523 array of pointers to <structname>struct buffer_head</structname> 6524 </para> 6525 </listitem> 6526 </varlistentry> 6527 </variablelist> 6528</refsect1> 6529<refsect1> 6530<title>Description</title> 6531<para> 6532 <function>ll_rw_block</function> takes an array of pointers to <structname>struct buffer_heads</structname>, and 6533 requests an I/O operation on them, either a <constant>READ</constant> or a <constant>WRITE</constant>. The third 6534 <constant>READA</constant> option is described in the documentation for <function>generic_make_request</function> 6535 which <function>ll_rw_block</function> calls. 6536 </para><para> 6537 6538 This function drops any buffer that it cannot get a lock on (with the 6539 BH_Lock state bit), any buffer that appears to be clean when doing a write 6540 request, and any buffer that appears to be up-to-date when doing read 6541 request. Further it marks as clean buffers that are processed for 6542 writing (the buffer cache won't assume that they are actually clean 6543 until the buffer gets unlocked). 6544 </para><para> 6545 6546 ll_rw_block sets b_end_io to simple completion handler that marks 6547 the buffer up-to-date (if appropriate), unlocks the buffer and wakes 6548 any waiters. 6549 </para><para> 6550 6551 All of the buffers must be for the same device, and must also be a 6552 multiple of the current approved size for the device. 6553</para> 6554</refsect1> 6555</refentry> 6556 6557<refentry id="API-bh-uptodate-or-lock"> 6558<refentryinfo> 6559 <title>LINUX</title> 6560 <productname>Kernel Hackers Manual</productname> 6561 <date>July 2017</date> 6562</refentryinfo> 6563<refmeta> 6564 <refentrytitle><phrase>bh_uptodate_or_lock</phrase></refentrytitle> 6565 <manvolnum>9</manvolnum> 6566 <refmiscinfo class="version">4.1.27</refmiscinfo> 6567</refmeta> 6568<refnamediv> 6569 <refname>bh_uptodate_or_lock</refname> 6570 <refpurpose> 6571 Test whether the buffer is uptodate 6572 </refpurpose> 6573</refnamediv> 6574<refsynopsisdiv> 6575 <title>Synopsis</title> 6576 <funcsynopsis><funcprototype> 6577 <funcdef>int <function>bh_uptodate_or_lock </function></funcdef> 6578 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 6579 </funcprototype></funcsynopsis> 6580</refsynopsisdiv> 6581<refsect1> 6582 <title>Arguments</title> 6583 <variablelist> 6584 <varlistentry> 6585 <term><parameter>bh</parameter></term> 6586 <listitem> 6587 <para> 6588 struct buffer_head 6589 </para> 6590 </listitem> 6591 </varlistentry> 6592 </variablelist> 6593</refsect1> 6594<refsect1> 6595<title>Description</title> 6596<para> 6597 Return true if the buffer is up-to-date and false, 6598 with the buffer locked, if not. 6599</para> 6600</refsect1> 6601</refentry> 6602 6603<refentry id="API-bh-submit-read"> 6604<refentryinfo> 6605 <title>LINUX</title> 6606 <productname>Kernel Hackers Manual</productname> 6607 <date>July 2017</date> 6608</refentryinfo> 6609<refmeta> 6610 <refentrytitle><phrase>bh_submit_read</phrase></refentrytitle> 6611 <manvolnum>9</manvolnum> 6612 <refmiscinfo class="version">4.1.27</refmiscinfo> 6613</refmeta> 6614<refnamediv> 6615 <refname>bh_submit_read</refname> 6616 <refpurpose> 6617 Submit a locked buffer for reading 6618 </refpurpose> 6619</refnamediv> 6620<refsynopsisdiv> 6621 <title>Synopsis</title> 6622 <funcsynopsis><funcprototype> 6623 <funcdef>int <function>bh_submit_read </function></funcdef> 6624 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 6625 </funcprototype></funcsynopsis> 6626</refsynopsisdiv> 6627<refsect1> 6628 <title>Arguments</title> 6629 <variablelist> 6630 <varlistentry> 6631 <term><parameter>bh</parameter></term> 6632 <listitem> 6633 <para> 6634 struct buffer_head 6635 </para> 6636 </listitem> 6637 </varlistentry> 6638 </variablelist> 6639</refsect1> 6640<refsect1> 6641<title>Description</title> 6642<para> 6643 Returns zero on success and -EIO on error. 6644</para> 6645</refsect1> 6646</refentry> 6647 6648<!-- block/bio.c --> 6649<refentry id="API-bio-reset"> 6650<refentryinfo> 6651 <title>LINUX</title> 6652 <productname>Kernel Hackers Manual</productname> 6653 <date>July 2017</date> 6654</refentryinfo> 6655<refmeta> 6656 <refentrytitle><phrase>bio_reset</phrase></refentrytitle> 6657 <manvolnum>9</manvolnum> 6658 <refmiscinfo class="version">4.1.27</refmiscinfo> 6659</refmeta> 6660<refnamediv> 6661 <refname>bio_reset</refname> 6662 <refpurpose> 6663 reinitialize a bio 6664 </refpurpose> 6665</refnamediv> 6666<refsynopsisdiv> 6667 <title>Synopsis</title> 6668 <funcsynopsis><funcprototype> 6669 <funcdef>void <function>bio_reset </function></funcdef> 6670 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 6671 </funcprototype></funcsynopsis> 6672</refsynopsisdiv> 6673<refsect1> 6674 <title>Arguments</title> 6675 <variablelist> 6676 <varlistentry> 6677 <term><parameter>bio</parameter></term> 6678 <listitem> 6679 <para> 6680 bio to reset 6681 </para> 6682 </listitem> 6683 </varlistentry> 6684 </variablelist> 6685</refsect1> 6686<refsect1> 6687<title>Description</title> 6688<para> 6689 After calling <function>bio_reset</function>, <parameter>bio</parameter> will be in the same state as a freshly 6690 allocated bio returned bio <function>bio_alloc_bioset</function> - the only fields that are 6691 preserved are the ones that are initialized by <function>bio_alloc_bioset</function>. See 6692 comment in struct bio. 6693</para> 6694</refsect1> 6695</refentry> 6696 6697<refentry id="API-bio-chain"> 6698<refentryinfo> 6699 <title>LINUX</title> 6700 <productname>Kernel Hackers Manual</productname> 6701 <date>July 2017</date> 6702</refentryinfo> 6703<refmeta> 6704 <refentrytitle><phrase>bio_chain</phrase></refentrytitle> 6705 <manvolnum>9</manvolnum> 6706 <refmiscinfo class="version">4.1.27</refmiscinfo> 6707</refmeta> 6708<refnamediv> 6709 <refname>bio_chain</refname> 6710 <refpurpose> 6711 chain bio completions 6712 </refpurpose> 6713</refnamediv> 6714<refsynopsisdiv> 6715 <title>Synopsis</title> 6716 <funcsynopsis><funcprototype> 6717 <funcdef>void <function>bio_chain </function></funcdef> 6718 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 6719 <paramdef>struct bio * <parameter>parent</parameter></paramdef> 6720 </funcprototype></funcsynopsis> 6721</refsynopsisdiv> 6722<refsect1> 6723 <title>Arguments</title> 6724 <variablelist> 6725 <varlistentry> 6726 <term><parameter>bio</parameter></term> 6727 <listitem> 6728 <para> 6729 the target bio 6730 </para> 6731 </listitem> 6732 </varlistentry> 6733 <varlistentry> 6734 <term><parameter>parent</parameter></term> 6735 <listitem> 6736 <para> 6737 the <parameter>bio</parameter>'s parent bio 6738 </para> 6739 </listitem> 6740 </varlistentry> 6741 </variablelist> 6742</refsect1> 6743<refsect1> 6744<title>Description</title> 6745<para> 6746 The caller won't have a bi_end_io called when <parameter>bio</parameter> completes - instead, 6747 <parameter>parent</parameter>'s bi_end_io won't be called until both <parameter>parent</parameter> and <parameter>bio</parameter> have 6748 completed; the chained bio will also be freed when it completes. 6749 </para><para> 6750 6751 The caller must not set bi_private or bi_end_io in <parameter>bio</parameter>. 6752</para> 6753</refsect1> 6754</refentry> 6755 6756<refentry id="API-bio-alloc-bioset"> 6757<refentryinfo> 6758 <title>LINUX</title> 6759 <productname>Kernel Hackers Manual</productname> 6760 <date>July 2017</date> 6761</refentryinfo> 6762<refmeta> 6763 <refentrytitle><phrase>bio_alloc_bioset</phrase></refentrytitle> 6764 <manvolnum>9</manvolnum> 6765 <refmiscinfo class="version">4.1.27</refmiscinfo> 6766</refmeta> 6767<refnamediv> 6768 <refname>bio_alloc_bioset</refname> 6769 <refpurpose> 6770 allocate a bio for I/O 6771 </refpurpose> 6772</refnamediv> 6773<refsynopsisdiv> 6774 <title>Synopsis</title> 6775 <funcsynopsis><funcprototype> 6776 <funcdef>struct bio * <function>bio_alloc_bioset </function></funcdef> 6777 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 6778 <paramdef>int <parameter>nr_iovecs</parameter></paramdef> 6779 <paramdef>struct bio_set * <parameter>bs</parameter></paramdef> 6780 </funcprototype></funcsynopsis> 6781</refsynopsisdiv> 6782<refsect1> 6783 <title>Arguments</title> 6784 <variablelist> 6785 <varlistentry> 6786 <term><parameter>gfp_mask</parameter></term> 6787 <listitem> 6788 <para> 6789 the GFP_ mask given to the slab allocator 6790 </para> 6791 </listitem> 6792 </varlistentry> 6793 <varlistentry> 6794 <term><parameter>nr_iovecs</parameter></term> 6795 <listitem> 6796 <para> 6797 number of iovecs to pre-allocate 6798 </para> 6799 </listitem> 6800 </varlistentry> 6801 <varlistentry> 6802 <term><parameter>bs</parameter></term> 6803 <listitem> 6804 <para> 6805 the bio_set to allocate from. 6806 </para> 6807 </listitem> 6808 </varlistentry> 6809 </variablelist> 6810</refsect1> 6811<refsect1> 6812<title>Description</title> 6813<para> 6814 If <parameter>bs</parameter> is NULL, uses <function>kmalloc</function> to allocate the bio; else the allocation is 6815 backed by the <parameter>bs</parameter>'s mempool. 6816 </para><para> 6817 6818 When <parameter>bs</parameter> is not NULL, if <constant>__GFP_WAIT</constant> is set then bio_alloc will always be 6819 able to allocate a bio. This is due to the mempool guarantees. To make this 6820 work, callers must never allocate more than 1 bio at a time from this pool. 6821 Callers that need to allocate more than 1 bio must always submit the 6822 previously allocated bio for IO before attempting to allocate a new one. 6823 Failure to do so can cause deadlocks under memory pressure. 6824 </para><para> 6825 6826 Note that when running under <function>generic_make_request</function> (i.e. any block 6827 driver), bios are not submitted until after you return - see the code in 6828 <function>generic_make_request</function> that converts recursion into iteration, to prevent 6829 stack overflows. 6830 </para><para> 6831 6832 This would normally mean allocating multiple bios under 6833 <function>generic_make_request</function> would be susceptible to deadlocks, but we have 6834 deadlock avoidance code that resubmits any blocked bios from a rescuer 6835 thread. 6836 </para><para> 6837 6838 However, we do not guarantee forward progress for allocations from other 6839 mempools. Doing multiple allocations from the same mempool under 6840 <function>generic_make_request</function> should be avoided - instead, use bio_set's front_pad 6841 for per bio allocations. 6842</para> 6843</refsect1> 6844<refsect1> 6845<title>RETURNS</title> 6846<para> 6847 Pointer to new bio on success, NULL on failure. 6848</para> 6849</refsect1> 6850</refentry> 6851 6852<refentry id="API-bio-put"> 6853<refentryinfo> 6854 <title>LINUX</title> 6855 <productname>Kernel Hackers Manual</productname> 6856 <date>July 2017</date> 6857</refentryinfo> 6858<refmeta> 6859 <refentrytitle><phrase>bio_put</phrase></refentrytitle> 6860 <manvolnum>9</manvolnum> 6861 <refmiscinfo class="version">4.1.27</refmiscinfo> 6862</refmeta> 6863<refnamediv> 6864 <refname>bio_put</refname> 6865 <refpurpose> 6866 release a reference to a bio 6867 </refpurpose> 6868</refnamediv> 6869<refsynopsisdiv> 6870 <title>Synopsis</title> 6871 <funcsynopsis><funcprototype> 6872 <funcdef>void <function>bio_put </function></funcdef> 6873 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 6874 </funcprototype></funcsynopsis> 6875</refsynopsisdiv> 6876<refsect1> 6877 <title>Arguments</title> 6878 <variablelist> 6879 <varlistentry> 6880 <term><parameter>bio</parameter></term> 6881 <listitem> 6882 <para> 6883 bio to release reference to 6884 </para> 6885 </listitem> 6886 </varlistentry> 6887 </variablelist> 6888</refsect1> 6889<refsect1> 6890<title>Description</title> 6891<para> 6892 Put a reference to a <structname>struct bio</structname>, either one you have gotten with 6893 bio_alloc, bio_get or bio_clone. The last put of a bio will free it. 6894</para> 6895</refsect1> 6896</refentry> 6897 6898<refentry id="API---bio-clone-fast"> 6899<refentryinfo> 6900 <title>LINUX</title> 6901 <productname>Kernel Hackers Manual</productname> 6902 <date>July 2017</date> 6903</refentryinfo> 6904<refmeta> 6905 <refentrytitle><phrase>__bio_clone_fast</phrase></refentrytitle> 6906 <manvolnum>9</manvolnum> 6907 <refmiscinfo class="version">4.1.27</refmiscinfo> 6908</refmeta> 6909<refnamediv> 6910 <refname>__bio_clone_fast</refname> 6911 <refpurpose> 6912 clone a bio that shares the original bio's biovec 6913 </refpurpose> 6914</refnamediv> 6915<refsynopsisdiv> 6916 <title>Synopsis</title> 6917 <funcsynopsis><funcprototype> 6918 <funcdef>void <function>__bio_clone_fast </function></funcdef> 6919 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 6920 <paramdef>struct bio * <parameter>bio_src</parameter></paramdef> 6921 </funcprototype></funcsynopsis> 6922</refsynopsisdiv> 6923<refsect1> 6924 <title>Arguments</title> 6925 <variablelist> 6926 <varlistentry> 6927 <term><parameter>bio</parameter></term> 6928 <listitem> 6929 <para> 6930 destination bio 6931 </para> 6932 </listitem> 6933 </varlistentry> 6934 <varlistentry> 6935 <term><parameter>bio_src</parameter></term> 6936 <listitem> 6937 <para> 6938 bio to clone 6939 </para> 6940 </listitem> 6941 </varlistentry> 6942 </variablelist> 6943</refsect1> 6944<refsect1> 6945<title>Description</title> 6946<para> 6947 Clone a <structname>bio</structname>. Caller will own the returned bio, but not 6948 the actual data it points to. Reference count of returned 6949 bio will be one. 6950 </para><para> 6951 6952 Caller must ensure that <parameter>bio_src</parameter> is not freed before <parameter>bio</parameter>. 6953</para> 6954</refsect1> 6955</refentry> 6956 6957<refentry id="API-bio-clone-fast"> 6958<refentryinfo> 6959 <title>LINUX</title> 6960 <productname>Kernel Hackers Manual</productname> 6961 <date>July 2017</date> 6962</refentryinfo> 6963<refmeta> 6964 <refentrytitle><phrase>bio_clone_fast</phrase></refentrytitle> 6965 <manvolnum>9</manvolnum> 6966 <refmiscinfo class="version">4.1.27</refmiscinfo> 6967</refmeta> 6968<refnamediv> 6969 <refname>bio_clone_fast</refname> 6970 <refpurpose> 6971 clone a bio that shares the original bio's biovec 6972 </refpurpose> 6973</refnamediv> 6974<refsynopsisdiv> 6975 <title>Synopsis</title> 6976 <funcsynopsis><funcprototype> 6977 <funcdef>struct bio * <function>bio_clone_fast </function></funcdef> 6978 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 6979 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 6980 <paramdef>struct bio_set * <parameter>bs</parameter></paramdef> 6981 </funcprototype></funcsynopsis> 6982</refsynopsisdiv> 6983<refsect1> 6984 <title>Arguments</title> 6985 <variablelist> 6986 <varlistentry> 6987 <term><parameter>bio</parameter></term> 6988 <listitem> 6989 <para> 6990 bio to clone 6991 </para> 6992 </listitem> 6993 </varlistentry> 6994 <varlistentry> 6995 <term><parameter>gfp_mask</parameter></term> 6996 <listitem> 6997 <para> 6998 allocation priority 6999 </para> 7000 </listitem> 7001 </varlistentry> 7002 <varlistentry> 7003 <term><parameter>bs</parameter></term> 7004 <listitem> 7005 <para> 7006 bio_set to allocate from 7007 </para> 7008 </listitem> 7009 </varlistentry> 7010 </variablelist> 7011</refsect1> 7012<refsect1> 7013<title>Description</title> 7014<para> 7015 Like __bio_clone_fast, only also allocates the returned bio 7016</para> 7017</refsect1> 7018</refentry> 7019 7020<refentry id="API-bio-clone-bioset"> 7021<refentryinfo> 7022 <title>LINUX</title> 7023 <productname>Kernel Hackers Manual</productname> 7024 <date>July 2017</date> 7025</refentryinfo> 7026<refmeta> 7027 <refentrytitle><phrase>bio_clone_bioset</phrase></refentrytitle> 7028 <manvolnum>9</manvolnum> 7029 <refmiscinfo class="version">4.1.27</refmiscinfo> 7030</refmeta> 7031<refnamediv> 7032 <refname>bio_clone_bioset</refname> 7033 <refpurpose> 7034 clone a bio 7035 </refpurpose> 7036</refnamediv> 7037<refsynopsisdiv> 7038 <title>Synopsis</title> 7039 <funcsynopsis><funcprototype> 7040 <funcdef>struct bio * <function>bio_clone_bioset </function></funcdef> 7041 <paramdef>struct bio * <parameter>bio_src</parameter></paramdef> 7042 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 7043 <paramdef>struct bio_set * <parameter>bs</parameter></paramdef> 7044 </funcprototype></funcsynopsis> 7045</refsynopsisdiv> 7046<refsect1> 7047 <title>Arguments</title> 7048 <variablelist> 7049 <varlistentry> 7050 <term><parameter>bio_src</parameter></term> 7051 <listitem> 7052 <para> 7053 bio to clone 7054 </para> 7055 </listitem> 7056 </varlistentry> 7057 <varlistentry> 7058 <term><parameter>gfp_mask</parameter></term> 7059 <listitem> 7060 <para> 7061 allocation priority 7062 </para> 7063 </listitem> 7064 </varlistentry> 7065 <varlistentry> 7066 <term><parameter>bs</parameter></term> 7067 <listitem> 7068 <para> 7069 bio_set to allocate from 7070 </para> 7071 </listitem> 7072 </varlistentry> 7073 </variablelist> 7074</refsect1> 7075<refsect1> 7076<title>Description</title> 7077<para> 7078 Clone bio. Caller will own the returned bio, but not the actual data it 7079 points to. Reference count of returned bio will be one. 7080</para> 7081</refsect1> 7082</refentry> 7083 7084<refentry id="API-bio-get-nr-vecs"> 7085<refentryinfo> 7086 <title>LINUX</title> 7087 <productname>Kernel Hackers Manual</productname> 7088 <date>July 2017</date> 7089</refentryinfo> 7090<refmeta> 7091 <refentrytitle><phrase>bio_get_nr_vecs</phrase></refentrytitle> 7092 <manvolnum>9</manvolnum> 7093 <refmiscinfo class="version">4.1.27</refmiscinfo> 7094</refmeta> 7095<refnamediv> 7096 <refname>bio_get_nr_vecs</refname> 7097 <refpurpose> 7098 return approx number of vecs 7099 </refpurpose> 7100</refnamediv> 7101<refsynopsisdiv> 7102 <title>Synopsis</title> 7103 <funcsynopsis><funcprototype> 7104 <funcdef>int <function>bio_get_nr_vecs </function></funcdef> 7105 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 7106 </funcprototype></funcsynopsis> 7107</refsynopsisdiv> 7108<refsect1> 7109 <title>Arguments</title> 7110 <variablelist> 7111 <varlistentry> 7112 <term><parameter>bdev</parameter></term> 7113 <listitem> 7114 <para> 7115 I/O target 7116 </para> 7117 </listitem> 7118 </varlistentry> 7119 </variablelist> 7120</refsect1> 7121<refsect1> 7122<title>Description</title> 7123<para> 7124 Return the approximate number of pages we can send to this target. 7125 There's no guarantee that you will be able to fit this number of pages 7126 into a bio, it does not account for dynamic restrictions that vary 7127 on offset. 7128</para> 7129</refsect1> 7130</refentry> 7131 7132<refentry id="API-bio-add-pc-page"> 7133<refentryinfo> 7134 <title>LINUX</title> 7135 <productname>Kernel Hackers Manual</productname> 7136 <date>July 2017</date> 7137</refentryinfo> 7138<refmeta> 7139 <refentrytitle><phrase>bio_add_pc_page</phrase></refentrytitle> 7140 <manvolnum>9</manvolnum> 7141 <refmiscinfo class="version">4.1.27</refmiscinfo> 7142</refmeta> 7143<refnamediv> 7144 <refname>bio_add_pc_page</refname> 7145 <refpurpose> 7146 attempt to add page to bio 7147 </refpurpose> 7148</refnamediv> 7149<refsynopsisdiv> 7150 <title>Synopsis</title> 7151 <funcsynopsis><funcprototype> 7152 <funcdef>int <function>bio_add_pc_page </function></funcdef> 7153 <paramdef>struct request_queue * <parameter>q</parameter></paramdef> 7154 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7155 <paramdef>struct page * <parameter>page</parameter></paramdef> 7156 <paramdef>unsigned int <parameter>len</parameter></paramdef> 7157 <paramdef>unsigned int <parameter>offset</parameter></paramdef> 7158 </funcprototype></funcsynopsis> 7159</refsynopsisdiv> 7160<refsect1> 7161 <title>Arguments</title> 7162 <variablelist> 7163 <varlistentry> 7164 <term><parameter>q</parameter></term> 7165 <listitem> 7166 <para> 7167 the target queue 7168 </para> 7169 </listitem> 7170 </varlistentry> 7171 <varlistentry> 7172 <term><parameter>bio</parameter></term> 7173 <listitem> 7174 <para> 7175 destination bio 7176 </para> 7177 </listitem> 7178 </varlistentry> 7179 <varlistentry> 7180 <term><parameter>page</parameter></term> 7181 <listitem> 7182 <para> 7183 page to add 7184 </para> 7185 </listitem> 7186 </varlistentry> 7187 <varlistentry> 7188 <term><parameter>len</parameter></term> 7189 <listitem> 7190 <para> 7191 vec entry length 7192 </para> 7193 </listitem> 7194 </varlistentry> 7195 <varlistentry> 7196 <term><parameter>offset</parameter></term> 7197 <listitem> 7198 <para> 7199 vec entry offset 7200 </para> 7201 </listitem> 7202 </varlistentry> 7203 </variablelist> 7204</refsect1> 7205<refsect1> 7206<title>Description</title> 7207<para> 7208 Attempt to add a page to the bio_vec maplist. This can fail for a 7209 number of reasons, such as the bio being full or target block device 7210 limitations. The target block device must allow bio's up to PAGE_SIZE, 7211 so it is always possible to add a single page to an empty bio. 7212 </para><para> 7213 7214 This should only be used by REQ_PC bios. 7215</para> 7216</refsect1> 7217</refentry> 7218 7219<refentry id="API-bio-add-page"> 7220<refentryinfo> 7221 <title>LINUX</title> 7222 <productname>Kernel Hackers Manual</productname> 7223 <date>July 2017</date> 7224</refentryinfo> 7225<refmeta> 7226 <refentrytitle><phrase>bio_add_page</phrase></refentrytitle> 7227 <manvolnum>9</manvolnum> 7228 <refmiscinfo class="version">4.1.27</refmiscinfo> 7229</refmeta> 7230<refnamediv> 7231 <refname>bio_add_page</refname> 7232 <refpurpose> 7233 attempt to add page to bio 7234 </refpurpose> 7235</refnamediv> 7236<refsynopsisdiv> 7237 <title>Synopsis</title> 7238 <funcsynopsis><funcprototype> 7239 <funcdef>int <function>bio_add_page </function></funcdef> 7240 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7241 <paramdef>struct page * <parameter>page</parameter></paramdef> 7242 <paramdef>unsigned int <parameter>len</parameter></paramdef> 7243 <paramdef>unsigned int <parameter>offset</parameter></paramdef> 7244 </funcprototype></funcsynopsis> 7245</refsynopsisdiv> 7246<refsect1> 7247 <title>Arguments</title> 7248 <variablelist> 7249 <varlistentry> 7250 <term><parameter>bio</parameter></term> 7251 <listitem> 7252 <para> 7253 destination bio 7254 </para> 7255 </listitem> 7256 </varlistentry> 7257 <varlistentry> 7258 <term><parameter>page</parameter></term> 7259 <listitem> 7260 <para> 7261 page to add 7262 </para> 7263 </listitem> 7264 </varlistentry> 7265 <varlistentry> 7266 <term><parameter>len</parameter></term> 7267 <listitem> 7268 <para> 7269 vec entry length 7270 </para> 7271 </listitem> 7272 </varlistentry> 7273 <varlistentry> 7274 <term><parameter>offset</parameter></term> 7275 <listitem> 7276 <para> 7277 vec entry offset 7278 </para> 7279 </listitem> 7280 </varlistentry> 7281 </variablelist> 7282</refsect1> 7283<refsect1> 7284<title>Description</title> 7285<para> 7286 Attempt to add a page to the bio_vec maplist. This can fail for a 7287 number of reasons, such as the bio being full or target block device 7288 limitations. The target block device must allow bio's up to PAGE_SIZE, 7289 so it is always possible to add a single page to an empty bio. 7290</para> 7291</refsect1> 7292</refentry> 7293 7294<refentry id="API-submit-bio-wait"> 7295<refentryinfo> 7296 <title>LINUX</title> 7297 <productname>Kernel Hackers Manual</productname> 7298 <date>July 2017</date> 7299</refentryinfo> 7300<refmeta> 7301 <refentrytitle><phrase>submit_bio_wait</phrase></refentrytitle> 7302 <manvolnum>9</manvolnum> 7303 <refmiscinfo class="version">4.1.27</refmiscinfo> 7304</refmeta> 7305<refnamediv> 7306 <refname>submit_bio_wait</refname> 7307 <refpurpose> 7308 submit a bio, and wait until it completes 7309 </refpurpose> 7310</refnamediv> 7311<refsynopsisdiv> 7312 <title>Synopsis</title> 7313 <funcsynopsis><funcprototype> 7314 <funcdef>int <function>submit_bio_wait </function></funcdef> 7315 <paramdef>int <parameter>rw</parameter></paramdef> 7316 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7317 </funcprototype></funcsynopsis> 7318</refsynopsisdiv> 7319<refsect1> 7320 <title>Arguments</title> 7321 <variablelist> 7322 <varlistentry> 7323 <term><parameter>rw</parameter></term> 7324 <listitem> 7325 <para> 7326 whether to <constant>READ</constant> or <constant>WRITE</constant>, or maybe to <constant>READA</constant> (read ahead) 7327 </para> 7328 </listitem> 7329 </varlistentry> 7330 <varlistentry> 7331 <term><parameter>bio</parameter></term> 7332 <listitem> 7333 <para> 7334 The <structname>struct bio</structname> which describes the I/O 7335 </para> 7336 </listitem> 7337 </varlistentry> 7338 </variablelist> 7339</refsect1> 7340<refsect1> 7341<title>Description</title> 7342<para> 7343 Simple wrapper around <function>submit_bio</function>. Returns 0 on success, or the error from 7344 <function>bio_endio</function> on failure. 7345</para> 7346</refsect1> 7347</refentry> 7348 7349<refentry id="API-bio-advance"> 7350<refentryinfo> 7351 <title>LINUX</title> 7352 <productname>Kernel Hackers Manual</productname> 7353 <date>July 2017</date> 7354</refentryinfo> 7355<refmeta> 7356 <refentrytitle><phrase>bio_advance</phrase></refentrytitle> 7357 <manvolnum>9</manvolnum> 7358 <refmiscinfo class="version">4.1.27</refmiscinfo> 7359</refmeta> 7360<refnamediv> 7361 <refname>bio_advance</refname> 7362 <refpurpose> 7363 increment/complete a bio by some number of bytes 7364 </refpurpose> 7365</refnamediv> 7366<refsynopsisdiv> 7367 <title>Synopsis</title> 7368 <funcsynopsis><funcprototype> 7369 <funcdef>void <function>bio_advance </function></funcdef> 7370 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7371 <paramdef>unsigned <parameter>bytes</parameter></paramdef> 7372 </funcprototype></funcsynopsis> 7373</refsynopsisdiv> 7374<refsect1> 7375 <title>Arguments</title> 7376 <variablelist> 7377 <varlistentry> 7378 <term><parameter>bio</parameter></term> 7379 <listitem> 7380 <para> 7381 bio to advance 7382 </para> 7383 </listitem> 7384 </varlistentry> 7385 <varlistentry> 7386 <term><parameter>bytes</parameter></term> 7387 <listitem> 7388 <para> 7389 number of bytes to complete 7390 </para> 7391 </listitem> 7392 </varlistentry> 7393 </variablelist> 7394</refsect1> 7395<refsect1> 7396<title>Description</title> 7397<para> 7398 This updates bi_sector, bi_size and bi_idx; if the number of bytes to 7399 complete doesn't align with a bvec boundary, then bv_len and bv_offset will 7400 be updated on the last bvec as well. 7401 </para><para> 7402 7403 <parameter>bio</parameter> will then represent the remaining, uncompleted portion of the io. 7404</para> 7405</refsect1> 7406</refentry> 7407 7408<refentry id="API-bio-alloc-pages"> 7409<refentryinfo> 7410 <title>LINUX</title> 7411 <productname>Kernel Hackers Manual</productname> 7412 <date>July 2017</date> 7413</refentryinfo> 7414<refmeta> 7415 <refentrytitle><phrase>bio_alloc_pages</phrase></refentrytitle> 7416 <manvolnum>9</manvolnum> 7417 <refmiscinfo class="version">4.1.27</refmiscinfo> 7418</refmeta> 7419<refnamediv> 7420 <refname>bio_alloc_pages</refname> 7421 <refpurpose> 7422 allocates a single page for each bvec in a bio 7423 </refpurpose> 7424</refnamediv> 7425<refsynopsisdiv> 7426 <title>Synopsis</title> 7427 <funcsynopsis><funcprototype> 7428 <funcdef>int <function>bio_alloc_pages </function></funcdef> 7429 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7430 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 7431 </funcprototype></funcsynopsis> 7432</refsynopsisdiv> 7433<refsect1> 7434 <title>Arguments</title> 7435 <variablelist> 7436 <varlistentry> 7437 <term><parameter>bio</parameter></term> 7438 <listitem> 7439 <para> 7440 bio to allocate pages for 7441 </para> 7442 </listitem> 7443 </varlistentry> 7444 <varlistentry> 7445 <term><parameter>gfp_mask</parameter></term> 7446 <listitem> 7447 <para> 7448 flags for allocation 7449 </para> 7450 </listitem> 7451 </varlistentry> 7452 </variablelist> 7453</refsect1> 7454<refsect1> 7455<title>Description</title> 7456<para> 7457 Allocates pages up to <parameter>bio</parameter>->bi_vcnt. 7458 </para><para> 7459 7460 Returns 0 on success, -ENOMEM on failure. On failure, any allocated pages are 7461 freed. 7462</para> 7463</refsect1> 7464</refentry> 7465 7466<refentry id="API-bio-copy-data"> 7467<refentryinfo> 7468 <title>LINUX</title> 7469 <productname>Kernel Hackers Manual</productname> 7470 <date>July 2017</date> 7471</refentryinfo> 7472<refmeta> 7473 <refentrytitle><phrase>bio_copy_data</phrase></refentrytitle> 7474 <manvolnum>9</manvolnum> 7475 <refmiscinfo class="version">4.1.27</refmiscinfo> 7476</refmeta> 7477<refnamediv> 7478 <refname>bio_copy_data</refname> 7479 <refpurpose> 7480 copy contents of data buffers from one chain of bios to another 7481 </refpurpose> 7482</refnamediv> 7483<refsynopsisdiv> 7484 <title>Synopsis</title> 7485 <funcsynopsis><funcprototype> 7486 <funcdef>void <function>bio_copy_data </function></funcdef> 7487 <paramdef>struct bio * <parameter>dst</parameter></paramdef> 7488 <paramdef>struct bio * <parameter>src</parameter></paramdef> 7489 </funcprototype></funcsynopsis> 7490</refsynopsisdiv> 7491<refsect1> 7492 <title>Arguments</title> 7493 <variablelist> 7494 <varlistentry> 7495 <term><parameter>dst</parameter></term> 7496 <listitem> 7497 <para> 7498 destination bio list 7499 </para> 7500 </listitem> 7501 </varlistentry> 7502 <varlistentry> 7503 <term><parameter>src</parameter></term> 7504 <listitem> 7505 <para> 7506 source bio list 7507 </para> 7508 </listitem> 7509 </varlistentry> 7510 </variablelist> 7511</refsect1> 7512<refsect1> 7513<title>Description</title> 7514<para> 7515 If <parameter>src</parameter> and <parameter>dst</parameter> are single bios, bi_next must be NULL - otherwise, treats 7516 <parameter>src</parameter> and <parameter>dst</parameter> as linked lists of bios. 7517 </para><para> 7518 7519 Stops when it reaches the end of either <parameter>src</parameter> or <parameter>dst</parameter> - that is, copies 7520 min(src->bi_size, dst->bi_size) bytes (or the equivalent for lists of bios). 7521</para> 7522</refsect1> 7523</refentry> 7524 7525<refentry id="API-bio-uncopy-user"> 7526<refentryinfo> 7527 <title>LINUX</title> 7528 <productname>Kernel Hackers Manual</productname> 7529 <date>July 2017</date> 7530</refentryinfo> 7531<refmeta> 7532 <refentrytitle><phrase>bio_uncopy_user</phrase></refentrytitle> 7533 <manvolnum>9</manvolnum> 7534 <refmiscinfo class="version">4.1.27</refmiscinfo> 7535</refmeta> 7536<refnamediv> 7537 <refname>bio_uncopy_user</refname> 7538 <refpurpose> 7539 finish previously mapped bio 7540 </refpurpose> 7541</refnamediv> 7542<refsynopsisdiv> 7543 <title>Synopsis</title> 7544 <funcsynopsis><funcprototype> 7545 <funcdef>int <function>bio_uncopy_user </function></funcdef> 7546 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7547 </funcprototype></funcsynopsis> 7548</refsynopsisdiv> 7549<refsect1> 7550 <title>Arguments</title> 7551 <variablelist> 7552 <varlistentry> 7553 <term><parameter>bio</parameter></term> 7554 <listitem> 7555 <para> 7556 bio being terminated 7557 </para> 7558 </listitem> 7559 </varlistentry> 7560 </variablelist> 7561</refsect1> 7562<refsect1> 7563<title>Description</title> 7564<para> 7565 Free pages allocated from <function>bio_copy_user_iov</function> and write back data 7566 to user space in case of a read. 7567</para> 7568</refsect1> 7569</refentry> 7570 7571<refentry id="API-bio-unmap-user"> 7572<refentryinfo> 7573 <title>LINUX</title> 7574 <productname>Kernel Hackers Manual</productname> 7575 <date>July 2017</date> 7576</refentryinfo> 7577<refmeta> 7578 <refentrytitle><phrase>bio_unmap_user</phrase></refentrytitle> 7579 <manvolnum>9</manvolnum> 7580 <refmiscinfo class="version">4.1.27</refmiscinfo> 7581</refmeta> 7582<refnamediv> 7583 <refname>bio_unmap_user</refname> 7584 <refpurpose> 7585 unmap a bio 7586 </refpurpose> 7587</refnamediv> 7588<refsynopsisdiv> 7589 <title>Synopsis</title> 7590 <funcsynopsis><funcprototype> 7591 <funcdef>void <function>bio_unmap_user </function></funcdef> 7592 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7593 </funcprototype></funcsynopsis> 7594</refsynopsisdiv> 7595<refsect1> 7596 <title>Arguments</title> 7597 <variablelist> 7598 <varlistentry> 7599 <term><parameter>bio</parameter></term> 7600 <listitem> 7601 <para> 7602 the bio being unmapped 7603 </para> 7604 </listitem> 7605 </varlistentry> 7606 </variablelist> 7607</refsect1> 7608<refsect1> 7609<title>Description</title> 7610<para> 7611 Unmap a bio previously mapped by <function>bio_map_user</function>. Must be called with 7612 a process context. 7613 </para><para> 7614 7615 <function>bio_unmap_user</function> may sleep. 7616</para> 7617</refsect1> 7618</refentry> 7619 7620<refentry id="API-bio-map-kern"> 7621<refentryinfo> 7622 <title>LINUX</title> 7623 <productname>Kernel Hackers Manual</productname> 7624 <date>July 2017</date> 7625</refentryinfo> 7626<refmeta> 7627 <refentrytitle><phrase>bio_map_kern</phrase></refentrytitle> 7628 <manvolnum>9</manvolnum> 7629 <refmiscinfo class="version">4.1.27</refmiscinfo> 7630</refmeta> 7631<refnamediv> 7632 <refname>bio_map_kern</refname> 7633 <refpurpose> 7634 map kernel address into bio 7635 </refpurpose> 7636</refnamediv> 7637<refsynopsisdiv> 7638 <title>Synopsis</title> 7639 <funcsynopsis><funcprototype> 7640 <funcdef>struct bio * <function>bio_map_kern </function></funcdef> 7641 <paramdef>struct request_queue * <parameter>q</parameter></paramdef> 7642 <paramdef>void * <parameter>data</parameter></paramdef> 7643 <paramdef>unsigned int <parameter>len</parameter></paramdef> 7644 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 7645 </funcprototype></funcsynopsis> 7646</refsynopsisdiv> 7647<refsect1> 7648 <title>Arguments</title> 7649 <variablelist> 7650 <varlistentry> 7651 <term><parameter>q</parameter></term> 7652 <listitem> 7653 <para> 7654 the struct request_queue for the bio 7655 </para> 7656 </listitem> 7657 </varlistentry> 7658 <varlistentry> 7659 <term><parameter>data</parameter></term> 7660 <listitem> 7661 <para> 7662 pointer to buffer to map 7663 </para> 7664 </listitem> 7665 </varlistentry> 7666 <varlistentry> 7667 <term><parameter>len</parameter></term> 7668 <listitem> 7669 <para> 7670 length in bytes 7671 </para> 7672 </listitem> 7673 </varlistentry> 7674 <varlistentry> 7675 <term><parameter>gfp_mask</parameter></term> 7676 <listitem> 7677 <para> 7678 allocation flags for bio allocation 7679 </para> 7680 </listitem> 7681 </varlistentry> 7682 </variablelist> 7683</refsect1> 7684<refsect1> 7685<title>Description</title> 7686<para> 7687 Map the kernel address into a bio suitable for io to a block 7688 device. Returns an error pointer in case of error. 7689</para> 7690</refsect1> 7691</refentry> 7692 7693<refentry id="API-bio-copy-kern"> 7694<refentryinfo> 7695 <title>LINUX</title> 7696 <productname>Kernel Hackers Manual</productname> 7697 <date>July 2017</date> 7698</refentryinfo> 7699<refmeta> 7700 <refentrytitle><phrase>bio_copy_kern</phrase></refentrytitle> 7701 <manvolnum>9</manvolnum> 7702 <refmiscinfo class="version">4.1.27</refmiscinfo> 7703</refmeta> 7704<refnamediv> 7705 <refname>bio_copy_kern</refname> 7706 <refpurpose> 7707 copy kernel address into bio 7708 </refpurpose> 7709</refnamediv> 7710<refsynopsisdiv> 7711 <title>Synopsis</title> 7712 <funcsynopsis><funcprototype> 7713 <funcdef>struct bio * <function>bio_copy_kern </function></funcdef> 7714 <paramdef>struct request_queue * <parameter>q</parameter></paramdef> 7715 <paramdef>void * <parameter>data</parameter></paramdef> 7716 <paramdef>unsigned int <parameter>len</parameter></paramdef> 7717 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 7718 <paramdef>int <parameter>reading</parameter></paramdef> 7719 </funcprototype></funcsynopsis> 7720</refsynopsisdiv> 7721<refsect1> 7722 <title>Arguments</title> 7723 <variablelist> 7724 <varlistentry> 7725 <term><parameter>q</parameter></term> 7726 <listitem> 7727 <para> 7728 the struct request_queue for the bio 7729 </para> 7730 </listitem> 7731 </varlistentry> 7732 <varlistentry> 7733 <term><parameter>data</parameter></term> 7734 <listitem> 7735 <para> 7736 pointer to buffer to copy 7737 </para> 7738 </listitem> 7739 </varlistentry> 7740 <varlistentry> 7741 <term><parameter>len</parameter></term> 7742 <listitem> 7743 <para> 7744 length in bytes 7745 </para> 7746 </listitem> 7747 </varlistentry> 7748 <varlistentry> 7749 <term><parameter>gfp_mask</parameter></term> 7750 <listitem> 7751 <para> 7752 allocation flags for bio and page allocation 7753 </para> 7754 </listitem> 7755 </varlistentry> 7756 <varlistentry> 7757 <term><parameter>reading</parameter></term> 7758 <listitem> 7759 <para> 7760 data direction is READ 7761 </para> 7762 </listitem> 7763 </varlistentry> 7764 </variablelist> 7765</refsect1> 7766<refsect1> 7767<title>Description</title> 7768<para> 7769 copy the kernel address into a bio suitable for io to a block 7770 device. Returns an error pointer in case of error. 7771</para> 7772</refsect1> 7773</refentry> 7774 7775<refentry id="API-bio-endio"> 7776<refentryinfo> 7777 <title>LINUX</title> 7778 <productname>Kernel Hackers Manual</productname> 7779 <date>July 2017</date> 7780</refentryinfo> 7781<refmeta> 7782 <refentrytitle><phrase>bio_endio</phrase></refentrytitle> 7783 <manvolnum>9</manvolnum> 7784 <refmiscinfo class="version">4.1.27</refmiscinfo> 7785</refmeta> 7786<refnamediv> 7787 <refname>bio_endio</refname> 7788 <refpurpose> 7789 end I/O on a bio 7790 </refpurpose> 7791</refnamediv> 7792<refsynopsisdiv> 7793 <title>Synopsis</title> 7794 <funcsynopsis><funcprototype> 7795 <funcdef>void <function>bio_endio </function></funcdef> 7796 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7797 <paramdef>int <parameter>error</parameter></paramdef> 7798 </funcprototype></funcsynopsis> 7799</refsynopsisdiv> 7800<refsect1> 7801 <title>Arguments</title> 7802 <variablelist> 7803 <varlistentry> 7804 <term><parameter>bio</parameter></term> 7805 <listitem> 7806 <para> 7807 bio 7808 </para> 7809 </listitem> 7810 </varlistentry> 7811 <varlistentry> 7812 <term><parameter>error</parameter></term> 7813 <listitem> 7814 <para> 7815 error, if any 7816 </para> 7817 </listitem> 7818 </varlistentry> 7819 </variablelist> 7820</refsect1> 7821<refsect1> 7822<title>Description</title> 7823<para> 7824 <function>bio_endio</function> will end I/O on the whole bio. <function>bio_endio</function> is the 7825 preferred way to end I/O on a bio, it takes care of clearing 7826 BIO_UPTODATE on error. <parameter>error</parameter> is 0 on success, and and one of the 7827 established -Exxxx (-EIO, for instance) error values in case 7828 something went wrong. No one should call <function>bi_end_io</function> directly on a 7829 bio unless they own it and thus know that it has an end_io 7830 function. 7831</para> 7832</refsect1> 7833</refentry> 7834 7835<refentry id="API-bio-endio-nodec"> 7836<refentryinfo> 7837 <title>LINUX</title> 7838 <productname>Kernel Hackers Manual</productname> 7839 <date>July 2017</date> 7840</refentryinfo> 7841<refmeta> 7842 <refentrytitle><phrase>bio_endio_nodec</phrase></refentrytitle> 7843 <manvolnum>9</manvolnum> 7844 <refmiscinfo class="version">4.1.27</refmiscinfo> 7845</refmeta> 7846<refnamediv> 7847 <refname>bio_endio_nodec</refname> 7848 <refpurpose> 7849 end I/O on a bio, without decrementing bi_remaining 7850 </refpurpose> 7851</refnamediv> 7852<refsynopsisdiv> 7853 <title>Synopsis</title> 7854 <funcsynopsis><funcprototype> 7855 <funcdef>void <function>bio_endio_nodec </function></funcdef> 7856 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7857 <paramdef>int <parameter>error</parameter></paramdef> 7858 </funcprototype></funcsynopsis> 7859</refsynopsisdiv> 7860<refsect1> 7861 <title>Arguments</title> 7862 <variablelist> 7863 <varlistentry> 7864 <term><parameter>bio</parameter></term> 7865 <listitem> 7866 <para> 7867 bio 7868 </para> 7869 </listitem> 7870 </varlistentry> 7871 <varlistentry> 7872 <term><parameter>error</parameter></term> 7873 <listitem> 7874 <para> 7875 error, if any 7876 </para> 7877 </listitem> 7878 </varlistentry> 7879 </variablelist> 7880</refsect1> 7881<refsect1> 7882<title>Description</title> 7883<para> 7884 For code that has saved and restored bi_end_io; thing hard before using this 7885 function, probably you should've cloned the entire bio. 7886</para> 7887</refsect1> 7888</refentry> 7889 7890<refentry id="API-bio-split"> 7891<refentryinfo> 7892 <title>LINUX</title> 7893 <productname>Kernel Hackers Manual</productname> 7894 <date>July 2017</date> 7895</refentryinfo> 7896<refmeta> 7897 <refentrytitle><phrase>bio_split</phrase></refentrytitle> 7898 <manvolnum>9</manvolnum> 7899 <refmiscinfo class="version">4.1.27</refmiscinfo> 7900</refmeta> 7901<refnamediv> 7902 <refname>bio_split</refname> 7903 <refpurpose> 7904 split a bio 7905 </refpurpose> 7906</refnamediv> 7907<refsynopsisdiv> 7908 <title>Synopsis</title> 7909 <funcsynopsis><funcprototype> 7910 <funcdef>struct bio * <function>bio_split </function></funcdef> 7911 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7912 <paramdef>int <parameter>sectors</parameter></paramdef> 7913 <paramdef>gfp_t <parameter>gfp</parameter></paramdef> 7914 <paramdef>struct bio_set * <parameter>bs</parameter></paramdef> 7915 </funcprototype></funcsynopsis> 7916</refsynopsisdiv> 7917<refsect1> 7918 <title>Arguments</title> 7919 <variablelist> 7920 <varlistentry> 7921 <term><parameter>bio</parameter></term> 7922 <listitem> 7923 <para> 7924 bio to split 7925 </para> 7926 </listitem> 7927 </varlistentry> 7928 <varlistentry> 7929 <term><parameter>sectors</parameter></term> 7930 <listitem> 7931 <para> 7932 number of sectors to split from the front of <parameter>bio</parameter> 7933 </para> 7934 </listitem> 7935 </varlistentry> 7936 <varlistentry> 7937 <term><parameter>gfp</parameter></term> 7938 <listitem> 7939 <para> 7940 gfp mask 7941 </para> 7942 </listitem> 7943 </varlistentry> 7944 <varlistentry> 7945 <term><parameter>bs</parameter></term> 7946 <listitem> 7947 <para> 7948 bio set to allocate from 7949 </para> 7950 </listitem> 7951 </varlistentry> 7952 </variablelist> 7953</refsect1> 7954<refsect1> 7955<title>Description</title> 7956<para> 7957 Allocates and returns a new bio which represents <parameter>sectors</parameter> from the start of 7958 <parameter>bio</parameter>, and updates <parameter>bio</parameter> to represent the remaining sectors. 7959 </para><para> 7960 7961 Unless this is a discard request the newly allocated bio will point 7962 to <parameter>bio</parameter>'s bi_io_vec; it is the caller's responsibility to ensure that 7963 <parameter>bio</parameter> is not freed before the split. 7964</para> 7965</refsect1> 7966</refentry> 7967 7968<refentry id="API-bio-trim"> 7969<refentryinfo> 7970 <title>LINUX</title> 7971 <productname>Kernel Hackers Manual</productname> 7972 <date>July 2017</date> 7973</refentryinfo> 7974<refmeta> 7975 <refentrytitle><phrase>bio_trim</phrase></refentrytitle> 7976 <manvolnum>9</manvolnum> 7977 <refmiscinfo class="version">4.1.27</refmiscinfo> 7978</refmeta> 7979<refnamediv> 7980 <refname>bio_trim</refname> 7981 <refpurpose> 7982 trim a bio 7983 </refpurpose> 7984</refnamediv> 7985<refsynopsisdiv> 7986 <title>Synopsis</title> 7987 <funcsynopsis><funcprototype> 7988 <funcdef>void <function>bio_trim </function></funcdef> 7989 <paramdef>struct bio * <parameter>bio</parameter></paramdef> 7990 <paramdef>int <parameter>offset</parameter></paramdef> 7991 <paramdef>int <parameter>size</parameter></paramdef> 7992 </funcprototype></funcsynopsis> 7993</refsynopsisdiv> 7994<refsect1> 7995 <title>Arguments</title> 7996 <variablelist> 7997 <varlistentry> 7998 <term><parameter>bio</parameter></term> 7999 <listitem> 8000 <para> 8001 bio to trim 8002 </para> 8003 </listitem> 8004 </varlistentry> 8005 <varlistentry> 8006 <term><parameter>offset</parameter></term> 8007 <listitem> 8008 <para> 8009 number of sectors to trim from the front of <parameter>bio</parameter> 8010 </para> 8011 </listitem> 8012 </varlistentry> 8013 <varlistentry> 8014 <term><parameter>size</parameter></term> 8015 <listitem> 8016 <para> 8017 size we want to trim <parameter>bio</parameter> to, in sectors 8018 </para> 8019 </listitem> 8020 </varlistentry> 8021 </variablelist> 8022</refsect1> 8023</refentry> 8024 8025<refentry id="API-bioset-create"> 8026<refentryinfo> 8027 <title>LINUX</title> 8028 <productname>Kernel Hackers Manual</productname> 8029 <date>July 2017</date> 8030</refentryinfo> 8031<refmeta> 8032 <refentrytitle><phrase>bioset_create</phrase></refentrytitle> 8033 <manvolnum>9</manvolnum> 8034 <refmiscinfo class="version">4.1.27</refmiscinfo> 8035</refmeta> 8036<refnamediv> 8037 <refname>bioset_create</refname> 8038 <refpurpose> 8039 Create a bio_set 8040 </refpurpose> 8041</refnamediv> 8042<refsynopsisdiv> 8043 <title>Synopsis</title> 8044 <funcsynopsis><funcprototype> 8045 <funcdef>struct bio_set * <function>bioset_create </function></funcdef> 8046 <paramdef>unsigned int <parameter>pool_size</parameter></paramdef> 8047 <paramdef>unsigned int <parameter>front_pad</parameter></paramdef> 8048 </funcprototype></funcsynopsis> 8049</refsynopsisdiv> 8050<refsect1> 8051 <title>Arguments</title> 8052 <variablelist> 8053 <varlistentry> 8054 <term><parameter>pool_size</parameter></term> 8055 <listitem> 8056 <para> 8057 Number of bio and bio_vecs to cache in the mempool 8058 </para> 8059 </listitem> 8060 </varlistentry> 8061 <varlistentry> 8062 <term><parameter>front_pad</parameter></term> 8063 <listitem> 8064 <para> 8065 Number of bytes to allocate in front of the returned bio 8066 </para> 8067 </listitem> 8068 </varlistentry> 8069 </variablelist> 8070</refsect1> 8071<refsect1> 8072<title>Description</title> 8073<para> 8074 Set up a bio_set to be used with <parameter>bio_alloc_bioset</parameter>. Allows the caller 8075 to ask for a number of bytes to be allocated in front of the bio. 8076 Front pad allocation is useful for embedding the bio inside 8077 another structure, to avoid allocating extra data to go with the bio. 8078 Note that the bio must be embedded at the END of that structure always, 8079 or things will break badly. 8080</para> 8081</refsect1> 8082</refentry> 8083 8084<refentry id="API-bioset-create-nobvec"> 8085<refentryinfo> 8086 <title>LINUX</title> 8087 <productname>Kernel Hackers Manual</productname> 8088 <date>July 2017</date> 8089</refentryinfo> 8090<refmeta> 8091 <refentrytitle><phrase>bioset_create_nobvec</phrase></refentrytitle> 8092 <manvolnum>9</manvolnum> 8093 <refmiscinfo class="version">4.1.27</refmiscinfo> 8094</refmeta> 8095<refnamediv> 8096 <refname>bioset_create_nobvec</refname> 8097 <refpurpose> 8098 Create a bio_set without bio_vec mempool 8099 </refpurpose> 8100</refnamediv> 8101<refsynopsisdiv> 8102 <title>Synopsis</title> 8103 <funcsynopsis><funcprototype> 8104 <funcdef>struct bio_set * <function>bioset_create_nobvec </function></funcdef> 8105 <paramdef>unsigned int <parameter>pool_size</parameter></paramdef> 8106 <paramdef>unsigned int <parameter>front_pad</parameter></paramdef> 8107 </funcprototype></funcsynopsis> 8108</refsynopsisdiv> 8109<refsect1> 8110 <title>Arguments</title> 8111 <variablelist> 8112 <varlistentry> 8113 <term><parameter>pool_size</parameter></term> 8114 <listitem> 8115 <para> 8116 Number of bio to cache in the mempool 8117 </para> 8118 </listitem> 8119 </varlistentry> 8120 <varlistentry> 8121 <term><parameter>front_pad</parameter></term> 8122 <listitem> 8123 <para> 8124 Number of bytes to allocate in front of the returned bio 8125 </para> 8126 </listitem> 8127 </varlistentry> 8128 </variablelist> 8129</refsect1> 8130<refsect1> 8131<title>Description</title> 8132<para> 8133 Same functionality as <function>bioset_create</function> except that mempool is not 8134 created for bio_vecs. Saving some memory for <function>bio_clone_fast</function> users. 8135</para> 8136</refsect1> 8137</refentry> 8138 8139<!-- fs/seq_file.c --> 8140<refentry id="API-seq-open"> 8141<refentryinfo> 8142 <title>LINUX</title> 8143 <productname>Kernel Hackers Manual</productname> 8144 <date>July 2017</date> 8145</refentryinfo> 8146<refmeta> 8147 <refentrytitle><phrase>seq_open</phrase></refentrytitle> 8148 <manvolnum>9</manvolnum> 8149 <refmiscinfo class="version">4.1.27</refmiscinfo> 8150</refmeta> 8151<refnamediv> 8152 <refname>seq_open</refname> 8153 <refpurpose> 8154 initialize sequential file 8155 </refpurpose> 8156</refnamediv> 8157<refsynopsisdiv> 8158 <title>Synopsis</title> 8159 <funcsynopsis><funcprototype> 8160 <funcdef>int <function>seq_open </function></funcdef> 8161 <paramdef>struct file * <parameter>file</parameter></paramdef> 8162 <paramdef>const struct seq_operations * <parameter>op</parameter></paramdef> 8163 </funcprototype></funcsynopsis> 8164</refsynopsisdiv> 8165<refsect1> 8166 <title>Arguments</title> 8167 <variablelist> 8168 <varlistentry> 8169 <term><parameter>file</parameter></term> 8170 <listitem> 8171 <para> 8172 file we initialize 8173 </para> 8174 </listitem> 8175 </varlistentry> 8176 <varlistentry> 8177 <term><parameter>op</parameter></term> 8178 <listitem> 8179 <para> 8180 method table describing the sequence 8181 </para> 8182 </listitem> 8183 </varlistentry> 8184 </variablelist> 8185</refsect1> 8186<refsect1> 8187<title>Description</title> 8188<para> 8189 <function>seq_open</function> sets <parameter>file</parameter>, associating it with a sequence described 8190 by <parameter>op</parameter>. <parameter>op</parameter>-><function>start</function> sets the iterator up and returns the first 8191 element of sequence. <parameter>op</parameter>-><function>stop</function> shuts it down. <parameter>op</parameter>-><function>next</function> 8192 returns the next element of sequence. <parameter>op</parameter>-><function>show</function> prints element 8193 into the buffer. In case of error -><function>start</function> and -><function>next</function> return 8194 ERR_PTR(error). In the end of sequence they return <constant>NULL</constant>. -><function>show</function> 8195 returns 0 in case of success and negative number in case of error. 8196 Returning SEQ_SKIP means <quote>discard this element and move on</quote>. 8197</para> 8198</refsect1> 8199</refentry> 8200 8201<refentry id="API-seq-read"> 8202<refentryinfo> 8203 <title>LINUX</title> 8204 <productname>Kernel Hackers Manual</productname> 8205 <date>July 2017</date> 8206</refentryinfo> 8207<refmeta> 8208 <refentrytitle><phrase>seq_read</phrase></refentrytitle> 8209 <manvolnum>9</manvolnum> 8210 <refmiscinfo class="version">4.1.27</refmiscinfo> 8211</refmeta> 8212<refnamediv> 8213 <refname>seq_read</refname> 8214 <refpurpose> 8215 -><function>read</function> method for sequential files. 8216 </refpurpose> 8217</refnamediv> 8218<refsynopsisdiv> 8219 <title>Synopsis</title> 8220 <funcsynopsis><funcprototype> 8221 <funcdef>ssize_t <function>seq_read </function></funcdef> 8222 <paramdef>struct file * <parameter>file</parameter></paramdef> 8223 <paramdef>char __user * <parameter>buf</parameter></paramdef> 8224 <paramdef>size_t <parameter>size</parameter></paramdef> 8225 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 8226 </funcprototype></funcsynopsis> 8227</refsynopsisdiv> 8228<refsect1> 8229 <title>Arguments</title> 8230 <variablelist> 8231 <varlistentry> 8232 <term><parameter>file</parameter></term> 8233 <listitem> 8234 <para> 8235 the file to read from 8236 </para> 8237 </listitem> 8238 </varlistentry> 8239 <varlistentry> 8240 <term><parameter>buf</parameter></term> 8241 <listitem> 8242 <para> 8243 the buffer to read to 8244 </para> 8245 </listitem> 8246 </varlistentry> 8247 <varlistentry> 8248 <term><parameter>size</parameter></term> 8249 <listitem> 8250 <para> 8251 the maximum number of bytes to read 8252 </para> 8253 </listitem> 8254 </varlistentry> 8255 <varlistentry> 8256 <term><parameter>ppos</parameter></term> 8257 <listitem> 8258 <para> 8259 the current position in the file 8260 </para> 8261 </listitem> 8262 </varlistentry> 8263 </variablelist> 8264</refsect1> 8265<refsect1> 8266<title>Description</title> 8267<para> 8268 Ready-made ->f_op-><function>read</function> 8269</para> 8270</refsect1> 8271</refentry> 8272 8273<refentry id="API-seq-lseek"> 8274<refentryinfo> 8275 <title>LINUX</title> 8276 <productname>Kernel Hackers Manual</productname> 8277 <date>July 2017</date> 8278</refentryinfo> 8279<refmeta> 8280 <refentrytitle><phrase>seq_lseek</phrase></refentrytitle> 8281 <manvolnum>9</manvolnum> 8282 <refmiscinfo class="version">4.1.27</refmiscinfo> 8283</refmeta> 8284<refnamediv> 8285 <refname>seq_lseek</refname> 8286 <refpurpose> 8287 -><function>llseek</function> method for sequential files. 8288 </refpurpose> 8289</refnamediv> 8290<refsynopsisdiv> 8291 <title>Synopsis</title> 8292 <funcsynopsis><funcprototype> 8293 <funcdef>loff_t <function>seq_lseek </function></funcdef> 8294 <paramdef>struct file * <parameter>file</parameter></paramdef> 8295 <paramdef>loff_t <parameter>offset</parameter></paramdef> 8296 <paramdef>int <parameter>whence</parameter></paramdef> 8297 </funcprototype></funcsynopsis> 8298</refsynopsisdiv> 8299<refsect1> 8300 <title>Arguments</title> 8301 <variablelist> 8302 <varlistentry> 8303 <term><parameter>file</parameter></term> 8304 <listitem> 8305 <para> 8306 the file in question 8307 </para> 8308 </listitem> 8309 </varlistentry> 8310 <varlistentry> 8311 <term><parameter>offset</parameter></term> 8312 <listitem> 8313 <para> 8314 new position 8315 </para> 8316 </listitem> 8317 </varlistentry> 8318 <varlistentry> 8319 <term><parameter>whence</parameter></term> 8320 <listitem> 8321 <para> 8322 0 for absolute, 1 for relative position 8323 </para> 8324 </listitem> 8325 </varlistentry> 8326 </variablelist> 8327</refsect1> 8328<refsect1> 8329<title>Description</title> 8330<para> 8331 Ready-made ->f_op-><function>llseek</function> 8332</para> 8333</refsect1> 8334</refentry> 8335 8336<refentry id="API-seq-release"> 8337<refentryinfo> 8338 <title>LINUX</title> 8339 <productname>Kernel Hackers Manual</productname> 8340 <date>July 2017</date> 8341</refentryinfo> 8342<refmeta> 8343 <refentrytitle><phrase>seq_release</phrase></refentrytitle> 8344 <manvolnum>9</manvolnum> 8345 <refmiscinfo class="version">4.1.27</refmiscinfo> 8346</refmeta> 8347<refnamediv> 8348 <refname>seq_release</refname> 8349 <refpurpose> 8350 free the structures associated with sequential file. 8351 </refpurpose> 8352</refnamediv> 8353<refsynopsisdiv> 8354 <title>Synopsis</title> 8355 <funcsynopsis><funcprototype> 8356 <funcdef>int <function>seq_release </function></funcdef> 8357 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 8358 <paramdef>struct file * <parameter>file</parameter></paramdef> 8359 </funcprototype></funcsynopsis> 8360</refsynopsisdiv> 8361<refsect1> 8362 <title>Arguments</title> 8363 <variablelist> 8364 <varlistentry> 8365 <term><parameter>inode</parameter></term> 8366 <listitem> 8367 <para> 8368 its inode 8369 </para> 8370 </listitem> 8371 </varlistentry> 8372 <varlistentry> 8373 <term><parameter>file</parameter></term> 8374 <listitem> 8375 <para> 8376 file in question 8377 </para> 8378 </listitem> 8379 </varlistentry> 8380 </variablelist> 8381</refsect1> 8382<refsect1> 8383<title>Description</title> 8384<para> 8385 Frees the structures associated with sequential file; can be used 8386 as ->f_op-><function>release</function> if you don't have private data to destroy. 8387</para> 8388</refsect1> 8389</refentry> 8390 8391<refentry id="API-seq-escape"> 8392<refentryinfo> 8393 <title>LINUX</title> 8394 <productname>Kernel Hackers Manual</productname> 8395 <date>July 2017</date> 8396</refentryinfo> 8397<refmeta> 8398 <refentrytitle><phrase>seq_escape</phrase></refentrytitle> 8399 <manvolnum>9</manvolnum> 8400 <refmiscinfo class="version">4.1.27</refmiscinfo> 8401</refmeta> 8402<refnamediv> 8403 <refname>seq_escape</refname> 8404 <refpurpose> 8405 print string into buffer, escaping some characters 8406 </refpurpose> 8407</refnamediv> 8408<refsynopsisdiv> 8409 <title>Synopsis</title> 8410 <funcsynopsis><funcprototype> 8411 <funcdef>int <function>seq_escape </function></funcdef> 8412 <paramdef>struct seq_file * <parameter>m</parameter></paramdef> 8413 <paramdef>const char * <parameter>s</parameter></paramdef> 8414 <paramdef>const char * <parameter>esc</parameter></paramdef> 8415 </funcprototype></funcsynopsis> 8416</refsynopsisdiv> 8417<refsect1> 8418 <title>Arguments</title> 8419 <variablelist> 8420 <varlistentry> 8421 <term><parameter>m</parameter></term> 8422 <listitem> 8423 <para> 8424 target buffer 8425 </para> 8426 </listitem> 8427 </varlistentry> 8428 <varlistentry> 8429 <term><parameter>s</parameter></term> 8430 <listitem> 8431 <para> 8432 string 8433 </para> 8434 </listitem> 8435 </varlistentry> 8436 <varlistentry> 8437 <term><parameter>esc</parameter></term> 8438 <listitem> 8439 <para> 8440 set of characters that need escaping 8441 </para> 8442 </listitem> 8443 </varlistentry> 8444 </variablelist> 8445</refsect1> 8446<refsect1> 8447<title>Description</title> 8448<para> 8449 Puts string into buffer, replacing each occurrence of character from 8450 <parameter>esc</parameter> with usual octal escape. Returns 0 in case of success, -1 - in 8451 case of overflow. 8452</para> 8453</refsect1> 8454</refentry> 8455 8456<refentry id="API-mangle-path"> 8457<refentryinfo> 8458 <title>LINUX</title> 8459 <productname>Kernel Hackers Manual</productname> 8460 <date>July 2017</date> 8461</refentryinfo> 8462<refmeta> 8463 <refentrytitle><phrase>mangle_path</phrase></refentrytitle> 8464 <manvolnum>9</manvolnum> 8465 <refmiscinfo class="version">4.1.27</refmiscinfo> 8466</refmeta> 8467<refnamediv> 8468 <refname>mangle_path</refname> 8469 <refpurpose> 8470 mangle and copy path to buffer beginning 8471 </refpurpose> 8472</refnamediv> 8473<refsynopsisdiv> 8474 <title>Synopsis</title> 8475 <funcsynopsis><funcprototype> 8476 <funcdef>char * <function>mangle_path </function></funcdef> 8477 <paramdef>char * <parameter>s</parameter></paramdef> 8478 <paramdef>const char * <parameter>p</parameter></paramdef> 8479 <paramdef>const char * <parameter>esc</parameter></paramdef> 8480 </funcprototype></funcsynopsis> 8481</refsynopsisdiv> 8482<refsect1> 8483 <title>Arguments</title> 8484 <variablelist> 8485 <varlistentry> 8486 <term><parameter>s</parameter></term> 8487 <listitem> 8488 <para> 8489 buffer start 8490 </para> 8491 </listitem> 8492 </varlistentry> 8493 <varlistentry> 8494 <term><parameter>p</parameter></term> 8495 <listitem> 8496 <para> 8497 beginning of path in above buffer 8498 </para> 8499 </listitem> 8500 </varlistentry> 8501 <varlistentry> 8502 <term><parameter>esc</parameter></term> 8503 <listitem> 8504 <para> 8505 set of characters that need escaping 8506 </para> 8507 </listitem> 8508 </varlistentry> 8509 </variablelist> 8510</refsect1> 8511<refsect1> 8512<title>Description</title> 8513<para> 8514 Copy the path from <parameter>p</parameter> to <parameter>s</parameter>, replacing each occurrence of character from 8515 <parameter>esc</parameter> with usual octal escape. 8516 Returns pointer past last written character in <parameter>s</parameter>, or NULL in case of 8517 failure. 8518</para> 8519</refsect1> 8520</refentry> 8521 8522<refentry id="API-seq-path"> 8523<refentryinfo> 8524 <title>LINUX</title> 8525 <productname>Kernel Hackers Manual</productname> 8526 <date>July 2017</date> 8527</refentryinfo> 8528<refmeta> 8529 <refentrytitle><phrase>seq_path</phrase></refentrytitle> 8530 <manvolnum>9</manvolnum> 8531 <refmiscinfo class="version">4.1.27</refmiscinfo> 8532</refmeta> 8533<refnamediv> 8534 <refname>seq_path</refname> 8535 <refpurpose> 8536 seq_file interface to print a pathname 8537 </refpurpose> 8538</refnamediv> 8539<refsynopsisdiv> 8540 <title>Synopsis</title> 8541 <funcsynopsis><funcprototype> 8542 <funcdef>int <function>seq_path </function></funcdef> 8543 <paramdef>struct seq_file * <parameter>m</parameter></paramdef> 8544 <paramdef>const struct path * <parameter>path</parameter></paramdef> 8545 <paramdef>const char * <parameter>esc</parameter></paramdef> 8546 </funcprototype></funcsynopsis> 8547</refsynopsisdiv> 8548<refsect1> 8549 <title>Arguments</title> 8550 <variablelist> 8551 <varlistentry> 8552 <term><parameter>m</parameter></term> 8553 <listitem> 8554 <para> 8555 the seq_file handle 8556 </para> 8557 </listitem> 8558 </varlistentry> 8559 <varlistentry> 8560 <term><parameter>path</parameter></term> 8561 <listitem> 8562 <para> 8563 the struct path to print 8564 </para> 8565 </listitem> 8566 </varlistentry> 8567 <varlistentry> 8568 <term><parameter>esc</parameter></term> 8569 <listitem> 8570 <para> 8571 set of characters to escape in the output 8572 </para> 8573 </listitem> 8574 </varlistentry> 8575 </variablelist> 8576</refsect1> 8577<refsect1> 8578<title>Description</title> 8579<para> 8580 return the absolute path of 'path', as represented by the 8581 dentry / mnt pair in the path parameter. 8582</para> 8583</refsect1> 8584</refentry> 8585 8586<refentry id="API-seq-write"> 8587<refentryinfo> 8588 <title>LINUX</title> 8589 <productname>Kernel Hackers Manual</productname> 8590 <date>July 2017</date> 8591</refentryinfo> 8592<refmeta> 8593 <refentrytitle><phrase>seq_write</phrase></refentrytitle> 8594 <manvolnum>9</manvolnum> 8595 <refmiscinfo class="version">4.1.27</refmiscinfo> 8596</refmeta> 8597<refnamediv> 8598 <refname>seq_write</refname> 8599 <refpurpose> 8600 write arbitrary data to buffer 8601 </refpurpose> 8602</refnamediv> 8603<refsynopsisdiv> 8604 <title>Synopsis</title> 8605 <funcsynopsis><funcprototype> 8606 <funcdef>int <function>seq_write </function></funcdef> 8607 <paramdef>struct seq_file * <parameter>seq</parameter></paramdef> 8608 <paramdef>const void * <parameter>data</parameter></paramdef> 8609 <paramdef>size_t <parameter>len</parameter></paramdef> 8610 </funcprototype></funcsynopsis> 8611</refsynopsisdiv> 8612<refsect1> 8613 <title>Arguments</title> 8614 <variablelist> 8615 <varlistentry> 8616 <term><parameter>seq</parameter></term> 8617 <listitem> 8618 <para> 8619 seq_file identifying the buffer to which data should be written 8620 </para> 8621 </listitem> 8622 </varlistentry> 8623 <varlistentry> 8624 <term><parameter>data</parameter></term> 8625 <listitem> 8626 <para> 8627 data address 8628 </para> 8629 </listitem> 8630 </varlistentry> 8631 <varlistentry> 8632 <term><parameter>len</parameter></term> 8633 <listitem> 8634 <para> 8635 number of bytes 8636 </para> 8637 </listitem> 8638 </varlistentry> 8639 </variablelist> 8640</refsect1> 8641<refsect1> 8642<title>Description</title> 8643<para> 8644 Return 0 on success, non-zero otherwise. 8645</para> 8646</refsect1> 8647</refentry> 8648 8649<refentry id="API-seq-pad"> 8650<refentryinfo> 8651 <title>LINUX</title> 8652 <productname>Kernel Hackers Manual</productname> 8653 <date>July 2017</date> 8654</refentryinfo> 8655<refmeta> 8656 <refentrytitle><phrase>seq_pad</phrase></refentrytitle> 8657 <manvolnum>9</manvolnum> 8658 <refmiscinfo class="version">4.1.27</refmiscinfo> 8659</refmeta> 8660<refnamediv> 8661 <refname>seq_pad</refname> 8662 <refpurpose> 8663 write padding spaces to buffer 8664 </refpurpose> 8665</refnamediv> 8666<refsynopsisdiv> 8667 <title>Synopsis</title> 8668 <funcsynopsis><funcprototype> 8669 <funcdef>void <function>seq_pad </function></funcdef> 8670 <paramdef>struct seq_file * <parameter>m</parameter></paramdef> 8671 <paramdef>char <parameter>c</parameter></paramdef> 8672 </funcprototype></funcsynopsis> 8673</refsynopsisdiv> 8674<refsect1> 8675 <title>Arguments</title> 8676 <variablelist> 8677 <varlistentry> 8678 <term><parameter>m</parameter></term> 8679 <listitem> 8680 <para> 8681 seq_file identifying the buffer to which data should be written 8682 </para> 8683 </listitem> 8684 </varlistentry> 8685 <varlistentry> 8686 <term><parameter>c</parameter></term> 8687 <listitem> 8688 <para> 8689 the byte to append after padding if non-zero 8690 </para> 8691 </listitem> 8692 </varlistentry> 8693 </variablelist> 8694</refsect1> 8695</refentry> 8696 8697<refentry id="API-seq-hlist-start"> 8698<refentryinfo> 8699 <title>LINUX</title> 8700 <productname>Kernel Hackers Manual</productname> 8701 <date>July 2017</date> 8702</refentryinfo> 8703<refmeta> 8704 <refentrytitle><phrase>seq_hlist_start</phrase></refentrytitle> 8705 <manvolnum>9</manvolnum> 8706 <refmiscinfo class="version">4.1.27</refmiscinfo> 8707</refmeta> 8708<refnamediv> 8709 <refname>seq_hlist_start</refname> 8710 <refpurpose> 8711 start an iteration of a hlist 8712 </refpurpose> 8713</refnamediv> 8714<refsynopsisdiv> 8715 <title>Synopsis</title> 8716 <funcsynopsis><funcprototype> 8717 <funcdef>struct hlist_node * <function>seq_hlist_start </function></funcdef> 8718 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 8719 <paramdef>loff_t <parameter>pos</parameter></paramdef> 8720 </funcprototype></funcsynopsis> 8721</refsynopsisdiv> 8722<refsect1> 8723 <title>Arguments</title> 8724 <variablelist> 8725 <varlistentry> 8726 <term><parameter>head</parameter></term> 8727 <listitem> 8728 <para> 8729 the head of the hlist 8730 </para> 8731 </listitem> 8732 </varlistentry> 8733 <varlistentry> 8734 <term><parameter>pos</parameter></term> 8735 <listitem> 8736 <para> 8737 the start position of the sequence 8738 </para> 8739 </listitem> 8740 </varlistentry> 8741 </variablelist> 8742</refsect1> 8743<refsect1> 8744<title>Description</title> 8745<para> 8746 Called at seq_file->op-><function>start</function>. 8747</para> 8748</refsect1> 8749</refentry> 8750 8751<refentry id="API-seq-hlist-start-head"> 8752<refentryinfo> 8753 <title>LINUX</title> 8754 <productname>Kernel Hackers Manual</productname> 8755 <date>July 2017</date> 8756</refentryinfo> 8757<refmeta> 8758 <refentrytitle><phrase>seq_hlist_start_head</phrase></refentrytitle> 8759 <manvolnum>9</manvolnum> 8760 <refmiscinfo class="version">4.1.27</refmiscinfo> 8761</refmeta> 8762<refnamediv> 8763 <refname>seq_hlist_start_head</refname> 8764 <refpurpose> 8765 start an iteration of a hlist 8766 </refpurpose> 8767</refnamediv> 8768<refsynopsisdiv> 8769 <title>Synopsis</title> 8770 <funcsynopsis><funcprototype> 8771 <funcdef>struct hlist_node * <function>seq_hlist_start_head </function></funcdef> 8772 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 8773 <paramdef>loff_t <parameter>pos</parameter></paramdef> 8774 </funcprototype></funcsynopsis> 8775</refsynopsisdiv> 8776<refsect1> 8777 <title>Arguments</title> 8778 <variablelist> 8779 <varlistentry> 8780 <term><parameter>head</parameter></term> 8781 <listitem> 8782 <para> 8783 the head of the hlist 8784 </para> 8785 </listitem> 8786 </varlistentry> 8787 <varlistentry> 8788 <term><parameter>pos</parameter></term> 8789 <listitem> 8790 <para> 8791 the start position of the sequence 8792 </para> 8793 </listitem> 8794 </varlistentry> 8795 </variablelist> 8796</refsect1> 8797<refsect1> 8798<title>Description</title> 8799<para> 8800 Called at seq_file->op-><function>start</function>. Call this function if you want to 8801 print a header at the top of the output. 8802</para> 8803</refsect1> 8804</refentry> 8805 8806<refentry id="API-seq-hlist-next"> 8807<refentryinfo> 8808 <title>LINUX</title> 8809 <productname>Kernel Hackers Manual</productname> 8810 <date>July 2017</date> 8811</refentryinfo> 8812<refmeta> 8813 <refentrytitle><phrase>seq_hlist_next</phrase></refentrytitle> 8814 <manvolnum>9</manvolnum> 8815 <refmiscinfo class="version">4.1.27</refmiscinfo> 8816</refmeta> 8817<refnamediv> 8818 <refname>seq_hlist_next</refname> 8819 <refpurpose> 8820 move to the next position of the hlist 8821 </refpurpose> 8822</refnamediv> 8823<refsynopsisdiv> 8824 <title>Synopsis</title> 8825 <funcsynopsis><funcprototype> 8826 <funcdef>struct hlist_node * <function>seq_hlist_next </function></funcdef> 8827 <paramdef>void * <parameter>v</parameter></paramdef> 8828 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 8829 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 8830 </funcprototype></funcsynopsis> 8831</refsynopsisdiv> 8832<refsect1> 8833 <title>Arguments</title> 8834 <variablelist> 8835 <varlistentry> 8836 <term><parameter>v</parameter></term> 8837 <listitem> 8838 <para> 8839 the current iterator 8840 </para> 8841 </listitem> 8842 </varlistentry> 8843 <varlistentry> 8844 <term><parameter>head</parameter></term> 8845 <listitem> 8846 <para> 8847 the head of the hlist 8848 </para> 8849 </listitem> 8850 </varlistentry> 8851 <varlistentry> 8852 <term><parameter>ppos</parameter></term> 8853 <listitem> 8854 <para> 8855 the current position 8856 </para> 8857 </listitem> 8858 </varlistentry> 8859 </variablelist> 8860</refsect1> 8861<refsect1> 8862<title>Description</title> 8863<para> 8864 Called at seq_file->op-><function>next</function>. 8865</para> 8866</refsect1> 8867</refentry> 8868 8869<refentry id="API-seq-hlist-start-rcu"> 8870<refentryinfo> 8871 <title>LINUX</title> 8872 <productname>Kernel Hackers Manual</productname> 8873 <date>July 2017</date> 8874</refentryinfo> 8875<refmeta> 8876 <refentrytitle><phrase>seq_hlist_start_rcu</phrase></refentrytitle> 8877 <manvolnum>9</manvolnum> 8878 <refmiscinfo class="version">4.1.27</refmiscinfo> 8879</refmeta> 8880<refnamediv> 8881 <refname>seq_hlist_start_rcu</refname> 8882 <refpurpose> 8883 start an iteration of a hlist protected by RCU 8884 </refpurpose> 8885</refnamediv> 8886<refsynopsisdiv> 8887 <title>Synopsis</title> 8888 <funcsynopsis><funcprototype> 8889 <funcdef>struct hlist_node * <function>seq_hlist_start_rcu </function></funcdef> 8890 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 8891 <paramdef>loff_t <parameter>pos</parameter></paramdef> 8892 </funcprototype></funcsynopsis> 8893</refsynopsisdiv> 8894<refsect1> 8895 <title>Arguments</title> 8896 <variablelist> 8897 <varlistentry> 8898 <term><parameter>head</parameter></term> 8899 <listitem> 8900 <para> 8901 the head of the hlist 8902 </para> 8903 </listitem> 8904 </varlistentry> 8905 <varlistentry> 8906 <term><parameter>pos</parameter></term> 8907 <listitem> 8908 <para> 8909 the start position of the sequence 8910 </para> 8911 </listitem> 8912 </varlistentry> 8913 </variablelist> 8914</refsect1> 8915<refsect1> 8916<title>Description</title> 8917<para> 8918 Called at seq_file->op-><function>start</function>. 8919 </para><para> 8920 8921 This list-traversal primitive may safely run concurrently with 8922 the _rcu list-mutation primitives such as <function>hlist_add_head_rcu</function> 8923 as long as the traversal is guarded by <function>rcu_read_lock</function>. 8924</para> 8925</refsect1> 8926</refentry> 8927 8928<refentry id="API-seq-hlist-start-head-rcu"> 8929<refentryinfo> 8930 <title>LINUX</title> 8931 <productname>Kernel Hackers Manual</productname> 8932 <date>July 2017</date> 8933</refentryinfo> 8934<refmeta> 8935 <refentrytitle><phrase>seq_hlist_start_head_rcu</phrase></refentrytitle> 8936 <manvolnum>9</manvolnum> 8937 <refmiscinfo class="version">4.1.27</refmiscinfo> 8938</refmeta> 8939<refnamediv> 8940 <refname>seq_hlist_start_head_rcu</refname> 8941 <refpurpose> 8942 start an iteration of a hlist protected by RCU 8943 </refpurpose> 8944</refnamediv> 8945<refsynopsisdiv> 8946 <title>Synopsis</title> 8947 <funcsynopsis><funcprototype> 8948 <funcdef>struct hlist_node * <function>seq_hlist_start_head_rcu </function></funcdef> 8949 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 8950 <paramdef>loff_t <parameter>pos</parameter></paramdef> 8951 </funcprototype></funcsynopsis> 8952</refsynopsisdiv> 8953<refsect1> 8954 <title>Arguments</title> 8955 <variablelist> 8956 <varlistentry> 8957 <term><parameter>head</parameter></term> 8958 <listitem> 8959 <para> 8960 the head of the hlist 8961 </para> 8962 </listitem> 8963 </varlistentry> 8964 <varlistentry> 8965 <term><parameter>pos</parameter></term> 8966 <listitem> 8967 <para> 8968 the start position of the sequence 8969 </para> 8970 </listitem> 8971 </varlistentry> 8972 </variablelist> 8973</refsect1> 8974<refsect1> 8975<title>Description</title> 8976<para> 8977 Called at seq_file->op-><function>start</function>. Call this function if you want to 8978 print a header at the top of the output. 8979 </para><para> 8980 8981 This list-traversal primitive may safely run concurrently with 8982 the _rcu list-mutation primitives such as <function>hlist_add_head_rcu</function> 8983 as long as the traversal is guarded by <function>rcu_read_lock</function>. 8984</para> 8985</refsect1> 8986</refentry> 8987 8988<refentry id="API-seq-hlist-next-rcu"> 8989<refentryinfo> 8990 <title>LINUX</title> 8991 <productname>Kernel Hackers Manual</productname> 8992 <date>July 2017</date> 8993</refentryinfo> 8994<refmeta> 8995 <refentrytitle><phrase>seq_hlist_next_rcu</phrase></refentrytitle> 8996 <manvolnum>9</manvolnum> 8997 <refmiscinfo class="version">4.1.27</refmiscinfo> 8998</refmeta> 8999<refnamediv> 9000 <refname>seq_hlist_next_rcu</refname> 9001 <refpurpose> 9002 move to the next position of the hlist protected by RCU 9003 </refpurpose> 9004</refnamediv> 9005<refsynopsisdiv> 9006 <title>Synopsis</title> 9007 <funcsynopsis><funcprototype> 9008 <funcdef>struct hlist_node * <function>seq_hlist_next_rcu </function></funcdef> 9009 <paramdef>void * <parameter>v</parameter></paramdef> 9010 <paramdef>struct hlist_head * <parameter>head</parameter></paramdef> 9011 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 9012 </funcprototype></funcsynopsis> 9013</refsynopsisdiv> 9014<refsect1> 9015 <title>Arguments</title> 9016 <variablelist> 9017 <varlistentry> 9018 <term><parameter>v</parameter></term> 9019 <listitem> 9020 <para> 9021 the current iterator 9022 </para> 9023 </listitem> 9024 </varlistentry> 9025 <varlistentry> 9026 <term><parameter>head</parameter></term> 9027 <listitem> 9028 <para> 9029 the head of the hlist 9030 </para> 9031 </listitem> 9032 </varlistentry> 9033 <varlistentry> 9034 <term><parameter>ppos</parameter></term> 9035 <listitem> 9036 <para> 9037 the current position 9038 </para> 9039 </listitem> 9040 </varlistentry> 9041 </variablelist> 9042</refsect1> 9043<refsect1> 9044<title>Description</title> 9045<para> 9046 Called at seq_file->op-><function>next</function>. 9047 </para><para> 9048 9049 This list-traversal primitive may safely run concurrently with 9050 the _rcu list-mutation primitives such as <function>hlist_add_head_rcu</function> 9051 as long as the traversal is guarded by <function>rcu_read_lock</function>. 9052</para> 9053</refsect1> 9054</refentry> 9055 9056<refentry id="API-seq-hlist-start-percpu"> 9057<refentryinfo> 9058 <title>LINUX</title> 9059 <productname>Kernel Hackers Manual</productname> 9060 <date>July 2017</date> 9061</refentryinfo> 9062<refmeta> 9063 <refentrytitle><phrase>seq_hlist_start_percpu</phrase></refentrytitle> 9064 <manvolnum>9</manvolnum> 9065 <refmiscinfo class="version">4.1.27</refmiscinfo> 9066</refmeta> 9067<refnamediv> 9068 <refname>seq_hlist_start_percpu</refname> 9069 <refpurpose> 9070 start an iteration of a percpu hlist array 9071 </refpurpose> 9072</refnamediv> 9073<refsynopsisdiv> 9074 <title>Synopsis</title> 9075 <funcsynopsis><funcprototype> 9076 <funcdef>struct hlist_node * <function>seq_hlist_start_percpu </function></funcdef> 9077 <paramdef>struct hlist_head __percpu * <parameter>head</parameter></paramdef> 9078 <paramdef>int * <parameter>cpu</parameter></paramdef> 9079 <paramdef>loff_t <parameter>pos</parameter></paramdef> 9080 </funcprototype></funcsynopsis> 9081</refsynopsisdiv> 9082<refsect1> 9083 <title>Arguments</title> 9084 <variablelist> 9085 <varlistentry> 9086 <term><parameter>head</parameter></term> 9087 <listitem> 9088 <para> 9089 pointer to percpu array of struct hlist_heads 9090 </para> 9091 </listitem> 9092 </varlistentry> 9093 <varlistentry> 9094 <term><parameter>cpu</parameter></term> 9095 <listitem> 9096 <para> 9097 pointer to cpu <quote>cursor</quote> 9098 </para> 9099 </listitem> 9100 </varlistentry> 9101 <varlistentry> 9102 <term><parameter>pos</parameter></term> 9103 <listitem> 9104 <para> 9105 start position of sequence 9106 </para> 9107 </listitem> 9108 </varlistentry> 9109 </variablelist> 9110</refsect1> 9111<refsect1> 9112<title>Description</title> 9113<para> 9114 Called at seq_file->op-><function>start</function>. 9115</para> 9116</refsect1> 9117</refentry> 9118 9119<refentry id="API-seq-hlist-next-percpu"> 9120<refentryinfo> 9121 <title>LINUX</title> 9122 <productname>Kernel Hackers Manual</productname> 9123 <date>July 2017</date> 9124</refentryinfo> 9125<refmeta> 9126 <refentrytitle><phrase>seq_hlist_next_percpu</phrase></refentrytitle> 9127 <manvolnum>9</manvolnum> 9128 <refmiscinfo class="version">4.1.27</refmiscinfo> 9129</refmeta> 9130<refnamediv> 9131 <refname>seq_hlist_next_percpu</refname> 9132 <refpurpose> 9133 move to the next position of the percpu hlist array 9134 </refpurpose> 9135</refnamediv> 9136<refsynopsisdiv> 9137 <title>Synopsis</title> 9138 <funcsynopsis><funcprototype> 9139 <funcdef>struct hlist_node * <function>seq_hlist_next_percpu </function></funcdef> 9140 <paramdef>void * <parameter>v</parameter></paramdef> 9141 <paramdef>struct hlist_head __percpu * <parameter>head</parameter></paramdef> 9142 <paramdef>int * <parameter>cpu</parameter></paramdef> 9143 <paramdef>loff_t * <parameter>pos</parameter></paramdef> 9144 </funcprototype></funcsynopsis> 9145</refsynopsisdiv> 9146<refsect1> 9147 <title>Arguments</title> 9148 <variablelist> 9149 <varlistentry> 9150 <term><parameter>v</parameter></term> 9151 <listitem> 9152 <para> 9153 pointer to current hlist_node 9154 </para> 9155 </listitem> 9156 </varlistentry> 9157 <varlistentry> 9158 <term><parameter>head</parameter></term> 9159 <listitem> 9160 <para> 9161 pointer to percpu array of struct hlist_heads 9162 </para> 9163 </listitem> 9164 </varlistentry> 9165 <varlistentry> 9166 <term><parameter>cpu</parameter></term> 9167 <listitem> 9168 <para> 9169 pointer to cpu <quote>cursor</quote> 9170 </para> 9171 </listitem> 9172 </varlistentry> 9173 <varlistentry> 9174 <term><parameter>pos</parameter></term> 9175 <listitem> 9176 <para> 9177 start position of sequence 9178 </para> 9179 </listitem> 9180 </varlistentry> 9181 </variablelist> 9182</refsect1> 9183<refsect1> 9184<title>Description</title> 9185<para> 9186 Called at seq_file->op-><function>next</function>. 9187</para> 9188</refsect1> 9189</refentry> 9190 9191<!-- fs/filesystems.c --> 9192<refentry id="API-register-filesystem"> 9193<refentryinfo> 9194 <title>LINUX</title> 9195 <productname>Kernel Hackers Manual</productname> 9196 <date>July 2017</date> 9197</refentryinfo> 9198<refmeta> 9199 <refentrytitle><phrase>register_filesystem</phrase></refentrytitle> 9200 <manvolnum>9</manvolnum> 9201 <refmiscinfo class="version">4.1.27</refmiscinfo> 9202</refmeta> 9203<refnamediv> 9204 <refname>register_filesystem</refname> 9205 <refpurpose> 9206 register a new filesystem 9207 </refpurpose> 9208</refnamediv> 9209<refsynopsisdiv> 9210 <title>Synopsis</title> 9211 <funcsynopsis><funcprototype> 9212 <funcdef>int <function>register_filesystem </function></funcdef> 9213 <paramdef>struct file_system_type * <parameter>fs</parameter></paramdef> 9214 </funcprototype></funcsynopsis> 9215</refsynopsisdiv> 9216<refsect1> 9217 <title>Arguments</title> 9218 <variablelist> 9219 <varlistentry> 9220 <term><parameter>fs</parameter></term> 9221 <listitem> 9222 <para> 9223 the file system structure 9224 </para> 9225 </listitem> 9226 </varlistentry> 9227 </variablelist> 9228</refsect1> 9229<refsect1> 9230<title>Description</title> 9231<para> 9232 Adds the file system passed to the list of file systems the kernel 9233 is aware of for mount and other syscalls. Returns 0 on success, 9234 or a negative errno code on an error. 9235 </para><para> 9236 9237 The <structname>struct file_system_type</structname> that is passed is linked into the kernel 9238 structures and must not be freed until the file system has been 9239 unregistered. 9240</para> 9241</refsect1> 9242</refentry> 9243 9244<refentry id="API-unregister-filesystem"> 9245<refentryinfo> 9246 <title>LINUX</title> 9247 <productname>Kernel Hackers Manual</productname> 9248 <date>July 2017</date> 9249</refentryinfo> 9250<refmeta> 9251 <refentrytitle><phrase>unregister_filesystem</phrase></refentrytitle> 9252 <manvolnum>9</manvolnum> 9253 <refmiscinfo class="version">4.1.27</refmiscinfo> 9254</refmeta> 9255<refnamediv> 9256 <refname>unregister_filesystem</refname> 9257 <refpurpose> 9258 unregister a file system 9259 </refpurpose> 9260</refnamediv> 9261<refsynopsisdiv> 9262 <title>Synopsis</title> 9263 <funcsynopsis><funcprototype> 9264 <funcdef>int <function>unregister_filesystem </function></funcdef> 9265 <paramdef>struct file_system_type * <parameter>fs</parameter></paramdef> 9266 </funcprototype></funcsynopsis> 9267</refsynopsisdiv> 9268<refsect1> 9269 <title>Arguments</title> 9270 <variablelist> 9271 <varlistentry> 9272 <term><parameter>fs</parameter></term> 9273 <listitem> 9274 <para> 9275 filesystem to unregister 9276 </para> 9277 </listitem> 9278 </varlistentry> 9279 </variablelist> 9280</refsect1> 9281<refsect1> 9282<title>Description</title> 9283<para> 9284 Remove a file system that was previously successfully registered 9285 with the kernel. An error is returned if the file system is not found. 9286 Zero is returned on a success. 9287 </para><para> 9288 9289 Once this function has returned the <structname>struct file_system_type</structname> structure 9290 may be freed or reused. 9291</para> 9292</refsect1> 9293</refentry> 9294 9295<!-- fs/fs-writeback.c --> 9296<refentry id="API-writeback-in-progress"> 9297<refentryinfo> 9298 <title>LINUX</title> 9299 <productname>Kernel Hackers Manual</productname> 9300 <date>July 2017</date> 9301</refentryinfo> 9302<refmeta> 9303 <refentrytitle><phrase>writeback_in_progress</phrase></refentrytitle> 9304 <manvolnum>9</manvolnum> 9305 <refmiscinfo class="version">4.1.27</refmiscinfo> 9306</refmeta> 9307<refnamediv> 9308 <refname>writeback_in_progress</refname> 9309 <refpurpose> 9310 determine whether there is writeback in progress 9311 </refpurpose> 9312</refnamediv> 9313<refsynopsisdiv> 9314 <title>Synopsis</title> 9315 <funcsynopsis><funcprototype> 9316 <funcdef>int <function>writeback_in_progress </function></funcdef> 9317 <paramdef>struct backing_dev_info * <parameter>bdi</parameter></paramdef> 9318 </funcprototype></funcsynopsis> 9319</refsynopsisdiv> 9320<refsect1> 9321 <title>Arguments</title> 9322 <variablelist> 9323 <varlistentry> 9324 <term><parameter>bdi</parameter></term> 9325 <listitem> 9326 <para> 9327 the device's backing_dev_info structure. 9328 </para> 9329 </listitem> 9330 </varlistentry> 9331 </variablelist> 9332</refsect1> 9333<refsect1> 9334<title>Description</title> 9335<para> 9336 Determine whether there is writeback waiting to be handled against a 9337 backing device. 9338</para> 9339</refsect1> 9340</refentry> 9341 9342<refentry id="API-writeback-inodes-sb-nr"> 9343<refentryinfo> 9344 <title>LINUX</title> 9345 <productname>Kernel Hackers Manual</productname> 9346 <date>July 2017</date> 9347</refentryinfo> 9348<refmeta> 9349 <refentrytitle><phrase>writeback_inodes_sb_nr</phrase></refentrytitle> 9350 <manvolnum>9</manvolnum> 9351 <refmiscinfo class="version">4.1.27</refmiscinfo> 9352</refmeta> 9353<refnamediv> 9354 <refname>writeback_inodes_sb_nr</refname> 9355 <refpurpose> 9356 writeback dirty inodes from given super_block 9357 </refpurpose> 9358</refnamediv> 9359<refsynopsisdiv> 9360 <title>Synopsis</title> 9361 <funcsynopsis><funcprototype> 9362 <funcdef>void <function>writeback_inodes_sb_nr </function></funcdef> 9363 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9364 <paramdef>unsigned long <parameter>nr</parameter></paramdef> 9365 <paramdef>enum wb_reason <parameter>reason</parameter></paramdef> 9366 </funcprototype></funcsynopsis> 9367</refsynopsisdiv> 9368<refsect1> 9369 <title>Arguments</title> 9370 <variablelist> 9371 <varlistentry> 9372 <term><parameter>sb</parameter></term> 9373 <listitem> 9374 <para> 9375 the superblock 9376 </para> 9377 </listitem> 9378 </varlistentry> 9379 <varlistentry> 9380 <term><parameter>nr</parameter></term> 9381 <listitem> 9382 <para> 9383 the number of pages to write 9384 </para> 9385 </listitem> 9386 </varlistentry> 9387 <varlistentry> 9388 <term><parameter>reason</parameter></term> 9389 <listitem> 9390 <para> 9391 reason why some writeback work initiated 9392 </para> 9393 </listitem> 9394 </varlistentry> 9395 </variablelist> 9396</refsect1> 9397<refsect1> 9398<title>Description</title> 9399<para> 9400 Start writeback on some inodes on this super_block. No guarantees are made 9401 on how many (if any) will be written, and this function does not wait 9402 for IO completion of submitted IO. 9403</para> 9404</refsect1> 9405</refentry> 9406 9407<refentry id="API-writeback-inodes-sb"> 9408<refentryinfo> 9409 <title>LINUX</title> 9410 <productname>Kernel Hackers Manual</productname> 9411 <date>July 2017</date> 9412</refentryinfo> 9413<refmeta> 9414 <refentrytitle><phrase>writeback_inodes_sb</phrase></refentrytitle> 9415 <manvolnum>9</manvolnum> 9416 <refmiscinfo class="version">4.1.27</refmiscinfo> 9417</refmeta> 9418<refnamediv> 9419 <refname>writeback_inodes_sb</refname> 9420 <refpurpose> 9421 writeback dirty inodes from given super_block 9422 </refpurpose> 9423</refnamediv> 9424<refsynopsisdiv> 9425 <title>Synopsis</title> 9426 <funcsynopsis><funcprototype> 9427 <funcdef>void <function>writeback_inodes_sb </function></funcdef> 9428 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9429 <paramdef>enum wb_reason <parameter>reason</parameter></paramdef> 9430 </funcprototype></funcsynopsis> 9431</refsynopsisdiv> 9432<refsect1> 9433 <title>Arguments</title> 9434 <variablelist> 9435 <varlistentry> 9436 <term><parameter>sb</parameter></term> 9437 <listitem> 9438 <para> 9439 the superblock 9440 </para> 9441 </listitem> 9442 </varlistentry> 9443 <varlistentry> 9444 <term><parameter>reason</parameter></term> 9445 <listitem> 9446 <para> 9447 reason why some writeback work was initiated 9448 </para> 9449 </listitem> 9450 </varlistentry> 9451 </variablelist> 9452</refsect1> 9453<refsect1> 9454<title>Description</title> 9455<para> 9456 Start writeback on some inodes on this super_block. No guarantees are made 9457 on how many (if any) will be written, and this function does not wait 9458 for IO completion of submitted IO. 9459</para> 9460</refsect1> 9461</refentry> 9462 9463<refentry id="API-try-to-writeback-inodes-sb-nr"> 9464<refentryinfo> 9465 <title>LINUX</title> 9466 <productname>Kernel Hackers Manual</productname> 9467 <date>July 2017</date> 9468</refentryinfo> 9469<refmeta> 9470 <refentrytitle><phrase>try_to_writeback_inodes_sb_nr</phrase></refentrytitle> 9471 <manvolnum>9</manvolnum> 9472 <refmiscinfo class="version">4.1.27</refmiscinfo> 9473</refmeta> 9474<refnamediv> 9475 <refname>try_to_writeback_inodes_sb_nr</refname> 9476 <refpurpose> 9477 try to start writeback if none underway 9478 </refpurpose> 9479</refnamediv> 9480<refsynopsisdiv> 9481 <title>Synopsis</title> 9482 <funcsynopsis><funcprototype> 9483 <funcdef>int <function>try_to_writeback_inodes_sb_nr </function></funcdef> 9484 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9485 <paramdef>unsigned long <parameter>nr</parameter></paramdef> 9486 <paramdef>enum wb_reason <parameter>reason</parameter></paramdef> 9487 </funcprototype></funcsynopsis> 9488</refsynopsisdiv> 9489<refsect1> 9490 <title>Arguments</title> 9491 <variablelist> 9492 <varlistentry> 9493 <term><parameter>sb</parameter></term> 9494 <listitem> 9495 <para> 9496 the superblock 9497 </para> 9498 </listitem> 9499 </varlistentry> 9500 <varlistentry> 9501 <term><parameter>nr</parameter></term> 9502 <listitem> 9503 <para> 9504 the number of pages to write 9505 </para> 9506 </listitem> 9507 </varlistentry> 9508 <varlistentry> 9509 <term><parameter>reason</parameter></term> 9510 <listitem> 9511 <para> 9512 the reason of writeback 9513 </para> 9514 </listitem> 9515 </varlistentry> 9516 </variablelist> 9517</refsect1> 9518<refsect1> 9519<title>Description</title> 9520<para> 9521 Invoke writeback_inodes_sb_nr if no writeback is currently underway. 9522 Returns 1 if writeback was started, 0 if not. 9523</para> 9524</refsect1> 9525</refentry> 9526 9527<refentry id="API-try-to-writeback-inodes-sb"> 9528<refentryinfo> 9529 <title>LINUX</title> 9530 <productname>Kernel Hackers Manual</productname> 9531 <date>July 2017</date> 9532</refentryinfo> 9533<refmeta> 9534 <refentrytitle><phrase>try_to_writeback_inodes_sb</phrase></refentrytitle> 9535 <manvolnum>9</manvolnum> 9536 <refmiscinfo class="version">4.1.27</refmiscinfo> 9537</refmeta> 9538<refnamediv> 9539 <refname>try_to_writeback_inodes_sb</refname> 9540 <refpurpose> 9541 try to start writeback if none underway 9542 </refpurpose> 9543</refnamediv> 9544<refsynopsisdiv> 9545 <title>Synopsis</title> 9546 <funcsynopsis><funcprototype> 9547 <funcdef>int <function>try_to_writeback_inodes_sb </function></funcdef> 9548 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9549 <paramdef>enum wb_reason <parameter>reason</parameter></paramdef> 9550 </funcprototype></funcsynopsis> 9551</refsynopsisdiv> 9552<refsect1> 9553 <title>Arguments</title> 9554 <variablelist> 9555 <varlistentry> 9556 <term><parameter>sb</parameter></term> 9557 <listitem> 9558 <para> 9559 the superblock 9560 </para> 9561 </listitem> 9562 </varlistentry> 9563 <varlistentry> 9564 <term><parameter>reason</parameter></term> 9565 <listitem> 9566 <para> 9567 reason why some writeback work was initiated 9568 </para> 9569 </listitem> 9570 </varlistentry> 9571 </variablelist> 9572</refsect1> 9573<refsect1> 9574<title>Description</title> 9575<para> 9576 Implement by <function>try_to_writeback_inodes_sb_nr</function> 9577 Returns 1 if writeback was started, 0 if not. 9578</para> 9579</refsect1> 9580</refentry> 9581 9582<refentry id="API-sync-inodes-sb"> 9583<refentryinfo> 9584 <title>LINUX</title> 9585 <productname>Kernel Hackers Manual</productname> 9586 <date>July 2017</date> 9587</refentryinfo> 9588<refmeta> 9589 <refentrytitle><phrase>sync_inodes_sb</phrase></refentrytitle> 9590 <manvolnum>9</manvolnum> 9591 <refmiscinfo class="version">4.1.27</refmiscinfo> 9592</refmeta> 9593<refnamediv> 9594 <refname>sync_inodes_sb</refname> 9595 <refpurpose> 9596 sync sb inode pages 9597 </refpurpose> 9598</refnamediv> 9599<refsynopsisdiv> 9600 <title>Synopsis</title> 9601 <funcsynopsis><funcprototype> 9602 <funcdef>void <function>sync_inodes_sb </function></funcdef> 9603 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9604 </funcprototype></funcsynopsis> 9605</refsynopsisdiv> 9606<refsect1> 9607 <title>Arguments</title> 9608 <variablelist> 9609 <varlistentry> 9610 <term><parameter>sb</parameter></term> 9611 <listitem> 9612 <para> 9613 the superblock 9614 </para> 9615 </listitem> 9616 </varlistentry> 9617 </variablelist> 9618</refsect1> 9619<refsect1> 9620<title>Description</title> 9621<para> 9622 This function writes and waits on any dirty inode belonging to this 9623 super_block. 9624</para> 9625</refsect1> 9626</refentry> 9627 9628<refentry id="API-write-inode-now"> 9629<refentryinfo> 9630 <title>LINUX</title> 9631 <productname>Kernel Hackers Manual</productname> 9632 <date>July 2017</date> 9633</refentryinfo> 9634<refmeta> 9635 <refentrytitle><phrase>write_inode_now</phrase></refentrytitle> 9636 <manvolnum>9</manvolnum> 9637 <refmiscinfo class="version">4.1.27</refmiscinfo> 9638</refmeta> 9639<refnamediv> 9640 <refname>write_inode_now</refname> 9641 <refpurpose> 9642 write an inode to disk 9643 </refpurpose> 9644</refnamediv> 9645<refsynopsisdiv> 9646 <title>Synopsis</title> 9647 <funcsynopsis><funcprototype> 9648 <funcdef>int <function>write_inode_now </function></funcdef> 9649 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 9650 <paramdef>int <parameter>sync</parameter></paramdef> 9651 </funcprototype></funcsynopsis> 9652</refsynopsisdiv> 9653<refsect1> 9654 <title>Arguments</title> 9655 <variablelist> 9656 <varlistentry> 9657 <term><parameter>inode</parameter></term> 9658 <listitem> 9659 <para> 9660 inode to write to disk 9661 </para> 9662 </listitem> 9663 </varlistentry> 9664 <varlistentry> 9665 <term><parameter>sync</parameter></term> 9666 <listitem> 9667 <para> 9668 whether the write should be synchronous or not 9669 </para> 9670 </listitem> 9671 </varlistentry> 9672 </variablelist> 9673</refsect1> 9674<refsect1> 9675<title>Description</title> 9676<para> 9677 This function commits an inode to disk immediately if it is dirty. This is 9678 primarily needed by knfsd. 9679 </para><para> 9680 9681 The caller must either have a ref on the inode or must have set I_WILL_FREE. 9682</para> 9683</refsect1> 9684</refentry> 9685 9686<refentry id="API-sync-inode"> 9687<refentryinfo> 9688 <title>LINUX</title> 9689 <productname>Kernel Hackers Manual</productname> 9690 <date>July 2017</date> 9691</refentryinfo> 9692<refmeta> 9693 <refentrytitle><phrase>sync_inode</phrase></refentrytitle> 9694 <manvolnum>9</manvolnum> 9695 <refmiscinfo class="version">4.1.27</refmiscinfo> 9696</refmeta> 9697<refnamediv> 9698 <refname>sync_inode</refname> 9699 <refpurpose> 9700 write an inode and its pages to disk. 9701 </refpurpose> 9702</refnamediv> 9703<refsynopsisdiv> 9704 <title>Synopsis</title> 9705 <funcsynopsis><funcprototype> 9706 <funcdef>int <function>sync_inode </function></funcdef> 9707 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 9708 <paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef> 9709 </funcprototype></funcsynopsis> 9710</refsynopsisdiv> 9711<refsect1> 9712 <title>Arguments</title> 9713 <variablelist> 9714 <varlistentry> 9715 <term><parameter>inode</parameter></term> 9716 <listitem> 9717 <para> 9718 the inode to sync 9719 </para> 9720 </listitem> 9721 </varlistentry> 9722 <varlistentry> 9723 <term><parameter>wbc</parameter></term> 9724 <listitem> 9725 <para> 9726 controls the writeback mode 9727 </para> 9728 </listitem> 9729 </varlistentry> 9730 </variablelist> 9731</refsect1> 9732<refsect1> 9733<title>Description</title> 9734<para> 9735 <function>sync_inode</function> will write an inode and its pages to disk. It will also 9736 correctly update the inode on its superblock's dirty inode lists and will 9737 update inode->i_state. 9738 </para><para> 9739 9740 The caller must have a ref on the inode. 9741</para> 9742</refsect1> 9743</refentry> 9744 9745<refentry id="API-sync-inode-metadata"> 9746<refentryinfo> 9747 <title>LINUX</title> 9748 <productname>Kernel Hackers Manual</productname> 9749 <date>July 2017</date> 9750</refentryinfo> 9751<refmeta> 9752 <refentrytitle><phrase>sync_inode_metadata</phrase></refentrytitle> 9753 <manvolnum>9</manvolnum> 9754 <refmiscinfo class="version">4.1.27</refmiscinfo> 9755</refmeta> 9756<refnamediv> 9757 <refname>sync_inode_metadata</refname> 9758 <refpurpose> 9759 write an inode to disk 9760 </refpurpose> 9761</refnamediv> 9762<refsynopsisdiv> 9763 <title>Synopsis</title> 9764 <funcsynopsis><funcprototype> 9765 <funcdef>int <function>sync_inode_metadata </function></funcdef> 9766 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 9767 <paramdef>int <parameter>wait</parameter></paramdef> 9768 </funcprototype></funcsynopsis> 9769</refsynopsisdiv> 9770<refsect1> 9771 <title>Arguments</title> 9772 <variablelist> 9773 <varlistentry> 9774 <term><parameter>inode</parameter></term> 9775 <listitem> 9776 <para> 9777 the inode to sync 9778 </para> 9779 </listitem> 9780 </varlistentry> 9781 <varlistentry> 9782 <term><parameter>wait</parameter></term> 9783 <listitem> 9784 <para> 9785 wait for I/O to complete. 9786 </para> 9787 </listitem> 9788 </varlistentry> 9789 </variablelist> 9790</refsect1> 9791<refsect1> 9792<title>Description</title> 9793<para> 9794 Write an inode to disk and adjust its dirty state after completion. 9795</para> 9796</refsect1> 9797<refsect1> 9798<title>Note</title> 9799<para> 9800 only writes the actual inode, no associated data or other metadata. 9801</para> 9802</refsect1> 9803</refentry> 9804 9805<!-- fs/block_dev.c --> 9806<refentry id="API-freeze-bdev"> 9807<refentryinfo> 9808 <title>LINUX</title> 9809 <productname>Kernel Hackers Manual</productname> 9810 <date>July 2017</date> 9811</refentryinfo> 9812<refmeta> 9813 <refentrytitle><phrase>freeze_bdev</phrase></refentrytitle> 9814 <manvolnum>9</manvolnum> 9815 <refmiscinfo class="version">4.1.27</refmiscinfo> 9816</refmeta> 9817<refnamediv> 9818 <refname>freeze_bdev</refname> 9819 <refpurpose> 9820 - lock a filesystem and force it into a consistent state 9821 </refpurpose> 9822</refnamediv> 9823<refsynopsisdiv> 9824 <title>Synopsis</title> 9825 <funcsynopsis><funcprototype> 9826 <funcdef>struct super_block * <function>freeze_bdev </function></funcdef> 9827 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 9828 </funcprototype></funcsynopsis> 9829</refsynopsisdiv> 9830<refsect1> 9831 <title>Arguments</title> 9832 <variablelist> 9833 <varlistentry> 9834 <term><parameter>bdev</parameter></term> 9835 <listitem> 9836 <para> 9837 blockdevice to lock 9838 </para> 9839 </listitem> 9840 </varlistentry> 9841 </variablelist> 9842</refsect1> 9843<refsect1> 9844<title>Description</title> 9845<para> 9846 If a superblock is found on this device, we take the s_umount semaphore 9847 on it to make sure nobody unmounts until the snapshot creation is done. 9848 The reference counter (bd_fsfreeze_count) guarantees that only the last 9849 unfreeze process can unfreeze the frozen filesystem actually when multiple 9850 freeze requests arrive simultaneously. It counts up in <function>freeze_bdev</function> and 9851 count down in <function>thaw_bdev</function>. When it becomes 0, <function>thaw_bdev</function> will unfreeze 9852 actually. 9853</para> 9854</refsect1> 9855</refentry> 9856 9857<refentry id="API-thaw-bdev"> 9858<refentryinfo> 9859 <title>LINUX</title> 9860 <productname>Kernel Hackers Manual</productname> 9861 <date>July 2017</date> 9862</refentryinfo> 9863<refmeta> 9864 <refentrytitle><phrase>thaw_bdev</phrase></refentrytitle> 9865 <manvolnum>9</manvolnum> 9866 <refmiscinfo class="version">4.1.27</refmiscinfo> 9867</refmeta> 9868<refnamediv> 9869 <refname>thaw_bdev</refname> 9870 <refpurpose> 9871 - unlock filesystem 9872 </refpurpose> 9873</refnamediv> 9874<refsynopsisdiv> 9875 <title>Synopsis</title> 9876 <funcsynopsis><funcprototype> 9877 <funcdef>int <function>thaw_bdev </function></funcdef> 9878 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 9879 <paramdef>struct super_block * <parameter>sb</parameter></paramdef> 9880 </funcprototype></funcsynopsis> 9881</refsynopsisdiv> 9882<refsect1> 9883 <title>Arguments</title> 9884 <variablelist> 9885 <varlistentry> 9886 <term><parameter>bdev</parameter></term> 9887 <listitem> 9888 <para> 9889 blockdevice to unlock 9890 </para> 9891 </listitem> 9892 </varlistentry> 9893 <varlistentry> 9894 <term><parameter>sb</parameter></term> 9895 <listitem> 9896 <para> 9897 associated superblock 9898 </para> 9899 </listitem> 9900 </varlistentry> 9901 </variablelist> 9902</refsect1> 9903<refsect1> 9904<title>Description</title> 9905<para> 9906 Unlocks the filesystem and marks it writeable again after <function>freeze_bdev</function>. 9907</para> 9908</refsect1> 9909</refentry> 9910 9911<refentry id="API-bdev-read-page"> 9912<refentryinfo> 9913 <title>LINUX</title> 9914 <productname>Kernel Hackers Manual</productname> 9915 <date>July 2017</date> 9916</refentryinfo> 9917<refmeta> 9918 <refentrytitle><phrase>bdev_read_page</phrase></refentrytitle> 9919 <manvolnum>9</manvolnum> 9920 <refmiscinfo class="version">4.1.27</refmiscinfo> 9921</refmeta> 9922<refnamediv> 9923 <refname>bdev_read_page</refname> 9924 <refpurpose> 9925 Start reading a page from a block device 9926 </refpurpose> 9927</refnamediv> 9928<refsynopsisdiv> 9929 <title>Synopsis</title> 9930 <funcsynopsis><funcprototype> 9931 <funcdef>int <function>bdev_read_page </function></funcdef> 9932 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 9933 <paramdef>sector_t <parameter>sector</parameter></paramdef> 9934 <paramdef>struct page * <parameter>page</parameter></paramdef> 9935 </funcprototype></funcsynopsis> 9936</refsynopsisdiv> 9937<refsect1> 9938 <title>Arguments</title> 9939 <variablelist> 9940 <varlistentry> 9941 <term><parameter>bdev</parameter></term> 9942 <listitem> 9943 <para> 9944 The device to read the page from 9945 </para> 9946 </listitem> 9947 </varlistentry> 9948 <varlistentry> 9949 <term><parameter>sector</parameter></term> 9950 <listitem> 9951 <para> 9952 The offset on the device to read the page to (need not be aligned) 9953 </para> 9954 </listitem> 9955 </varlistentry> 9956 <varlistentry> 9957 <term><parameter>page</parameter></term> 9958 <listitem> 9959 <para> 9960 The page to read 9961 </para> 9962 </listitem> 9963 </varlistentry> 9964 </variablelist> 9965</refsect1> 9966<refsect1> 9967<title>Description</title> 9968<para> 9969 On entry, the page should be locked. It will be unlocked when the page 9970 has been read. If the block driver implements rw_page synchronously, 9971 that will be true on exit from this function, but it need not be. 9972 </para><para> 9973 9974 Errors returned by this function are usually <quote>soft</quote>, eg out of memory, or 9975 queue full; callers should try a different route to read this page rather 9976 than propagate an error back up the stack. 9977</para> 9978</refsect1> 9979<refsect1> 9980<title>Return</title> 9981<para> 9982 negative errno if an error occurs, 0 if submission was successful. 9983</para> 9984</refsect1> 9985</refentry> 9986 9987<refentry id="API-bdev-write-page"> 9988<refentryinfo> 9989 <title>LINUX</title> 9990 <productname>Kernel Hackers Manual</productname> 9991 <date>July 2017</date> 9992</refentryinfo> 9993<refmeta> 9994 <refentrytitle><phrase>bdev_write_page</phrase></refentrytitle> 9995 <manvolnum>9</manvolnum> 9996 <refmiscinfo class="version">4.1.27</refmiscinfo> 9997</refmeta> 9998<refnamediv> 9999 <refname>bdev_write_page</refname> 10000 <refpurpose> 10001 Start writing a page to a block device 10002 </refpurpose> 10003</refnamediv> 10004<refsynopsisdiv> 10005 <title>Synopsis</title> 10006 <funcsynopsis><funcprototype> 10007 <funcdef>int <function>bdev_write_page </function></funcdef> 10008 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10009 <paramdef>sector_t <parameter>sector</parameter></paramdef> 10010 <paramdef>struct page * <parameter>page</parameter></paramdef> 10011 <paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef> 10012 </funcprototype></funcsynopsis> 10013</refsynopsisdiv> 10014<refsect1> 10015 <title>Arguments</title> 10016 <variablelist> 10017 <varlistentry> 10018 <term><parameter>bdev</parameter></term> 10019 <listitem> 10020 <para> 10021 The device to write the page to 10022 </para> 10023 </listitem> 10024 </varlistentry> 10025 <varlistentry> 10026 <term><parameter>sector</parameter></term> 10027 <listitem> 10028 <para> 10029 The offset on the device to write the page to (need not be aligned) 10030 </para> 10031 </listitem> 10032 </varlistentry> 10033 <varlistentry> 10034 <term><parameter>page</parameter></term> 10035 <listitem> 10036 <para> 10037 The page to write 10038 </para> 10039 </listitem> 10040 </varlistentry> 10041 <varlistentry> 10042 <term><parameter>wbc</parameter></term> 10043 <listitem> 10044 <para> 10045 The writeback_control for the write 10046 </para> 10047 </listitem> 10048 </varlistentry> 10049 </variablelist> 10050</refsect1> 10051<refsect1> 10052<title>Description</title> 10053<para> 10054 On entry, the page should be locked and not currently under writeback. 10055 On exit, if the write started successfully, the page will be unlocked and 10056 under writeback. If the write failed already (eg the driver failed to 10057 queue the page to the device), the page will still be locked. If the 10058 caller is a ->writepage implementation, it will need to unlock the page. 10059 </para><para> 10060 10061 Errors returned by this function are usually <quote>soft</quote>, eg out of memory, or 10062 queue full; callers should try a different route to write this page rather 10063 than propagate an error back up the stack. 10064</para> 10065</refsect1> 10066<refsect1> 10067<title>Return</title> 10068<para> 10069 negative errno if an error occurs, 0 if submission was successful. 10070</para> 10071</refsect1> 10072</refentry> 10073 10074<refentry id="API-bdev-direct-access"> 10075<refentryinfo> 10076 <title>LINUX</title> 10077 <productname>Kernel Hackers Manual</productname> 10078 <date>July 2017</date> 10079</refentryinfo> 10080<refmeta> 10081 <refentrytitle><phrase>bdev_direct_access</phrase></refentrytitle> 10082 <manvolnum>9</manvolnum> 10083 <refmiscinfo class="version">4.1.27</refmiscinfo> 10084</refmeta> 10085<refnamediv> 10086 <refname>bdev_direct_access</refname> 10087 <refpurpose> 10088 Get the address for directly-accessibly memory 10089 </refpurpose> 10090</refnamediv> 10091<refsynopsisdiv> 10092 <title>Synopsis</title> 10093 <funcsynopsis><funcprototype> 10094 <funcdef>long <function>bdev_direct_access </function></funcdef> 10095 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10096 <paramdef>sector_t <parameter>sector</parameter></paramdef> 10097 <paramdef>void ** <parameter>addr</parameter></paramdef> 10098 <paramdef>unsigned long * <parameter>pfn</parameter></paramdef> 10099 <paramdef>long <parameter>size</parameter></paramdef> 10100 </funcprototype></funcsynopsis> 10101</refsynopsisdiv> 10102<refsect1> 10103 <title>Arguments</title> 10104 <variablelist> 10105 <varlistentry> 10106 <term><parameter>bdev</parameter></term> 10107 <listitem> 10108 <para> 10109 The device containing the memory 10110 </para> 10111 </listitem> 10112 </varlistentry> 10113 <varlistentry> 10114 <term><parameter>sector</parameter></term> 10115 <listitem> 10116 <para> 10117 The offset within the device 10118 </para> 10119 </listitem> 10120 </varlistentry> 10121 <varlistentry> 10122 <term><parameter>addr</parameter></term> 10123 <listitem> 10124 <para> 10125 Where to put the address of the memory 10126 </para> 10127 </listitem> 10128 </varlistentry> 10129 <varlistentry> 10130 <term><parameter>pfn</parameter></term> 10131 <listitem> 10132 <para> 10133 The Page Frame Number for the memory 10134 </para> 10135 </listitem> 10136 </varlistentry> 10137 <varlistentry> 10138 <term><parameter>size</parameter></term> 10139 <listitem> 10140 <para> 10141 The number of bytes requested 10142 </para> 10143 </listitem> 10144 </varlistentry> 10145 </variablelist> 10146</refsect1> 10147<refsect1> 10148<title>Description</title> 10149<para> 10150 If a block device is made up of directly addressable memory, this function 10151 will tell the caller the PFN and the address of the memory. The address 10152 may be directly dereferenced within the kernel without the need to call 10153 <function>ioremap</function>, <function>kmap</function> or similar. The PFN is suitable for inserting into 10154 page tables. 10155</para> 10156</refsect1> 10157<refsect1> 10158<title>Return</title> 10159<para> 10160 negative errno if an error occurs, otherwise the number of bytes 10161 accessible at this address. 10162</para> 10163</refsect1> 10164</refentry> 10165 10166<refentry id="API-bdgrab"> 10167<refentryinfo> 10168 <title>LINUX</title> 10169 <productname>Kernel Hackers Manual</productname> 10170 <date>July 2017</date> 10171</refentryinfo> 10172<refmeta> 10173 <refentrytitle><phrase>bdgrab</phrase></refentrytitle> 10174 <manvolnum>9</manvolnum> 10175 <refmiscinfo class="version">4.1.27</refmiscinfo> 10176</refmeta> 10177<refnamediv> 10178 <refname>bdgrab</refname> 10179 <refpurpose> 10180 - Grab a reference to an already referenced block device 10181 </refpurpose> 10182</refnamediv> 10183<refsynopsisdiv> 10184 <title>Synopsis</title> 10185 <funcsynopsis><funcprototype> 10186 <funcdef>struct block_device * <function>bdgrab </function></funcdef> 10187 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10188 </funcprototype></funcsynopsis> 10189</refsynopsisdiv> 10190<refsect1> 10191 <title>Arguments</title> 10192 <variablelist> 10193 <varlistentry> 10194 <term><parameter>bdev</parameter></term> 10195 <listitem> 10196 <para> 10197 Block device to grab a reference to. 10198 </para> 10199 </listitem> 10200 </varlistentry> 10201 </variablelist> 10202</refsect1> 10203</refentry> 10204 10205<refentry id="API-bd-link-disk-holder"> 10206<refentryinfo> 10207 <title>LINUX</title> 10208 <productname>Kernel Hackers Manual</productname> 10209 <date>July 2017</date> 10210</refentryinfo> 10211<refmeta> 10212 <refentrytitle><phrase>bd_link_disk_holder</phrase></refentrytitle> 10213 <manvolnum>9</manvolnum> 10214 <refmiscinfo class="version">4.1.27</refmiscinfo> 10215</refmeta> 10216<refnamediv> 10217 <refname>bd_link_disk_holder</refname> 10218 <refpurpose> 10219 create symlinks between holding disk and slave bdev 10220 </refpurpose> 10221</refnamediv> 10222<refsynopsisdiv> 10223 <title>Synopsis</title> 10224 <funcsynopsis><funcprototype> 10225 <funcdef>int <function>bd_link_disk_holder </function></funcdef> 10226 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10227 <paramdef>struct gendisk * <parameter>disk</parameter></paramdef> 10228 </funcprototype></funcsynopsis> 10229</refsynopsisdiv> 10230<refsect1> 10231 <title>Arguments</title> 10232 <variablelist> 10233 <varlistentry> 10234 <term><parameter>bdev</parameter></term> 10235 <listitem> 10236 <para> 10237 the claimed slave bdev 10238 </para> 10239 </listitem> 10240 </varlistentry> 10241 <varlistentry> 10242 <term><parameter>disk</parameter></term> 10243 <listitem> 10244 <para> 10245 the holding disk 10246 </para> 10247 </listitem> 10248 </varlistentry> 10249 </variablelist> 10250</refsect1> 10251<refsect1> 10252<title>Description</title> 10253<para> 10254 DON'T USE THIS UNLESS YOU'RE ALREADY USING IT. 10255 </para><para> 10256 10257 This functions creates the following sysfs symlinks. 10258 </para><para> 10259 10260 - from <quote>slaves</quote> directory of the holder <parameter>disk</parameter> to the claimed <parameter>bdev</parameter> 10261 - from <quote>holders</quote> directory of the <parameter>bdev</parameter> to the holder <parameter>disk</parameter> 10262 </para><para> 10263 10264 For example, if /dev/dm-0 maps to /dev/sda and disk for dm-0 is 10265 passed to <function>bd_link_disk_holder</function>, then: 10266 </para><para> 10267 10268 /sys/block/dm-0/slaves/sda --> /sys/block/sda 10269 /sys/block/sda/holders/dm-0 --> /sys/block/dm-0 10270 </para><para> 10271 10272 The caller must have claimed <parameter>bdev</parameter> before calling this function and 10273 ensure that both <parameter>bdev</parameter> and <parameter>disk</parameter> are valid during the creation and 10274 lifetime of these symlinks. 10275</para> 10276</refsect1> 10277<refsect1> 10278<title>CONTEXT</title> 10279<para> 10280 Might sleep. 10281</para> 10282</refsect1> 10283<refsect1> 10284<title>RETURNS</title> 10285<para> 10286 0 on success, -errno on failure. 10287</para> 10288</refsect1> 10289</refentry> 10290 10291<refentry id="API-bd-unlink-disk-holder"> 10292<refentryinfo> 10293 <title>LINUX</title> 10294 <productname>Kernel Hackers Manual</productname> 10295 <date>July 2017</date> 10296</refentryinfo> 10297<refmeta> 10298 <refentrytitle><phrase>bd_unlink_disk_holder</phrase></refentrytitle> 10299 <manvolnum>9</manvolnum> 10300 <refmiscinfo class="version">4.1.27</refmiscinfo> 10301</refmeta> 10302<refnamediv> 10303 <refname>bd_unlink_disk_holder</refname> 10304 <refpurpose> 10305 destroy symlinks created by <function>bd_link_disk_holder</function> 10306 </refpurpose> 10307</refnamediv> 10308<refsynopsisdiv> 10309 <title>Synopsis</title> 10310 <funcsynopsis><funcprototype> 10311 <funcdef>void <function>bd_unlink_disk_holder </function></funcdef> 10312 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10313 <paramdef>struct gendisk * <parameter>disk</parameter></paramdef> 10314 </funcprototype></funcsynopsis> 10315</refsynopsisdiv> 10316<refsect1> 10317 <title>Arguments</title> 10318 <variablelist> 10319 <varlistentry> 10320 <term><parameter>bdev</parameter></term> 10321 <listitem> 10322 <para> 10323 the calimed slave bdev 10324 </para> 10325 </listitem> 10326 </varlistentry> 10327 <varlistentry> 10328 <term><parameter>disk</parameter></term> 10329 <listitem> 10330 <para> 10331 the holding disk 10332 </para> 10333 </listitem> 10334 </varlistentry> 10335 </variablelist> 10336</refsect1> 10337<refsect1> 10338<title>Description</title> 10339<para> 10340 DON'T USE THIS UNLESS YOU'RE ALREADY USING IT. 10341</para> 10342</refsect1> 10343<refsect1> 10344<title>CONTEXT</title> 10345<para> 10346 Might sleep. 10347</para> 10348</refsect1> 10349</refentry> 10350 10351<refentry id="API-check-disk-size-change"> 10352<refentryinfo> 10353 <title>LINUX</title> 10354 <productname>Kernel Hackers Manual</productname> 10355 <date>July 2017</date> 10356</refentryinfo> 10357<refmeta> 10358 <refentrytitle><phrase>check_disk_size_change</phrase></refentrytitle> 10359 <manvolnum>9</manvolnum> 10360 <refmiscinfo class="version">4.1.27</refmiscinfo> 10361</refmeta> 10362<refnamediv> 10363 <refname>check_disk_size_change</refname> 10364 <refpurpose> 10365 checks for disk size change and adjusts bdev size. 10366 </refpurpose> 10367</refnamediv> 10368<refsynopsisdiv> 10369 <title>Synopsis</title> 10370 <funcsynopsis><funcprototype> 10371 <funcdef>void <function>check_disk_size_change </function></funcdef> 10372 <paramdef>struct gendisk * <parameter>disk</parameter></paramdef> 10373 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10374 </funcprototype></funcsynopsis> 10375</refsynopsisdiv> 10376<refsect1> 10377 <title>Arguments</title> 10378 <variablelist> 10379 <varlistentry> 10380 <term><parameter>disk</parameter></term> 10381 <listitem> 10382 <para> 10383 struct gendisk to check 10384 </para> 10385 </listitem> 10386 </varlistentry> 10387 <varlistentry> 10388 <term><parameter>bdev</parameter></term> 10389 <listitem> 10390 <para> 10391 struct bdev to adjust. 10392 </para> 10393 </listitem> 10394 </varlistentry> 10395 </variablelist> 10396</refsect1> 10397<refsect1> 10398<title>Description</title> 10399<para> 10400 This routine checks to see if the bdev size does not match the disk size 10401 and adjusts it if it differs. 10402</para> 10403</refsect1> 10404</refentry> 10405 10406<refentry id="API-revalidate-disk"> 10407<refentryinfo> 10408 <title>LINUX</title> 10409 <productname>Kernel Hackers Manual</productname> 10410 <date>July 2017</date> 10411</refentryinfo> 10412<refmeta> 10413 <refentrytitle><phrase>revalidate_disk</phrase></refentrytitle> 10414 <manvolnum>9</manvolnum> 10415 <refmiscinfo class="version">4.1.27</refmiscinfo> 10416</refmeta> 10417<refnamediv> 10418 <refname>revalidate_disk</refname> 10419 <refpurpose> 10420 wrapper for lower-level driver's revalidate_disk call-back 10421 </refpurpose> 10422</refnamediv> 10423<refsynopsisdiv> 10424 <title>Synopsis</title> 10425 <funcsynopsis><funcprototype> 10426 <funcdef>int <function>revalidate_disk </function></funcdef> 10427 <paramdef>struct gendisk * <parameter>disk</parameter></paramdef> 10428 </funcprototype></funcsynopsis> 10429</refsynopsisdiv> 10430<refsect1> 10431 <title>Arguments</title> 10432 <variablelist> 10433 <varlistentry> 10434 <term><parameter>disk</parameter></term> 10435 <listitem> 10436 <para> 10437 struct gendisk to be revalidated 10438 </para> 10439 </listitem> 10440 </varlistentry> 10441 </variablelist> 10442</refsect1> 10443<refsect1> 10444<title>Description</title> 10445<para> 10446 This routine is a wrapper for lower-level driver's revalidate_disk 10447 call-backs. It is used to do common pre and post operations needed 10448 for all revalidate_disk operations. 10449</para> 10450</refsect1> 10451</refentry> 10452 10453<refentry id="API-blkdev-get"> 10454<refentryinfo> 10455 <title>LINUX</title> 10456 <productname>Kernel Hackers Manual</productname> 10457 <date>July 2017</date> 10458</refentryinfo> 10459<refmeta> 10460 <refentrytitle><phrase>blkdev_get</phrase></refentrytitle> 10461 <manvolnum>9</manvolnum> 10462 <refmiscinfo class="version">4.1.27</refmiscinfo> 10463</refmeta> 10464<refnamediv> 10465 <refname>blkdev_get</refname> 10466 <refpurpose> 10467 open a block device 10468 </refpurpose> 10469</refnamediv> 10470<refsynopsisdiv> 10471 <title>Synopsis</title> 10472 <funcsynopsis><funcprototype> 10473 <funcdef>int <function>blkdev_get </function></funcdef> 10474 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 10475 <paramdef>fmode_t <parameter>mode</parameter></paramdef> 10476 <paramdef>void * <parameter>holder</parameter></paramdef> 10477 </funcprototype></funcsynopsis> 10478</refsynopsisdiv> 10479<refsect1> 10480 <title>Arguments</title> 10481 <variablelist> 10482 <varlistentry> 10483 <term><parameter>bdev</parameter></term> 10484 <listitem> 10485 <para> 10486 block_device to open 10487 </para> 10488 </listitem> 10489 </varlistentry> 10490 <varlistentry> 10491 <term><parameter>mode</parameter></term> 10492 <listitem> 10493 <para> 10494 FMODE_* mask 10495 </para> 10496 </listitem> 10497 </varlistentry> 10498 <varlistentry> 10499 <term><parameter>holder</parameter></term> 10500 <listitem> 10501 <para> 10502 exclusive holder identifier 10503 </para> 10504 </listitem> 10505 </varlistentry> 10506 </variablelist> 10507</refsect1> 10508<refsect1> 10509<title>Description</title> 10510<para> 10511 Open <parameter>bdev</parameter> with <parameter>mode</parameter>. If <parameter>mode</parameter> includes <constant>FMODE_EXCL</constant>, <parameter>bdev</parameter> is 10512 open with exclusive access. Specifying <constant>FMODE_EXCL</constant> with <constant>NULL</constant> 10513 <parameter>holder</parameter> is invalid. Exclusive opens may nest for the same <parameter>holder</parameter>. 10514 </para><para> 10515 10516 On success, the reference count of <parameter>bdev</parameter> is unchanged. On failure, 10517 <parameter>bdev</parameter> is put. 10518</para> 10519</refsect1> 10520<refsect1> 10521<title>CONTEXT</title> 10522<para> 10523 Might sleep. 10524</para> 10525</refsect1> 10526<refsect1> 10527<title>RETURNS</title> 10528<para> 10529 0 on success, -errno on failure. 10530</para> 10531</refsect1> 10532</refentry> 10533 10534<refentry id="API-blkdev-get-by-path"> 10535<refentryinfo> 10536 <title>LINUX</title> 10537 <productname>Kernel Hackers Manual</productname> 10538 <date>July 2017</date> 10539</refentryinfo> 10540<refmeta> 10541 <refentrytitle><phrase>blkdev_get_by_path</phrase></refentrytitle> 10542 <manvolnum>9</manvolnum> 10543 <refmiscinfo class="version">4.1.27</refmiscinfo> 10544</refmeta> 10545<refnamediv> 10546 <refname>blkdev_get_by_path</refname> 10547 <refpurpose> 10548 open a block device by name 10549 </refpurpose> 10550</refnamediv> 10551<refsynopsisdiv> 10552 <title>Synopsis</title> 10553 <funcsynopsis><funcprototype> 10554 <funcdef>struct block_device * <function>blkdev_get_by_path </function></funcdef> 10555 <paramdef>const char * <parameter>path</parameter></paramdef> 10556 <paramdef>fmode_t <parameter>mode</parameter></paramdef> 10557 <paramdef>void * <parameter>holder</parameter></paramdef> 10558 </funcprototype></funcsynopsis> 10559</refsynopsisdiv> 10560<refsect1> 10561 <title>Arguments</title> 10562 <variablelist> 10563 <varlistentry> 10564 <term><parameter>path</parameter></term> 10565 <listitem> 10566 <para> 10567 path to the block device to open 10568 </para> 10569 </listitem> 10570 </varlistentry> 10571 <varlistentry> 10572 <term><parameter>mode</parameter></term> 10573 <listitem> 10574 <para> 10575 FMODE_* mask 10576 </para> 10577 </listitem> 10578 </varlistentry> 10579 <varlistentry> 10580 <term><parameter>holder</parameter></term> 10581 <listitem> 10582 <para> 10583 exclusive holder identifier 10584 </para> 10585 </listitem> 10586 </varlistentry> 10587 </variablelist> 10588</refsect1> 10589<refsect1> 10590<title>Description</title> 10591<para> 10592 Open the blockdevice described by the device file at <parameter>path</parameter>. <parameter>mode</parameter> 10593 and <parameter>holder</parameter> are identical to <function>blkdev_get</function>. 10594 </para><para> 10595 10596 On success, the returned block_device has reference count of one. 10597</para> 10598</refsect1> 10599<refsect1> 10600<title>CONTEXT</title> 10601<para> 10602 Might sleep. 10603</para> 10604</refsect1> 10605<refsect1> 10606<title>RETURNS</title> 10607<para> 10608 Pointer to block_device on success, ERR_PTR(-errno) on failure. 10609</para> 10610</refsect1> 10611</refentry> 10612 10613<refentry id="API-blkdev-get-by-dev"> 10614<refentryinfo> 10615 <title>LINUX</title> 10616 <productname>Kernel Hackers Manual</productname> 10617 <date>July 2017</date> 10618</refentryinfo> 10619<refmeta> 10620 <refentrytitle><phrase>blkdev_get_by_dev</phrase></refentrytitle> 10621 <manvolnum>9</manvolnum> 10622 <refmiscinfo class="version">4.1.27</refmiscinfo> 10623</refmeta> 10624<refnamediv> 10625 <refname>blkdev_get_by_dev</refname> 10626 <refpurpose> 10627 open a block device by device number 10628 </refpurpose> 10629</refnamediv> 10630<refsynopsisdiv> 10631 <title>Synopsis</title> 10632 <funcsynopsis><funcprototype> 10633 <funcdef>struct block_device * <function>blkdev_get_by_dev </function></funcdef> 10634 <paramdef>dev_t <parameter>dev</parameter></paramdef> 10635 <paramdef>fmode_t <parameter>mode</parameter></paramdef> 10636 <paramdef>void * <parameter>holder</parameter></paramdef> 10637 </funcprototype></funcsynopsis> 10638</refsynopsisdiv> 10639<refsect1> 10640 <title>Arguments</title> 10641 <variablelist> 10642 <varlistentry> 10643 <term><parameter>dev</parameter></term> 10644 <listitem> 10645 <para> 10646 device number of block device to open 10647 </para> 10648 </listitem> 10649 </varlistentry> 10650 <varlistentry> 10651 <term><parameter>mode</parameter></term> 10652 <listitem> 10653 <para> 10654 FMODE_* mask 10655 </para> 10656 </listitem> 10657 </varlistentry> 10658 <varlistentry> 10659 <term><parameter>holder</parameter></term> 10660 <listitem> 10661 <para> 10662 exclusive holder identifier 10663 </para> 10664 </listitem> 10665 </varlistentry> 10666 </variablelist> 10667</refsect1> 10668<refsect1> 10669<title>Description</title> 10670<para> 10671 Open the blockdevice described by device number <parameter>dev</parameter>. <parameter>mode</parameter> and 10672 <parameter>holder</parameter> are identical to <function>blkdev_get</function>. 10673 </para><para> 10674 10675 Use it ONLY if you really do not have anything better - i.e. when 10676 you are behind a truly sucky interface and all you are given is a 10677 device number. _Never_ to be used for internal purposes. If you 10678 ever need it - reconsider your API. 10679 </para><para> 10680 10681 On success, the returned block_device has reference count of one. 10682</para> 10683</refsect1> 10684<refsect1> 10685<title>CONTEXT</title> 10686<para> 10687 Might sleep. 10688</para> 10689</refsect1> 10690<refsect1> 10691<title>RETURNS</title> 10692<para> 10693 Pointer to block_device on success, ERR_PTR(-errno) on failure. 10694</para> 10695</refsect1> 10696</refentry> 10697 10698<refentry id="API-lookup-bdev"> 10699<refentryinfo> 10700 <title>LINUX</title> 10701 <productname>Kernel Hackers Manual</productname> 10702 <date>July 2017</date> 10703</refentryinfo> 10704<refmeta> 10705 <refentrytitle><phrase>lookup_bdev</phrase></refentrytitle> 10706 <manvolnum>9</manvolnum> 10707 <refmiscinfo class="version">4.1.27</refmiscinfo> 10708</refmeta> 10709<refnamediv> 10710 <refname>lookup_bdev</refname> 10711 <refpurpose> 10712 lookup a struct block_device by name 10713 </refpurpose> 10714</refnamediv> 10715<refsynopsisdiv> 10716 <title>Synopsis</title> 10717 <funcsynopsis><funcprototype> 10718 <funcdef>struct block_device * <function>lookup_bdev </function></funcdef> 10719 <paramdef>const char * <parameter>pathname</parameter></paramdef> 10720 </funcprototype></funcsynopsis> 10721</refsynopsisdiv> 10722<refsect1> 10723 <title>Arguments</title> 10724 <variablelist> 10725 <varlistentry> 10726 <term><parameter>pathname</parameter></term> 10727 <listitem> 10728 <para> 10729 special file representing the block device 10730 </para> 10731 </listitem> 10732 </varlistentry> 10733 </variablelist> 10734</refsect1> 10735<refsect1> 10736<title>Description</title> 10737<para> 10738 Get a reference to the blockdevice at <parameter>pathname</parameter> in the current 10739 namespace if possible and return it. Return ERR_PTR(error) 10740 otherwise. 10741</para> 10742</refsect1> 10743</refentry> 10744 10745 </sect1> 10746 </chapter> 10747 10748 <chapter id="proc"> 10749 <title>The proc filesystem</title> 10750 10751 <sect1 id="sysctl_interface"><title>sysctl interface</title> 10752<!-- kernel/sysctl.c --> 10753<refentry id="API-proc-dostring"> 10754<refentryinfo> 10755 <title>LINUX</title> 10756 <productname>Kernel Hackers Manual</productname> 10757 <date>July 2017</date> 10758</refentryinfo> 10759<refmeta> 10760 <refentrytitle><phrase>proc_dostring</phrase></refentrytitle> 10761 <manvolnum>9</manvolnum> 10762 <refmiscinfo class="version">4.1.27</refmiscinfo> 10763</refmeta> 10764<refnamediv> 10765 <refname>proc_dostring</refname> 10766 <refpurpose> 10767 read a string sysctl 10768 </refpurpose> 10769</refnamediv> 10770<refsynopsisdiv> 10771 <title>Synopsis</title> 10772 <funcsynopsis><funcprototype> 10773 <funcdef>int <function>proc_dostring </function></funcdef> 10774 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 10775 <paramdef>int <parameter>write</parameter></paramdef> 10776 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 10777 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 10778 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 10779 </funcprototype></funcsynopsis> 10780</refsynopsisdiv> 10781<refsect1> 10782 <title>Arguments</title> 10783 <variablelist> 10784 <varlistentry> 10785 <term><parameter>table</parameter></term> 10786 <listitem> 10787 <para> 10788 the sysctl table 10789 </para> 10790 </listitem> 10791 </varlistentry> 10792 <varlistentry> 10793 <term><parameter>write</parameter></term> 10794 <listitem> 10795 <para> 10796 <constant>TRUE</constant> if this is a write to the sysctl file 10797 </para> 10798 </listitem> 10799 </varlistentry> 10800 <varlistentry> 10801 <term><parameter>buffer</parameter></term> 10802 <listitem> 10803 <para> 10804 the user buffer 10805 </para> 10806 </listitem> 10807 </varlistentry> 10808 <varlistentry> 10809 <term><parameter>lenp</parameter></term> 10810 <listitem> 10811 <para> 10812 the size of the user buffer 10813 </para> 10814 </listitem> 10815 </varlistentry> 10816 <varlistentry> 10817 <term><parameter>ppos</parameter></term> 10818 <listitem> 10819 <para> 10820 file position 10821 </para> 10822 </listitem> 10823 </varlistentry> 10824 </variablelist> 10825</refsect1> 10826<refsect1> 10827<title>Description</title> 10828<para> 10829 Reads/writes a string from/to the user buffer. If the kernel 10830 buffer provided is not large enough to hold the string, the 10831 string is truncated. The copied string is <constant>NULL-terminated</constant>. 10832 If the string is being read by the user process, it is copied 10833 and a newline '\n' is added. It is truncated if the buffer is 10834 not large enough. 10835 </para><para> 10836 10837 Returns 0 on success. 10838</para> 10839</refsect1> 10840</refentry> 10841 10842<refentry id="API-proc-dointvec"> 10843<refentryinfo> 10844 <title>LINUX</title> 10845 <productname>Kernel Hackers Manual</productname> 10846 <date>July 2017</date> 10847</refentryinfo> 10848<refmeta> 10849 <refentrytitle><phrase>proc_dointvec</phrase></refentrytitle> 10850 <manvolnum>9</manvolnum> 10851 <refmiscinfo class="version">4.1.27</refmiscinfo> 10852</refmeta> 10853<refnamediv> 10854 <refname>proc_dointvec</refname> 10855 <refpurpose> 10856 read a vector of integers 10857 </refpurpose> 10858</refnamediv> 10859<refsynopsisdiv> 10860 <title>Synopsis</title> 10861 <funcsynopsis><funcprototype> 10862 <funcdef>int <function>proc_dointvec </function></funcdef> 10863 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 10864 <paramdef>int <parameter>write</parameter></paramdef> 10865 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 10866 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 10867 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 10868 </funcprototype></funcsynopsis> 10869</refsynopsisdiv> 10870<refsect1> 10871 <title>Arguments</title> 10872 <variablelist> 10873 <varlistentry> 10874 <term><parameter>table</parameter></term> 10875 <listitem> 10876 <para> 10877 the sysctl table 10878 </para> 10879 </listitem> 10880 </varlistentry> 10881 <varlistentry> 10882 <term><parameter>write</parameter></term> 10883 <listitem> 10884 <para> 10885 <constant>TRUE</constant> if this is a write to the sysctl file 10886 </para> 10887 </listitem> 10888 </varlistentry> 10889 <varlistentry> 10890 <term><parameter>buffer</parameter></term> 10891 <listitem> 10892 <para> 10893 the user buffer 10894 </para> 10895 </listitem> 10896 </varlistentry> 10897 <varlistentry> 10898 <term><parameter>lenp</parameter></term> 10899 <listitem> 10900 <para> 10901 the size of the user buffer 10902 </para> 10903 </listitem> 10904 </varlistentry> 10905 <varlistentry> 10906 <term><parameter>ppos</parameter></term> 10907 <listitem> 10908 <para> 10909 file position 10910 </para> 10911 </listitem> 10912 </varlistentry> 10913 </variablelist> 10914</refsect1> 10915<refsect1> 10916<title>Description</title> 10917<para> 10918 Reads/writes up to table->maxlen/sizeof(unsigned int) integer 10919 values from/to the user buffer, treated as an ASCII string. 10920 </para><para> 10921 10922 Returns 0 on success. 10923</para> 10924</refsect1> 10925</refentry> 10926 10927<refentry id="API-proc-dointvec-minmax"> 10928<refentryinfo> 10929 <title>LINUX</title> 10930 <productname>Kernel Hackers Manual</productname> 10931 <date>July 2017</date> 10932</refentryinfo> 10933<refmeta> 10934 <refentrytitle><phrase>proc_dointvec_minmax</phrase></refentrytitle> 10935 <manvolnum>9</manvolnum> 10936 <refmiscinfo class="version">4.1.27</refmiscinfo> 10937</refmeta> 10938<refnamediv> 10939 <refname>proc_dointvec_minmax</refname> 10940 <refpurpose> 10941 read a vector of integers with min/max values 10942 </refpurpose> 10943</refnamediv> 10944<refsynopsisdiv> 10945 <title>Synopsis</title> 10946 <funcsynopsis><funcprototype> 10947 <funcdef>int <function>proc_dointvec_minmax </function></funcdef> 10948 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 10949 <paramdef>int <parameter>write</parameter></paramdef> 10950 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 10951 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 10952 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 10953 </funcprototype></funcsynopsis> 10954</refsynopsisdiv> 10955<refsect1> 10956 <title>Arguments</title> 10957 <variablelist> 10958 <varlistentry> 10959 <term><parameter>table</parameter></term> 10960 <listitem> 10961 <para> 10962 the sysctl table 10963 </para> 10964 </listitem> 10965 </varlistentry> 10966 <varlistentry> 10967 <term><parameter>write</parameter></term> 10968 <listitem> 10969 <para> 10970 <constant>TRUE</constant> if this is a write to the sysctl file 10971 </para> 10972 </listitem> 10973 </varlistentry> 10974 <varlistentry> 10975 <term><parameter>buffer</parameter></term> 10976 <listitem> 10977 <para> 10978 the user buffer 10979 </para> 10980 </listitem> 10981 </varlistentry> 10982 <varlistentry> 10983 <term><parameter>lenp</parameter></term> 10984 <listitem> 10985 <para> 10986 the size of the user buffer 10987 </para> 10988 </listitem> 10989 </varlistentry> 10990 <varlistentry> 10991 <term><parameter>ppos</parameter></term> 10992 <listitem> 10993 <para> 10994 file position 10995 </para> 10996 </listitem> 10997 </varlistentry> 10998 </variablelist> 10999</refsect1> 11000<refsect1> 11001<title>Description</title> 11002<para> 11003 Reads/writes up to table->maxlen/sizeof(unsigned int) integer 11004 values from/to the user buffer, treated as an ASCII string. 11005 </para><para> 11006 11007 This routine will ensure the values are within the range specified by 11008 table->extra1 (min) and table->extra2 (max). 11009 </para><para> 11010 11011 Returns 0 on success. 11012</para> 11013</refsect1> 11014</refentry> 11015 11016<refentry id="API-proc-doulongvec-minmax"> 11017<refentryinfo> 11018 <title>LINUX</title> 11019 <productname>Kernel Hackers Manual</productname> 11020 <date>July 2017</date> 11021</refentryinfo> 11022<refmeta> 11023 <refentrytitle><phrase>proc_doulongvec_minmax</phrase></refentrytitle> 11024 <manvolnum>9</manvolnum> 11025 <refmiscinfo class="version">4.1.27</refmiscinfo> 11026</refmeta> 11027<refnamediv> 11028 <refname>proc_doulongvec_minmax</refname> 11029 <refpurpose> 11030 read a vector of long integers with min/max values 11031 </refpurpose> 11032</refnamediv> 11033<refsynopsisdiv> 11034 <title>Synopsis</title> 11035 <funcsynopsis><funcprototype> 11036 <funcdef>int <function>proc_doulongvec_minmax </function></funcdef> 11037 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 11038 <paramdef>int <parameter>write</parameter></paramdef> 11039 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 11040 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 11041 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 11042 </funcprototype></funcsynopsis> 11043</refsynopsisdiv> 11044<refsect1> 11045 <title>Arguments</title> 11046 <variablelist> 11047 <varlistentry> 11048 <term><parameter>table</parameter></term> 11049 <listitem> 11050 <para> 11051 the sysctl table 11052 </para> 11053 </listitem> 11054 </varlistentry> 11055 <varlistentry> 11056 <term><parameter>write</parameter></term> 11057 <listitem> 11058 <para> 11059 <constant>TRUE</constant> if this is a write to the sysctl file 11060 </para> 11061 </listitem> 11062 </varlistentry> 11063 <varlistentry> 11064 <term><parameter>buffer</parameter></term> 11065 <listitem> 11066 <para> 11067 the user buffer 11068 </para> 11069 </listitem> 11070 </varlistentry> 11071 <varlistentry> 11072 <term><parameter>lenp</parameter></term> 11073 <listitem> 11074 <para> 11075 the size of the user buffer 11076 </para> 11077 </listitem> 11078 </varlistentry> 11079 <varlistentry> 11080 <term><parameter>ppos</parameter></term> 11081 <listitem> 11082 <para> 11083 file position 11084 </para> 11085 </listitem> 11086 </varlistentry> 11087 </variablelist> 11088</refsect1> 11089<refsect1> 11090<title>Description</title> 11091<para> 11092 Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long 11093 values from/to the user buffer, treated as an ASCII string. 11094 </para><para> 11095 11096 This routine will ensure the values are within the range specified by 11097 table->extra1 (min) and table->extra2 (max). 11098 </para><para> 11099 11100 Returns 0 on success. 11101</para> 11102</refsect1> 11103</refentry> 11104 11105<refentry id="API-proc-doulongvec-ms-jiffies-minmax"> 11106<refentryinfo> 11107 <title>LINUX</title> 11108 <productname>Kernel Hackers Manual</productname> 11109 <date>July 2017</date> 11110</refentryinfo> 11111<refmeta> 11112 <refentrytitle><phrase>proc_doulongvec_ms_jiffies_minmax</phrase></refentrytitle> 11113 <manvolnum>9</manvolnum> 11114 <refmiscinfo class="version">4.1.27</refmiscinfo> 11115</refmeta> 11116<refnamediv> 11117 <refname>proc_doulongvec_ms_jiffies_minmax</refname> 11118 <refpurpose> 11119 read a vector of millisecond values with min/max values 11120 </refpurpose> 11121</refnamediv> 11122<refsynopsisdiv> 11123 <title>Synopsis</title> 11124 <funcsynopsis><funcprototype> 11125 <funcdef>int <function>proc_doulongvec_ms_jiffies_minmax </function></funcdef> 11126 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 11127 <paramdef>int <parameter>write</parameter></paramdef> 11128 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 11129 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 11130 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 11131 </funcprototype></funcsynopsis> 11132</refsynopsisdiv> 11133<refsect1> 11134 <title>Arguments</title> 11135 <variablelist> 11136 <varlistentry> 11137 <term><parameter>table</parameter></term> 11138 <listitem> 11139 <para> 11140 the sysctl table 11141 </para> 11142 </listitem> 11143 </varlistentry> 11144 <varlistentry> 11145 <term><parameter>write</parameter></term> 11146 <listitem> 11147 <para> 11148 <constant>TRUE</constant> if this is a write to the sysctl file 11149 </para> 11150 </listitem> 11151 </varlistentry> 11152 <varlistentry> 11153 <term><parameter>buffer</parameter></term> 11154 <listitem> 11155 <para> 11156 the user buffer 11157 </para> 11158 </listitem> 11159 </varlistentry> 11160 <varlistentry> 11161 <term><parameter>lenp</parameter></term> 11162 <listitem> 11163 <para> 11164 the size of the user buffer 11165 </para> 11166 </listitem> 11167 </varlistentry> 11168 <varlistentry> 11169 <term><parameter>ppos</parameter></term> 11170 <listitem> 11171 <para> 11172 file position 11173 </para> 11174 </listitem> 11175 </varlistentry> 11176 </variablelist> 11177</refsect1> 11178<refsect1> 11179<title>Description</title> 11180<para> 11181 Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long 11182 values from/to the user buffer, treated as an ASCII string. The values 11183 are treated as milliseconds, and converted to jiffies when they are stored. 11184 </para><para> 11185 11186 This routine will ensure the values are within the range specified by 11187 table->extra1 (min) and table->extra2 (max). 11188 </para><para> 11189 11190 Returns 0 on success. 11191</para> 11192</refsect1> 11193</refentry> 11194 11195<refentry id="API-proc-dointvec-jiffies"> 11196<refentryinfo> 11197 <title>LINUX</title> 11198 <productname>Kernel Hackers Manual</productname> 11199 <date>July 2017</date> 11200</refentryinfo> 11201<refmeta> 11202 <refentrytitle><phrase>proc_dointvec_jiffies</phrase></refentrytitle> 11203 <manvolnum>9</manvolnum> 11204 <refmiscinfo class="version">4.1.27</refmiscinfo> 11205</refmeta> 11206<refnamediv> 11207 <refname>proc_dointvec_jiffies</refname> 11208 <refpurpose> 11209 read a vector of integers as seconds 11210 </refpurpose> 11211</refnamediv> 11212<refsynopsisdiv> 11213 <title>Synopsis</title> 11214 <funcsynopsis><funcprototype> 11215 <funcdef>int <function>proc_dointvec_jiffies </function></funcdef> 11216 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 11217 <paramdef>int <parameter>write</parameter></paramdef> 11218 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 11219 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 11220 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 11221 </funcprototype></funcsynopsis> 11222</refsynopsisdiv> 11223<refsect1> 11224 <title>Arguments</title> 11225 <variablelist> 11226 <varlistentry> 11227 <term><parameter>table</parameter></term> 11228 <listitem> 11229 <para> 11230 the sysctl table 11231 </para> 11232 </listitem> 11233 </varlistentry> 11234 <varlistentry> 11235 <term><parameter>write</parameter></term> 11236 <listitem> 11237 <para> 11238 <constant>TRUE</constant> if this is a write to the sysctl file 11239 </para> 11240 </listitem> 11241 </varlistentry> 11242 <varlistentry> 11243 <term><parameter>buffer</parameter></term> 11244 <listitem> 11245 <para> 11246 the user buffer 11247 </para> 11248 </listitem> 11249 </varlistentry> 11250 <varlistentry> 11251 <term><parameter>lenp</parameter></term> 11252 <listitem> 11253 <para> 11254 the size of the user buffer 11255 </para> 11256 </listitem> 11257 </varlistentry> 11258 <varlistentry> 11259 <term><parameter>ppos</parameter></term> 11260 <listitem> 11261 <para> 11262 file position 11263 </para> 11264 </listitem> 11265 </varlistentry> 11266 </variablelist> 11267</refsect1> 11268<refsect1> 11269<title>Description</title> 11270<para> 11271 Reads/writes up to table->maxlen/sizeof(unsigned int) integer 11272 values from/to the user buffer, treated as an ASCII string. 11273 The values read are assumed to be in seconds, and are converted into 11274 jiffies. 11275 </para><para> 11276 11277 Returns 0 on success. 11278</para> 11279</refsect1> 11280</refentry> 11281 11282<refentry id="API-proc-dointvec-userhz-jiffies"> 11283<refentryinfo> 11284 <title>LINUX</title> 11285 <productname>Kernel Hackers Manual</productname> 11286 <date>July 2017</date> 11287</refentryinfo> 11288<refmeta> 11289 <refentrytitle><phrase>proc_dointvec_userhz_jiffies</phrase></refentrytitle> 11290 <manvolnum>9</manvolnum> 11291 <refmiscinfo class="version">4.1.27</refmiscinfo> 11292</refmeta> 11293<refnamediv> 11294 <refname>proc_dointvec_userhz_jiffies</refname> 11295 <refpurpose> 11296 read a vector of integers as 1/USER_HZ seconds 11297 </refpurpose> 11298</refnamediv> 11299<refsynopsisdiv> 11300 <title>Synopsis</title> 11301 <funcsynopsis><funcprototype> 11302 <funcdef>int <function>proc_dointvec_userhz_jiffies </function></funcdef> 11303 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 11304 <paramdef>int <parameter>write</parameter></paramdef> 11305 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 11306 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 11307 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 11308 </funcprototype></funcsynopsis> 11309</refsynopsisdiv> 11310<refsect1> 11311 <title>Arguments</title> 11312 <variablelist> 11313 <varlistentry> 11314 <term><parameter>table</parameter></term> 11315 <listitem> 11316 <para> 11317 the sysctl table 11318 </para> 11319 </listitem> 11320 </varlistentry> 11321 <varlistentry> 11322 <term><parameter>write</parameter></term> 11323 <listitem> 11324 <para> 11325 <constant>TRUE</constant> if this is a write to the sysctl file 11326 </para> 11327 </listitem> 11328 </varlistentry> 11329 <varlistentry> 11330 <term><parameter>buffer</parameter></term> 11331 <listitem> 11332 <para> 11333 the user buffer 11334 </para> 11335 </listitem> 11336 </varlistentry> 11337 <varlistentry> 11338 <term><parameter>lenp</parameter></term> 11339 <listitem> 11340 <para> 11341 the size of the user buffer 11342 </para> 11343 </listitem> 11344 </varlistentry> 11345 <varlistentry> 11346 <term><parameter>ppos</parameter></term> 11347 <listitem> 11348 <para> 11349 pointer to the file position 11350 </para> 11351 </listitem> 11352 </varlistentry> 11353 </variablelist> 11354</refsect1> 11355<refsect1> 11356<title>Description</title> 11357<para> 11358 Reads/writes up to table->maxlen/sizeof(unsigned int) integer 11359 values from/to the user buffer, treated as an ASCII string. 11360 The values read are assumed to be in 1/USER_HZ seconds, and 11361 are converted into jiffies. 11362 </para><para> 11363 11364 Returns 0 on success. 11365</para> 11366</refsect1> 11367</refentry> 11368 11369<refentry id="API-proc-dointvec-ms-jiffies"> 11370<refentryinfo> 11371 <title>LINUX</title> 11372 <productname>Kernel Hackers Manual</productname> 11373 <date>July 2017</date> 11374</refentryinfo> 11375<refmeta> 11376 <refentrytitle><phrase>proc_dointvec_ms_jiffies</phrase></refentrytitle> 11377 <manvolnum>9</manvolnum> 11378 <refmiscinfo class="version">4.1.27</refmiscinfo> 11379</refmeta> 11380<refnamediv> 11381 <refname>proc_dointvec_ms_jiffies</refname> 11382 <refpurpose> 11383 read a vector of integers as 1 milliseconds 11384 </refpurpose> 11385</refnamediv> 11386<refsynopsisdiv> 11387 <title>Synopsis</title> 11388 <funcsynopsis><funcprototype> 11389 <funcdef>int <function>proc_dointvec_ms_jiffies </function></funcdef> 11390 <paramdef>struct ctl_table * <parameter>table</parameter></paramdef> 11391 <paramdef>int <parameter>write</parameter></paramdef> 11392 <paramdef>void __user * <parameter>buffer</parameter></paramdef> 11393 <paramdef>size_t * <parameter>lenp</parameter></paramdef> 11394 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 11395 </funcprototype></funcsynopsis> 11396</refsynopsisdiv> 11397<refsect1> 11398 <title>Arguments</title> 11399 <variablelist> 11400 <varlistentry> 11401 <term><parameter>table</parameter></term> 11402 <listitem> 11403 <para> 11404 the sysctl table 11405 </para> 11406 </listitem> 11407 </varlistentry> 11408 <varlistentry> 11409 <term><parameter>write</parameter></term> 11410 <listitem> 11411 <para> 11412 <constant>TRUE</constant> if this is a write to the sysctl file 11413 </para> 11414 </listitem> 11415 </varlistentry> 11416 <varlistentry> 11417 <term><parameter>buffer</parameter></term> 11418 <listitem> 11419 <para> 11420 the user buffer 11421 </para> 11422 </listitem> 11423 </varlistentry> 11424 <varlistentry> 11425 <term><parameter>lenp</parameter></term> 11426 <listitem> 11427 <para> 11428 the size of the user buffer 11429 </para> 11430 </listitem> 11431 </varlistentry> 11432 <varlistentry> 11433 <term><parameter>ppos</parameter></term> 11434 <listitem> 11435 <para> 11436 the current position in the file 11437 </para> 11438 </listitem> 11439 </varlistentry> 11440 </variablelist> 11441</refsect1> 11442<refsect1> 11443<title>Description</title> 11444<para> 11445 Reads/writes up to table->maxlen/sizeof(unsigned int) integer 11446 values from/to the user buffer, treated as an ASCII string. 11447 The values read are assumed to be in 1/1000 seconds, and 11448 are converted into jiffies. 11449 </para><para> 11450 11451 Returns 0 on success. 11452</para> 11453</refsect1> 11454</refentry> 11455 11456 </sect1> 11457 11458 <sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title> 11459<!-- fs/proc/base.c --> 11460<refentry id="API-proc-flush-task"> 11461<refentryinfo> 11462 <title>LINUX</title> 11463 <productname>Kernel Hackers Manual</productname> 11464 <date>July 2017</date> 11465</refentryinfo> 11466<refmeta> 11467 <refentrytitle><phrase>proc_flush_task</phrase></refentrytitle> 11468 <manvolnum>9</manvolnum> 11469 <refmiscinfo class="version">4.1.27</refmiscinfo> 11470</refmeta> 11471<refnamediv> 11472 <refname>proc_flush_task</refname> 11473 <refpurpose> 11474 Remove dcache entries for <parameter>task</parameter> from the /proc dcache. 11475 </refpurpose> 11476</refnamediv> 11477<refsynopsisdiv> 11478 <title>Synopsis</title> 11479 <funcsynopsis><funcprototype> 11480 <funcdef>void <function>proc_flush_task </function></funcdef> 11481 <paramdef>struct task_struct * <parameter>task</parameter></paramdef> 11482 </funcprototype></funcsynopsis> 11483</refsynopsisdiv> 11484<refsect1> 11485 <title>Arguments</title> 11486 <variablelist> 11487 <varlistentry> 11488 <term><parameter>task</parameter></term> 11489 <listitem> 11490 <para> 11491 task that should be flushed. 11492 </para> 11493 </listitem> 11494 </varlistentry> 11495 </variablelist> 11496</refsect1> 11497<refsect1> 11498<title>Description</title> 11499<para> 11500 When flushing dentries from proc, one needs to flush them from global 11501 proc (proc_mnt) and from all the namespaces' procs this task was seen 11502 in. This call is supposed to do all of this job. 11503 </para><para> 11504 11505 Looks in the dcache for 11506 /proc/<parameter>pid</parameter> 11507 /proc/<parameter>tgid</parameter>/task/<parameter>pid</parameter> 11508 if either directory is present flushes it and all of it'ts children 11509 from the dcache. 11510 </para><para> 11511 11512 It is safe and reasonable to cache /proc entries for a task until 11513 that task exits. After that they just clog up the dcache with 11514 useless entries, possibly causing useful dcache entries to be 11515 flushed instead. This routine is proved to flush those useless 11516 dcache entries at process exit time. 11517</para> 11518</refsect1> 11519<refsect1> 11520<title>NOTE</title> 11521<para> 11522 This routine is just an optimization so it does not guarantee 11523 that no dcache entries will exist at process exit time it 11524 just makes it very unlikely that any will persist. 11525</para> 11526</refsect1> 11527</refentry> 11528 11529 </sect1> 11530 </chapter> 11531 11532 <chapter id="fs_events"> 11533 <title>Events based on file descriptors</title> 11534<!-- fs/eventfd.c --> 11535<refentry id="API-eventfd-signal"> 11536<refentryinfo> 11537 <title>LINUX</title> 11538 <productname>Kernel Hackers Manual</productname> 11539 <date>July 2017</date> 11540</refentryinfo> 11541<refmeta> 11542 <refentrytitle><phrase>eventfd_signal</phrase></refentrytitle> 11543 <manvolnum>9</manvolnum> 11544 <refmiscinfo class="version">4.1.27</refmiscinfo> 11545</refmeta> 11546<refnamediv> 11547 <refname>eventfd_signal</refname> 11548 <refpurpose> 11549 Adds <parameter>n</parameter> to the eventfd counter. 11550 </refpurpose> 11551</refnamediv> 11552<refsynopsisdiv> 11553 <title>Synopsis</title> 11554 <funcsynopsis><funcprototype> 11555 <funcdef>__u64 <function>eventfd_signal </function></funcdef> 11556 <paramdef>struct eventfd_ctx * <parameter>ctx</parameter></paramdef> 11557 <paramdef>__u64 <parameter>n</parameter></paramdef> 11558 </funcprototype></funcsynopsis> 11559</refsynopsisdiv> 11560<refsect1> 11561 <title>Arguments</title> 11562 <variablelist> 11563 <varlistentry> 11564 <term><parameter>ctx</parameter></term> 11565 <listitem> 11566 <para> 11567 [in] Pointer to the eventfd context. 11568 </para> 11569 </listitem> 11570 </varlistentry> 11571 <varlistentry> 11572 <term><parameter>n</parameter></term> 11573 <listitem> 11574 <para> 11575 [in] Value of the counter to be added to the eventfd internal counter. 11576 The value cannot be negative. 11577 </para> 11578 </listitem> 11579 </varlistentry> 11580 </variablelist> 11581</refsect1> 11582<refsect1> 11583<title>Description</title> 11584<para> 11585 This function is supposed to be called by the kernel in paths that do not 11586 allow sleeping. In this function we allow the counter to reach the ULLONG_MAX 11587 value, and we signal this as overflow condition by returining a POLLERR 11588 to poll(2). 11589 </para><para> 11590 11591 Returns the amount by which the counter was incrememnted. This will be less 11592 than <parameter>n</parameter> if the counter has overflowed. 11593</para> 11594</refsect1> 11595</refentry> 11596 11597<refentry id="API-eventfd-ctx-get"> 11598<refentryinfo> 11599 <title>LINUX</title> 11600 <productname>Kernel Hackers Manual</productname> 11601 <date>July 2017</date> 11602</refentryinfo> 11603<refmeta> 11604 <refentrytitle><phrase>eventfd_ctx_get</phrase></refentrytitle> 11605 <manvolnum>9</manvolnum> 11606 <refmiscinfo class="version">4.1.27</refmiscinfo> 11607</refmeta> 11608<refnamediv> 11609 <refname>eventfd_ctx_get</refname> 11610 <refpurpose> 11611 Acquires a reference to the internal eventfd context. 11612 </refpurpose> 11613</refnamediv> 11614<refsynopsisdiv> 11615 <title>Synopsis</title> 11616 <funcsynopsis><funcprototype> 11617 <funcdef>struct eventfd_ctx * <function>eventfd_ctx_get </function></funcdef> 11618 <paramdef>struct eventfd_ctx * <parameter>ctx</parameter></paramdef> 11619 </funcprototype></funcsynopsis> 11620</refsynopsisdiv> 11621<refsect1> 11622 <title>Arguments</title> 11623 <variablelist> 11624 <varlistentry> 11625 <term><parameter>ctx</parameter></term> 11626 <listitem> 11627 <para> 11628 [in] Pointer to the eventfd context. 11629 </para> 11630 </listitem> 11631 </varlistentry> 11632 </variablelist> 11633</refsect1> 11634<refsect1> 11635<title>Returns</title> 11636<para> 11637 In case of success, returns a pointer to the eventfd context. 11638</para> 11639</refsect1> 11640</refentry> 11641 11642<refentry id="API-eventfd-ctx-put"> 11643<refentryinfo> 11644 <title>LINUX</title> 11645 <productname>Kernel Hackers Manual</productname> 11646 <date>July 2017</date> 11647</refentryinfo> 11648<refmeta> 11649 <refentrytitle><phrase>eventfd_ctx_put</phrase></refentrytitle> 11650 <manvolnum>9</manvolnum> 11651 <refmiscinfo class="version">4.1.27</refmiscinfo> 11652</refmeta> 11653<refnamediv> 11654 <refname>eventfd_ctx_put</refname> 11655 <refpurpose> 11656 Releases a reference to the internal eventfd context. 11657 </refpurpose> 11658</refnamediv> 11659<refsynopsisdiv> 11660 <title>Synopsis</title> 11661 <funcsynopsis><funcprototype> 11662 <funcdef>void <function>eventfd_ctx_put </function></funcdef> 11663 <paramdef>struct eventfd_ctx * <parameter>ctx</parameter></paramdef> 11664 </funcprototype></funcsynopsis> 11665</refsynopsisdiv> 11666<refsect1> 11667 <title>Arguments</title> 11668 <variablelist> 11669 <varlistentry> 11670 <term><parameter>ctx</parameter></term> 11671 <listitem> 11672 <para> 11673 [in] Pointer to eventfd context. 11674 </para> 11675 </listitem> 11676 </varlistentry> 11677 </variablelist> 11678</refsect1> 11679<refsect1> 11680<title>Description</title> 11681<para> 11682 The eventfd context reference must have been previously acquired either 11683 with <function>eventfd_ctx_get</function> or <function>eventfd_ctx_fdget</function>. 11684</para> 11685</refsect1> 11686</refentry> 11687 11688<refentry id="API-eventfd-ctx-remove-wait-queue"> 11689<refentryinfo> 11690 <title>LINUX</title> 11691 <productname>Kernel Hackers Manual</productname> 11692 <date>July 2017</date> 11693</refentryinfo> 11694<refmeta> 11695 <refentrytitle><phrase>eventfd_ctx_remove_wait_queue</phrase></refentrytitle> 11696 <manvolnum>9</manvolnum> 11697 <refmiscinfo class="version">4.1.27</refmiscinfo> 11698</refmeta> 11699<refnamediv> 11700 <refname>eventfd_ctx_remove_wait_queue</refname> 11701 <refpurpose> 11702 Read the current counter and removes wait queue. 11703 </refpurpose> 11704</refnamediv> 11705<refsynopsisdiv> 11706 <title>Synopsis</title> 11707 <funcsynopsis><funcprototype> 11708 <funcdef>int <function>eventfd_ctx_remove_wait_queue </function></funcdef> 11709 <paramdef>struct eventfd_ctx * <parameter>ctx</parameter></paramdef> 11710 <paramdef>wait_queue_t * <parameter>wait</parameter></paramdef> 11711 <paramdef>__u64 * <parameter>cnt</parameter></paramdef> 11712 </funcprototype></funcsynopsis> 11713</refsynopsisdiv> 11714<refsect1> 11715 <title>Arguments</title> 11716 <variablelist> 11717 <varlistentry> 11718 <term><parameter>ctx</parameter></term> 11719 <listitem> 11720 <para> 11721 [in] Pointer to eventfd context. 11722 </para> 11723 </listitem> 11724 </varlistentry> 11725 <varlistentry> 11726 <term><parameter>wait</parameter></term> 11727 <listitem> 11728 <para> 11729 [in] Wait queue to be removed. 11730 </para> 11731 </listitem> 11732 </varlistentry> 11733 <varlistentry> 11734 <term><parameter>cnt</parameter></term> 11735 <listitem> 11736 <para> 11737 [out] Pointer to the 64-bit counter value. 11738 </para> 11739 </listitem> 11740 </varlistentry> 11741 </variablelist> 11742</refsect1> 11743<refsect1> 11744<title>Description</title> 11745<para> 11746 Returns <constant>0</constant> if successful, or the following error codes: 11747 </para><para> 11748 11749 -EAGAIN : The operation would have blocked. 11750 </para><para> 11751 11752 This is used to atomically remove a wait queue entry from the eventfd wait 11753 queue head, and read/reset the counter value. 11754</para> 11755</refsect1> 11756</refentry> 11757 11758<refentry id="API-eventfd-ctx-read"> 11759<refentryinfo> 11760 <title>LINUX</title> 11761 <productname>Kernel Hackers Manual</productname> 11762 <date>July 2017</date> 11763</refentryinfo> 11764<refmeta> 11765 <refentrytitle><phrase>eventfd_ctx_read</phrase></refentrytitle> 11766 <manvolnum>9</manvolnum> 11767 <refmiscinfo class="version">4.1.27</refmiscinfo> 11768</refmeta> 11769<refnamediv> 11770 <refname>eventfd_ctx_read</refname> 11771 <refpurpose> 11772 Reads the eventfd counter or wait if it is zero. 11773 </refpurpose> 11774</refnamediv> 11775<refsynopsisdiv> 11776 <title>Synopsis</title> 11777 <funcsynopsis><funcprototype> 11778 <funcdef>ssize_t <function>eventfd_ctx_read </function></funcdef> 11779 <paramdef>struct eventfd_ctx * <parameter>ctx</parameter></paramdef> 11780 <paramdef>int <parameter>no_wait</parameter></paramdef> 11781 <paramdef>__u64 * <parameter>cnt</parameter></paramdef> 11782 </funcprototype></funcsynopsis> 11783</refsynopsisdiv> 11784<refsect1> 11785 <title>Arguments</title> 11786 <variablelist> 11787 <varlistentry> 11788 <term><parameter>ctx</parameter></term> 11789 <listitem> 11790 <para> 11791 [in] Pointer to eventfd context. 11792 </para> 11793 </listitem> 11794 </varlistentry> 11795 <varlistentry> 11796 <term><parameter>no_wait</parameter></term> 11797 <listitem> 11798 <para> 11799 [in] Different from zero if the operation should not block. 11800 </para> 11801 </listitem> 11802 </varlistentry> 11803 <varlistentry> 11804 <term><parameter>cnt</parameter></term> 11805 <listitem> 11806 <para> 11807 [out] Pointer to the 64-bit counter value. 11808 </para> 11809 </listitem> 11810 </varlistentry> 11811 </variablelist> 11812</refsect1> 11813<refsect1> 11814<title>Description</title> 11815<para> 11816 Returns <constant>0</constant> if successful, or the following error codes: 11817 </para><para> 11818 11819 -EAGAIN : The operation would have blocked but <parameter>no_wait</parameter> was non-zero. 11820 -ERESTARTSYS : A signal interrupted the wait operation. 11821 </para><para> 11822 11823 If <parameter>no_wait</parameter> is zero, the function might sleep until the eventfd internal 11824 counter becomes greater than zero. 11825</para> 11826</refsect1> 11827</refentry> 11828 11829<refentry id="API-eventfd-fget"> 11830<refentryinfo> 11831 <title>LINUX</title> 11832 <productname>Kernel Hackers Manual</productname> 11833 <date>July 2017</date> 11834</refentryinfo> 11835<refmeta> 11836 <refentrytitle><phrase>eventfd_fget</phrase></refentrytitle> 11837 <manvolnum>9</manvolnum> 11838 <refmiscinfo class="version">4.1.27</refmiscinfo> 11839</refmeta> 11840<refnamediv> 11841 <refname>eventfd_fget</refname> 11842 <refpurpose> 11843 Acquire a reference of an eventfd file descriptor. 11844 </refpurpose> 11845</refnamediv> 11846<refsynopsisdiv> 11847 <title>Synopsis</title> 11848 <funcsynopsis><funcprototype> 11849 <funcdef>struct file * <function>eventfd_fget </function></funcdef> 11850 <paramdef>int <parameter>fd</parameter></paramdef> 11851 </funcprototype></funcsynopsis> 11852</refsynopsisdiv> 11853<refsect1> 11854 <title>Arguments</title> 11855 <variablelist> 11856 <varlistentry> 11857 <term><parameter>fd</parameter></term> 11858 <listitem> 11859 <para> 11860 [in] Eventfd file descriptor. 11861 </para> 11862 </listitem> 11863 </varlistentry> 11864 </variablelist> 11865</refsect1> 11866<refsect1> 11867<title>Description</title> 11868<para> 11869 Returns a pointer to the eventfd file structure in case of success, or the 11870</para> 11871</refsect1> 11872<refsect1> 11873<title>following error pointer</title> 11874<para> 11875 </para><para> 11876 11877 -EBADF : Invalid <parameter>fd</parameter> file descriptor. 11878 -EINVAL : The <parameter>fd</parameter> file descriptor is not an eventfd file. 11879</para> 11880</refsect1> 11881</refentry> 11882 11883<refentry id="API-eventfd-ctx-fdget"> 11884<refentryinfo> 11885 <title>LINUX</title> 11886 <productname>Kernel Hackers Manual</productname> 11887 <date>July 2017</date> 11888</refentryinfo> 11889<refmeta> 11890 <refentrytitle><phrase>eventfd_ctx_fdget</phrase></refentrytitle> 11891 <manvolnum>9</manvolnum> 11892 <refmiscinfo class="version">4.1.27</refmiscinfo> 11893</refmeta> 11894<refnamediv> 11895 <refname>eventfd_ctx_fdget</refname> 11896 <refpurpose> 11897 Acquires a reference to the internal eventfd context. 11898 </refpurpose> 11899</refnamediv> 11900<refsynopsisdiv> 11901 <title>Synopsis</title> 11902 <funcsynopsis><funcprototype> 11903 <funcdef>struct eventfd_ctx * <function>eventfd_ctx_fdget </function></funcdef> 11904 <paramdef>int <parameter>fd</parameter></paramdef> 11905 </funcprototype></funcsynopsis> 11906</refsynopsisdiv> 11907<refsect1> 11908 <title>Arguments</title> 11909 <variablelist> 11910 <varlistentry> 11911 <term><parameter>fd</parameter></term> 11912 <listitem> 11913 <para> 11914 [in] Eventfd file descriptor. 11915 </para> 11916 </listitem> 11917 </varlistentry> 11918 </variablelist> 11919</refsect1> 11920<refsect1> 11921<title>Description</title> 11922<para> 11923 Returns a pointer to the internal eventfd context, otherwise the error 11924</para> 11925</refsect1> 11926<refsect1> 11927<title>pointers returned by the following functions</title> 11928<para> 11929 </para><para> 11930 11931 eventfd_fget 11932</para> 11933</refsect1> 11934</refentry> 11935 11936<refentry id="API-eventfd-ctx-fileget"> 11937<refentryinfo> 11938 <title>LINUX</title> 11939 <productname>Kernel Hackers Manual</productname> 11940 <date>July 2017</date> 11941</refentryinfo> 11942<refmeta> 11943 <refentrytitle><phrase>eventfd_ctx_fileget</phrase></refentrytitle> 11944 <manvolnum>9</manvolnum> 11945 <refmiscinfo class="version">4.1.27</refmiscinfo> 11946</refmeta> 11947<refnamediv> 11948 <refname>eventfd_ctx_fileget</refname> 11949 <refpurpose> 11950 Acquires a reference to the internal eventfd context. 11951 </refpurpose> 11952</refnamediv> 11953<refsynopsisdiv> 11954 <title>Synopsis</title> 11955 <funcsynopsis><funcprototype> 11956 <funcdef>struct eventfd_ctx * <function>eventfd_ctx_fileget </function></funcdef> 11957 <paramdef>struct file * <parameter>file</parameter></paramdef> 11958 </funcprototype></funcsynopsis> 11959</refsynopsisdiv> 11960<refsect1> 11961 <title>Arguments</title> 11962 <variablelist> 11963 <varlistentry> 11964 <term><parameter>file</parameter></term> 11965 <listitem> 11966 <para> 11967 [in] Eventfd file pointer. 11968 </para> 11969 </listitem> 11970 </varlistentry> 11971 </variablelist> 11972</refsect1> 11973<refsect1> 11974<title>Description</title> 11975<para> 11976 Returns a pointer to the internal eventfd context, otherwise the error 11977</para> 11978</refsect1> 11979<refsect1> 11980<title>pointer</title> 11981<para> 11982 </para><para> 11983 11984 -EINVAL : The <parameter>fd</parameter> file descriptor is not an eventfd file. 11985</para> 11986</refsect1> 11987</refentry> 11988 11989 </chapter> 11990 11991 <chapter id="sysfs"> 11992 <title>The Filesystem for Exporting Kernel Objects</title> 11993<!-- fs/sysfs/file.c --> 11994<refentry id="API-sysfs-create-file-ns"> 11995<refentryinfo> 11996 <title>LINUX</title> 11997 <productname>Kernel Hackers Manual</productname> 11998 <date>July 2017</date> 11999</refentryinfo> 12000<refmeta> 12001 <refentrytitle><phrase>sysfs_create_file_ns</phrase></refentrytitle> 12002 <manvolnum>9</manvolnum> 12003 <refmiscinfo class="version">4.1.27</refmiscinfo> 12004</refmeta> 12005<refnamediv> 12006 <refname>sysfs_create_file_ns</refname> 12007 <refpurpose> 12008 create an attribute file for an object with custom ns 12009 </refpurpose> 12010</refnamediv> 12011<refsynopsisdiv> 12012 <title>Synopsis</title> 12013 <funcsynopsis><funcprototype> 12014 <funcdef>int <function>sysfs_create_file_ns </function></funcdef> 12015 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12016 <paramdef>const struct attribute * <parameter>attr</parameter></paramdef> 12017 <paramdef>const void * <parameter>ns</parameter></paramdef> 12018 </funcprototype></funcsynopsis> 12019</refsynopsisdiv> 12020<refsect1> 12021 <title>Arguments</title> 12022 <variablelist> 12023 <varlistentry> 12024 <term><parameter>kobj</parameter></term> 12025 <listitem> 12026 <para> 12027 object we're creating for 12028 </para> 12029 </listitem> 12030 </varlistentry> 12031 <varlistentry> 12032 <term><parameter>attr</parameter></term> 12033 <listitem> 12034 <para> 12035 attribute descriptor 12036 </para> 12037 </listitem> 12038 </varlistentry> 12039 <varlistentry> 12040 <term><parameter>ns</parameter></term> 12041 <listitem> 12042 <para> 12043 namespace the new file should belong to 12044 </para> 12045 </listitem> 12046 </varlistentry> 12047 </variablelist> 12048</refsect1> 12049</refentry> 12050 12051<refentry id="API-sysfs-add-file-to-group"> 12052<refentryinfo> 12053 <title>LINUX</title> 12054 <productname>Kernel Hackers Manual</productname> 12055 <date>July 2017</date> 12056</refentryinfo> 12057<refmeta> 12058 <refentrytitle><phrase>sysfs_add_file_to_group</phrase></refentrytitle> 12059 <manvolnum>9</manvolnum> 12060 <refmiscinfo class="version">4.1.27</refmiscinfo> 12061</refmeta> 12062<refnamediv> 12063 <refname>sysfs_add_file_to_group</refname> 12064 <refpurpose> 12065 add an attribute file to a pre-existing group. 12066 </refpurpose> 12067</refnamediv> 12068<refsynopsisdiv> 12069 <title>Synopsis</title> 12070 <funcsynopsis><funcprototype> 12071 <funcdef>int <function>sysfs_add_file_to_group </function></funcdef> 12072 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12073 <paramdef>const struct attribute * <parameter>attr</parameter></paramdef> 12074 <paramdef>const char * <parameter>group</parameter></paramdef> 12075 </funcprototype></funcsynopsis> 12076</refsynopsisdiv> 12077<refsect1> 12078 <title>Arguments</title> 12079 <variablelist> 12080 <varlistentry> 12081 <term><parameter>kobj</parameter></term> 12082 <listitem> 12083 <para> 12084 object we're acting for. 12085 </para> 12086 </listitem> 12087 </varlistentry> 12088 <varlistentry> 12089 <term><parameter>attr</parameter></term> 12090 <listitem> 12091 <para> 12092 attribute descriptor. 12093 </para> 12094 </listitem> 12095 </varlistentry> 12096 <varlistentry> 12097 <term><parameter>group</parameter></term> 12098 <listitem> 12099 <para> 12100 group name. 12101 </para> 12102 </listitem> 12103 </varlistentry> 12104 </variablelist> 12105</refsect1> 12106</refentry> 12107 12108<refentry id="API-sysfs-chmod-file"> 12109<refentryinfo> 12110 <title>LINUX</title> 12111 <productname>Kernel Hackers Manual</productname> 12112 <date>July 2017</date> 12113</refentryinfo> 12114<refmeta> 12115 <refentrytitle><phrase>sysfs_chmod_file</phrase></refentrytitle> 12116 <manvolnum>9</manvolnum> 12117 <refmiscinfo class="version">4.1.27</refmiscinfo> 12118</refmeta> 12119<refnamediv> 12120 <refname>sysfs_chmod_file</refname> 12121 <refpurpose> 12122 update the modified mode value on an object attribute. 12123 </refpurpose> 12124</refnamediv> 12125<refsynopsisdiv> 12126 <title>Synopsis</title> 12127 <funcsynopsis><funcprototype> 12128 <funcdef>int <function>sysfs_chmod_file </function></funcdef> 12129 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12130 <paramdef>const struct attribute * <parameter>attr</parameter></paramdef> 12131 <paramdef>umode_t <parameter>mode</parameter></paramdef> 12132 </funcprototype></funcsynopsis> 12133</refsynopsisdiv> 12134<refsect1> 12135 <title>Arguments</title> 12136 <variablelist> 12137 <varlistentry> 12138 <term><parameter>kobj</parameter></term> 12139 <listitem> 12140 <para> 12141 object we're acting for. 12142 </para> 12143 </listitem> 12144 </varlistentry> 12145 <varlistentry> 12146 <term><parameter>attr</parameter></term> 12147 <listitem> 12148 <para> 12149 attribute descriptor. 12150 </para> 12151 </listitem> 12152 </varlistentry> 12153 <varlistentry> 12154 <term><parameter>mode</parameter></term> 12155 <listitem> 12156 <para> 12157 file permissions. 12158 </para> 12159 </listitem> 12160 </varlistentry> 12161 </variablelist> 12162</refsect1> 12163</refentry> 12164 12165<refentry id="API-sysfs-remove-file-ns"> 12166<refentryinfo> 12167 <title>LINUX</title> 12168 <productname>Kernel Hackers Manual</productname> 12169 <date>July 2017</date> 12170</refentryinfo> 12171<refmeta> 12172 <refentrytitle><phrase>sysfs_remove_file_ns</phrase></refentrytitle> 12173 <manvolnum>9</manvolnum> 12174 <refmiscinfo class="version">4.1.27</refmiscinfo> 12175</refmeta> 12176<refnamediv> 12177 <refname>sysfs_remove_file_ns</refname> 12178 <refpurpose> 12179 remove an object attribute with a custom ns tag 12180 </refpurpose> 12181</refnamediv> 12182<refsynopsisdiv> 12183 <title>Synopsis</title> 12184 <funcsynopsis><funcprototype> 12185 <funcdef>void <function>sysfs_remove_file_ns </function></funcdef> 12186 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12187 <paramdef>const struct attribute * <parameter>attr</parameter></paramdef> 12188 <paramdef>const void * <parameter>ns</parameter></paramdef> 12189 </funcprototype></funcsynopsis> 12190</refsynopsisdiv> 12191<refsect1> 12192 <title>Arguments</title> 12193 <variablelist> 12194 <varlistentry> 12195 <term><parameter>kobj</parameter></term> 12196 <listitem> 12197 <para> 12198 object we're acting for 12199 </para> 12200 </listitem> 12201 </varlistentry> 12202 <varlistentry> 12203 <term><parameter>attr</parameter></term> 12204 <listitem> 12205 <para> 12206 attribute descriptor 12207 </para> 12208 </listitem> 12209 </varlistentry> 12210 <varlistentry> 12211 <term><parameter>ns</parameter></term> 12212 <listitem> 12213 <para> 12214 namespace tag of the file to remove 12215 </para> 12216 </listitem> 12217 </varlistentry> 12218 </variablelist> 12219</refsect1> 12220<refsect1> 12221<title>Description</title> 12222<para> 12223 Hash the attribute name and namespace tag and kill the victim. 12224</para> 12225</refsect1> 12226</refentry> 12227 12228<refentry id="API-sysfs-remove-file-from-group"> 12229<refentryinfo> 12230 <title>LINUX</title> 12231 <productname>Kernel Hackers Manual</productname> 12232 <date>July 2017</date> 12233</refentryinfo> 12234<refmeta> 12235 <refentrytitle><phrase>sysfs_remove_file_from_group</phrase></refentrytitle> 12236 <manvolnum>9</manvolnum> 12237 <refmiscinfo class="version">4.1.27</refmiscinfo> 12238</refmeta> 12239<refnamediv> 12240 <refname>sysfs_remove_file_from_group</refname> 12241 <refpurpose> 12242 remove an attribute file from a group. 12243 </refpurpose> 12244</refnamediv> 12245<refsynopsisdiv> 12246 <title>Synopsis</title> 12247 <funcsynopsis><funcprototype> 12248 <funcdef>void <function>sysfs_remove_file_from_group </function></funcdef> 12249 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12250 <paramdef>const struct attribute * <parameter>attr</parameter></paramdef> 12251 <paramdef>const char * <parameter>group</parameter></paramdef> 12252 </funcprototype></funcsynopsis> 12253</refsynopsisdiv> 12254<refsect1> 12255 <title>Arguments</title> 12256 <variablelist> 12257 <varlistentry> 12258 <term><parameter>kobj</parameter></term> 12259 <listitem> 12260 <para> 12261 object we're acting for. 12262 </para> 12263 </listitem> 12264 </varlistentry> 12265 <varlistentry> 12266 <term><parameter>attr</parameter></term> 12267 <listitem> 12268 <para> 12269 attribute descriptor. 12270 </para> 12271 </listitem> 12272 </varlistentry> 12273 <varlistentry> 12274 <term><parameter>group</parameter></term> 12275 <listitem> 12276 <para> 12277 group name. 12278 </para> 12279 </listitem> 12280 </varlistentry> 12281 </variablelist> 12282</refsect1> 12283</refentry> 12284 12285<refentry id="API-sysfs-create-bin-file"> 12286<refentryinfo> 12287 <title>LINUX</title> 12288 <productname>Kernel Hackers Manual</productname> 12289 <date>July 2017</date> 12290</refentryinfo> 12291<refmeta> 12292 <refentrytitle><phrase>sysfs_create_bin_file</phrase></refentrytitle> 12293 <manvolnum>9</manvolnum> 12294 <refmiscinfo class="version">4.1.27</refmiscinfo> 12295</refmeta> 12296<refnamediv> 12297 <refname>sysfs_create_bin_file</refname> 12298 <refpurpose> 12299 create binary file for object. 12300 </refpurpose> 12301</refnamediv> 12302<refsynopsisdiv> 12303 <title>Synopsis</title> 12304 <funcsynopsis><funcprototype> 12305 <funcdef>int <function>sysfs_create_bin_file </function></funcdef> 12306 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12307 <paramdef>const struct bin_attribute * <parameter>attr</parameter></paramdef> 12308 </funcprototype></funcsynopsis> 12309</refsynopsisdiv> 12310<refsect1> 12311 <title>Arguments</title> 12312 <variablelist> 12313 <varlistentry> 12314 <term><parameter>kobj</parameter></term> 12315 <listitem> 12316 <para> 12317 object. 12318 </para> 12319 </listitem> 12320 </varlistentry> 12321 <varlistentry> 12322 <term><parameter>attr</parameter></term> 12323 <listitem> 12324 <para> 12325 attribute descriptor. 12326 </para> 12327 </listitem> 12328 </varlistentry> 12329 </variablelist> 12330</refsect1> 12331</refentry> 12332 12333<refentry id="API-sysfs-remove-bin-file"> 12334<refentryinfo> 12335 <title>LINUX</title> 12336 <productname>Kernel Hackers Manual</productname> 12337 <date>July 2017</date> 12338</refentryinfo> 12339<refmeta> 12340 <refentrytitle><phrase>sysfs_remove_bin_file</phrase></refentrytitle> 12341 <manvolnum>9</manvolnum> 12342 <refmiscinfo class="version">4.1.27</refmiscinfo> 12343</refmeta> 12344<refnamediv> 12345 <refname>sysfs_remove_bin_file</refname> 12346 <refpurpose> 12347 remove binary file for object. 12348 </refpurpose> 12349</refnamediv> 12350<refsynopsisdiv> 12351 <title>Synopsis</title> 12352 <funcsynopsis><funcprototype> 12353 <funcdef>void <function>sysfs_remove_bin_file </function></funcdef> 12354 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12355 <paramdef>const struct bin_attribute * <parameter>attr</parameter></paramdef> 12356 </funcprototype></funcsynopsis> 12357</refsynopsisdiv> 12358<refsect1> 12359 <title>Arguments</title> 12360 <variablelist> 12361 <varlistentry> 12362 <term><parameter>kobj</parameter></term> 12363 <listitem> 12364 <para> 12365 object. 12366 </para> 12367 </listitem> 12368 </varlistentry> 12369 <varlistentry> 12370 <term><parameter>attr</parameter></term> 12371 <listitem> 12372 <para> 12373 attribute descriptor. 12374 </para> 12375 </listitem> 12376 </varlistentry> 12377 </variablelist> 12378</refsect1> 12379</refentry> 12380 12381<!-- fs/sysfs/symlink.c --> 12382<refentry id="API-sysfs-create-link"> 12383<refentryinfo> 12384 <title>LINUX</title> 12385 <productname>Kernel Hackers Manual</productname> 12386 <date>July 2017</date> 12387</refentryinfo> 12388<refmeta> 12389 <refentrytitle><phrase>sysfs_create_link</phrase></refentrytitle> 12390 <manvolnum>9</manvolnum> 12391 <refmiscinfo class="version">4.1.27</refmiscinfo> 12392</refmeta> 12393<refnamediv> 12394 <refname>sysfs_create_link</refname> 12395 <refpurpose> 12396 create symlink between two objects. 12397 </refpurpose> 12398</refnamediv> 12399<refsynopsisdiv> 12400 <title>Synopsis</title> 12401 <funcsynopsis><funcprototype> 12402 <funcdef>int <function>sysfs_create_link </function></funcdef> 12403 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12404 <paramdef>struct kobject * <parameter>target</parameter></paramdef> 12405 <paramdef>const char * <parameter>name</parameter></paramdef> 12406 </funcprototype></funcsynopsis> 12407</refsynopsisdiv> 12408<refsect1> 12409 <title>Arguments</title> 12410 <variablelist> 12411 <varlistentry> 12412 <term><parameter>kobj</parameter></term> 12413 <listitem> 12414 <para> 12415 object whose directory we're creating the link in. 12416 </para> 12417 </listitem> 12418 </varlistentry> 12419 <varlistentry> 12420 <term><parameter>target</parameter></term> 12421 <listitem> 12422 <para> 12423 object we're pointing to. 12424 </para> 12425 </listitem> 12426 </varlistentry> 12427 <varlistentry> 12428 <term><parameter>name</parameter></term> 12429 <listitem> 12430 <para> 12431 name of the symlink. 12432 </para> 12433 </listitem> 12434 </varlistentry> 12435 </variablelist> 12436</refsect1> 12437</refentry> 12438 12439<refentry id="API-sysfs-remove-link"> 12440<refentryinfo> 12441 <title>LINUX</title> 12442 <productname>Kernel Hackers Manual</productname> 12443 <date>July 2017</date> 12444</refentryinfo> 12445<refmeta> 12446 <refentrytitle><phrase>sysfs_remove_link</phrase></refentrytitle> 12447 <manvolnum>9</manvolnum> 12448 <refmiscinfo class="version">4.1.27</refmiscinfo> 12449</refmeta> 12450<refnamediv> 12451 <refname>sysfs_remove_link</refname> 12452 <refpurpose> 12453 remove symlink in object's directory. 12454 </refpurpose> 12455</refnamediv> 12456<refsynopsisdiv> 12457 <title>Synopsis</title> 12458 <funcsynopsis><funcprototype> 12459 <funcdef>void <function>sysfs_remove_link </function></funcdef> 12460 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12461 <paramdef>const char * <parameter>name</parameter></paramdef> 12462 </funcprototype></funcsynopsis> 12463</refsynopsisdiv> 12464<refsect1> 12465 <title>Arguments</title> 12466 <variablelist> 12467 <varlistentry> 12468 <term><parameter>kobj</parameter></term> 12469 <listitem> 12470 <para> 12471 object we're acting for. 12472 </para> 12473 </listitem> 12474 </varlistentry> 12475 <varlistentry> 12476 <term><parameter>name</parameter></term> 12477 <listitem> 12478 <para> 12479 name of the symlink to remove. 12480 </para> 12481 </listitem> 12482 </varlistentry> 12483 </variablelist> 12484</refsect1> 12485</refentry> 12486 12487<refentry id="API-sysfs-rename-link-ns"> 12488<refentryinfo> 12489 <title>LINUX</title> 12490 <productname>Kernel Hackers Manual</productname> 12491 <date>July 2017</date> 12492</refentryinfo> 12493<refmeta> 12494 <refentrytitle><phrase>sysfs_rename_link_ns</phrase></refentrytitle> 12495 <manvolnum>9</manvolnum> 12496 <refmiscinfo class="version">4.1.27</refmiscinfo> 12497</refmeta> 12498<refnamediv> 12499 <refname>sysfs_rename_link_ns</refname> 12500 <refpurpose> 12501 rename symlink in object's directory. 12502 </refpurpose> 12503</refnamediv> 12504<refsynopsisdiv> 12505 <title>Synopsis</title> 12506 <funcsynopsis><funcprototype> 12507 <funcdef>int <function>sysfs_rename_link_ns </function></funcdef> 12508 <paramdef>struct kobject * <parameter>kobj</parameter></paramdef> 12509 <paramdef>struct kobject * <parameter>targ</parameter></paramdef> 12510 <paramdef>const char * <parameter>old</parameter></paramdef> 12511 <paramdef>const char * <parameter>new</parameter></paramdef> 12512 <paramdef>const void * <parameter>new_ns</parameter></paramdef> 12513 </funcprototype></funcsynopsis> 12514</refsynopsisdiv> 12515<refsect1> 12516 <title>Arguments</title> 12517 <variablelist> 12518 <varlistentry> 12519 <term><parameter>kobj</parameter></term> 12520 <listitem> 12521 <para> 12522 object we're acting for. 12523 </para> 12524 </listitem> 12525 </varlistentry> 12526 <varlistentry> 12527 <term><parameter>targ</parameter></term> 12528 <listitem> 12529 <para> 12530 object we're pointing to. 12531 </para> 12532 </listitem> 12533 </varlistentry> 12534 <varlistentry> 12535 <term><parameter>old</parameter></term> 12536 <listitem> 12537 <para> 12538 previous name of the symlink. 12539 </para> 12540 </listitem> 12541 </varlistentry> 12542 <varlistentry> 12543 <term><parameter>new</parameter></term> 12544 <listitem> 12545 <para> 12546 new name of the symlink. 12547 </para> 12548 </listitem> 12549 </varlistentry> 12550 <varlistentry> 12551 <term><parameter>new_ns</parameter></term> 12552 <listitem> 12553 <para> 12554 new namespace of the symlink. 12555 </para> 12556 </listitem> 12557 </varlistentry> 12558 </variablelist> 12559</refsect1> 12560<refsect1> 12561<title>Description</title> 12562<para> 12563 A helper function for the common rename symlink idiom. 12564</para> 12565</refsect1> 12566</refentry> 12567 12568 </chapter> 12569 12570 <chapter id="debugfs"> 12571 <title>The debugfs filesystem</title> 12572 12573 <sect1 id="debugfs_interface"><title>debugfs interface</title> 12574<!-- fs/debugfs/inode.c --> 12575<refentry id="API-debugfs-create-file"> 12576<refentryinfo> 12577 <title>LINUX</title> 12578 <productname>Kernel Hackers Manual</productname> 12579 <date>July 2017</date> 12580</refentryinfo> 12581<refmeta> 12582 <refentrytitle><phrase>debugfs_create_file</phrase></refentrytitle> 12583 <manvolnum>9</manvolnum> 12584 <refmiscinfo class="version">4.1.27</refmiscinfo> 12585</refmeta> 12586<refnamediv> 12587 <refname>debugfs_create_file</refname> 12588 <refpurpose> 12589 create a file in the debugfs filesystem 12590 </refpurpose> 12591</refnamediv> 12592<refsynopsisdiv> 12593 <title>Synopsis</title> 12594 <funcsynopsis><funcprototype> 12595 <funcdef>struct dentry * <function>debugfs_create_file </function></funcdef> 12596 <paramdef>const char * <parameter>name</parameter></paramdef> 12597 <paramdef>umode_t <parameter>mode</parameter></paramdef> 12598 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 12599 <paramdef>void * <parameter>data</parameter></paramdef> 12600 <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef> 12601 </funcprototype></funcsynopsis> 12602</refsynopsisdiv> 12603<refsect1> 12604 <title>Arguments</title> 12605 <variablelist> 12606 <varlistentry> 12607 <term><parameter>name</parameter></term> 12608 <listitem> 12609 <para> 12610 a pointer to a string containing the name of the file to create. 12611 </para> 12612 </listitem> 12613 </varlistentry> 12614 <varlistentry> 12615 <term><parameter>mode</parameter></term> 12616 <listitem> 12617 <para> 12618 the permission that the file should have. 12619 </para> 12620 </listitem> 12621 </varlistentry> 12622 <varlistentry> 12623 <term><parameter>parent</parameter></term> 12624 <listitem> 12625 <para> 12626 a pointer to the parent dentry for this file. This should be a 12627 directory dentry if set. If this parameter is NULL, then the 12628 file will be created in the root of the debugfs filesystem. 12629 </para> 12630 </listitem> 12631 </varlistentry> 12632 <varlistentry> 12633 <term><parameter>data</parameter></term> 12634 <listitem> 12635 <para> 12636 a pointer to something that the caller will want to get to later 12637 on. The inode.i_private pointer will point to this value on 12638 the <function>open</function> call. 12639 </para> 12640 </listitem> 12641 </varlistentry> 12642 <varlistentry> 12643 <term><parameter>fops</parameter></term> 12644 <listitem> 12645 <para> 12646 a pointer to a struct file_operations that should be used for 12647 this file. 12648 </para> 12649 </listitem> 12650 </varlistentry> 12651 </variablelist> 12652</refsect1> 12653<refsect1> 12654<title>Description</title> 12655<para> 12656 This is the basic <quote>create a file</quote> function for debugfs. It allows for a 12657 wide range of flexibility in creating a file, or a directory (if you want 12658 to create a directory, the <function>debugfs_create_dir</function> function is 12659 recommended to be used instead.) 12660 </para><para> 12661 12662 This function will return a pointer to a dentry if it succeeds. This 12663 pointer must be passed to the <function>debugfs_remove</function> function when the file is 12664 to be removed (no automatic cleanup happens if your module is unloaded, 12665 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 12666 </para><para> 12667 12668 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 12669 returned. 12670</para> 12671</refsect1> 12672</refentry> 12673 12674<refentry id="API-debugfs-create-file-size"> 12675<refentryinfo> 12676 <title>LINUX</title> 12677 <productname>Kernel Hackers Manual</productname> 12678 <date>July 2017</date> 12679</refentryinfo> 12680<refmeta> 12681 <refentrytitle><phrase>debugfs_create_file_size</phrase></refentrytitle> 12682 <manvolnum>9</manvolnum> 12683 <refmiscinfo class="version">4.1.27</refmiscinfo> 12684</refmeta> 12685<refnamediv> 12686 <refname>debugfs_create_file_size</refname> 12687 <refpurpose> 12688 create a file in the debugfs filesystem 12689 </refpurpose> 12690</refnamediv> 12691<refsynopsisdiv> 12692 <title>Synopsis</title> 12693 <funcsynopsis><funcprototype> 12694 <funcdef>struct dentry * <function>debugfs_create_file_size </function></funcdef> 12695 <paramdef>const char * <parameter>name</parameter></paramdef> 12696 <paramdef>umode_t <parameter>mode</parameter></paramdef> 12697 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 12698 <paramdef>void * <parameter>data</parameter></paramdef> 12699 <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef> 12700 <paramdef>loff_t <parameter>file_size</parameter></paramdef> 12701 </funcprototype></funcsynopsis> 12702</refsynopsisdiv> 12703<refsect1> 12704 <title>Arguments</title> 12705 <variablelist> 12706 <varlistentry> 12707 <term><parameter>name</parameter></term> 12708 <listitem> 12709 <para> 12710 a pointer to a string containing the name of the file to create. 12711 </para> 12712 </listitem> 12713 </varlistentry> 12714 <varlistentry> 12715 <term><parameter>mode</parameter></term> 12716 <listitem> 12717 <para> 12718 the permission that the file should have. 12719 </para> 12720 </listitem> 12721 </varlistentry> 12722 <varlistentry> 12723 <term><parameter>parent</parameter></term> 12724 <listitem> 12725 <para> 12726 a pointer to the parent dentry for this file. This should be a 12727 directory dentry if set. If this parameter is NULL, then the 12728 file will be created in the root of the debugfs filesystem. 12729 </para> 12730 </listitem> 12731 </varlistentry> 12732 <varlistentry> 12733 <term><parameter>data</parameter></term> 12734 <listitem> 12735 <para> 12736 a pointer to something that the caller will want to get to later 12737 on. The inode.i_private pointer will point to this value on 12738 the <function>open</function> call. 12739 </para> 12740 </listitem> 12741 </varlistentry> 12742 <varlistentry> 12743 <term><parameter>fops</parameter></term> 12744 <listitem> 12745 <para> 12746 a pointer to a struct file_operations that should be used for 12747 this file. 12748 </para> 12749 </listitem> 12750 </varlistentry> 12751 <varlistentry> 12752 <term><parameter>file_size</parameter></term> 12753 <listitem> 12754 <para> 12755 initial file size 12756 </para> 12757 </listitem> 12758 </varlistentry> 12759 </variablelist> 12760</refsect1> 12761<refsect1> 12762<title>Description</title> 12763<para> 12764 This is the basic <quote>create a file</quote> function for debugfs. It allows for a 12765 wide range of flexibility in creating a file, or a directory (if you want 12766 to create a directory, the <function>debugfs_create_dir</function> function is 12767 recommended to be used instead.) 12768 </para><para> 12769 12770 This function will return a pointer to a dentry if it succeeds. This 12771 pointer must be passed to the <function>debugfs_remove</function> function when the file is 12772 to be removed (no automatic cleanup happens if your module is unloaded, 12773 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 12774 </para><para> 12775 12776 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 12777 returned. 12778</para> 12779</refsect1> 12780</refentry> 12781 12782<refentry id="API-debugfs-create-dir"> 12783<refentryinfo> 12784 <title>LINUX</title> 12785 <productname>Kernel Hackers Manual</productname> 12786 <date>July 2017</date> 12787</refentryinfo> 12788<refmeta> 12789 <refentrytitle><phrase>debugfs_create_dir</phrase></refentrytitle> 12790 <manvolnum>9</manvolnum> 12791 <refmiscinfo class="version">4.1.27</refmiscinfo> 12792</refmeta> 12793<refnamediv> 12794 <refname>debugfs_create_dir</refname> 12795 <refpurpose> 12796 create a directory in the debugfs filesystem 12797 </refpurpose> 12798</refnamediv> 12799<refsynopsisdiv> 12800 <title>Synopsis</title> 12801 <funcsynopsis><funcprototype> 12802 <funcdef>struct dentry * <function>debugfs_create_dir </function></funcdef> 12803 <paramdef>const char * <parameter>name</parameter></paramdef> 12804 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 12805 </funcprototype></funcsynopsis> 12806</refsynopsisdiv> 12807<refsect1> 12808 <title>Arguments</title> 12809 <variablelist> 12810 <varlistentry> 12811 <term><parameter>name</parameter></term> 12812 <listitem> 12813 <para> 12814 a pointer to a string containing the name of the directory to 12815 create. 12816 </para> 12817 </listitem> 12818 </varlistentry> 12819 <varlistentry> 12820 <term><parameter>parent</parameter></term> 12821 <listitem> 12822 <para> 12823 a pointer to the parent dentry for this file. This should be a 12824 directory dentry if set. If this parameter is NULL, then the 12825 directory will be created in the root of the debugfs filesystem. 12826 </para> 12827 </listitem> 12828 </varlistentry> 12829 </variablelist> 12830</refsect1> 12831<refsect1> 12832<title>Description</title> 12833<para> 12834 This function creates a directory in debugfs with the given name. 12835 </para><para> 12836 12837 This function will return a pointer to a dentry if it succeeds. This 12838 pointer must be passed to the <function>debugfs_remove</function> function when the file is 12839 to be removed (no automatic cleanup happens if your module is unloaded, 12840 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 12841 </para><para> 12842 12843 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 12844 returned. 12845</para> 12846</refsect1> 12847</refentry> 12848 12849<refentry id="API-debugfs-create-automount"> 12850<refentryinfo> 12851 <title>LINUX</title> 12852 <productname>Kernel Hackers Manual</productname> 12853 <date>July 2017</date> 12854</refentryinfo> 12855<refmeta> 12856 <refentrytitle><phrase>debugfs_create_automount</phrase></refentrytitle> 12857 <manvolnum>9</manvolnum> 12858 <refmiscinfo class="version">4.1.27</refmiscinfo> 12859</refmeta> 12860<refnamediv> 12861 <refname>debugfs_create_automount</refname> 12862 <refpurpose> 12863 create automount point in the debugfs filesystem 12864 </refpurpose> 12865</refnamediv> 12866<refsynopsisdiv> 12867 <title>Synopsis</title> 12868 <funcsynopsis><funcprototype> 12869 <funcdef>struct dentry * <function>debugfs_create_automount </function></funcdef> 12870 <paramdef>const char * <parameter>name</parameter></paramdef> 12871 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 12872 <paramdef>struct vfsmount *(*<parameter>f</parameter>) 12873 <funcparams>void *</funcparams></paramdef> 12874 <paramdef>void * <parameter>data</parameter></paramdef> 12875 </funcprototype></funcsynopsis> 12876</refsynopsisdiv> 12877<refsect1> 12878 <title>Arguments</title> 12879 <variablelist> 12880 <varlistentry> 12881 <term><parameter>name</parameter></term> 12882 <listitem> 12883 <para> 12884 a pointer to a string containing the name of the file to create. 12885 </para> 12886 </listitem> 12887 </varlistentry> 12888 <varlistentry> 12889 <term><parameter>parent</parameter></term> 12890 <listitem> 12891 <para> 12892 a pointer to the parent dentry for this file. This should be a 12893 directory dentry if set. If this parameter is NULL, then the 12894 file will be created in the root of the debugfs filesystem. 12895 </para> 12896 </listitem> 12897 </varlistentry> 12898 <varlistentry> 12899 <term><parameter>f</parameter></term> 12900 <listitem> 12901 <para> 12902 function to be called when pathname resolution steps on that one. 12903 </para> 12904 </listitem> 12905 </varlistentry> 12906 <varlistentry> 12907 <term><parameter>data</parameter></term> 12908 <listitem> 12909 <para> 12910 opaque argument to pass to <function>f</function>. 12911 </para> 12912 </listitem> 12913 </varlistentry> 12914 </variablelist> 12915</refsect1> 12916<refsect1> 12917<title>Description</title> 12918<para> 12919 <parameter>f</parameter> should return what -><function>d_automount</function> would. 12920</para> 12921</refsect1> 12922</refentry> 12923 12924<refentry id="API-debugfs-create-symlink"> 12925<refentryinfo> 12926 <title>LINUX</title> 12927 <productname>Kernel Hackers Manual</productname> 12928 <date>July 2017</date> 12929</refentryinfo> 12930<refmeta> 12931 <refentrytitle><phrase>debugfs_create_symlink</phrase></refentrytitle> 12932 <manvolnum>9</manvolnum> 12933 <refmiscinfo class="version">4.1.27</refmiscinfo> 12934</refmeta> 12935<refnamediv> 12936 <refname>debugfs_create_symlink</refname> 12937 <refpurpose> 12938 create a symbolic link in the debugfs filesystem 12939 </refpurpose> 12940</refnamediv> 12941<refsynopsisdiv> 12942 <title>Synopsis</title> 12943 <funcsynopsis><funcprototype> 12944 <funcdef>struct dentry * <function>debugfs_create_symlink </function></funcdef> 12945 <paramdef>const char * <parameter>name</parameter></paramdef> 12946 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 12947 <paramdef>const char * <parameter>target</parameter></paramdef> 12948 </funcprototype></funcsynopsis> 12949</refsynopsisdiv> 12950<refsect1> 12951 <title>Arguments</title> 12952 <variablelist> 12953 <varlistentry> 12954 <term><parameter>name</parameter></term> 12955 <listitem> 12956 <para> 12957 a pointer to a string containing the name of the symbolic link to 12958 create. 12959 </para> 12960 </listitem> 12961 </varlistentry> 12962 <varlistentry> 12963 <term><parameter>parent</parameter></term> 12964 <listitem> 12965 <para> 12966 a pointer to the parent dentry for this symbolic link. This 12967 should be a directory dentry if set. If this parameter is NULL, 12968 then the symbolic link will be created in the root of the debugfs 12969 filesystem. 12970 </para> 12971 </listitem> 12972 </varlistentry> 12973 <varlistentry> 12974 <term><parameter>target</parameter></term> 12975 <listitem> 12976 <para> 12977 a pointer to a string containing the path to the target of the 12978 symbolic link. 12979 </para> 12980 </listitem> 12981 </varlistentry> 12982 </variablelist> 12983</refsect1> 12984<refsect1> 12985<title>Description</title> 12986<para> 12987 This function creates a symbolic link with the given name in debugfs that 12988 links to the given target path. 12989 </para><para> 12990 12991 This function will return a pointer to a dentry if it succeeds. This 12992 pointer must be passed to the <function>debugfs_remove</function> function when the symbolic 12993 link is to be removed (no automatic cleanup happens if your module is 12994 unloaded, you are responsible here.) If an error occurs, <constant>NULL</constant> will be 12995 returned. 12996 </para><para> 12997 12998 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 12999 returned. 13000</para> 13001</refsect1> 13002</refentry> 13003 13004<refentry id="API-debugfs-remove"> 13005<refentryinfo> 13006 <title>LINUX</title> 13007 <productname>Kernel Hackers Manual</productname> 13008 <date>July 2017</date> 13009</refentryinfo> 13010<refmeta> 13011 <refentrytitle><phrase>debugfs_remove</phrase></refentrytitle> 13012 <manvolnum>9</manvolnum> 13013 <refmiscinfo class="version">4.1.27</refmiscinfo> 13014</refmeta> 13015<refnamediv> 13016 <refname>debugfs_remove</refname> 13017 <refpurpose> 13018 removes a file or directory from the debugfs filesystem 13019 </refpurpose> 13020</refnamediv> 13021<refsynopsisdiv> 13022 <title>Synopsis</title> 13023 <funcsynopsis><funcprototype> 13024 <funcdef>void <function>debugfs_remove </function></funcdef> 13025 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 13026 </funcprototype></funcsynopsis> 13027</refsynopsisdiv> 13028<refsect1> 13029 <title>Arguments</title> 13030 <variablelist> 13031 <varlistentry> 13032 <term><parameter>dentry</parameter></term> 13033 <listitem> 13034 <para> 13035 a pointer to a the dentry of the file or directory to be 13036 removed. 13037 </para> 13038 </listitem> 13039 </varlistentry> 13040 </variablelist> 13041</refsect1> 13042<refsect1> 13043<title>Description</title> 13044<para> 13045 This function removes a file or directory in debugfs that was previously 13046 created with a call to another debugfs function (like 13047 <function>debugfs_create_file</function> or variants thereof.) 13048 </para><para> 13049 13050 This function is required to be called in order for the file to be 13051 removed, no automatic cleanup of files will happen when a module is 13052 removed, you are responsible here. 13053</para> 13054</refsect1> 13055</refentry> 13056 13057<refentry id="API-debugfs-remove-recursive"> 13058<refentryinfo> 13059 <title>LINUX</title> 13060 <productname>Kernel Hackers Manual</productname> 13061 <date>July 2017</date> 13062</refentryinfo> 13063<refmeta> 13064 <refentrytitle><phrase>debugfs_remove_recursive</phrase></refentrytitle> 13065 <manvolnum>9</manvolnum> 13066 <refmiscinfo class="version">4.1.27</refmiscinfo> 13067</refmeta> 13068<refnamediv> 13069 <refname>debugfs_remove_recursive</refname> 13070 <refpurpose> 13071 recursively removes a directory 13072 </refpurpose> 13073</refnamediv> 13074<refsynopsisdiv> 13075 <title>Synopsis</title> 13076 <funcsynopsis><funcprototype> 13077 <funcdef>void <function>debugfs_remove_recursive </function></funcdef> 13078 <paramdef>struct dentry * <parameter>dentry</parameter></paramdef> 13079 </funcprototype></funcsynopsis> 13080</refsynopsisdiv> 13081<refsect1> 13082 <title>Arguments</title> 13083 <variablelist> 13084 <varlistentry> 13085 <term><parameter>dentry</parameter></term> 13086 <listitem> 13087 <para> 13088 a pointer to a the dentry of the directory to be removed. 13089 </para> 13090 </listitem> 13091 </varlistentry> 13092 </variablelist> 13093</refsect1> 13094<refsect1> 13095<title>Description</title> 13096<para> 13097 This function recursively removes a directory tree in debugfs that 13098 was previously created with a call to another debugfs function 13099 (like <function>debugfs_create_file</function> or variants thereof.) 13100 </para><para> 13101 13102 This function is required to be called in order for the file to be 13103 removed, no automatic cleanup of files will happen when a module is 13104 removed, you are responsible here. 13105</para> 13106</refsect1> 13107</refentry> 13108 13109<refentry id="API-debugfs-rename"> 13110<refentryinfo> 13111 <title>LINUX</title> 13112 <productname>Kernel Hackers Manual</productname> 13113 <date>July 2017</date> 13114</refentryinfo> 13115<refmeta> 13116 <refentrytitle><phrase>debugfs_rename</phrase></refentrytitle> 13117 <manvolnum>9</manvolnum> 13118 <refmiscinfo class="version">4.1.27</refmiscinfo> 13119</refmeta> 13120<refnamediv> 13121 <refname>debugfs_rename</refname> 13122 <refpurpose> 13123 rename a file/directory in the debugfs filesystem 13124 </refpurpose> 13125</refnamediv> 13126<refsynopsisdiv> 13127 <title>Synopsis</title> 13128 <funcsynopsis><funcprototype> 13129 <funcdef>struct dentry * <function>debugfs_rename </function></funcdef> 13130 <paramdef>struct dentry * <parameter>old_dir</parameter></paramdef> 13131 <paramdef>struct dentry * <parameter>old_dentry</parameter></paramdef> 13132 <paramdef>struct dentry * <parameter>new_dir</parameter></paramdef> 13133 <paramdef>const char * <parameter>new_name</parameter></paramdef> 13134 </funcprototype></funcsynopsis> 13135</refsynopsisdiv> 13136<refsect1> 13137 <title>Arguments</title> 13138 <variablelist> 13139 <varlistentry> 13140 <term><parameter>old_dir</parameter></term> 13141 <listitem> 13142 <para> 13143 a pointer to the parent dentry for the renamed object. This 13144 should be a directory dentry. 13145 </para> 13146 </listitem> 13147 </varlistentry> 13148 <varlistentry> 13149 <term><parameter>old_dentry</parameter></term> 13150 <listitem> 13151 <para> 13152 dentry of an object to be renamed. 13153 </para> 13154 </listitem> 13155 </varlistentry> 13156 <varlistentry> 13157 <term><parameter>new_dir</parameter></term> 13158 <listitem> 13159 <para> 13160 a pointer to the parent dentry where the object should be 13161 moved. This should be a directory dentry. 13162 </para> 13163 </listitem> 13164 </varlistentry> 13165 <varlistentry> 13166 <term><parameter>new_name</parameter></term> 13167 <listitem> 13168 <para> 13169 a pointer to a string containing the target name. 13170 </para> 13171 </listitem> 13172 </varlistentry> 13173 </variablelist> 13174</refsect1> 13175<refsect1> 13176<title>Description</title> 13177<para> 13178 This function renames a file/directory in debugfs. The target must not 13179 exist for rename to succeed. 13180 </para><para> 13181 13182 This function will return a pointer to old_dentry (which is updated to 13183 reflect renaming) if it succeeds. If an error occurs, <constant>NULL</constant> will be 13184 returned. 13185 </para><para> 13186 13187 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 13188 returned. 13189</para> 13190</refsect1> 13191</refentry> 13192 13193<refentry id="API-debugfs-initialized"> 13194<refentryinfo> 13195 <title>LINUX</title> 13196 <productname>Kernel Hackers Manual</productname> 13197 <date>July 2017</date> 13198</refentryinfo> 13199<refmeta> 13200 <refentrytitle><phrase>debugfs_initialized</phrase></refentrytitle> 13201 <manvolnum>9</manvolnum> 13202 <refmiscinfo class="version">4.1.27</refmiscinfo> 13203</refmeta> 13204<refnamediv> 13205 <refname>debugfs_initialized</refname> 13206 <refpurpose> 13207 Tells whether debugfs has been registered 13208 </refpurpose> 13209</refnamediv> 13210<refsynopsisdiv> 13211 <title>Synopsis</title> 13212 <funcsynopsis><funcprototype> 13213 <funcdef>bool <function>debugfs_initialized </function></funcdef> 13214 <paramdef> <parameter>void</parameter></paramdef> 13215 </funcprototype></funcsynopsis> 13216</refsynopsisdiv> 13217<refsect1> 13218 <title>Arguments</title> 13219 <variablelist> 13220 <varlistentry> 13221 <term><parameter>void</parameter></term> 13222 <listitem> 13223 <para> 13224 no arguments 13225 </para> 13226 </listitem> 13227 </varlistentry> 13228 </variablelist> 13229</refsect1> 13230</refentry> 13231 13232<!-- fs/debugfs/file.c --> 13233<refentry id="API-debugfs-create-u8"> 13234<refentryinfo> 13235 <title>LINUX</title> 13236 <productname>Kernel Hackers Manual</productname> 13237 <date>July 2017</date> 13238</refentryinfo> 13239<refmeta> 13240 <refentrytitle><phrase>debugfs_create_u8</phrase></refentrytitle> 13241 <manvolnum>9</manvolnum> 13242 <refmiscinfo class="version">4.1.27</refmiscinfo> 13243</refmeta> 13244<refnamediv> 13245 <refname>debugfs_create_u8</refname> 13246 <refpurpose> 13247 create a debugfs file that is used to read and write an unsigned 8-bit value 13248 </refpurpose> 13249</refnamediv> 13250<refsynopsisdiv> 13251 <title>Synopsis</title> 13252 <funcsynopsis><funcprototype> 13253 <funcdef>struct dentry * <function>debugfs_create_u8 </function></funcdef> 13254 <paramdef>const char * <parameter>name</parameter></paramdef> 13255 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13256 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13257 <paramdef>u8 * <parameter>value</parameter></paramdef> 13258 </funcprototype></funcsynopsis> 13259</refsynopsisdiv> 13260<refsect1> 13261 <title>Arguments</title> 13262 <variablelist> 13263 <varlistentry> 13264 <term><parameter>name</parameter></term> 13265 <listitem> 13266 <para> 13267 a pointer to a string containing the name of the file to create. 13268 </para> 13269 </listitem> 13270 </varlistentry> 13271 <varlistentry> 13272 <term><parameter>mode</parameter></term> 13273 <listitem> 13274 <para> 13275 the permission that the file should have 13276 </para> 13277 </listitem> 13278 </varlistentry> 13279 <varlistentry> 13280 <term><parameter>parent</parameter></term> 13281 <listitem> 13282 <para> 13283 a pointer to the parent dentry for this file. This should be a 13284 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13285 file will be created in the root of the debugfs filesystem. 13286 </para> 13287 </listitem> 13288 </varlistentry> 13289 <varlistentry> 13290 <term><parameter>value</parameter></term> 13291 <listitem> 13292 <para> 13293 a pointer to the variable that the file should read to and write 13294 from. 13295 </para> 13296 </listitem> 13297 </varlistentry> 13298 </variablelist> 13299</refsect1> 13300<refsect1> 13301<title>Description</title> 13302<para> 13303 This function creates a file in debugfs with the given name that 13304 contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so 13305 set, it can be read from, and written to. 13306 </para><para> 13307 13308 This function will return a pointer to a dentry if it succeeds. This 13309 pointer must be passed to the <function>debugfs_remove</function> function when the file is 13310 to be removed (no automatic cleanup happens if your module is unloaded, 13311 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 13312 </para><para> 13313 13314 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 13315 returned. It is not wise to check for this value, but rather, check for 13316 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 13317 code. 13318</para> 13319</refsect1> 13320</refentry> 13321 13322<refentry id="API-debugfs-create-u16"> 13323<refentryinfo> 13324 <title>LINUX</title> 13325 <productname>Kernel Hackers Manual</productname> 13326 <date>July 2017</date> 13327</refentryinfo> 13328<refmeta> 13329 <refentrytitle><phrase>debugfs_create_u16</phrase></refentrytitle> 13330 <manvolnum>9</manvolnum> 13331 <refmiscinfo class="version">4.1.27</refmiscinfo> 13332</refmeta> 13333<refnamediv> 13334 <refname>debugfs_create_u16</refname> 13335 <refpurpose> 13336 create a debugfs file that is used to read and write an unsigned 16-bit value 13337 </refpurpose> 13338</refnamediv> 13339<refsynopsisdiv> 13340 <title>Synopsis</title> 13341 <funcsynopsis><funcprototype> 13342 <funcdef>struct dentry * <function>debugfs_create_u16 </function></funcdef> 13343 <paramdef>const char * <parameter>name</parameter></paramdef> 13344 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13345 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13346 <paramdef>u16 * <parameter>value</parameter></paramdef> 13347 </funcprototype></funcsynopsis> 13348</refsynopsisdiv> 13349<refsect1> 13350 <title>Arguments</title> 13351 <variablelist> 13352 <varlistentry> 13353 <term><parameter>name</parameter></term> 13354 <listitem> 13355 <para> 13356 a pointer to a string containing the name of the file to create. 13357 </para> 13358 </listitem> 13359 </varlistentry> 13360 <varlistentry> 13361 <term><parameter>mode</parameter></term> 13362 <listitem> 13363 <para> 13364 the permission that the file should have 13365 </para> 13366 </listitem> 13367 </varlistentry> 13368 <varlistentry> 13369 <term><parameter>parent</parameter></term> 13370 <listitem> 13371 <para> 13372 a pointer to the parent dentry for this file. This should be a 13373 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13374 file will be created in the root of the debugfs filesystem. 13375 </para> 13376 </listitem> 13377 </varlistentry> 13378 <varlistentry> 13379 <term><parameter>value</parameter></term> 13380 <listitem> 13381 <para> 13382 a pointer to the variable that the file should read to and write 13383 from. 13384 </para> 13385 </listitem> 13386 </varlistentry> 13387 </variablelist> 13388</refsect1> 13389<refsect1> 13390<title>Description</title> 13391<para> 13392 This function creates a file in debugfs with the given name that 13393 contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so 13394 set, it can be read from, and written to. 13395 </para><para> 13396 13397 This function will return a pointer to a dentry if it succeeds. This 13398 pointer must be passed to the <function>debugfs_remove</function> function when the file is 13399 to be removed (no automatic cleanup happens if your module is unloaded, 13400 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 13401 </para><para> 13402 13403 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 13404 returned. It is not wise to check for this value, but rather, check for 13405 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 13406 code. 13407</para> 13408</refsect1> 13409</refentry> 13410 13411<refentry id="API-debugfs-create-u32"> 13412<refentryinfo> 13413 <title>LINUX</title> 13414 <productname>Kernel Hackers Manual</productname> 13415 <date>July 2017</date> 13416</refentryinfo> 13417<refmeta> 13418 <refentrytitle><phrase>debugfs_create_u32</phrase></refentrytitle> 13419 <manvolnum>9</manvolnum> 13420 <refmiscinfo class="version">4.1.27</refmiscinfo> 13421</refmeta> 13422<refnamediv> 13423 <refname>debugfs_create_u32</refname> 13424 <refpurpose> 13425 create a debugfs file that is used to read and write an unsigned 32-bit value 13426 </refpurpose> 13427</refnamediv> 13428<refsynopsisdiv> 13429 <title>Synopsis</title> 13430 <funcsynopsis><funcprototype> 13431 <funcdef>struct dentry * <function>debugfs_create_u32 </function></funcdef> 13432 <paramdef>const char * <parameter>name</parameter></paramdef> 13433 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13434 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13435 <paramdef>u32 * <parameter>value</parameter></paramdef> 13436 </funcprototype></funcsynopsis> 13437</refsynopsisdiv> 13438<refsect1> 13439 <title>Arguments</title> 13440 <variablelist> 13441 <varlistentry> 13442 <term><parameter>name</parameter></term> 13443 <listitem> 13444 <para> 13445 a pointer to a string containing the name of the file to create. 13446 </para> 13447 </listitem> 13448 </varlistentry> 13449 <varlistentry> 13450 <term><parameter>mode</parameter></term> 13451 <listitem> 13452 <para> 13453 the permission that the file should have 13454 </para> 13455 </listitem> 13456 </varlistentry> 13457 <varlistentry> 13458 <term><parameter>parent</parameter></term> 13459 <listitem> 13460 <para> 13461 a pointer to the parent dentry for this file. This should be a 13462 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13463 file will be created in the root of the debugfs filesystem. 13464 </para> 13465 </listitem> 13466 </varlistentry> 13467 <varlistentry> 13468 <term><parameter>value</parameter></term> 13469 <listitem> 13470 <para> 13471 a pointer to the variable that the file should read to and write 13472 from. 13473 </para> 13474 </listitem> 13475 </varlistentry> 13476 </variablelist> 13477</refsect1> 13478<refsect1> 13479<title>Description</title> 13480<para> 13481 This function creates a file in debugfs with the given name that 13482 contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so 13483 set, it can be read from, and written to. 13484 </para><para> 13485 13486 This function will return a pointer to a dentry if it succeeds. This 13487 pointer must be passed to the <function>debugfs_remove</function> function when the file is 13488 to be removed (no automatic cleanup happens if your module is unloaded, 13489 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 13490 </para><para> 13491 13492 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 13493 returned. It is not wise to check for this value, but rather, check for 13494 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 13495 code. 13496</para> 13497</refsect1> 13498</refentry> 13499 13500<refentry id="API-debugfs-create-u64"> 13501<refentryinfo> 13502 <title>LINUX</title> 13503 <productname>Kernel Hackers Manual</productname> 13504 <date>July 2017</date> 13505</refentryinfo> 13506<refmeta> 13507 <refentrytitle><phrase>debugfs_create_u64</phrase></refentrytitle> 13508 <manvolnum>9</manvolnum> 13509 <refmiscinfo class="version">4.1.27</refmiscinfo> 13510</refmeta> 13511<refnamediv> 13512 <refname>debugfs_create_u64</refname> 13513 <refpurpose> 13514 create a debugfs file that is used to read and write an unsigned 64-bit value 13515 </refpurpose> 13516</refnamediv> 13517<refsynopsisdiv> 13518 <title>Synopsis</title> 13519 <funcsynopsis><funcprototype> 13520 <funcdef>struct dentry * <function>debugfs_create_u64 </function></funcdef> 13521 <paramdef>const char * <parameter>name</parameter></paramdef> 13522 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13523 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13524 <paramdef>u64 * <parameter>value</parameter></paramdef> 13525 </funcprototype></funcsynopsis> 13526</refsynopsisdiv> 13527<refsect1> 13528 <title>Arguments</title> 13529 <variablelist> 13530 <varlistentry> 13531 <term><parameter>name</parameter></term> 13532 <listitem> 13533 <para> 13534 a pointer to a string containing the name of the file to create. 13535 </para> 13536 </listitem> 13537 </varlistentry> 13538 <varlistentry> 13539 <term><parameter>mode</parameter></term> 13540 <listitem> 13541 <para> 13542 the permission that the file should have 13543 </para> 13544 </listitem> 13545 </varlistentry> 13546 <varlistentry> 13547 <term><parameter>parent</parameter></term> 13548 <listitem> 13549 <para> 13550 a pointer to the parent dentry for this file. This should be a 13551 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13552 file will be created in the root of the debugfs filesystem. 13553 </para> 13554 </listitem> 13555 </varlistentry> 13556 <varlistentry> 13557 <term><parameter>value</parameter></term> 13558 <listitem> 13559 <para> 13560 a pointer to the variable that the file should read to and write 13561 from. 13562 </para> 13563 </listitem> 13564 </varlistentry> 13565 </variablelist> 13566</refsect1> 13567<refsect1> 13568<title>Description</title> 13569<para> 13570 This function creates a file in debugfs with the given name that 13571 contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so 13572 set, it can be read from, and written to. 13573 </para><para> 13574 13575 This function will return a pointer to a dentry if it succeeds. This 13576 pointer must be passed to the <function>debugfs_remove</function> function when the file is 13577 to be removed (no automatic cleanup happens if your module is unloaded, 13578 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 13579 </para><para> 13580 13581 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 13582 returned. It is not wise to check for this value, but rather, check for 13583 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 13584 code. 13585</para> 13586</refsect1> 13587</refentry> 13588 13589<refentry id="API-debugfs-create-x8"> 13590<refentryinfo> 13591 <title>LINUX</title> 13592 <productname>Kernel Hackers Manual</productname> 13593 <date>July 2017</date> 13594</refentryinfo> 13595<refmeta> 13596 <refentrytitle><phrase>debugfs_create_x8</phrase></refentrytitle> 13597 <manvolnum>9</manvolnum> 13598 <refmiscinfo class="version">4.1.27</refmiscinfo> 13599</refmeta> 13600<refnamediv> 13601 <refname>debugfs_create_x8</refname> 13602 <refpurpose> 13603 create a debugfs file that is used to read and write an unsigned 8-bit value 13604 </refpurpose> 13605</refnamediv> 13606<refsynopsisdiv> 13607 <title>Synopsis</title> 13608 <funcsynopsis><funcprototype> 13609 <funcdef>struct dentry * <function>debugfs_create_x8 </function></funcdef> 13610 <paramdef>const char * <parameter>name</parameter></paramdef> 13611 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13612 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13613 <paramdef>u8 * <parameter>value</parameter></paramdef> 13614 </funcprototype></funcsynopsis> 13615</refsynopsisdiv> 13616<refsect1> 13617 <title>Arguments</title> 13618 <variablelist> 13619 <varlistentry> 13620 <term><parameter>name</parameter></term> 13621 <listitem> 13622 <para> 13623 a pointer to a string containing the name of the file to create. 13624 </para> 13625 </listitem> 13626 </varlistentry> 13627 <varlistentry> 13628 <term><parameter>mode</parameter></term> 13629 <listitem> 13630 <para> 13631 the permission that the file should have 13632 </para> 13633 </listitem> 13634 </varlistentry> 13635 <varlistentry> 13636 <term><parameter>parent</parameter></term> 13637 <listitem> 13638 <para> 13639 a pointer to the parent dentry for this file. This should be a 13640 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13641 file will be created in the root of the debugfs filesystem. 13642 </para> 13643 </listitem> 13644 </varlistentry> 13645 <varlistentry> 13646 <term><parameter>value</parameter></term> 13647 <listitem> 13648 <para> 13649 a pointer to the variable that the file should read to and write 13650 from. 13651 </para> 13652 </listitem> 13653 </varlistentry> 13654 </variablelist> 13655</refsect1> 13656</refentry> 13657 13658<refentry id="API-debugfs-create-x16"> 13659<refentryinfo> 13660 <title>LINUX</title> 13661 <productname>Kernel Hackers Manual</productname> 13662 <date>July 2017</date> 13663</refentryinfo> 13664<refmeta> 13665 <refentrytitle><phrase>debugfs_create_x16</phrase></refentrytitle> 13666 <manvolnum>9</manvolnum> 13667 <refmiscinfo class="version">4.1.27</refmiscinfo> 13668</refmeta> 13669<refnamediv> 13670 <refname>debugfs_create_x16</refname> 13671 <refpurpose> 13672 create a debugfs file that is used to read and write an unsigned 16-bit value 13673 </refpurpose> 13674</refnamediv> 13675<refsynopsisdiv> 13676 <title>Synopsis</title> 13677 <funcsynopsis><funcprototype> 13678 <funcdef>struct dentry * <function>debugfs_create_x16 </function></funcdef> 13679 <paramdef>const char * <parameter>name</parameter></paramdef> 13680 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13681 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13682 <paramdef>u16 * <parameter>value</parameter></paramdef> 13683 </funcprototype></funcsynopsis> 13684</refsynopsisdiv> 13685<refsect1> 13686 <title>Arguments</title> 13687 <variablelist> 13688 <varlistentry> 13689 <term><parameter>name</parameter></term> 13690 <listitem> 13691 <para> 13692 a pointer to a string containing the name of the file to create. 13693 </para> 13694 </listitem> 13695 </varlistentry> 13696 <varlistentry> 13697 <term><parameter>mode</parameter></term> 13698 <listitem> 13699 <para> 13700 the permission that the file should have 13701 </para> 13702 </listitem> 13703 </varlistentry> 13704 <varlistentry> 13705 <term><parameter>parent</parameter></term> 13706 <listitem> 13707 <para> 13708 a pointer to the parent dentry for this file. This should be a 13709 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13710 file will be created in the root of the debugfs filesystem. 13711 </para> 13712 </listitem> 13713 </varlistentry> 13714 <varlistentry> 13715 <term><parameter>value</parameter></term> 13716 <listitem> 13717 <para> 13718 a pointer to the variable that the file should read to and write 13719 from. 13720 </para> 13721 </listitem> 13722 </varlistentry> 13723 </variablelist> 13724</refsect1> 13725</refentry> 13726 13727<refentry id="API-debugfs-create-x32"> 13728<refentryinfo> 13729 <title>LINUX</title> 13730 <productname>Kernel Hackers Manual</productname> 13731 <date>July 2017</date> 13732</refentryinfo> 13733<refmeta> 13734 <refentrytitle><phrase>debugfs_create_x32</phrase></refentrytitle> 13735 <manvolnum>9</manvolnum> 13736 <refmiscinfo class="version">4.1.27</refmiscinfo> 13737</refmeta> 13738<refnamediv> 13739 <refname>debugfs_create_x32</refname> 13740 <refpurpose> 13741 create a debugfs file that is used to read and write an unsigned 32-bit value 13742 </refpurpose> 13743</refnamediv> 13744<refsynopsisdiv> 13745 <title>Synopsis</title> 13746 <funcsynopsis><funcprototype> 13747 <funcdef>struct dentry * <function>debugfs_create_x32 </function></funcdef> 13748 <paramdef>const char * <parameter>name</parameter></paramdef> 13749 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13750 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13751 <paramdef>u32 * <parameter>value</parameter></paramdef> 13752 </funcprototype></funcsynopsis> 13753</refsynopsisdiv> 13754<refsect1> 13755 <title>Arguments</title> 13756 <variablelist> 13757 <varlistentry> 13758 <term><parameter>name</parameter></term> 13759 <listitem> 13760 <para> 13761 a pointer to a string containing the name of the file to create. 13762 </para> 13763 </listitem> 13764 </varlistentry> 13765 <varlistentry> 13766 <term><parameter>mode</parameter></term> 13767 <listitem> 13768 <para> 13769 the permission that the file should have 13770 </para> 13771 </listitem> 13772 </varlistentry> 13773 <varlistentry> 13774 <term><parameter>parent</parameter></term> 13775 <listitem> 13776 <para> 13777 a pointer to the parent dentry for this file. This should be a 13778 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13779 file will be created in the root of the debugfs filesystem. 13780 </para> 13781 </listitem> 13782 </varlistentry> 13783 <varlistentry> 13784 <term><parameter>value</parameter></term> 13785 <listitem> 13786 <para> 13787 a pointer to the variable that the file should read to and write 13788 from. 13789 </para> 13790 </listitem> 13791 </varlistentry> 13792 </variablelist> 13793</refsect1> 13794</refentry> 13795 13796<refentry id="API-debugfs-create-x64"> 13797<refentryinfo> 13798 <title>LINUX</title> 13799 <productname>Kernel Hackers Manual</productname> 13800 <date>July 2017</date> 13801</refentryinfo> 13802<refmeta> 13803 <refentrytitle><phrase>debugfs_create_x64</phrase></refentrytitle> 13804 <manvolnum>9</manvolnum> 13805 <refmiscinfo class="version">4.1.27</refmiscinfo> 13806</refmeta> 13807<refnamediv> 13808 <refname>debugfs_create_x64</refname> 13809 <refpurpose> 13810 create a debugfs file that is used to read and write an unsigned 64-bit value 13811 </refpurpose> 13812</refnamediv> 13813<refsynopsisdiv> 13814 <title>Synopsis</title> 13815 <funcsynopsis><funcprototype> 13816 <funcdef>struct dentry * <function>debugfs_create_x64 </function></funcdef> 13817 <paramdef>const char * <parameter>name</parameter></paramdef> 13818 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13819 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13820 <paramdef>u64 * <parameter>value</parameter></paramdef> 13821 </funcprototype></funcsynopsis> 13822</refsynopsisdiv> 13823<refsect1> 13824 <title>Arguments</title> 13825 <variablelist> 13826 <varlistentry> 13827 <term><parameter>name</parameter></term> 13828 <listitem> 13829 <para> 13830 a pointer to a string containing the name of the file to create. 13831 </para> 13832 </listitem> 13833 </varlistentry> 13834 <varlistentry> 13835 <term><parameter>mode</parameter></term> 13836 <listitem> 13837 <para> 13838 the permission that the file should have 13839 </para> 13840 </listitem> 13841 </varlistentry> 13842 <varlistentry> 13843 <term><parameter>parent</parameter></term> 13844 <listitem> 13845 <para> 13846 a pointer to the parent dentry for this file. This should be a 13847 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13848 file will be created in the root of the debugfs filesystem. 13849 </para> 13850 </listitem> 13851 </varlistentry> 13852 <varlistentry> 13853 <term><parameter>value</parameter></term> 13854 <listitem> 13855 <para> 13856 a pointer to the variable that the file should read to and write 13857 from. 13858 </para> 13859 </listitem> 13860 </varlistentry> 13861 </variablelist> 13862</refsect1> 13863</refentry> 13864 13865<refentry id="API-debugfs-create-size-t"> 13866<refentryinfo> 13867 <title>LINUX</title> 13868 <productname>Kernel Hackers Manual</productname> 13869 <date>July 2017</date> 13870</refentryinfo> 13871<refmeta> 13872 <refentrytitle><phrase>debugfs_create_size_t</phrase></refentrytitle> 13873 <manvolnum>9</manvolnum> 13874 <refmiscinfo class="version">4.1.27</refmiscinfo> 13875</refmeta> 13876<refnamediv> 13877 <refname>debugfs_create_size_t</refname> 13878 <refpurpose> 13879 create a debugfs file that is used to read and write an size_t value 13880 </refpurpose> 13881</refnamediv> 13882<refsynopsisdiv> 13883 <title>Synopsis</title> 13884 <funcsynopsis><funcprototype> 13885 <funcdef>struct dentry * <function>debugfs_create_size_t </function></funcdef> 13886 <paramdef>const char * <parameter>name</parameter></paramdef> 13887 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13888 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13889 <paramdef>size_t * <parameter>value</parameter></paramdef> 13890 </funcprototype></funcsynopsis> 13891</refsynopsisdiv> 13892<refsect1> 13893 <title>Arguments</title> 13894 <variablelist> 13895 <varlistentry> 13896 <term><parameter>name</parameter></term> 13897 <listitem> 13898 <para> 13899 a pointer to a string containing the name of the file to create. 13900 </para> 13901 </listitem> 13902 </varlistentry> 13903 <varlistentry> 13904 <term><parameter>mode</parameter></term> 13905 <listitem> 13906 <para> 13907 the permission that the file should have 13908 </para> 13909 </listitem> 13910 </varlistentry> 13911 <varlistentry> 13912 <term><parameter>parent</parameter></term> 13913 <listitem> 13914 <para> 13915 a pointer to the parent dentry for this file. This should be a 13916 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13917 file will be created in the root of the debugfs filesystem. 13918 </para> 13919 </listitem> 13920 </varlistentry> 13921 <varlistentry> 13922 <term><parameter>value</parameter></term> 13923 <listitem> 13924 <para> 13925 a pointer to the variable that the file should read to and write 13926 from. 13927 </para> 13928 </listitem> 13929 </varlistentry> 13930 </variablelist> 13931</refsect1> 13932</refentry> 13933 13934<refentry id="API-debugfs-create-atomic-t"> 13935<refentryinfo> 13936 <title>LINUX</title> 13937 <productname>Kernel Hackers Manual</productname> 13938 <date>July 2017</date> 13939</refentryinfo> 13940<refmeta> 13941 <refentrytitle><phrase>debugfs_create_atomic_t</phrase></refentrytitle> 13942 <manvolnum>9</manvolnum> 13943 <refmiscinfo class="version">4.1.27</refmiscinfo> 13944</refmeta> 13945<refnamediv> 13946 <refname>debugfs_create_atomic_t</refname> 13947 <refpurpose> 13948 create a debugfs file that is used to read and write an atomic_t value 13949 </refpurpose> 13950</refnamediv> 13951<refsynopsisdiv> 13952 <title>Synopsis</title> 13953 <funcsynopsis><funcprototype> 13954 <funcdef>struct dentry * <function>debugfs_create_atomic_t </function></funcdef> 13955 <paramdef>const char * <parameter>name</parameter></paramdef> 13956 <paramdef>umode_t <parameter>mode</parameter></paramdef> 13957 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 13958 <paramdef>atomic_t * <parameter>value</parameter></paramdef> 13959 </funcprototype></funcsynopsis> 13960</refsynopsisdiv> 13961<refsect1> 13962 <title>Arguments</title> 13963 <variablelist> 13964 <varlistentry> 13965 <term><parameter>name</parameter></term> 13966 <listitem> 13967 <para> 13968 a pointer to a string containing the name of the file to create. 13969 </para> 13970 </listitem> 13971 </varlistentry> 13972 <varlistentry> 13973 <term><parameter>mode</parameter></term> 13974 <listitem> 13975 <para> 13976 the permission that the file should have 13977 </para> 13978 </listitem> 13979 </varlistentry> 13980 <varlistentry> 13981 <term><parameter>parent</parameter></term> 13982 <listitem> 13983 <para> 13984 a pointer to the parent dentry for this file. This should be a 13985 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 13986 file will be created in the root of the debugfs filesystem. 13987 </para> 13988 </listitem> 13989 </varlistentry> 13990 <varlistentry> 13991 <term><parameter>value</parameter></term> 13992 <listitem> 13993 <para> 13994 a pointer to the variable that the file should read to and write 13995 from. 13996 </para> 13997 </listitem> 13998 </varlistentry> 13999 </variablelist> 14000</refsect1> 14001</refentry> 14002 14003<refentry id="API-debugfs-create-bool"> 14004<refentryinfo> 14005 <title>LINUX</title> 14006 <productname>Kernel Hackers Manual</productname> 14007 <date>July 2017</date> 14008</refentryinfo> 14009<refmeta> 14010 <refentrytitle><phrase>debugfs_create_bool</phrase></refentrytitle> 14011 <manvolnum>9</manvolnum> 14012 <refmiscinfo class="version">4.1.27</refmiscinfo> 14013</refmeta> 14014<refnamediv> 14015 <refname>debugfs_create_bool</refname> 14016 <refpurpose> 14017 create a debugfs file that is used to read and write a boolean value 14018 </refpurpose> 14019</refnamediv> 14020<refsynopsisdiv> 14021 <title>Synopsis</title> 14022 <funcsynopsis><funcprototype> 14023 <funcdef>struct dentry * <function>debugfs_create_bool </function></funcdef> 14024 <paramdef>const char * <parameter>name</parameter></paramdef> 14025 <paramdef>umode_t <parameter>mode</parameter></paramdef> 14026 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 14027 <paramdef>u32 * <parameter>value</parameter></paramdef> 14028 </funcprototype></funcsynopsis> 14029</refsynopsisdiv> 14030<refsect1> 14031 <title>Arguments</title> 14032 <variablelist> 14033 <varlistentry> 14034 <term><parameter>name</parameter></term> 14035 <listitem> 14036 <para> 14037 a pointer to a string containing the name of the file to create. 14038 </para> 14039 </listitem> 14040 </varlistentry> 14041 <varlistentry> 14042 <term><parameter>mode</parameter></term> 14043 <listitem> 14044 <para> 14045 the permission that the file should have 14046 </para> 14047 </listitem> 14048 </varlistentry> 14049 <varlistentry> 14050 <term><parameter>parent</parameter></term> 14051 <listitem> 14052 <para> 14053 a pointer to the parent dentry for this file. This should be a 14054 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 14055 file will be created in the root of the debugfs filesystem. 14056 </para> 14057 </listitem> 14058 </varlistentry> 14059 <varlistentry> 14060 <term><parameter>value</parameter></term> 14061 <listitem> 14062 <para> 14063 a pointer to the variable that the file should read to and write 14064 from. 14065 </para> 14066 </listitem> 14067 </varlistentry> 14068 </variablelist> 14069</refsect1> 14070<refsect1> 14071<title>Description</title> 14072<para> 14073 This function creates a file in debugfs with the given name that 14074 contains the value of the variable <parameter>value</parameter>. If the <parameter>mode</parameter> variable is so 14075 set, it can be read from, and written to. 14076 </para><para> 14077 14078 This function will return a pointer to a dentry if it succeeds. This 14079 pointer must be passed to the <function>debugfs_remove</function> function when the file is 14080 to be removed (no automatic cleanup happens if your module is unloaded, 14081 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 14082 </para><para> 14083 14084 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 14085 returned. It is not wise to check for this value, but rather, check for 14086 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 14087 code. 14088</para> 14089</refsect1> 14090</refentry> 14091 14092<refentry id="API-debugfs-create-blob"> 14093<refentryinfo> 14094 <title>LINUX</title> 14095 <productname>Kernel Hackers Manual</productname> 14096 <date>July 2017</date> 14097</refentryinfo> 14098<refmeta> 14099 <refentrytitle><phrase>debugfs_create_blob</phrase></refentrytitle> 14100 <manvolnum>9</manvolnum> 14101 <refmiscinfo class="version">4.1.27</refmiscinfo> 14102</refmeta> 14103<refnamediv> 14104 <refname>debugfs_create_blob</refname> 14105 <refpurpose> 14106 create a debugfs file that is used to read a binary blob 14107 </refpurpose> 14108</refnamediv> 14109<refsynopsisdiv> 14110 <title>Synopsis</title> 14111 <funcsynopsis><funcprototype> 14112 <funcdef>struct dentry * <function>debugfs_create_blob </function></funcdef> 14113 <paramdef>const char * <parameter>name</parameter></paramdef> 14114 <paramdef>umode_t <parameter>mode</parameter></paramdef> 14115 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 14116 <paramdef>struct debugfs_blob_wrapper * <parameter>blob</parameter></paramdef> 14117 </funcprototype></funcsynopsis> 14118</refsynopsisdiv> 14119<refsect1> 14120 <title>Arguments</title> 14121 <variablelist> 14122 <varlistentry> 14123 <term><parameter>name</parameter></term> 14124 <listitem> 14125 <para> 14126 a pointer to a string containing the name of the file to create. 14127 </para> 14128 </listitem> 14129 </varlistentry> 14130 <varlistentry> 14131 <term><parameter>mode</parameter></term> 14132 <listitem> 14133 <para> 14134 the permission that the file should have 14135 </para> 14136 </listitem> 14137 </varlistentry> 14138 <varlistentry> 14139 <term><parameter>parent</parameter></term> 14140 <listitem> 14141 <para> 14142 a pointer to the parent dentry for this file. This should be a 14143 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 14144 file will be created in the root of the debugfs filesystem. 14145 </para> 14146 </listitem> 14147 </varlistentry> 14148 <varlistentry> 14149 <term><parameter>blob</parameter></term> 14150 <listitem> 14151 <para> 14152 a pointer to a struct debugfs_blob_wrapper which contains a pointer 14153 to the blob data and the size of the data. 14154 </para> 14155 </listitem> 14156 </varlistentry> 14157 </variablelist> 14158</refsect1> 14159<refsect1> 14160<title>Description</title> 14161<para> 14162 This function creates a file in debugfs with the given name that exports 14163 <parameter>blob</parameter>->data as a binary blob. If the <parameter>mode</parameter> variable is so set it can be 14164 read from. Writing is not supported. 14165 </para><para> 14166 14167 This function will return a pointer to a dentry if it succeeds. This 14168 pointer must be passed to the <function>debugfs_remove</function> function when the file is 14169 to be removed (no automatic cleanup happens if your module is unloaded, 14170 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 14171 </para><para> 14172 14173 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 14174 returned. It is not wise to check for this value, but rather, check for 14175 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 14176 code. 14177</para> 14178</refsect1> 14179</refentry> 14180 14181<refentry id="API-debugfs-create-u32-array"> 14182<refentryinfo> 14183 <title>LINUX</title> 14184 <productname>Kernel Hackers Manual</productname> 14185 <date>July 2017</date> 14186</refentryinfo> 14187<refmeta> 14188 <refentrytitle><phrase>debugfs_create_u32_array</phrase></refentrytitle> 14189 <manvolnum>9</manvolnum> 14190 <refmiscinfo class="version">4.1.27</refmiscinfo> 14191</refmeta> 14192<refnamediv> 14193 <refname>debugfs_create_u32_array</refname> 14194 <refpurpose> 14195 create a debugfs file that is used to read u32 array. 14196 </refpurpose> 14197</refnamediv> 14198<refsynopsisdiv> 14199 <title>Synopsis</title> 14200 <funcsynopsis><funcprototype> 14201 <funcdef>struct dentry * <function>debugfs_create_u32_array </function></funcdef> 14202 <paramdef>const char * <parameter>name</parameter></paramdef> 14203 <paramdef>umode_t <parameter>mode</parameter></paramdef> 14204 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 14205 <paramdef>u32 * <parameter>array</parameter></paramdef> 14206 <paramdef>u32 <parameter>elements</parameter></paramdef> 14207 </funcprototype></funcsynopsis> 14208</refsynopsisdiv> 14209<refsect1> 14210 <title>Arguments</title> 14211 <variablelist> 14212 <varlistentry> 14213 <term><parameter>name</parameter></term> 14214 <listitem> 14215 <para> 14216 a pointer to a string containing the name of the file to create. 14217 </para> 14218 </listitem> 14219 </varlistentry> 14220 <varlistentry> 14221 <term><parameter>mode</parameter></term> 14222 <listitem> 14223 <para> 14224 the permission that the file should have. 14225 </para> 14226 </listitem> 14227 </varlistentry> 14228 <varlistentry> 14229 <term><parameter>parent</parameter></term> 14230 <listitem> 14231 <para> 14232 a pointer to the parent dentry for this file. This should be a 14233 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 14234 file will be created in the root of the debugfs filesystem. 14235 </para> 14236 </listitem> 14237 </varlistentry> 14238 <varlistentry> 14239 <term><parameter>array</parameter></term> 14240 <listitem> 14241 <para> 14242 u32 array that provides data. 14243 </para> 14244 </listitem> 14245 </varlistentry> 14246 <varlistentry> 14247 <term><parameter>elements</parameter></term> 14248 <listitem> 14249 <para> 14250 total number of elements in the array. 14251 </para> 14252 </listitem> 14253 </varlistentry> 14254 </variablelist> 14255</refsect1> 14256<refsect1> 14257<title>Description</title> 14258<para> 14259 This function creates a file in debugfs with the given name that exports 14260 <parameter>array</parameter> as data. If the <parameter>mode</parameter> variable is so set it can be read from. 14261 Writing is not supported. Seek within the file is also not supported. 14262 Once array is created its size can not be changed. 14263 </para><para> 14264 14265 The function returns a pointer to dentry on success. If debugfs is not 14266 enabled in the kernel, the value -<constant>ENODEV</constant> will be returned. 14267</para> 14268</refsect1> 14269</refentry> 14270 14271<refentry id="API-debugfs-print-regs32"> 14272<refentryinfo> 14273 <title>LINUX</title> 14274 <productname>Kernel Hackers Manual</productname> 14275 <date>July 2017</date> 14276</refentryinfo> 14277<refmeta> 14278 <refentrytitle><phrase>debugfs_print_regs32</phrase></refentrytitle> 14279 <manvolnum>9</manvolnum> 14280 <refmiscinfo class="version">4.1.27</refmiscinfo> 14281</refmeta> 14282<refnamediv> 14283 <refname>debugfs_print_regs32</refname> 14284 <refpurpose> 14285 use seq_print to describe a set of registers 14286 </refpurpose> 14287</refnamediv> 14288<refsynopsisdiv> 14289 <title>Synopsis</title> 14290 <funcsynopsis><funcprototype> 14291 <funcdef>void <function>debugfs_print_regs32 </function></funcdef> 14292 <paramdef>struct seq_file * <parameter>s</parameter></paramdef> 14293 <paramdef>const struct debugfs_reg32 * <parameter>regs</parameter></paramdef> 14294 <paramdef>int <parameter>nregs</parameter></paramdef> 14295 <paramdef>void __iomem * <parameter>base</parameter></paramdef> 14296 <paramdef>char * <parameter>prefix</parameter></paramdef> 14297 </funcprototype></funcsynopsis> 14298</refsynopsisdiv> 14299<refsect1> 14300 <title>Arguments</title> 14301 <variablelist> 14302 <varlistentry> 14303 <term><parameter>s</parameter></term> 14304 <listitem> 14305 <para> 14306 the seq_file structure being used to generate output 14307 </para> 14308 </listitem> 14309 </varlistentry> 14310 <varlistentry> 14311 <term><parameter>regs</parameter></term> 14312 <listitem> 14313 <para> 14314 an array if struct debugfs_reg32 structures 14315 </para> 14316 </listitem> 14317 </varlistentry> 14318 <varlistentry> 14319 <term><parameter>nregs</parameter></term> 14320 <listitem> 14321 <para> 14322 the length of the above array 14323 </para> 14324 </listitem> 14325 </varlistentry> 14326 <varlistentry> 14327 <term><parameter>base</parameter></term> 14328 <listitem> 14329 <para> 14330 the base address to be used in reading the registers 14331 </para> 14332 </listitem> 14333 </varlistentry> 14334 <varlistentry> 14335 <term><parameter>prefix</parameter></term> 14336 <listitem> 14337 <para> 14338 a string to be prefixed to every output line 14339 </para> 14340 </listitem> 14341 </varlistentry> 14342 </variablelist> 14343</refsect1> 14344<refsect1> 14345<title>Description</title> 14346<para> 14347 This function outputs a text block describing the current values of 14348 some 32-bit hardware registers. It is meant to be used within debugfs 14349 files based on seq_file that need to show registers, intermixed with other 14350 information. The prefix argument may be used to specify a leading string, 14351 because some peripherals have several blocks of identical registers, 14352 for example configuration of dma channels 14353</para> 14354</refsect1> 14355</refentry> 14356 14357<refentry id="API-debugfs-create-regset32"> 14358<refentryinfo> 14359 <title>LINUX</title> 14360 <productname>Kernel Hackers Manual</productname> 14361 <date>July 2017</date> 14362</refentryinfo> 14363<refmeta> 14364 <refentrytitle><phrase>debugfs_create_regset32</phrase></refentrytitle> 14365 <manvolnum>9</manvolnum> 14366 <refmiscinfo class="version">4.1.27</refmiscinfo> 14367</refmeta> 14368<refnamediv> 14369 <refname>debugfs_create_regset32</refname> 14370 <refpurpose> 14371 create a debugfs file that returns register values 14372 </refpurpose> 14373</refnamediv> 14374<refsynopsisdiv> 14375 <title>Synopsis</title> 14376 <funcsynopsis><funcprototype> 14377 <funcdef>struct dentry * <function>debugfs_create_regset32 </function></funcdef> 14378 <paramdef>const char * <parameter>name</parameter></paramdef> 14379 <paramdef>umode_t <parameter>mode</parameter></paramdef> 14380 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 14381 <paramdef>struct debugfs_regset32 * <parameter>regset</parameter></paramdef> 14382 </funcprototype></funcsynopsis> 14383</refsynopsisdiv> 14384<refsect1> 14385 <title>Arguments</title> 14386 <variablelist> 14387 <varlistentry> 14388 <term><parameter>name</parameter></term> 14389 <listitem> 14390 <para> 14391 a pointer to a string containing the name of the file to create. 14392 </para> 14393 </listitem> 14394 </varlistentry> 14395 <varlistentry> 14396 <term><parameter>mode</parameter></term> 14397 <listitem> 14398 <para> 14399 the permission that the file should have 14400 </para> 14401 </listitem> 14402 </varlistentry> 14403 <varlistentry> 14404 <term><parameter>parent</parameter></term> 14405 <listitem> 14406 <para> 14407 a pointer to the parent dentry for this file. This should be a 14408 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 14409 file will be created in the root of the debugfs filesystem. 14410 </para> 14411 </listitem> 14412 </varlistentry> 14413 <varlistentry> 14414 <term><parameter>regset</parameter></term> 14415 <listitem> 14416 <para> 14417 a pointer to a struct debugfs_regset32, which contains a pointer 14418 to an array of register definitions, the array size and the base 14419 address where the register bank is to be found. 14420 </para> 14421 </listitem> 14422 </varlistentry> 14423 </variablelist> 14424</refsect1> 14425<refsect1> 14426<title>Description</title> 14427<para> 14428 This function creates a file in debugfs with the given name that reports 14429 the names and values of a set of 32-bit registers. If the <parameter>mode</parameter> variable 14430 is so set it can be read from. Writing is not supported. 14431 </para><para> 14432 14433 This function will return a pointer to a dentry if it succeeds. This 14434 pointer must be passed to the <function>debugfs_remove</function> function when the file is 14435 to be removed (no automatic cleanup happens if your module is unloaded, 14436 you are responsible here.) If an error occurs, <constant>NULL</constant> will be returned. 14437 </para><para> 14438 14439 If debugfs is not enabled in the kernel, the value -<constant>ENODEV</constant> will be 14440 returned. It is not wise to check for this value, but rather, check for 14441 <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling 14442 code. 14443</para> 14444</refsect1> 14445</refentry> 14446 14447<refentry id="API-debugfs-create-devm-seqfile"> 14448<refentryinfo> 14449 <title>LINUX</title> 14450 <productname>Kernel Hackers Manual</productname> 14451 <date>July 2017</date> 14452</refentryinfo> 14453<refmeta> 14454 <refentrytitle><phrase>debugfs_create_devm_seqfile</phrase></refentrytitle> 14455 <manvolnum>9</manvolnum> 14456 <refmiscinfo class="version">4.1.27</refmiscinfo> 14457</refmeta> 14458<refnamediv> 14459 <refname>debugfs_create_devm_seqfile</refname> 14460 <refpurpose> 14461 create a debugfs file that is bound to device. 14462 </refpurpose> 14463</refnamediv> 14464<refsynopsisdiv> 14465 <title>Synopsis</title> 14466 <funcsynopsis><funcprototype> 14467 <funcdef>struct dentry * <function>debugfs_create_devm_seqfile </function></funcdef> 14468 <paramdef>struct device * <parameter>dev</parameter></paramdef> 14469 <paramdef>const char * <parameter>name</parameter></paramdef> 14470 <paramdef>struct dentry * <parameter>parent</parameter></paramdef> 14471 <paramdef>int (*<parameter>read_fn</parameter>) 14472 <funcparams>struct seq_file *s, void *data</funcparams></paramdef> 14473 </funcprototype></funcsynopsis> 14474</refsynopsisdiv> 14475<refsect1> 14476 <title>Arguments</title> 14477 <variablelist> 14478 <varlistentry> 14479 <term><parameter>dev</parameter></term> 14480 <listitem> 14481 <para> 14482 device related to this debugfs file. 14483 </para> 14484 </listitem> 14485 </varlistentry> 14486 <varlistentry> 14487 <term><parameter>name</parameter></term> 14488 <listitem> 14489 <para> 14490 name of the debugfs file. 14491 </para> 14492 </listitem> 14493 </varlistentry> 14494 <varlistentry> 14495 <term><parameter>parent</parameter></term> 14496 <listitem> 14497 <para> 14498 a pointer to the parent dentry for this file. This should be a 14499 directory dentry if set. If this parameter is <constant>NULL</constant>, then the 14500 file will be created in the root of the debugfs filesystem. 14501 </para> 14502 </listitem> 14503 </varlistentry> 14504 <varlistentry> 14505 <term><parameter>read_fn</parameter></term> 14506 <listitem> 14507 <para> 14508 function pointer called to print the seq_file content. 14509 </para> 14510 </listitem> 14511 </varlistentry> 14512 </variablelist> 14513</refsect1> 14514</refentry> 14515 14516 </sect1> 14517 </chapter> 14518 14519 <chapter id="LinuxJDBAPI"> 14520 <chapterinfo> 14521 <title>The Linux Journalling API</title> 14522 14523 <authorgroup> 14524 <author> 14525 <firstname>Roger</firstname> 14526 <surname>Gammans</surname> 14527 <affiliation> 14528 <address> 14529 <email>rgammans@computer-surgery.co.uk</email> 14530 </address> 14531 </affiliation> 14532 </author> 14533 </authorgroup> 14534 14535 <authorgroup> 14536 <author> 14537 <firstname>Stephen</firstname> 14538 <surname>Tweedie</surname> 14539 <affiliation> 14540 <address> 14541 <email>sct@redhat.com</email> 14542 </address> 14543 </affiliation> 14544 </author> 14545 </authorgroup> 14546 14547 <copyright> 14548 <year>2002</year> 14549 <holder>Roger Gammans</holder> 14550 </copyright> 14551 </chapterinfo> 14552 14553 <title>The Linux Journalling API</title> 14554 14555 <sect1 id="journaling_overview"> 14556 <title>Overview</title> 14557 <sect2 id="journaling_details"> 14558 <title>Details</title> 14559<para> 14560The journalling layer is easy to use. You need to 14561first of all create a journal_t data structure. There are 14562two calls to do this dependent on how you decide to allocate the physical 14563media on which the journal resides. The journal_init_inode() call 14564is for journals stored in filesystem inodes, or the journal_init_dev() 14565call can be use for journal stored on a raw device (in a continuous range 14566of blocks). A journal_t is a typedef for a struct pointer, so when 14567you are finally finished make sure you call journal_destroy() on it 14568to free up any used kernel memory. 14569</para> 14570 14571<para> 14572Once you have got your journal_t object you need to 'mount' or load the journal 14573file, unless of course you haven't initialised it yet - in which case you 14574need to call journal_create(). 14575</para> 14576 14577<para> 14578Most of the time however your journal file will already have been created, but 14579before you load it you must call journal_wipe() to empty the journal file. 14580Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the 14581job of the client file system to detect this and skip the call to journal_wipe(). 14582</para> 14583 14584<para> 14585In either case the next call should be to journal_load() which prepares the 14586journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery() 14587for you if it detects any outstanding transactions in the journal and similarly 14588journal_load() will call journal_recover() if necessary. 14589I would advise reading fs/ext3/super.c for examples on this stage. 14590[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly 14591complicate the API. Or isn't a good idea for the journal layer to hide 14592dirty mounts from the client fs] 14593</para> 14594 14595<para> 14596Now you can go ahead and start modifying the underlying 14597filesystem. Almost. 14598</para> 14599 14600<para> 14601 14602You still need to actually journal your filesystem changes, this 14603is done by wrapping them into transactions. Additionally you 14604also need to wrap the modification of each of the buffers 14605with calls to the journal layer, so it knows what the modifications 14606you are actually making are. To do this use journal_start() which 14607returns a transaction handle. 14608</para> 14609 14610<para> 14611journal_start() 14612and its counterpart journal_stop(), which indicates the end of a transaction 14613are nestable calls, so you can reenter a transaction if necessary, 14614but remember you must call journal_stop() the same number of times as 14615journal_start() before the transaction is completed (or more accurately 14616leaves the update phase). Ext3/VFS makes use of this feature to simplify 14617quota support. 14618</para> 14619 14620<para> 14621Inside each transaction you need to wrap the modifications to the 14622individual buffers (blocks). Before you start to modify a buffer you 14623need to call journal_get_{create,write,undo}_access() as appropriate, 14624this allows the journalling layer to copy the unmodified data if it 14625needs to. After all the buffer may be part of a previously uncommitted 14626transaction. 14627At this point you are at last ready to modify a buffer, and once 14628you are have done so you need to call journal_dirty_{meta,}data(). 14629Or if you've asked for access to a buffer you now know is now longer 14630required to be pushed back on the device you can call journal_forget() 14631in much the same way as you might have used bforget() in the past. 14632</para> 14633 14634<para> 14635A journal_flush() may be called at any time to commit and checkpoint 14636all your transactions. 14637</para> 14638 14639<para> 14640Then at umount time , in your put_super() you can then call journal_destroy() 14641to clean up your in-core journal object. 14642</para> 14643 14644<para> 14645Unfortunately there a couple of ways the journal layer can cause a deadlock. 14646The first thing to note is that each task can only have 14647a single outstanding transaction at any one time, remember nothing 14648commits until the outermost journal_stop(). This means 14649you must complete the transaction at the end of each file/inode/address 14650etc. operation you perform, so that the journalling system isn't re-entered 14651on another journal. Since transactions can't be nested/batched 14652across differing journals, and another filesystem other than 14653yours (say ext3) may be modified in a later syscall. 14654</para> 14655 14656<para> 14657The second case to bear in mind is that journal_start() can 14658block if there isn't enough space in the journal for your transaction 14659(based on the passed nblocks param) - when it blocks it merely(!) needs to 14660wait for transactions to complete and be committed from other tasks, 14661so essentially we are waiting for journal_stop(). So to avoid 14662deadlocks you must treat journal_start/stop() as if they 14663were semaphores and include them in your semaphore ordering rules to prevent 14664deadlocks. Note that journal_extend() has similar blocking behaviour to 14665journal_start() so you can deadlock here just as easily as on journal_start(). 14666</para> 14667 14668<para> 14669Try to reserve the right number of blocks the first time. ;-). This will 14670be the maximum number of blocks you are going to touch in this transaction. 14671I advise having a look at at least ext3_jbd.h to see the basis on which 14672ext3 uses to make these decisions. 14673</para> 14674 14675<para> 14676Another wriggle to watch out for is your on-disk block allocation strategy. 14677why? Because, if you undo a delete, you need to ensure you haven't reused any 14678of the freed blocks in a later transaction. One simple way of doing this 14679is make sure any blocks you allocate only have checkpointed transactions 14680listed against them. Ext3 does this in ext3_test_allocatable(). 14681</para> 14682 14683<para> 14684Lock is also providing through journal_{un,}lock_updates(), 14685ext3 uses this when it wants a window with a clean and stable fs for a moment. 14686eg. 14687</para> 14688 14689<programlisting> 14690 14691 journal_lock_updates() //stop new stuff happening.. 14692 journal_flush() // checkpoint everything. 14693 ..do stuff on stable fs 14694 journal_unlock_updates() // carry on with filesystem use. 14695</programlisting> 14696 14697<para> 14698The opportunities for abuse and DOS attacks with this should be obvious, 14699if you allow unprivileged userspace to trigger codepaths containing these 14700calls. 14701</para> 14702 14703<para> 14704A new feature of jbd since 2.5.25 is commit callbacks with the new 14705journal_callback_set() function you can now ask the journalling layer 14706to call you back when the transaction is finally committed to disk, so that 14707you can do some of your own management. The key to this is the journal_callback 14708struct, this maintains the internal callback information but you can 14709extend it like this:- 14710</para> 14711<programlisting> 14712 struct myfs_callback_s { 14713 //Data structure element required by jbd.. 14714 struct journal_callback for_jbd; 14715 // Stuff for myfs allocated together. 14716 myfs_inode* i_commited; 14717 14718 } 14719</programlisting> 14720 14721<para> 14722this would be useful if you needed to know when data was committed to a 14723particular inode. 14724</para> 14725 14726 </sect2> 14727 14728 <sect2 id="jbd_summary"> 14729 <title>Summary</title> 14730<para> 14731Using the journal is a matter of wrapping the different context changes, 14732being each mount, each modification (transaction) and each changed buffer 14733to tell the journalling layer about them. 14734</para> 14735 14736<para> 14737Here is a some pseudo code to give you an idea of how it works, as 14738an example. 14739</para> 14740 14741<programlisting> 14742 journal_t* my_jnrl = journal_create(); 14743 journal_init_{dev,inode}(jnrl,...) 14744 if (clean) journal_wipe(); 14745 journal_load(); 14746 14747 foreach(transaction) { /*transactions must be 14748 completed before 14749 a syscall returns to 14750 userspace*/ 14751 14752 handle_t * xct=journal_start(my_jnrl); 14753 foreach(bh) { 14754 journal_get_{create,write,undo}_access(xact,bh); 14755 if ( myfs_modify(bh) ) { /* returns true 14756 if makes changes */ 14757 journal_dirty_{meta,}data(xact,bh); 14758 } else { 14759 journal_forget(bh); 14760 } 14761 } 14762 journal_stop(xct); 14763 } 14764 journal_destroy(my_jrnl); 14765</programlisting> 14766 </sect2> 14767 14768 </sect1> 14769 14770 <sect1 id="data_types"> 14771 <title>Data Types</title> 14772 <para> 14773 The journalling layer uses typedefs to 'hide' the concrete definitions 14774 of the structures used. As a client of the JBD layer you can 14775 just rely on the using the pointer as a magic cookie of some sort. 14776 14777 Obviously the hiding is not enforced as this is 'C'. 14778 </para> 14779 <sect2 id="structures"><title>Structures</title> 14780<!-- include/linux/jbd.h --> 14781<refentry id="API-typedef-handle-t"> 14782<refentryinfo> 14783 <title>LINUX</title> 14784 <productname>Kernel Hackers Manual</productname> 14785 <date>July 2017</date> 14786</refentryinfo> 14787<refmeta> 14788 <refentrytitle><phrase>typedef handle_t</phrase></refentrytitle> 14789 <manvolnum>9</manvolnum> 14790</refmeta> 14791<refnamediv> 14792 <refname>typedef handle_t</refname> 14793 <refpurpose> 14794 The handle_t type represents a single atomic update being performed by some process. 14795 </refpurpose> 14796</refnamediv> 14797<refsynopsisdiv> 14798 <title>Synopsis</title> 14799 <synopsis>typedef handle_t;</synopsis> 14800</refsynopsisdiv> 14801<refsect1> 14802<title>Description</title> 14803<para> 14804 </para><para> 14805 14806 All filesystem modifications made by the process go 14807 through this handle. Recursive operations (such as quota operations) 14808 are gathered into a single update. 14809 </para><para> 14810 14811 The buffer credits field is used to account for journaled buffers 14812 being modified by the running process. To ensure that there is 14813 enough log space for all outstanding operations, we need to limit the 14814 number of outstanding buffers possible at any time. When the 14815 operation completes, any buffer credits not used are credited back to 14816 the transaction, so that at all times we know how many buffers the 14817 outstanding updates on a transaction might possibly touch. 14818 </para><para> 14819 14820 This is an opaque datatype. 14821</para> 14822</refsect1> 14823</refentry> 14824 14825<refentry id="API-typedef-journal-t"> 14826<refentryinfo> 14827 <title>LINUX</title> 14828 <productname>Kernel Hackers Manual</productname> 14829 <date>July 2017</date> 14830</refentryinfo> 14831<refmeta> 14832 <refentrytitle><phrase>typedef journal_t</phrase></refentrytitle> 14833 <manvolnum>9</manvolnum> 14834</refmeta> 14835<refnamediv> 14836 <refname>typedef journal_t</refname> 14837 <refpurpose> 14838 The journal_t maintains all of the journaling state information for a single filesystem. 14839 </refpurpose> 14840</refnamediv> 14841<refsynopsisdiv> 14842 <title>Synopsis</title> 14843 <synopsis>typedef journal_t;</synopsis> 14844</refsynopsisdiv> 14845<refsect1> 14846<title>Description</title> 14847<para> 14848 </para><para> 14849 14850 journal_t is linked to from the fs superblock structure. 14851 </para><para> 14852 14853 We use the journal_t to keep track of all outstanding transaction 14854 activity on the filesystem, and to manage the state of the log 14855 writing process. 14856 </para><para> 14857 14858 This is an opaque datatype. 14859</para> 14860</refsect1> 14861</refentry> 14862 14863<refentry id="API-struct-handle-s"> 14864<refentryinfo> 14865 <title>LINUX</title> 14866 <productname>Kernel Hackers Manual</productname> 14867 <date>July 2017</date> 14868</refentryinfo> 14869<refmeta> 14870 <refentrytitle><phrase>struct handle_s</phrase></refentrytitle> 14871 <manvolnum>9</manvolnum> 14872 <refmiscinfo class="version">4.1.27</refmiscinfo> 14873</refmeta> 14874<refnamediv> 14875 <refname>struct handle_s</refname> 14876 <refpurpose> 14877 this is the concrete type associated with handle_t. 14878 </refpurpose> 14879</refnamediv> 14880<refsynopsisdiv> 14881 <title>Synopsis</title> 14882 <programlisting> 14883struct handle_s { 14884 transaction_t * h_transaction; 14885 int h_buffer_credits; 14886 int h_ref; 14887 int h_err; 14888 unsigned int h_sync:1; 14889 unsigned int h_jdata:1; 14890 unsigned int h_aborted:1; 14891#ifdef CONFIG_DEBUG_LOCK_ALLOC 14892 struct lockdep_map h_lockdep_map; 14893#endif 14894}; </programlisting> 14895</refsynopsisdiv> 14896 <refsect1> 14897 <title>Members</title> 14898 <variablelist> 14899 <varlistentry> <term>h_transaction</term> 14900 <listitem><para> 14901 Which compound transaction is this update a part of? 14902 </para></listitem> 14903 </varlistentry> 14904 <varlistentry> <term>h_buffer_credits</term> 14905 <listitem><para> 14906 Number of remaining buffers we are allowed to dirty. 14907 </para></listitem> 14908 </varlistentry> 14909 <varlistentry> <term>h_ref</term> 14910 <listitem><para> 14911 Reference count on this handle 14912 </para></listitem> 14913 </varlistentry> 14914 <varlistentry> <term>h_err</term> 14915 <listitem><para> 14916 Field for caller's use to track errors through large fs operations 14917 </para></listitem> 14918 </varlistentry> 14919 <varlistentry> <term>h_sync</term> 14920 <listitem><para> 14921 flag for sync-on-close 14922 </para></listitem> 14923 </varlistentry> 14924 <varlistentry> <term>h_jdata</term> 14925 <listitem><para> 14926 flag to force data journaling 14927 </para></listitem> 14928 </varlistentry> 14929 <varlistentry> <term>h_aborted</term> 14930 <listitem><para> 14931 flag indicating fatal error on handle 14932 </para></listitem> 14933 </varlistentry> 14934 <varlistentry> <term>h_lockdep_map</term> 14935 <listitem><para> 14936 lockdep info for debugging lock problems 14937 </para></listitem> 14938 </varlistentry> 14939 </variablelist> 14940 </refsect1> 14941</refentry> 14942 14943<refentry id="API-struct-journal-s"> 14944<refentryinfo> 14945 <title>LINUX</title> 14946 <productname>Kernel Hackers Manual</productname> 14947 <date>July 2017</date> 14948</refentryinfo> 14949<refmeta> 14950 <refentrytitle><phrase>struct journal_s</phrase></refentrytitle> 14951 <manvolnum>9</manvolnum> 14952 <refmiscinfo class="version">4.1.27</refmiscinfo> 14953</refmeta> 14954<refnamediv> 14955 <refname>struct journal_s</refname> 14956 <refpurpose> 14957 this is the concrete type associated with journal_t. 14958 </refpurpose> 14959</refnamediv> 14960<refsynopsisdiv> 14961 <title>Synopsis</title> 14962 <programlisting> 14963struct journal_s { 14964 unsigned long j_flags; 14965 int j_errno; 14966 struct buffer_head * j_sb_buffer; 14967 journal_superblock_t * j_superblock; 14968 int j_format_version; 14969 spinlock_t j_state_lock; 14970 int j_barrier_count; 14971 transaction_t * j_running_transaction; 14972 transaction_t * j_committing_transaction; 14973 transaction_t * j_checkpoint_transactions; 14974 wait_queue_head_t j_wait_transaction_locked; 14975 wait_queue_head_t j_wait_logspace; 14976 wait_queue_head_t j_wait_done_commit; 14977 wait_queue_head_t j_wait_checkpoint; 14978 wait_queue_head_t j_wait_commit; 14979 wait_queue_head_t j_wait_updates; 14980 struct mutex j_checkpoint_mutex; 14981 unsigned int j_head; 14982 unsigned int j_tail; 14983 unsigned int j_free; 14984 unsigned int j_first; 14985 unsigned int j_last; 14986 struct block_device * j_dev; 14987 int j_blocksize; 14988 unsigned int j_blk_offset; 14989 struct block_device * j_fs_dev; 14990 unsigned int j_maxlen; 14991 spinlock_t j_list_lock; 14992 struct inode * j_inode; 14993 tid_t j_tail_sequence; 14994 tid_t j_transaction_sequence; 14995 tid_t j_commit_sequence; 14996 tid_t j_commit_request; 14997 tid_t j_commit_waited; 14998 __u8 j_uuid[16]; 14999 struct task_struct * j_task; 15000 int j_max_transaction_buffers; 15001 unsigned long j_commit_interval; 15002 struct timer_list j_commit_timer; 15003 spinlock_t j_revoke_lock; 15004 struct jbd_revoke_table_s * j_revoke; 15005 struct jbd_revoke_table_s * j_revoke_table[2]; 15006 struct buffer_head ** j_wbuf; 15007 int j_wbufsize; 15008 pid_t j_last_sync_writer; 15009 u64 j_average_commit_time; 15010 void * j_private; 15011}; </programlisting> 15012</refsynopsisdiv> 15013 <refsect1> 15014 <title>Members</title> 15015 <variablelist> 15016 <varlistentry> <term>j_flags</term> 15017 <listitem><para> 15018 General journaling state flags 15019 </para></listitem> 15020 </varlistentry> 15021 <varlistentry> <term>j_errno</term> 15022 <listitem><para> 15023 Is there an outstanding uncleared error on the journal (from a 15024 prior abort)? 15025 </para></listitem> 15026 </varlistentry> 15027 <varlistentry> <term>j_sb_buffer</term> 15028 <listitem><para> 15029 First part of superblock buffer 15030 </para></listitem> 15031 </varlistentry> 15032 <varlistentry> <term>j_superblock</term> 15033 <listitem><para> 15034 Second part of superblock buffer 15035 </para></listitem> 15036 </varlistentry> 15037 <varlistentry> <term>j_format_version</term> 15038 <listitem><para> 15039 Version of the superblock format 15040 </para></listitem> 15041 </varlistentry> 15042 <varlistentry> <term>j_state_lock</term> 15043 <listitem><para> 15044 Protect the various scalars in the journal 15045 </para></listitem> 15046 </varlistentry> 15047 <varlistentry> <term>j_barrier_count</term> 15048 <listitem><para> 15049 Number of processes waiting to create a barrier lock 15050 </para></listitem> 15051 </varlistentry> 15052 <varlistentry> <term>j_running_transaction</term> 15053 <listitem><para> 15054 The current running transaction.. 15055 </para></listitem> 15056 </varlistentry> 15057 <varlistentry> <term>j_committing_transaction</term> 15058 <listitem><para> 15059 the transaction we are pushing to disk 15060 </para></listitem> 15061 </varlistentry> 15062 <varlistentry> <term>j_checkpoint_transactions</term> 15063 <listitem><para> 15064 a linked circular list of all transactions 15065 waiting for checkpointing 15066 </para></listitem> 15067 </varlistentry> 15068 <varlistentry> <term>j_wait_transaction_locked</term> 15069 <listitem><para> 15070 Wait queue for waiting for a locked transaction 15071 to start committing, or for a barrier lock to be released 15072 </para></listitem> 15073 </varlistentry> 15074 <varlistentry> <term>j_wait_logspace</term> 15075 <listitem><para> 15076 Wait queue for waiting for checkpointing to complete 15077 </para></listitem> 15078 </varlistentry> 15079 <varlistentry> <term>j_wait_done_commit</term> 15080 <listitem><para> 15081 Wait queue for waiting for commit to complete 15082 </para></listitem> 15083 </varlistentry> 15084 <varlistentry> <term>j_wait_checkpoint</term> 15085 <listitem><para> 15086 Wait queue to trigger checkpointing 15087 </para></listitem> 15088 </varlistentry> 15089 <varlistentry> <term>j_wait_commit</term> 15090 <listitem><para> 15091 Wait queue to trigger commit 15092 </para></listitem> 15093 </varlistentry> 15094 <varlistentry> <term>j_wait_updates</term> 15095 <listitem><para> 15096 Wait queue to wait for updates to complete 15097 </para></listitem> 15098 </varlistentry> 15099 <varlistentry> <term>j_checkpoint_mutex</term> 15100 <listitem><para> 15101 Mutex for locking against concurrent checkpoints 15102 </para></listitem> 15103 </varlistentry> 15104 <varlistentry> <term>j_head</term> 15105 <listitem><para> 15106 Journal head - identifies the first unused block in the journal 15107 </para></listitem> 15108 </varlistentry> 15109 <varlistentry> <term>j_tail</term> 15110 <listitem><para> 15111 Journal tail - identifies the oldest still-used block in the 15112 journal. 15113 </para></listitem> 15114 </varlistentry> 15115 <varlistentry> <term>j_free</term> 15116 <listitem><para> 15117 Journal free - how many free blocks are there in the journal? 15118 </para></listitem> 15119 </varlistentry> 15120 <varlistentry> <term>j_first</term> 15121 <listitem><para> 15122 The block number of the first usable block 15123 </para></listitem> 15124 </varlistentry> 15125 <varlistentry> <term>j_last</term> 15126 <listitem><para> 15127 The block number one beyond the last usable block 15128 </para></listitem> 15129 </varlistentry> 15130 <varlistentry> <term>j_dev</term> 15131 <listitem><para> 15132 Device where we store the journal 15133 </para></listitem> 15134 </varlistentry> 15135 <varlistentry> <term>j_blocksize</term> 15136 <listitem><para> 15137 blocksize for the location where we store the journal. 15138 </para></listitem> 15139 </varlistentry> 15140 <varlistentry> <term>j_blk_offset</term> 15141 <listitem><para> 15142 starting block offset for into the device where we store the 15143 journal 15144 </para></listitem> 15145 </varlistentry> 15146 <varlistentry> <term>j_fs_dev</term> 15147 <listitem><para> 15148 Device which holds the client fs. For internal journal this will 15149 be equal to j_dev 15150 </para></listitem> 15151 </varlistentry> 15152 <varlistentry> <term>j_maxlen</term> 15153 <listitem><para> 15154 Total maximum capacity of the journal region on disk. 15155 </para></listitem> 15156 </varlistentry> 15157 <varlistentry> <term>j_list_lock</term> 15158 <listitem><para> 15159 Protects the buffer lists and internal buffer state. 15160 </para></listitem> 15161 </varlistentry> 15162 <varlistentry> <term>j_inode</term> 15163 <listitem><para> 15164 Optional inode where we store the journal. If present, all journal 15165 block numbers are mapped into this inode via <function>bmap</function>. 15166 </para></listitem> 15167 </varlistentry> 15168 <varlistentry> <term>j_tail_sequence</term> 15169 <listitem><para> 15170 Sequence number of the oldest transaction in the log 15171 </para></listitem> 15172 </varlistentry> 15173 <varlistentry> <term>j_transaction_sequence</term> 15174 <listitem><para> 15175 Sequence number of the next transaction to grant 15176 </para></listitem> 15177 </varlistentry> 15178 <varlistentry> <term>j_commit_sequence</term> 15179 <listitem><para> 15180 Sequence number of the most recently committed 15181 transaction 15182 </para></listitem> 15183 </varlistentry> 15184 <varlistentry> <term>j_commit_request</term> 15185 <listitem><para> 15186 Sequence number of the most recent transaction wanting 15187 commit 15188 </para></listitem> 15189 </varlistentry> 15190 <varlistentry> <term>j_commit_waited</term> 15191 <listitem><para> 15192 Sequence number of the most recent transaction someone 15193 is waiting for to commit. 15194 </para></listitem> 15195 </varlistentry> 15196 <varlistentry> <term>j_uuid[16]</term> 15197 <listitem><para> 15198 Uuid of client object. 15199 </para></listitem> 15200 </varlistentry> 15201 <varlistentry> <term>j_task</term> 15202 <listitem><para> 15203 Pointer to the current commit thread for this journal 15204 </para></listitem> 15205 </varlistentry> 15206 <varlistentry> <term>j_max_transaction_buffers</term> 15207 <listitem><para> 15208 Maximum number of metadata buffers to allow in a 15209 single compound commit transaction 15210 </para></listitem> 15211 </varlistentry> 15212 <varlistentry> <term>j_commit_interval</term> 15213 <listitem><para> 15214 What is the maximum transaction lifetime before we begin 15215 a commit? 15216 </para></listitem> 15217 </varlistentry> 15218 <varlistentry> <term>j_commit_timer</term> 15219 <listitem><para> 15220 The timer used to wakeup the commit thread 15221 </para></listitem> 15222 </varlistentry> 15223 <varlistentry> <term>j_revoke_lock</term> 15224 <listitem><para> 15225 Protect the revoke table 15226 </para></listitem> 15227 </varlistentry> 15228 <varlistentry> <term>j_revoke</term> 15229 <listitem><para> 15230 The revoke table - maintains the list of revoked blocks in the 15231 current transaction. 15232 </para></listitem> 15233 </varlistentry> 15234 <varlistentry> <term>j_revoke_table[2]</term> 15235 <listitem><para> 15236 alternate revoke tables for j_revoke 15237 </para></listitem> 15238 </varlistentry> 15239 <varlistentry> <term>j_wbuf</term> 15240 <listitem><para> 15241 array of buffer_heads for journal_commit_transaction 15242 </para></listitem> 15243 </varlistentry> 15244 <varlistentry> <term>j_wbufsize</term> 15245 <listitem><para> 15246 maximum number of buffer_heads allowed in j_wbuf, the 15247 number that will fit in j_blocksize 15248 </para></listitem> 15249 </varlistentry> 15250 <varlistentry> <term>j_last_sync_writer</term> 15251 <listitem><para> 15252 most recent pid which did a synchronous write 15253 </para></listitem> 15254 </varlistentry> 15255 <varlistentry> <term>j_average_commit_time</term> 15256 <listitem><para> 15257 the average amount of time in nanoseconds it 15258 takes to commit a transaction to the disk. 15259 </para></listitem> 15260 </varlistentry> 15261 <varlistentry> <term>j_private</term> 15262 <listitem><para> 15263 An opaque pointer to fs-private information. 15264 </para></listitem> 15265 </varlistentry> 15266 </variablelist> 15267 </refsect1> 15268</refentry> 15269 15270 </sect2> 15271 </sect1> 15272 15273 <sect1 id="functions"> 15274 <title>Functions</title> 15275 <para> 15276 The functions here are split into two groups those that 15277 affect a journal as a whole, and those which are used to 15278 manage transactions 15279 </para> 15280 <sect2 id="journal_level"><title>Journal Level</title> 15281<!-- fs/jbd/journal.c --> 15282<refentry id="API-journal-init-dev"> 15283<refentryinfo> 15284 <title>LINUX</title> 15285 <productname>Kernel Hackers Manual</productname> 15286 <date>July 2017</date> 15287</refentryinfo> 15288<refmeta> 15289 <refentrytitle><phrase>journal_init_dev</phrase></refentrytitle> 15290 <manvolnum>9</manvolnum> 15291 <refmiscinfo class="version">4.1.27</refmiscinfo> 15292</refmeta> 15293<refnamediv> 15294 <refname>journal_init_dev</refname> 15295 <refpurpose> 15296 creates and initialises a journal structure 15297 </refpurpose> 15298</refnamediv> 15299<refsynopsisdiv> 15300 <title>Synopsis</title> 15301 <funcsynopsis><funcprototype> 15302 <funcdef>journal_t * <function>journal_init_dev </function></funcdef> 15303 <paramdef>struct block_device * <parameter>bdev</parameter></paramdef> 15304 <paramdef>struct block_device * <parameter>fs_dev</parameter></paramdef> 15305 <paramdef>int <parameter>start</parameter></paramdef> 15306 <paramdef>int <parameter>len</parameter></paramdef> 15307 <paramdef>int <parameter>blocksize</parameter></paramdef> 15308 </funcprototype></funcsynopsis> 15309</refsynopsisdiv> 15310<refsect1> 15311 <title>Arguments</title> 15312 <variablelist> 15313 <varlistentry> 15314 <term><parameter>bdev</parameter></term> 15315 <listitem> 15316 <para> 15317 Block device on which to create the journal 15318 </para> 15319 </listitem> 15320 </varlistentry> 15321 <varlistentry> 15322 <term><parameter>fs_dev</parameter></term> 15323 <listitem> 15324 <para> 15325 Device which hold journalled filesystem for this journal. 15326 </para> 15327 </listitem> 15328 </varlistentry> 15329 <varlistentry> 15330 <term><parameter>start</parameter></term> 15331 <listitem> 15332 <para> 15333 Block nr Start of journal. 15334 </para> 15335 </listitem> 15336 </varlistentry> 15337 <varlistentry> 15338 <term><parameter>len</parameter></term> 15339 <listitem> 15340 <para> 15341 Length of the journal in blocks. 15342 </para> 15343 </listitem> 15344 </varlistentry> 15345 <varlistentry> 15346 <term><parameter>blocksize</parameter></term> 15347 <listitem> 15348 <para> 15349 blocksize of journalling device 15350 </para> 15351 </listitem> 15352 </varlistentry> 15353 </variablelist> 15354</refsect1> 15355<refsect1> 15356<title>Returns</title> 15357<para> 15358 a newly created journal_t * 15359 </para><para> 15360 15361 journal_init_dev creates a journal which maps a fixed contiguous 15362 range of blocks on an arbitrary block device. 15363</para> 15364</refsect1> 15365</refentry> 15366 15367<refentry id="API-journal-init-inode"> 15368<refentryinfo> 15369 <title>LINUX</title> 15370 <productname>Kernel Hackers Manual</productname> 15371 <date>July 2017</date> 15372</refentryinfo> 15373<refmeta> 15374 <refentrytitle><phrase>journal_init_inode</phrase></refentrytitle> 15375 <manvolnum>9</manvolnum> 15376 <refmiscinfo class="version">4.1.27</refmiscinfo> 15377</refmeta> 15378<refnamediv> 15379 <refname>journal_init_inode</refname> 15380 <refpurpose> 15381 creates a journal which maps to a inode. 15382 </refpurpose> 15383</refnamediv> 15384<refsynopsisdiv> 15385 <title>Synopsis</title> 15386 <funcsynopsis><funcprototype> 15387 <funcdef>journal_t * <function>journal_init_inode </function></funcdef> 15388 <paramdef>struct inode * <parameter>inode</parameter></paramdef> 15389 </funcprototype></funcsynopsis> 15390</refsynopsisdiv> 15391<refsect1> 15392 <title>Arguments</title> 15393 <variablelist> 15394 <varlistentry> 15395 <term><parameter>inode</parameter></term> 15396 <listitem> 15397 <para> 15398 An inode to create the journal in 15399 </para> 15400 </listitem> 15401 </varlistentry> 15402 </variablelist> 15403</refsect1> 15404<refsect1> 15405<title>Description</title> 15406<para> 15407 journal_init_inode creates a journal which maps an on-disk inode as 15408 the journal. The inode must exist already, must support <function>bmap</function> and 15409 must have all data blocks preallocated. 15410</para> 15411</refsect1> 15412</refentry> 15413 15414<refentry id="API-journal-create"> 15415<refentryinfo> 15416 <title>LINUX</title> 15417 <productname>Kernel Hackers Manual</productname> 15418 <date>July 2017</date> 15419</refentryinfo> 15420<refmeta> 15421 <refentrytitle><phrase>journal_create</phrase></refentrytitle> 15422 <manvolnum>9</manvolnum> 15423 <refmiscinfo class="version">4.1.27</refmiscinfo> 15424</refmeta> 15425<refnamediv> 15426 <refname>journal_create</refname> 15427 <refpurpose> 15428 Initialise the new journal file 15429 </refpurpose> 15430</refnamediv> 15431<refsynopsisdiv> 15432 <title>Synopsis</title> 15433 <funcsynopsis><funcprototype> 15434 <funcdef>int <function>journal_create </function></funcdef> 15435 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15436 </funcprototype></funcsynopsis> 15437</refsynopsisdiv> 15438<refsect1> 15439 <title>Arguments</title> 15440 <variablelist> 15441 <varlistentry> 15442 <term><parameter>journal</parameter></term> 15443 <listitem> 15444 <para> 15445 Journal to create. This structure must have been initialised 15446 </para> 15447 </listitem> 15448 </varlistentry> 15449 </variablelist> 15450</refsect1> 15451<refsect1> 15452<title>Description</title> 15453<para> 15454 Given a journal_t structure which tells us which disk blocks we can 15455 use, create a new journal superblock and initialise all of the 15456 journal fields from scratch. 15457</para> 15458</refsect1> 15459</refentry> 15460 15461<refentry id="API-journal-load"> 15462<refentryinfo> 15463 <title>LINUX</title> 15464 <productname>Kernel Hackers Manual</productname> 15465 <date>July 2017</date> 15466</refentryinfo> 15467<refmeta> 15468 <refentrytitle><phrase>journal_load</phrase></refentrytitle> 15469 <manvolnum>9</manvolnum> 15470 <refmiscinfo class="version">4.1.27</refmiscinfo> 15471</refmeta> 15472<refnamediv> 15473 <refname>journal_load</refname> 15474 <refpurpose> 15475 Read journal from disk. 15476 </refpurpose> 15477</refnamediv> 15478<refsynopsisdiv> 15479 <title>Synopsis</title> 15480 <funcsynopsis><funcprototype> 15481 <funcdef>int <function>journal_load </function></funcdef> 15482 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15483 </funcprototype></funcsynopsis> 15484</refsynopsisdiv> 15485<refsect1> 15486 <title>Arguments</title> 15487 <variablelist> 15488 <varlistentry> 15489 <term><parameter>journal</parameter></term> 15490 <listitem> 15491 <para> 15492 Journal to act on. 15493 </para> 15494 </listitem> 15495 </varlistentry> 15496 </variablelist> 15497</refsect1> 15498<refsect1> 15499<title>Description</title> 15500<para> 15501 Given a journal_t structure which tells us which disk blocks contain 15502 a journal, read the journal from disk to initialise the in-memory 15503 structures. 15504</para> 15505</refsect1> 15506</refentry> 15507 15508<refentry id="API-journal-destroy"> 15509<refentryinfo> 15510 <title>LINUX</title> 15511 <productname>Kernel Hackers Manual</productname> 15512 <date>July 2017</date> 15513</refentryinfo> 15514<refmeta> 15515 <refentrytitle><phrase>journal_destroy</phrase></refentrytitle> 15516 <manvolnum>9</manvolnum> 15517 <refmiscinfo class="version">4.1.27</refmiscinfo> 15518</refmeta> 15519<refnamediv> 15520 <refname>journal_destroy</refname> 15521 <refpurpose> 15522 Release a journal_t structure. 15523 </refpurpose> 15524</refnamediv> 15525<refsynopsisdiv> 15526 <title>Synopsis</title> 15527 <funcsynopsis><funcprototype> 15528 <funcdef>int <function>journal_destroy </function></funcdef> 15529 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15530 </funcprototype></funcsynopsis> 15531</refsynopsisdiv> 15532<refsect1> 15533 <title>Arguments</title> 15534 <variablelist> 15535 <varlistentry> 15536 <term><parameter>journal</parameter></term> 15537 <listitem> 15538 <para> 15539 Journal to act on. 15540 </para> 15541 </listitem> 15542 </varlistentry> 15543 </variablelist> 15544</refsect1> 15545<refsect1> 15546<title>Description</title> 15547<para> 15548 Release a journal_t structure once it is no longer in use by the 15549 journaled object. 15550 Return <0 if we couldn't clean up the journal. 15551</para> 15552</refsect1> 15553</refentry> 15554 15555<refentry id="API-journal-check-used-features"> 15556<refentryinfo> 15557 <title>LINUX</title> 15558 <productname>Kernel Hackers Manual</productname> 15559 <date>July 2017</date> 15560</refentryinfo> 15561<refmeta> 15562 <refentrytitle><phrase>journal_check_used_features</phrase></refentrytitle> 15563 <manvolnum>9</manvolnum> 15564 <refmiscinfo class="version">4.1.27</refmiscinfo> 15565</refmeta> 15566<refnamediv> 15567 <refname>journal_check_used_features</refname> 15568 <refpurpose> 15569 Check if features specified are used. 15570 </refpurpose> 15571</refnamediv> 15572<refsynopsisdiv> 15573 <title>Synopsis</title> 15574 <funcsynopsis><funcprototype> 15575 <funcdef>int <function>journal_check_used_features </function></funcdef> 15576 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15577 <paramdef>unsigned long <parameter>compat</parameter></paramdef> 15578 <paramdef>unsigned long <parameter>ro</parameter></paramdef> 15579 <paramdef>unsigned long <parameter>incompat</parameter></paramdef> 15580 </funcprototype></funcsynopsis> 15581</refsynopsisdiv> 15582<refsect1> 15583 <title>Arguments</title> 15584 <variablelist> 15585 <varlistentry> 15586 <term><parameter>journal</parameter></term> 15587 <listitem> 15588 <para> 15589 Journal to check. 15590 </para> 15591 </listitem> 15592 </varlistentry> 15593 <varlistentry> 15594 <term><parameter>compat</parameter></term> 15595 <listitem> 15596 <para> 15597 bitmask of compatible features 15598 </para> 15599 </listitem> 15600 </varlistentry> 15601 <varlistentry> 15602 <term><parameter>ro</parameter></term> 15603 <listitem> 15604 <para> 15605 bitmask of features that force read-only mount 15606 </para> 15607 </listitem> 15608 </varlistentry> 15609 <varlistentry> 15610 <term><parameter>incompat</parameter></term> 15611 <listitem> 15612 <para> 15613 bitmask of incompatible features 15614 </para> 15615 </listitem> 15616 </varlistentry> 15617 </variablelist> 15618</refsect1> 15619<refsect1> 15620<title>Description</title> 15621<para> 15622 Check whether the journal uses all of a given set of 15623 features. Return true (non-zero) if it does. 15624</para> 15625</refsect1> 15626</refentry> 15627 15628<refentry id="API-journal-check-available-features"> 15629<refentryinfo> 15630 <title>LINUX</title> 15631 <productname>Kernel Hackers Manual</productname> 15632 <date>July 2017</date> 15633</refentryinfo> 15634<refmeta> 15635 <refentrytitle><phrase>journal_check_available_features</phrase></refentrytitle> 15636 <manvolnum>9</manvolnum> 15637 <refmiscinfo class="version">4.1.27</refmiscinfo> 15638</refmeta> 15639<refnamediv> 15640 <refname>journal_check_available_features</refname> 15641 <refpurpose> 15642 Check feature set in journalling layer 15643 </refpurpose> 15644</refnamediv> 15645<refsynopsisdiv> 15646 <title>Synopsis</title> 15647 <funcsynopsis><funcprototype> 15648 <funcdef>int <function>journal_check_available_features </function></funcdef> 15649 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15650 <paramdef>unsigned long <parameter>compat</parameter></paramdef> 15651 <paramdef>unsigned long <parameter>ro</parameter></paramdef> 15652 <paramdef>unsigned long <parameter>incompat</parameter></paramdef> 15653 </funcprototype></funcsynopsis> 15654</refsynopsisdiv> 15655<refsect1> 15656 <title>Arguments</title> 15657 <variablelist> 15658 <varlistentry> 15659 <term><parameter>journal</parameter></term> 15660 <listitem> 15661 <para> 15662 Journal to check. 15663 </para> 15664 </listitem> 15665 </varlistentry> 15666 <varlistentry> 15667 <term><parameter>compat</parameter></term> 15668 <listitem> 15669 <para> 15670 bitmask of compatible features 15671 </para> 15672 </listitem> 15673 </varlistentry> 15674 <varlistentry> 15675 <term><parameter>ro</parameter></term> 15676 <listitem> 15677 <para> 15678 bitmask of features that force read-only mount 15679 </para> 15680 </listitem> 15681 </varlistentry> 15682 <varlistentry> 15683 <term><parameter>incompat</parameter></term> 15684 <listitem> 15685 <para> 15686 bitmask of incompatible features 15687 </para> 15688 </listitem> 15689 </varlistentry> 15690 </variablelist> 15691</refsect1> 15692<refsect1> 15693<title>Description</title> 15694<para> 15695 Check whether the journaling code supports the use of 15696 all of a given set of features on this journal. Return true 15697</para> 15698</refsect1> 15699</refentry> 15700 15701<refentry id="API-journal-set-features"> 15702<refentryinfo> 15703 <title>LINUX</title> 15704 <productname>Kernel Hackers Manual</productname> 15705 <date>July 2017</date> 15706</refentryinfo> 15707<refmeta> 15708 <refentrytitle><phrase>journal_set_features</phrase></refentrytitle> 15709 <manvolnum>9</manvolnum> 15710 <refmiscinfo class="version">4.1.27</refmiscinfo> 15711</refmeta> 15712<refnamediv> 15713 <refname>journal_set_features</refname> 15714 <refpurpose> 15715 Mark a given journal feature in the superblock 15716 </refpurpose> 15717</refnamediv> 15718<refsynopsisdiv> 15719 <title>Synopsis</title> 15720 <funcsynopsis><funcprototype> 15721 <funcdef>int <function>journal_set_features </function></funcdef> 15722 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15723 <paramdef>unsigned long <parameter>compat</parameter></paramdef> 15724 <paramdef>unsigned long <parameter>ro</parameter></paramdef> 15725 <paramdef>unsigned long <parameter>incompat</parameter></paramdef> 15726 </funcprototype></funcsynopsis> 15727</refsynopsisdiv> 15728<refsect1> 15729 <title>Arguments</title> 15730 <variablelist> 15731 <varlistentry> 15732 <term><parameter>journal</parameter></term> 15733 <listitem> 15734 <para> 15735 Journal to act on. 15736 </para> 15737 </listitem> 15738 </varlistentry> 15739 <varlistentry> 15740 <term><parameter>compat</parameter></term> 15741 <listitem> 15742 <para> 15743 bitmask of compatible features 15744 </para> 15745 </listitem> 15746 </varlistentry> 15747 <varlistentry> 15748 <term><parameter>ro</parameter></term> 15749 <listitem> 15750 <para> 15751 bitmask of features that force read-only mount 15752 </para> 15753 </listitem> 15754 </varlistentry> 15755 <varlistentry> 15756 <term><parameter>incompat</parameter></term> 15757 <listitem> 15758 <para> 15759 bitmask of incompatible features 15760 </para> 15761 </listitem> 15762 </varlistentry> 15763 </variablelist> 15764</refsect1> 15765<refsect1> 15766<title>Description</title> 15767<para> 15768 Mark a given journal feature as present on the 15769 superblock. Returns true if the requested features could be set. 15770</para> 15771</refsect1> 15772</refentry> 15773 15774<refentry id="API-journal-update-format"> 15775<refentryinfo> 15776 <title>LINUX</title> 15777 <productname>Kernel Hackers Manual</productname> 15778 <date>July 2017</date> 15779</refentryinfo> 15780<refmeta> 15781 <refentrytitle><phrase>journal_update_format</phrase></refentrytitle> 15782 <manvolnum>9</manvolnum> 15783 <refmiscinfo class="version">4.1.27</refmiscinfo> 15784</refmeta> 15785<refnamediv> 15786 <refname>journal_update_format</refname> 15787 <refpurpose> 15788 Update on-disk journal structure. 15789 </refpurpose> 15790</refnamediv> 15791<refsynopsisdiv> 15792 <title>Synopsis</title> 15793 <funcsynopsis><funcprototype> 15794 <funcdef>int <function>journal_update_format </function></funcdef> 15795 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15796 </funcprototype></funcsynopsis> 15797</refsynopsisdiv> 15798<refsect1> 15799 <title>Arguments</title> 15800 <variablelist> 15801 <varlistentry> 15802 <term><parameter>journal</parameter></term> 15803 <listitem> 15804 <para> 15805 Journal to act on. 15806 </para> 15807 </listitem> 15808 </varlistentry> 15809 </variablelist> 15810</refsect1> 15811<refsect1> 15812<title>Description</title> 15813<para> 15814 Given an initialised but unloaded journal struct, poke about in the 15815 on-disk structure to update it to the most recent supported version. 15816</para> 15817</refsect1> 15818</refentry> 15819 15820<refentry id="API-journal-flush"> 15821<refentryinfo> 15822 <title>LINUX</title> 15823 <productname>Kernel Hackers Manual</productname> 15824 <date>July 2017</date> 15825</refentryinfo> 15826<refmeta> 15827 <refentrytitle><phrase>journal_flush</phrase></refentrytitle> 15828 <manvolnum>9</manvolnum> 15829 <refmiscinfo class="version">4.1.27</refmiscinfo> 15830</refmeta> 15831<refnamediv> 15832 <refname>journal_flush</refname> 15833 <refpurpose> 15834 Flush journal 15835 </refpurpose> 15836</refnamediv> 15837<refsynopsisdiv> 15838 <title>Synopsis</title> 15839 <funcsynopsis><funcprototype> 15840 <funcdef>int <function>journal_flush </function></funcdef> 15841 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15842 </funcprototype></funcsynopsis> 15843</refsynopsisdiv> 15844<refsect1> 15845 <title>Arguments</title> 15846 <variablelist> 15847 <varlistentry> 15848 <term><parameter>journal</parameter></term> 15849 <listitem> 15850 <para> 15851 Journal to act on. 15852 </para> 15853 </listitem> 15854 </varlistentry> 15855 </variablelist> 15856</refsect1> 15857<refsect1> 15858<title>Description</title> 15859<para> 15860 Flush all data for a given journal to disk and empty the journal. 15861 Filesystems can use this when remounting readonly to ensure that 15862 recovery does not need to happen on remount. 15863</para> 15864</refsect1> 15865</refentry> 15866 15867<refentry id="API-journal-wipe"> 15868<refentryinfo> 15869 <title>LINUX</title> 15870 <productname>Kernel Hackers Manual</productname> 15871 <date>July 2017</date> 15872</refentryinfo> 15873<refmeta> 15874 <refentrytitle><phrase>journal_wipe</phrase></refentrytitle> 15875 <manvolnum>9</manvolnum> 15876 <refmiscinfo class="version">4.1.27</refmiscinfo> 15877</refmeta> 15878<refnamediv> 15879 <refname>journal_wipe</refname> 15880 <refpurpose> 15881 Wipe journal contents 15882 </refpurpose> 15883</refnamediv> 15884<refsynopsisdiv> 15885 <title>Synopsis</title> 15886 <funcsynopsis><funcprototype> 15887 <funcdef>int <function>journal_wipe </function></funcdef> 15888 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15889 <paramdef>int <parameter>write</parameter></paramdef> 15890 </funcprototype></funcsynopsis> 15891</refsynopsisdiv> 15892<refsect1> 15893 <title>Arguments</title> 15894 <variablelist> 15895 <varlistentry> 15896 <term><parameter>journal</parameter></term> 15897 <listitem> 15898 <para> 15899 Journal to act on. 15900 </para> 15901 </listitem> 15902 </varlistentry> 15903 <varlistentry> 15904 <term><parameter>write</parameter></term> 15905 <listitem> 15906 <para> 15907 flag (see below) 15908 </para> 15909 </listitem> 15910 </varlistentry> 15911 </variablelist> 15912</refsect1> 15913<refsect1> 15914<title>Description</title> 15915<para> 15916 Wipe out all of the contents of a journal, safely. This will produce 15917 a warning if the journal contains any valid recovery information. 15918 Must be called between journal_init_*() and <function>journal_load</function>. 15919 </para><para> 15920 15921 If 'write' is non-zero, then we wipe out the journal on disk; otherwise 15922 we merely suppress recovery. 15923</para> 15924</refsect1> 15925</refentry> 15926 15927<refentry id="API-journal-abort"> 15928<refentryinfo> 15929 <title>LINUX</title> 15930 <productname>Kernel Hackers Manual</productname> 15931 <date>July 2017</date> 15932</refentryinfo> 15933<refmeta> 15934 <refentrytitle><phrase>journal_abort</phrase></refentrytitle> 15935 <manvolnum>9</manvolnum> 15936 <refmiscinfo class="version">4.1.27</refmiscinfo> 15937</refmeta> 15938<refnamediv> 15939 <refname>journal_abort</refname> 15940 <refpurpose> 15941 Shutdown the journal immediately. 15942 </refpurpose> 15943</refnamediv> 15944<refsynopsisdiv> 15945 <title>Synopsis</title> 15946 <funcsynopsis><funcprototype> 15947 <funcdef>void <function>journal_abort </function></funcdef> 15948 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 15949 <paramdef>int <parameter>errno</parameter></paramdef> 15950 </funcprototype></funcsynopsis> 15951</refsynopsisdiv> 15952<refsect1> 15953 <title>Arguments</title> 15954 <variablelist> 15955 <varlistentry> 15956 <term><parameter>journal</parameter></term> 15957 <listitem> 15958 <para> 15959 the journal to shutdown. 15960 </para> 15961 </listitem> 15962 </varlistentry> 15963 <varlistentry> 15964 <term><parameter>errno</parameter></term> 15965 <listitem> 15966 <para> 15967 an error number to record in the journal indicating 15968 the reason for the shutdown. 15969 </para> 15970 </listitem> 15971 </varlistentry> 15972 </variablelist> 15973</refsect1> 15974<refsect1> 15975<title>Description</title> 15976<para> 15977 Perform a complete, immediate shutdown of the ENTIRE 15978 journal (not of a single transaction). This operation cannot be 15979 undone without closing and reopening the journal. 15980 </para><para> 15981 15982 The journal_abort function is intended to support higher level error 15983 recovery mechanisms such as the ext2/ext3 remount-readonly error 15984 mode. 15985 </para><para> 15986 15987 Journal abort has very specific semantics. Any existing dirty, 15988 unjournaled buffers in the main filesystem will still be written to 15989 disk by bdflush, but the journaling mechanism will be suspended 15990 immediately and no further transaction commits will be honoured. 15991 </para><para> 15992 15993 Any dirty, journaled buffers will be written back to disk without 15994 hitting the journal. Atomicity cannot be guaranteed on an aborted 15995 filesystem, but we _do_ attempt to leave as much data as possible 15996 behind for fsck to use for cleanup. 15997 </para><para> 15998 15999 Any attempt to get a new transaction handle on a journal which is in 16000 ABORT state will just result in an -EROFS error return. A 16001 journal_stop on an existing handle will return -EIO if we have 16002 entered abort state during the update. 16003 </para><para> 16004 16005 Recursive transactions are not disturbed by journal abort until the 16006 final journal_stop, which will receive the -EIO error. 16007 </para><para> 16008 16009 Finally, the journal_abort call allows the caller to supply an errno 16010 which will be recorded (if possible) in the journal superblock. This 16011 allows a client to record failure conditions in the middle of a 16012 transaction without having to complete the transaction to record the 16013 failure to disk. ext3_error, for example, now uses this 16014 functionality. 16015 </para><para> 16016 16017 Errors which originate from within the journaling layer will NOT 16018 supply an errno; a null errno implies that absolutely no further 16019 writes are done to the journal (unless there are any already in 16020 progress). 16021</para> 16022</refsect1> 16023</refentry> 16024 16025<refentry id="API-journal-errno"> 16026<refentryinfo> 16027 <title>LINUX</title> 16028 <productname>Kernel Hackers Manual</productname> 16029 <date>July 2017</date> 16030</refentryinfo> 16031<refmeta> 16032 <refentrytitle><phrase>journal_errno</phrase></refentrytitle> 16033 <manvolnum>9</manvolnum> 16034 <refmiscinfo class="version">4.1.27</refmiscinfo> 16035</refmeta> 16036<refnamediv> 16037 <refname>journal_errno</refname> 16038 <refpurpose> 16039 returns the journal's error state. 16040 </refpurpose> 16041</refnamediv> 16042<refsynopsisdiv> 16043 <title>Synopsis</title> 16044 <funcsynopsis><funcprototype> 16045 <funcdef>int <function>journal_errno </function></funcdef> 16046 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16047 </funcprototype></funcsynopsis> 16048</refsynopsisdiv> 16049<refsect1> 16050 <title>Arguments</title> 16051 <variablelist> 16052 <varlistentry> 16053 <term><parameter>journal</parameter></term> 16054 <listitem> 16055 <para> 16056 journal to examine. 16057 </para> 16058 </listitem> 16059 </varlistentry> 16060 </variablelist> 16061</refsect1> 16062<refsect1> 16063<title>Description</title> 16064<para> 16065 This is the errno numbet set with <function>journal_abort</function>, the last 16066 time the journal was mounted - if the journal was stopped 16067 without calling abort this will be 0. 16068 </para><para> 16069 16070 If the journal has been aborted on this mount time -EROFS will 16071 be returned. 16072</para> 16073</refsect1> 16074</refentry> 16075 16076<refentry id="API-journal-clear-err"> 16077<refentryinfo> 16078 <title>LINUX</title> 16079 <productname>Kernel Hackers Manual</productname> 16080 <date>July 2017</date> 16081</refentryinfo> 16082<refmeta> 16083 <refentrytitle><phrase>journal_clear_err</phrase></refentrytitle> 16084 <manvolnum>9</manvolnum> 16085 <refmiscinfo class="version">4.1.27</refmiscinfo> 16086</refmeta> 16087<refnamediv> 16088 <refname>journal_clear_err</refname> 16089 <refpurpose> 16090 clears the journal's error state 16091 </refpurpose> 16092</refnamediv> 16093<refsynopsisdiv> 16094 <title>Synopsis</title> 16095 <funcsynopsis><funcprototype> 16096 <funcdef>int <function>journal_clear_err </function></funcdef> 16097 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16098 </funcprototype></funcsynopsis> 16099</refsynopsisdiv> 16100<refsect1> 16101 <title>Arguments</title> 16102 <variablelist> 16103 <varlistentry> 16104 <term><parameter>journal</parameter></term> 16105 <listitem> 16106 <para> 16107 journal to act on. 16108 </para> 16109 </listitem> 16110 </varlistentry> 16111 </variablelist> 16112</refsect1> 16113<refsect1> 16114<title>Description</title> 16115<para> 16116 An error must be cleared or Acked to take a FS out of readonly 16117 mode. 16118</para> 16119</refsect1> 16120</refentry> 16121 16122<refentry id="API-journal-ack-err"> 16123<refentryinfo> 16124 <title>LINUX</title> 16125 <productname>Kernel Hackers Manual</productname> 16126 <date>July 2017</date> 16127</refentryinfo> 16128<refmeta> 16129 <refentrytitle><phrase>journal_ack_err</phrase></refentrytitle> 16130 <manvolnum>9</manvolnum> 16131 <refmiscinfo class="version">4.1.27</refmiscinfo> 16132</refmeta> 16133<refnamediv> 16134 <refname>journal_ack_err</refname> 16135 <refpurpose> 16136 Ack journal err. 16137 </refpurpose> 16138</refnamediv> 16139<refsynopsisdiv> 16140 <title>Synopsis</title> 16141 <funcsynopsis><funcprototype> 16142 <funcdef>void <function>journal_ack_err </function></funcdef> 16143 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16144 </funcprototype></funcsynopsis> 16145</refsynopsisdiv> 16146<refsect1> 16147 <title>Arguments</title> 16148 <variablelist> 16149 <varlistentry> 16150 <term><parameter>journal</parameter></term> 16151 <listitem> 16152 <para> 16153 journal to act on. 16154 </para> 16155 </listitem> 16156 </varlistentry> 16157 </variablelist> 16158</refsect1> 16159<refsect1> 16160<title>Description</title> 16161<para> 16162 An error must be cleared or Acked to take a FS out of readonly 16163 mode. 16164</para> 16165</refsect1> 16166</refentry> 16167 16168<!-- fs/jbd/recovery.c --> 16169<refentry id="API-journal-recover"> 16170<refentryinfo> 16171 <title>LINUX</title> 16172 <productname>Kernel Hackers Manual</productname> 16173 <date>July 2017</date> 16174</refentryinfo> 16175<refmeta> 16176 <refentrytitle><phrase>journal_recover</phrase></refentrytitle> 16177 <manvolnum>9</manvolnum> 16178 <refmiscinfo class="version">4.1.27</refmiscinfo> 16179</refmeta> 16180<refnamediv> 16181 <refname>journal_recover</refname> 16182 <refpurpose> 16183 recovers a on-disk journal 16184 </refpurpose> 16185</refnamediv> 16186<refsynopsisdiv> 16187 <title>Synopsis</title> 16188 <funcsynopsis><funcprototype> 16189 <funcdef>int <function>journal_recover </function></funcdef> 16190 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16191 </funcprototype></funcsynopsis> 16192</refsynopsisdiv> 16193<refsect1> 16194 <title>Arguments</title> 16195 <variablelist> 16196 <varlistentry> 16197 <term><parameter>journal</parameter></term> 16198 <listitem> 16199 <para> 16200 the journal to recover 16201 </para> 16202 </listitem> 16203 </varlistentry> 16204 </variablelist> 16205</refsect1> 16206<refsect1> 16207<title>Description</title> 16208<para> 16209 The primary function for recovering the log contents when mounting a 16210 journaled device. 16211 </para><para> 16212 16213 Recovery is done in three passes. In the first pass, we look for the 16214 end of the log. In the second, we assemble the list of revoke 16215 blocks. In the third and final pass, we replay any un-revoked blocks 16216 in the log. 16217</para> 16218</refsect1> 16219</refentry> 16220 16221<refentry id="API-journal-skip-recovery"> 16222<refentryinfo> 16223 <title>LINUX</title> 16224 <productname>Kernel Hackers Manual</productname> 16225 <date>July 2017</date> 16226</refentryinfo> 16227<refmeta> 16228 <refentrytitle><phrase>journal_skip_recovery</phrase></refentrytitle> 16229 <manvolnum>9</manvolnum> 16230 <refmiscinfo class="version">4.1.27</refmiscinfo> 16231</refmeta> 16232<refnamediv> 16233 <refname>journal_skip_recovery</refname> 16234 <refpurpose> 16235 Start journal and wipe exiting records 16236 </refpurpose> 16237</refnamediv> 16238<refsynopsisdiv> 16239 <title>Synopsis</title> 16240 <funcsynopsis><funcprototype> 16241 <funcdef>int <function>journal_skip_recovery </function></funcdef> 16242 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16243 </funcprototype></funcsynopsis> 16244</refsynopsisdiv> 16245<refsect1> 16246 <title>Arguments</title> 16247 <variablelist> 16248 <varlistentry> 16249 <term><parameter>journal</parameter></term> 16250 <listitem> 16251 <para> 16252 journal to startup 16253 </para> 16254 </listitem> 16255 </varlistentry> 16256 </variablelist> 16257</refsect1> 16258<refsect1> 16259<title>Description</title> 16260<para> 16261 Locate any valid recovery information from the journal and set up the 16262 journal structures in memory to ignore it (presumably because the 16263 caller has evidence that it is out of date). 16264 This function does'nt appear to be exorted.. 16265 </para><para> 16266 16267 We perform one pass over the journal to allow us to tell the user how 16268 much recovery information is being erased, and to let us initialise 16269 the journal transaction sequence numbers to the next unused ID. 16270</para> 16271</refsect1> 16272</refentry> 16273 16274 </sect2> 16275 <sect2 id="transaction_level"><title>Transasction Level</title> 16276<!-- fs/jbd/transaction.c --> 16277<refentry id="API-journal-start"> 16278<refentryinfo> 16279 <title>LINUX</title> 16280 <productname>Kernel Hackers Manual</productname> 16281 <date>July 2017</date> 16282</refentryinfo> 16283<refmeta> 16284 <refentrytitle><phrase>journal_start</phrase></refentrytitle> 16285 <manvolnum>9</manvolnum> 16286 <refmiscinfo class="version">4.1.27</refmiscinfo> 16287</refmeta> 16288<refnamediv> 16289 <refname>journal_start</refname> 16290 <refpurpose> 16291 Obtain a new handle. 16292 </refpurpose> 16293</refnamediv> 16294<refsynopsisdiv> 16295 <title>Synopsis</title> 16296 <funcsynopsis><funcprototype> 16297 <funcdef>handle_t * <function>journal_start </function></funcdef> 16298 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16299 <paramdef>int <parameter>nblocks</parameter></paramdef> 16300 </funcprototype></funcsynopsis> 16301</refsynopsisdiv> 16302<refsect1> 16303 <title>Arguments</title> 16304 <variablelist> 16305 <varlistentry> 16306 <term><parameter>journal</parameter></term> 16307 <listitem> 16308 <para> 16309 Journal to start transaction on. 16310 </para> 16311 </listitem> 16312 </varlistentry> 16313 <varlistentry> 16314 <term><parameter>nblocks</parameter></term> 16315 <listitem> 16316 <para> 16317 number of block buffer we might modify 16318 </para> 16319 </listitem> 16320 </varlistentry> 16321 </variablelist> 16322</refsect1> 16323<refsect1> 16324<title>Description</title> 16325<para> 16326 We make sure that the transaction can guarantee at least nblocks of 16327 modified buffers in the log. We block until the log can guarantee 16328 that much space. 16329 </para><para> 16330 16331 This function is visible to journal users (like ext3fs), so is not 16332 called with the journal already locked. 16333 </para><para> 16334 16335 Return a pointer to a newly allocated handle, or an <function>ERR_PTR</function> value 16336 on failure. 16337</para> 16338</refsect1> 16339</refentry> 16340 16341<refentry id="API-journal-extend"> 16342<refentryinfo> 16343 <title>LINUX</title> 16344 <productname>Kernel Hackers Manual</productname> 16345 <date>July 2017</date> 16346</refentryinfo> 16347<refmeta> 16348 <refentrytitle><phrase>journal_extend</phrase></refentrytitle> 16349 <manvolnum>9</manvolnum> 16350 <refmiscinfo class="version">4.1.27</refmiscinfo> 16351</refmeta> 16352<refnamediv> 16353 <refname>journal_extend</refname> 16354 <refpurpose> 16355 extend buffer credits. 16356 </refpurpose> 16357</refnamediv> 16358<refsynopsisdiv> 16359 <title>Synopsis</title> 16360 <funcsynopsis><funcprototype> 16361 <funcdef>int <function>journal_extend </function></funcdef> 16362 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16363 <paramdef>int <parameter>nblocks</parameter></paramdef> 16364 </funcprototype></funcsynopsis> 16365</refsynopsisdiv> 16366<refsect1> 16367 <title>Arguments</title> 16368 <variablelist> 16369 <varlistentry> 16370 <term><parameter>handle</parameter></term> 16371 <listitem> 16372 <para> 16373 handle to 'extend' 16374 </para> 16375 </listitem> 16376 </varlistentry> 16377 <varlistentry> 16378 <term><parameter>nblocks</parameter></term> 16379 <listitem> 16380 <para> 16381 nr blocks to try to extend by. 16382 </para> 16383 </listitem> 16384 </varlistentry> 16385 </variablelist> 16386</refsect1> 16387<refsect1> 16388<title>Description</title> 16389<para> 16390 Some transactions, such as large extends and truncates, can be done 16391 atomically all at once or in several stages. The operation requests 16392 a credit for a number of buffer modications in advance, but can 16393 extend its credit if it needs more. 16394 </para><para> 16395 16396 journal_extend tries to give the running handle more buffer credits. 16397 It does not guarantee that allocation - this is a best-effort only. 16398 The calling process MUST be able to deal cleanly with a failure to 16399 extend here. 16400 </para><para> 16401 16402 Return 0 on success, non-zero on failure. 16403 </para><para> 16404 16405 return code < 0 implies an error 16406 return code > 0 implies normal transaction-full status. 16407</para> 16408</refsect1> 16409</refentry> 16410 16411<refentry id="API-journal-restart"> 16412<refentryinfo> 16413 <title>LINUX</title> 16414 <productname>Kernel Hackers Manual</productname> 16415 <date>July 2017</date> 16416</refentryinfo> 16417<refmeta> 16418 <refentrytitle><phrase>journal_restart</phrase></refentrytitle> 16419 <manvolnum>9</manvolnum> 16420 <refmiscinfo class="version">4.1.27</refmiscinfo> 16421</refmeta> 16422<refnamediv> 16423 <refname>journal_restart</refname> 16424 <refpurpose> 16425 restart a handle. 16426 </refpurpose> 16427</refnamediv> 16428<refsynopsisdiv> 16429 <title>Synopsis</title> 16430 <funcsynopsis><funcprototype> 16431 <funcdef>int <function>journal_restart </function></funcdef> 16432 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16433 <paramdef>int <parameter>nblocks</parameter></paramdef> 16434 </funcprototype></funcsynopsis> 16435</refsynopsisdiv> 16436<refsect1> 16437 <title>Arguments</title> 16438 <variablelist> 16439 <varlistentry> 16440 <term><parameter>handle</parameter></term> 16441 <listitem> 16442 <para> 16443 handle to restart 16444 </para> 16445 </listitem> 16446 </varlistentry> 16447 <varlistentry> 16448 <term><parameter>nblocks</parameter></term> 16449 <listitem> 16450 <para> 16451 nr credits requested 16452 </para> 16453 </listitem> 16454 </varlistentry> 16455 </variablelist> 16456</refsect1> 16457<refsect1> 16458<title>Description</title> 16459<para> 16460 Restart a handle for a multi-transaction filesystem 16461 operation. 16462 </para><para> 16463 16464 If the <function>journal_extend</function> call above fails to grant new buffer credits 16465 to a running handle, a call to journal_restart will commit the 16466 handle's transaction so far and reattach the handle to a new 16467 transaction capabable of guaranteeing the requested number of 16468 credits. 16469</para> 16470</refsect1> 16471</refentry> 16472 16473<refentry id="API-journal-lock-updates"> 16474<refentryinfo> 16475 <title>LINUX</title> 16476 <productname>Kernel Hackers Manual</productname> 16477 <date>July 2017</date> 16478</refentryinfo> 16479<refmeta> 16480 <refentrytitle><phrase>journal_lock_updates</phrase></refentrytitle> 16481 <manvolnum>9</manvolnum> 16482 <refmiscinfo class="version">4.1.27</refmiscinfo> 16483</refmeta> 16484<refnamediv> 16485 <refname>journal_lock_updates</refname> 16486 <refpurpose> 16487 establish a transaction barrier. 16488 </refpurpose> 16489</refnamediv> 16490<refsynopsisdiv> 16491 <title>Synopsis</title> 16492 <funcsynopsis><funcprototype> 16493 <funcdef>void <function>journal_lock_updates </function></funcdef> 16494 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16495 </funcprototype></funcsynopsis> 16496</refsynopsisdiv> 16497<refsect1> 16498 <title>Arguments</title> 16499 <variablelist> 16500 <varlistentry> 16501 <term><parameter>journal</parameter></term> 16502 <listitem> 16503 <para> 16504 Journal to establish a barrier on. 16505 </para> 16506 </listitem> 16507 </varlistentry> 16508 </variablelist> 16509</refsect1> 16510<refsect1> 16511<title>Description</title> 16512<para> 16513 This locks out any further updates from being started, and blocks until all 16514 existing updates have completed, returning only once the journal is in a 16515 quiescent state with no updates running. 16516 </para><para> 16517 16518 We do not use simple mutex for synchronization as there are syscalls which 16519 want to return with filesystem locked and that trips up lockdep. Also 16520 hibernate needs to lock filesystem but locked mutex then blocks hibernation. 16521 Since locking filesystem is rare operation, we use simple counter and 16522 waitqueue for locking. 16523</para> 16524</refsect1> 16525</refentry> 16526 16527<refentry id="API-journal-unlock-updates"> 16528<refentryinfo> 16529 <title>LINUX</title> 16530 <productname>Kernel Hackers Manual</productname> 16531 <date>July 2017</date> 16532</refentryinfo> 16533<refmeta> 16534 <refentrytitle><phrase>journal_unlock_updates</phrase></refentrytitle> 16535 <manvolnum>9</manvolnum> 16536 <refmiscinfo class="version">4.1.27</refmiscinfo> 16537</refmeta> 16538<refnamediv> 16539 <refname>journal_unlock_updates</refname> 16540 <refpurpose> 16541 release barrier 16542 </refpurpose> 16543</refnamediv> 16544<refsynopsisdiv> 16545 <title>Synopsis</title> 16546 <funcsynopsis><funcprototype> 16547 <funcdef>void <function>journal_unlock_updates </function></funcdef> 16548 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 16549 </funcprototype></funcsynopsis> 16550</refsynopsisdiv> 16551<refsect1> 16552 <title>Arguments</title> 16553 <variablelist> 16554 <varlistentry> 16555 <term><parameter>journal</parameter></term> 16556 <listitem> 16557 <para> 16558 Journal to release the barrier on. 16559 </para> 16560 </listitem> 16561 </varlistentry> 16562 </variablelist> 16563</refsect1> 16564<refsect1> 16565<title>Description</title> 16566<para> 16567 Release a transaction barrier obtained with <function>journal_lock_updates</function>. 16568</para> 16569</refsect1> 16570</refentry> 16571 16572<refentry id="API-journal-get-write-access"> 16573<refentryinfo> 16574 <title>LINUX</title> 16575 <productname>Kernel Hackers Manual</productname> 16576 <date>July 2017</date> 16577</refentryinfo> 16578<refmeta> 16579 <refentrytitle><phrase>journal_get_write_access</phrase></refentrytitle> 16580 <manvolnum>9</manvolnum> 16581 <refmiscinfo class="version">4.1.27</refmiscinfo> 16582</refmeta> 16583<refnamediv> 16584 <refname>journal_get_write_access</refname> 16585 <refpurpose> 16586 notify intent to modify a buffer for metadata (not data) update. 16587 </refpurpose> 16588</refnamediv> 16589<refsynopsisdiv> 16590 <title>Synopsis</title> 16591 <funcsynopsis><funcprototype> 16592 <funcdef>int <function>journal_get_write_access </function></funcdef> 16593 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16594 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16595 </funcprototype></funcsynopsis> 16596</refsynopsisdiv> 16597<refsect1> 16598 <title>Arguments</title> 16599 <variablelist> 16600 <varlistentry> 16601 <term><parameter>handle</parameter></term> 16602 <listitem> 16603 <para> 16604 transaction to add buffer modifications to 16605 </para> 16606 </listitem> 16607 </varlistentry> 16608 <varlistentry> 16609 <term><parameter>bh</parameter></term> 16610 <listitem> 16611 <para> 16612 bh to be used for metadata writes 16613 </para> 16614 </listitem> 16615 </varlistentry> 16616 </variablelist> 16617</refsect1> 16618<refsect1> 16619<title>Description</title> 16620<para> 16621 Returns an error code or 0 on success. 16622 </para><para> 16623 16624 In full data journalling mode the buffer may be of type BJ_AsyncData, 16625 because we're <function>write</function>ing a buffer which is also part of a shared mapping. 16626</para> 16627</refsect1> 16628</refentry> 16629 16630<refentry id="API-journal-get-create-access"> 16631<refentryinfo> 16632 <title>LINUX</title> 16633 <productname>Kernel Hackers Manual</productname> 16634 <date>July 2017</date> 16635</refentryinfo> 16636<refmeta> 16637 <refentrytitle><phrase>journal_get_create_access</phrase></refentrytitle> 16638 <manvolnum>9</manvolnum> 16639 <refmiscinfo class="version">4.1.27</refmiscinfo> 16640</refmeta> 16641<refnamediv> 16642 <refname>journal_get_create_access</refname> 16643 <refpurpose> 16644 notify intent to use newly created bh 16645 </refpurpose> 16646</refnamediv> 16647<refsynopsisdiv> 16648 <title>Synopsis</title> 16649 <funcsynopsis><funcprototype> 16650 <funcdef>int <function>journal_get_create_access </function></funcdef> 16651 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16652 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16653 </funcprototype></funcsynopsis> 16654</refsynopsisdiv> 16655<refsect1> 16656 <title>Arguments</title> 16657 <variablelist> 16658 <varlistentry> 16659 <term><parameter>handle</parameter></term> 16660 <listitem> 16661 <para> 16662 transaction to new buffer to 16663 </para> 16664 </listitem> 16665 </varlistentry> 16666 <varlistentry> 16667 <term><parameter>bh</parameter></term> 16668 <listitem> 16669 <para> 16670 new buffer. 16671 </para> 16672 </listitem> 16673 </varlistentry> 16674 </variablelist> 16675</refsect1> 16676<refsect1> 16677<title>Description</title> 16678<para> 16679 Call this if you create a new bh. 16680</para> 16681</refsect1> 16682</refentry> 16683 16684<refentry id="API-journal-get-undo-access"> 16685<refentryinfo> 16686 <title>LINUX</title> 16687 <productname>Kernel Hackers Manual</productname> 16688 <date>July 2017</date> 16689</refentryinfo> 16690<refmeta> 16691 <refentrytitle><phrase>journal_get_undo_access</phrase></refentrytitle> 16692 <manvolnum>9</manvolnum> 16693 <refmiscinfo class="version">4.1.27</refmiscinfo> 16694</refmeta> 16695<refnamediv> 16696 <refname>journal_get_undo_access</refname> 16697 <refpurpose> 16698 Notify intent to modify metadata with non-rewindable consequences 16699 </refpurpose> 16700</refnamediv> 16701<refsynopsisdiv> 16702 <title>Synopsis</title> 16703 <funcsynopsis><funcprototype> 16704 <funcdef>int <function>journal_get_undo_access </function></funcdef> 16705 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16706 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16707 </funcprototype></funcsynopsis> 16708</refsynopsisdiv> 16709<refsect1> 16710 <title>Arguments</title> 16711 <variablelist> 16712 <varlistentry> 16713 <term><parameter>handle</parameter></term> 16714 <listitem> 16715 <para> 16716 transaction 16717 </para> 16718 </listitem> 16719 </varlistentry> 16720 <varlistentry> 16721 <term><parameter>bh</parameter></term> 16722 <listitem> 16723 <para> 16724 buffer to undo 16725 </para> 16726 </listitem> 16727 </varlistentry> 16728 </variablelist> 16729</refsect1> 16730<refsect1> 16731<title>Description</title> 16732<para> 16733 Sometimes there is a need to distinguish between metadata which has 16734 been committed to disk and that which has not. The ext3fs code uses 16735 this for freeing and allocating space, we have to make sure that we 16736 do not reuse freed space until the deallocation has been committed, 16737 since if we overwrote that space we would make the delete 16738 un-rewindable in case of a crash. 16739 </para><para> 16740 16741 To deal with that, journal_get_undo_access requests write access to a 16742 buffer for parts of non-rewindable operations such as delete 16743 operations on the bitmaps. The journaling code must keep a copy of 16744 the buffer's contents prior to the undo_access call until such time 16745 as we know that the buffer has definitely been committed to disk. 16746 </para><para> 16747 16748 We never need to know which transaction the committed data is part 16749 of, buffers touched here are guaranteed to be dirtied later and so 16750 will be committed to a new transaction in due course, at which point 16751 we can discard the old committed data pointer. 16752 </para><para> 16753 16754 Returns error number or 0 on success. 16755</para> 16756</refsect1> 16757</refentry> 16758 16759<refentry id="API-journal-dirty-data"> 16760<refentryinfo> 16761 <title>LINUX</title> 16762 <productname>Kernel Hackers Manual</productname> 16763 <date>July 2017</date> 16764</refentryinfo> 16765<refmeta> 16766 <refentrytitle><phrase>journal_dirty_data</phrase></refentrytitle> 16767 <manvolnum>9</manvolnum> 16768 <refmiscinfo class="version">4.1.27</refmiscinfo> 16769</refmeta> 16770<refnamediv> 16771 <refname>journal_dirty_data</refname> 16772 <refpurpose> 16773 mark a buffer as containing dirty data to be flushed 16774 </refpurpose> 16775</refnamediv> 16776<refsynopsisdiv> 16777 <title>Synopsis</title> 16778 <funcsynopsis><funcprototype> 16779 <funcdef>int <function>journal_dirty_data </function></funcdef> 16780 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16781 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16782 </funcprototype></funcsynopsis> 16783</refsynopsisdiv> 16784<refsect1> 16785 <title>Arguments</title> 16786 <variablelist> 16787 <varlistentry> 16788 <term><parameter>handle</parameter></term> 16789 <listitem> 16790 <para> 16791 transaction 16792 </para> 16793 </listitem> 16794 </varlistentry> 16795 <varlistentry> 16796 <term><parameter>bh</parameter></term> 16797 <listitem> 16798 <para> 16799 bufferhead to mark 16800 </para> 16801 </listitem> 16802 </varlistentry> 16803 </variablelist> 16804</refsect1> 16805<refsect1> 16806<title>Description</title> 16807<para> 16808 Mark a buffer as containing dirty data which needs to be flushed before 16809 we can commit the current transaction. 16810 </para><para> 16811 16812 The buffer is placed on the transaction's data list and is marked as 16813 belonging to the transaction. 16814 </para><para> 16815 16816 Returns error number or 0 on success. 16817 </para><para> 16818 16819 <function>journal_dirty_data</function> can be called via page_launder->ext3_writepage 16820 by kswapd. 16821</para> 16822</refsect1> 16823</refentry> 16824 16825<refentry id="API-journal-dirty-metadata"> 16826<refentryinfo> 16827 <title>LINUX</title> 16828 <productname>Kernel Hackers Manual</productname> 16829 <date>July 2017</date> 16830</refentryinfo> 16831<refmeta> 16832 <refentrytitle><phrase>journal_dirty_metadata</phrase></refentrytitle> 16833 <manvolnum>9</manvolnum> 16834 <refmiscinfo class="version">4.1.27</refmiscinfo> 16835</refmeta> 16836<refnamediv> 16837 <refname>journal_dirty_metadata</refname> 16838 <refpurpose> 16839 mark a buffer as containing dirty metadata 16840 </refpurpose> 16841</refnamediv> 16842<refsynopsisdiv> 16843 <title>Synopsis</title> 16844 <funcsynopsis><funcprototype> 16845 <funcdef>int <function>journal_dirty_metadata </function></funcdef> 16846 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16847 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16848 </funcprototype></funcsynopsis> 16849</refsynopsisdiv> 16850<refsect1> 16851 <title>Arguments</title> 16852 <variablelist> 16853 <varlistentry> 16854 <term><parameter>handle</parameter></term> 16855 <listitem> 16856 <para> 16857 transaction to add buffer to. 16858 </para> 16859 </listitem> 16860 </varlistentry> 16861 <varlistentry> 16862 <term><parameter>bh</parameter></term> 16863 <listitem> 16864 <para> 16865 buffer to mark 16866 </para> 16867 </listitem> 16868 </varlistentry> 16869 </variablelist> 16870</refsect1> 16871<refsect1> 16872<title>Description</title> 16873<para> 16874 Mark dirty metadata which needs to be journaled as part of the current 16875 transaction. 16876 </para><para> 16877 16878 The buffer is placed on the transaction's metadata list and is marked 16879 as belonging to the transaction. 16880 </para><para> 16881 16882 Returns error number or 0 on success. 16883 </para><para> 16884 16885 Special care needs to be taken if the buffer already belongs to the 16886 current committing transaction (in which case we should have frozen 16887 data present for that commit). In that case, we don't relink the 16888</para> 16889</refsect1> 16890<refsect1> 16891<title>buffer</title> 16892<para> 16893 that only gets done when the old transaction finally 16894 completes its commit. 16895</para> 16896</refsect1> 16897</refentry> 16898 16899<refentry id="API-journal-forget"> 16900<refentryinfo> 16901 <title>LINUX</title> 16902 <productname>Kernel Hackers Manual</productname> 16903 <date>July 2017</date> 16904</refentryinfo> 16905<refmeta> 16906 <refentrytitle><phrase>journal_forget</phrase></refentrytitle> 16907 <manvolnum>9</manvolnum> 16908 <refmiscinfo class="version">4.1.27</refmiscinfo> 16909</refmeta> 16910<refnamediv> 16911 <refname>journal_forget</refname> 16912 <refpurpose> 16913 <function>bforget</function> for potentially-journaled buffers. 16914 </refpurpose> 16915</refnamediv> 16916<refsynopsisdiv> 16917 <title>Synopsis</title> 16918 <funcsynopsis><funcprototype> 16919 <funcdef>int <function>journal_forget </function></funcdef> 16920 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16921 <paramdef>struct buffer_head * <parameter>bh</parameter></paramdef> 16922 </funcprototype></funcsynopsis> 16923</refsynopsisdiv> 16924<refsect1> 16925 <title>Arguments</title> 16926 <variablelist> 16927 <varlistentry> 16928 <term><parameter>handle</parameter></term> 16929 <listitem> 16930 <para> 16931 transaction handle 16932 </para> 16933 </listitem> 16934 </varlistentry> 16935 <varlistentry> 16936 <term><parameter>bh</parameter></term> 16937 <listitem> 16938 <para> 16939 bh to 'forget' 16940 </para> 16941 </listitem> 16942 </varlistentry> 16943 </variablelist> 16944</refsect1> 16945<refsect1> 16946<title>Description</title> 16947<para> 16948 We can only do the bforget if there are no commits pending against the 16949 buffer. If the buffer is dirty in the current running transaction we 16950 can safely unlink it. 16951 </para><para> 16952 16953 bh may not be a journalled buffer at all - it may be a non-JBD 16954 buffer which came off the hashtable. Check for this. 16955 </para><para> 16956 16957 Decrements bh->b_count by one. 16958 </para><para> 16959 16960 Allow this call even if the handle has aborted --- it may be part of 16961 the caller's cleanup after an abort. 16962</para> 16963</refsect1> 16964</refentry> 16965 16966<refentry id="API-journal-stop"> 16967<refentryinfo> 16968 <title>LINUX</title> 16969 <productname>Kernel Hackers Manual</productname> 16970 <date>July 2017</date> 16971</refentryinfo> 16972<refmeta> 16973 <refentrytitle><phrase>journal_stop</phrase></refentrytitle> 16974 <manvolnum>9</manvolnum> 16975 <refmiscinfo class="version">4.1.27</refmiscinfo> 16976</refmeta> 16977<refnamediv> 16978 <refname>journal_stop</refname> 16979 <refpurpose> 16980 complete a transaction 16981 </refpurpose> 16982</refnamediv> 16983<refsynopsisdiv> 16984 <title>Synopsis</title> 16985 <funcsynopsis><funcprototype> 16986 <funcdef>int <function>journal_stop </function></funcdef> 16987 <paramdef>handle_t * <parameter>handle</parameter></paramdef> 16988 </funcprototype></funcsynopsis> 16989</refsynopsisdiv> 16990<refsect1> 16991 <title>Arguments</title> 16992 <variablelist> 16993 <varlistentry> 16994 <term><parameter>handle</parameter></term> 16995 <listitem> 16996 <para> 16997 tranaction to complete. 16998 </para> 16999 </listitem> 17000 </varlistentry> 17001 </variablelist> 17002</refsect1> 17003<refsect1> 17004<title>Description</title> 17005<para> 17006 All done for a particular handle. 17007 </para><para> 17008 17009 There is not much action needed here. We just return any remaining 17010 buffer credits to the transaction and remove the handle. The only 17011 complication is that we need to start a commit operation if the 17012 filesystem is marked for synchronous update. 17013 </para><para> 17014 17015 journal_stop itself will not usually return an error, but it may 17016 do so in unusual circumstances. In particular, expect it to 17017 return -EIO if a journal_abort has been executed since the 17018 transaction began. 17019</para> 17020</refsect1> 17021</refentry> 17022 17023<refentry id="API-journal-force-commit"> 17024<refentryinfo> 17025 <title>LINUX</title> 17026 <productname>Kernel Hackers Manual</productname> 17027 <date>July 2017</date> 17028</refentryinfo> 17029<refmeta> 17030 <refentrytitle><phrase>journal_force_commit</phrase></refentrytitle> 17031 <manvolnum>9</manvolnum> 17032 <refmiscinfo class="version">4.1.27</refmiscinfo> 17033</refmeta> 17034<refnamediv> 17035 <refname>journal_force_commit</refname> 17036 <refpurpose> 17037 force any uncommitted transactions 17038 </refpurpose> 17039</refnamediv> 17040<refsynopsisdiv> 17041 <title>Synopsis</title> 17042 <funcsynopsis><funcprototype> 17043 <funcdef>int <function>journal_force_commit </function></funcdef> 17044 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 17045 </funcprototype></funcsynopsis> 17046</refsynopsisdiv> 17047<refsect1> 17048 <title>Arguments</title> 17049 <variablelist> 17050 <varlistentry> 17051 <term><parameter>journal</parameter></term> 17052 <listitem> 17053 <para> 17054 journal to force 17055 </para> 17056 </listitem> 17057 </varlistentry> 17058 </variablelist> 17059</refsect1> 17060<refsect1> 17061<title>For synchronous operations</title> 17062<para> 17063 force any uncommitted transactions 17064 to disk. May seem kludgy, but it reuses all the handle batching 17065 code in a very simple manner. 17066</para> 17067</refsect1> 17068</refentry> 17069 17070<refentry id="API-journal-try-to-free-buffers"> 17071<refentryinfo> 17072 <title>LINUX</title> 17073 <productname>Kernel Hackers Manual</productname> 17074 <date>July 2017</date> 17075</refentryinfo> 17076<refmeta> 17077 <refentrytitle><phrase>journal_try_to_free_buffers</phrase></refentrytitle> 17078 <manvolnum>9</manvolnum> 17079 <refmiscinfo class="version">4.1.27</refmiscinfo> 17080</refmeta> 17081<refnamediv> 17082 <refname>journal_try_to_free_buffers</refname> 17083 <refpurpose> 17084 try to free page buffers. 17085 </refpurpose> 17086</refnamediv> 17087<refsynopsisdiv> 17088 <title>Synopsis</title> 17089 <funcsynopsis><funcprototype> 17090 <funcdef>int <function>journal_try_to_free_buffers </function></funcdef> 17091 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 17092 <paramdef>struct page * <parameter>page</parameter></paramdef> 17093 <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef> 17094 </funcprototype></funcsynopsis> 17095</refsynopsisdiv> 17096<refsect1> 17097 <title>Arguments</title> 17098 <variablelist> 17099 <varlistentry> 17100 <term><parameter>journal</parameter></term> 17101 <listitem> 17102 <para> 17103 journal for operation 17104 </para> 17105 </listitem> 17106 </varlistentry> 17107 <varlistentry> 17108 <term><parameter>page</parameter></term> 17109 <listitem> 17110 <para> 17111 to try and free 17112 </para> 17113 </listitem> 17114 </varlistentry> 17115 <varlistentry> 17116 <term><parameter>gfp_mask</parameter></term> 17117 <listitem> 17118 <para> 17119 we use the mask to detect how hard should we try to release 17120 buffers. If __GFP_WAIT and __GFP_FS is set, we wait for commit code to 17121 release the buffers. 17122 </para> 17123 </listitem> 17124 </varlistentry> 17125 </variablelist> 17126</refsect1> 17127<refsect1> 17128<title>Description</title> 17129<para> 17130 </para><para> 17131 17132 For all the buffers on this page, 17133 if they are fully written out ordered data, move them onto BUF_CLEAN 17134 so <function>try_to_free_buffers</function> can reap them. 17135 </para><para> 17136 17137 This function returns non-zero if we wish <function>try_to_free_buffers</function> 17138 to be called. We do this if the page is releasable by <function>try_to_free_buffers</function>. 17139 We also do it if the page has locked or dirty buffers and the caller wants 17140 us to perform sync or async writeout. 17141 </para><para> 17142 17143 This complicates JBD locking somewhat. We aren't protected by the 17144 BKL here. We wish to remove the buffer from its committing or 17145 running transaction's ->t_datalist via __journal_unfile_buffer. 17146 </para><para> 17147 17148 This may *change* the value of transaction_t->t_datalist, so anyone 17149 who looks at t_datalist needs to lock against this function. 17150 </para><para> 17151 17152 Even worse, someone may be doing a journal_dirty_data on this 17153 buffer. So we need to lock against that. <function>journal_dirty_data</function> 17154 will come out of the lock with the buffer dirty, which makes it 17155 ineligible for release here. 17156 </para><para> 17157 17158 Who else is affected by this? hmm... Really the only contender 17159 is <function>do_get_write_access</function> - it could be looking at the buffer while 17160 <function>journal_try_to_free_buffer</function> is changing its state. But that 17161 cannot happen because we never reallocate freed data as metadata 17162 while the data is part of a transaction. Yes? 17163 </para><para> 17164 17165 Return 0 on failure, 1 on success 17166</para> 17167</refsect1> 17168</refentry> 17169 17170<refentry id="API-journal-invalidatepage"> 17171<refentryinfo> 17172 <title>LINUX</title> 17173 <productname>Kernel Hackers Manual</productname> 17174 <date>July 2017</date> 17175</refentryinfo> 17176<refmeta> 17177 <refentrytitle><phrase>journal_invalidatepage</phrase></refentrytitle> 17178 <manvolnum>9</manvolnum> 17179 <refmiscinfo class="version">4.1.27</refmiscinfo> 17180</refmeta> 17181<refnamediv> 17182 <refname>journal_invalidatepage</refname> 17183 <refpurpose> 17184 invalidate a journal page 17185 </refpurpose> 17186</refnamediv> 17187<refsynopsisdiv> 17188 <title>Synopsis</title> 17189 <funcsynopsis><funcprototype> 17190 <funcdef>void <function>journal_invalidatepage </function></funcdef> 17191 <paramdef>journal_t * <parameter>journal</parameter></paramdef> 17192 <paramdef>struct page * <parameter>page</parameter></paramdef> 17193 <paramdef>unsigned int <parameter>offset</parameter></paramdef> 17194 <paramdef>unsigned int <parameter>length</parameter></paramdef> 17195 </funcprototype></funcsynopsis> 17196</refsynopsisdiv> 17197<refsect1> 17198 <title>Arguments</title> 17199 <variablelist> 17200 <varlistentry> 17201 <term><parameter>journal</parameter></term> 17202 <listitem> 17203 <para> 17204 journal to use for flush 17205 </para> 17206 </listitem> 17207 </varlistentry> 17208 <varlistentry> 17209 <term><parameter>page</parameter></term> 17210 <listitem> 17211 <para> 17212 page to flush 17213 </para> 17214 </listitem> 17215 </varlistentry> 17216 <varlistentry> 17217 <term><parameter>offset</parameter></term> 17218 <listitem> 17219 <para> 17220 offset of the range to invalidate 17221 </para> 17222 </listitem> 17223 </varlistentry> 17224 <varlistentry> 17225 <term><parameter>length</parameter></term> 17226 <listitem> 17227 <para> 17228 length of the range to invalidate 17229 </para> 17230 </listitem> 17231 </varlistentry> 17232 </variablelist> 17233</refsect1> 17234<refsect1> 17235<title>Description</title> 17236<para> 17237 Reap page buffers containing data in specified range in page. 17238</para> 17239</refsect1> 17240</refentry> 17241 17242 </sect2> 17243 </sect1> 17244 <sect1 id="see_also"> 17245 <title>See also</title> 17246 <para> 17247 <citation> 17248 <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz"> 17249 Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie 17250 </ulink> 17251 </citation> 17252 </para> 17253 <para> 17254 <citation> 17255 <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html"> 17256 Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie 17257 </ulink> 17258 </citation> 17259 </para> 17260 </sect1> 17261 17262 </chapter> 17263 17264 <chapter id="splice"> 17265 <title>splice API</title> 17266 <para> 17267 splice is a method for moving blocks of data around inside the 17268 kernel, without continually transferring them between the kernel 17269 and user space. 17270 </para> 17271<refentry id="API-splice-to-pipe"> 17272<refentryinfo> 17273 <title>LINUX</title> 17274 <productname>Kernel Hackers Manual</productname> 17275 <date>July 2017</date> 17276</refentryinfo> 17277<refmeta> 17278 <refentrytitle><phrase>splice_to_pipe</phrase></refentrytitle> 17279 <manvolnum>9</manvolnum> 17280 <refmiscinfo class="version">4.1.27</refmiscinfo> 17281</refmeta> 17282<refnamediv> 17283 <refname>splice_to_pipe</refname> 17284 <refpurpose> 17285 fill passed data into a pipe 17286 </refpurpose> 17287</refnamediv> 17288<refsynopsisdiv> 17289 <title>Synopsis</title> 17290 <funcsynopsis><funcprototype> 17291 <funcdef>ssize_t <function>splice_to_pipe </function></funcdef> 17292 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17293 <paramdef>struct splice_pipe_desc * <parameter>spd</parameter></paramdef> 17294 </funcprototype></funcsynopsis> 17295</refsynopsisdiv> 17296<refsect1> 17297 <title>Arguments</title> 17298 <variablelist> 17299 <varlistentry> 17300 <term><parameter>pipe</parameter></term> 17301 <listitem> 17302 <para> 17303 pipe to fill 17304 </para> 17305 </listitem> 17306 </varlistentry> 17307 <varlistentry> 17308 <term><parameter>spd</parameter></term> 17309 <listitem> 17310 <para> 17311 data to fill 17312 </para> 17313 </listitem> 17314 </varlistentry> 17315 </variablelist> 17316</refsect1> 17317<refsect1> 17318<title>Description</title> 17319<para> 17320 <parameter>spd</parameter> contains a map of pages and len/offset tuples, along with 17321 the struct pipe_buf_operations associated with these pages. This 17322 function will link that data to the pipe. 17323</para> 17324</refsect1> 17325</refentry> 17326 17327<refentry id="API-generic-file-splice-read"> 17328<refentryinfo> 17329 <title>LINUX</title> 17330 <productname>Kernel Hackers Manual</productname> 17331 <date>July 2017</date> 17332</refentryinfo> 17333<refmeta> 17334 <refentrytitle><phrase>generic_file_splice_read</phrase></refentrytitle> 17335 <manvolnum>9</manvolnum> 17336 <refmiscinfo class="version">4.1.27</refmiscinfo> 17337</refmeta> 17338<refnamediv> 17339 <refname>generic_file_splice_read</refname> 17340 <refpurpose> 17341 splice data from file to a pipe 17342 </refpurpose> 17343</refnamediv> 17344<refsynopsisdiv> 17345 <title>Synopsis</title> 17346 <funcsynopsis><funcprototype> 17347 <funcdef>ssize_t <function>generic_file_splice_read </function></funcdef> 17348 <paramdef>struct file * <parameter>in</parameter></paramdef> 17349 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 17350 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17351 <paramdef>size_t <parameter>len</parameter></paramdef> 17352 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 17353 </funcprototype></funcsynopsis> 17354</refsynopsisdiv> 17355<refsect1> 17356 <title>Arguments</title> 17357 <variablelist> 17358 <varlistentry> 17359 <term><parameter>in</parameter></term> 17360 <listitem> 17361 <para> 17362 file to splice from 17363 </para> 17364 </listitem> 17365 </varlistentry> 17366 <varlistentry> 17367 <term><parameter>ppos</parameter></term> 17368 <listitem> 17369 <para> 17370 position in <parameter>in</parameter> 17371 </para> 17372 </listitem> 17373 </varlistentry> 17374 <varlistentry> 17375 <term><parameter>pipe</parameter></term> 17376 <listitem> 17377 <para> 17378 pipe to splice to 17379 </para> 17380 </listitem> 17381 </varlistentry> 17382 <varlistentry> 17383 <term><parameter>len</parameter></term> 17384 <listitem> 17385 <para> 17386 number of bytes to splice 17387 </para> 17388 </listitem> 17389 </varlistentry> 17390 <varlistentry> 17391 <term><parameter>flags</parameter></term> 17392 <listitem> 17393 <para> 17394 splice modifier flags 17395 </para> 17396 </listitem> 17397 </varlistentry> 17398 </variablelist> 17399</refsect1> 17400<refsect1> 17401<title>Description</title> 17402<para> 17403 Will read pages from given file and fill them into a pipe. Can be 17404 used as long as the address_space operations for the source implements 17405 a <function>readpage</function> hook. 17406</para> 17407</refsect1> 17408</refentry> 17409 17410<refentry id="API-splice-from-pipe-feed"> 17411<refentryinfo> 17412 <title>LINUX</title> 17413 <productname>Kernel Hackers Manual</productname> 17414 <date>July 2017</date> 17415</refentryinfo> 17416<refmeta> 17417 <refentrytitle><phrase>splice_from_pipe_feed</phrase></refentrytitle> 17418 <manvolnum>9</manvolnum> 17419 <refmiscinfo class="version">4.1.27</refmiscinfo> 17420</refmeta> 17421<refnamediv> 17422 <refname>splice_from_pipe_feed</refname> 17423 <refpurpose> 17424 feed available data from a pipe to a file 17425 </refpurpose> 17426</refnamediv> 17427<refsynopsisdiv> 17428 <title>Synopsis</title> 17429 <funcsynopsis><funcprototype> 17430 <funcdef>int <function>splice_from_pipe_feed </function></funcdef> 17431 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17432 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17433 <paramdef>splice_actor * <parameter>actor</parameter></paramdef> 17434 </funcprototype></funcsynopsis> 17435</refsynopsisdiv> 17436<refsect1> 17437 <title>Arguments</title> 17438 <variablelist> 17439 <varlistentry> 17440 <term><parameter>pipe</parameter></term> 17441 <listitem> 17442 <para> 17443 pipe to splice from 17444 </para> 17445 </listitem> 17446 </varlistentry> 17447 <varlistentry> 17448 <term><parameter>sd</parameter></term> 17449 <listitem> 17450 <para> 17451 information to <parameter>actor</parameter> 17452 </para> 17453 </listitem> 17454 </varlistentry> 17455 <varlistentry> 17456 <term><parameter>actor</parameter></term> 17457 <listitem> 17458 <para> 17459 handler that splices the data 17460 </para> 17461 </listitem> 17462 </varlistentry> 17463 </variablelist> 17464</refsect1> 17465<refsect1> 17466<title>Description</title> 17467<para> 17468 This function loops over the pipe and calls <parameter>actor</parameter> to do the 17469 actual moving of a single struct pipe_buffer to the desired 17470 destination. It returns when there's no more buffers left in 17471 the pipe or if the requested number of bytes (<parameter>sd</parameter>->total_len) 17472 have been copied. It returns a positive number (one) if the 17473 pipe needs to be filled with more data, zero if the required 17474 number of bytes have been copied and -errno on error. 17475 </para><para> 17476 17477 This, together with splice_from_pipe_{begin,end,next}, may be 17478 used to implement the functionality of <function>__splice_from_pipe</function> when 17479 locking is required around copying the pipe buffers to the 17480 destination. 17481</para> 17482</refsect1> 17483</refentry> 17484 17485<refentry id="API-splice-from-pipe-next"> 17486<refentryinfo> 17487 <title>LINUX</title> 17488 <productname>Kernel Hackers Manual</productname> 17489 <date>July 2017</date> 17490</refentryinfo> 17491<refmeta> 17492 <refentrytitle><phrase>splice_from_pipe_next</phrase></refentrytitle> 17493 <manvolnum>9</manvolnum> 17494 <refmiscinfo class="version">4.1.27</refmiscinfo> 17495</refmeta> 17496<refnamediv> 17497 <refname>splice_from_pipe_next</refname> 17498 <refpurpose> 17499 wait for some data to splice from 17500 </refpurpose> 17501</refnamediv> 17502<refsynopsisdiv> 17503 <title>Synopsis</title> 17504 <funcsynopsis><funcprototype> 17505 <funcdef>int <function>splice_from_pipe_next </function></funcdef> 17506 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17507 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17508 </funcprototype></funcsynopsis> 17509</refsynopsisdiv> 17510<refsect1> 17511 <title>Arguments</title> 17512 <variablelist> 17513 <varlistentry> 17514 <term><parameter>pipe</parameter></term> 17515 <listitem> 17516 <para> 17517 pipe to splice from 17518 </para> 17519 </listitem> 17520 </varlistentry> 17521 <varlistentry> 17522 <term><parameter>sd</parameter></term> 17523 <listitem> 17524 <para> 17525 information about the splice operation 17526 </para> 17527 </listitem> 17528 </varlistentry> 17529 </variablelist> 17530</refsect1> 17531<refsect1> 17532<title>Description</title> 17533<para> 17534 This function will wait for some data and return a positive 17535 value (one) if pipe buffers are available. It will return zero 17536 or -errno if no more data needs to be spliced. 17537</para> 17538</refsect1> 17539</refentry> 17540 17541<refentry id="API-splice-from-pipe-begin"> 17542<refentryinfo> 17543 <title>LINUX</title> 17544 <productname>Kernel Hackers Manual</productname> 17545 <date>July 2017</date> 17546</refentryinfo> 17547<refmeta> 17548 <refentrytitle><phrase>splice_from_pipe_begin</phrase></refentrytitle> 17549 <manvolnum>9</manvolnum> 17550 <refmiscinfo class="version">4.1.27</refmiscinfo> 17551</refmeta> 17552<refnamediv> 17553 <refname>splice_from_pipe_begin</refname> 17554 <refpurpose> 17555 start splicing from pipe 17556 </refpurpose> 17557</refnamediv> 17558<refsynopsisdiv> 17559 <title>Synopsis</title> 17560 <funcsynopsis><funcprototype> 17561 <funcdef>void <function>splice_from_pipe_begin </function></funcdef> 17562 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17563 </funcprototype></funcsynopsis> 17564</refsynopsisdiv> 17565<refsect1> 17566 <title>Arguments</title> 17567 <variablelist> 17568 <varlistentry> 17569 <term><parameter>sd</parameter></term> 17570 <listitem> 17571 <para> 17572 information about the splice operation 17573 </para> 17574 </listitem> 17575 </varlistentry> 17576 </variablelist> 17577</refsect1> 17578<refsect1> 17579<title>Description</title> 17580<para> 17581 This function should be called before a loop containing 17582 <function>splice_from_pipe_next</function> and <function>splice_from_pipe_feed</function> to 17583 initialize the necessary fields of <parameter>sd</parameter>. 17584</para> 17585</refsect1> 17586</refentry> 17587 17588<refentry id="API-splice-from-pipe-end"> 17589<refentryinfo> 17590 <title>LINUX</title> 17591 <productname>Kernel Hackers Manual</productname> 17592 <date>July 2017</date> 17593</refentryinfo> 17594<refmeta> 17595 <refentrytitle><phrase>splice_from_pipe_end</phrase></refentrytitle> 17596 <manvolnum>9</manvolnum> 17597 <refmiscinfo class="version">4.1.27</refmiscinfo> 17598</refmeta> 17599<refnamediv> 17600 <refname>splice_from_pipe_end</refname> 17601 <refpurpose> 17602 finish splicing from pipe 17603 </refpurpose> 17604</refnamediv> 17605<refsynopsisdiv> 17606 <title>Synopsis</title> 17607 <funcsynopsis><funcprototype> 17608 <funcdef>void <function>splice_from_pipe_end </function></funcdef> 17609 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17610 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17611 </funcprototype></funcsynopsis> 17612</refsynopsisdiv> 17613<refsect1> 17614 <title>Arguments</title> 17615 <variablelist> 17616 <varlistentry> 17617 <term><parameter>pipe</parameter></term> 17618 <listitem> 17619 <para> 17620 pipe to splice from 17621 </para> 17622 </listitem> 17623 </varlistentry> 17624 <varlistentry> 17625 <term><parameter>sd</parameter></term> 17626 <listitem> 17627 <para> 17628 information about the splice operation 17629 </para> 17630 </listitem> 17631 </varlistentry> 17632 </variablelist> 17633</refsect1> 17634<refsect1> 17635<title>Description</title> 17636<para> 17637 This function will wake up pipe writers if necessary. It should 17638 be called after a loop containing <function>splice_from_pipe_next</function> and 17639 <function>splice_from_pipe_feed</function>. 17640</para> 17641</refsect1> 17642</refentry> 17643 17644<refentry id="API---splice-from-pipe"> 17645<refentryinfo> 17646 <title>LINUX</title> 17647 <productname>Kernel Hackers Manual</productname> 17648 <date>July 2017</date> 17649</refentryinfo> 17650<refmeta> 17651 <refentrytitle><phrase>__splice_from_pipe</phrase></refentrytitle> 17652 <manvolnum>9</manvolnum> 17653 <refmiscinfo class="version">4.1.27</refmiscinfo> 17654</refmeta> 17655<refnamediv> 17656 <refname>__splice_from_pipe</refname> 17657 <refpurpose> 17658 splice data from a pipe to given actor 17659 </refpurpose> 17660</refnamediv> 17661<refsynopsisdiv> 17662 <title>Synopsis</title> 17663 <funcsynopsis><funcprototype> 17664 <funcdef>ssize_t <function>__splice_from_pipe </function></funcdef> 17665 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17666 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17667 <paramdef>splice_actor * <parameter>actor</parameter></paramdef> 17668 </funcprototype></funcsynopsis> 17669</refsynopsisdiv> 17670<refsect1> 17671 <title>Arguments</title> 17672 <variablelist> 17673 <varlistentry> 17674 <term><parameter>pipe</parameter></term> 17675 <listitem> 17676 <para> 17677 pipe to splice from 17678 </para> 17679 </listitem> 17680 </varlistentry> 17681 <varlistentry> 17682 <term><parameter>sd</parameter></term> 17683 <listitem> 17684 <para> 17685 information to <parameter>actor</parameter> 17686 </para> 17687 </listitem> 17688 </varlistentry> 17689 <varlistentry> 17690 <term><parameter>actor</parameter></term> 17691 <listitem> 17692 <para> 17693 handler that splices the data 17694 </para> 17695 </listitem> 17696 </varlistentry> 17697 </variablelist> 17698</refsect1> 17699<refsect1> 17700<title>Description</title> 17701<para> 17702 This function does little more than loop over the pipe and call 17703 <parameter>actor</parameter> to do the actual moving of a single struct pipe_buffer to 17704 the desired destination. See pipe_to_file, pipe_to_sendpage, or 17705 pipe_to_user. 17706</para> 17707</refsect1> 17708</refentry> 17709 17710<refentry id="API-splice-from-pipe"> 17711<refentryinfo> 17712 <title>LINUX</title> 17713 <productname>Kernel Hackers Manual</productname> 17714 <date>July 2017</date> 17715</refentryinfo> 17716<refmeta> 17717 <refentrytitle><phrase>splice_from_pipe</phrase></refentrytitle> 17718 <manvolnum>9</manvolnum> 17719 <refmiscinfo class="version">4.1.27</refmiscinfo> 17720</refmeta> 17721<refnamediv> 17722 <refname>splice_from_pipe</refname> 17723 <refpurpose> 17724 splice data from a pipe to a file 17725 </refpurpose> 17726</refnamediv> 17727<refsynopsisdiv> 17728 <title>Synopsis</title> 17729 <funcsynopsis><funcprototype> 17730 <funcdef>ssize_t <function>splice_from_pipe </function></funcdef> 17731 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17732 <paramdef>struct file * <parameter>out</parameter></paramdef> 17733 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 17734 <paramdef>size_t <parameter>len</parameter></paramdef> 17735 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 17736 <paramdef>splice_actor * <parameter>actor</parameter></paramdef> 17737 </funcprototype></funcsynopsis> 17738</refsynopsisdiv> 17739<refsect1> 17740 <title>Arguments</title> 17741 <variablelist> 17742 <varlistentry> 17743 <term><parameter>pipe</parameter></term> 17744 <listitem> 17745 <para> 17746 pipe to splice from 17747 </para> 17748 </listitem> 17749 </varlistentry> 17750 <varlistentry> 17751 <term><parameter>out</parameter></term> 17752 <listitem> 17753 <para> 17754 file to splice to 17755 </para> 17756 </listitem> 17757 </varlistentry> 17758 <varlistentry> 17759 <term><parameter>ppos</parameter></term> 17760 <listitem> 17761 <para> 17762 position in <parameter>out</parameter> 17763 </para> 17764 </listitem> 17765 </varlistentry> 17766 <varlistentry> 17767 <term><parameter>len</parameter></term> 17768 <listitem> 17769 <para> 17770 how many bytes to splice 17771 </para> 17772 </listitem> 17773 </varlistentry> 17774 <varlistentry> 17775 <term><parameter>flags</parameter></term> 17776 <listitem> 17777 <para> 17778 splice modifier flags 17779 </para> 17780 </listitem> 17781 </varlistentry> 17782 <varlistentry> 17783 <term><parameter>actor</parameter></term> 17784 <listitem> 17785 <para> 17786 handler that splices the data 17787 </para> 17788 </listitem> 17789 </varlistentry> 17790 </variablelist> 17791</refsect1> 17792<refsect1> 17793<title>Description</title> 17794<para> 17795 See __splice_from_pipe. This function locks the pipe inode, 17796 otherwise it's identical to <function>__splice_from_pipe</function>. 17797</para> 17798</refsect1> 17799</refentry> 17800 17801<refentry id="API-iter-file-splice-write"> 17802<refentryinfo> 17803 <title>LINUX</title> 17804 <productname>Kernel Hackers Manual</productname> 17805 <date>July 2017</date> 17806</refentryinfo> 17807<refmeta> 17808 <refentrytitle><phrase>iter_file_splice_write</phrase></refentrytitle> 17809 <manvolnum>9</manvolnum> 17810 <refmiscinfo class="version">4.1.27</refmiscinfo> 17811</refmeta> 17812<refnamediv> 17813 <refname>iter_file_splice_write</refname> 17814 <refpurpose> 17815 splice data from a pipe to a file 17816 </refpurpose> 17817</refnamediv> 17818<refsynopsisdiv> 17819 <title>Synopsis</title> 17820 <funcsynopsis><funcprototype> 17821 <funcdef>ssize_t <function>iter_file_splice_write </function></funcdef> 17822 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17823 <paramdef>struct file * <parameter>out</parameter></paramdef> 17824 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 17825 <paramdef>size_t <parameter>len</parameter></paramdef> 17826 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 17827 </funcprototype></funcsynopsis> 17828</refsynopsisdiv> 17829<refsect1> 17830 <title>Arguments</title> 17831 <variablelist> 17832 <varlistentry> 17833 <term><parameter>pipe</parameter></term> 17834 <listitem> 17835 <para> 17836 pipe info 17837 </para> 17838 </listitem> 17839 </varlistentry> 17840 <varlistentry> 17841 <term><parameter>out</parameter></term> 17842 <listitem> 17843 <para> 17844 file to write to 17845 </para> 17846 </listitem> 17847 </varlistentry> 17848 <varlistentry> 17849 <term><parameter>ppos</parameter></term> 17850 <listitem> 17851 <para> 17852 position in <parameter>out</parameter> 17853 </para> 17854 </listitem> 17855 </varlistentry> 17856 <varlistentry> 17857 <term><parameter>len</parameter></term> 17858 <listitem> 17859 <para> 17860 number of bytes to splice 17861 </para> 17862 </listitem> 17863 </varlistentry> 17864 <varlistentry> 17865 <term><parameter>flags</parameter></term> 17866 <listitem> 17867 <para> 17868 splice modifier flags 17869 </para> 17870 </listitem> 17871 </varlistentry> 17872 </variablelist> 17873</refsect1> 17874<refsect1> 17875<title>Description</title> 17876<para> 17877 Will either move or copy pages (determined by <parameter>flags</parameter> options) from 17878 the given pipe inode to the given file. 17879 This one is ->write_iter-based. 17880</para> 17881</refsect1> 17882</refentry> 17883 17884<refentry id="API-generic-splice-sendpage"> 17885<refentryinfo> 17886 <title>LINUX</title> 17887 <productname>Kernel Hackers Manual</productname> 17888 <date>July 2017</date> 17889</refentryinfo> 17890<refmeta> 17891 <refentrytitle><phrase>generic_splice_sendpage</phrase></refentrytitle> 17892 <manvolnum>9</manvolnum> 17893 <refmiscinfo class="version">4.1.27</refmiscinfo> 17894</refmeta> 17895<refnamediv> 17896 <refname>generic_splice_sendpage</refname> 17897 <refpurpose> 17898 splice data from a pipe to a socket 17899 </refpurpose> 17900</refnamediv> 17901<refsynopsisdiv> 17902 <title>Synopsis</title> 17903 <funcsynopsis><funcprototype> 17904 <funcdef>ssize_t <function>generic_splice_sendpage </function></funcdef> 17905 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 17906 <paramdef>struct file * <parameter>out</parameter></paramdef> 17907 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 17908 <paramdef>size_t <parameter>len</parameter></paramdef> 17909 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 17910 </funcprototype></funcsynopsis> 17911</refsynopsisdiv> 17912<refsect1> 17913 <title>Arguments</title> 17914 <variablelist> 17915 <varlistentry> 17916 <term><parameter>pipe</parameter></term> 17917 <listitem> 17918 <para> 17919 pipe to splice from 17920 </para> 17921 </listitem> 17922 </varlistentry> 17923 <varlistentry> 17924 <term><parameter>out</parameter></term> 17925 <listitem> 17926 <para> 17927 socket to write to 17928 </para> 17929 </listitem> 17930 </varlistentry> 17931 <varlistentry> 17932 <term><parameter>ppos</parameter></term> 17933 <listitem> 17934 <para> 17935 position in <parameter>out</parameter> 17936 </para> 17937 </listitem> 17938 </varlistentry> 17939 <varlistentry> 17940 <term><parameter>len</parameter></term> 17941 <listitem> 17942 <para> 17943 number of bytes to splice 17944 </para> 17945 </listitem> 17946 </varlistentry> 17947 <varlistentry> 17948 <term><parameter>flags</parameter></term> 17949 <listitem> 17950 <para> 17951 splice modifier flags 17952 </para> 17953 </listitem> 17954 </varlistentry> 17955 </variablelist> 17956</refsect1> 17957<refsect1> 17958<title>Description</title> 17959<para> 17960 Will send <parameter>len</parameter> bytes from the pipe to a network socket. No data copying 17961 is involved. 17962</para> 17963</refsect1> 17964</refentry> 17965 17966<refentry id="API-splice-direct-to-actor"> 17967<refentryinfo> 17968 <title>LINUX</title> 17969 <productname>Kernel Hackers Manual</productname> 17970 <date>July 2017</date> 17971</refentryinfo> 17972<refmeta> 17973 <refentrytitle><phrase>splice_direct_to_actor</phrase></refentrytitle> 17974 <manvolnum>9</manvolnum> 17975 <refmiscinfo class="version">4.1.27</refmiscinfo> 17976</refmeta> 17977<refnamediv> 17978 <refname>splice_direct_to_actor</refname> 17979 <refpurpose> 17980 splices data directly between two non-pipes 17981 </refpurpose> 17982</refnamediv> 17983<refsynopsisdiv> 17984 <title>Synopsis</title> 17985 <funcsynopsis><funcprototype> 17986 <funcdef>ssize_t <function>splice_direct_to_actor </function></funcdef> 17987 <paramdef>struct file * <parameter>in</parameter></paramdef> 17988 <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef> 17989 <paramdef>splice_direct_actor * <parameter>actor</parameter></paramdef> 17990 </funcprototype></funcsynopsis> 17991</refsynopsisdiv> 17992<refsect1> 17993 <title>Arguments</title> 17994 <variablelist> 17995 <varlistentry> 17996 <term><parameter>in</parameter></term> 17997 <listitem> 17998 <para> 17999 file to splice from 18000 </para> 18001 </listitem> 18002 </varlistentry> 18003 <varlistentry> 18004 <term><parameter>sd</parameter></term> 18005 <listitem> 18006 <para> 18007 actor information on where to splice to 18008 </para> 18009 </listitem> 18010 </varlistentry> 18011 <varlistentry> 18012 <term><parameter>actor</parameter></term> 18013 <listitem> 18014 <para> 18015 handles the data splicing 18016 </para> 18017 </listitem> 18018 </varlistentry> 18019 </variablelist> 18020</refsect1> 18021<refsect1> 18022<title>Description</title> 18023<para> 18024 This is a special case helper to splice directly between two 18025 points, without requiring an explicit pipe. Internally an allocated 18026 pipe is cached in the process, and reused during the lifetime of 18027 that process. 18028</para> 18029</refsect1> 18030</refentry> 18031 18032<refentry id="API-do-splice-direct"> 18033<refentryinfo> 18034 <title>LINUX</title> 18035 <productname>Kernel Hackers Manual</productname> 18036 <date>July 2017</date> 18037</refentryinfo> 18038<refmeta> 18039 <refentrytitle><phrase>do_splice_direct</phrase></refentrytitle> 18040 <manvolnum>9</manvolnum> 18041 <refmiscinfo class="version">4.1.27</refmiscinfo> 18042</refmeta> 18043<refnamediv> 18044 <refname>do_splice_direct</refname> 18045 <refpurpose> 18046 splices data directly between two files 18047 </refpurpose> 18048</refnamediv> 18049<refsynopsisdiv> 18050 <title>Synopsis</title> 18051 <funcsynopsis><funcprototype> 18052 <funcdef>long <function>do_splice_direct </function></funcdef> 18053 <paramdef>struct file * <parameter>in</parameter></paramdef> 18054 <paramdef>loff_t * <parameter>ppos</parameter></paramdef> 18055 <paramdef>struct file * <parameter>out</parameter></paramdef> 18056 <paramdef>loff_t * <parameter>opos</parameter></paramdef> 18057 <paramdef>size_t <parameter>len</parameter></paramdef> 18058 <paramdef>unsigned int <parameter>flags</parameter></paramdef> 18059 </funcprototype></funcsynopsis> 18060</refsynopsisdiv> 18061<refsect1> 18062 <title>Arguments</title> 18063 <variablelist> 18064 <varlistentry> 18065 <term><parameter>in</parameter></term> 18066 <listitem> 18067 <para> 18068 file to splice from 18069 </para> 18070 </listitem> 18071 </varlistentry> 18072 <varlistentry> 18073 <term><parameter>ppos</parameter></term> 18074 <listitem> 18075 <para> 18076 input file offset 18077 </para> 18078 </listitem> 18079 </varlistentry> 18080 <varlistentry> 18081 <term><parameter>out</parameter></term> 18082 <listitem> 18083 <para> 18084 file to splice to 18085 </para> 18086 </listitem> 18087 </varlistentry> 18088 <varlistentry> 18089 <term><parameter>opos</parameter></term> 18090 <listitem> 18091 <para> 18092 output file offset 18093 </para> 18094 </listitem> 18095 </varlistentry> 18096 <varlistentry> 18097 <term><parameter>len</parameter></term> 18098 <listitem> 18099 <para> 18100 number of bytes to splice 18101 </para> 18102 </listitem> 18103 </varlistentry> 18104 <varlistentry> 18105 <term><parameter>flags</parameter></term> 18106 <listitem> 18107 <para> 18108 splice modifier flags 18109 </para> 18110 </listitem> 18111 </varlistentry> 18112 </variablelist> 18113</refsect1> 18114<refsect1> 18115<title>Description</title> 18116<para> 18117 For use by <function>do_sendfile</function>. splice can easily emulate sendfile, but 18118 doing it in the application would incur an extra system call 18119 (splice in + splice out, as compared to just <function>sendfile</function>). So this helper 18120 can splice directly through a process-private pipe. 18121</para> 18122</refsect1> 18123</refentry> 18124 18125 </chapter> 18126 18127 <chapter id="pipes"> 18128 <title>pipes API</title> 18129 <para> 18130 Pipe interfaces are all for in-kernel (builtin image) use. 18131 They are not exported for use by modules. 18132 </para> 18133<!-- include/linux/pipe_fs_i.h --> 18134<refentry id="API-struct-pipe-buffer"> 18135<refentryinfo> 18136 <title>LINUX</title> 18137 <productname>Kernel Hackers Manual</productname> 18138 <date>July 2017</date> 18139</refentryinfo> 18140<refmeta> 18141 <refentrytitle><phrase>struct pipe_buffer</phrase></refentrytitle> 18142 <manvolnum>9</manvolnum> 18143 <refmiscinfo class="version">4.1.27</refmiscinfo> 18144</refmeta> 18145<refnamediv> 18146 <refname>struct pipe_buffer</refname> 18147 <refpurpose> 18148 a linux kernel pipe buffer 18149 </refpurpose> 18150</refnamediv> 18151<refsynopsisdiv> 18152 <title>Synopsis</title> 18153 <programlisting> 18154struct pipe_buffer { 18155 struct page * page; 18156 unsigned int offset; 18157 unsigned int len; 18158 const struct pipe_buf_operations * ops; 18159 unsigned int flags; 18160 unsigned long private; 18161}; </programlisting> 18162</refsynopsisdiv> 18163 <refsect1> 18164 <title>Members</title> 18165 <variablelist> 18166 <varlistentry> <term>page</term> 18167 <listitem><para> 18168the page containing the data for the pipe buffer 18169 </para></listitem> 18170 </varlistentry> 18171 <varlistentry> <term>offset</term> 18172 <listitem><para> 18173offset of data inside the <parameter>page</parameter> 18174 </para></listitem> 18175 </varlistentry> 18176 <varlistentry> <term>len</term> 18177 <listitem><para> 18178length of data inside the <parameter>page</parameter> 18179 </para></listitem> 18180 </varlistentry> 18181 <varlistentry> <term>ops</term> 18182 <listitem><para> 18183operations associated with this buffer. See <parameter>pipe_buf_operations</parameter>. 18184 </para></listitem> 18185 </varlistentry> 18186 <varlistentry> <term>flags</term> 18187 <listitem><para> 18188pipe buffer flags. See above. 18189 </para></listitem> 18190 </varlistentry> 18191 <varlistentry> <term>private</term> 18192 <listitem><para> 18193private data owned by the ops. 18194 </para></listitem> 18195 </varlistentry> 18196 </variablelist> 18197 </refsect1> 18198</refentry> 18199 18200<refentry id="API-struct-pipe-inode-info"> 18201<refentryinfo> 18202 <title>LINUX</title> 18203 <productname>Kernel Hackers Manual</productname> 18204 <date>July 2017</date> 18205</refentryinfo> 18206<refmeta> 18207 <refentrytitle><phrase>struct pipe_inode_info</phrase></refentrytitle> 18208 <manvolnum>9</manvolnum> 18209 <refmiscinfo class="version">4.1.27</refmiscinfo> 18210</refmeta> 18211<refnamediv> 18212 <refname>struct pipe_inode_info</refname> 18213 <refpurpose> 18214 a linux kernel pipe 18215 </refpurpose> 18216</refnamediv> 18217<refsynopsisdiv> 18218 <title>Synopsis</title> 18219 <programlisting> 18220struct pipe_inode_info { 18221 struct mutex mutex; 18222 wait_queue_head_t wait; 18223 unsigned int nrbufs; 18224 unsigned int curbuf; 18225 unsigned int buffers; 18226 unsigned int readers; 18227 unsigned int writers; 18228 unsigned int files; 18229 unsigned int waiting_writers; 18230 unsigned int r_counter; 18231 unsigned int w_counter; 18232 struct page * tmp_page; 18233 struct fasync_struct * fasync_readers; 18234 struct fasync_struct * fasync_writers; 18235 struct pipe_buffer * bufs; 18236}; </programlisting> 18237</refsynopsisdiv> 18238 <refsect1> 18239 <title>Members</title> 18240 <variablelist> 18241 <varlistentry> <term>mutex</term> 18242 <listitem><para> 18243 mutex protecting the whole thing 18244 </para></listitem> 18245 </varlistentry> 18246 <varlistentry> <term>wait</term> 18247 <listitem><para> 18248 reader/writer wait point in case of empty/full pipe 18249 </para></listitem> 18250 </varlistentry> 18251 <varlistentry> <term>nrbufs</term> 18252 <listitem><para> 18253 the number of non-empty pipe buffers in this pipe 18254 </para></listitem> 18255 </varlistentry> 18256 <varlistentry> <term>curbuf</term> 18257 <listitem><para> 18258 the current pipe buffer entry 18259 </para></listitem> 18260 </varlistentry> 18261 <varlistentry> <term>buffers</term> 18262 <listitem><para> 18263 total number of buffers (should be a power of 2) 18264 </para></listitem> 18265 </varlistentry> 18266 <varlistentry> <term>readers</term> 18267 <listitem><para> 18268 number of current readers of this pipe 18269 </para></listitem> 18270 </varlistentry> 18271 <varlistentry> <term>writers</term> 18272 <listitem><para> 18273 number of current writers of this pipe 18274 </para></listitem> 18275 </varlistentry> 18276 <varlistentry> <term>files</term> 18277 <listitem><para> 18278 number of struct file referring this pipe (protected by ->i_lock) 18279 </para></listitem> 18280 </varlistentry> 18281 <varlistentry> <term>waiting_writers</term> 18282 <listitem><para> 18283 number of writers blocked waiting for room 18284 </para></listitem> 18285 </varlistentry> 18286 <varlistentry> <term>r_counter</term> 18287 <listitem><para> 18288 reader counter 18289 </para></listitem> 18290 </varlistentry> 18291 <varlistentry> <term>w_counter</term> 18292 <listitem><para> 18293 writer counter 18294 </para></listitem> 18295 </varlistentry> 18296 <varlistentry> <term>tmp_page</term> 18297 <listitem><para> 18298 cached released page 18299 </para></listitem> 18300 </varlistentry> 18301 <varlistentry> <term>fasync_readers</term> 18302 <listitem><para> 18303 reader side fasync 18304 </para></listitem> 18305 </varlistentry> 18306 <varlistentry> <term>fasync_writers</term> 18307 <listitem><para> 18308 writer side fasync 18309 </para></listitem> 18310 </varlistentry> 18311 <varlistentry> <term>bufs</term> 18312 <listitem><para> 18313 the circular array of pipe buffers 18314 </para></listitem> 18315 </varlistentry> 18316 </variablelist> 18317 </refsect1> 18318</refentry> 18319 18320<refentry id="API-generic-pipe-buf-steal"> 18321<refentryinfo> 18322 <title>LINUX</title> 18323 <productname>Kernel Hackers Manual</productname> 18324 <date>July 2017</date> 18325</refentryinfo> 18326<refmeta> 18327 <refentrytitle><phrase>generic_pipe_buf_steal</phrase></refentrytitle> 18328 <manvolnum>9</manvolnum> 18329 <refmiscinfo class="version">4.1.27</refmiscinfo> 18330</refmeta> 18331<refnamediv> 18332 <refname>generic_pipe_buf_steal</refname> 18333 <refpurpose> 18334 attempt to take ownership of a <structname>pipe_buffer</structname> 18335 </refpurpose> 18336</refnamediv> 18337<refsynopsisdiv> 18338 <title>Synopsis</title> 18339 <funcsynopsis><funcprototype> 18340 <funcdef>int <function>generic_pipe_buf_steal </function></funcdef> 18341 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 18342 <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef> 18343 </funcprototype></funcsynopsis> 18344</refsynopsisdiv> 18345<refsect1> 18346 <title>Arguments</title> 18347 <variablelist> 18348 <varlistentry> 18349 <term><parameter>pipe</parameter></term> 18350 <listitem> 18351 <para> 18352 the pipe that the buffer belongs to 18353 </para> 18354 </listitem> 18355 </varlistentry> 18356 <varlistentry> 18357 <term><parameter>buf</parameter></term> 18358 <listitem> 18359 <para> 18360 the buffer to attempt to steal 18361 </para> 18362 </listitem> 18363 </varlistentry> 18364 </variablelist> 18365</refsect1> 18366<refsect1> 18367<title>Description</title> 18368<para> 18369 This function attempts to steal the <structname>struct page</structname> attached to 18370 <parameter>buf</parameter>. If successful, this function returns 0 and returns with 18371 the page locked. The caller may then reuse the page for whatever 18372 he wishes; the typical use is insertion into a different file 18373 page cache. 18374</para> 18375</refsect1> 18376</refentry> 18377 18378<refentry id="API-generic-pipe-buf-get"> 18379<refentryinfo> 18380 <title>LINUX</title> 18381 <productname>Kernel Hackers Manual</productname> 18382 <date>July 2017</date> 18383</refentryinfo> 18384<refmeta> 18385 <refentrytitle><phrase>generic_pipe_buf_get</phrase></refentrytitle> 18386 <manvolnum>9</manvolnum> 18387 <refmiscinfo class="version">4.1.27</refmiscinfo> 18388</refmeta> 18389<refnamediv> 18390 <refname>generic_pipe_buf_get</refname> 18391 <refpurpose> 18392 get a reference to a <structname>struct pipe_buffer</structname> 18393 </refpurpose> 18394</refnamediv> 18395<refsynopsisdiv> 18396 <title>Synopsis</title> 18397 <funcsynopsis><funcprototype> 18398 <funcdef>void <function>generic_pipe_buf_get </function></funcdef> 18399 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 18400 <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef> 18401 </funcprototype></funcsynopsis> 18402</refsynopsisdiv> 18403<refsect1> 18404 <title>Arguments</title> 18405 <variablelist> 18406 <varlistentry> 18407 <term><parameter>pipe</parameter></term> 18408 <listitem> 18409 <para> 18410 the pipe that the buffer belongs to 18411 </para> 18412 </listitem> 18413 </varlistentry> 18414 <varlistentry> 18415 <term><parameter>buf</parameter></term> 18416 <listitem> 18417 <para> 18418 the buffer to get a reference to 18419 </para> 18420 </listitem> 18421 </varlistentry> 18422 </variablelist> 18423</refsect1> 18424<refsect1> 18425<title>Description</title> 18426<para> 18427 This function grabs an extra reference to <parameter>buf</parameter>. It's used in 18428 in the <function>tee</function> system call, when we duplicate the buffers in one 18429 pipe into another. 18430</para> 18431</refsect1> 18432</refentry> 18433 18434<refentry id="API-generic-pipe-buf-confirm"> 18435<refentryinfo> 18436 <title>LINUX</title> 18437 <productname>Kernel Hackers Manual</productname> 18438 <date>July 2017</date> 18439</refentryinfo> 18440<refmeta> 18441 <refentrytitle><phrase>generic_pipe_buf_confirm</phrase></refentrytitle> 18442 <manvolnum>9</manvolnum> 18443 <refmiscinfo class="version">4.1.27</refmiscinfo> 18444</refmeta> 18445<refnamediv> 18446 <refname>generic_pipe_buf_confirm</refname> 18447 <refpurpose> 18448 verify contents of the pipe buffer 18449 </refpurpose> 18450</refnamediv> 18451<refsynopsisdiv> 18452 <title>Synopsis</title> 18453 <funcsynopsis><funcprototype> 18454 <funcdef>int <function>generic_pipe_buf_confirm </function></funcdef> 18455 <paramdef>struct pipe_inode_info * <parameter>info</parameter></paramdef> 18456 <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef> 18457 </funcprototype></funcsynopsis> 18458</refsynopsisdiv> 18459<refsect1> 18460 <title>Arguments</title> 18461 <variablelist> 18462 <varlistentry> 18463 <term><parameter>info</parameter></term> 18464 <listitem> 18465 <para> 18466 the pipe that the buffer belongs to 18467 </para> 18468 </listitem> 18469 </varlistentry> 18470 <varlistentry> 18471 <term><parameter>buf</parameter></term> 18472 <listitem> 18473 <para> 18474 the buffer to confirm 18475 </para> 18476 </listitem> 18477 </varlistentry> 18478 </variablelist> 18479</refsect1> 18480<refsect1> 18481<title>Description</title> 18482<para> 18483 This function does nothing, because the generic pipe code uses 18484 pages that are always good when inserted into the pipe. 18485</para> 18486</refsect1> 18487</refentry> 18488 18489<refentry id="API-generic-pipe-buf-release"> 18490<refentryinfo> 18491 <title>LINUX</title> 18492 <productname>Kernel Hackers Manual</productname> 18493 <date>July 2017</date> 18494</refentryinfo> 18495<refmeta> 18496 <refentrytitle><phrase>generic_pipe_buf_release</phrase></refentrytitle> 18497 <manvolnum>9</manvolnum> 18498 <refmiscinfo class="version">4.1.27</refmiscinfo> 18499</refmeta> 18500<refnamediv> 18501 <refname>generic_pipe_buf_release</refname> 18502 <refpurpose> 18503 put a reference to a <structname>struct pipe_buffer</structname> 18504 </refpurpose> 18505</refnamediv> 18506<refsynopsisdiv> 18507 <title>Synopsis</title> 18508 <funcsynopsis><funcprototype> 18509 <funcdef>void <function>generic_pipe_buf_release </function></funcdef> 18510 <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef> 18511 <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef> 18512 </funcprototype></funcsynopsis> 18513</refsynopsisdiv> 18514<refsect1> 18515 <title>Arguments</title> 18516 <variablelist> 18517 <varlistentry> 18518 <term><parameter>pipe</parameter></term> 18519 <listitem> 18520 <para> 18521 the pipe that the buffer belongs to 18522 </para> 18523 </listitem> 18524 </varlistentry> 18525 <varlistentry> 18526 <term><parameter>buf</parameter></term> 18527 <listitem> 18528 <para> 18529 the buffer to put a reference to 18530 </para> 18531 </listitem> 18532 </varlistentry> 18533 </variablelist> 18534</refsect1> 18535<refsect1> 18536<title>Description</title> 18537<para> 18538 This function releases a reference to <parameter>buf</parameter>. 18539</para> 18540</refsect1> 18541</refentry> 18542 18543 </chapter> 18544 18545</book> 18546