CST(Crypto Systems Toolkit) 7.1学习笔记-chapter5

5.用CST编程的基本原则
5.1使用头文件
使用前必须包括头文件 #include <cstlib.h>,
bsapi:包含加密，解密，标记，检验等接口
hash:包含一些hash函数
prng:包含伪随机数产生
ut:CST常用功能函数
5.2通用数据类型
u8:unsigned char
u32:unsigned long
ut_mblk:内存数据块
typedef struct
{
u8    *data;数据本身
size_t size;数据的大小
size_t used;可以存放在ut_mblk中的最大数据量
}ut_mblk;
说明：1,使用这个结构来传递二进制数据如keys,parameters,vectors;
2,分配内存块使用ut_new_mblk,释放用ut_dispose_mblk;
3,也可以使用ut_new_mem和ut_dispose_mem来为各个字段分配和释放内存。
ut_mblk_list:内存块链表
typedef struct ut_mblk_list_s *ut_mblk_list;
struct ut_mblk_list_s
{
ut_mblk_list prev;
ut_mblk_list next;
ut_mblk block;
};
说明：1,可以使用它来传递巨大的数据;
2,创建节点用ut_new_list,释放用ut_dispose_list;
3,CST还提供了一些函数来操作这个list,如：ut_copy_list_item_after,ut_copy_list_item_before...
5.3,使用ut_setflags和ut_init初始化程序
程序一开始包含cstlib.h后，首先调用ut_setflags和ut_init来初始化程序。它们做了下面一些工作（stderr available, determines the threadingmodel, initialises memory checks, error logging）。
5.3.1,ut_setflags
它使用ORed-together标志来告诉ut_init哪个配置属性被打开或关闭。它的语法是：
u32 rval = ut_setflags(u32 ORed_flags);

flags:
CSTFLAGS_USESTDERR:告诉内部函数stderr是可用的
CSTFLAGS_MULTITHREADED:在所有的操作系统中，在CST里，打开了多线程和临界区保护。
CSTFLAGS_MUTEX_PTHREAD,CSTFLAGS_MUTEX_SYSV:默认是前者。

说明：1,使用ut_getflags来得到哪个标志被设置
2,ut_setflags成功返回0,失败返回不能设置的标志。
5.3.2,ut_init 在程序中仅能调用一次
语法是：
void ut_init(const char *appname, const char *usage, const char *logfile, FILE *logstream);
更好的使用方法：
#ifndef NDEBUE /*if in debug mode */
ut_init("myapp","just run it!","mylogfile", stderr);
#else /*debug/ not debug*/
ut_init(0,0,0,0);
#endif

调试状态：错误信息被写入mylogfile并且同时输出到stderr,所有的错误信息还加上前缀myapp.
发布状态：所有错误日志被关闭。
5.4,用ut_logX来错误记录或者logstream
语法：
ut_logX(errnum, action, format [, args]);
X:是一个格式化字串时参数的个数
errnum:如果为0,无错误;如果非0,那么错误信息被显示，并且被拷贝到ut_errno并且被设置为0.
action:则为下面的值
typedef enum 
{
  UT_ACONTINUE = -2, /* Report message and continue execution */
  UT_AABORT,         /* Core dump if possible, else EXIT_FAIL */
  UT_AXOK,           /* Exit, successful termination */
  UT_AXFAIL,         /* Exit, general internal error failure */
  UT_AXFILE,         /* Exit, file-related problem */
  UT_AXMEMORY,       /* Exit, memory failure */
  UT_AXTEST,         /* Exit, failed test (or assert) */
  UT_AXARGS,         /* Exit, bad command-line arguments */
  UT_AXABORT,        /* Exit, user abort request */
  UT_AXINPUT,        /* Exit, bad input (user or file) */
  UT_AXPANIC,        /* Exit, something bad happened */
  UT_AXNO = 127      /* Exit, `false' for apps returning true/false 
                      * answers */
} ut_action;

例子：
1, if(!(fp = fopen("datafile", "rb") ))
   ut_log0(0UL, UT_AXFILE, "couldn't open data file") ;
   2, if (!(fp = fopen ("datafile", "rb") )) 
   {
   ut_log1(0UL, UT_ACONTINUE, "couldn't open file %s", "datafile") ;
  goto handle_file_failure;
}
5.5,用ut_shutdown来结束应用程序,在程序中仅被调用一次。
5.6,CST提供的I/O
下面的两个函数仅是为了方便起见，CST才提供的，它其实跟CST关系不大。
read_mblk:读文件中数据到ut_mblk
write_mblk:与上相反
5.7,分配和释放内存
CST提供ut_new_mem和ut_dispose_mem来分配和释放内存。