Welcome to NYCU CSIT Mirror site

Table of filesystems: libmount Reference Manual

Table of filesystems

Table of filesystems — container for entries from fstab, mtab or mountinfo

Functions

void mnt_free_table ()
struct libmnt_table * mnt_new_table ()
int mnt_reset_table ()
void mnt_ref_table ()
void mnt_unref_table ()
struct libmnt_table * mnt_new_table_from_dir ()
struct libmnt_table * mnt_new_table_from_file ()
int mnt_table_add_fs ()
int mnt_table_append_intro_comment ()
int mnt_table_append_trailing_comment ()
void mnt_table_enable_comments ()
struct libmnt_fs * mnt_table_find_devno ()
int mnt_table_find_fs ()
struct libmnt_fs * mnt_table_find_mountpoint ()
int mnt_table_find_next_fs ()
struct libmnt_fs * mnt_table_find_pair ()
struct libmnt_fs * mnt_table_find_source ()
struct libmnt_fs * mnt_table_find_srcpath ()
struct libmnt_fs * mnt_table_find_tag ()
struct libmnt_fs * mnt_table_find_target ()
struct libmnt_fs * mnt_table_find_target_with_option ()
int mnt_table_first_fs ()
struct libmnt_cache * mnt_table_get_cache ()
const char * mnt_table_get_intro_comment ()
int mnt_table_get_nents ()
int mnt_table_get_root_fs ()
const char * mnt_table_get_trailing_comment ()
void * mnt_table_get_userdata ()
int mnt_table_insert_fs ()
int mnt_table_is_empty ()
int mnt_table_is_fs_mounted ()
int mnt_table_last_fs ()
int mnt_table_move_fs ()
int mnt_table_next_child_fs ()
int mnt_table_next_fs ()
int mnt_table_over_fs ()
int mnt_table_parse_dir ()
int mnt_table_parse_file ()
int mnt_table_parse_fstab ()
int mnt_table_parse_mtab ()
int mnt_table_parse_stream ()
int mnt_table_parse_swaps ()
int mnt_table_remove_fs ()
int mnt_table_set_cache ()
int mnt_table_set_intro_comment ()
int mnt_table_set_iter ()
int mnt_table_set_parser_errcb ()
int mnt_table_set_trailing_comment ()
int mnt_table_set_userdata ()
int mnt_table_uniq_fs ()
int mnt_table_with_comments ()

Types and Values

struct libmnt_table

Description

Note that mnt_table_find_* functions are mount(8) compatible. These functions try to find 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 a fstab with two entries:

1
2
LABEL=foo	/foo	auto   rw
/dev/foo	/foo	auto   rw

where both lines are used for the *same* device, then

1
mnt_table_find_source(tb, "/dev/foo", &fs);

will returns the second line, and

1
mnt_table_find_source(tb, "LABEL=foo", &fs);

will returns the first entry, and

1
mnt_table_find_source(tb, "UUID=anyuuid", &fs);

will return the first entry (if UUID matches with the device).

Functions

mnt_free_table ()

void
mnt_free_table (struct libmnt_table *tb);

Deallocates the table. This function does not care about reference count. Don't use this function directly -- it's better to use mnt_unref_table().

The table entries (filesystems) are unreferenced by mnt_reset_table() and cache by mnt_unref_cache().

Parameters

tb

tab pointer

 

mnt_new_table ()

struct libmnt_table *
mnt_new_table (void);

The tab is a container for struct libmnt_fs entries that usually represents a fstab, mtab or mountinfo file from your system.

See also mnt_table_parse_file().

Returns

newly allocated tab struct.


mnt_reset_table ()

int
mnt_reset_table (struct libmnt_table *tb);

Removes all entries (filesystems) from the table. The filesystems with zero reference count will be deallocated.

Parameters

tb

tab pointer

 

Returns

0 on success or negative number in case of error.


mnt_ref_table ()

void
mnt_ref_table (struct libmnt_table *tb);

Increments reference counter.

Parameters

tb

table pointer

 

mnt_unref_table ()

void
mnt_unref_table (struct libmnt_table *tb);

De-increments reference counter, on zero the tb is automatically deallocated by mnt_free_table().

Parameters

tb

table pointer

 

mnt_new_table_from_dir ()

struct libmnt_table *
mnt_new_table_from_dir (const char *dirname);

Parameters

dirname

directory with *.fstab files

 

Returns

newly allocated tab on success and NULL in case of error.


mnt_new_table_from_file ()

struct libmnt_table *
mnt_new_table_from_file (const char *filename);

Same as mnt_new_table() + mnt_table_parse_file(). Use this function for private files only. This function does not allow using the error callback, so you cannot provide any feedback to end-users about broken records in files (e.g. fstab).

Parameters

filename

/etc/{m,fs}tab or /proc/self/mountinfo path

 

Returns

newly allocated tab on success and NULL in case of error.


mnt_table_add_fs ()

int
mnt_table_add_fs (struct libmnt_table *tb,
                  struct libmnt_fs *fs);

Adds a new entry to tab and increment fs reference counter. Don't forget to use mnt_unref_fs() after mnt_table_add_fs() you want to keep the fs referenced by the table only.

Parameters

tb

tab pointer

 

fs

new entry

 

Returns

0 on success or negative number in case of error.


mnt_table_append_intro_comment ()

int
mnt_table_append_intro_comment (struct libmnt_table *tb,
                                const char *comm);

mnt_table_append_trailing_comment ()

int
mnt_table_append_trailing_comment (struct libmnt_table *tb,
                                   const char *comm);

Appends to the trailing table comment.

Parameters

tb

pointer to tab

 

comm

comment of NULL

 

Returns

0 on success or negative number in case of error.


mnt_table_enable_comments ()

void
mnt_table_enable_comments (struct libmnt_table *tb,
                           int enable);

Enables parsing of comments.

The initial (intro) file comment is accessible by mnt_table_get_intro_comment(). The intro and the comment of the first fstab entry has to be separated by blank line. The filesystem comments are accessible by mnt_fs_get_comment(). The trailing fstab comment is accessible by mnt_table_get_trailing_comment().

1
2
3
4
5
6
7
8
9
#
# Intro comment
#

# this comments belongs to the first fs
LABEL=foo /mnt/foo auto defaults 1 2
# this comments belongs to the second fs
LABEL=bar /mnt/bar auto defaults 1 2
# tailing comment

Parameters

tb

pointer to tab

 

enable

TRUE or FALSE

 

mnt_table_find_devno ()

struct libmnt_fs *
mnt_table_find_devno (struct libmnt_table *tb,
                      dev_t devno,
                      int direction);

Note that zero could be a valid device number for the root pseudo filesystem (e.g. tmpfs).

Parameters

tb

/proc/self/mountinfo

 

devno

device number

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_fs ()

int
mnt_table_find_fs (struct libmnt_table *tb,
                   struct libmnt_fs *fs);

Checks if fs is part of table tb .

Parameters

tb

tab pointer

 

fs

entry to look for

 

Returns

index of fs in table, 0 if not found or negative number in case of error.

Since: 2.34


mnt_table_find_mountpoint ()

struct libmnt_fs *
mnt_table_find_mountpoint (struct libmnt_table *tb,
                           const char *path,
                           int direction);

Same as mnt_get_mountpoint(), except this function does not rely on st_dev numbers.

Parameters

tb

tab pointer

 

path

directory

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_next_fs ()

int
mnt_table_find_next_fs (struct libmnt_table *tb,
                        struct libmnt_iter *itr,
                        int (*match_func) (struct libmnt_fs *, void *),
                        void *userdata,
                        struct libmnt_fs **fs);

This function allows searching in tb .

Parameters

tb

table

 

itr

iterator

 

match_func

function returning 1 or 0

 

userdata

extra data for match_func

 

fs

returns pointer to the next matching table entry

 

Returns

negative number in case of error, 1 at end of table or 0 o success.


mnt_table_find_pair ()

struct libmnt_fs *
mnt_table_find_pair (struct libmnt_table *tb,
                     const char *source,
                     const char *target,
                     int direction);

This function is implemented by mnt_fs_match_source() and mnt_fs_match_target() functions. It means that this is more expensive than others mnt_table_find_* function, because every tab entry is fully evaluated.

Parameters

tb

tab pointer

 

source

TAG or path

 

target

mountpoint

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_source ()

struct libmnt_fs *
mnt_table_find_source (struct libmnt_table *tb,
                       const char *source,
                       int direction);

This is a high-level API for mnt_table_find_{srcpath,tag}. You needn't care about the source format (device, LABEL, UUID, ...). This function parses the source and calls mnt_table_find_tag() or mnt_table_find_srcpath().

Parameters

tb

tab pointer

 

source

TAG or path

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_srcpath ()

struct libmnt_fs *
mnt_table_find_srcpath (struct libmnt_table *tb,
                        const char *path,
                        int direction);

Try to lookup an entry in the given tab, four iterations are possible, the first with path , the second with realpath(path ), the third with tags (LABEL, UUID, ..) from path and the fourth with realpath(path ) against realpath(entry->srcpath).

The 2nd, 3rd and 4th iterations are not performed when the tb cache is not set (see mnt_table_set_cache()).

For btrfs returns tab entry for default id.

Note that NULL is a valid source path; it will be replaced with "none". The "none" is used in /proc/{mounts,self/mountinfo} for pseudo filesystems.

Parameters

tb

tab pointer

 

path

source path (devname or dirname) or NULL

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_tag ()

struct libmnt_fs *
mnt_table_find_tag (struct libmnt_table *tb,
                    const char *tag,
                    const char *val,
                    int direction);

Try to lookup an entry in the given tab, the first attempt is to lookup by tag and val , for the second attempt the tag is evaluated (converted to the device name) and mnt_table_find_srcpath() is performed. The second attempt is not performed when tb cache is not set (see mnt_table_set_cache()).

Parameters

tb

tab pointer

 

tag

tag name (e.g "LABEL", "UUID", ...)

 

val

tag value

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_target ()

struct libmnt_fs *
mnt_table_find_target (struct libmnt_table *tb,
                       const char *path,
                       int direction);

Try to lookup an entry in the given tab, three iterations are possible, the first with path , the second with realpath(path ) and the third with realpath(path ) against realpath(fs->target). The 2nd and 3rd iterations are not performed when the tb cache is not set (see mnt_table_set_cache()). If mnt_cache_set_targets(cache, mtab) was called, the 3rd iteration skips any fs->target found in mtab (see mnt_resolve_target()).

Parameters

tb

tab pointer

 

path

mountpoint directory

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.


mnt_table_find_target_with_option ()

struct libmnt_fs *
mnt_table_find_target_with_option (struct libmnt_table *tb,
                                   const char *path,
                                   const char *option,
                                   const char *val,
                                   int direction);

Try to lookup an entry in the given tab that matches combination of path and option . In difference to mnt_table_find_target(), only path iteration is done. No lookup by device name, no canonicalization.

Parameters

tb

tab pointer

 

path

mountpoint directory

 

option

option name (e.g "subvol", "subvolid", ...)

 

val

option value or NULL

 

direction

MNT_ITER_{FORWARD,BACKWARD}

 

Returns

a tab entry or NULL.

Since: 2.28


mnt_table_first_fs ()

int
mnt_table_first_fs (struct libmnt_table *tb,
                    struct libmnt_fs **fs);

Parameters

tb

tab pointer

 

fs

returns the first tab entry

 

Returns

0 on success, negative number in case of error or 1 at the end of list.


mnt_table_get_cache ()

struct libmnt_cache *
mnt_table_get_cache (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

pointer to struct libmnt_cache instance or NULL.


mnt_table_get_intro_comment ()

const char *
mnt_table_get_intro_comment (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

initial comment in tb


mnt_table_get_nents ()

int
mnt_table_get_nents (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

number of entries in table.


mnt_table_get_root_fs ()

int
mnt_table_get_root_fs (struct libmnt_table *tb,
                       struct libmnt_fs **root);

The function uses the parent ID from the mountinfo file to determine the root filesystem (the filesystem with the smallest ID with parent ID missing in the table). The function is designed mostly for applications where it is necessary to sort mountpoints by IDs to get the tree of the mountpoints (e.g. findmnt default output).

If you're not sure, then use

mnt_table_find_target(tb, "/", MNT_ITER_BACKWARD);

this is more robust and usable for arbitrary tab files (including fstab).

Parameters

tb

mountinfo file (/proc/self/mountinfo)

 

root

returns pointer to the root filesystem (/)

 

Returns

0 on success or negative number in case of error.


mnt_table_get_trailing_comment ()

const char *
mnt_table_get_trailing_comment (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

table trailing comment


mnt_table_get_userdata ()

void *
mnt_table_get_userdata (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

pointer to user's data.


mnt_table_insert_fs ()

int
mnt_table_insert_fs (struct libmnt_table *tb,
                     int before,
                     struct libmnt_fs *pos,
                     struct libmnt_fs *fs);

Adds a new entry to tb before or after a specific table entry pos . If the pos is NULL than add the begin of the tab if before is 1; or to the tail of the tb if before is 0.

This function increments reference to fs . Don't forget to use mnt_unref_fs() after mnt_table_insert_fs() if you want to keep the fs referenced by the table only.

Parameters

tb

tab pointer

 

before

1 to insert before pos, 0 to insert after pos

 

pos

entry to specify position or NULL

 

fs

new entry

 

Returns

0 on success or negative number in case of error.

Since: 2.34


mnt_table_is_empty ()

int
mnt_table_is_empty (struct libmnt_table *tb);

Parameters

tb

pointer to tab

 

Returns

1 if the table is without filesystems, or 0.


mnt_table_is_fs_mounted ()

int
mnt_table_is_fs_mounted (struct libmnt_table *tb,
                         struct libmnt_fs *fstab_fs);

Checks if the fstab_fs entry is already in the tb table. The "swap" is ignored. This function explicitly compares the source, target and root of the filesystems.

Note that source and target are canonicalized only if a cache for tb is defined (see mnt_table_set_cache()). The target canonicalization may trigger automount on autofs mountpoints!

Don't use it if you want to know if a device is mounted, just use mnt_table_find_source() on the device.

This function is designed mostly for "mount -a".

Parameters

tb

/proc/self/mountinfo file

 

fstab_fs

/etc/fstab entry

 

Returns

0 or 1


mnt_table_last_fs ()

int
mnt_table_last_fs (struct libmnt_table *tb,
                   struct libmnt_fs **fs);

Parameters

tb

tab pointer

 

fs

returns the last tab entry

 

Returns

0 on success, negative number in case of error or 1 at the end of list.


mnt_table_move_fs ()

int
mnt_table_move_fs (struct libmnt_table *src,
                   struct libmnt_table *dst,
                   int before,
                   struct libmnt_fs *pos,
                   struct libmnt_fs *fs);

Removes fs from src table and adds it before/after a specific entry pos of dst table. If the pos is NULL than add the begin of the dst if before is 1; or to the tail of the dst if before is 0.

The reference counter of fs is not modified.

Parameters

src

tab pointer of source table

 

dst

tab pointer of destination table

 

before

1 to move before position, 0 to move after position

 

pos

entry to specify position or NULL

 

fs

entry to move

 

Returns

0 on success or negative number in case of error.

Since: 2.34


mnt_table_next_child_fs ()

int
mnt_table_next_child_fs (struct libmnt_table *tb,
                         struct libmnt_iter *itr,
                         struct libmnt_fs *parent,
                         struct libmnt_fs **chld);

Note that filesystems are returned in the order of mounting (according to IDs in /proc/self/mountinfo).

Parameters

tb

mountinfo file (/proc/self/mountinfo)

 

itr

iterator

 

parent

parental FS

 

chld

returns the next child filesystem

 

Returns

0 on success, negative number in case of error or 1 at the end of list.


mnt_table_next_fs ()

int
mnt_table_next_fs (struct libmnt_table *tb,
                   struct libmnt_iter *itr,
                   struct libmnt_fs **fs);

Parameters

tb

tab pointer

 

itr

iterator

 

fs

returns the next tab entry

 

Returns

0 on success, negative number in case of error or 1 at the end of list.

Example:

1
2
3
4
while(mnt_table_next_fs(tb, itr, &fs) == 0) {
const char *dir = mnt_fs_get_target(fs);
printf("mount point: %s\n", dir);
}

lists all mountpoints from fstab in reverse order.


mnt_table_over_fs ()

int
mnt_table_over_fs (struct libmnt_table *tb,
                   struct libmnt_fs *parent,
                   struct libmnt_fs **child);

This function returns by child the first filesystenm which is over-mounted on parent . It means the mountpoint of child is the same as for parent and parent->id is the same as child->parent_id.

Note that you need to call this function in loop until it returns 1 to get the highest filesystem.

Example:

1
2
3
4
while (mnt_table_over_fs(tb, cur, &over) == 0) {
	printf("%s overmounted by %d\n", mnt_fs_get_target(cur), mnt_fs_get_id(over));
	cur = over;
}

Parameters

tb

tab pointer

 

parent

pointer to parental FS

 

child

returns pointer to FS which over-mounting parent (optional)

 

Returns

0 on success, negative number in case of error or 1 at the end of list.


mnt_table_parse_dir ()

int
mnt_table_parse_dir (struct libmnt_table *tb,
                     const char *dirname);

The directory:

  • files are sorted by strverscmp(3)

  • files that start with "." are ignored (e.g. ".10foo.fstab")

  • files without the ".fstab" extension are ignored

Parameters

tb

mount table

 

dirname

directory

 

Returns

0 on success or negative number in case of error.


mnt_table_parse_file ()

int
mnt_table_parse_file (struct libmnt_table *tb,
                      const char *filename);

Parses the whole table (e.g. /etc/fstab) and appends new records to the tab .

The libmount parser ignores broken (syntax error) lines, these lines are reported to the caller by the errcb() function (see mnt_table_set_parser_errcb()).

Parameters

tb

tab pointer

 

filename

file

 

Returns

0 on success, negative number in case of error.


mnt_table_parse_fstab ()

int
mnt_table_parse_fstab (struct libmnt_table *tb,
                       const char *filename);

This function parses /etc/fstab and appends new lines to the tab . If the filename is a directory, then mnt_table_parse_dir() is called.

See also mnt_table_set_parser_errcb().

Parameters

tb

table

 

filename

overwrites default (/etc/fstab or $LIBMOUNT_FSTAB) or NULL

 

Returns

0 on success or negative number in case of error.


mnt_table_parse_mtab ()

int
mnt_table_parse_mtab (struct libmnt_table *tb,
                      const char *filename);

The default filename is /proc/self/mountinfo. If the mount table is a mountinfo file then /run/mount/utabs is parsed too and both files are merged to the one libmnt_table.

If libmount is compiled with classic mtab file support, and the /etc/mtab is a regular file then this file is parsed.

It's strongly recommended to use NULL as a filename to keep code portable.

See also mnt_table_set_parser_errcb().

Parameters

tb

table

 

filename

overwrites default or NULL

 

Returns

0 on success or negative number in case of error.


mnt_table_parse_stream ()

int
mnt_table_parse_stream (struct libmnt_table *tb,
                        FILE *f,
                        const char *filename);

Parameters

tb

tab pointer

 

f

file stream

 

filename

filename used for debug and error messages

 

Returns

0 on success, negative number in case of error.


mnt_table_parse_swaps ()

int
mnt_table_parse_swaps (struct libmnt_table *tb,
                       const char *filename);

This function parses /proc/swaps and appends new lines to the tab .

See also mnt_table_set_parser_errcb().

Parameters

tb

table

 

filename

overwrites default (/proc/swaps or $LIBMOUNT_SWAPS) or NULL

 

Returns

0 on success or negative number in case of error.


mnt_table_remove_fs ()

int
mnt_table_remove_fs (struct libmnt_table *tb,
                     struct libmnt_fs *fs);

Removes the fs from the table and de-increment reference counter of the fs . The filesystem with zero reference counter will be deallocated. Don't forget to use mnt_ref_fs() before call mnt_table_remove_fs() if you want to use fs later.

Parameters

tb

tab pointer

 

fs

new entry

 

Returns

0 on success or negative number in case of error.


mnt_table_set_cache ()

int
mnt_table_set_cache (struct libmnt_table *tb,
                     struct libmnt_cache *mpc);

Sets up a cache for canonicalized paths and evaluated tags (LABEL/UUID). The cache is recommended for mnt_table_find_*() functions.

The cache could be shared between more tabs. Be careful when you share the same cache between more threads -- currently the cache does not provide any locking method.

This function increments cache reference counter. It's recommended to use mnt_unref_cache() after mnt_table_set_cache() if you want to keep the cache referenced by tb only.

See also mnt_new_cache().

Parameters

tb

pointer to tab

 

mpc

pointer to struct libmnt_cache instance

 

Returns

0 on success or negative number in case of error.


mnt_table_set_intro_comment ()

int
mnt_table_set_intro_comment (struct libmnt_table *tb,
                             const char *comm);

mnt_table_set_iter ()

int
mnt_table_set_iter (struct libmnt_table *tb,
                    struct libmnt_iter *itr,
                    struct libmnt_fs *fs);

Sets iter to the position of fs in the file tb .

Parameters

tb

tab pointer

 

itr

iterator

 

fs

tab entry

 

Returns

0 on success, negative number in case of error.


mnt_table_set_parser_errcb ()

int
mnt_table_set_parser_errcb (struct libmnt_table *tb,
                            int (*cb) (struct libmnt_table *tb, const char *filename, int line));

The error callback function is called by table parser (mnt_table_parse_file()) in case of a syntax error. The callback function could be used for error evaluation, libmount will continue/stop parsing according to callback return codes:

<0 : fatal error (abort parsing) 0 : success (parsing continues) >0 : recoverable error (the line is ignored, parsing continues).

Parameters

tb

pointer to table

 

cb

pointer to callback function

 

Returns

0 on success or negative number in case of error.


mnt_table_set_trailing_comment ()

int
mnt_table_set_trailing_comment (struct libmnt_table *tb,
                                const char *comm);

Sets the trailing comment in table.

Parameters

tb

pointer to tab

 

comm

comment string

 

Returns

0 on success or negative number in case of error.


mnt_table_set_userdata ()

int
mnt_table_set_userdata (struct libmnt_table *tb,
                        void *data);

Sets pointer to the private user data.

Parameters

tb

pointer to tab

 

data

pointer to user data

 

Returns

0 on success or negative number in case of error.


mnt_table_uniq_fs ()

int
mnt_table_uniq_fs (struct libmnt_table *tb,
                   int flags,
                   int (*cmp) (struct libmnt_table *, struct libmnt_fs *, struct libmnt_fs *));

This function de-duplicate the tb , but does not change order of the filesystems. The cmp function has to return 0 if the filesystems are equal, otherwise non-zero.

The default is to keep in the table later mounted filesystems (function uses backward mode iterator).

MNT_UNIQ_FORWARD : remove later mounted filesystems MNT_UNIQ_KEEPTREE : keep parent->id relationship still valid

Parameters

tb

table

 

flags

MNT_UNIQ_*

 

cmp

function to compare filesystems

 

Returns

negative number in case of error, or 0 o success.


mnt_table_with_comments ()

int
mnt_table_with_comments (struct libmnt_table *tb);

Parameters

tb

pointer to table

 

Returns

1 if comments parsing is enabled, or 0.

Types and Values

struct libmnt_table

struct libmnt_table;

List of struct libmnt_fs entries (parsed fstab/mtab/mountinfo)