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