/* Copyright (C) 2005      David Decotigny
   Copyright (C) 2000-2005 The KOS Team (Thomas Petazzoni, David
                           Decotigny, Julien Munier)

   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License
   as published by the Free Software Foundation; either version 2
   of the License, or (at your option) any later version.
   
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
   
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
   USA. 
*/
#ifndef _SOS_FS_NSCACHE_H_
#define _SOS_FS_NSCACHE_H_


/**
 * @file fs_nscache.h
 *
 * FS Namespace cache (aka file hierarchy) management. Internal API
 * reserved to fs.c and to the FS managers ! See fs.c for details and
 * role of this subsystem in the whole VFS.
 *
 * We keep the usual filesystem semantics of a "file hierarchy":
 *
 *        parent0
 *        /     \
 *    child1    child2
 *   /     \         \
 * child1a child1b   child2a
 *
 * The system allows that different children actually reference the
 * same "on-disk" node (sos_fs_node). For example: child1a and child2a
 * might reference the same sos_fs_node: this represents a so-called
 * "hard link".
 *
 * The functions of this module are in charge of updating the nscache
 * nodes and their reference count. They don't influence the other
 * subsystems (apart from the sos_fs_nscache_unref_node() function
 * which can unreference the underlying sos_fs_node).
 *
 * Note: only the nscache nodes that are actually used or those that
 * are their parents (ie in the path from these nodes to the global
 * root) will remain in memory. The others will be destroyed as soon
 * as they are not needed anymore. For example, il I do a
 * stat("/mnt/toto/titi.txt", & st), all the nscache nodes from "/" to
 * "titi.txt" will be allocated, the stat performed, and all of them
 * will be destroyed. We could imagine a real "cache" here to avoid
 * these bursts of allocations/deallocations, by keeping the last
 * accessed nodes aside when they are not referenced anymore (in a
 * hash table for example, the key being {parent nscache node address,
 * child name}).
 *
 * Note about mountpoints: When a FS is mounted in, say "/mnt", the
 * nscache node of the new FS is registered neither as its child nor
 * as its parent, but as a kind of "brother" of /mnt. As seen from the
 * global root ("/"), "mnt" in a direct child and the mounted root is
 * its brother. But, once mounted, as seen from a child node
 * "/mnt/toto", the mounted root is seen as the direct parent of
 * /mnt/toto and "mnt" is seen as its brother. That is, each time we
 * try to resolve (lookup) the children on a mountpoint, we must
 * "follow" the mountchain. In the previous example, multiple
 * successive FS could be mounted on the same "/mnt".
 */

#include <sos/types.h>
#include <sos/errno.h>

/**
 * Opaque structure defined in fs_nscache.c
 *
 * Essentially contains:
 *  - a name (allocated in-place)
 *  - a reference to the associated FS node (struct sos_fs_node)
 *  - a reference to the parent nscache node (if any)
 *  - a list of pointers to the children nscache nodes (for directories)
 */
struct sos_fs_nscache_node;

#include "fs.h"


/**
 * Support for non-0 terminated strings (Pascal-style). Useful to
 * prevent from altering the contents of the string in order to split
 * pathnames into components (@see sos_fs_pathname_split_path)
 */
struct sos_fs_pathname
{
  const char * contents;
  sos_size_t length;
};


sos_ret_t sos_fs_nscache_subsystem_setup(void);


/**
 * Lookup the given entry in the given nsnode. The lookup is limited
 * to the children entries that are already in memory. When this
 * lookup fails, this simply means that the entry is not already in
 * memory, and has to be resolved using disk accesses (@see
 * fs_lookup_node in fs.c)
 *
 * @param cur_nsnode The node in which we are looking for the entry
 * @param root_node The base node beyond which lookup must not go (to
 * support chroot): a kind of "barrier"
 *
 * @param result_nsnode The nsnode for the given entry (set only when
 * the return value is SOS_OK)
 *
 * @return error if the entry could not be found in the nsnode
 * directory. OK otherwise, and *result_nsnode is set.
 *
 * @note The symlinks are NOT expanded. The mountpoints ARE followed.
 * @note result_nsnode is a NEW reference to the node. It should be
 * unreferenced when unused
 */
sos_ret_t
sos_fs_nscache_lookup(struct sos_fs_nscache_node * cur_nsnode,
		      const struct sos_fs_pathname * node_name,
		      const struct sos_fs_nscache_node * root_nsnode,
		      struct sos_fs_nscache_node ** result_nsnode);


/**
 * Add a new child node for the given parent, for the given fs_node
 *
 * @param parent might be NULL, meaning that the node is the root of a
 * mounted filesystem
 *
 * @note The new node has the value 0 for the opened_file and
 * mount_chain counters
 * @note result_nsnode is a NEW reference to the node. It should be
 * unreferenced when unused
 */
sos_ret_t
sos_fs_nscache_add_new_child_node(struct sos_fs_nscache_node * parent,
				  const struct sos_fs_pathname * node_name,
				  struct sos_fs_node * fsnode,
				  struct sos_fs_nscache_node ** result_nsnode);


/**
 * Add a new child node for the given parent, for the given already
 * existing nsnode (with no parent !)
 *
 * @param parent can not be NULL
 *
 * @note nsnode should NOT have any parent
 */
sos_ret_t
sos_fs_nscache_add_existing_child_node(struct sos_fs_nscache_node * parent,
				       const struct sos_fs_pathname * node_name,
				       struct sos_fs_nscache_node * nsnode);


/**
 * Disconnect the given node from its parent, if any
 * @note reference count of nsnode is NOT modified
 */
sos_ret_t
sos_fs_nscache_disconnect_node(struct sos_fs_nscache_node * nsnode);


/**
 * Register the given root of a new file system (mounted_root) in the
 * mountpoint chain located at mountpoint, ie build the mountchain.
 */
sos_ret_t
sos_fs_nscache_mount(struct sos_fs_nscache_node * mountpoint,
		     struct sos_fs_nscache_node * mounted_root);


/**
 * Break the mountchain at the given mounted root, making sure that
 * this nscache node is not reference by any opened file or child node
 * anymore.
 */
sos_ret_t
sos_fs_nscache_umount(struct sos_fs_nscache_node * mounted_root);


/** Return true if the node is involved in any mountchain */
sos_bool_t
sos_fs_nscache_is_mountnode(const struct sos_fs_nscache_node * nsnode);


/*
 * Accessor functions
 */


/**
 * Return the FS node of the given nscache node.
 *
 * @note The FS node returned is NOT newly referenced
 */
struct sos_fs_node *
sos_fs_nscache_get_fs_node(const struct sos_fs_nscache_node * nsnode);


/**
 * Return the parent nscache node of the given nscache node.
 *
 * @note The nscache node returned is NOT newly referenced
 */
sos_ret_t
sos_fs_nscache_get_parent(const struct sos_fs_nscache_node * nsnode,
			  struct sos_fs_nscache_node ** result_parent);


sos_ret_t
sos_fs_nscache_get_name(const struct sos_fs_nscache_node * nsnode,
			struct sos_fs_pathname * result_pathname);


/**
 * Return the value of the reference count for the given nscache node
 */
sos_ret_t
sos_fs_nscache_get_ref_cnt(const struct sos_fs_nscache_node * nsnode);


sos_ret_t
sos_fs_nscache_register_opened_file(struct sos_fs_nscache_node * nsnode,
				    struct sos_fs_opened_file * of);


sos_ret_t sos_fs_nscache_ref_node(struct sos_fs_nscache_node * nsnode);


sos_ret_t _sos_fs_nscache_unref_node(struct sos_fs_nscache_node ** nsnode);
#define sos_fs_nscache_unref_node(n) _sos_fs_nscache_unref_node(& (n))


/*
 * Functions reserved to sos_fs_manager_type::mount() and
 * sos_fs_manager_type::umount()
 */
#define sos_fs_nscache_create_mounted_root(fsnode,result_nsnode) \
  sos_fs_nscache_add_new_child_node(NULL, NULL, (fsnode), (result_nsnode))


/*
 * Pathname manipulation functions
 */

sos_bool_t fs_pathname_iseq(const struct sos_fs_pathname * p1,
			    const struct sos_fs_pathname * p2);

/**
 * Remove any leading slash from the path
 *
 * @Return TRUE when slashes were found at the begining
 */
sos_bool_t sos_fs_pathname_eat_slashes(const struct sos_fs_pathname * path,
				       struct sos_fs_pathname * result);

/**
 * Transform "a/b/c" into { first_component="a" remaining_path="/b/c" }
 * Transform "/a/b/c" into { first_component="a" remaining_path="/b/c" }
 * Transform "////a////b/c" into { first_component="a" remaining_path="////b/c" }
 * Transform "a" into { first_component="a" remaining_path="" }
 * Transform "/a" into { first_component="a" remaining_path="" }
 * Transform "a/" into { first_component="a" remaining_path="" }
 * Transform "/a/" into { first_component="a" remaining_path="" }
 *
 * @Return TRUE when slashes after first component were found. In the
 * previous example: true everywhere except for the path "a" and "/a"
 */
sos_bool_t
sos_fs_pathname_split_path(const struct sos_fs_pathname * path,
			   struct sos_fs_pathname * result_first_component,
			   struct sos_fs_pathname * result_remaining_path);

#endif /* _SOS_FS_NSCACHE_H_ */