VFS_GETOPT(9)

✨ VFS_GETOPT(9) ✨ — the Kernel Developer's Manual girlies' edition 💅

okay bestie, sit DOWN, because today we're talking about vfs_getopt and its entire friend group 🫶 this is a Kernel Developer's Manual page, so grab a strawberry drink and let's get into it 🌸

🎀 NAME 🎀

vfs_getopt, vfs_getopts, vfs_flagopt, vfs_scanopt, vfs_copyopt, vfs_filteropt, vfs_setopt, vfs_setopt_part, vfs_setopts — manipulate mount options and their values

like. the whole squad. mount options and the values that come with them. that's the job 💖

🌈 SYNOPSIS 🌈

#include <sys/param.h>
#include <sys/mount.h>

int
vfs_getopt(struct vfsoptlist *opts, const char *name, void **buf,
    int *len);

char *
vfs_getops(struct vfsoptlist *opts, const char *name, int *error);

int
vfs_flagopt(struct vfsoptlist *opts, const char *name, uint64_t *flags,
    uint64_t flag);

int
vfs_scanopt(struct vfsoptlist *opts, const char *name, const char *fmt,
    ...);

int
vfs_copyopt(struct vfsoptlist *opts, const char *name, void *dest,
    int len);

int
vfs_filteropt(struct vfsoptlist *opts, const char **legal);

int
vfs_setopt(struct vfsoptlist *opts, const char *name, void *value,
    int len);

int
vfs_setopt_part(struct vfsoptlist *opts, const char *name, void *value,
    int len);

int
vfs_setopts(struct vfsoptlist *opts, const char *name,
    const char *value);

💜 DESCRIPTION 💜

the way that this whole page is just nine little functions handling mount options like the icons they are 😭 let's go one by one, no skipping, fr fr.

• vfs_getopt() — this one sets buf to point at the value of the named mount option, and sets len to the length of that value if it's not NULL. and listen, buf points to the actual value — you do not need to free or release it (and honestly? you probably should not be modifying it either 🙈).
• vfs_getopts() — returns the value of the specified option, but only if it's a string (i.e., NUL terminated).
• vfs_flagopt() — checks whether an option exists. if the option does exist, and flags is not NULL, then flag gets added to the ones already set in flags. if the option does not exist, and flags is not NULL, then flag gets removed from the ones already set in flags. classic usage looks like this, and it's giving very much "set the flag only if the vibes are right":

if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0))
        vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK);

• vfs_scanopt() — performs a vsscanf(3) with the option's value, using the given format, into the specified variable arguments. the value must be a string (i.e., NUL terminated).
• vfs_copyopt() — makes a copy of the option's value. the len argument has to match the length of the option's value exactly — like, a larger buffer will still cause vfs_copyout() to fail with EINVAL. no cap, exact match or nothing 💀
• vfs_filteropt() — makes sure no unknown options were specified. an option is valid if its name matches one of the names in the list of legal names. and yes, an option may be prefixed with 'no' and still be considered valid. lenient queen 👑
• vfs_setopt() and vfs_setopt_part() — these two copy new data into the option's value. in vfs_setopt(), the len argument must match the length of the option's value exactly (i.e., a larger buffer will still cause vfs_copyout() to fail with EINVAL). same energy as vfs_copyopt(), same exact-match drama.
• vfs_setopts() — copies a new string into the option's value. the string, including the NUL byte, must be no longer than the option's length. count that byte bestie, it counts 🌸

⭐ RETURN VALUES ⭐

the receipts, function by function:

• vfs_getopt() returns 0 if the option was found; otherwise, ENOENT is returned.
• vfs_getops() returns the specified option if it is found, and is NUL terminated. if the option was found but is not NUL terminated, error is set to EINVAL and NULL is returned. if the option was not found, error is set to 0, and NULL is returned.
• vfs_flagopt() returns 1 if the option was found, and 0 if it was not.
• vfs_scanopt() returns 0 if the option was not found, or was not NUL terminated; otherwise, the return value of vsscanf(3) is returned. and if vsscanf(3) returns 0, it will be returned unchanged — so a return value of 0 does not always mean the option does not exist, or is not a valid string. sneaky little 0, we love an ambiguous queen 😭
• vfs_copyopt() and vfs_setopt() return 0 if the copy was successful, EINVAL if the option was found but the lengths did not match, and ENOENT if the option was not found.
• vfs_filteropt() returns 0 if all of the options are legal; otherwise, EINVAL is returned.
• vfs_setopts() returns 0 if the copy was successful, EINVAL if the option was found but the string was too long, and ENOENT if the option was not found.

🦋 AUTHORS 🦋

this manual page was written by Chad David <davidc@FreeBSD.org> and Ruslan Ermilov <ru@FreeBSD.org>. absolute legends, thank you for your service 🫶

and that's the page!! Debian, July 31, 2011, VFS_GETOPT(9) — mwah, iconic, periodt 💖✨🎀