lib/libpuffs/puffs_flush.3

   1 .\"     $NetBSD: puffs_flush.3,v 1.7 2008/08/12 19:44:39 pooka 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 These routines are used inform the kernel that any information it might
  62 have cached is no longer valid.
  63 .Fn puffs_inval_namecache_dir
  64 invalidates the name cache for a given directory.
  65 The argument
  66 .Va cookie
  67 should describe an existing and valid directory cookie for the file
  68 system.
  69 Similarly,
  70 .Fn puffs_inval_namecache_all
  71 invalidates the name cache for the entire file system
  72 (this routine might go away).
  73 .Pp
  74 The cached pages (file contents) for a regular file described by
  75 .Va cookie
  76 are invalidated using
  77 .Fn puffs_inval_pagecache_node .
  78 A specific range can be invalidated using
  79 .Fn puffs_inval_pagecache_node_range
  80 for a platform specific page level granularity.
  81 The offset
  82 .Va start
  83 will be
  84 .Em truncated
  85 to a page boundary while
  86 .Va end
  87 will be
  88 .Em "rounded up"
  89 to the next page boundary.
  90 As a special case, specifying 0 as
  91 .Va end
  92 will invalidate all contents from
  93 .Va start
  94 to the end of the file.
  95 .Pp
  96 It is especially important to note that these routines will not only
  97 invalidate data in the "read cache", but also data in the "write back"
  98 cache (conceptually speaking; in reality they are the same cache), which
  99 has not yet been flushed to the file server.
 100 Therefore any unflushed data will be lost.
 101 .Pp
 102 The counterparts of the invalidation routines are the flushing routines
 103 .Fn puffs_flush_pagecache_node
 104 and
 105 .Fn puffs_flush_pagecache_node_range ,
 106 which force unwritten data from the kernel page cache to be written.
 107 For the flush range version, the same range rules as with the
 108 invalidation routine apply.
 109 The data is flushed asynchronously, i.e. if the routine returns
 110 successfully, all the caller knows is that the data has been queued
 111 for writing.
 112 .Sh SEE ALSO
 113 .Xr puffs 3