From 1457d1e348f07315cbf85d5b1223f08938bdcaa1 Mon Sep 17 00:00:00 2001 From: Delia Pavel Date: Mon, 20 Nov 2023 22:27:40 +0200 Subject: [PATCH] lib/posix-user: Add comments for posix-user Signed-off-by: Delia-Maria Pavel --- lib/posix-user/musl-imported/include/grp.h | 110 +++++++++++++++++++++ lib/posix-user/user.h | 24 +++++ 2 files changed, 134 insertions(+) diff --git a/lib/posix-user/musl-imported/include/grp.h b/lib/posix-user/musl-imported/include/grp.h index c738eef06..3f808061f 100644 --- a/lib/posix-user/musl-imported/include/grp.h +++ b/lib/posix-user/musl-imported/include/grp.h @@ -15,22 +15,104 @@ extern "C" { #include +/** + * An entry containing the necessary data for defining a group + */ struct group { + /* Group name */ char *gr_name; + /* Group password */ char *gr_passwd; + /* Group identifier */ gid_t gr_gid; + /* List of group members */ char **gr_mem; }; +/** + * Searches through the groups (there is just the default group at the moment) + * for a specific group ID and returns a pointer to an object with the group + * information. + * + * @param gid + * Group id to search by + * @return + * Pointer to the group with group id `gid`. + */ struct group *getgrgid(gid_t); +/** + * Searches through the groups (there is just the default group at the moment) + * for a specific group name and returns a pointer to an object with the group + * information. + * + * @param name + * Group name to search by + * @return + * Pointer to the group with group name `name`. + */ struct group *getgrnam(const char *); +/** + * Like `getgrgid`, but stores the retrieved `group` + * structure in the space pointed to by `grp`. + * + * @param gid + * Group id to search by + * @param grp + * Group structure in which the group with the `gid` group id is stored + * @param buf + * Buffer which holds the string fields pointed to by the members of the + * `group` structure + * @param buflen + * Length of buffer `buf` + * @param result + * Pointer to a location in which a pointer to the updated `group` structure + * is stored. If an error occurs or if the requested entry cannot be found, + * a NULL pointer is stored in this location + * @return + * 0 on success, `ERANGE` if `buflen` is not large enough. + */ int getgrgid_r(gid_t, struct group *, char *, size_t, struct group **); +/** + * Like `getgrnam`, but stores the retrieved `group` structure + * in the space pointed to by `grp`. + * + * @param name + * Group name to search by + * @param grp + * Group structure in which the group with the `name` group name is stored + * @param buf + * Buffer which holds the string fields pointed to by the members of the + * `group` structure + * @param buflen + * Length of buffer `buf` + * @param result + * Pointer to a location in which a pointer to the updated `group` structure + * is stored. If an error occurs or if the requested entry cannot be found, + * a NULL pointer is stored in this location + * @return + * 0 on success, `ERANGE` if `buflen` is not large enough. + */ int getgrnam_r(const char *, struct group *, char *, size_t, struct group **); #if defined(_XOPEN_SOURCE) || defined(_GNU_SOURCE) || defined(_BSD_SOURCE) +/** + * The first time this function is called, it returns the first entry. + * Afterward, it returns successive entries. + * This function allows iterating over all the groups from the array. + * + * @return + * The current group entry. + */ struct group *getgrent(void); +/** + * This function is normally used to close the group database, + * but since, in this case, this is just an array, it does nothing. + */ void endgrent(void); +/** + * Sets the groups iterator at the beginning of the `groups` array. + */ void setgrent(void); #endif @@ -40,7 +122,35 @@ int putgrent(const struct group *, FILE *); #endif #if defined(_GNU_SOURCE) || defined(_BSD_SOURCE) +/** + * Gets the list of groups that the given user belongs to. + * + * @param user + * User for whom to get the group list in which it belongs + * @param group + * Group which will be included in `groups`, + * if it was not among the groups defined for `user` + * @param groups + * Array of groups the user belongs to + * @param ngroups + * Maximum number of groups to return in the list at input, number of groups + * the user belogs to at output + * @return + * The number of groups the user belongs to, or -1 on error. + */ int getgrouplist(const char *, gid_t, gid_t *, int *); +/** + * Sets the supplementary group IDs for the calling process. There is only one + * group (the default group), so this function only tests if the caller tries + * to set any invalid groups. + * + * @param size + * Size of the `list` buffer + * @param list + * List of supplementary group IDs + * @return + * 0 on success, -1 on error. + */ int setgroups(size_t, const gid_t *); int initgroups(const char *, gid_t); #endif diff --git a/lib/posix-user/user.h b/lib/posix-user/user.h index 8d0d674aa..0ad37a643 100644 --- a/lib/posix-user/user.h +++ b/lib/posix-user/user.h @@ -43,9 +43,33 @@ #define UK_DEFAULT_GROUP CONFIG_LIBPOSIX_USER_GROUPNAME #define UK_DEFAULT_PASS "" +/** + * Initializes the `passwds` list and inserts in it the first entry. + * This entry contains the default values defined above, such that + * name => `UK_DEFAULT_USER`, passwd => `UK_DEFAULT_PASS`, + * uid => `UK_DEFAULT_UID`, gid => `UK_DEFAULT_GID`, + * gecos => `UK_DEFAULT_USER`, dir = "/", shell = "". + */ void pu_init_passwds(void); +/** + * Initializes the `groups` list and inserts in it the first entry. + * This entry contains the default values defined above, such that + * name => `UK_DEFAULT_GROUP`, passwd => `UK_DEFAULT_PASS`, + * uid => `UK_DEFAULT_GID`, mem => `{ `UK_DEFAULT_USER` }`. + */ void pu_init_groups(void); +/** + * Copies `src` string at the end of the `dest` string, + * also adding `\0` at the end. + * + * @param src + * Source string + * @param dest + * Destination string + * @return + * Destination string, containing the source string at the end. + */ static inline char *pu_cpystr(char *src, char *dest) { UK_ASSERT(src); -- 2.39.5