shell.c

/*
 * shell.c
 * 一个教学用的迷你 Shell（tiny shell, tsh）程序骨架。
 *
 * 这个文件是什么：
 * 1. 它不是完整的 bash/zsh，而是操作系统课程里常见的“简化版命令解释器”。
 * 2. 它的重点不是做复杂命令功能，而是练习进程、信号、前后台作业控制。
 * 3. 文件里已经给了大量辅助函数，核心逻辑需要在几个关键函数中自己实现。
 *
 * 这个文件要做什么：
 * 1. 读取用户输入的一行命令。
 * 2. 解析命令和参数。
 * 3. 执行内置命令，例如 quit、jobs、bg、fg。
 * 4. 对普通程序创建子进程并执行。
 * 5. 维护一个作业表，记录哪些任务在前台、后台、暂停中。
 * 6. 处理 Ctrl-C、Ctrl-Z、子进程退出等信号。
 *
 * 为什么要这么做：
 * 1. shell 的本质就是“解释命令 + 管理进程”。
 * 2. 前后台作业控制是理解 Unix 进程模型和信号机制的经典练习。
 * 3. 通过 jobs 表来跟踪任务，shell 才能支持 jobs / fg / bg 这类命令。
 *
 * 当前文件状态：
 * 1. 这是实验骨架，不是完整实现。
 * 2. eval、waitfg、几个信号处理函数目前还是空的。
 * 3. 下面的中文注释主要帮助你先看懂“这个文件是什么、要做什么、为什么这样做”。
 *
 * Name: Weihang Lv
 * Date: 26/5/9
 */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <signal.h>
#include <sys/types.h>
#include <sys/wait.h>
#include <errno.h>

/* 固定上限：控制命令长度、参数数量、作业数量 */
#define MAXLINE    1024   /* max line size */
#define MAXARGS     128   /* max args on a command line */
#define MAXJOBS      16   /* max jobs at any point in time */
#define MAXJID    1<<16   /* max job ID */

/* 作业状态：shell 用它表示一个任务当前处于什么阶段 */
#define UNDEF 0 /* undefined */
#define FG 1    /* running in foreground */
#define BG 2    /* running in background */
#define ST 3    /* stopped */

/*
 * 作业状态说明：
 * FG: 前台运行
 * BG: 后台运行
 * ST: 暂停
 *
 * 常见状态迁移：
 * FG -> ST : 用户按 Ctrl-Z
 * ST -> FG : 执行 fg
 * ST -> BG : 执行 bg
 * BG -> FG : 执行 fg
 *
 * 关键限制：
 * 同一时刻最多只能有一个前台作业。
 */

/* 全局变量：shell 在运行期间持续依赖这些状态 */
extern char **environ;      /* libc 提供的环境变量表 */
char prompt[] = "tsh> ";    /* shell 提示符，测试通常依赖它 */
int verbose = 0;            /* 调试开关，为 1 时打印更多信息 */
int nextjid = 1;            /* 下一个可分配的作业 id */
char sbuf[MAXLINE];         /* 预留的字符串缓冲区 */

/*
 * job_t 表示一个被 shell 管理的作业。
 * shell 不只是“运行命令”，还要记住这个命令对应的进程和状态，
 * 这样后续才能实现 jobs、bg、fg 等控制。
 */
struct job_t {
    pid_t pid;              /* 进程 id：内核层面真正标识进程 */
    int jid;                /* 作业 id：给用户看的编号，如 [1] [2] */
    int state;              /* UNDEF / BG / FG / ST */
    char cmdline[MAXLINE];  /* 启动该作业时的原始命令行 */
};
struct job_t jobs[MAXJOBS]; /* 全局作业表 */
/* 全局变量结束 */


/* 函数声明 */

/* 这些是实验中需要重点实现的核心函数 */
void eval(char *cmdline);
int builtin_cmd(char **argv);
void do_bgfg(char **argv);
void waitfg(pid_t pid);

void sigchld_handler(int sig);
void sigtstp_handler(int sig);
void sigint_handler(int sig);

/* 这些是已经提供好的辅助函数 */
int parseline(const char *cmdline, char **argv);
void sigquit_handler(int sig);

void clearjob(struct job_t *job);
void initjobs(struct job_t *jobs);
int maxjid(struct job_t *jobs);
int addjob(struct job_t *jobs, pid_t pid, int state, char *cmdline);
int deletejob(struct job_t *jobs, pid_t pid);
pid_t fgpid(struct job_t *jobs);
struct job_t *getjobpid(struct job_t *jobs, pid_t pid);
struct job_t *getjobjid(struct job_t *jobs, int jid);
int pid2jid(pid_t pid);
void listjobs(struct job_t *jobs);

void usage(void);
void unix_error(char *msg);
void app_error(char *msg);
typedef void handler_t(int);
handler_t *Signal(int signum, handler_t *handler);

/*
 * main - shell 主函数
 *
 * 主流程：
 * 1. 处理 shell 自己的启动参数
 * 2. 注册信号处理函数
 * 3. 初始化作业表
 * 4. 进入循环：打印提示符 -> 读输入 -> 调 eval 执行
 */
int main(int argc, char **argv)
{
    char c;
    char cmdline[MAXLINE];
    int emit_prompt = 1; /* 默认打印提示符 */

    /*
     * 把 stderr 重定向到 stdout。
     * 这样实验驱动程序只读标准输出，也能拿到错误信息。
     */
    dup2(1, 2);

    /* 解析 shell 程序自己的命令行参数 */
    while ((c = getopt(argc, argv, "hvp")) != EOF) {
        switch (c) {
        case 'h':             /* 打印帮助信息 */
            usage();
            break;
        case 'v':             /* 打开调试输出 */
            verbose = 1;
            break;
        case 'p':             /* 不打印提示符，便于自动化测试 */
            emit_prompt = 0;
            break;
        default:
            usage();
        }
    }

    /* 注册信号处理函数 */

    /*
     * 这三个信号和作业控制最相关：
     * SIGINT  : Ctrl-C，通常用于终止前台作业
     * SIGTSTP : Ctrl-Z，通常用于暂停前台作业
     * SIGCHLD : 子进程状态变化时通知父进程
     */
    Signal(SIGINT,  sigint_handler);   /* ctrl-c */
    Signal(SIGTSTP, sigtstp_handler);  /* ctrl-z */
    Signal(SIGCHLD, sigchld_handler);  /* 子进程结束或停止 */

    /* 供测试驱动程序优雅结束 shell */
    Signal(SIGQUIT, sigquit_handler);

    /* 初始化作业表，把所有槽位清空 */
    initjobs(jobs);

    /* shell 核心循环：不断读取和执行命令 */
    while (1) {

        /* 读取一行命令 */
        if (emit_prompt) {
            printf("%s", prompt);
            fflush(stdout);
        }
        if ((fgets(cmdline, MAXLINE, stdin) == NULL) && ferror(stdin))
            app_error("fgets error");
        if (feof(stdin)) { /* Ctrl-D，表示输入结束 */
            fflush(stdout);
            exit(0);
        }

        /* 交给 eval 解析并执行这行命令 */
        eval(cmdline);
        fflush(stdout);
        fflush(stdout);
    }

    exit(0); /* 正常情况下不会走到这里 */
}

/*
 * eval - 解释并执行用户刚输入的一行命令
 *
 * 这是整个 shell 的“调度中心”，通常要负责：
 * 1. 调 parseline，把字符串拆成 argv 参数数组
 * 2. 判断是否是内置命令
 * 3. 如果不是，就 fork 子进程
 * 4. 子进程里 exec 外部程序
 * 5. 父进程把新任务登记到 jobs 表
 * 6. 前台任务等待结束，后台任务直接返回提示符
 *
 * 为什么这里最关键：
 * 因为 shell 的核心功能几乎都汇总在这里，它连接了解析、执行、进程管理和作业管理。
 *
 * 为什么常常要给子进程设置新的进程组：
 * shell 自己不应该在 Ctrl-C / Ctrl-Z 时被误伤，
 * 所以通常要把子进程从 shell 所在进程组里分离出来，再由 shell 决定把信号转发给谁。
 */
void eval(char *cmdline)
{
    return;
}

/*
 * parseline - 解析命令行，构造 argv 参数数组
 *
 * 主要行为：
 * 1. 按空格拆分参数
 * 2. 单引号包起来的内容视为一个整体参数
 * 3. 若最后有 &，说明该命令应在后台运行
 *
 * 返回值含义：
 * 1 表示后台作业
 * 0 表示前台作业
 */
int parseline(const char *cmdline, char **argv)
{
    static char array[MAXLINE]; /* 保存命令行副本，避免直接改原串 */
    char *buf = array;          /* 遍历字符串的工作指针 */
    char *delim;                /* 当前找到的分隔符 */
    int argc;                   /* 参数数量 */
    int bg;                     /* 是否后台运行 */

    strcpy(buf, cmdline);
    buf[strlen(buf)-1] = ' ';  /* 把结尾换行符替换成空格，便于统一处理 */
    while (*buf && (*buf == ' ')) /* 跳过开头的空格 */
        buf++;

    /* 逐步构造 argv[] */
    argc = 0;
    if (*buf == '\'') {
        buf++;
        delim = strchr(buf, '\'');
    }
    else {
        delim = strchr(buf, ' ');
    }

    while (delim) {
        argv[argc++] = buf;
        *delim = '\0';
        buf = delim + 1;
        while (*buf && (*buf == ' ')) /* 跳过连续空格 */
               buf++;

        if (*buf == '\'') {
            buf++;
            delim = strchr(buf, '\'');
        }
        else {
            delim = strchr(buf, ' ');
        }
    }
    argv[argc] = NULL;

    if (argc == 0)  /* 空行直接忽略 */
        return 1;

    /* 最后一个参数如果是 &，说明要后台运行；并将其从参数表里删掉 */
    if ((bg = (*argv[argc-1] == '&')) != 0) {
        argv[--argc] = NULL;
    }
    return bg;
}

/*
 * builtin_cmd - 检查并执行内置命令
 *
 * 为什么内置命令需要在这里直接处理，而不是都 fork 出去：
 * 1. quit 会结束 shell 自己，必须由父进程执行
 * 2. jobs 需要读取 shell 内部维护的作业表
 * 3. bg / fg 需要直接修改作业状态
 *
 * 返回值：
 * 1 表示已经处理完
 * 0 表示不是内置命令，后续应走 fork/exec 流程
 */
int builtin_cmd(char **argv)
{
    if (argv[0] == NULL) {
        return 0; /* 空命令，没有可执行内容 */
    }

    /* quit：退出 shell */
    if (!strcmp(argv[0], "quit")) {
        exit(0);
    }

    /* jobs：打印当前作业列表 */
    if (!strcmp(argv[0], "jobs")) {
        listjobs(jobs);
        return 1;
    }

    /* bg / fg：切换作业到后台或前台 */
    if (!strcmp(argv[0], "bg") || !strcmp(argv[0], "fg")) {
        do_bgfg(argv);
        return 1;
    }

    /* 单独输入 & 没有意义，直接忽略 */
    if (!strcmp(argv[0], "&")) {
        return 1;
    }

    return 0;     /* 不是内置命令 */
}

/*
 * do_bgfg - 执行内置命令 bg / fg
 *
 * 它的典型职责：
 * 1. 分辨用户给的是 pid 还是 %jid
 * 2. 在作业表中找到对应任务
 * 3. 如果是 bg，就让任务在后台继续执行
 * 4. 如果是 fg，就把任务切回前台并等待
 *
 * 为什么单独拆函数：
 * quit/jobs 的逻辑比较简单，
 * 但 bg/fg 涉及作业查找、状态切换、信号发送，复杂度更高，拆出来更清楚。
 */
void do_bgfg(char **argv)
{
    struct job_t *job;
    int pid;
    pid_t pgid;
    char *id = argv[1];
    if(id == NULL)
        return;
    if(id[0] == '%')
    {
        job = getjobjid(jobs, atoi(id+1));
        if(job == NULL)
        {
            printf("No job with id %s\n", id+1);
            return;
        }
    }
    else if(isdigit(id[0])){
        job = getjobpid(jobs, atoi(id));
        if(job == NULL)
        {
            printf("No process with id %s\n", id);
            return;
        }
    }
    else
    {
        printf("Invalid job id or pid\n");
        return;
    }
    if (kill(-(job->pid), SIGCONT) < 0) {
        unix_error("kill (sigcont) error");
    }
    if(!strcmp(argv[0],"bg"))
    {
        job->state = BG;
        printf("Job [%d] (%d) is running in background\n", job->jid, job->pid);
    }
    else if(!strcmp(argv[0],"fg"))
    {
        job->state = FG;
        printf("Job [%d] (%d) is running in foreground\n", job->jid, job->pid);
        waitfg(job->pid);
    }
}

/*
 * waitfg - 阻塞等待某个 pid 不再处于前台
 *
 * 为什么需要它：
 * 前台命令执行时，shell 不应该立刻返回提示符；
 * 否则用户会在前一个命令还没结束时，误以为 shell 已经空闲了。
 *
 * 常见实现方式：
 * 持续检查 fgpid(jobs) 是否仍然等于目标 pid，
 * 直到该作业结束或状态不再是前台。
 */
void waitfg(pid_t pid)
{
    return;
}

/*****************
 * Signal handlers
 *****************/

/*
 * sigchld_handler - 处理 SIGCHLD
 *
 * 触发场景：
 * 1. 子进程正常退出
 * 2. 子进程被信号终止
 * 3. 子进程被暂停
 *
 * 为什么必须处理：
 * 1. 不回收子进程就会产生僵尸进程
 * 2. shell 需要同步更新 jobs 表，知道哪些作业已经结束或暂停
 *
 * 典型写法：
 * 使用 waitpid(-1, &status, WNOHANG | WUNTRACED) 循环回收所有状态变化的子进程。
 */
void sigchld_handler(int sig)
{
    return;
}

/*
 * sigint_handler - 处理 Ctrl-C 触发的 SIGINT
 *
 * 目标：
 * 不终止 shell 本身，而是把 SIGINT 转发给当前前台作业。
 * 这样用户按 Ctrl-C 时，结束的是正在运行的前台命令。
 */
void sigint_handler(int sig)
{
    return;
}

/*
 * sigtstp_handler - 处理 Ctrl-Z 触发的 SIGTSTP
 *
 * 目标：
 * 不暂停 shell 本身，而是暂停当前前台作业。
 * 暂停后的作业状态一般要变成 ST，后续可以再通过 bg / fg 恢复。
 */
void sigtstp_handler(int sig)
{
    return;
}

/*********************
 * End signal handlers
 *********************/

/***********************************************
 * Helper routines that manipulate the job list
 **********************************************/

/* clearjob - 清空一个作业槽位，表示该位置当前没有任务 */
void clearjob(struct job_t *job) {
    job->pid = 0;
    job->jid = 0;
    job->state = UNDEF;
    job->cmdline[0] = '\0';
}

/* initjobs - 初始化整个作业表 */
void initjobs(struct job_t *jobs) {
    int i;

    for (i = 0; i < MAXJOBS; i++)
        clearjob(&jobs[i]);
}

/* maxjid - 找出当前作业表里最大的 jid */
int maxjid(struct job_t *jobs)
{
    int i, max=0;

    for (i = 0; i < MAXJOBS; i++)
        if (jobs[i].jid > max)
            max = jobs[i].jid;
    return max;
}

/*
 * addjob - 向作业表中登记一个新作业
 *
 * 为什么 fork 后还要做这一步：
 * 因为 shell 后面还要支持 jobs 查询、fg/bg 切换、信号转发，
 * 所以必须把新任务记录下来。
 */
int addjob(struct job_t *jobs, pid_t pid, int state, char *cmdline)
{
    int i;

    if (pid < 1)
        return 0;

    for (i = 0; i < MAXJOBS; i++) {
        if (jobs[i].pid == 0) {
            jobs[i].pid = pid;
            jobs[i].state = state;
            jobs[i].jid = nextjid++;
            if (nextjid > MAXJOBS)
                nextjid = 1;
            strcpy(jobs[i].cmdline, cmdline);
            if(verbose){
                printf("Added job [%d] %d %s\n", jobs[i].jid, jobs[i].pid, jobs[i].cmdline);
            }
            return 1;
        }
    }
    printf("Tried to create too many jobs\n");
    return 0;
}

/* deletejob - 按 pid 从作业表里删除一个已经结束的作业 */
int deletejob(struct job_t *jobs, pid_t pid)
{
    int i;

    if (pid < 1)
        return 0;

    for (i = 0; i < MAXJOBS; i++) {
        if (jobs[i].pid == pid) {
            clearjob(&jobs[i]);
            nextjid = maxjid(jobs)+1;
            return 1;
        }
    }
    return 0;
}

/* fgpid - 返回当前前台作业的 pid；如果没有则返回 0 */
pid_t fgpid(struct job_t *jobs) {
    int i;

    for (i = 0; i < MAXJOBS; i++)
        if (jobs[i].state == FG)
            return jobs[i].pid;
    return 0;
}

/* getjobpid - 通过 pid 在作业表中查找任务 */
struct job_t *getjobpid(struct job_t *jobs, pid_t pid) {
    int i;

    if (pid < 1)
        return NULL;
    for (i = 0; i < MAXJOBS; i++)
        if (jobs[i].pid == pid)
            return &jobs[i];
    return NULL;
}

/* getjobjid - 通过 jid 在作业表中查找任务 */
struct job_t *getjobjid(struct job_t *jobs, int jid)
{
    int i;

    if (jid < 1)
        return NULL;
    for (i = 0; i < MAXJOBS; i++)
        if (jobs[i].jid == jid)
            return &jobs[i];
    return NULL;
}

/* pid2jid - 把系统进程号 pid 转成 shell 展示用的作业号 jid */
int pid2jid(pid_t pid)
{
    int i;

    if (pid < 1)
        return 0;
    for (i = 0; i < MAXJOBS; i++)
        if (jobs[i].pid == pid) {
            return jobs[i].jid;
        }
    return 0;
}

/*
 * listjobs - 打印当前作业列表
 *
 * 这是 jobs 内置命令真正调用的底层函数。
 * 输出格式大致为：[jid] (pid) 状态 命令行
 */
void listjobs(struct job_t *jobs)
{
    int i;

    for (i = 0; i < MAXJOBS; i++) {
        if (jobs[i].pid != 0) {
            printf("[%d] (%d) ", jobs[i].jid, jobs[i].pid);
            switch (jobs[i].state) {
                case BG:
                    printf("Running ");
                    break;
                case FG:
                    printf("Foreground ");
                    break;
                case ST:
                    printf("Stopped ");
                    break;
                default:
                    printf("listjobs: Internal error: job[%d].state=%d ",
                           i, jobs[i].state);
            }
            printf("%s", jobs[i].cmdline);
        }
    }
}
/******************************
 * end job list helper routines
 ******************************/


/***********************
 * Other helper routines
 ***********************/

/*
 * usage - 打印 shell 程序自身的帮助信息
 */
void usage(void)
{
    printf("Usage: shell [-hvp]\n");
    printf("   -h   print this message\n");
    printf("   -v   print additional diagnostic information\n");
    printf("   -p   do not emit a command prompt\n");
    exit(1);
}

/*
 * unix_error - 打印系统调用错误并退出
 *
 * 用于 fork、waitpid、sigaction 等系统调用出错时快速报错。
 */
void unix_error(char *msg)
{
    fprintf(stdout, "%s: %s\n", msg, strerror(errno));
    exit(1);
}

/*
 * app_error - 打印程序自身错误并退出
 *
 * 和 unix_error 的区别在于，这里更适合处理应用逻辑层面的错误。
 */
void app_error(char *msg)
{
    fprintf(stdout, "%s\n", msg);
    exit(1);
}

/*
 * Signal - 对 sigaction 的简单封装
 *
 * 这样做的好处：
 * 1. 统一注册信号处理函数的写法
 * 2. 统一错误处理
 * 3. 默认启用 SA_RESTART，减少信号打断系统调用带来的麻烦
 */
handler_t *Signal(int signum, handler_t *handler)
{
    struct sigaction action, old_action;

    action.sa_handler = handler;
    sigemptyset(&action.sa_mask); /* 处理该信号时，屏蔽同类信号 */
    action.sa_flags = SA_RESTART; /* 若可行，被中断的系统调用自动重启 */

    if (sigaction(signum, &action, &old_action) < 0)
        unix_error("Signal error");
    return (old_action.sa_handler);
}

/*
 * sigquit_handler - 供测试驱动程序优雅结束 shell
 */
void sigquit_handler(int sig)
{
    printf("Terminating after receipt of SIGQUIT signal\n");
    exit(1);
}