mc.utils提供了常用的公共方法，是多种工具的集合库。

加载方式

lua

local utils = require 'mc.utils'

数据类操作接口说明

`utils.to_hex`

描述

将二进制转化为空格分割的十六进制序列

参数

参数	类型	描述	是否必选
data	string	待转化的二进制	必选

空格分割的十六进制序列，类型为string

异常

示例

lua

local utils = require 'mc.utils'
local t1 = '\x61\x70\x70\x6C\x65\x62\x61\x6E\x61\x6E\x61\x63\x61\x74\x64\x6F\x67'
utils.to_hex(t1)
-- 输出: '61 70 70 6C 65 62 61 6E 61 6E 61 63 61 74 64 6F \n67 '

`utils.calc_checksum`

描述

计算校验和

参数

参数	类型	描述	是否必选
data	string	待计算校验和的字符串	必选

校验和，类型为integer

异常

示例

lua

local utils = require 'mc.utils'
local data = '\x01\x02\x03'
lu.assertEquals(utils.calc_ckecksum(data), 250) -- 校验和

`utils.get_first_nonzero_pos`

描述

获取一个32位无符号整数中第一个非零位的位置

参数

参数	类型	描述	是否必选
mask	integer	32位无符号整数	必选

最低有效位第一个非零位的位置，从0开始计数

异常

示例

lua

local utils = require 'mc.utils'
local pos = utils.get_first_nonzero_pos(0xff00)
lu.assertEquals(pos, 8)

`utils.set_value_with_mask`

描述

将一个32位无符号整数中指定掩码位置的值设置为另一个32位无符号整数

参数

参数	类型	描述	是否必选
mask	integer	掩码	必选
src_data	integer	原始数据值	必选
set_data	integer	用于设置的数据，需要对齐到掩码的有效位	必选

基于掩码修改目标数据的特定位后得到的新数据

异常无

示例

lua

local utils = require 'mc.utils'
local mask_data = utils.set_value_with_mask(0xff00, 0x3456, 0x22)
lu.assertEquals(mask_data, 0x2256)

`utils.get_value_with_mask`

描述

获取一个32位无符号整数中指定掩码位置的值

参数

参数	类型	描述	是否必选
mask	integer	掩码	必选
src_data	integer	原始数据值	必选

原始数据中指定掩码位置的值

异常

示例

lua

local utils = require 'mc.utils'
local mask_data = utils.get_value_with_mask(0xff00, 0x2200)
lu.assertEquals(mask_data, 0x22)

`utils.bus_mask`

描述将二进制中的某些位根据指定的掩码提取出来，并将结果作为一个新二进制返回

参数

参数	类型	描述	是否必选
data	string	字符串	必选
len	integer	数据长度（字节数）	必选
mask	integer	掩码	必选

二进制

异常

示例

lua

local utils = require 'mc.utils'
local mask_data = utils.bus_mask('\x01\x02\x03\x04', 4, 0x1234)
lu.assertEquals(string.unpack('I4', mask_data), 0x9000000)

字符串操作接口说明

`utils.split`

描述

字符串分割

参数

参数	类型	描述	是否必选
data	string	待分割的字符串	必选

字符串表

异常

示例

lua

local utils = require 'mc.utils'
local data = 'apple:banana:cat'
local res = {'apple', 'banana', 'cat'}
lu.assertEquals(utils.split(data, ':'), res)
lu.assertEquals(utils.split("aaaa", '\n'), {"aaaa"})
lu.assertEquals(utils.split("", '\n'), nil)

`utils.ByteTablesToString`

描述

将多个Lua表中的字节数据转换为一个字符串

参数

参数	类型	描述	是否必选
table	table	Lua表，数量可以为多个	必选

转换后的字符串

异常

示例

lua

local utils = require 'mc.utils'
local str = utils.ByteTablesToString(table1, table2)

文件类操作接口说明

`utils.remove_file`

描述

删除文件

参数

参数	类型	描述	是否必选
path	string	待删除文件路径	必选

异常

示例

lua

local utils = require 'mc.utils'
utils.remove_file(path)

`utils.move_file`

描述

移动文件

参数

参数	类型	描述	是否必选
from	string	初始文件路径	必选
to	string	移动后文件路径	必选

异常

示例

lua

local utils = require 'mc.utils'
utils.move_file(from, to)

`utils.copy_file`

描述

拷贝文件

参数

参数	类型	描述	是否必选
src	string	源文件路径	必选
dest	string	拷贝文件路径	必选

拷贝成功返回 true，失败返回 false

异常

示例

lua

local utils = require 'mc.utils'
local is_ok = utils.copy_file(src, dest)

`utils.chmod`

描述

修改文件权限

参数

参数	类型	描述	是否必选
path	string	文件路径	必选
fd_mode	integer	文件权限	必选

成功时返回0，失败时返回-1

异常

示例

lua

local utils = require 'mc.utils'
utils.chmod(path, fd_mode)

`utils.mkdir`

描述

参数

参数	类型	描述	是否必选
path	string	目录路径	必选
fd_mode	integer	目录权限	必选

成功时返回0，失败时返回-1

异常

示例

lua

local utils = require 'mc.utils'
utils.mkdir(path, fd_mode)

`utils.mkdir_with_parents`

描述

创建目录，如果父目录不存在，则同时创建父目录

参数

参数	类型	描述	是否必选
path	string	目录路径	必选
fd_mode	integer	目录权限	必选

成功时返回0，失败时返回-1

异常

示例

lua

local utils = require 'mc.utils'
utils.mkdir_with_parents(path, fd_mode)

`utils.chown`

描述

压缩文件修改文件属主

参数

参数	类型	描述	是否必选
file	string	文件路径	必选
owner	integer	用户ID	必选
group	integer	组ID	必选

成功时返回0，失败时返回-1

异常

示例

lua

local utils = require 'mc.utils'
utils.chown(file, owner, group)

`utils.realpath`

描述

将路径转化为绝对路径

参数

参数	类型	描述	是否必选
filepath	string	文件路径	必选

成功时返回转化后的路径，失败时抛异常

异常

转化失败时，使用luaL_error抛异常，报错提示为"realpath failed"

示例

lua

local utils = require 'mc.utils'
local ok, real_path = pcall(utils.realpath, filepath)

`utils.feof`

描述

判断一个文件是否到达文件末尾

参数

参数	类型	描述	是否必选
file	文件句柄	待判断文件	必选

判断结果，类型为boolean

异常

示例

lua

local utils = require 'mc.utils'
local is_eof = utils.feof(file)

`utils.FileLock`

描述

文件锁，详见flock方法说明

参数

参数	类型	描述
file	string	文件路径

示例

lua

local utils = require 'mc.utils'
-- 共享锁
local lock = utils.FileLock.shared(file)
-- 互斥锁
local lock = utils.FileLock.exclusive(file)
-- 解锁
lock:close()

`utils.flock`

描述

文件锁定。接受一个文件句柄作为参数，并根据传入的参数来执行不同的文件锁定操作。使用 luaL_checkoption 函数来检查传入的第二个参数，并根据参数值选择不同的锁定操作。参数值可以是 shared、unlock 或 exclusive ，分别对应共享锁、解锁和独占锁。如果传入了第三个参数且其值为真，则表示非阻塞锁定

参数

参数	类型	描述	是否必选
file	文件句柄	文件	必选
operation	string	操作类型，可以是`shared`、`unlock` 或 `exclusive`	必选
is_blocking	boolean	是否非阻塞锁定	可选

异常

若接受到无效的文件句柄，将抛异常，报错提示为 "file handle is closed"

示例

lua

-- 以两个参数的情况为例
local utils = require 'mc.utils'
local ok = pcall(utils.flock, file, 'shared')

压缩包操作接口说明

`utils.tar_zip`

描述

压缩文件

参数

参数	类型	描述	是否必选
sourcedir	string	源文件所在目录	必选
sourcefile	string	待压缩文件名	必选
destfile	string	压缩后文件名	必选

异常

示例

lua

local utils = require 'mc.utils'
utils.tar_zip(sourcedir, sourcefile, destfile)

`utils.tar_unzip`

描述

解压文件

参数

参数	类型	描述	是否必选
sourcefile	string	待解压文件路径	必选
destdir	string	解压目标目录	必选

异常

示例

lua

local utils = require 'mc.utils'
utils.tar_unzip(sourcefile, destdir)

`utils.before_unzip_check`

描述

防zip炸弹检查，列出详细的解压后的文件大小和文件名，并做如下校验：
解压后文件总大小判断小于 toobig_size
解压后文件总数量判断小于 toomany_num
文件路径的合法性校验

参数

参数	类型	描述	是否必选
sourcefile	string	待解压文件路径	必选
toobig_size	number	文件总大小上限	必选
toomany_num	integer	文件总数量上限	必选

判断结果，类型为boolean

异常

示例

lua

local utils = require 'mc.utils'
local is_ok = utils.before_unzip_check(sourcefile, toobig_size, toomany_num)

`utils.secure_tar_unzip`

描述

安全解压文件，用于解压gzip、bzip2格式的压缩包，解压文件数量和大小的限制由业务进行输入约束

参数

参数	类型	描述	是否必选
sourcefile	string	待解压文件路径	必选
destdir	string	解压目标目录	必选
toobig_size	number	解压后文件总大小上限	必选
toomany_num	integer	解压后文件总数量上限	必选

解压成功返回 true，失败返回 false

异常

示例

lua

local utils = require 'mc.utils'
utils.secure_tar_unzip(sourcefile, destdir, toobig_size, toomany_num)

`utils.unzip_s`

描述

安全解压文件，用于解压zip格式的压缩包，解压文件数量和大小的限制由业务进行输入约束

参数

参数	类型	描述	是否必选
sourcefile	string	待解压文件路径	必选
destdir	string	解压目标目录	必选
toobig_size	number	解压后文件总大小上限	必选
toomany_num	integer	解压后文件总数量上限	必选

解压成功返回 true，失败返回 false

异常

示例

lua

local utils = require 'mc.utils'
local is_ok = utils.unzip_s(sourcefile, destdir, toobig_size, toomany_num)

时间类操作接口说明

`utils.time_ms`

描述

获取系统启动时间

参数

系统启动时间，单位为毫秒，类型为integer

异常

示例

lua

local utils = require 'mc.utils'
local st = utils.time_ms()

`utils.date_format`

描述

格式化日期，能够将整数或字符串时间戳转换为可读的日期时间字符串

参数

参数	类型	描述	是否必选
src_data	string 或者 integer	时间戳	必选
format	string	日期格式字符串	必选
zone_exist	boolean	是否附加时区字符串	必选

日期时间字符串

异常

示例

lua

local utils = require 'mc.utils'
local time = utils.date_format(Timestamp, '%Y-%m-%d %H:%M:%S', false)

`utils.get_timestamp`

描述

根据日期获取时间戳

参数

参数	类型	描述	是否必选
year	integer	年	必选
month	integer	月	必选
day	integer	日	必选
hour	integer	时	必选
minute	integer	分	必选
second	integer	秒	必选

时间戳，类型为integer

异常

示例

lua

local utils = require 'mc.utils'
utils.get_timestamp(year, month, day, hour, minute, second)

`utils.time`

描述

获取当前系统时间

参数

当前系统时间，类型为包含"tv_sec"和"tv_nsec"两个键的表

异常

示例

lua

local utils = require 'mc.utils'
local current_time = utils.time()

`utils.usleep`

描述

使用C语言的 usleep 函数来实现让当前线程休眠指定的微秒数

参数

参数	类型	描述	是否必选
time	integer	线程休眠指定的微秒数	必选

成功时返回0，失败时返回-1

异常

示例

lua

-- 以休眠 100000 微秒为例
local utils = require 'mc.utils'
utils.usleep(100000)

`utils.msleep`

描述

让当前线程休眠指定毫秒

参数

参数	类型	描述	是否必选
time	integer	线程休眠指定的毫秒数	必选

成功时返回0，失败时返回-1

异常

示例

lua

-- 以休眠 100 毫秒为例
local utils = require 'mc.utils'
utils.sleep(100)

表操作接口说明

`utils.get_table_node`

描述

get_table_node(tb, index, ...)
从表中取数据，中途遇到节点为nil则直接返回nil

参数

参数	类型	描述	是否必选
tb	table	待取数据的表	必选
index	table键，可以为字符串、数字等	数据索引，若有多个索引，将逐层访问嵌套表中的字段	必选

根据索引返回表中数据，例如get_table_node(tb, index1, index2)正常返回tb[index1][index2]，若无该节点则返回nil

异常

示例

lua

local utils = require 'mc.utils'
local data = {'a', 'b', 'c', 'd'}
lu.assertEquals(utils.get_table_node(data, 1), 'a')
lu.assertEquals(utils.get_table_node(data, 5), nil)

`utils.add_table_node`

描述

add_table_node(tb, object, index, ...)
往表里添加数据，遇到父节点为nil则创建父节点

参数

参数	类型	描述	是否必选
tb	table	待添加数据的表	必选
object	可以为字符串、数字等	添加的数据	必选
index	table键，可以为字符串、数字等	数据索引，若有多个索引，将逐层访问嵌套表中的字段	必选

异常

示例

lua

local utils = require 'mc.utils'
local data = {'a', 'b', 'c', 'd'}
local res = {'a', 'e', 'c', 'd'}
utils.add_table_node(data, 'e', 2)
lu.assertEquals(data, res)

`utils.remove_table_node`

描述remove_table_node(tb, index, ...)

从表里删除数据，中途遇到节点为nil则提前返回

参数

参数	类型	描述	是否必选
tb	table	待删除数据的表	必选
index	table键，可以为字符串、数字等	数据索引，若有多个索引，将逐层访问嵌套表中的字段	必选

被删除节点的数据

异常

示例

lua

local utils = require 'mc.utils'
local data = {'a', 'b', 'c', 'd'}
local res = {'a', [3] = 'c', [4] = 'd'}
lu.assertEquals(utils.remove_table_node(data, 2), 'b')
lu.assertEquals(data, res)

`utils.merge_array`

描述

合并数组

参数

参数	类型	描述	是否必选
a	table	待合并数组1	必选
b	table	待合并数组2	必选

合并后的数组

异常

示例

lua

local utils = require 'mc.utils'
local a = {1, 2, 3}
local b = {4, 5}
lu.assertEquals(utils.merge_array(a, b), {1, 2, 3, 4, 5})

`utils.merge_table`

描述

合并表

参数

参数	类型	描述	是否必选
a	table	待合并表1	必选
b	table	待合并表2	必选

合并后的表

异常

示例

lua

local utils = require 'mc.utils'
local a = {"k1" = "v1", "k2" = "v2"}
local b = {"k3" = "v3"}
lu.assertEquals(utils.merge_table(a, b), {"k1" = "v1", "k2" = "v2", "k3" = "v3"})

`utils.array_contains`

描述

判断数组中是否包含元素

参数

参数	类型	描述	是否必选
array	table	数组	必选
element	数字、字符串等Lua类型	元素	必选

判断结果，类型为boolean

异常

示例

lua

local utils = require 'mc.utils'
local data = {1, 2, 3, 4, 5}
lu.assertEquals(utils.array_contains(data, 5), true)
lu.assertEquals(utils.array_contains(data, 6), false)

其他工具接口说明

`utils.convert_number`

描述

将数字从一种类型转换为另一种类型

参数

参数	类型及描述	是否必选
original_type	string	原始类型，若原始类型为 number，则该参数应为'd'
original_value	类型与original_type对应	原始值
converted_type	string	转换后的类型，若转换后的类型为 number，则该参数应为'd'，若转换后的类型为integer，该参数需为 'y'、'n'、'q'、'i'、'u'、'x'、't'中的一种，若转换后的类型为string，该参数为's'，若转换后的类型为boolean，该参数为'b'；

转换后的值，类型与converted_type相对应

异常

示例

lua

local utils = require 'mc.utils'
local num = utils.convert_number(original_type, original_value, converted_type)

`utils.sched_yield`

描述

使当前线程放弃CPU的使用权，以便其它线程有机会执行。通过调用该函数，可以实现线程主动让出CPU的操作，以提高系统的并发性能

参数无

返回无

异常无

示例

lua

local utils = require 'mc.utils'
utils.sched_yield()

`utils.rsyslog_reload_config`

描述

重新加载rsyslog配置文件

参数

异常

示例

lua

local utils = require 'mc.utils'
utils.rsyslog_reload_config()

`utils.decode_xml`

描述

解析xml数据放入表中

参数

参数	类型	描述	是否必选
str	string	xml数据	必选

解析得到的表

异常

示例

lua

local utils = require 'mc.utils'
utils.decode_xml(s)

加载方式 ​

数据类操作接口说明 ​

utils.to_hex ​

utils.calc_checksum ​

utils.get_first_nonzero_pos ​

utils.set_value_with_mask ​

utils.get_value_with_mask ​

utils.bus_mask ​

字符串操作接口说明 ​

utils.split ​

utils.ByteTablesToString ​

文件类操作接口说明 ​

utils.remove_file ​

utils.move_file ​

utils.copy_file ​

utils.chmod ​

utils.mkdir ​

utils.mkdir_with_parents ​

utils.chown ​

utils.realpath ​

utils.feof ​

utils.FileLock ​

utils.flock ​

压缩包操作接口说明 ​

utils.tar_zip ​

utils.tar_unzip ​

utils.before_unzip_check ​

utils.secure_tar_unzip ​

utils.unzip_s ​

时间类操作接口说明 ​

utils.time_ms ​

utils.date_format ​

utils.get_timestamp ​

utils.time ​

utils.usleep ​

utils.msleep ​

表操作接口说明 ​

utils.get_table_node ​

utils.add_table_node ​

utils.remove_table_node ​

utils.merge_array ​

utils.merge_table ​

utils.array_contains ​

其他工具接口说明 ​

utils.convert_number ​

utils.sched_yield ​

utils.rsyslog_reload_config ​

utils.decode_xml ​