Merge pull request #110 from Galfurian/develop

Improve Dynamic and 2D Ring Buffer Implementation, Enhance Shell Functionality, and Add Comments and Error Checks

files/README → files/README.md

@@ -1,4 +1,4 @@
-MentOS 0.7.2
+# MentOS 0.7.2
 
 Welcome to the MentOS, the Mentoring Operating System.
 

files/home/user/README.md

@@ -0,0 +1 @@
+../../README.md

libc/inc/err.h

@@ -7,14 +7,51 @@
 
 #include <stdarg.h>
 
-/// @brief Print formatted error message on stderr and exit
-/// @param eval The exit value.
-/// @param fmt  The format string.
+/// @brief Print a formatted error message on stderr and exit the program.
+///
+/// @details This function prints an error message to stderr, formatted
+/// according to the given format string, followed by a system error message if
+/// applicable. It then terminates the program with the specified exit value.
+/// This is typically used when a system call fails.
+///
+/// @param eval The exit value to use when terminating the program.
+/// @param fmt The format string for the error message.
 void err(int eval, const char *fmt, ...);
+
+/// @brief Print a formatted error message on stderr using a va_list and exit
+/// the program.
+///
+/// @details This function is similar to `err()`, but accepts a `va_list` to
+/// support variable arguments. This allows you to pass a list of arguments that
+/// can be formatted into the error message. The program exits with the
+/// specified exit value.
+///
+/// @param eval The exit value to use when terminating the program.
+/// @param fmt The format string for the error message.
+/// @param args The variable argument list.
 void verr(int eval, const char *fmt, va_list args);
 
-/// @brief Print formatted message on stderr without appending an error message and exit
-/// @param eval The exit value.
-/// @param fmt  The format string.
+/// @brief Print a formatted message on stderr without appending an error
+/// message and exit.
+///
+/// @details This function prints a formatted message to stderr without
+/// appending a system error message (such as those related to errno). It then
+/// terminates the program with the specified exit value. This is useful when
+/// the error isn't related to a system call failure but requires exiting the
+/// program.
+///
+/// @param eval The exit value to use when terminating the program.
+/// @param fmt The format string for the message.
 void errx(int eval, const char *fmt, ...);
+
+/// @brief Print a formatted message on stderr using a va_list and exit without
+/// appending an error message.
+///
+/// @details This function is similar to `errx()`, but accepts a `va_list` to
+/// handle variable arguments. It prints the formatted message and exits the
+/// program without appending a system error message.
+///
+/// @param eval The exit value to use when terminating the program.
+/// @param fmt The format string for the message.
+/// @param args The variable argument list.
 void verrx(int eval, const char *fmt, va_list args);

libc/inc/shadow.h

@@ -1,22 +1,52 @@
-// @file shadow.h
-/// @brief Secret password file routines
+/// @file shadow.h
+/// @brief Defines structures and functions for working with the shadow password
+/// file.
+/// @copyright (c) 2014-2024 This file is distributed under the MIT License.
+/// See LICENSE.md for details.
+
 #pragma once
 
 #include "stddef.h"
 
-#define SHADOW "/etc/shadow"
+#define SHADOW "/etc/shadow" ///< Path to the shadow password file.
 
+/// @brief Structure representing a shadow password record.
+/// @details This structure is used to store details from the shadow password
+/// file (`/etc/shadow`), including information such as the user's encrypted
+/// password and password change policies.
 struct spwd {
-    char *sp_namp;             ///< user login name.
-    char *sp_pwdp;             ///< encrypted password.
-    long int sp_lstchg;        ///< last password change.
-    long int sp_min;           ///< days until change allowed.
-    long int sp_max;           ///< days before change required.
-    long int sp_warn;          ///< days warning for expiration.
-    long int sp_inact;         ///< days before account inactive.
-    long int sp_expire;        ///< date when account expires.
-    unsigned long int sp_flag; ///< reserved for future use.
+    char *sp_namp;             ///< User login name.
+    char *sp_pwdp;             ///< Encrypted password.
+    long int sp_lstchg;        ///< Date of the last password change, in days since the epoch.
+    long int sp_min;           ///< Minimum number of days until the next password change is allowed.
+    long int sp_max;           ///< Maximum number of days before a password change is required.
+    long int sp_warn;          ///< Number of days before the password expires to warn the user.
+    long int sp_inact;         ///< Number of days after expiration until the account is considered inactive.
+    long int sp_expire;        ///< Date when the account expires, in days since the epoch.
+    unsigned long int sp_flag; ///< Reserved for future use.
 };
 
-struct spwd *getspnam(const char *);
-int getspnam_r(const char *, struct spwd *, char *, size_t, struct spwd **);
+/// @brief Retrieves a shadow password record by username.
+///
+/// @details This function retrieves the shadow password entry for a specific
+/// user from the shadow password file (`/etc/shadow`). It uses a static buffer
+/// to store the result, which is overwritten on each call.
+///
+/// @param name The login name of the user to search for.
+/// @return Pointer to the `spwd` structure with the user's shadow password entry, or NULL if not found.
+struct spwd *getspnam(const char * name);
+
+/// @brief Retrieves a shadow password record by username (reentrant version).
+///
+/// @details This function retrieves the shadow password entry for a specific
+/// user in a reentrant manner. It stores the result in user-provided buffers to
+/// avoid race conditions. This is the safer, thread-safe version of
+/// `getspnam()`.
+///
+/// @param name The login name of the user to search for.
+/// @param spwd_buf Pointer to a user-provided `spwd` structure where the result will be stored.
+/// @param buf Buffer to hold additional string data like the encrypted password.
+/// @param buflen Size of the buffer provided.
+/// @param result Pointer to the result. On success, this will point to `spwd_buf`, or NULL on failure.
+/// @return 0 on success, or a non-zero error code on failure.
+int getspnam_r(const char *name, struct spwd *spwd_buf, char *buf, size_t buflen, struct spwd **result);

libc/inc/stdio.h

@@ -82,6 +82,15 @@ int printf(const char *fmt, ...);
 ///         On failure, a negative number is returned.
 int sprintf(char *str, const char *fmt, ...);
 
+/// @brief Writes formatted output to `str`.
+/// @param str The buffer where the formatted string will be placed.
+/// @param size The size of the buffer.
+/// @param fmt The format string, following the same specifications as printf.
+/// @param ... The list of arguments.
+/// @return On success, the total number of characters written (excluding the null terminator) is returned.
+///         On failure, a negative number is returned.
+int snprintf(char *str, size_t size, const char *fmt, ...);
+
 #ifndef __KERNEL__
 /// @brief Write formatted output to a file.
 /// @param fd  The file descriptor associated with the file.
@@ -100,6 +109,14 @@ int fprintf(int fd, const char *fmt, ...);
 int vfprintf(int fd, const char *fmt, va_list args);
 #endif
 
+/// @brief Formats a string and ensures buffer boundaries are respected.
+/// @param str The output buffer where the formatted string will be stored.
+/// @param size The maximum size of the output buffer.
+/// @param fmt The format string.
+/// @param args The argument list for the format specifiers.
+/// @return int The number of characters written, excluding the null-terminator.
+int vsnprintf(char *str, size_t size, const char *fmt, va_list args);
+
 /// @brief Write formatted data from variable argument list to string.
 /// @param str  Pointer to a buffer where the resulting C-string is stored.
 /// @param fmt  Format string, following the same specifications as printf.

libc/inc/sys/mman.h

@@ -14,8 +14,6 @@
 #define MAP_SHARED  0x01 ///< The memory is shared.
 #define MAP_PRIVATE 0x02 ///< The memory is private.
 
-#ifndef __KERNEL__
-
 /// @brief creates a new mapping in the virtual address space of the calling process.
 /// @param addr the starting address for the new mapping.
 /// @param length specifies the length of the mapping (which must be greater than 0).
@@ -31,23 +29,3 @@ void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset)
 /// @param length the length of the mapped area.
 /// @return 0 on success, -1 on falure and errno is set.
 int munmap(void *addr, size_t length);
-
-#else
-
-/// @brief creates a new mapping in the virtual address space of the calling process.
-/// @param addr the starting address for the new mapping.
-/// @param length specifies the length of the mapping (which must be greater than 0).
-/// @param prot describes the desired memory protection of the mapping (and must not conflict with the open mode of the file).
-/// @param flags determines whether updates to the mapping are visible to other processes mapping the same region.
-/// @param fd in case of file mapping, the file descriptor to use.
-/// @param offset offset in the file, which must be a multiple of the page size PAGE_SIZE.
-/// @return returns a pointer to the mapped area, -1 and errno is set.
-void *sys_mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
-
-/// @brief deletes the mappings for the specified address range.
-/// @param addr the starting address.
-/// @param length the length of the mapped area.
-/// @return 0 on success, -1 on falure and errno is set.
-int sys_munmap(void *addr, size_t length);
-
-#endif

libc/inc/sys/msg.h

@@ -63,51 +63,6 @@ struct msqid_ds {
     pid_t msg_lrpid;
 };
 
-#ifdef __KERNEL__
-
-/// @brief Initializes the message queue system.
-/// @return 0 on success, 1 on failure.
-int msq_init(void);
-
-/// @brief Get a System V message queue identifier.
-/// @param key can be used either to obtain the identifier of a previously
-/// created message queue, or to create a new set.
-/// @param msgflg controls the behaviour of the function.
-/// @return the message queue identifier, -1 on failure, and errno is set to
-/// indicate the error.
-int sys_msgget(key_t key, int msgflg);
-
-/// @brief Used to send messages.
-/// @param msqid the message queue identifier.
-/// @param msgp points to a used-defined msgbuf.
-/// @param msgsz specifies the size in bytes of mtext.
-/// @param msgflg specifies the action to be taken in case of specific events.
-/// @return 0 on success, -1 on failure and errno is set to indicate the error.
-int sys_msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);
-
-/// @brief Used to receive messages.
-/// @param msqid the message queue identifier.
-/// @param msgp points to a used-defined msgbuf.
-/// @param msgsz specifies the size in bytes of mtext.
-/// @param msgtyp specifies the type of message requested, as follows:
-/// - msgtyp == 0: the first message on the queue is received.
-/// - msgtyp  > 0: the first message of type, msgtyp, is received.
-/// - msgtyp  < 0: the first message of the lowest type that is less than or
-///                equal to the absolute value of msgtyp is received.
-/// @param msgflg specifies the action to be taken in case of specific events.
-/// @return the number of bytes actually copied on success, -1 on failure and
-/// errno is set to indicate the error.
-ssize_t sys_msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, int msgflg);
-
-/// @brief Message queue control operations.
-/// @param msqid the message queue identifier.
-/// @param cmd The command to perform.
-/// @param buf used with IPC_STAT and IPC_SET.
-/// @return 0 on success, -1 on failure and errno is set to indicate the error.
-int sys_msgctl(int msqid, int cmd, struct msqid_ds *buf);
-
-#else
-
 /// @brief Get a System V message queue identifier.
 /// @param key can be used either to obtain the identifier of a previously
 /// created message queue, or to create a new set.
@@ -144,5 +99,3 @@ ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, int msgflg);
 /// @param buf used with IPC_STAT and IPC_SET.
 /// @return 0 on success, -1 on failure and errno is set to indicate the error.
 int msgctl(int msqid, int cmd, struct msqid_ds *buf);
-
-#endif

libc/inc/sys/sem.h

@@ -26,8 +26,9 @@
 #define SEM_STAT 18 ///< Return a semid_ds structure.
 #define SEM_INFO 19 ///< Return a seminfo structure.
 
-/// }@
+/// @}
 
+/// @brief Defines the maximum number of semaphores in a semaphore set.
 #define SEM_SET_MAX 256
 
 /// @brief Optional argument for semctl() function
@@ -76,38 +77,6 @@ struct sembuf {
     short sem_flg;
 };
 
-#ifdef __KERNEL__
-
-/// @brief Initializes the semaphore system.
-/// @return 0 on success, 1 on failure.
-int sem_init(void);
-
-/// @brief Get a System V semaphore set identifier.
-/// @param key can be used either to obtain the identifier of a previously
-/// created semaphore set, or to create a new set.
-/// @param nsems number of semaphores.
-/// @param semflg controls the behaviour of the function.
-/// @return the semaphore set identifier, -1 on failure, and errno is set to
-/// indicate the error.
-long sys_semget(key_t key, int nsems, int semflg);
-
-/// @brief Performs operations on selected semaphores in the set.
-/// @param semid the semaphore set identifier.
-/// @param sops specifies operations to be performed on single semaphores.
-/// @param nsops number of operations.
-/// @return 0 on success, -1 on failure and errno is set to indicate the error.
-long sys_semop(int semid, struct sembuf *sops, unsigned nsops);
-
-/// @brief Performs control operations on a semaphore set.
-/// @param semid the semaphore set identifier.
-/// @param semnum the n-th semaphore of the set on which we perform the operations.
-/// @param cmd the command to perform.
-/// @param arg
-/// @return 0 on success, -1 on failure and errno is set to indicate the error.
-long sys_semctl(int semid, int semnum, int cmd, union semun *arg);
-
-#else
-
 /// @brief Get a System V semaphore set identifier.
 /// @param key can be used either to obtain the identifier of a previously
 /// created semaphore set, or to create a new set.
@@ -131,5 +100,3 @@ long semop(int semid, struct sembuf *sops, unsigned nsops);
 /// @param arg
 /// @return 0 on success, -1 on failure and errno is set to indicate the error.
 long semctl(int semid, int semnum, int cmd, union semun *arg);
-
-#endif

libc/inc/sys/shm.h

@@ -86,47 +86,6 @@ struct shmid_ds {
 #define SHM_REMAP  040000  ///< Take-over region on attach.
 #define SHM_EXEC   0100000 ///< Execution access.
 
-#ifdef __KERNEL__
-
-/// @brief Initializes the shared memory.
-/// @return 0 on success, 1 on failure.
-int shm_init(void);
-
-/// @brief Get a System V shared memory identifier.
-/// @param key can be used either to obtain the identifier of a previously
-/// created shared memory, or to create a new one.
-/// @param size of the shared memory, rounded up to a multiple of PAGE_SIZE.
-/// @param shmflg controls the behaviour of the function.
-/// @return the shared memory identifier, -1 on failure, and errno is set to
-/// indicate the error.
-long sys_shmget(key_t key, size_t size, int shmflg);
-
-/// @brief Attaches the shared memory segment identified by shmid to the address
-/// space of the calling process.
-/// @param shmid the shared memory identifier.
-/// @param shmaddr the attaching address.
-/// @param shmflg controls the behaviour of the function.
-/// @return returns the address of the attached shared memory segment; on error
-/// (void *) -1 is returned, and errno is set to indicate the error.
-void *sys_shmat(int shmid, const void *shmaddr, int shmflg);
-
-/// @brief Detaches the shared memory segment located at the address specified
-/// by shmaddr from the address space of the calling process
-/// @param shmaddr the address of the shared memory segment.
-/// @return 0 on success, -1 on failure and errno is set to indicate the error.
-long sys_shmdt(const void *shmaddr);
-
-/// @brief Performs the control operation specified by cmd on the shared memory
-/// segment whose identifier is given in shmid.
-/// @param shmid the shared memory identifier.
-/// @param cmd the command to perform.
-/// @param buf is a pointer to a shmid_ds structure.
-/// @return a non-negative value basedon on the requested operation, -1 on
-/// failure and errno is set to indicate the error.
-long sys_shmctl(int shmid, int cmd, struct shmid_ds *buf);
-
-#else
-
 /// @brief Get a System V shared memory identifier.
 /// @param key can be used either to obtain the identifier of a previously
 /// created shared memory, or to create a new one.
@@ -159,5 +118,3 @@ long shmdt(const void *shmaddr);
 /// @return a non-negative value basedon on the requested operation, -1 on
 /// failure and errno is set to indicate the error.
 long shmctl(int shmid, int cmd, struct shmid_ds *buf);
-
-#endif

libc/src/crypt/sha256.c

@@ -157,12 +157,6 @@ static inline void __sha256_transform(SHA256_ctx_t *ctx, const uint8_t data[])
     ctx->state[7] += h;
 }
 
-/// @brief Converts a byte array into its hexadecimal string representation.
-/// @param src Pointer to the source byte array.
-/// @param src_length Length of the source byte array.
-/// @param out Pointer to the output buffer for the hexadecimal string.
-/// @param out_length Length of the output buffer (must be at least 2 * src_length + 1).
-/// @details The output string will be null-terminated if the buffer is large enough.
 void sha256_bytes_to_hex(uint8_t *src, size_t src_length, char *out, size_t out_length)
 {
     // Check if the output buffer is large enough to hold the hex string