Merge pull request #17 from wang904/master

更新了libc api的文档

docs/introduction/intro.md

@@ -1,3 +1,3 @@
 # DragonOS简介
 
-DragonOS龙操作系统（以下简称“DragonOS”）是一个基于x86-64体系结构开发的，基于GPLv2协议开放源代码的64位操作系统。
+DragonOS龙操作系统（以下简称“DragonOS”）是一个基于x86-64体系结构开发的，基于GPLv2协议开放源代码的64位操作系统。

docs/userland/libc/apis/api-list/ctype.md

@@ -0,0 +1,38 @@
+# ctype.h
+## 函数列表（这里只列出已实现的函数）：  
+
+    ``int isprint(int c)`` : 传入一个字符，判断是否可以被输出  
+
+    ``int islower(int c)`` : 传入一个字符，判断是否是小写字母  
+
+    ``int isupper(int c)`` : 传入一个字符，判断是否是大写字母  
+
+    ``int isalpha(int c)`` : 传入一个字符，判断是否是字母  
+
+    ``int isdigit(int c)`` : 传入一个字符，判断是否是数字  
+
+    ``int toupper(int c)`` : 传入一个小写字母字符，返回这个字母的大写形式  
+
+    ``int tolower(int c)`` : 传入一个大写字母字符，返回这个字母的小写形式  
+
+    ``int isspace(int c)``  : 传入一个字符，判断是否是空白字符  
+
+## 宏定义：
+
+    ### 暂无用处  
+
+    ``#define _U 01`` 
+    
+    ``#define _L 02``  
+
+    ``#define _N 04``  
+
+    ``#define _S 010``  
+
+    ``#define _P 020``  
+
+    ``#define _C 040``  
+
+    ``#define _X 0100``  
+
+    ``#define _B 0200`` 

docs/userland/libc/apis/api-list/dirent.md

@@ -0,0 +1,59 @@
+# dirent.h
+## 简介
+    与文件夹有关的头文件。
+
+## 结构体列表：
+
+    ``struct DIR`` : 
+        
+        变量列表：
+
+        ``int fd`` : 文件夹id（不推荐修改）
+
+        ``int buf_pos`` : 文件夹缓冲区指针的位置
+        
+        ``int buf_len`` : 文件夹缓冲区的大小（默认为256）
+    
+    ``struct dirent`` : 
+        
+        变量列表： 
+
+        ``ino_t(see libc/sys/types.h) ino`` : 文件序列号（不推荐修改）
+
+        ``off_t d_off`` : dir偏移量（不推荐修改）
+
+        ``unsigned short d_reclen`` : 文件夹中的记录数
+
+        ``unsigned char d_type`` : 目标的类型(有可能是文件，文件夹，磁盘)
+
+        ``char d_name[]`` : 目标的名字
+
+## 函数列表（这里只列出已实现的函数）：
+
+    ``DIR opendir(const char *path)``  
+        
+        传入文件夹的路径，返回文件夹结构体
+    
+    ``int closedir(DIR *dirp)`` 
+
+        传入文件夹结构体，关闭文件夹，释放内存
+
+        若失败，返回-1
+
+    ``dirent readdir(DIR *dir)``
+
+        传入文件夹结构体，读入文件夹里的内容，并打包为dirent结构体返回
+
+## 宏定义：
+
+    文件夹类型：
+
+    ``#define VFS_ATTR_FILE (1UL << 0)``
+    
+    ``#define VFS_ATTR_DIR (1UL << 1)``
+    
+    ``#define VFS_ATTR_DEVICE (1UL << 2)``
+    
+    缓冲区长度的默认值
+    
+    ``#define DIR_BUF_SIZE 256``

docs/userland/libc/apis/api-list/errno.md

@@ -0,0 +1,185 @@
+# errno.h
+
+## 简介：
+
+    共享错误号码
+## 属性：
+
+    ``extern int errno`` : 通用错误代码
+
+## 宏定义（复制自代码，了解即可）：
+
+    #define E2BIG 1            /* 参数列表过长，或者在输出buffer中缺少空间 或者参数比系统内建的最大值要大 Argument list too long.*/
+    
+    #define EACCES 2           /* 访问被拒绝 Permission denied*/ 
+    
+    #define EADDRINUSE 3       /* 地址正在被使用 Address in use.*/
+    
+    #define EADDRNOTAVAIL 4    /* 地址不可用 Address  not available.*/
+    
+    #define EAFNOSUPPORT 5     /* 地址family不支持 Address family not supported.*/
+    
+    #define EAGAIN 6           /* 资源不可用，请重试。 Resource unavailable, try again (may be the same value as [EWOULDBLOCK]).*/
+    
+    #define EALREADY 7         /* 连接已经在处理 Connection already in progress.*/
+    
+    #define EBADF 8            /* 错误的文件描述符 Bad file descriptor.*/
+    
+    #define EBADMSG 9          /* 错误的消息 Bad message.*/
+
+    
+    #define EBUSY 10           /* 设备或资源忙 Device or resource busy.*/
+    
+    #define ECANCELED 11       /* 操作被取消 Operation canceled.*/
+    
+    #define ECHILD 12          /* 没有子进程 No child processes.*/
+    
+    #define ECONNABORTED 13    /* 连接已断开 Connection aborted.*/
+    
+    #define ECONNREFUSED 14    /* 连接被拒绝 Connection refused.*/
+    
+    #define ECONNRESET 15      /* 连接被重置 Connection reset.*/
+    
+    #define EDEADLK 16         /* 资源死锁将要发生 Resource deadlock would occur.*/
+    
+    #define EDESTADDRREQ 17    /* 需要目标地址 Destination address required.*/
+    
+    #define EDOM 18            /* 数学参数超出作用域 Mathematics argument out of domain of function.*/
+    
+    #define EDQUOT 19          /* 保留使用 Reserved*/
+
+
+
+    #define EEXIST 20          /* 文件已存在 File exists.*/
+
+    #define EFAULT 21          /* 错误的地址 Bad address*/
+
+    #define EFBIG 22           /* 文件太大 File too large.*/
+
+    #define EHOSTUNREACH 23    /* 主机不可达 Host is unreachable.*/
+
+    #define EIDRM 24           /* 标志符被移除 Identifier removed.*/
+
+    #define EILSEQ 25          /* 不合法的字符序列 Illegal byte sequence.*/
+
+    #define EINPROGRESS 26     /* 操作正在处理 Operation in progress.*/
+
+    #define EINTR 27           /* 被中断的函数 Interrupted function.*/
+
+    #define EINVAL 28          /* 不可用的参数 Invalid argument.*/
+
+    #define EIO 29             /* I/O错误 I/O error.*/
+
+
+
+    #define EISCONN 30         /* 套接字已连接 Socket is connected.*/
+
+    #define EISDIR 31          /* 是一个目录 Is a directory*/
+
+    #define ELOOP 32           /* 符号链接级别过多 Too many levels of symbolic links.*/
+
+    #define EMFILE 33          /* 文件描述符的值过大 File descriptor value too large.*/
+
+    #define EMLINK 34          /* 链接数过多 Too many links.*/
+
+    #define EMSGSIZE 35        /* 消息过大 Message too large.*/
+
+    #define EMULTIHOP 36       /* 保留使用 Reserved.*/
+
+    #define ENAMETOOLONG 37    /* 文件名过长 Filename too long.*/
+
+    #define ENETDOWN 38        /* 网络已关闭 Network is down.*/
+
+    #define ENETRESET 39       /* 网络连接已断开 Connection aborted by network.*/
+
+    #define ENETUNREACH 40     /* 网络不可达 Network unreachable.*/
+
+    #define ENFILE 41          /* 系统中打开的文件过多 Too many files open in system.*/
+
+    #define ENOBUFS 42         /* 缓冲区空间不足 No buffer space available.*/
+
+    #define ENODATA 43         /* 队列头没有可读取的消息 No message is available on the STREAM head read queue.*/
+
+    #define ENODEV 44          /* 没有指定的设备 No such device.*/
+
+    #define ENOENT 45          /* 没有指定的文件或目录 No such file or directory.*/
+
+    #define ENOEXEC 46         /* 可执行文件格式错误 Executable file format error.*/
+
+    #define ENOLCK 47          /* 没有可用的锁 No locks available.*/
+
+    #define ENOLINK 48         /* 保留 Reserved.*/
+
+
+    #define ENOMEM 49          /* 没有足够的空间 Not enough space.*/
+
+
+    #define ENOMSG 50          /* 没有期待类型的消息 No message of the desired type.*/
+
+    #define ENOPROTOOPT 51     /* 协议不可用 Protocol not available.*/
+
+    #define ENOSPC 52          /* 设备上没有空间 No space left on device.*/
+
+    #define ENOSR 53           /* 没有STREAM资源  No STREAM resources.*/
+
+    #define ENOSTR 54          /* 不是STREAM Not a STREAM*/
+
+    #define ENOSYS 55          /* 功能不支持 Function not supported.*/
+
+    #define ENOTCONN 56        /* 套接字未连接 The socket is not connected.*/
+
+    #define ENOTDIR 57         /* 不是目录 Not a directory.*/
+
+    #define ENOTEMPTY 58       /* 目录非空 Directory not empty.*/
+
+    #define ENOTRECOVERABLE 59 /* 状态不可覆盖 State not recoverable.*/
+
+
+
+    #define ENOTSOCK 60        /* 不是一个套接字 Not a socket.*/
+
+    #define ENOTSUP 61         /* 不被支持 Not supported (may be the same value as [EOPNOTSUPP]).*/
+
+    #define ENOTTY 62          /* 不正确的I/O控制操作 Inappropriate I/O control operation.*/
+
+    #define ENXIO 63           /* 没有这样的设备或地址 No such device or address.*/
+
+    #define EOPNOTSUPP 64      /* 套接字不支持该操作 Operation not supported on socket (may be the same value as [ENOTSUP]).*/
+
+    #define EOVERFLOW 65       /* 数值过大，产生溢出 Value too large to be stored in data type.*/
+
+    #define EOWNERDEAD 66      /* 之前的拥有者挂了 Previous owner died.*/
+
+    #define EPERM 67           /* 操作不被允许 Operation not permitted.*/
+
+    #define EPIPE 68           /* 断开的管道 Broken pipe.*/
+
+    #define EPROTO 69          /* 协议错误 Protocol error.*/
+
+
+
+    #define EPROTONOSUPPORT 70 /* 协议不被支持 Protocol not supported.*/
+
+    #define EPROTOTYPE 71      /* 对于套接字而言，错误的协议 Protocol wrong type for socket.*/
+
+    #define ERANGE 72          /* 结果过大 Result too large.*/
+
+    #define EROFS 73           /* 只读的文件系统 Read-only file system.*/
+
+    #define ESPIPE 74          /* 错误的寻道 Invalid seek.*/
+
+    #define ESRCH 75           /* 没有这样的进程 No such process.*/
+
+    #define ESTALE 76          /* 保留 Reserved.*/
+
+    #define ETIME 77           /* 流式ioctl()超时 Stream ioctl() timeout*/
+
+    #define ETIMEDOUT 78       /* 连接超时 Connection timed out.*/
+
+    #define ETXTBSY 79         /* 文本文件忙 Text file busy.*/
+
+
+
+    #define EWOULDBLOCK 80     /* 操作将被禁止 Operation would block (may be the same value as [EAGAIN]).*/
+
+    #define EXDEV 81           /* 跨设备连接 Cross-device link.*/

docs/userland/libc/apis/api-list/fcntl.md

@@ -0,0 +1,44 @@
+# fcntl.h
+
+## 简介
+
+    文件操作
+## 函数列表：
+
+    ``int open(const char * path,int options, ...)``
+
+    传入文件路径，和文件类型（详细请看下面的宏定义），将文件打开并返回文件id。
+
+## 宏定义（粘贴自代码，了解即可）：
+
+    #define O_RDONLY 00000000 // Open Read-only
+    
+    #define O_WRONLY 00000001 // Open Write-only
+    
+    #define O_RDWR 00000002   // Open read/write
+    
+    #define O_ACCMODE 00000003 // Mask for file access modes
+
+    
+    #define O_CREAT 00000100 // Create file if it does not exist
+    
+    #define O_EXCL 00000200 // Fail if file already exists
+    
+    #define O_NOCTTY 00000400 // Do not assign controlling terminal
+
+    #define O_TRUNC 00001000 // 文件存在且是普通文件，并以O_RDWR或O_WRONLY打开，则它会被清空
+
+    #define O_APPEND 00002000   // 文件指针会被移动到文件末尾
+
+    #define O_NONBLOCK 00004000 // 非阻塞式IO模式
+
+    
+    #define O_EXEC 00010000 // 以仅执行的方式打开（非目录文件）
+    
+    #define O_SEARCH 00020000   // Open the directory for search only
+    
+    #define O_DIRECTORY 00040000 // 打开的必须是一个目录
+    
+    #define O_NOFOLLOW 00100000 // Do not follow symbolic links
+
+

docs/userland/libc/apis/api-list/math.md

@@ -0,0 +1,21 @@
+# math.h
+
+## 简介：
+
+    数学库
+
+## 函数列表：
+
+    ``double fabs(double x)`` : 返回 x 的绝对值
+    
+    ``float fabsf(float x)`` : 返回 x 的绝对值
+
+    ``long double fabsl(long double x)``: 返回 x 的绝对值
+
+    ``double round(double x)`` 四舍五入 x
+
+    ``float roundf(float x)`` 四舍五入 x
+
+    ``long double roundl(long double x)`` 四舍五入 x
+
+    ``int64_t pow(int64_t x,int y)`` 返回 x 的 y 次方 

docs/userland/libc/apis/api-list/printf.md

@@ -0,0 +1,3 @@
+# printf.h
+
+不建议引用，需要 ``printf`` 函数请引用 ``stdio.h`` 

docs/userland/libc/apis/api-list/stddef.md

@@ -0,0 +1,11 @@
+# stddef.h
+
+## 简介： 
+
+    定义了关于指针的常用类型
+
+## 定义：
+
+    ``typedef __PTDIFF_TYPE__ ptrdiff_t``  : 两个指针相减的结果类型
+
+    ``NULL ((void *) 0)`` : 空指针

docs/userland/libc/apis/api-list/stdio.md

@@ -0,0 +1,52 @@
+# stdio.h
+
+## 简介：
+
+    向标准输入输出里操作
+## 函数列表：
+
+    ``int64_t put_string(char *str, uint64_t front_color, uint64_t bg_color)``
+
+        输出字符串（带有前景色，背景色）
+    
+    ``int printf(const char *fmt, ...)``
+        
+        就是正常的 ``printf`` 
+    
+    ``int sprintf(char *buf,const char *fmt,...)```
+
+        就是正常的 ``sprintf``
+    
+    ``int vsprintf(char *buf,const char *fmt,va_list args)``
+
+        格式化，不建议调用，请用 printf 或 sprintf 替代。
+## 宏定义
+
+    ### 字体颜色的宏定义
+
+        ``#define COLOR_WHITE 0x00ffffff  //白``
+
+        ``#define COLOR_BLACK 0x00000000  //黑``
+
+        ``#define COLOR_RED 0x00ff0000    //红``
+
+        ``#define COLOR_ORANGE 0x00ff8000 //橙``
+
+        ``#define COLOR_YELLOW 0x00ffff00 //黄``
+
+        ``#define COLOR_GREEN 0x0000ff00  //绿``
+
+        ``#define COLOR_BLUE 0x000000ff   //蓝``
+
+        ``#define COLOR_INDIGO 0x0000ffff //靛``
+
+        ``#define COLOR_PURPLE 0x008000ff //紫``
+    ### 无需使用
+        
+        ``#define SEEK_SET 0 /* Seek relative to start-of-file */``
+        
+        ``#define SEEK_CUR 1 /* Seek relative to current position */``
+        
+        ``#define SEEK_END 2 /* Seek relative to end-of-file */``
+
+        ``#define SEEK_MAX 3``

docs/userland/libc/apis/api-list/stdlib.md

@@ -0,0 +1,20 @@
+# stdlib.h
+
+## 简介：
+
+    一些常用函数
+## 函数列表：
+
+    ``void *malloc(ssize_t size)`` ： 普通的 ``malloc``
+
+    ``void free(void *ptr)`` : 释放内存
+
+    ``int abs(int x)`` : x 的绝对值
+
+    ``long labs(long x)`` : x 的绝对值
+
+    ``long long llabs(long long x)`` : x 的绝对值
+
+    ``int atoi(const char *str)`` 字符串转数字
+
+    ``void exit(int status)`` : 普通的 ``exit``

docs/userland/libc/apis/api-list/string.md

@@ -0,0 +1,25 @@
+# string.h
+
+## 简介:
+
+    字符串操作
+
+## 函数列表:
+
+    ``size_t strlen(const char *s)`` : 返回字符串长度
+    
+    ``int strcmp(const char *a,const char *b)`` 比较字符串的字典序
+
+    ``char* strncpy(char *dst,const char *src,size_t count)`` 
+
+        拷贝制定字节数的字符串
+
+        dst: 目标地址
+
+        src： 原字符串
+
+        count: 字节数
+    
+    ``char* strcpy(char *dst,const char *src)`` : 复制整个字符串
+
+    ``char* strcat(char *dest,const char* src)`` : 拼接两个字符串

docs/userland/libc/apis/api-list/time.md

@@ -0,0 +1,32 @@
+# time.h
+
+## 简介：
+
+    时间相关
+
+时刻以纳秒为单位
+
+## 结构体：
+
+    ``struct timespec`` : 时间戳
+        
+        ### 变量列表:
+            
+            ``long int tv_sec`` : 秒
+            
+            ``long int tv_nsec`` : 纳秒 
+## 宏定义：
+
+    ``#define CLOCKS_PER_SEC 1000000`` 每一秒有1000000个时刻（纳秒）
+
+## 函数列表：
+
+    ``int nanosleep(const struct timespec *rdtp,struct timespec *rmtp)``
+
+        休眠指定时间
+
+        rdtp ： 指定休眠的时间
+
+        rmtp ： 返回剩余时间
+    
+    ``clock_t clock()`` ： 获得当前系统时间

docs/userland/libc/apis/api-list/unistd.md

@@ -0,0 +1,56 @@
+# unistd.h
+
+## 简介：
+
+    也是一些常用函数
+
+## 函数列表：
+
+    ``int close(int fd)`` ： 关闭文件
+    
+    ``ssize_t read(int fd,void *buf,size_t count)`` : 从文件读取
+        
+        传入文件id，缓冲区，以及字节数
+        
+        返回成功读取的字节数
+    
+    ``ssize_t write(int fd,void const *buf,size_t count)`` ： 写入文件
+
+        传入文件id，缓冲区，字节数
+
+        返回成功写入的字节数
+    
+    ``off_t lseek(int fd,off_t offset,int whence)`` : 调整文件访问位置
+
+        传入文件id，偏移量，调整模式
+
+        返回结束后的文件访问位置
+    
+    ``pid_t fork(void)`` ： fork 当前进程
+
+    ``pid_t vfork(void)`` ： fork 当前进程，与父进程共享 VM,flags,fd
+
+    ``uint64_t brk(uint64_t end_brk)`` : 将堆内存调整为end_brk
+        
+        若end_brk 为 -1，返回堆区域的起始地址
+
+        若end_brk 为 -2，返回堆区域的结束地址
+
+        否则调整堆区的结束地址域，并返回错误码
+    
+    ``void *sbrk(int64_t increment)`` :  
+        
+        将堆内存空间加上offset（注意，该系统调用只应在普通进程中调用，而不能是内核线程）
+
+        increment ： 偏移量
+    
+    ``int64_t chdir(char *dest_path)``
+
+        切换工作目录（传入目录路径）
+
+    ``int execv(const char* path,char * const argv[])`` : 执行文件
+        path ： 路径
+        argv ： 执行参数列表
+    
+    ``extern int usleep(useconds_t usec)`` ： 睡眠usec微秒
+

docs/userland/libc/apis/index.rst

@@ -1,9 +1,21 @@
 API文档
 ====================================
-
 .. toctree::
    :maxdepth: 1
    :caption: 目录
-
-
-[内容待完善]
+   
+   api-list/ctype
+   api-list/dirent
+   api-list/errno
+   api-list/fcntl
+   api-list/math
+   api-list/stdio
+   api-list/printf
+   api-list/stddef
+   api-list/stdlib
+   api-list/string
+   api-list/time
+   api-list/unistd
+   
+这里是所有libc头文件的集合,在代码里可以这样引用:  
+``#include<libc/xxx.h>``