From: Karel Zak Date: Wed, 14 Apr 2010 12:01:24 +0000 (+0200) Subject: libmount: cleanup docs X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=192c6aad9c8e6ae5c4a480f41b9359180a468150;p=util-linux libmount: cleanup docs Signed-off-by: Karel Zak --- diff --git a/shlibs/mount/src/cache.c b/shlibs/mount/src/cache.c index 524979b6..bd6ea3a0 100644 --- a/shlibs/mount/src/cache.c +++ b/shlibs/mount/src/cache.c @@ -5,6 +5,16 @@ * 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 #include #include @@ -20,7 +30,7 @@ #include "mountP.h" /* - * Canonicalized (resolved) paths cache + * Canonicalized (resolved) paths & tags cache */ #define MNT_CACHE_CHUNKSZ 128 @@ -55,7 +65,7 @@ struct _mnt_cache { /** * 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) { @@ -66,7 +76,7 @@ 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) { @@ -158,9 +168,9 @@ error: /** * 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) { @@ -188,7 +198,7 @@ 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) @@ -223,7 +233,7 @@ const char *mnt_cache_find_tag(mnt_cache *cache, * * 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) @@ -355,7 +365,7 @@ char *mnt_cache_find_tag_value(mnt_cache *cache, * @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) @@ -401,7 +411,7 @@ error: * @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) @@ -439,7 +449,7 @@ error: * @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) @@ -558,7 +568,7 @@ int main(int argc, char *argv[]) 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 } }; diff --git a/shlibs/mount/src/fs.c b/shlibs/mount/src/fs.c index d0fadc98..885a4a2b 100644 --- a/shlibs/mount/src/fs.c +++ b/shlibs/mount/src/fs.c @@ -3,10 +3,14 @@ * * 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 #include #include @@ -20,7 +24,7 @@ /** * mnt_new_fs: * - * Returns newly allocated mnt_file fs. + * Returns: newly allocated mnt_file fs. */ mnt_fs *mnt_new_fs(void) { @@ -61,7 +65,7 @@ void mnt_free_fs(mnt_fs *fs) * 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) { @@ -74,7 +78,7 @@ 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) { @@ -89,16 +93,13 @@ 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) { @@ -115,7 +116,7 @@ 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) @@ -150,7 +151,9 @@ int __mnt_fs_set_source(mnt_fs *fs, char *source) * @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) { @@ -179,14 +182,15 @@ 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: + * + * * 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; @@ -198,8 +202,10 @@ int mnt_fs_set_source(mnt_fs *fs, const char *source) * printf("%s: %s\n", tag, val); // LABEL or UUID * } else * printf("device: %s\n", src); // device or bind path + * + * * - * 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) { @@ -216,7 +222,7 @@ 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) { @@ -229,7 +235,9 @@ 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) { @@ -253,7 +261,7 @@ 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) { @@ -287,7 +295,9 @@ int __mnt_fs_set_fstype(mnt_fs *fs, char *fstype) * @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) { @@ -308,7 +318,7 @@ 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) { @@ -321,22 +331,30 @@ 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; } /** @@ -345,7 +363,7 @@ int mnt_fs_set_optstr(mnt_fs *fs, const char *optstr) * * 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) { @@ -359,7 +377,7 @@ 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) { @@ -372,7 +390,7 @@ 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) { @@ -385,7 +403,7 @@ 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) { @@ -400,7 +418,7 @@ 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) { @@ -413,7 +431,7 @@ 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) { @@ -469,7 +487,7 @@ dev_t mnt_fs_get_devno(mnt_fs *fs) * @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) @@ -491,7 +509,7 @@ int mnt_fs_get_option(mnt_fs *fs, const char *name, * * 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) { @@ -533,7 +551,7 @@ 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) { @@ -601,7 +619,7 @@ 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) @@ -616,7 +634,7 @@ 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) @@ -662,7 +680,7 @@ static char *mangle(const char *s) /** * 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 @@ -670,7 +688,12 @@ static char *mangle(const char *s) * @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, @@ -709,9 +732,9 @@ done: * 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) { @@ -736,7 +759,7 @@ 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) { diff --git a/shlibs/mount/src/init.c b/shlibs/mount/src/init.c index 544361bc..68c13f94 100644 --- a/shlibs/mount/src/init.c +++ b/shlibs/mount/src/init.c @@ -5,12 +5,28 @@ * GNU Lesser General Public License. */ +/** + * SECTION: init + * @title: Library initialization + * @short_description: initialize debuging + */ + #include #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) diff --git a/shlibs/mount/src/iter.c b/shlibs/mount/src/iter.c index 4baa7ffb..5c02c2a7 100644 --- a/shlibs/mount/src/iter.c +++ b/shlibs/mount/src/iter.c @@ -4,6 +4,15 @@ * 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 #include #include @@ -14,7 +23,7 @@ * 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) { diff --git a/shlibs/mount/src/lock.c b/shlibs/mount/src/lock.c index 2d2b3c07..e0b0d0b8 100644 --- a/shlibs/mount/src/lock.c +++ b/shlibs/mount/src/lock.c @@ -4,6 +4,16 @@ * 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 #include #include @@ -39,7 +49,7 @@ struct _mnt_lock { * @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) { @@ -79,7 +89,7 @@ void mnt_free_lock(mnt_lock *ml) * 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) { @@ -94,7 +104,7 @@ 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) { @@ -126,7 +136,7 @@ static void mnt_lockalrm_handler(int sig) * 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) { @@ -189,7 +199,7 @@ 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. @@ -256,11 +266,13 @@ void mnt_unlock_file(mnt_lock *ml) * 1. create linkfile (e.g. /etc/mtab~.) * 2. link linkfile --> lockfile (e.g. /etc/mtab~. --> /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: * + * + * * mnt_lock *ml; * * void unlock_fallback(void) @@ -292,8 +304,10 @@ void mnt_unlock_file(mnt_lock *ml) * ml = NULL; * return 0; * } + * + * * - * 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) { @@ -497,6 +511,10 @@ int test_lock(struct mtest *ts, int argc, char *argv[]) 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[] = { diff --git a/shlibs/mount/src/mount.h.in b/shlibs/mount/src/mount.h.in index eeddc812..c3100ee0 100644 --- a/shlibs/mount/src/mount.h.in +++ b/shlibs/mount/src/mount.h.in @@ -248,7 +248,7 @@ extern int mnt_fs_match_fstype(mnt_fs *fs, const char *types); 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, diff --git a/shlibs/mount/src/optent.c b/shlibs/mount/src/optent.c index 4bb7db10..749f447c 100644 --- a/shlibs/mount/src/optent.c +++ b/shlibs/mount/src/optent.c @@ -5,6 +5,11 @@ * GNU Lesser General Public License. */ +/** + * SECTION: optent + * @title: Mount option entry + * @short_description: the entry keeps one parsed mount option + */ #include #include #include @@ -174,7 +179,7 @@ err: * 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) @@ -245,10 +250,7 @@ err: * 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) @@ -261,10 +263,7 @@ 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) @@ -277,10 +276,10 @@ 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]") @@ -302,7 +301,7 @@ const char *mnt_optent_get_type(mnt_optent *op) * * 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) { @@ -344,7 +343,7 @@ err: * 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) { @@ -355,10 +354,10 @@ 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=). + * Returns: 1 if the option requires an argument (option=). */ int mnt_optent_require_value(mnt_optent *op) { @@ -369,7 +368,7 @@ 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) { @@ -400,9 +399,9 @@ static int get_number_base(const char *type) * (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) { @@ -456,7 +455,7 @@ err: * 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) { @@ -500,7 +499,7 @@ err: * 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) { @@ -539,7 +538,7 @@ err: * * 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) { @@ -550,7 +549,7 @@ 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) @@ -570,7 +569,7 @@ 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) { @@ -590,7 +589,7 @@ 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) { @@ -605,7 +604,7 @@ 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) { @@ -620,7 +619,7 @@ 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) { @@ -638,7 +637,7 @@ 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) @@ -652,19 +651,22 @@ 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: + * + * * 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"); + * + * * - * 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) { @@ -686,9 +688,9 @@ 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) { @@ -703,7 +705,7 @@ 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) { diff --git a/shlibs/mount/src/optls.c b/shlibs/mount/src/optls.c index f819d12b..f8b73470 100644 --- a/shlibs/mount/src/optls.c +++ b/shlibs/mount/src/optls.c @@ -4,6 +4,16 @@ * 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 #include #include @@ -52,7 +62,8 @@ void mnt_free_optls(mnt_optls *ls) * @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 @@ -60,6 +71,8 @@ void mnt_free_optls(mnt_optls *ls) * * Example (add new options "foo" and "bar="): * + * + * * #define MY_MS_FOO (1 << 1) * #define MY_MS_BAR (1 << 2) * @@ -71,6 +84,8 @@ void mnt_free_optls(mnt_optls *ls) * }; * * mnt_optls_add_map(ls, myoptions); + * + * * * Returns: 0 on success, 1 on failed verification, or -1 in case of error. */ @@ -108,7 +123,9 @@ int mnt_optls_add_map(mnt_optls *ls, const struct mnt_optmap *map) * @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) { @@ -165,10 +182,10 @@ mnt_optent *mnt_optls_add_option(mnt_optls *ls, * @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 @@ -183,7 +200,7 @@ mnt_optent *mnt_optls_add_option(mnt_optls *ls, * 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) { @@ -210,7 +227,7 @@ 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) { @@ -254,7 +271,7 @@ 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) @@ -302,7 +319,7 @@ int mnt_optls_remove_option_by_flags(mnt_optls *ls, * * 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) @@ -346,7 +363,8 @@ int mnt_optls_remove_option_by_iflags(mnt_optls *ls, * @option: returns pointer to the option object * * Example (print all options): - * + * + * * * mnt_optent *option; * mnt_optls *ls = mnt_optls_new(); * @@ -354,8 +372,10 @@ int mnt_optls_remove_option_by_iflags(mnt_optls *ls, * * while(mnt_optls_next_option(ls, itr, NULL, &option)) * printf("%s\n", mnt_optent_get_name(option))); + * + * * - * 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) @@ -382,7 +402,7 @@ int mnt_optls_next_option(mnt_optls *ls, mnt_iter *itr, * @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) { @@ -416,7 +436,7 @@ 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) { @@ -444,7 +464,7 @@ 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) { @@ -474,7 +494,7 @@ 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) { @@ -510,7 +530,7 @@ err: * 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) { @@ -547,8 +567,8 @@ err: * 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) { @@ -589,6 +609,8 @@ err: * @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) { diff --git a/shlibs/mount/src/optmap.c b/shlibs/mount/src/optmap.c index 873c545c..ff8cc8c6 100644 --- a/shlibs/mount/src/optmap.c +++ b/shlibs/mount/src/optmap.c @@ -3,9 +3,13 @@ * * 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) @@ -45,6 +49,8 @@ * - 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 #include @@ -153,7 +159,7 @@ static const struct mnt_optmap userspace_opts_map[] = * 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) { diff --git a/shlibs/mount/src/optstr.c b/shlibs/mount/src/optstr.c index 3e4eb482..ed40cace 100644 --- a/shlibs/mount/src/optstr.c +++ b/shlibs/mount/src/optstr.c @@ -5,6 +5,16 @@ * 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 #include #include @@ -129,7 +139,7 @@ static int mnt_optstr_locate_option(char *optstr, const char *name, char **begin * * 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) diff --git a/shlibs/mount/src/tab.c b/shlibs/mount/src/tab.c index 819b11d3..71aa805b 100644 --- a/shlibs/mount/src/tab.c +++ b/shlibs/mount/src/tab.c @@ -1,31 +1,37 @@ /* - * Copyright (C) 2008 Karel Zak + * Copyright (C) 2008-2010 Karel Zak * * 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=", &fs); * - * will returns the first entry (if UUID matches with the device). + * will returns the first entry (if UUID matches with the device). */ #include @@ -51,7 +57,7 @@ * 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) { @@ -97,7 +103,7 @@ void mnt_free_tab(mnt_tab *tb) * 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) { @@ -119,7 +125,7 @@ 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) { @@ -134,7 +140,7 @@ 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) { @@ -146,7 +152,7 @@ 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) { @@ -161,7 +167,7 @@ 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) { @@ -190,7 +196,7 @@ 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) { @@ -255,7 +261,7 @@ int mnt_tab_get_root_fs(mnt_tab *tb, mnt_fs **root) * 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) @@ -313,7 +319,7 @@ int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr, * @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): * @@ -364,7 +370,7 @@ again: * * 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, @@ -403,7 +409,7 @@ int mnt_tab_find_next_fs(mnt_tab *tb, mnt_iter *itr, * * 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) { @@ -431,7 +437,7 @@ 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) { @@ -487,7 +493,7 @@ 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) { @@ -587,7 +593,7 @@ 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) @@ -632,7 +638,7 @@ mnt_fs *mnt_tab_find_tag(mnt_tab *tb, const char *tag, * 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) { @@ -670,7 +676,7 @@ 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) { @@ -699,7 +705,7 @@ 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) { diff --git a/shlibs/mount/src/tab_parse.c b/shlibs/mount/src/tab_parse.c index f8d6680f..fe2b1103 100644 --- a/shlibs/mount/src/tab_parse.c +++ b/shlibs/mount/src/tab_parse.c @@ -381,12 +381,8 @@ err: * * 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: - * + * + * * mnt_tab *tb = mnt_new_tab("/etc/fstab"); * int rc; * @@ -401,6 +397,12 @@ err: * mnt_fprintf_tab(tb, stdout, NULL); * * mnt_free_tab(tb); + * + * + * + * 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) { @@ -450,7 +452,7 @@ error: * 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) { @@ -472,7 +474,7 @@ 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) { @@ -486,7 +488,7 @@ 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." */ diff --git a/shlibs/mount/src/utils.c b/shlibs/mount/src/utils.c index fb9ffe8d..1f3337f2 100644 --- a/shlibs/mount/src/utils.c +++ b/shlibs/mount/src/utils.c @@ -5,6 +5,11 @@ * GNU Lesser General Public License. */ +/** + * SECTION: utils + * @title: Utils + * @short_description: misc utils. + */ #include #include #include diff --git a/shlibs/mount/src/version.c b/shlibs/mount/src/version.c index 0380e1c2..d00a1686 100644 --- a/shlibs/mount/src/version.c +++ b/shlibs/mount/src/version.c @@ -7,6 +7,12 @@ * See COPYING.libmount for the License of this software. */ +/** + * SECTION: version + * @title: Version functions + * @short_description: functions to get library version. + */ + #include #include #include