From a668d264d6d123bba3e33b0af39e2cacce88d047 Mon Sep 17 00:00:00 2001 From: Nikolaus Rath Date: Sun, 9 Oct 2016 20:18:38 -0700 Subject: Include testfsN examples in Doxygen documentation. --- example/timefs1.c | 95 ++++++++++++++++++++++------------------- example/timefs2.c | 93 +++++++++++++++++++++++------------------ example/timefs3.c | 123 +++++++++++++++++++++++++++++------------------------- 3 files changed, 172 insertions(+), 139 deletions(-) diff --git a/example/timefs1.c b/example/timefs1.c index 430e00f..50363fd 100644 --- a/example/timefs1.c +++ b/example/timefs1.c @@ -4,50 +4,61 @@ This program can be distributed under the terms of the GNU GPL. See the file COPYING. +*/ - This example implements a file system with a single file whose - contents change dynamically: it always contains the current time. - - While timefs2.c uses fuse_lowlevel_notify_store() to actively push - the updated data into the kernel cache, this example uses - fuse_lowlevel_notify_inval_inode() to notify the kernel that the - cache has to be invalidated - but the kernel still has to explicitly - request the updated data on the next read. - - To see the effect, first start the file system with the - ``--no-notify`` option: - - $ timefs --update-interval=1 --no-notify mnt/ - - Observe that the output never changes, even though the file system - updates it once per second. This is because the contents are cached - in the kernel: - - $ for i in 1 2 3 4 5; do - > cat mnt/current_time - > sleep 1 - > done - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - - If you instead enable the notification functions, the changes become - visible: - - $ timefs --update-interval=1 mnt/ - $ for i in 1 2 3 4 5; do - > cat mnt/current_time - > sleep 1 - > done - The current time is 15:58:40 - The current time is 15:58:41 - The current time is 15:58:42 - The current time is 15:58:43 - The current time is 15:58:44 +/** @file + * @tableofcontents + * + * This example implements a file system with a single file whose + * contents change dynamically: it always contains the current time. + * + * While timefs2.c uses fuse_lowlevel_notify_store() to actively push + * the updated data into the kernel cache, this example uses + * fuse_lowlevel_notify_inval_inode() to notify the kernel that the + * cache has to be invalidated - but the kernel still has to explicitly + * request the updated data on the next read. + * + * To see the effect, first start the file system with the + * ``--no-notify`` option: + * + * $ timefs --update-interval=1 --no-notify mnt/ + * + * Observe that the output never changes, even though the file system + * updates it once per second. This is because the contents are cached + * in the kernel: + * + * $ for i in 1 2 3 4 5; do + * > cat mnt/current_time + * > sleep 1 + * > done + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * + * If you instead enable the notification functions, the changes become + * visible: + * + * $ timefs --update-interval=1 mnt/ + * $ for i in 1 2 3 4 5; do + * > cat mnt/current_time + * > sleep 1 + * > done + * The current time is 15:58:40 + * The current time is 15:58:41 + * The current time is 15:58:42 + * The current time is 15:58:43 + * The current time is 15:58:44 + * + * \section section_compile compiling this example + * + * gcc -Wall timefs1.c `pkg-config fuse3 --cflags --libs` -o timefs1 + * + * \section section_source the complete source + * \include timefs1.c + */ -*/ #define FUSE_USE_VERSION 30 diff --git a/example/timefs2.c b/example/timefs2.c index ea10cc1..ae3fe99 100644 --- a/example/timefs2.c +++ b/example/timefs2.c @@ -4,49 +4,60 @@ This program can be distributed under the terms of the GNU GPL. See the file COPYING. +*/ - This example implements a file system with a single file whose - contents change dynamically: it always contains the current time. - - While timefs1.c uses fuse_lowlevel_notify_inval_inode() to let the - kernel know that it has to invalidate the cache, this example - actively pushes the updated data into the kernel cache using - fuse_lowlevel_notify_store(). - - To see the effect, first start the file system with the - ``--no-notify`` option: - - $ timefs --update-interval=1 --no-notify mnt/ - - Observe that the output never changes, even though the file system - updates it once per second. This is because the contents are cached - in the kernel: - - $ for i in 1 2 3 4 5; do - > cat mnt/current_time - > sleep 1 - > done - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - The current time is 15:58:18 - - If you instead enable the notification functions, the changes become - visible: - - $ timefs --update-interval=1 mnt/ - $ for i in 1 2 3 4 5; do - > cat mnt/current_time - > sleep 1 - > done - The current time is 15:58:40 - The current time is 15:58:41 - The current time is 15:58:42 - The current time is 15:58:43 - The current time is 15:58:44 +/** @file + * @tableofcontents + * + * This example implements a file system with a single file whose + * contents change dynamically: it always contains the current time. + * + * While timefs1.c uses fuse_lowlevel_notify_inval_inode() to let the + * kernel know that it has to invalidate the cache, this example + * actively pushes the updated data into the kernel cache using + * fuse_lowlevel_notify_store(). + * + * To see the effect, first start the file system with the + * ``--no-notify`` option: + * + * $ timefs --update-interval=1 --no-notify mnt/ + * + * Observe that the output never changes, even though the file system + * updates it once per second. This is because the contents are cached + * in the kernel: + * + * $ for i in 1 2 3 4 5; do + * > cat mnt/current_time + * > sleep 1 + * > done + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * The current time is 15:58:18 + * + * If you instead enable the notification functions, the changes become + * visible: + * + * $ timefs --update-interval=1 mnt/ + * $ for i in 1 2 3 4 5; do + * > cat mnt/current_time + * > sleep 1 + * > done + * The current time is 15:58:40 + * The current time is 15:58:41 + * The current time is 15:58:42 + * The current time is 15:58:43 + * The current time is 15:58:44 + * + * \section section_compile compiling this example + * + * gcc -Wall timefs2.c `pkg-config fuse3 --cflags --libs` -o timefs2 + * + * \section section_source the complete source + * \include timefs2.c + */ -*/ #define FUSE_USE_VERSION 30 diff --git a/example/timefs3.c b/example/timefs3.c index c04b81c..613407c 100644 --- a/example/timefs3.c +++ b/example/timefs3.c @@ -4,64 +4,75 @@ This program can be distributed under the terms of the GNU GPL. See the file COPYING. +*/ - This example implements a file system with a single file whose - file name changes dynamically to reflect the current time. - - It illustrates the use of the fuse_lowlevel_notify_inval_entry() - function. - - To see the effect, first start the file system with the - ``--no-notify`` - - $ timefs --update-interval=1 --timeout 30 --no-notify mnt/ - - Observe that `ls` always prints the correct directory contents - (since `readdir` output is not cached):: - - $ ls mnt; sleep 1; ls mnt; sleep 1; ls mnt - Time_is_15h_48m_33s current_time - Time_is_15h_48m_34s current_time - Time_is_15h_48m_35s current_time - - However, if you try to access a file by name the kernel will - report that it still exists: - - $ file=$(ls mnt/); echo $file - Time_is_15h_50m_09s - $ sleep 5; stat mnt/$file - File: ‘mnt/Time_is_15h_50m_09s’ - Size: 32 Blocks: 0 IO Block: 4096 regular file - Device: 2ah/42d Inode: 3 Links: 1 - Access: (0444/-r--r--r--) Uid: ( 0/ root) Gid: ( 0/ root) - Access: 1969-12-31 16:00:00.000000000 -0800 - Modify: 1969-12-31 16:00:00.000000000 -0800 - Change: 1969-12-31 16:00:00.000000000 -0800 - Birth: - - - Only once the kernel cache timeout has been reached will the stat - call fail: - - $ sleep 30; stat mnt/$file - stat: cannot stat ‘mnt/Time_is_15h_50m_09s’: No such file or directory - - In contrast, if you enable notifications you will be unable to stat - the file as soon as the file system updates its name: - - $ timefs --update-interval=1 --timeout 30 --no-notify mnt/ - $ file=$(ls mnt/); stat mnt/$file - File: ‘mnt/Time_is_20h_42m_11s’ - Size: 0 Blocks: 0 IO Block: 4096 regular empty file - Device: 2ah/42d Inode: 2 Links: 1 - Access: (0000/----------) Uid: ( 0/ root) Gid: ( 0/ root) - Access: 1969-12-31 16:00:00.000000000 -0800 - Modify: 1969-12-31 16:00:00.000000000 -0800 - Change: 1969-12-31 16:00:00.000000000 -0800 - Birth: - - $ sleep 1; stat mnt/$file - stat: cannot stat ‘mnt/Time_is_20h_42m_11s’: No such file or directory +/** @file + * @tableofcontents + * + * This example implements a file system with a single file whose + * file name changes dynamically to reflect the current time. + * + * It illustrates the use of the fuse_lowlevel_notify_inval_entry() + * function. + * + * To see the effect, first start the file system with the + * ``--no-notify`` + * + * $ timefs --update-interval=1 --timeout 30 --no-notify mnt/ + * + * Observe that `ls` always prints the correct directory contents + * (since `readdir` output is not cached):: + * + * $ ls mnt; sleep 1; ls mnt; sleep 1; ls mnt + * Time_is_15h_48m_33s current_time + * Time_is_15h_48m_34s current_time + * Time_is_15h_48m_35s current_time + * + * However, if you try to access a file by name the kernel will + * report that it still exists: + * + * $ file=$(ls mnt/); echo $file + * Time_is_15h_50m_09s + * $ sleep 5; stat mnt/$file + * File: ‘mnt/Time_is_15h_50m_09s’ + * Size: 32 Blocks: 0 IO Block: 4096 regular file + * Device: 2ah/42d Inode: 3 Links: 1 + * Access: (0444/-r--r--r--) Uid: ( 0/ root) Gid: ( 0/ root) + * Access: 1969-12-31 16:00:00.000000000 -0800 + * Modify: 1969-12-31 16:00:00.000000000 -0800 + * Change: 1969-12-31 16:00:00.000000000 -0800 + * Birth: - + * + * Only once the kernel cache timeout has been reached will the stat + * call fail: + * + * $ sleep 30; stat mnt/$file + * stat: cannot stat ‘mnt/Time_is_15h_50m_09s’: No such file or directory + * + * In contrast, if you enable notifications you will be unable to stat + * the file as soon as the file system updates its name: + * + * $ timefs --update-interval=1 --timeout 30 --no-notify mnt/ + * $ file=$(ls mnt/); stat mnt/$file + * File: ‘mnt/Time_is_20h_42m_11s’ + * Size: 0 Blocks: 0 IO Block: 4096 regular empty file + * Device: 2ah/42d Inode: 2 Links: 1 + * Access: (0000/----------) Uid: ( 0/ root) Gid: ( 0/ root) + * Access: 1969-12-31 16:00:00.000000000 -0800 + * Modify: 1969-12-31 16:00:00.000000000 -0800 + * Change: 1969-12-31 16:00:00.000000000 -0800 + * Birth: - + * $ sleep 1; stat mnt/$file + * stat: cannot stat ‘mnt/Time_is_20h_42m_11s’: No such file or directory + * + * \section section_compile compiling this example + * + * gcc -Wall timefs3.c `pkg-config fuse3 --cflags --libs` -o timefs3 + * + * \section section_source the complete source + * \include timefs3.c + */ -*/ #define FUSE_USE_VERSION 30 -- cgit v1.2.3