From 7dfb43254cc64044e75a5da4bbf02a86d110aee3 Mon Sep 17 00:00:00 2001 From: Miklos Szeredi Date: Wed, 17 Jul 2013 15:58:53 +0200 Subject: [PATCH] Documentation fixes --- doc/mainpage.dox | 18 +++++++++--------- example/fioc.c | 2 +- example/fioc.h | 2 +- example/hello.c | 2 -- example/hello_ll.c | 15 ++++++++------- example/null.c | 2 +- include/fuse.h | 39 ++++++++++++++++++--------------------- include/fuse_common.h | 9 +++++---- include/fuse_lowlevel.h | 11 ++++++----- 9 files changed, 49 insertions(+), 51 deletions(-) diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 920220774..9b1801fef 100755 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -1,11 +1,11 @@ /*! \mainpage FUSE API documentation -Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like computer operating systems that lets non-privileged users create their own file systems without editing kernel code. This is achieved by running file system code in user space while the FUSE module provides only a "bridge" to the actual kernel interfaces. +Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like computer operating systems that lets non-privileged users create their own file systems without editing kernel code. This is achieved by running file system code in user space while the FUSE module provides only a "bridge" to the actual kernel interfaces. (c) Wikipedia -@tableofcontents +@tableofcontents @@ -22,7 +22,7 @@ Filesystem in Userspace (FUSE) is a loadable kernel module for Unix-like compute \section section2 Kernel -\include kernel.txt +\include kernel.txt @@ -57,20 +57,20 @@ have a look at the examples listed in the example directory, which can be found http://sourceforge.net/apps/mediawiki/fuse/index.php?title=Main_Page - the fuse wiki -http://en.wikipedia.org/wiki/Filesystem_in_Userspace - FUSE on wikipedia +http://en.wikipedia.org/wiki/Filesystem_in_Userspace - FUSE on wikipedia \section section_todo todo general: - + - fuse_lowlevel.h, describe: - a channel (or communication channel) is created by fuse_mount(..) - a fuse session is associated with a channel and a signal handler and runs until the assigned signal handler shuts the session down, see fuse_session_loop(se) and hello_ll.c - + - http://www.cs.nmsu.edu/~pfeiffer/fuse-tutorial/ - + - http://cinwell.wordpress.com/ - http://sourceforge.net/apps/mediawiki/fuse/index.php?title=FuseProtocolSketch @@ -78,10 +78,10 @@ general: - http://muratbuffalo.blogspot.de/2011/05/refuse-to-crash-with-re-fuse.html examples: - - demonstrate the effect of single vs multithreaded -> fuse_loop fuse_loop_mt + - demonstrate the effect of single vs multithreaded -> fuse_loop fuse_loop_mt - add comments and source form all existing examples - + - also add examples form here: http://sourceforge.net/apps/mediawiki/fuse/index.php?title=Main_Page#How_should_threads_be_startedx3f - add this new example: http://fuse.996288.n3.nabble.com/Create-multiple-filesystems-in-same-process-td9292.html diff --git a/example/fioc.c b/example/fioc.c index cfb18aea6..c79c734e8 100755 --- a/example/fioc.c +++ b/example/fioc.c @@ -18,7 +18,7 @@ * gcc -Wall fioc.c `pkg-config fuse --cflags --libs` -o fioc * * \section section_source the complete source - * \include fioc.c + * \include fioc.c */ diff --git a/example/fioc.h b/example/fioc.h index c9bf3583a..42799aa5d 100755 --- a/example/fioc.h +++ b/example/fioc.h @@ -11,7 +11,7 @@ * @tableofcontents * * fioc.h - FUSE-ioctl: ioctl support for FUSE - * + * * \include fioc.h */ diff --git a/example/hello.c b/example/hello.c index 580bff2a2..f678931d3 100755 --- a/example/hello.c +++ b/example/hello.c @@ -108,7 +108,6 @@ static int hello_read(const char *path, char *buf, size_t size, off_t offset, return size; } -// fuse_operations hello_oper is redirecting function-calls to _our_ functions implemented above static struct fuse_operations hello_oper = { .getattr = hello_getattr, .readdir = hello_readdir, @@ -116,7 +115,6 @@ static struct fuse_operations hello_oper = { .read = hello_read, }; -// in the main function we call the blocking fuse_main(..) function with &hello_oper int main(int argc, char *argv[]) { return fuse_main(argc, argv, &hello_oper, NULL); diff --git a/example/hello_ll.c b/example/hello_ll.c index 06c881b3b..151fe8b6d 100755 --- a/example/hello_ll.c +++ b/example/hello_ll.c @@ -9,9 +9,9 @@ /** @file * * hello_ll.c - fuse low level functionality - * + * * unlike hello.c this example will stay in the foreground. it also replaced - * the convenience function fuse_main(..) with a more low level approach. + * the convenience function fuse_main(..) with a more low level approach. * * \section section_compile compiling this example * @@ -20,7 +20,7 @@ * \section section_usage usage \verbatim % mkdir mnt - % ./hello_ll mnt # program will wait in foreground until you press CTRL+C + % ./hello_ll mnt # program will wait in foreground until you press CTRL+C in a different shell do: % ls -la mnt total 4 @@ -191,15 +191,16 @@ int main(int argc, char *argv[]) if (fuse_parse_cmdline(&args, &mountpoint, NULL, NULL) != -1 && (ch = fuse_mount(mountpoint, &args)) != NULL) { struct fuse_session *se; + se = fuse_lowlevel_new(&args, &hello_ll_oper, sizeof(hello_ll_oper), NULL); if (se != NULL) { if (fuse_set_signal_handlers(se) != -1) { fuse_session_add_chan(se, ch); - - /* fuse_session_loop(..) blocks until ctrl+c or fusermount -u */ - err = fuse_session_loop(se); - + + /* Block until ctrl+c or fusermount -u */ + err = fuse_session_loop(se); + fuse_remove_signal_handlers(se); fuse_session_remove_chan(ch); } diff --git a/example/null.c b/example/null.c index 695233331..3e57dbe9f 100755 --- a/example/null.c +++ b/example/null.c @@ -8,7 +8,7 @@ /** @file * - * null.c - FUSE: Filesystem in Userspace + * null.c - FUSE: Filesystem in Userspace * * \section section_compile compiling this example * diff --git a/include/fuse.h b/include/fuse.h index c7647ce02..b8a93074e 100644 --- a/include/fuse.h +++ b/include/fuse.h @@ -114,7 +114,7 @@ struct fuse_operations { */ int (*mknod) (const char *, mode_t, dev_t); - /** Create a directory + /** Create a directory * * Note that the mode argument may not have the type specification * bits set, i.e. S_ISDIR(mode) can be false. To obtain the @@ -589,7 +589,7 @@ struct fuse_context { * @param op the file system operation * @param user_data user data supplied in the context during the init() method * @return 0 on success, nonzero on failure - * + * * Example usage, see hello.c */ /* @@ -637,7 +637,7 @@ void fuse_destroy(struct fuse *f); * * @param f the FUSE handle * @return 0 if no error occurred, -1 otherwise - * + * * See also: fuse_loop() */ int fuse_loop(struct fuse *f); @@ -658,27 +658,24 @@ void fuse_exit(struct fuse *f); * * Calling this function requires the pthreads library to be linked to * the application. - * - * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in single-threaded mode, - * and that you will not have to worry about reentrancy, - * though you will have to worry about recursive lookups. In single-threaded mode, FUSE - * holds a global lock on your filesystem, and will wait for one callback to return - * before calling another. This can lead to deadlocks, if your script makes any attempt - * to access files or directories in the filesystem it is providing. - * (This includes calling stat() on the mount-point, statfs() calls from the 'df' command, - * and so on and so forth.) It is worth paying a little attention and being careful about this. - * - * Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make multiple simultaneous - * calls into the various callback functions given by your fuse_operations record. - * - * If you are using multiple threads, you can enjoy all the parallel execution and interactive - * response benefits of threads, and you get to enjoy all the benefits of race conditions - * and locking bugs, too. Ensure that any code used in the callback funtion of fuse_operations - * is also thread-safe. + * + * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in + * single-threaded mode, and that you will not have to worry about reentrancy, + * though you will have to worry about recursive lookups. In single-threaded + * mode, FUSE will wait for one callback to return before calling another. + * + * Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make + * multiple simultaneous calls into the various callback functions given by your + * fuse_operations record. + * + * If you are using multiple threads, you can enjoy all the parallel execution + * and interactive response benefits of threads, and you get to enjoy all the + * benefits of race conditions and locking bugs, too. Ensure that any code used + * in the callback funtion of fuse_operations is also thread-safe. * * @param f the FUSE handle * @return 0 if no error occurred, -1 otherwise - * + * * See also: fuse_loop() */ int fuse_loop_mt(struct fuse *f); diff --git a/include/fuse_common.h b/include/fuse_common.h index 9fd4bbb09..35706cb27 100644 --- a/include/fuse_common.h +++ b/include/fuse_common.h @@ -451,12 +451,13 @@ ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src, * Stores session in a global variable. May only be called once per * process until fuse_remove_signal_handlers() is called. * - * Once either of the POSIX signals arrives, the exit_handler() in fuse_signals.c is called: + * Once either of the POSIX signals arrives, the exit_handler() in + * fuse_signals.c is called: * \snippet fuse_signals.c doxygen_exit_handler - * + * * @param se the session to exit * @return 0 on success, -1 on failure - * + * * See also: * fuse_remove_signal_handlers() */ @@ -469,7 +470,7 @@ int fuse_set_signal_handlers(struct fuse_session *se); * be called again. * * @param se the same session as given in fuse_set_signal_handlers() - * + * * See also: * fuse_set_signal_handlers() */ diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h index 6075b03e7..df1f770ff 100644 --- a/include/fuse_lowlevel.h +++ b/include/fuse_lowlevel.h @@ -1566,7 +1566,7 @@ int fuse_req_interrupted(fuse_req_t req); * @param userdata user data * @return the created session object, or NULL on failure * - * Example: See hello_ll.c: + * Example: See hello_ll.c: * \snippet hello_ll.c doxygen_fuse_lowlevel_usage */ struct fuse_session *fuse_lowlevel_new(struct fuse_args *args, @@ -1638,9 +1638,10 @@ int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf, void fuse_session_destroy(struct fuse_session *se); /** - * Exit a session. This function is invoked by the POSIX signal handlers, when registered using: + * Exit a session. + * + * This function is invoked by the POSIX signal handlers, when registered using: * * fuse_set_signal_handlers() - * * fuse_remove_signal_handlers() * * @param se the session */ @@ -1665,8 +1666,8 @@ int fuse_session_exited(struct fuse_session *se); * Enter a single threaded, blocking event loop. * * Using POSIX signals this event loop can be exited but the session - * needs to be configued by issuing: - * fuse_set_signal_handlers() first. + * needs to be configued by issuing: + * fuse_set_signal_handlers() first. * * @param se the session * @return 0 on success, -1 on error