GB/T 32395-2015 信息技术 中文Linux操作系统应用编程接口（API）扩充要求

　　ICS 35. 060 L 74

　　中 华 人 民 共 和 国 国 家 标 准

　　GB/T 32395—2015

　　信息技术 中文 Linux操作系统应用编程

　　接口(API)扩充要求

　　Information technology—Extended requirementsofApplication Programming

　　Interface(API) forChineseLinux operatingsystem

　　2015-12-31发布 2016-07-01实施

　　中华人民共和国国家质量监督检验检疫总局中 国 国 家 标 准 化 管 理 委 员 会

　　发

　　布

　　GB/T 32395—2015

　　GB/T 32395—2015

　　前 言

　　本标准按照 GB/T 1. 1—2009 给出的规则起草 。

　　本标准由全国信息技术标准化技术委员会(SAC/TC28)提出并归 口 。

　　请注意本文件的某些内容可能涉及专利 。本文件的发布机构不承担识别这些专利的责任 。

　　本标准起草单位 : 中标软件有限公司 、工业和信息化部电子工业标准化研究院 、新华科技(南京) 系统软件有限公司 、北京中科红旗软件技术有限公司 、北京赛西科技发展有限责任公司 、北京络威尔软件有限公司 、北京大学(计算机科学技术研究所) 、清华大学 、北京即时俊业软件有限公司 、北京法国电信研发中心有限公司 、太阳计算机系统(中国)有限公司 、苏州开源先锋软件有限公司 。

　　本标准主要起草人 :张东 、苗宗利 、武校田 、张永军 、谢谦 、李祥凯 、吴鹏 、孙廉焘 、韦韬 、陶品 、霍东灵 、陆伯鹰 、张相峰 、滕召智 。

　　信息技术 中文 Linux操作系统应用编程

　　接口(API)扩充要求

　　1 范围

　　本标准规定了中文 Linux操 作 系 统 应 提 供 的 应 用 编 程 接 口 , 包 括 便 利 函 数 库 与 农 历 函 数 库 , 为Linux下应用的开发与部署提供便利 , 以提高 Linux应用程序的可移植性 。

　　本标准适用于 Linux操作系统开发 、应用与维护 。

　　2 规范性引用文件

　　下列文件对于本文件的应用是必不可少的 。凡是注 日期的引用文件 ,仅注 日期的版本适用于本文件 。凡是不注日期的引用文件 ,其最新版本(包括所有的修改单)适用于本文件 。

　　ISO/IEC 23360-1 Liux标 准 集 核 心 规 范 3. 1 第 1 部 分 通 用 规 范 [Linux Standard Base (LSB) core specification3. 1—Part1: Generic specification]

　　RFC822ARPA 的互联网文本消息的格式标准 (Standard for the Formatof ARPA InternetText Messages)

　　桌面入口规范 (Desktop Entry Specification)

　　http://standards.freedesktop. org/desktop-entry-spec/latest/index. html桌面菜单规范 (Desktop Menu Specification)

　　http://www. freedesktop. org/wiki/Specifications/menu-spec基础文件规范 (Base directory Specification)

　　http://www. freedesktop. org/wiki/Specifications/basedir-spec共享 MIME数据库 (shared MIME database)

　　http://www. freedesktop. org/wiki/Specifications/shared-mime-info-spec主题图标规范 (Icon Theme specification)

　　http://www. freedesktop. org/wiki/Specifications/icon-theme-spec最近访问文件规范(The RecentFile specification)

　　http://www. freedesktop. org/wiki/Specifications/recent-file-spec自动启动规范(Autostartspecification)

　　http://www. freedesktop. org/wiki/Specifications/autostart-spec

　　3 术语、定义及缩略语

　　3. 1 术语和定义

　　下列术语和定义适用于本文件 。

　　3. 1. 1

　　动态连接 dynamic linking

　　应用程序开始执行时才实际连接到所需函数库代码上的连接方式 。

　　GB/T 32395—2015

　　3. 1.2

　　共享对象名 shareobjectname (soname)

　　存在于动态连接函数库中 、在函数库构造阶段指定的用于标识自身的符号 ,应用程序编译阶段据此指定需要连接的函数库 ,执行阶段据此实现动态连接 。通过这种机制 , 同一动态连接函数库的多个版本可以在系统上并存 。

　　3. 1.3

　　动态连接器 dynamic linker

　　系统提供的用于实现动态连接的程序 。动态连接器检查应用程序 ,发现所需函数库的共享对象名 ,进而找到函数库的实际存放位置 ,读入内存并实现连接 。

　　3. 1.4

　　桌面条目 Desktop entry

　　符合桌面条目规范 ,其 Type项值为 “Application”,并且以 “.desktop”为结尾命名的文件 。 桌面条目描述了一个菜单项 ,包名称 、图标 , 以及该项被选中时应做什么 。

　　3. 1.5

　　目录条目 Directory entry

　　符合桌面条目规范 ,其 Type项值为“Directory”,并且以“.directory”为结尾命名的文件 。 目录条目描述了一个子菜单的本地化名称和图标 。

　　3. 1.6

　　菜单路径 Menu path

　　通往一个特定菜单的路径 。菜单路径是相对路径 ,不应以字母斜杠(“/”)开始 。一个菜单路径由其父菜单路径名称及其菜单自己的名称组成 ,例如“Foo/Bar/Baz”就是一个有效菜单路径 。

　　3. 1.7

　　图标 icon

　　一种显示在屏幕上 ,用户能以某一器件(例如鼠标)对其指点 , 以便选出特定的功能或应用软件的图形符号 。这种图形符号通常是一种图片表示 。

　　3. 1. 8

　　图标主题 icon theme

　　一组图标的总称 ,用于将图标名称及尺寸影射到一个文件 , 主题可以继承其他主题并对它们进行扩展 。

　　3. 1.9

　　图标文件 icon file

　　一个可被加载并用作图标的图像 。支持的文件类型包括 :PNG、XPM、SVG,PNG是推荐使用的位图格式 ;支持 XPM原因是为了向后兼容 ,建议新的主题不使用 XPM 文件 ; SVG 是矢量图标 ,对 SVG的支持是可选的 。

　　3. 1. 10

　　本地环境 locale

　　对用户环境中与语言和文化习俗相关子集的定义 。

　　3.2 缩略语

　　下列缩略语适用于本文件 。

　　LSB Linux标准集(Linux Standard Base)

　　MIME 多用途网际邮件扩充协议(Multipurpose InternetMailExtensions)

　　PNG 可移植网络图形格式(Portable Network Graphic Format,PNG)

　　SVG 可缩放矢量图形(Scalable Vector Graphics)

　　XPM X像图(X PixMap)

　　4 便利函数库 libclutil

　　4. 1 libclutil接口

　　便利函数库是为方便应用程序开商开发跨不同 Linux操作系统发布平台的应用程序而提供的公共基础性设施 ,功能包括创建文件类型 、创建应用程序描述文件 、创建程序启动菜单 。

　　表 1定义了 libclutil的库名及共享对象名 。 函数库的存放位置是实现定义的 ,但应在动态连接器的搜索目录中 。

　　表 1 libclutil定义

　　符合本标准的实现应提供表 2 中定义的接 口 。

　　表 2 libclutil接口

　　4.2 libclutil数据定义

　　4.3 libclutil接口定义

　　4.3. 1 Desktop entry相关接口

　　4.3. 1. 1 desktop_entry_new

　　名称

　　desktop_entry_new— 创建新的 Desktop Entry格式

　　# include

　　desktop_entry_t desktop_entry_new() ;参数

　　无 。

　　描述

　　该函数 用 于 创 建 新 的 Desktop Entry。 本 标 准 所 涉 及 的 Desktop Entry应 符 合 Desktop Entry Specification的要求 。

　　该函数所返回的 desktop_entry_t类型 ,为 Desktop Entry的操作指针 ,应被如下定义 :

　　typedef structdesktop_entry * desktop_entry_t;

　　其中 structdesktop_entry的具体内容是实现定义的 ,可以是对应用程序透明的 。

　　应用程序应可使用函数 desktop_ entry_ getitem() 或 desktop_ entry_ getitem_ utf8() 对该结构体的内容进行读取 ;使用函数 desktop_entry_setitem()或 desktop_ entry_ setitem_ utf8()设置该结构体的内容 ;使用函数 desktop_entry_free()释放该结构体的内容 ;而不必直接访问或修改结构体中的内容 。

　　应用程序通过该函数创建的 Desktop Entry,当不再使用时 ,应通过调用 desktop_entry_free()释放所创建的 Desktop Entry。

　　返回值

　　成功时返回一个有效的 Desktop Entry指针 ;失败返回 NULL。

　　4.3. 1.2 desktop_entry_free

　　名称

　　desktop_entry_free— 释放 Desktop Entry格式

　　# include

　　voiddesktop_entry_free(destop_entry_t dent) ;参数

　　dent 需被释放的 Desktop Entry对象的指针 。

　　描述

　　该函数用于释放指定的 Desktop Entry空间 。

　　返回值

　　无 。

　　4.3. 1.3 desktop_entry_firstsection

　　名称

　　desktop_entry_firstsection— 获得 Desktop Entry的第一个 section名称格式

　　# include

　　char * desktop_entry_firstsection(destop_entry_t dent) ;参数

　　dent Desktop Entry指针 ;描述

　　该函数用于获得 Desktop Entry的第一个 section名称 。

　　本标准并没有定义实现以何种顺序决定哪个 section为第一个 。

　　如果该 Desktop Entry只有一个 section,并且该 section没有名称 ,该函数可以返回空字符串 。

　　应用程序通过调用本函数获得的字符串 ,不再使用时应调用 free()函数进行释放 。

　　返回值

　　成功返回指向包含第一个 section名称的字符串的指针 ;失败返回 NULL。

　　4.3. 1.4 desktop_entry_nextsection

　　名称

　　desktop_entry_nextsection— 获得 Desktop Entry的下一个 section名称格式

　　# include

　　char * desktop_entry_nextsection(destop_entry_t dent) ;参数

　　dent Desktop Entry指针 ;描述

　　该函数用于获得 Desktop Entry的下一个 section名称 。符合本标准的实现应能记录应用程序上一次调用本函数时的位置 ,并自动查找下一个 section。

　　如果应用程序在第一次调用本(该)函数前 ,没有调用过 desktop_ entry_firstsection() ,则表现将与desktop_entry_firstsection()相同 。

　　实现以何种顺序决定 section的顺序 ,本标准并没有定义 。

　　应用程序通过调用本函数获得的字符串 ,不再使用时应调用 free()函数进行释放 。

　　返回值

　　成功返回指向包含下一个 section名称的字符串的指针 ;失败返回 NULL。

　　4.3. 1.5 desktop_entry_addsection

　　名称

　　desktop_entry_addsection— 在 Desktop Entry中增加一个 section格式

　　# include

　　intdesktop_entry_addsection(destop_entry_t dent, char * section) ;参数

　　dent Desktop Entry指针 ;

　　section 需增加的 section名称 。

　　描述

　　该函数用于在 Desktop Entry中增加一个 section。

　　如果需要增加的 section在 Desktop Entry中不存在 ,则增加 ;否则 ,则失败 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_EXIST section已经存在 ;

　　其他 其他自定义的原因 。

　　4.3. 1.6 desktop_entry_delsection

　　名称

　　desktop_entry_delsection— 从 Desktop Entry中删除一个 section格式

　　# include

　　intdesktop_entry_delsection(destop_entry_t dent, char * section, intrecursive) ;参数

　　dent Desktop Entry指针 ;

　　section 需删除的 section名称 。

　　recursive 是否要删除本节所有的 item 的标志 。

　　描述

　　该函数用于从 Desktop Entry中删除一个 section。

　　如果 recursive为 1,则删除 section以及 section中所有 item;如果 recursive为 0并且 section中存在 item ,则失败 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST section不存在 ;

　　CL_ERR_NOEMPTY recursive为 0且 section中存在 item;

　　其他 其他自定义的原因 。

　　4.3. 1.7 desktop_entry_firstitem

　　名称

　　desktop_entry_firstitem— 获得 Desktop Entry某个 section中第一个 item 的 keyword格式

　　# include

　　char * desktop_entry_firstitem(destop_entry_t dent, char * section) ;参数

　　dent Desktop Entry指针 ;

　　section section名称 。

　　描述

　　该函数用于获得 Desktop Entry某个 section中第一个 item 的 keyword。

　　section可以为 NULL,此时将返回默认 section的第一个 item。

　　实现以何种顺序决定哪个 section为默认 section, 以及 section中哪个 item 为第一个 item ,本标准并没有定义 。

　　应用程序通过调用本函数获得的 keyword字符串 ,不再使用时应调用 free()函数进行释放 。返回值

　　成功返回指向包含第一个 item 名称的 keyword 的指针 ;失败返回 NULL。

　　4.3. 1. 8 desktop_entry_nextitem

　　名称

　　desktop_entry_nextitem— 获得 Desktop Entry某个 section中下一个 item 的 keyword格式

　　# include

　　char * desktop_entry_nextitem(destop_entry_t dent, char * section) ;参数

　　dent Desktop Entry指针 ;

　　section section名称 。

　　描述

　　该函数用于获得 Desktop Entry某个 section中下一个 item 的 keyword。符合本标准的实现应能记录应用程序上一次调用本函数时的位置 ,并自动查找下一个 item。

　　如果应用程序第一次调用本函数 ,表现将与 desktop_entry_firstitem()相同 。

　　section可以为 NULL,此时将返回默认 section的下一个 item。

　　实现以何种顺序决定哪个 section为默认 section, 以及 section中哪个 item 为第一个 item ,本标准并没有定义 。

　　应用程序通过调用本函数获得的 keyword字符串 ,不再使用时应调用 free()函数进行释放 。返回值

　　成功返回指向包含下一个 item 名称的 keyword 的指针 ;失败返回 NULL。

　　4.3. 1.9 desktop_entry_getitem

　　名称

　　desktop_entry_getitem— 获得 Desktop Entry中指定 section中指定 item 的 value格式

　　# include

　　char * desktop_entry_getitem(destop_entry_t dent, char * keyword, char * section) ;参数

　　dent Desktop Entry指针 ;

　　keyword 需要获得的 item 的 keyword;

　　section 指定 section的名称 。

　　描述

　　该函数用于获得 Desktop Entry中指定 section中指定 item 的 value。

　　section可以为 NULL,此时将返回默认 section 中指定 item 的 value。 实现以何种顺序决定哪个section为默认 section,本标准并没有定义 。

　　value将使用应用程序当前设置的编码 ,符合本标准的实现应自动转换 。

　　应用程序通过调用本函数获得的 keyword字符串 ,不再使用时应调用 free()函数进行释放 。返回值

　　成功返回包含 item 的 value的指针 ;失败返回 NULL。

　　4.3. 1. 10 desktop_entry_getitem_utf8

　　名称

　　desktop_entry_getitem_utf8— 获得 Desktop Entry中指定 section中指定 item 的 value,该 value使用 UTF-8进行编码

　　格式

　　# include

　　char * desktop_entry_getitem_utf8(destop_entry_t dent, char * keyword, char * section) ;参数

　　dent Desktop Entry指针 ;

　　keyword 需要获得的 item 的 keyword;

　　section 指定 section的名称 。

　　描述

　　该函数用于获得 Desktop Entry中指定 section中指定 item 的 value,该 value应使用 UTF-8进行编码 。符合本标准的实现应能自动转换 。

　　section可以为 NULL,此时将返回默认 section 中指定 item 的 value。 实现以何种顺序决定哪个section为默认 section,本标准并没有定义 。

　　应用程序通过调用本函数获得的 keyword字符串 ,不再使用时应调用 free()函数进行释放 。返回值

　　成功返回包含 item 的 value的指针 ;失败返回 NULL。

　　4.3. 1. 11 desktop_entry_setitem

　　名称

　　desktop_entry_setitem— 设置 Desktop Entry中指定 section中指定 item 的 value格式

　　# include

　　intdesktop_entry_setitem(destop_entry_tdent, char * keyword, char * value, char * section) ;参数

　　dent Desktop Entry指针 ;

　　keyword 需设置的 item 的 keyword;

　　value 需设置的 value;

　　section 指定 section的名称 。

　　描述

　　该函数用于设置 Desktop Entry中指定 section中指定 item 的 value。

　　section可以为 NULL,此时将设置默认 section 中指定 item 的 value。 实现以何种顺序决定哪个section为默认 section,本标准并没有定义 。

　　value应使用应用程序当前设置的编码 ,符合本标准的实现应自动转换 。

　　如果参数 section和 keyword指定的 section或 item 不存在 ,实现应自动增加新的 section和 item。 value的值是否允许为 NULL或空字符串 , 由实现定义 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　其他 其他自定义的原因 。

　　4.3. 1. 12 desktop_entry_setitem_utf8

　　名称

　　desktop_entry_setitem_utf8— 设置 Desktop Entry中指定 section中指定 item 的 value格式

　　# include

　　intdesktop_entry_ setitem_ utf8(destop_ entry_ t dent, char * keyword, char * value, char * section) ;

　　参数

　　dent Desktop Entry指针 ;

　　keyword 需设置的 item 的 keyword;

　　value 需设置的 value;

　　section 指定 section的名称 。

　　描述

　　该函数用于设置 Desktop Entry中指定 section中指定 item 的 value。

　　section可以为 NULL,此时将设置默认 section 中指定 item 的 value。 实现以何种顺序决定哪个section为默认 section,本标准并没有定义 。

　　value应使用 UTF-8编码 ,符合本标准的实现应自动转换 。

　　如果参数 section和 keyword指定的 section或 item 不存在 ,实现应自动增加新的 section和 item。 value的值是否允许为 NULL或空字符串 , 由实现定义 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　其他 其他自定义的原因 。

　　4.3. 1. 13 desktop_entry_delitem

　　名称

　　desktop_entry_delitem— 删除 Desktop Entry中指定 section中指定的 item格式

　　# include

　　intdesktop_entry_delitem(destop_entry_t dent, char * keyword, char * section) ;参数

　　dent Desktop Entry指针 ;

　　keyword 需删除的 item 的 keyword;

　　section 指定 section的名称 。

　　描述

　　该函数用于删除 Desktop Entry中指定 section中指定的 item。

　　section可以为 NULL,此时将设置默认 section 中指定 item 的 value。 实现以何种顺序决定哪个section为默认 section,本标准并没有定义 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的 section或 item 不存在 ;

　　其他 其他自定义的原因 。

　　4.3. 1. 14 desktop_entry_from_file

　　名称

　　desktop_entry_from_file— 从一个 desktop文件中读入 Desktop Entry格式

　　# include

　　intdesktop_entry_from_file(destop_entry_t dent, constchar * filename) ;参数

　　dent Desktop Entry指针 ;

　　filename 需读入的文件的文件名 。

　　描述

　　该函数用于从一个 desktop文件中读入 Desktop Entry。

　　dent不能为 NULL,否则将返回参数无效错误 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的文件不存在 ;

　　CL_ERR_PERM 对指定的文件没有访问权限(读权限) ;

　　CL_ERR_NOTFILE 指定的文件不是一个普通文件或者文件格式不正确 ;

　　其他 其他自定义的原因 。

　　4.3. 1. 15 desktop_entry_to_file

　　名称

　　desktop_entry_to_file— 将 Desktop Entry中内容导入到一个文件中格式

　　# include

　　intdesktop_entry_to_file(constdestop_entry_t dent, constchar * filename) ;参数

　　dent Desktop Entry指针 ;

　　filename 要写入的文件名 。

　　描述

　　该函数用于将一个 Desktop Entry中的内容写入某个文件 。

　　dent不能为 NULL,否则将返回参数无效错误 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的文件不存在 ;

　　CL_ERR_PERM 对指定的文件没有访问权限(写权限) ;

　　CL_ERR_NOTFILE 指定的文件不是一个普通文件或者文件格式不正确 ;

　　其他 其他自定义的原因 。

　　4.3.2 MIME 类型相关接口

　　4.3.2. 1 mimetype_new

　　名称

　　mimetype_new— 创建一个新的文件类型 Desktop Entry格式

　　# include

　　desktop_entry_t mimetype_new(char * mimetype) ;参数

　　mimetype 文件类型名称

　　描述

　　该函数用于创建一个新的文件类型 Desktop Entry。该 Desktop Entry的默认 section中 ,keyword为“Type”的 item 的 value值将被设置为 “MimeType”; keyword 为 “MimeType”的 item 的 value值将被设置为 mimetype。

　　mimetype的格 式 一 般 应 符 合 MIME 规 范 , 实 现 可 自 行 决 定 是 否 允 许 不 符 合 规 范 的 mimetype出现 。

　　应用程序通过本函数获得的 Desktop Entry,不再使用时需调用 desktop_entry_free()进行释放 。返回值

　　成功返回创建的 Desktop Entry的指针 ;失败返回 NULL。

　　4.3.2.2 mimetype_get

　　名称

　　mimetype_get— 获取一个文件类型的 Desktop Entry指针格式

　　# include

　　desktop_entry_t mimetype_get(char * mimetype) ;参数

　　mimetype 文件类型名称描述

　　该函数用于获取某个文件类型的 Desktop Entry指针 。

　　如果 mimetype不存在 ,该函数应失败 。

　　应用程序通过本函数获得的 Desktop Entry,不再使用时需调用 desktop_entry_free()进行释放 。返回值

　　成功返回一个 Desktop Entry指针 ;失败返回 NULL。

　　4.3.2.3 mimetype_set

　　名称

　　mimetype_set— 向系统中增加一个文件类型格式

　　# include

　　intmimetype_set(desktop_entry_t dent, intoverwrite) ;参数

　　dent 文件类型 Desktop Entry指针 ;

　　overwrite 是否强制覆盖的标志 。

　　描述

　　该函数用于向系统中增加一个文件类型 。

　　如果 dent 描 述 的 文 件 类 型 不 存 在 , 则 创 建 一 个 新 的 文 件 类 型 ; 如 果 该 文 件 类 型 存 在 , 并 且overwrite为 1,则用新的描述 ,改写旧的描述 ,否则失败 。

　　调用该函数后 mimetype是否立即生效 , 由实现定义 。

　　dent所描述的文件类型 Desktop Entry中 ,包含下列 keyword 的 item 应在默认 section中出现 ,并且包含有效 value:

　　Type类型 ,应为“MimeType”;

　　MimeType文件类型 ;

　　Comment注释 。

　　包含下列 keyword 的 item 可以出现 :

　　Comment[]某种 locale下的注释 ,其中可以是任意一种 locale;

　　Icon 图标文件名 ;

　　Patterns匹配该文件类型的文件名描述 ,可以使用通配符 ,多个文件名间以 “;”分隔 ,如“file”、“file. * ; file”或“* . txt; file. * ”。

　　实现不应强制要求 dent中包含上述 item 以外的其他 item。如果实现所采用的机制必须使用其他的 item ,其内容应由实现自行填充 。

　　dent中还可以包含哪些 section或 item 是实现定义的 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_EXIST 指定的文件类型存在 ,并且 overwrite为 0;

　　其他 其他自定义的原因 。

　　4.3.2.4 mimetype_delete

　　名称

　　mimetype_delete— 从系统中删除一个文件类型格式

　　# include

　　intmimetype_delete(char * mimetype) ;

　　参数

　　mimetype需删除的 mimetype。

　　描述

　　该函数用于从系统中删除一个文件类型 。删除 mimetype后是否立即生效 , 由实现定义 。返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的文件类型不存在 ;

　　其他 其他自定义的原因 。

　　4.3.2.5 mimetype_add_magic

　　名称

　　mimetype_add_magic— 增加一个文件类型的 magic描述格式

　　# include

　　intmimetype_set_magic(char * mimetype, structmime_magic * magic) ;参数

　　mimetype文件类型名称 ;

　　magic要增加的 magic描述指针 。

　　描述

　　该函数用于增加一个文件类型的 magic描述 。

　　结构 mime_magic定义如下 :

　　structmime_magic{

　　char * offset;

　　char * type;

　　char * data;

　　} ;

　　关于 magic中 office、type和 data的定义 ,参见 ISO/IEC 23360-1 LSB3. 1 中对 file的定义 。返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的文件类型不存在 ;

　　其他 其他自定义的原因 。

　　4.3.3 应用程序描述文件相关接口

　　4.3.3. 1 progdesc_new

　　名称

　　progdesc_new— 创建一个新的应用程序描述 Desktop Entry格式

　　# include

　　desktop_entry_t progdesc_new() ;参数

　　无 。

　　描述

　　该函数用于创建一个新的程序描述 Desktop Entry。该 Desktop Entry的默认 section中 ,keyword为“Type”的 item 的 value值将被设置为“Application”。

　　应用程序通过本函数获得的 Desktop Entry,不再使用时需调用 desktop_entry_free()进行释放 。返回值

　　成功返回创建的 Desktop Entry的指针 ;失败返回 NULL。

　　4.3.3.2 progdesc_get

　　名称

　　progdesc_get— 获取一个应用程序描述的 Desktop Entry指针格式

　　# include

　　desktop_entry_t progdesc_get(char * filename) ;参数

　　filename 应用程序描述所在的文件 。

　　描述

　　该函数用于获取某个应用程序描述的 Desktop Entry指针 。

　　filename可以是一个绝对路径 ,也可以是相对路径 。如果是相对路径 ,实现将决定从哪个目录中查找该文件 。

　　如果实现以某种固定的扩展名(如 . desktop) 存储应用程序描述文件 ,那么该扩展名在 filename 中可以省略 。

　　如果 filename不存在 ,该函数应失败 。

　　应用程序通过本函数获得的 Desktop Entry,不再使用时需调用 desktop_entry_free()进行释放 。返回值

　　成功返回一个 Desktop Entry指针 ;失败返回 NULL。

　　4.3.3.3 progdesc_set

　　名称

　　progdesc_set— 向系统中增加一个应用程序描述格式

　　# include

　　intprogdesc_set(char * filename, desktop_entry_t dent, intoverwrite) ;参数

　　filename 该应用程序描述保留的文件名 ;

　　dent 应用程序描述 Desktop Entry指针 ;

　　overwrite 是否强制覆盖的标志 。

　　描述

　　该函数用于向系统中增加一个应用程序描述 。

　　如果 dent描述的文件不存在 ,则创建一个新的文件 ;如果该文件存在 ,并且 overwrite为 1,则用新的描述 ,改写旧的描述 ,否则失败 。

　　filename可以是一个绝对路径 ,也可以是相对路径 。如果是相对路径 ,实现将决定从哪个目录中查找该文件 。

　　如果实现以某种固定的扩展名(如 . desktop) 存储应用程序描述文件 ,那么该扩展名在 filename 中

　　可以省略 。

　　调用该函数后应用程序描述是否立即生效 , 由实现定义 。

　　dent所描述的应用程序描述 Desktop Entry中 ,包含下列 keyword 的 item 应在默认 section 中出现 ,并且包含有效 value:

　　Type类型 ,应为“Application”;

　　Exec需执行的应用程序及其参数 ;

　　Name名称 。

　　包含下列 keyword 的 item 可以出现 :

　　Name[]某种 locale下的名称 ,其中可以是任意一种 locale;

　　MimeType可以处理的文件类型 ,可以为多个 ,之间以 “;”分隔 ;

　　Comment注释 ;

　　Comment[]某种 locale下的注释 ,其中可以是任意一种本地环境 ;

　　Icon 图标文件名 ;

　　StartupNotify启动时是否通知窗口管理器 ;

　　Terminal应用程序是否要在终端下执行 。true为是;false为否 ;

　　Path执行程序的路径 ;

　　Categories起始菜单分组信息 。可以是起始菜单中的某个组 。

　　实现不应强制要求 dent中包含上述 item 以外的其他 item。如果实现所采用的机制必须使用其他的 item ,其内容应由实现自行填充 。

　　dent中还可以包含哪些 section或 item 是实现定义的 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_EXIST 指定的文件存在 ,并且 overwrite为 0;

　　其他 其他自定义的原因 。

　　4.3.3.4 progdesc_delete

　　名称

　　progdesc_delete— 从系统中删除一个应用程序描述文件格式

　　# include

　　intprogdesc_delete(char * filename) ;参数

　　filename 需要删除的文件 。

　　描述

　　该函数用于从系统中删除一个应用程序描述文件 。删除后是否立即生效 , 由实现定义 。

　　如果实现以某种固定的扩展名(如 . desktop) 存储应用程序描述文件 ,那么该扩展名在 filename 中可以省略 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的文件不存在 ;

　　其他 其他自定义的原因 。

　　4.3.4 启动菜单相关接口

　　4.3.4. 1 applnk_create

　　名称

　　applnk_create— 创建一个快捷方式或组格式

　　# include

　　intapplnk_create(desktop_entry_t dent, char * category, char * location, intalluser) ;参数

　　dent 包含快捷方式或组描述的 Desktop Entry指针 ;

　　category 对于快捷方式组 ,需要的组信息 ;

　　location 该快捷方式或组的创建位置 ;

　　alluser 是否为所有用户创建的标志 。

　　描述

　　该函数用于向系统中增加一个快捷方式或组 。

　　dent用于描述该快捷方式或组 ,描述的方式有两种 :

　　a) 方式一 :dent中包含下列 keyword 的 item 应存在 ,并且包含有效 value:

　　Name名称 ;

　　Type类型 ;

　　如果类型为“Application”,那么包含下列 keyword 的 item 应存在 ,并且包含有效 value: Exec执行的应用程序及参数 ;

　　如果类型为“Link”,那么包含下列 keyword 的 item 应存在 ,并且包含有效 value:

　　URL 连接的 url或文件 。

　　包含下列 keyword 的 item 可以存在 :

　　Name[]某种 locale下的名称 ,其中可以是任意一种 locale;

　　Comment注释 ;

　　Comment[]某种 locale下的注释 ,其中可以是任意一种 locale;

　　Icon 图标文件名 ;

　　Path执行程序的路径 ;

　　Filename指定文件存储的名称[取最后一项 , 即 basename()] 。

　　Type为“Diretory”时 ,将创建组 ;否则 ,创建快捷方式 。如果没有指定 Filename,在 desktop下创建的组(即 目录) 或者文件名称等于 dent中关键字 Name所描述的值(对于文件 ,文件名后加 . desktop后缀) 。

　　b) 方式二 :关键字 Type的值为空或者没有设置 ;并且包含下列 keyword 的 item 存在 ,并包含有效 value:

　　FileName文件名 。

　　此时 ,系统将自动读取 FileName指定的文件名(绝对路径或相对路径 ,该文件存放的默认位置是系统自定义的) ,用于创建快捷方式或组 。

　　该文件可以是用户使用 progdesc_set等函数创建的 ,也可以是通过编辑器或其他应用软件创建的 。

　　Filename将自 动 增 加 到 Desktop Entry文 件 中 , 如 果 原 来 的 Desktop Entry文 件 中 已 经 存 在Filename项 ,将被覆盖 。

　　Desktop Entry文件中应该包含的项以及创建规则等与方式一相同 。

　　对于本函数创建的组或快捷方式 ,其他函数(譬如 applnk_ delete) 使用/ 或 者 / (对 于 Filename 不 存 在 的 情 形) 或 者/(只针对起始菜单中的组)可以检索到 。

　　参数 category只对快捷方式组有效 ,用于确定该组的 category名 ,用于 progdesc添加使用 ;

　　参数 location表示快捷方式或组需要安装的位置(目录) ,可以接受的字符串包括 :

　　application起始菜单的应用程序下 ;

　　application/. . . [/. . . ]起始菜单的应用程序下的某个组下(如果该组不存在的话 , 函数将失败) ;

　　launcher 面板启动器 ;

　　desktop桌面 ;

　　desktop/. . . [/. . . ]桌面下的路径(如果路径中的某个目录不存在的话 , 函数将失败) ;

　　autostart 自动启动项 。

　　如果被指定的位置是一个文件或快捷方式的话 , 函数将失败 。

　　注 : 组只能被创建在起始菜单或桌面中 ;起始菜单中 的 快 捷 方 式 建 议 直 接 使 用 progdesc_ set() 创 建 并 指 定 所 在 的组 ,使用本函数创建时 ,也建议使用方式二 ,或者保证相同的 描 述 没 有 被 progdesc_ set创 建 过 ; 否 则 , 可 能 造 成系统不一致 。

　　alluser用于标志是否为所有用户创建快捷方式或组 。 为 1 时表示为所有用户创建(只有特权用户才可以) ;为 0 时 ,系统将只为当前用户创建 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOTFILE 需要写入的文件(譬如使用 Filename指定的文件)不是一个文件 ;

　　CL_ERR_NOEXIST 路径中间的目录不存在 ;或者使用方式二指定的文件名不存在 ;

　　其他 其他自定义的原因 。

　　4.3.4.2 applnk_delete

　　名称

　　applnk_delete— 删除一个快捷方式或组格式

　　# include

　　intapplnk_delete(char * location, intalluser, intrecursive) ;参数

　　location 该快捷方式或组的位置 ;

　　alluser 是否为所有用户删除的标志 ;

　　recursive 是否删除下属子组和快捷方式的标志 。

　　描述

　　该函数用于从系统中删除一个快捷方式或组 。

　　参数 location表示快捷方式组的位置(目录) ,可以接受的字符串包括 :

　　application/. . . [/. . . ]起始菜单的应用程序下的某个组 ;

　　desktop/. . . [/. . . ]桌面下的路径 ;

　　laucher/. . . 面板启动器下的快捷方式 ;

　　autostart/. . . 自动启动项下的项 。

　　alluser用于标志是否为所有用户删除快捷方式组 。 为 1 时删除所有用户的快捷方式组(只有特权用户才可以) ;为 0 时 ,系统将删除当前用户的快捷方式组 。

　　对于组 ,如果 recursive为 1,则删除该快捷方式组以及该组中的子组和快捷方式 ;如果 recursive为0并且该快捷方式组下不空 ,则失败 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 指定的快捷方式组不存在 ;

　　CL_ERR_NOEMPTY recursive为 0并且组下不空 ;

　　其他 其他自定义的原因 。

　　4.3.4.3 applnk_fast_create

　　名称

　　applnk_fast_create— 快速创建一个快捷方式或组格式

　　# include

　　intapplnk_fast_ create(const char * name, const char * name_ loc, const char * exec, const char * icon, constchar * category, constchar * location, intalluser) ;

　　参数

　　name 快捷方式或组的名称(locale为 C 时显示的名称) ;

　　name_loc 快捷方式或组的本地名称(当前 locale下显示的名称) ;

　　exec 被执行命令的路径 ;

　　icon 图标路径 ;

　　category 对于快捷方式组 ,需要的组信息 ;

　　location 该快捷方式或组的创建位置 ;

　　alluser 是否为所有用户创建的标志 。

　　描述

　　该函数用于向系统中快速增加一个快捷方式或组 。

　　name用 于 描 述 快 捷 方 式 或 组 的 名 称 , 该 名 称 将 在 没 有 指 定 当 前 locale 的 名 称 的 情 况 下 显 示 。 name不能为 NULL,否则将返回参数无效错误 ;

　　name_loc用于描述 快捷方式或组的本地名称 , 即在当前 locale下显示的名称 。name_loc应使用当前 locale编码 。name_loc可以为 NULL;

　　exec用于描 述 快 捷 方 式 的 执 行 命 令 路 径 名 。 如 果 增 加 的 是 一 个 快 捷 方 式 的 话 , exec 不 能 为NULL,否则将返回参数无效错误 ;如果增加的是一个组的话 ,exec将被忽略 ;

　　icon用于指定快捷方式或组的显示图标路径 。该路径可以是相对系统默认路径的相对路径 ,也可以是绝对路径 。icon可以为 NULL;

　　参数 category只对快捷方式组有效 ,用于确定该组的 category名 ,用于 progdesc添加使用 ;

　　location表示快捷方式或组需要安装的位置(目录) ,可以接受的字符串包括 :

　　application起始菜单的应用程序下 ;

　　application/. . . [/. . . ]起始菜单的应用程序下的某个组下(如果该组不存在的话 , 函数将失败) ;

　　launcher 面板启动器 ;

　　desktop桌面 ;

　　desktop/. . . [/. . . ]桌面下的路径(如果路径中的某个目录不存在的话 , 函数将失败) ;

　　autostart 自动启动项 。

　　如果被指定的位置是一个文件或快捷方式的话 , 函数将失败 。

　　组只能被创建在起始菜单或桌面中 。

　　alluser用于标志是否为所有用户创建快捷方式或组 。 为 1 时表示为所有用户创建(只有特权用户才可以) ;为 0 时 ,系统将只为当前用户创建 。

　　如果用户指定的快捷方式或组的名称已经存在 , 实现可以采用覆盖 、忽略或者重复创建等方式处理 ,本标准对于具体实现并不规定 。

　　在该函数执行过程中 ,可能需要创建新的 desktop文件 ,文件名将由实现决定 ,一般不应覆盖用户已有的其他文件 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST 路径中间的目录不存在 ;

　　其他 其他自定义的原因 。

　　4.3.5 图标相关接口

　　4.3.5. 1 icon_add

　　名称

　　icon_add— 向系统默认的图标路径中增加一个图标文件格式

　　# include

　　inticon_add(constchar * icon, constchar * dest) ;参数

　　icon 图标文件的源路径 ;

　　dest 增加到系统默认路径下的相对路径 。

　　描述

　　该函数用于向系统中增加一个图标 。

　　icon用于指定图标文件的原始路径 。应用应保证该文件为系统识别的图标文件格式 。但本标准对于实现是否要对文件格式的正确性进行检查并无要求 ;

　　dest用于指定增加到系统默认路径下的相对路径 。dest可以为 NULL,此时图标文件将被复制到系统默认路径下 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST icon指定的文件不存在 ;

　　其他 其他自定义的原因 。

　　4.3.5.2 icon_delete

　　名称

　　icon_delete— 从系统默认的图标路径中删除一个图标文件格式

　　# include

　　inticon_delete(constchar * icon) ;

　　参数

　　Icon 要删除的图标文件在系统默认路径下的相对路径 。

　　描述

　　该函数用于从系统中删除一个图标 。

　　icon用于指定要删除的图标文件在系统默认路径下的相对路径 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_ERR_NOEXIST icon指定的文件不存在 ;

　　其他 其他自定义的原因 。

　　4.3.6 RecentFile相关接口

　　4.3.6. 1 recent_file_add

　　名称

　　recent_file_add— 将一个文件增加到最近打开文件列表中格式

　　# include

　　intrecent_file_add(constchar * filename) ;参数

　　filename 需要增加的文件名 。

　　描述

　　该函数用于将一个文件增加到最近打开文件列表中 。

　　filename用于指定需要增加的文件 。filename不能为 NULL,否则将返回参数无效错误 ;本标准并不对系统是否要检查文件的存在性进行规定 。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　其他 其他自定义的原因 。

　　4.3.6.2 recent_file_delete

　　名称

　　recent_file_delete— 从最近打开文件列表中删除一个文件格式

　　# include

　　intrecent_file_delete(constchar * filename) ;参数

　　filename 需要删除的文件名 。

　　描述

　　该函数用于从最近打开文件列表中删除一个文件 。

　　filename用于指定需要删除的文件 。filename不能为 NULL,否则将返回参数无效错误 。返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　其他 其他自定义的原因 。

　　4.3.7 打开特定的应用程序相关接口

　　4.3.7. 1 clutil_open

　　名称

　　clutil_open— 使用默认打开程序打开一个文件格式

　　# include

　　intclutil_open(constchar * filename) ;参数

　　filename 需要打开的文件的路径 。

　　描述

　　该函数用于使用默认打开程序打开一个文件 。

　　filename是需要被打开的文件的路径 ,filename不能为 NULL,否则将返回参数无效错误 。返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　CL_NO_EXIST 打开方式不存在 ;

　　其他 其他自定义的原因 。

　　4.3.7.2 clutil_email名称

　　名称

　　clutil_email— 使用默认的邮件处理程序发送邮件格式

　　# include

　　intclutil_email(constchar * mailaddr, constchar *cc, constchar *bcc, constchar ** filename) ;参数

　　mailaddr 收件人地址 ;

　　cc 抄送者地址 ;

　　bcc 暗送者地址 ;

　　filename 需要附加的文件列表 。

　　描述

　　该函数用于使用使用默认的邮件处理程序发送邮件 。

　　mailaddr用于指定收件人地址 。mailaddr应符合 RFC822的规定 ,多个地址中可以使用逗号分隔 。 mailaddr可以为 NULL。

　　cc用于指定抄送者地 址 。 cc应 符 合 RFC822 的 规 定 , 多 个 地 址 中 可 以 使 用 逗 号 分 隔 。 cc可 以 为

　　NULL。

　　bcc用于指定暗送者地址 。 bcc应符合 RFC822 的规定 , 多个地址中可以使用逗号分隔 。 bcc可以为 NULL。

　　filename用 于 指 定 需 要 附 件 的 文 件 列 表 。 filename应 是 一 个 以 NULL结 束 的 字 符 串 指 针 数 组 。 filename可以为 NULL。

　　返回值

　　成功返回 0;失败返回非 0,并根据失败原因的不同 ,返回 :

　　CL_ERR_INVAL 参数无效 ;

　　其他 其他自定义的原因 。

　　5 农历函数库 liblunar-1

　　5. 1 liblunar-1接口

　　农历函数库提供了一组和农历相关的应用程序接 口 ,实现了公农历的相互转换功能 。

　　本函数库依赖于 glib,关于 NULL 、TRUE 、FALSE 、GError 、GDateYear 、GDateMonth 、GDate- Day的定义 ,详见 ISO/IEC 23360-1 LSB 3. 1。

　　表 3定义了 liblunar-1的库名及共享对象名 。 函数库的存放位置是实现定义的 ,但应在动态连接器的搜索目录中 。

　　表 3 liblunar-1定义

　　符合本标准的实现应提供表 4 中定义的接 口 。

　　表 4 liblunar-1接口

　　5.2 liblunar-1数据定义

　　5.3 liblunar-1接口定义

　　5.3. 1 初始化

　　5.3. 1. 1 lunar_init

　　名称

　　lunar_init— 初始化 liblunar库格式

　　# include

　　voidlunar_init(int * argc,char *** argv) ;参数

　　argc 命令行参数的个数 ;

　　argv 命令行参数数组 。

　　描述

　　该函数用来初始化 liblunar库 ,编写应用程序时 ,该函数应首先被调用 。

　　返回值

　　无 。

　　5.3.2 日期转换接口

　　5.3.2. 1 lunar_date_new

　　名称

　　lunar_date_new— 创建新的 LunarDate格式

　　# include

　　LunarDate* lunar_date_new (void)参数

　　无 。

　　描述

　　创建一个新的 LunarDate。该函数返回的为 LunarDate类型指针 ,

　　使用完毕 ,应使用 lunar_date_free()函数来释放该结构体的内容 。

　　返回值

　　成功时返回一个有效的 LunarDate指针 ,失败时返回 NULL。

　　5.3.2.2 lunar_date_set_solar_date

　　名称

　　lunar_date_set_solar_date— 设置公历日期格式

　　# include

　　voidlunar_ date_ set_ solar_ date (LunarDate * date, GDateYear year, GDateMonth month, GDateDay day, GDateHour hour, GError ** error) ;

　　参数

　　date 由 lunar_date_new()创建的 LunarDate指针 ;

　　year 设置公历年份 ;

　　month 设置公历月份 ;

　　day 设置公历 日 ;

　　hour 设置小时 ;

　　error 返回错误信息 ,设置为 NULL则忽略错误 。描述

　　为 date设置公历年 、月 、日和小时 。

　　示例

　　返回值

　　无 。

　　5.3.2.3 lunar_date_set_lunar_date

　　名称

　　lunar_date_set_lunar_date— 设置农历日期格式

　　# include

　　voidlunar_ date_ set_ lunar_ date (LunarDate * date, GDateYear year, GDateMonth month, GDateDay day, GDateHour hour, gboolean isleap, GError ** error) ;

　　参数

　　date 由 lunar_date_new()创建的 LunarDate指针 ;

　　year 设置农历年份 ;

　　month 设置农历月份 ;

　　day 设置农历 日 ;

　　hour 设置小时 ;

　　isleap 设置 month指定的月是不是闰月 ,如果是闰月 ,此变量设为 TRUE,否则请设置为

　　FALSE;

　　error 返回错误信息 ,设置为 NULL则忽略错误 。

　　描述

　　为 date设置农历年 、月 、日和小时 。如果是闰月 ,应该把 isleap这个参数设为 TRUE。

　　如果 isleap参数 设 置 错 误 (对 闰 月设 置 isleap 参 数 为 FALSE; 或 对 非 闰 月设 置 isleap 参 数 为TRUE) ,那么 error

　　将会返回错误信息 。所以每次调用此函数之后 ,都应该检查一下 error参数 ,对错误的设置应该及时给出说明或提示 。

　　示例

　　返回值

　　无

　　5.3.2.4 lunar_date_get_jieri

　　名称

　　lunar_date_get_jieri— 得到节日或节气信息格式

　　# include

　　gchar* lunar_date_get_jieri(LunarDate * date) ;参数

　　date 由 lunar_date_new()创建的 LunarDate指针 。

　　描述

　　根据当前设置的 日期 ,返回一个字符串 ,这个字符串是当前日期所对应的节日或节气 。

　　如果当前日期没有节日或节气 ,返回空串 。

　　返回值

　　一个字符串 ,包含节 日 、节气等 ,多个项之前使用空格分隔 。如果没有节日或节气 ,则返回空串 。

　　5.3.2.5 lunar_date_strftime

　　名称

　　lunar_date_strftime— 格式化输出 日期字符串格式

　　# include

　　gchar* lunar_date_strftime(LunarDate * date, constchar * format) ;参数

　　date 由 lunar_date_new()创建的 LunarDate指针 ;

　　format 指定输出格式 。可使用的格式及示例输出如下 :

　　大写公历 %(YEAR)年 %(MONTH)月%(DAY) 日 %(HOUR)时 ,

　　例如 :二 ○○八年一月二十一 日十一时 ;

　　小写公历 %(year)年 %(month)月%(day) 日 %(hour)时 ,

　　例如 :2008年 1 月 21 日 11时 ;

　　大写农历 %(NIAN)年 %(YUE)月%(RI) 日 %(SHI)时 ,

　　例如 :丁亥年腊月十四 日亥时 ;

　　小写农历 %(nian)年 %(yue)月%(ri) 日 %(shi)时 ,

　　例如 :2007年 12月 14 日 8 时 ;

　　大写干支 %(Y60)年 %(M60)月%(D60) 日 ,

　　例如 :丁亥年癸丑月庚申 日 ;

　　大写八字 %(Y8)年 %(M8)月%(D8) 日 %(S8)时 ,

　　例如 :丁亥年癸丑月庚申 日亥时 ;

　　生肖 %(shengxiao) ,

　　例如 :蛇 ;

　　节日节气 %(jieri) ,

　　例如 :立春 。

　　描述

　　根据指定的输出格式 %(???)来输出 日期字符串 。 以上的输出格式 %(???) 可以任意组合使用 ,其中的非格式字符将会原样输出 。

　　示例

　　返回值

　　返回一个已分配空间的以 0结尾的字符串 。使用完成后需要释放此字符串所占用的空间 。

　　5.3.2.6 lunar_date_free

　　名称

　　lunar_date_free— 释放 LunarDate格式

　　# include

　　voidlunar_date_free (LunarDate * date) ;参数

　　date 由 lunar_date_new()创建的 LunarDate指针 。

　　描述

　　释放之前由 lunar_date_new()创建的 LunarDate指针 。

　　返回值

　　无 。