* GNU Lesser General Public License.
*/
+/**
+ * SECTION: cache
+ * @title: Cache
+ * @short_description: paths and tags (UUID/LABEL) caching
+ *
+ * The cache is a very simple API for work with tags (LABEL, UUID, ...) and
+ * paths. The cache uses libblkid as a backend from TAGs resolution.
+ *
+ * All returned paths are always canonicalized.
+ */
#include <string.h>
#include <stdlib.h>
#include <ctype.h>
#include "mountP.h"
/*
- * Canonicalized (resolved) paths cache
+ * Canonicalized (resolved) paths & tags cache
*/
#define MNT_CACHE_CHUNKSZ 128
/**
* mnt_new_cache:
*
- * Returns new mnt_cache instance or NULL in case of ENOMEM error.
+ * Returns: new mnt_cache instance or NULL in case of ENOMEM error.
*/
mnt_cache *mnt_new_cache(void)
{
* mnt_free_cache:
* @cache: pointer to mnt_cache instance
*
- * Deallocates mnt_cache.
+ * Deallocates the cache.
*/
void mnt_free_cache(mnt_cache *cache)
{
/**
* mnt_cache_find_path:
* @cache: pointer to mnt_cache instance
- * @path: requested "native" (non-canonicalized) path
+ * @path: "native" (non-canonicalized) path
*
- * Returns cached canonicalized path or NULL.
+ * Returns: cached canonicalized path or NULL.
*/
const char *mnt_cache_find_path(mnt_cache *cache, const char *path)
{
* @token: tag name
* @value: tag value
*
- * Returns cached path or NULL.
+ * Returns: cached path or NULL.
*/
const char *mnt_cache_find_tag(mnt_cache *cache,
const char *token, const char *value)
*
* Reads @devname LABEL and UUID to the @cache.
*
- * Returns: 0 if at least on tag was added, 1 if no tag was added or
+ * Returns: 0 if at least one tag was added, 1 if no tag was added or
* -1 in case of error.
*/
int mnt_cache_read_tags(mnt_cache *cache, const char *devname)
* @path: "native" path
* @cache: cache for results or NULL
*
- * Returns absolute path or NULL in case of error. The result has to be
+ * Returns: absolute path or NULL in case of error. The result has to be
* deallocated by free() if @cache is NULL.
*/
char *mnt_resolve_path(const char *path, mnt_cache *cache)
* @value: tag value
* @cache: for results or NULL
*
- * Returns device name or NULL in case of error. The result has to be
+ * Returns: device name or NULL in case of error. The result has to be
* deallocated by free() if @cache is NULL.
*/
char *mnt_resolve_tag(const char *token, const char *value, mnt_cache *cache)
* @spec: path or tag
* @cache: paths cache
*
- * Returns canonicalized path or NULL. The result has to be
+ * Returns: canonicalized path or NULL. The result has to be
* deallocated by free() if @cache is NULL.
*/
char *mnt_resolve_spec(const char *spec, mnt_cache *cache)
struct mtest ts[] = {
{ "--resolve-path", test_resolve_path, " resolve paths from stdin" },
{ "--resolve-spec", test_resolve_spec, " evaluate specs from stdin" },
- { "--read-tags", test_read_tags, " read devname or TAG stdin" },
+ { "--read-tags", test_read_tags, " read devname or TAG from stdin" },
{ NULL }
};
*
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
- *
- * The mnt_fs is representation of one line in a fstab / mtab / mountinfo.
*/
+/**
+ * SECTION: fs
+ * @title: Filesystem
+ * @short_description: mnt_fs is represents one entry in fstab/mtab/mountinfo
+ *
+ */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
/**
* mnt_new_fs:
*
- * Returns newly allocated mnt_file fs.
+ * Returns: newly allocated mnt_file fs.
*/
mnt_fs *mnt_new_fs(void)
{
* mnt_fs_get_userdata:
* @fs: mnt_file instance
*
- * Returns private data set by mnt_fs_set_userdata() or NULL.
+ * Returns: private data set by mnt_fs_set_userdata() or NULL.
*/
void *mnt_fs_get_userdata(mnt_fs *fs)
{
*
* The "userdata" are library independent data.
*
- * Returns 0 or -1 in case of error (if @fs is NULL).
+ * Returns: 0 or -1 in case of error (if @fs is NULL).
*/
int mnt_fs_set_userdata(mnt_fs *fs, void *data)
{
* @fs: mnt_file (fstab/mtab/mountinfo) fs
*
* The mount "source path" is:
- * - a directory for 'bind' mounts (in fstab or mtab only)
- * - a device name for standard mounts
- * - NULL when path is not set (for example when TAG
- * (LABEL/UUID) is defined)
+ * - a directory for 'bind' mounts (in fstab or mtab only)
+ * - a device name for standard mounts
*
* See also mnt_fs_get_tag() and mnt_fs_get_source().
*
- * Returns mount "source" path or NULL in case of error or when the path
+ * Returns: mount source path or NULL in case of error or when the path
* is not defined.
- *
*/
const char *mnt_fs_get_srcpath(mnt_fs *fs)
{
/**
* @fs: mnt_file (fstab/mtab/mountinfo) fs
*
- * Returns mount "source". Note that the source could be unparsed TAG
+ * Returns: mount source. Note that the source could be unparsed TAG
* (LABEL/UUID). See also mnt_fs_get_srcpath() and mnt_fs_get_tag().
*/
const char *mnt_fs_get_source(mnt_fs *fs)
* @fs: fstab/mtab/mountinfo entry
* @source: new source
*
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @source.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_source(mnt_fs *fs, const char *source)
{
*
* "TAG" is NAME=VALUE (e.g. LABEL=foo)
*
- * The TAG is the first column in the fstab file. The TAG
- * or "srcpath" has to be always set for all entries.
+ * The TAG is the first column in the fstab file. The TAG or "srcpath" has to
+ * be always set for all entries.
*
* See also mnt_fs_get_source().
*
- * Example:
+ * <informalexample>
+ * <programlisting>
* char *src;
- * mnt_fs *fs = mnt_file_find_target(mf, "/home");
+ * mnt_fs *fs = mnt_tab_find_target(tb, "/home", MNT_ITER_FORWARD);
*
* if (!fs)
* goto err;
* printf("%s: %s\n", tag, val); // LABEL or UUID
* } else
* printf("device: %s\n", src); // device or bind path
+ * </programlisting>
+ * </informalexample>
*
- * Returns 0 on success or -1 in case that a TAG is not defined.
+ * Returns: 0 on success or -1 in case that a TAG is not defined.
*/
int mnt_fs_get_tag(mnt_fs *fs, const char **name, const char **value)
{
* mnt_fs_get_target:
* @fs: fstab/mtab/mountinfo entry pointer
*
- * Returns pointer to mountpoint path or NULL
+ * Returns: pointer to mountpoint path or NULL
*/
const char *mnt_fs_get_target(mnt_fs *fs)
{
* @fs: fstab/mtab/mountinfo entry
* @target: mountpoint
*
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @target.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_target(mnt_fs *fs, const char *target)
{
* mnt_fs_get_fstype:
* @fs: fstab/mtab/mountinfo entry pointer
*
- * Returns pointer to filesystem type.
+ * Returns: pointer to filesystem type.
*/
const char *mnt_fs_get_fstype(mnt_fs *fs)
{
* @fs: fstab/mtab/mountinfo entry
* @fstype: filesystem type
*
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @fstype.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_fstype(mnt_fs *fs, const char *fstype)
{
* mnt_fs_get_optstr:
* @fs: fstab/mtab/mountinfo entry pointer
*
- * Returns pointer to mount option string with all options (FS and VFS)
+ * Returns: pointer to mount option string with all options (FS and VFS)
*/
const char *mnt_fs_get_optstr(mnt_fs *fs)
{
* @fs: fstab/mtab/mountinfo entry
* @optstr: options string
*
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @optstr.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_optstr(mnt_fs *fs, const char *optstr)
{
+ char *p;
+
assert(fs);
if (!fs || !optstr)
return -1;
+ p = strdup(optstr);
+ if (!p)
+ return -1;
+
free(fs->optstr);
free(fs->fs_optstr);
free(fs->vfs_optstr);
fs->fs_optstr = fs->vfs_optstr = NULL;
- fs->optstr = strdup(optstr);
+ fs->optstr = p;
- return fs->optstr ? 0 : -1;
+ return 0;
}
/**
*
* This function works for "mountinfo" files only.
*
- * Returns pointer to superblock (fs-depend) mount option string or NULL.
+ * Returns: pointer to superblock (fs-depend) mount option string or NULL.
*/
const char *mnt_fs_get_fs_optstr(mnt_fs *fs)
{
*
* This function works for "mountinfo" files only.
*
- * Returns pointer to fs-independent (VFS) mount option string or NULL.
+ * Returns: pointer to fs-independent (VFS) mount option string or NULL.
*/
const char *mnt_fs_get_vfs_optstr(mnt_fs *fs)
{
* mnt_fs_get_freq:
* @fs: fstab/mtab/mountinfo entry pointer
*
- * Returns "dump frequency in days".
+ * Returns: "dump frequency in days".
*/
int mnt_fs_get_freq(mnt_fs *fs)
{
* @fs: fstab/mtab entry pointer
* @freq: dump frequency in days
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_freq(mnt_fs *fs, int freq)
{
* mnt_fs_get_passno:
* @fs: fstab/mtab entry pointer
*
- * Returns "pass number on parallel fsck".
+ * Returns: "pass number on parallel fsck".
*/
int mnt_fs_get_passno(mnt_fs *fs)
{
* @fs: fstab/mtab entry pointer
* @passno: pass number
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_set_passno(mnt_fs *fs, int passno)
{
* @value: returns pointer to the begin of the value (e.g. name=VALUE) or NULL
* @valsz: returns size of options value or 0
*
- * Returns 0 on success, 1 when not found the @name or -1 in case of error.
+ * Returns: 0 on success, 1 when not found the @name or -1 in case of error.
*/
int mnt_fs_get_option(mnt_fs *fs, const char *name,
char **value, size_t *valsz)
*
* The 2nd and 3rd attempts are not performed when @cache is NULL.
*
- * Returns 1 if @fs target is equal to @target else 0.
+ * Returns: 1 if @fs target is equal to @target else 0.
*/
int mnt_fs_match_target(mnt_fs *fs, const char *target, mnt_cache *cache)
{
* The 2nd, 3rd and 4th attempts are not performed when @cache is NULL. The
* 2nd and 3rd attempts are not performed if @fs->source is tag.
*
- * Returns 1 if @fs source is equal to @source else 0.
+ * Returns: 1 if @fs source is equal to @source else 0.
*/
int mnt_fs_match_source(mnt_fs *fs, const char *source, mnt_cache *cache)
{
*
* For more details see mnt_match_fstype().
*
- * Returns 1 if @fs type is matching to @types else 0. The function returns
+ * Returns: 1 if @fs type is matching to @types else 0. The function returns
* 0 when types is NULL.
*/
int mnt_fs_match_fstype(mnt_fs *fs, const char *types)
*
* For more details see mnt_match_options().
*
- * Returns 1 if @fs type is matching to @options else 0. The function returns
+ * Returns: 1 if @fs type is matching to @options else 0. The function returns
* 0 when types is NULL.
*/
int mnt_fs_match_options(mnt_fs *fs, const char *options)
/**
* mnt_fprintf_line:
* @f: FILE
- * @fmt: printf-like format string (see MNT_MFILE_PRINTFMT)
+ * @fmt: printf-like format string (see MNT_TAB_PRINTFMT)
* @source: (spec) device name or tag=value
* @target: mountpoint
* @fstype: filesystem type
* @freq: dump frequency in days
* @passno: pass number on parallel fsck
*
- * Returns return value from fprintf().
+ * It's recommended to use this function rather than directly call fprintf() to
+ * write an entry to mtab/fstab. All data in these files has to be properly
+ * formatted (for example space within paths/tags has to be escaped, see
+ * fstab(5) for more details).
+ *
+ * Returns: return value from fprintf().
*/
int mnt_fprintf_line( FILE *f,
const char *fmt,
* mnt_fs_fprintf:
* @fs: fstab/mtab/mountinfo entry
* @f: FILE
- * @fmt: printf-like format string (see MNT_MFILE_PRINTFMT)
+ * @fmt: printf-like format string (see MNT_TAB_PRINTFMT)
*
- * Returns return value from fprintf().
+ * Returns: return value from fprintf().
*/
int mnt_fs_fprintf(mnt_fs *fs, FILE *f, const char *fmt)
{
* @fs: fstab/mtab/mountinfo entry
* @file: output
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_fs_print_debug(mnt_fs *fs, FILE *file)
{
* GNU Lesser General Public License.
*/
+/**
+ * SECTION: init
+ * @title: Library initialization
+ * @short_description: initialize debuging
+ */
+
#include <stdlib.h>
#include "mountP.h"
int libmount_debug_mask;
+/**
+ * mnt_init_debug:
+ * @mask: debug mask (0xffff to enable full debuging)
+ *
+ * If the @mask is not specified then this function reads
+ * LIBMOUNT_DEBUG environment variable to get the mask.
+ *
+ * Already initialized debugging stuff cannot be changed. It does not
+ * have effect to call this function twice.
+ */
void mnt_init_debug(int mask)
{
if (libmount_debug_mask & DEBUG_INIT)
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
*/
+
+/**
+ * SECTION: iter
+ * @title: Iterator
+ * @short_description: unified iterator
+ *
+ * The iterator keeps direction and last position for access to the internal
+ * library tables/lists.
+ */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
* mnt_new_iter:
* @direction: MNT_INTER_{FOR,BACK}WARD direction
*
- * Returns newly allocated generic libmount iterator.
+ * Returns: newly allocated generic libmount iterator.
*/
mnt_iter *mnt_new_iter(int direction)
{
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
*/
+
+/**
+ * SECTION: lock
+ * @title: Mtab locking
+ * @short_description: locking methods for work with /etc/mtab
+ *
+ * The lock is backwardly compatible with the standard linux /etc/mtab locking.
+ * Note, it's necessary to use the same locking schema in all application that
+ * access the file.
+ */
#include <string.h>
#include <stdlib.h>
#include <sys/types.h>
* @lockfile: path to lockfile or NULL (default is _PATH_MOUNTED_LOCK)
* @id: unique linkfile identifier or 0 (default is getpid())
*
- * Returns newly allocated lock handler or NULL on case of error.
+ * Returns: newly allocated lock handler or NULL on case of error.
*/
mnt_lock *mnt_new_lock(const char *lockfile, pid_t id)
{
* mnt_lock_get_lockfile:
* @ml: mnt_lock handler
*
- * Returns path to lockfile.
+ * Returns: path to lockfile.
*/
const char *mnt_lock_get_lockfile(mnt_lock *ml)
{
* mnt_lock_get_linkfile:
* @ml: mnt_lock handler
*
- * Returns unique (per process) path to linkfile.
+ * Returns: unique (per process) path to linkfile.
*/
const char *mnt_lock_get_linkfile(mnt_lock *ml)
{
* Waits for F_SETLKW, unfortunately we have to use SIGALRM here to interrupt
* fcntl() to avoid never ending waiting.
*
- * Returns 0 on success, 1 on timeout, -errno on error.
+ * Returns: 0 on success, 1 on timeout, -errno on error.
*/
static int mnt_wait_lock(mnt_lock *ml, struct flock *fl, time_t maxtime)
{
* There was very small number of attempts and extremely long waiting (1s)
* that is useless on machines with large number of mount processes.
*
- * Now we wait few thousand microseconds between attempts and we have global
+ * Now we wait few thousand microseconds between attempts and we have a global
* time limit (30s) rather than limit for number of attempts. The advantage
* is that this method also counts time which we spend in fcntl(F_SETLKW) and
* number of attempts is not restricted.
* 1. create linkfile (e.g. /etc/mtab~.<pid>)
* 2. link linkfile --> lockfile (e.g. /etc/mtab~.<pid> --> /etc/mtab~)
*
- * 3. a) link() successful: setups F_SETLK lock (see fcnlt(2))
- * b) link() failed: wait (max 30s) on F_SETLKW lock, goto 2.
+ * 3. a) link() success: setups F_SETLK lock (see fcnlt(2))
+ * b) link() failed: wait (max 30s) on F_SETLKW lock, goto 2.
*
* Example:
*
+ * <informalexample>
+ * <programlisting>
* mnt_lock *ml;
*
* void unlock_fallback(void)
* ml = NULL;
* return 0;
* }
+ * </programlisting>
+ * </informalexample>
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_lock_file(mnt_lock *ml)
{
return 0;
}
+/*
+ * Note that this test should be executed from a script that creates many
+ * parallel processes, otherwise this test does not make sense.
+ */
int main(int argc, char *argv[])
{
struct mtest tss[] = {
extern int mnt_fs_match_options(mnt_fs *fs, const char *options);
/* mtab/fstab line */
-#define MNT_MFILE_PRINTFMT "%s %s %s %s %d %d\n"
+#define MNT_TAB_PRINTFMT "%s %s %s %s %d %d\n"
extern int mnt_fprintf_line(
FILE *f,
* GNU Lesser General Public License.
*/
+/**
+ * SECTION: optent
+ * @title: Mount option entry
+ * @short_description: the entry keeps one parsed mount option
+ */
#include <string.h>
#include <stdlib.h>
#include <ctype.h>
* Parses the first mount option from @optstr and move @optstr pointer
* to the next option.
*
- * Returns: new optent (parsed option) or NULL in case of error.
+ * Returns new optent (parsed option) or NULL in case of error.
*/
mnt_optent *mnt_new_optent_from_optstr(char **optstr,
struct mnt_optmap const **maps, int nmaps)
* mnt_optent_get_map:
* @op: pointer to mnt_optent instance
*
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or NULL is returned.
- *
- * Returns pointer to the head of the map that is associated with the option or
+ * Returns: pointer to the head of the map that is associated with the option or
* NULL (for "extra options").
*/
const struct mnt_optmap *mnt_optent_get_map(mnt_optent *op)
* mnt_optent_get_map_entry:
* @op: pointer to mnt_optent instance
*
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or NULL is returned.
-
- * Returns pointer to the map entry that describes the option or NULL (for
+ * Returns: pointer to the map entry that describes the option or NULL (for
* "extra options").
*/
const struct mnt_optmap *mnt_optent_get_mapent(mnt_optent *op)
* mnt_optent_get_type:
* @op: mnt_optent instance
*
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or the default "%s]" is returned.
+ * Note that the @op has to be associated with any option map
+ * or the default "%s]" is returned.
*
- * Returns pointer to the begin of type format string or NULL. For example:
+ * Returns: pointer to the begin of type format string or NULL. For example:
*
* "%s" --> string, required argument (definition in the map is: "foo=%s")
* "%s]" --> string, optional argument (definition in the map is: "foo[=%s]")
*
* The function unset (zeroize) the option value if the @data pointer is NULL.
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_optent_set_value(mnt_optent *op, const char *data)
{
* mnt_optent_has_value:
* @option: pointer to mnt_optent instance
*
- * Returns 1 if the option has actually set an argument value, or 0.
+ * Returns: 1 if the option has actually set an argument value, or 0.
*/
int mnt_optent_has_value(mnt_optent *op)
{
* mnt_optent_require_value:
* @op: pointer to mnt_optent instance
*
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or 0 is returned.
+ * Note that the @op has to be associated with any option map
+ * or 0 is returned.
*
- * Returns 1 if the option requires an argument (option=<arg>).
+ * Returns
: 1 if the option requires an argument (option=<arg>).
*/
int mnt_optent_require_value(mnt_optent *op)
{
* mnt_optent_is_inverted:
* @op: pointer to mnt_optent instance
*
- * Returns 1 if the option has MNT_INVERT mask or 0.
+ * Returns: 1 if the option has MNT_INVERT mask or 0.
*/
int mnt_optent_is_inverted(mnt_optent *op)
{
* (e.g "123ABC" returns -1).
*
* This function also converts {enum0,enumN} type to number 0..N. For more
- * details see info about options maps.
+ * details see info about option maps.
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_optent_strtoul_value(mnt_optent *op, unsigned long int *number)
{
* The whole option value has to be possible to convert to the number
* (e.g "123ABC" returns -1).
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_optent_strtol_value(mnt_optent *op, long int *number)
{
* The whole option value has to be possible to convert to the number
* (e.g "123ABC" returns -1).
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_optent_strtoull_value(mnt_optent *op, unsigned long long int *number)
{
*
* See also mnt_optent_has_value().
*
- * Returns pointer to value or NULL.
+ * Returns: pointer to value or NULL.
*/
const char *mnt_optent_get_value(mnt_optent *op)
{
* mnt_optent_strlen_value:
* @op: pointer to mnt_optent instance
*
- * Returns length of string that is necessary to print option value or -1 in
+ * Returns: length of string that is necessary to print option value or -1 in
* case of error.
*/
int mnt_optent_strlen_value(mnt_optent *op)
* @str: resulting string
* @size: size of string
*
- * Returns number of printed characters or negative number in case of error.
+ * Returns: number of printed characters or negative number in case of error.
*/
int mnt_optent_snprintf_value(mnt_optent *op, char *str, size_t size)
{
* mnt_optent_dup_value:
* @op: pointer to mnt_optent instance
*
- * Returns duplicate a option value.
+ * Returns: duplicate a option value.
*/
char *mnt_optent_dup_value(mnt_optent *op)
{
* mnt_optent_get_name:
* @op: pointer to mnt_optent instance
*
- * Returns option name or NULL in case of error.
+ * Returns: option name or NULL in case of error.
*/
const char *mnt_optent_get_name(mnt_optent *op)
{
* The initial value of the option mask is a copy from map->mask.
* Note that the mask is NOT a mountflag/ID.
*
- * Returns option mask or 0.
+ * Returns: option mask or 0.
*/
int mnt_optent_get_mask(mnt_optent *op)
{
* "nooption" (e.g. noexec) -- you have to carefully check for MNT_INVERT in
* the option mask. See mnt_optent_get_flag().
*
- * Returns option ID/mountflag or 0 for extra options (options with undefined
+ * Returns: option ID/mountflag or 0 for extra options (options with undefined
* options map).
*/
int mnt_optent_get_id(mnt_optent *op)
* @op: pointer to mnt_optent instance
* @flags: resulting flags
*
- * Adds option ID to @flags or removes option ID from @flags when the option
- * is inverted option (e.g. "norelatime")
+ * Adds option ID to @flags or removes the ID from @flags when the option
+ * is an inverted option (e.g. "norelatime")
*
- * Example:
+ * <informalexample>
+ * <programlisting>
* int flags = 0;
*
- * while(mnt_iterate_options(&itr, opts, map, &op) == 0)
+ * while(mnt_optls_next_option(&itr, opts, map, &op) == 0)
* mnt_optent_get_flag(op, &flags);
*
* if (flags & MS_RELATIME)
* printf("relatime is set\n");
+ * </programlisting>
+ * </informalexample>
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_optent_get_flag(mnt_optent *op, int *flags)
{
* mnt_optent_is_unknown:
* @op: pointer to mnt_optent instance
*
- * The "extra option" is unknown option (undefined in any option map)
+ * The "extra options" are unknown options (undefined in any option map)
*
- * Return 1 or 0.
+ * Returns: 1 or 0.
*/
int mnt_optent_is_unknown(mnt_optent *op)
{
*
* Prints details about the option.
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_optent_print_debug(mnt_optent *op, FILE *file)
{
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
*/
+
+/**
+ * SECTION: optls
+ * @title: Options container
+ * @short_description: high-level API for work with parsed mount options
+ *
+ * The optls container allows to work with parsed mount options and generate
+ * arguments for mount(2) syscall, output to mtab or analyze userspace specific
+ * options.
+ */
#include <string.h>
#include <stdlib.h>
#include <ctype.h>
* @map: pointer to the custom map
*
* Stores pointer to the custom options map (options description). The map has
- * to be accessible all time when the libmount works with options.
+ * to be accessible all time when the libmount works with options. (The map is
+ * usually a static array.)
*
* All already stored unknown mount options are reverified against the new map.
* Note, it's recommented to add all maps to the @optls container before options
*
* Example (add new options "foo" and "bar=<data>"):
*
+ * <informalexample>
+ * <programlisting>
* #define MY_MS_FOO (1 << 1)
* #define MY_MS_BAR (1 << 2)
*
* };
*
* mnt_optls_add_map(ls, myoptions);
+ * </programlisting>
+ * </informalexample>
*
* Returns: 0 on success, 1 on failed verification, or -1 in case of error.
*/
* @ls: pointer to mnt_optls instance
* @map_id: built-in map id (see mnt_get_builtin_map())
*
- * Returns 0 on success or -1 in case of error.
+ * Same as mnt_optls_add_map(), but works with libmount built in maps.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_optls_add_builtin_map(mnt_optls *ls, int id)
{
* @ls: pointer to mnt_optls instance.
* @optstr: zero terminated string with mount options (comma separaed list)
*
- * Parses @optstr and all options from @optstr are added to @optls. It's
+ * Parses @optstr and all options from @optstr are added to the @optls. It's
* possible to call this function more than once. The new options from @optstr
* will be appended to the container.
-*
+ *
* The options are accessible by mnt_optls_next_option().
*
* If the @optls container is associated with any options map(s), all new
* mnt_optls_add_option(ls, "user", "snake");
* mnt_optls_add_option(ls, "noexec", NULL);
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_optls_parse_optstr(mnt_optls *ls, const char *optstr)
{
* @ls: pointer to mnt_optls instance
* @name: option name
*
- * Returns 0 on success, 1 if @name not found and -1 in case of error.
+ * Returns: 0 on success, 1 if @name not found and -1 in case of error.
*/
int mnt_optls_remove_option(mnt_optls *ls, const char *name)
{
*
* See also mnt_optent_get_flag() and mnt_optls_remove_option_by_iflags().
*
- * Returns number of removed options or -1 in case of error.
+ * Returns: number of removed options or -1 in case of error.
*/
int mnt_optls_remove_option_by_flags(mnt_optls *ls,
const struct mnt_optmap *map, const int flags)
*
* See also mnt_optent_get_flag() and mnt_optls_remove_option_by_flags().
*
- * Returns number of removed options or -1 in case of error.
+ * Returns: number of removed options or -1 in case of error.
*/
int mnt_optls_remove_option_by_iflags(mnt_optls *ls,
const struct mnt_optmap *map, const int flags)
* @option: returns pointer to the option object
*
* Example (print all options):
- *
+ * <informalexample>
+ * <programlisting>*
* mnt_optent *option;
* mnt_optls *ls = mnt_optls_new();
*
*
* while(mnt_optls_next_option(ls, itr, NULL, &option))
* printf("%s\n", mnt_optent_get_name(option)));
+ * </programlisting>
+ * </informalexample>
*
- * Returns 0 on succes, -1 in case of error or 1 at end of list.
+ * Returns: 0 on succes, -1 in case of error or 1 at end of list.
*/
int mnt_optls_next_option(mnt_optls *ls, mnt_iter *itr,
const struct mnt_optmap *map, mnt_optent **option)
* @ls: pointer to mnt_optls instance
* @name: options name
*
- * Returns the option or NULL.
+ * Returns: the option or NULL.
*/
mnt_optent *mnt_optls_get_option(mnt_optls *ls, const char *name)
{
* mnt_optls_create_mountflags() that returns MNT_MFLAG options
* (mount(2) flags) only.
*
- * Return IDs from all options.
+ * Return: IDs from all options.
*/
int mnt_optls_get_ids(mnt_optls *ls, const struct mnt_optmap *map)
{
* The mountflags are IDs from all MNT_MFLAG options. See "struct mnt_optmap".
* For more details about mountflags see mount(2) syscall.
*
- * Returns mount flags or 0.
+ * Returns: mount flags or 0.
*/
int mnt_optls_create_mountflags(mnt_optls *ls)
{
*
* For more details about mountdata see mount(2) syscall.
*
- * Returns newly allocated string with mount options or NULL in case of error.
+ * Returns: newly allocated string with mount options or NULL in case of error.
*/
char *mnt_optls_create_mountdata(mnt_optls *ls)
{
* mnt_optls_create_mtab_optstr:
* @ls: pointer to mnt_optls instance
*
- * Returns newly allocated string with mount options for mtab.
+ * Returns: newly allocated string with mount options for mtab.
*/
char *mnt_optls_create_mtab_optstr(mnt_optls *ls)
{
* mnt_optls_create_userspace_optstr:
* @ls: pointer to mnt_optls instance
*
- * Returns newly allocated string with mount options that are
- * userspace specific (e.g. uhelper=).
+ * Returns: newly allocated string with mount options that are
+ * userspace specific (e.g. uhelper=,loop=).
*/
char *mnt_optls_create_userspace_optstr(mnt_optls *ls)
{
* @ls: pointer to mnt_optls instance
*
* Prints details about options container.
+ *
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_optls_print_debug(mnt_optls *ls, FILE *file)
{
*
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
+ */
+
+/**
+ * SECTION: optmap
+ * @title: Option maps
+ * @short_description: description for mount options
*
- * Option-maps
- * -----------
* The mount(2) linux syscall uses two arguments for mount options:
*
* 1) mountflags (see MS_* macros in linux/fs.h)
* - MNT_LINUX_MAP -- fs-independent kernel mount options (usually MS_* flags)
* - MNT_USERSPACE_MAP -- userspace specific mount options (e.g. "user", "loop")
*
+ * For more details about option map struct see "struct mnt_optmap" in
+ * mount/mount.h.
*/
#include <string.h>
#include <stdlib.h>
* MNT_USERSPACE_MAP - userpace mount(8) specific mount options
* (e.g user=, _netdev, ...)
*
- * Returns internal (static) libmount map.
+ * Returns: static built-in libmount map.
*/
const struct mnt_optmap *mnt_get_builtin_optmap(int id)
{
* GNU Lesser General Public License.
*/
+/**
+ * SECTION: optstr
+ * @title: Mount oprions string
+ * @short_description: low-level API for work with mount options
+ *
+ * This is simple and low-level API to work with mount options that are stored
+ * in string. This API is independent on the high-level options container and
+ * option maps.
+ */
+
#include <string.h>
#include <stdlib.h>
#include <ctype.h>
*
* Parses the first option in @optstr or -1 in case of error.
*
- * Returns 0 on success, 1 at the end of @optstr or -1 in case of error.
+ * Returns: 0 on success, 1 at the end of @optstr or -1 in case of error.
*/
int mnt_optstr_next_option(char **optstr, char **name, size_t *namesz,
char **value, size_t *valuesz)
/*
- * Copyright (C) 2008 Karel Zak <kzak@redhat.com>
+ * Copyright (C) 2008-2010 Karel Zak <kzak@redhat.com>
*
* This file may be redistributed under the terms of the
* GNU Lesser General Public License.
+ */
+
+/**
+ * SECTION: tab
+ * @title: Filesystems container
+ * @short_description: container for entries from fstab/mtab/mountinfo
+ *
*
- * Note:
- * mnt_tab_find_* functions are mount(8) compatible. It means it tries
- * to found an entry in more iterations where the first attempt is always
- * based on comparison with unmodified (non-canonicalized or un-evaluated)
- * paths or tags. For example fstab with two entries:
+ * Note that mnt_tab_find_* functions are mount(8) compatible. These functions
+ * try to found an entry in more iterations where the first attempt is always
+ * based on comparison with unmodified (non-canonicalized or un-evaluated)
+ * paths or tags. For example fstab with two entries:
*
- * LABEL=foo /foo auto rw
- * /dev/foo /foo auto rw
+ * LABEL=foo /foo auto rw
+ * /dev/foo /foo auto rw
*
- * where both lines are used for the *same* device, then
+ * where both lines are used for the *same* device, then
*
- * mnt_tab_find_source(tb, "/dev/foo", &fs);
+ * mnt_tab_find_source(tb, "/dev/foo", &fs);
*
- * will returns the second line, and
+ * will returns the second line, and
*
- * mnt_tab_find_source(tb, "LABEL=foo", &fs);
+ * mnt_tab_find_source(tb, "LABEL=foo", &fs);
*
- * will returns the first entry, and
+ * will returns the first entry, and
*
* mnt_tab_find_source(tb, "UUID=<anyuuid>", &fs);
*
- * will returns the first entry (if UUID matches with the device).
+ * will returns the first entry (if UUID matches with the device).
*/
#include <string.h>
* Note that this function does not parse the file. See also
* mnt_tab_parse_file().
*
- * Returns newly allocated tab struct.
+ * Returns: newly allocated tab struct.
*/
mnt_tab *mnt_new_tab(const char *filename)
{
* mnt_tab_get_nents:
* @tb: pointer to tab
*
- * Returns number of valid entries in tab.
+ * Returns: number of valid entries in tab.
*/
int mnt_tab_get_nents(mnt_tab *tb)
{
*
* See also mnt_new_cache().
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_tab_set_cache(mnt_tab *tb, mnt_cache *mpc)
{
* mnt_tab_get_cache:
* @tb: pointer to tab
*
- * Returns pointer to mnt_cache instance or NULL.
+ * Returns: pointer to mnt_cache instance or NULL.
*/
mnt_cache *mnt_tab_get_cache(mnt_tab *tb)
{
* mnt_tab_get_name:
* @tb: tab pointer
*
- * Returns tab filename or NULL.
+ * Returns: tab filename or NULL.
*/
const char *mnt_tab_get_name(mnt_tab *tb)
{
*
* Adds a new entry to tab.
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_tab_add_fs(mnt_tab *tb, mnt_fs *fs)
{
* @tb: tab pointer
* @fs: new entry
*
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
*/
int mnt_tab_remove_fs(mnt_tab *tb, mnt_fs *fs)
{
* Note that filesystems are returned in the order how was mounted (according to
* IDs in /proc/self/mountinfo).
*
- * Returns 0 on success, -1 in case of error or 1 at end of list.
+ * Returns: 0 on success, -1 in case of error or 1 at end of list.
*/
int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr,
mnt_fs *parent, mnt_fs **chld)
* @itr: iterator
* @fs: returns the next tab entry
*
- * Returns 0 on success, -1 in case of error or 1 at end of list.
+ * Returns: 0 on success, -1 in case of error or 1 at end of list.
*
* Example (list all mountpoints from fstab in backward order):
*
*
* This function allows search in @tb.
*
- * Returns -1 in case of error, 1 at end of table or 0 o success.
+ * Returns: -1 in case of error, 1 at end of table or 0 o success.
*/
int mnt_tab_find_next_fs(mnt_tab *tb, mnt_iter *itr,
int (*match_func)(mnt_fs *, void *), void *userdata,
*
* Sets @iter to the position of @fs in the file @tb.
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_tab_set_iter(mnt_tab *tb, mnt_iter *itr, mnt_fs *fs)
{
* against realpath(fs->target). The 2nd and 3rd iterations are not performed
* when @tb cache is not set (see mnt_tab_set_cache()).
*
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
*/
mnt_fs *mnt_tab_find_target(mnt_tab *tb, const char *path, int direction)
{
* The 2nd, 3rd and 4th iterations are not performed when @tb cache is not
* set (see mnt_tab_set_cache()).
*
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
*/
mnt_fs *mnt_tab_find_srcpath(mnt_tab *tb, const char *path, int direction)
{
* name) and mnt_tab_find_srcpath() is preformed. The second attempt is not
* performed when @tb cache is not set (see mnt_tab_set_cache()).
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
*/
mnt_fs *mnt_tab_find_tag(mnt_tab *tb, const char *tag,
const char *val, int direction)
* about @source format (device, LABEL, UUID, ...). This function parses @source
* and calls mnt_tab_find_tag() or mnt_tab_find_srcpath().
*
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
*/
mnt_fs *mnt_tab_find_source(mnt_tab *tb, const char *source, int direction)
{
* @fmt: per line printf-like format string (see MNT_MFILE_PRINTFMT)
* @tb: tab pointer
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_tab_fprintf(mnt_tab *tb, FILE *f, const char *fmt)
{
*
* Writes tab to disk. Don't forget to lock the file (see mnt_lock()).
*
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
*/
int mnt_tab_update_file(mnt_tab *tb)
{
*
* Parses whole table (e.g. /etc/fstab).
*
- * Returns 0 on success and -1 in case of error. The parse errors is possible
- * to detect by mnt_tab_get_nerrs() and error message is possible to create by
- * mnt_tab_strerror().
- *
- * Example:
- *
+ * <informalexample>
+ * <programlisting>
* mnt_tab *tb = mnt_new_tab("/etc/fstab");
* int rc;
*
* mnt_fprintf_tab(tb, stdout, NULL);
*
* mnt_free_tab(tb);
+ * </programlisting>
+ * </informalexample>
+ *
+ * Returns: 0 on success and -1 in case of error. The parse errors is possible
+ * to detect by mnt_tab_get_nerrs() and error message is possible to create by
+ * mnt_tab_strerror().
*/
int mnt_tab_parse_file(mnt_tab *tb)
{
* not provide details (by mnt_tab_strerror()) about failed parsing -- so you
* should not to use this function for user-writeable files like /etc/fstab.
*
- * Returns newly allocated tab on success and NULL in case of error.
+ * Returns: newly allocated tab on success and NULL in case of error.
*/
mnt_tab *mnt_new_tab_from_file(const char *filename)
{
* mnt_tab_get_nerrs:
* @tb: pointer to table
*
- * Returns number of broken (parse error) entries in the table.
+ * Returns: number of broken (parse error) entries in the table.
*/
int mnt_tab_get_nerrs(mnt_tab *tb)
{
* @buf: buffer to return error message
* @buflen: lenght of the buf
*
- * Returns error message for table (file) parse errors. For example:
+ * Returns: error message for table (file) parse errors. For example:
*
* "/etc/fstab: parse error at line(s): 1, 2 and 3."
*/
* GNU Lesser General Public License.
*/
+/**
+ * SECTION: utils
+ * @title: Utils
+ * @short_description: misc utils.
+ */
#include <unistd.h>
#include <errno.h>
#include <stdlib.h>
* See COPYING.libmount for the License of this software.
*/
+/**
+ * SECTION: version
+ * @title: Version functions
+ * @short_description: functions to get library version.
+ */
+
#include <unistd.h>
#include <string.h>
#include <stdio.h>
projects / util-linux / commitdiff