lib/libpuffs/puffs_flush.3

   1 .\"     $NetBSD: puffs_flush.3,v 1.6 2007/12/01 19:54:01 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd April 7, 2007
  27 .Dt PUFFS_FLUSH 3
  28 .Os
  29 .Sh NAME
  30 .Nm puffs_flush
  31 .Nd puffs kernel cache flushing and invalidation routines
  32 .Sh LIBRARY
  33 .Lb libpuffs
  34 .Sh SYNOPSIS
  35 .In puffs.h
  36 .Ft int
  37 .Fo puffs_inval_namecache_dir
  38 .Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie"
  39 .Fc
  40 .Ft int
  41 .Fn puffs_inval_namecache_all "struct puffs_usermount *pu"
  42 .Ft int
  43 .Fo puffs_inval_pagecache_node
  44 .Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie"
  45 .Fc
  46 .Ft int
  47 .Fo puffs_inval_pagecache_node_range
  48 .Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "off_t start"
  49 .Fa "off_t end"
  50 .Fc
  51 .Ft int
  52 .Fo puffs_flush_pagecache_node
  53 .Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie"
  54 .Fc
  55 .Ft int
  56 .Fo puffs_flush_pagecache_node_range
  57 .Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "off_t start"
  58 .Fa "off_t end"
  59 .Fc
  60 .Sh DESCRIPTION
  61 .Em IMPORTANT NOTE!
  62 This document describes interfaces which are not yet guaranteed to be
  63 stable.
  64 In case you update your system sources, please recompile everything
  65 and fix compilation errors.
  66 If your sources are out-of-sync, incorrect operation may result.
  67 The interfaces in this document will most likely be hugely simplified
  68 in later versions or made transparent to the implementation.
  69 .Pp
  70 These routines are used inform the kernel that any information it might
  71 have cached is no longer valid.
  72 .Fn puffs_inval_namecache_dir
  73 invalidates the name cache for a given directory.
  74 The argument
  75 .Va cookie
  76 should describe an existing and valid directory cookie for the file
  77 system.
  78 Similarly,
  79 .Fn puffs_inval_namecache_all
  80 invalidates the name cache for the entire file system
  81 (this routine might go away).
  82 .Pp
  83 The cached pages (file contents) for a regular file described by
  84 .Va cookie
  85 are invalidated using
  86 .Fn puffs_inval_pagecache_node .
  87 A specific range can be invalidated using
  88 .Fn puffs_inval_pagecache_node_range
  89 for a platform specific page level granularity.
  90 The offset
  91 .Va start
  92 will be
  93 .Em truncated
  94 to a page boundary while
  95 .Va end
  96 will be
  97 .Em "rounded up"
  98 to the next page boundary.
  99 As a special case, specifying 0 as
 100 .Va end
 101 will invalidate all contents from
 102 .Va start
 103 to the end of the file.
 104 .Pp
 105 It is especially important to note that these routines will not only
 106 invalidate data in the "read cache", but also data in the "write back"
 107 cache (conceptually speaking; in reality they are the same cache), which
 108 has not yet been flushed to the file server.
 109 Therefore any unflushed data will be lost.
 110 .Pp
 111 The counterparts of the invalidation routines are the flushing routines
 112 .Fn puffs_flush_pagecache_node
 113 and
 114 .Fn puffs_flush_pagecache_node_range ,
 115 which force unwritten data from the kernel page cache to be written.
 116 For the flush range version, the same range rules as with the
 117 invalidation routine apply.
 118 The data is flushed asynchronously, i.e. if the routine returns
 119 successfully, all the caller knows is that the data has been queued
 120 for writing.
 121 .Sh SEE ALSO
 122 .Xr puffs 3