C语言通用双向循环链表操作函数集

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

说明

相比Linux内核链表宿主结构可有多个链表结构的优点，本函数集侧重封装性和易用性，而灵活性和效率有所降低。
可基于该函数集方便地构造栈或队列集。
本函数集暂未考虑并发保护。

一概念

链表是一种物理存储单元上非连续、非顺序的存储结构，数据元素的逻辑顺序通过链表中的指针链接次序实现。链表由一系列存储结点组成，结点可在运行时动态生成。每个结点均由两部分组成，即存储数据元素的数据域和存储相邻结点地址的指针域。当进行插入或删除操作时，链表只需修改相关结点的指针域即可，因此相比线性表顺序结构更加方便省时。

链表可分为单链表(Singly Linked List)、双向链表(Doubly Linked List)和循环链表(Circular List)等。一个单链表结点仅包含一个指向其直接后继结点的指针，因此当需要操作某个结点的直接前驱结点时，必须从单链表表头开始查找。

双向链表和循环链表均为单链表的变体。通常创建双向循环链表以综合利用两者的优点。

1.1 双向链表

双向链表的每个结点除含有数据域外，还有两个指针域，分别指向直接前驱结点和直接后继结点。因此，从双向链表中的任一结点开始，均可方便地访问其前驱结点和后继结点。双向链表的结点结构示意图如下所示：

图1 双向链表的结点结构

其中，Data为结点存储的数据元素，prev指针指向该结点的前驱结点，next指针指向该结点的后继结点。双向链表通常含有一个表头结点，亦称哨兵结点(Sentinel Node)，用于简化插入和删除等操作。带头结点的非空双向链表如下图所示：

图2 带头结点的非空双向链表

图中，表头指针dhead指向表头结点Head，该结点的前驱指针为空；结点C为表尾结点，其后继指针为空。除表头结点和表尾结点外，对指向双向链表任一结点的指针p，满足下面的关系：

p = p->prev->next = p->next->prev

即当前结点前驱的后继是自身，其后继的前驱也是自身。

链表有查找、插入和删除三种基本操作。双向链表也不例外。

1) 查找操作

在带表头的双向链表中查找数据域为一特定值的某个结点时，可从表头结点开始向后依次匹配各结点数据域的值，若与特定值相同则返回指向该结点的指针，否则继续往后遍历直至表尾。

2) 插入操作

假设指针p和q指向双向链表中的两个前后相邻结点，将某个新结点(指针为s)插到p和q之间，其过程及C语言描述如下图所示：

图3 在双向链表中插入结点的过程

注意，结点前驱后继指针的操作顺序并非唯一，但必须保证最后才对p->next或q->prev赋值(操作➃)，否则会“丢失”p的后继结点或q的前驱结点。

可见，若相邻结点指针p、q均已知，则在p和q之间插入新结点s时，只需依次将s的前驱指针指向p，s的后继指针指向q，p的后继指针指向s，q的前驱指针指向s。即：

① s->prev = p;

② s->next = q;

③ p->next = s;

④ q->prev = s;

双向链表中p和q->prev指向同一结点，因此上述步骤等效于图3中q“视角”的第二种插入顺序。为便于记忆，可想象孩子(s)先后去拉爸爸(p)和妈妈(q)的手，爸爸(p)妈妈(q)再先后拉住孩子(s)的手。

3) 删除操作

删除某个结点，其实就是插入某个结点的逆操作。还是对于双向循环链表，要在连续的三个结点s,p,q中删除p结点，只需把s的右链域指针指向q，q的左链域指针指向s，并收回p结点即可。

假设指针p、s和q指向双向链表中的三个前后相邻结点，删除结点s的过程及C语言描述如下图所示：

图4 在双向链表中删除结点的过程

可见，删除时只需将p的后继指针指向q，q的前驱指针指向p，并回收结点s即可。

1.2 循环链表

将单链表尾结点的指针域指向第一个结点或表头结点，即构成单向循环链表，简称循环链表。从循环链表中任一结点单向出发，均可找到链表中其他结点。

借助表头结点可统一空表和非空表的运算，因此循环链表中往往加入表头结点。带头结点的循环链表如下图所示：

图5 带头结点的循环链表(头指针)

循环链表的操作算法与普通单链表基本相同，只是对表尾的判断有所改变。在循环链表chead中，判断表尾结点p的条件是p->next == chead，即当结点的后继指针指向表头结点时，说明已到表尾。

注意，创建循环链表时必须使其尾结点的后继指针指向表头结点，尤其是在尾结点后插入新结点时。

弃用头指针而采用尾指针，可方便地找到循环链表的开始结点和终端结点。如下图所示：

图6 带头结点的循环链表(尾指针)

1.3 双向循环链表

双向链表通常采用带表头结点的循环链表形式，即双向循环链表。双向循环链表在双向链表的基础上，将表头结点的前驱指针指向尾结点，尾结点的后驱指针指向头结点，首尾相连形成一个双向环。双向循环链表可方便地获取当前结点的前驱结点，不必像单向循环链表那样从头开始遍历；而其循环的特性又可方便地从任一结点出发单向遍历整个链表，不必像双向链表那样根据方向而使用不同的指针域。

带头结点的双向循环链表如下图所示：

图7 带头结点的双向循环链表

二实现

本节将采用C语言实现一个通用双向循环链表的创建及操作函数集。

文中“OMCI_”和“Omci”前缀为代码所在模块名信息，使用接口时可按需修改这些前缀。

2.1 数据结构

定义双向循环链表单元结构示意如下：

图8 双向循环链表单元结构示意图

其中，根结点的pHead字段指向链表头结点，pTail字段指向链表尾结点。头结点的pPrev字段指向尾结点，尾结点的pNext字段指向头结点。若链表为空(仅含头结点)，则pHead和pTail字段均指向头结点。

链表结点定义如下：

typedef struct T_OMCI_LIST_NODE{
struct T_OMCI_LIST_NODE *pPrev; /* 指向链表直接前驱结点的指针 */
struct T_OMCI_LIST_NODE *pNext; /* 指向链表直接后继结点的指针 */
VOID *pvNodeData; /* 指向链表数据的指针。获取具体数据时需显式转换该指针类型为目标类型 */
}T_OMCI_LIST_NODE;

相应地，链表定义如下：

typedef struct{
T_OMCI_LIST_NODE *pHead; /* 指向链表头结点的指针 */
T_OMCI_LIST_NODE *pTail; /* 指向链表尾结点的指针 */
INT32U dwNodeNum; /* 链表结点数目 */
INT32U dwNodeDataSize; /* 链表结点保存的数据字节数 */
}T_OMCI_LIST;

为支持不同的数据类型和数据结构(通用性)，链表结点数据域定义为VOID *pvNodeData指针。变量dwNodeDataSize指示数据域的数据宽度(字节数)。也可将数据宽度信息存储于头结点数据域内，从而不必定义变量dwNodeDataSize。通过遍历链表并计数可得结点数目，故变量dwNodeNum也并非必要。因此，dwNodeDataSize和dwNodeNum意在简化逻辑，也是“空间换时间”思想的体现。

除此之外，还定义以下状态值，以使链表内部状态透明化：

//链表函数返回状态枚举值
typedef enum{
OMCI_LIST_OK = (INT8U),
OMCI_LIST_ERROR = (INT8U)
}LIST_STATUS; //链表结点空闲情况枚举值
typedef enum{
OMCI_LIST_OCCUPIED = (INT8U),
OMCI_LIST_EMPTY = (INT8U),
OMCI_LIST_NULL = (INT8U)
}LIST_OCCUPATION; //BOOL型常量，适用于'Is'前缀函数
#define OMCI_LIST_TRUE (BOOL)1
#define OMCI_LIST_FALSE (BOOL)0

2.2 宏代码

为确保安全性，链表操作中需要进行大量的指针校验。因此，定义几个校验空指针的宏，以简化代码篇幅：

#define FUNC_NAME __FUNCTION__ //(__func__) /* 指针校验宏 */
//若无返回值则retVal置RETURN_VOID
#define RETURN_VOID
#define CHECK_SINGLE_POINTER(ptr1, retVal) do{\
if(NULL == (ptr1))
{ \
printf("[%s(%d)]Null Pointer: "#ptr1"!\n\r", FUNC_NAME, __LINE__); \
return retVal; \
} \
}while()
#define CHECK_DOUBLE_POINTER(ptr1, ptr2, retVal) do{\
if((NULL == (ptr1)) || (NULL == (ptr2))) \
{ \
printf("[%s(%d)]Null Pointer: "#ptr1"(%p), "#ptr2"(%p)!\n\r", FUNC_NAME, __LINE__, ptr1, ptr2); \
return retVal; \
} \
}while()
#define CHECK_TRIPLE_POINTER(ptr1, ptr2, ptr3, retVal) do{\
if((NULL == (ptr1)) || (NULL == (ptr2)) || (NULL == (ptr3))) \
{ \
printf("[%s(%d)]Null Pointer: "#ptr1"(%p), "#ptr2"(%p), "#ptr3"(%p)!\n\r", FUNC_NAME, __LINE__, ptr1, ptr2, ptr3); \
return retVal; \
} \
}while()

若待检查的指针中至少有一个指针为空时，校验宏打印所有待检查的指针值并退出。但其实现使得下面的语句在pList为空时崩溃(打印时试图访问pList->pHead等)：

CHECK_TRIPLE_POINTER(pList, pList->pHead, pList->pHead->pNext, OMCI_LIST_ERROR);

因此必须使用下面的分级校验以避免多级指针前级为NULL时访问本级出错：

CHECK_SINGLE_POINTER(pList, OMCI_LIST_ERROR);

CHECK_SINGLE_POINTER(pList->pHead, OMCI_LIST_ERROR);

CHECK_SINGLE_POINTER(pList->pHead->pNext, OMCI_LIST_ERROR);

若不打印各指针的值，则逻辑或(||)的运算顺序足矣保证CHECK_TRIPLE_POINTER写法的安全性。

注意，这些指针校验宏大量应用于2.3节函数接口中，以保证其安全性。使用者若能在外部杜绝空指针引用，则可添加条件编译开关“剔除”这些校验宏，以提高代码执行效率。

对于链表结点的操作比较固定，因此也用宏定义加以封装：

//创建结点为作为链表头以生成双向循环空链表
#define OMCI_INIT_NODE(pNode) do{ \
(pNode)->pNext = (pNode)->pPrev = (pNode); \
}while()
//"孤立"链表结点，避免通过该结点访问其前驱和后继结点(进而遍历链表)
#define OMCI_ISOL_NODE(pNode) do{ \
(pNode)->pNext = (pNode)->pPrev = NULL; \
}while()
//判断链表是否仅含头结点
#define OMCI_LIST_WITH_HEAD(pHeadNode) do{ \
(((pHeadNode)->pPrev == (pHeadNode)) && ((pHeadNode->pNext == pHeadNode))); \
}while() //插入链表结点
#define OMCI_INSERT_NODE(prevNode, insertNode) do{ \
(insertNode)->pNext = (prevNode)->pNext; \
(insertNode)->pPrev = (prevNode); \
(prevNode)->pNext->pPrev = (insertNode); \
(prevNode)->pNext = (insertNode); \
}while()
//删除链表结点
#define OMCI_REMOVE_NODE(removeNode) do{ \
(removeNode)->pPrev->pNext = (removeNode)->pNext; \
(removeNode)->pNext->pPrev = (removeNode)->pPrev; \
}while() //获取链表结点及其数据(不做安全性检查)
#define GET_NODE_NUM(pList) ((pList)->dwNodeNum)
#define GET_HEAD_NODE(pList) ((pList)->pHead)
#define GET_TAIL_NODE(pList) ((pList)->pTail)
#define GET_PREV_NODE(pNode) ((pNode)->pPrev)
#define GET_NEXT_NODE(pNode) ((pNode)->pNext)
#define GET_NODE_DATA(pNode) ((pNode)->pvNodeData) //双向循环链表遍历校验宏
#define LIST_ITER_CHECK(pList, retVal) do{\
CHECK_SINGLE_POINTER((pList), retVal); \
CHECK_SINGLE_POINTER((pList)->pHead, retVal); \
CHECK_SINGLE_POINTER((pList)->pHead->pNext, retVal); \
}while()
//双向循环链表遍历宏
//pList: 链表指针；pLoopNode: 链表结点，用作循环计数器；
//pTmpNode: 链表结点，用作删除pLoopNode时临时保存pLoopNode->pNext
//某些情况下采用遍历宏代替OmciLocateListNode或OmciTraverseListNode函数可提高执行效率。
//如外部数据和结点数据需按共同的规则转换时，采用遍历宏可使外部数据不必重复转换。
#define LIST_ITER_LOOP(pList, pLoopNode) \
for(pLoopNode = (pList)->pHead->pNext; \
pLoopNode != (pList)->pHead; \
pLoopNode = pLoopNode->pNext)
#define LIST_ITER_LOOP_SAFE(pList, pLoopNode, pTmpNode) \
for(pLoopNode = (pList)->pHead->pNext, pTmpNode = pLoopNode->pNext; \
pLoopNode != (pList)->pHead; \
pLoopNode = pTmpNode, pTmpNode = pLoopNode->pNext)

结点的插入和删除操作可参考1.1节双向链表的图例。GET_HEAD_NODE等宏可高效(但不安全)地获取链表结点及其数据，后续将给出其函数版本。LIST_ITER_LOOP宏旨在给使用者提供一定程度的自由度，某些情况下可提高执行效率。

2.3 函数接口

首先定义一组私有函数，主要是创建、删除和销毁链表结点。这些内部使用的函数已尽可能保证参数安全性，故省去参数校验处理。

为简便起见，下文中“XX指针”均表示指向XX的指针。

创建新的链表结点：

/**********************************************************************
* 函数名称： CreateListNode
* 功能描述：创建新的链表结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* VOID *pvNodeData :待插入的链表结点数据指针
* 输出参数： NA
* 返回值： T_OMCI_LIST_NODE*
***********************************************************************/
static T_OMCI_LIST_NODE *CreateListNode(T_OMCI_LIST *pList, VOID *pvNodeData)
{
T_OMCI_LIST_NODE *pInsertNode = (T_OMCI_LIST_NODE*)calloc((sizeof(T_OMCI_LIST_NODE)+pList->dwNodeDataSize), );
if(NULL == pInsertNode)
{
printf("[%s]pList(%p) failed to alloc for pInsertNode!\n", FUNC_NAME, pList);
return NULL;
} pInsertNode->pvNodeData = (INT8U *)pInsertNode + sizeof(T_OMCI_LIST_NODE);
if(NULL != pvNodeData)
{ //创建非头结点时
memmove(pInsertNode->pvNodeData, pvNodeData, pList->dwNodeDataSize);
} return pInsertNode;
}

删除指定的链表结点：

/**********************************************************************
* 函数名称： RemoveListNode
* 功能描述：删除指定的链表结点(释放结点内存并置其前驱后继指针为NULL)
* 输入参数： T_OMCI_LIST *pList :链表指针
* VOID *pvNode :待删除的链表结点指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：本函数未置待删除结点指针为NULL，请避免访问已删除结点
***********************************************************************/
static LIST_STATUS RemoveListNode(T_OMCI_LIST *pList, T_OMCI_LIST_NODE *pNode)
{
OMCI_ISOL_NODE(pNode);
free(pNode); //释放链表结点 return OMCI_LIST_OK;
}

OMCI_ISOL_NODE 宏用于"孤立"待删除的链表结点，避免通过该结点访问其前驱和后继结点(进而遍历链表)。因为RemoveListNode函数无法将结点指针置空(C语言值传递特性)，故调用者需注意避免再次使用已删除的结点。若要达到结点指针置空的目的，可调用销毁结点的接口函数：

/**********************************************************************
* 函数名称： DestroyListNode
* 功能描述：销毁指定的链表结点(释放结点内存并置结点指针为NULL)
* 输入参数： T_OMCI_LIST *pList :链表指针
* VOID **pNode :待销毁的链表结点指针的指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：当指向待销毁结点的指针存在多份拷贝且散布程序各处时(尤其当
* 调用链未能保证**pNode指向原始结点时)，无法彻底销毁该结点
***********************************************************************/
static LIST_STATUS DestroyListNode(T_OMCI_LIST *pList, T_OMCI_LIST_NODE **pNode)
{
free(*pNode); //释放链表结点
*pNode = NULL; return OMCI_LIST_OK;
}

DestroyListNode函数会释放指定结点的内存并将结点指针置空。但当代码中存在该结点指针的其他副本时，该函数显然无法将这些指针副本置空。

至于RemoveListNode和DestroyListNode函数孰优孰劣，可参考附注中对“迷途指针”的讨论。

有时可能需要获知链表的确切占用情况(通常没有必要)，如不含任何结点、仅含头结点或者还包含其他有用结点。GetListOccupation函数可满足这一“吹毛求疵”的需求，其他情况应使用下文将要给出的判空函数OmciIsListEmpty。OmciIsListEmpty将不含任何结点和仅含头结点均视为空链表，以隐藏内部细节。

/**********************************************************************
* 函数名称： GetListOccupation
* 功能描述：获取链表占用情况
* 输入参数： T_OMCI_LIST *pList :链表指针
* 输出参数： NA
* 返回值： LIST_OCCUPATION
* 注意事项：本函数仅用于内部测试。
***********************************************************************/
static LIST_OCCUPATION GetListOccupation(T_OMCI_LIST *pList)
{
CHECK_SINGLE_POINTER(pList, OMCI_LIST_NULL);
CHECK_SINGLE_POINTER(pList->pHead, OMCI_LIST_NULL); return ( == pList->dwNodeNum) ? OMCI_LIST_EMPTY : OMCI_LIST_OCCUPIED;
}

基于上述私有函数，可进一步构建链表及其结点的基本操作接口。

2.3.1 链表操作

使用链表前，必须对其初始化。初始化时将创建头结点，并确定后续将要链接的结点数据宽度。

/**********************************************************************
* 函数名称： OmciInitList
* 功能描述：链表初始化，产生空的双向循环链表
* 输入参数： T_OMCI_LIST *pList :链表指针
* INT32U dwNodeDataSize :链表结点保存的数据字节数
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
LIST_STATUS OmciInitList(T_OMCI_LIST *pList, INT32U dwNodeDataSize)
{
CHECK_SINGLE_POINTER(pList, OMCI_LIST_ERROR); if( == dwNodeDataSize)
{
printf("[%s]pList=%p, dwNodeDataSize=%uBytes, undesired initialization!\n",
FUNC_NAME, pList, dwNodeDataSize);
return OMCI_LIST_ERROR;
}
pList->dwNodeDataSize = dwNodeDataSize; //给予重新修改结点数据大小的机会 if(NULL != pList->pHead)
{
printf("[%s]pList(%p) has been initialized!\n", FUNC_NAME, pList);
return OMCI_LIST_OK;
} T_OMCI_LIST_NODE *pHeadNode = CreateListNode(pList, NULL);
if(NULL == pHeadNode)
{
printf("[%s]pList(%p) failed to create pHeadNode!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_INIT_NODE(pHeadNode);
pList->pHead = pList->pTail = pHeadNode;
pList->dwNodeNum = ; return OMCI_LIST_OK;
}

通常不会中途修改dwNodeDataSize。仅当使用者确知数据宽度的变化边界(如确知前N个结点数据为四字节，其后为八字节)时，中途修改dwNodeDataSize才有意义。当然，也可新增一个OmciResizeList接口。

调用OmciInitList接口后，将创建一张仅含头结点的空双向循环链表。此后可向链表中插入结点。

暂时不需要当前链表时，可清空链表除头结点外的结点。这样再次使用时无需初始化链表，直接插入结点即可。若确定不再需要当前链表时，可销毁链表的所有结点。OmciClearList和OmciDestroyList函数分别完成链表的清空和销毁。

/**********************************************************************
* 函数名称： OmciClearList
* 功能描述：清空双向循环链表除头结点外的结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：清空链表结点后，再次插入结点时不需要初始化链表。
***********************************************************************/
LIST_STATUS OmciClearList(T_OMCI_LIST *pList)
{
LIST_ITER_CHECK(pList, OMCI_LIST_ERROR); T_OMCI_LIST_NODE *pNextNode, *pListNode = pList->pHead->pNext;
while(pListNode != pList->pHead)
{
pNextNode = pListNode->pNext;
RemoveListNode(pList, pListNode);
pListNode = pNextNode;
} OMCI_INIT_NODE(pList->pHead);
pList->pTail = pList->pHead;
pList->dwNodeNum = ; return OMCI_LIST_OK;
}
/**********************************************************************
* 函数名称： OmciDestroyList
* 功能描述：销毁双向循环链表，包括头结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：销毁链表后，再次插入结点时需要初始化链表。
***********************************************************************/
LIST_STATUS OmciDestroyList(T_OMCI_LIST *pList)
{
LIST_ITER_CHECK(pList, OMCI_LIST_ERROR); T_OMCI_LIST_NODE *pNextNode, *pListNode = pList->pHead->pNext;
while(pListNode != pList->pHead)
{
pNextNode = pListNode->pNext;
DestroyListNode(pList, &pListNode);
pListNode = pNextNode;
} DestroyListNode(pList, &(pList->pHead)); //销毁头结点
pList->pTail = NULL; //尾结点指针置空
pList->dwNodeNum = ;
pList->dwNodeDataSize = ; return OMCI_LIST_OK;
}

清空或销毁链表后，OmciIsListEmpty函数的返回值将为逻辑真，表明当前链表为空。

/**********************************************************************
* 函数名称： OmciIsListEmpty
* 功能描述：判断链表是否为空(仅含头结点或不含任何结点)
* 输入参数： T_OMCI_LIST *pList :链表指针
* 输出参数： NA
* 返回值： BOOL
***********************************************************************/
BOOL OmciIsListEmpty(T_OMCI_LIST *pList)
{
CHECK_SINGLE_POINTER(pList, OMCI_LIST_TRUE);
CHECK_SINGLE_POINTER(pList->pHead, OMCI_LIST_TRUE); T_OMCI_LIST_NODE *pHeadNode = pList->pHead;
if(( == pList->dwNodeNum) &&
(pHeadNode->pPrev == pHeadNode) && //冗余校验以加强安全性
(pHeadNode->pNext == pHeadNode))
{
return OMCI_LIST_TRUE;
}
else
{
return OMCI_LIST_FALSE;
}
}

此处为加强安全性对头结点进行检验，但并非必要。若剔除冗余校验，则OmciIsListEmpty函数的实现会更为简洁高效。

2.3.2 结点操作

链表初始化后，可在链表头结点后逆序或顺序依次插入新的结点。当从头结点向后继方向遍历时，逆序插入的行为类似于栈，而顺序插入的行为类似于队列。

/**********************************************************************
* 函数名称： OmciPrependListNode
* 功能描述：在链表头结点后逆序增加结点，尾结点恒为头结点
* 在头结点指针pHead所指向结点和pHead->pNext所指向结点
* 之间插入新结点，先插入的结点向右移动。遍历链表时
* 从pHead开始向右依次访问至最先插入的结点，类似于栈。
* 输入参数： T_OMCI_LIST *pList :链表指针
* VOID *pvNodeData :待插入的链表结点数据指针
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
LIST_STATUS OmciPrependListNode(T_OMCI_LIST *pList, VOID *pvNodeData)
{
CHECK_DOUBLE_POINTER(pList, pvNodeData, OMCI_LIST_ERROR); if( == pList->dwNodeDataSize)
{
printf("[%s]pList=%p, dwNodeDataSize=0Bytes, probably uninitialized or initialized improperly. See 'OmciInitList'!\n",
FUNC_NAME, pList);
return OMCI_LIST_ERROR;
}
T_OMCI_LIST_NODE *pInsertNode = CreateListNode(pList, pvNodeData);
if(NULL == pInsertNode)
{
printf("[%s]pList(%p) failed to create pInsertNode!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_INSERT_NODE(pList->pHead, pInsertNode); //在链表头结点后增加一个结点 pList->dwNodeNum++; return OMCI_LIST_OK;
} /**********************************************************************
* 函数名称： OmciAppendListNode
* 功能描述：在链表头结点后顺序增加结点，新结点作为尾结点
* 在头结点指针pHead所指向结点前(即尾结点后)插入新结点，
* 先插入的结点向左移动。遍历链表时从pHead开始向右依次
* 访问至最后插入的结点，类似于队列。
* 双向循环链表已保证pList->pTail(即pHead->pPrev)非空。
* 输入参数： T_OMCI_LIST *pList :链表指针
* VOID *pvNodeData :待插入的链表结点数据指针
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
LIST_STATUS OmciAppendListNode(T_OMCI_LIST *pList, VOID *pvNodeData)
{
CHECK_DOUBLE_POINTER(pList, pvNodeData, OMCI_LIST_ERROR); if( == pList->dwNodeDataSize)
{
printf("[%s]pList=%p, dwNodeDataSize=0Bytes, probably uninitialized or initialized improperly. See 'OmciInitList'!\n",
FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} T_OMCI_LIST_NODE *pInsertNode = CreateListNode(pList, pvNodeData);
if(NULL == pInsertNode)
{
printf("[%s]pList(%p) failed to create pInsertNode!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_INSERT_NODE(pList->pTail, pInsertNode); //在链表尾结点后增加一个结点
pList->pTail = pInsertNode; //新的尾结点指向当前添加的结点 pList->dwNodeNum++; return OMCI_LIST_OK;
}

对dwNodeDataSize 的校验用于指示链表未初始化或未正确初始化的错误。将该校验置于私有函数CreateListNode中可简化Prepend和Append代码。但FUNC_NAME信息将暴露内部函数，从而给使用者造成疑惑，故该校验予以保留。

有时需要在链表中任意位置插入结点，此时可使用OmciInsertListNode接口。

/**********************************************************************
* 函数名称： OmciInsertListNode
* 功能描述：在链表中任意位置插入结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* T_OMCI_LIST_NODE *pPrevNode :待插入结点的前驱结点指针
* VOID *pvNodeData :待插入结点的数据域指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：若pPrevNode恒为头结点或尾结点，请使用OmciPrependListNode
* 或OmciAppendListNode函数
***********************************************************************/
LIST_STATUS OmciInsertListNode(T_OMCI_LIST *pList, T_OMCI_LIST_NODE *pPrevNode, VOID *pvNodeData)
{
CHECK_TRIPLE_POINTER(pList, pPrevNode, pvNodeData, OMCI_LIST_ERROR); if( == pList->dwNodeDataSize)
{
printf("[%s]pList=%p, dwNodeDataSize=0Bytes, probably uninitialized or initialized improperly. See 'OmciInitList'!\n",
FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} T_OMCI_LIST_NODE *pInsertNode = CreateListNode(pList, pvNodeData);
if(NULL == pInsertNode)
{
printf("[%s]pList(%p) failed to create pInsertNode!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_INSERT_NODE(pPrevNode, pInsertNode);
if(pPrevNode == pList->pTail)
pList->pTail = pInsertNode; pList->dwNodeNum++; return OMCI_LIST_OK;
}

当pPrevNode恒为头结点时，OmciInsertListNode接口等效于OmciPrependListNode；当pPrevNode恒为尾结点时，OmciInsertListNode接口等效于OmciAppendListNode。这两种情况建议使用Prepend或Append接口(毕竟减少一个参数)。

插入若干结点后，就可删除或销毁链表中除头结点外的任一结点。

/**********************************************************************
* 函数名称： OmciRemoveListNode
* 功能描述：删除双向循环链表中除头结点外的某一结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* T_OMCI_LIST_NODE *pNode :待删除的链表结点指针
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
LIST_STATUS OmciRemoveListNode(T_OMCI_LIST *pList, T_OMCI_LIST_NODE *pNode)
{
CHECK_DOUBLE_POINTER(pList, pNode, OMCI_LIST_ERROR);
CHECK_DOUBLE_POINTER(pNode->pPrev, pNode->pNext, OMCI_LIST_ERROR); if( == pList->dwNodeNum)
{
printf("[%s]pList(%p) has no node to be Removed!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_REMOVE_NODE(pNode);
if(pNode->pNext == pList->pHead)
{
pList->pTail = pNode->pPrev; //删除尾结点
} RemoveListNode(pList, pNode);
pList->dwNodeNum--; return OMCI_LIST_OK;
}
/**********************************************************************
* 函数名称： OmciDestroyListNode
* 功能描述：销毁双向循环链表中除头结点外的某一结点
* 输入参数： T_OMCI_LIST *pList :链表指针
* T_OMCI_LIST_NODE **pNode :待销毁的链表结点二级指针
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
LIST_STATUS OmciDestroyListNode(T_OMCI_LIST *pList, T_OMCI_LIST_NODE **pNode)
{
CHECK_DOUBLE_POINTER(pList, pNode, OMCI_LIST_ERROR);
CHECK_SINGLE_POINTER(*pNode, OMCI_LIST_ERROR); if( == pList->dwNodeNum)
{
printf("[%s]pList(%p) has no node to be Removed!\n", FUNC_NAME, pList);
return OMCI_LIST_ERROR;
} OMCI_REMOVE_NODE(*pNode);
if((*pNode)->pNext == pList->pHead)
{
pList->pTail = (*pNode)->pPrev; //删除尾结点
} DestroyListNode(pList, pNode);
pList->dwNodeNum--; return OMCI_LIST_OK;
}

然而，要删除或销毁链表结点，必须先定位到该结点。

在链表中“定位”某个结点有两种手段：一是通过结点编号查找，如OmciGetListNodeByIndex；二是通过某种给定条件匹配，如OmciLocateListNode(查找首个满足给定条件的结点)。

/**********************************************************************
* 函数名称： OmciGetListNodeByIndex
* 功能描述：获取链表中指定序号的结点(按头结点后继方向排序)
* 输入参数： T_OMCI_LIST* pList :链表指针
* INT32U dwNodeIndex :结点序号(从1开始)
* 输出参数： NA
* 返回值： T_OMCI_LIST_NODE* 链表结点指针(空表返回NULL)
***********************************************************************/
T_OMCI_LIST_NODE* OmciGetListNodeByIndex(T_OMCI_LIST *pList, INT32U dwNodeIndex)
{
CHECK_SINGLE_POINTER(pList, NULL); if( == dwNodeIndex)
return pList->pHead; //也可返回NULL
if(dwNodeIndex >= pList->dwNodeNum)
return pList->pTail; INT32U dwNodeIdx = ;
T_OMCI_LIST_NODE *pListNode = pList->pHead;
for(; dwNodeIdx <= dwNodeIndex; dwNodeIdx++)
pListNode = pListNode->pNext; return pListNode;
}
/**********************************************************************
* 函数名称： OmciLocateListNode
* 功能描述：查找链表中首个与pData满足函数fpCompareNode判定关系的结点
* 输入参数： T_OMCI_LIST* pList :链表指针
* VOID* pvData :待比较数据指针
* CompareNodeFunc fpCompareNode :比较回调函数指针
* 输出参数： NA
* 返回值： T_OMCI_LIST_NODE* 链表结点指针(未找到时返回NULL)
***********************************************************************/
/* 比较回调函数原型，用来自定义链表节点比较 */
typedef INT8U (*CompareNodeFunc)(VOID *pvNodeData, VOID *pvData, INT32U dwNodeDataSize);
T_OMCI_LIST_NODE* OmciLocateListNode(T_OMCI_LIST *pList, VOID *pvData, CompareNodeFunc fpCompareNode)
{
CHECK_TRIPLE_POINTER(pList, pvData, fpCompareNode, NULL);
CHECK_SINGLE_POINTER(pList->pHead, NULL);
CHECK_SINGLE_POINTER(pList->pHead->pNext, NULL); T_OMCI_LIST_NODE *pListNode = pList->pHead->pNext;
while(pListNode != pList->pHead)
{
if( == fpCompareNode(pListNode->pvNodeData, pvData, pList->dwNodeDataSize))
return pListNode; pListNode = pListNode->pNext;
} return NULL;
}

可见，OmciLocateListNode接口本质上就是“遍历+匹配”。要进行单纯而强大的遍历操作，可使用OmciTraverseListNode接口。

/**********************************************************************
* 函数名称： OmciTraverseListNode
* 功能描述：链表结点遍历函数，遍历操作由fpTravNode指定
* 输入参数： T_OMCI_LIST* pList :链表指针
* VOID* pvTravInfo :遍历操作回调函数所需信息
* 也可为空，取决于回调函数具体实现
* TravNodeFunc fpTravNode :遍历操作回调函数指针
* 输出参数： NA
* 返回值： LIST_STATUS
* 注意事项：本函数可间接实现Print等操作，但不建议代替后者。
* fpTravNode返回非0(OMCI_LIST_OK)值时中止遍历
***********************************************************************/
typedef LIST_STATUS (*TravNodeFunc)(VOID *pvNode, VOID *pvTravInfo, INT32U dwNodeDataSize);
LIST_STATUS OmciTraverseListNode(T_OMCI_LIST *pList, VOID *pvTravInfo, TravNodeFunc fpTravNode)
{
CHECK_DOUBLE_POINTER(pList, fpTravNode, OMCI_LIST_ERROR);
CHECK_SINGLE_POINTER(pList->pHead, OMCI_LIST_ERROR);
CHECK_SINGLE_POINTER(pList->pHead->pNext, OMCI_LIST_ERROR); T_OMCI_LIST_NODE *pListNode = pList->pHead->pNext;
while(pListNode != pList->pHead)
{
T_OMCI_LIST_NODE *pTmpNode = pListNode->pNext; //fpTravNode内可能会销毁结点pListNode
if(OMCI_LIST_OK != fpTravNode(pListNode, pvTravInfo, pList->dwNodeDataSize))
break; pListNode = pTmpNode;
} return OMCI_LIST_OK;
}

因为OmciAppendListNode和OmciPrependListNode已暗含“正序”和“逆序”的意思，故仅提供OmciTraverseListNode函数，而无需再增加逆序遍历的接口(除非需要同时双序遍历)。

常常需要打印输出链表结点的数据域内容，而OmciTraverseListNode接口稍显笨重。此时可使用专门的打印接口OmciPrintListNode。

/**********************************************************************
* 函数名称： OmciPrintListNode
* 功能描述：打印输出链表结点的数据域内容
* 输入参数： T_OMCI_LIST* pList :链表指针
* PrintListFunc fpPrintList :打印回调函数指针
* 输出参数： NA
* 返回值： LIST_STATUS
***********************************************************************/
/* 打印回调函数原型，用来自定义链表内容打印 */
typedef VOID (*PrintListFunc)(VOID *pNodeData, INT32U dwNodeNum);
LIST_STATUS OmciPrintListNode(T_OMCI_LIST *pList, PrintListFunc fpPrintList)
{
CHECK_DOUBLE_POINTER(pList, fpPrintList, OMCI_LIST_ERROR);
CHECK_SINGLE_POINTER(pList->pHead, OMCI_LIST_ERROR);
CHECK_SINGLE_POINTER(pList->pHead->pNext, OMCI_LIST_ERROR); T_OMCI_LIST_NODE *pListNode = pList->pHead->pNext;
while(pListNode != pList->pHead)
{
//具体打印格式交给回调函数灵活处理(可直接打印也可拷贝至本地处理后打印)
fpPrintList(pListNode->pvNodeData, pList->dwNodeNum);
pListNode = pListNode->pNext;
}
printf("\n"); return OMCI_LIST_OK;
}

对于CompareNodeFunc 和PrintListFunc，以下给出两个范例：

/**********************************************************************
* 函数名称： CompareNodeGeneric
* 功能描述：通用链表结点内存比较
* 输入参数： VOID *pvNodeData :链表结点数据指针
* VOID *pvData :待比较外部数据指针
* INT32U dwNodeDataSize :链表结点数据大小
* 输出参数： NA
* 返回值： 0：Equal; !0:Unequal
* 注意事项：比较长度为结点数据字节数，即默认与外部数据大小一致
***********************************************************************/
INT8U CompareNodeGeneric(VOID *pvNodeData, VOID *pvData, INT32U dwNodeDataSize)
{
CHECK_DOUBLE_POINTER(pvNodeData, pvData, );
return memcmp(pvNodeData, pvData, dwNodeDataSize);
}
/**********************************************************************
* 函数名称： PrintListWord
* 功能描述：打印链表结点，结点数据域为两字节整数
* 输入参数： VOID *pvNodeData :链表节点数据指针
* INT32U dwNodeNum :链表节点数目
* 输出参数： NA
* 返回值： VOID
* 注意事项：仅作示例，未考虑字节序等问题。
***********************************************************************/
VOID PrintListWord(VOID *pvNodeData, INT32U dwNodeNum)
{
CHECK_SINGLE_POINTER(pvNodeData, RETURN_VOID);
printf("%d ", *((INT16U *)pvNodeData));
}

最后，给出获取链表结点及其数据的安全接口：

/**********************************************************************
* 函数名称： OmciGetListNodeNum
* 功能描述：获取链表结点数目
* 输入参数： T_OMCI_LIST *pList :链表指针
* 输出参数： NA
* 返回值： INT32U 链表结点数目
***********************************************************************/
INT32U OmciGetListNodeNum(T_OMCI_LIST *pList)
{
CHECK_SINGLE_POINTER(pList, );
return (pList->dwNodeNum);
} /**********************************************************************
* 函数名称： OmciGetListHead/OmciGetListTail
* 功能描述：获取链表头结点/尾结点指针
* 输入参数： T_OMCI_LIST *pList :链表指针
***********************************************************************/
T_OMCI_LIST_NODE* OmciGetListHead(T_OMCI_LIST *pList)
{
CHECK_SINGLE_POINTER(pList, NULL);
return (pList->pHead);
}
T_OMCI_LIST_NODE* OmciGetListTail(T_OMCI_LIST *pList)
{
CHECK_SINGLE_POINTER(pList, NULL);
return (pList->pTail);
} /**********************************************************************
* 函数名称： OmciGetPrevNode/OmciGetNextNode
* 功能描述：获取链表指定结点的前驱结点/后继结点指针
* 输入参数： T_OMCI_LIST_NODE *pNode :指定结点的指针
***********************************************************************/
T_OMCI_LIST_NODE* OmciGetPrevNode(T_OMCI_LIST_NODE *pNode)
{
CHECK_SINGLE_POINTER(pNode, NULL);
return (pNode->pPrev);
}
T_OMCI_LIST_NODE* OmciGetNextNode(T_OMCI_LIST_NODE *pNode)
{
CHECK_SINGLE_POINTER(pNode, NULL);
return (pNode->pNext);
} /**********************************************************************
* 函数名称： OmciGetNodeData
* 功能描述：获取链表指定结点的数据域
* 输入参数： T_OMCI_LIST_NODE *pNode :指定结点的指针
***********************************************************************/
VOID* OmciGetNodeData(T_OMCI_LIST_NODE *pNode)
{
CHECK_DOUBLE_POINTER(pNode, pNode->pvNodeData, NULL);
return (pNode->pvNodeData);
}

三测试

本节将对上文实现的链表操作接口进行测试，测试函数兼作使用示例。

#ifdef TEST_AND_EXAMPLE static LIST_STATUS TravPrintWord(VOID *pvNode, VOID *pvTravInfo, INT32U dwNodeDataSize)
{
CHECK_SINGLE_POINTER(pvNode, OMCI_LIST_ERROR);
T_OMCI_LIST_NODE *pNode = (T_OMCI_LIST_NODE *)pvNode;
printf("%d ", *((INT16U *)GET_NODE_DATA(pNode)));
return OMCI_LIST_OK;
} T_OMCI_LIST gExampleList = {};
VOID ListTestExample(VOID)
{ //本函数并非严格意义上的测试函数，主要用作示例，且示例并非最佳用法。
INT8U ucTestIndex = ;
INT16U aTestListData[] = {, , , , , }; printf("\n<Test Case %u>: Initialization!\n", ucTestIndex++);
OmciInitList(&gExampleList, sizeof(INT16U));
printf("gExampleList=%p, pHead=%p, pTail=%p\n", &gExampleList,
OmciGetListHead(&gExampleList), OmciGetListTail(&gExampleList)); printf("\n<Test Case %u>: Append Node to List!\n", ucTestIndex++);
OmciAppendListNode(&gExampleList, &aTestListData[]);
OmciAppendListNode(&gExampleList, &aTestListData[]);
OmciAppendListNode(&gExampleList, &aTestListData[]);
printf("OmciIsListEmpty=%u(0-Occupied; 1-Empty)\n", OmciIsListEmpty(&gExampleList));
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList));
OmciPrintListNode(&gExampleList, PrintListWord); printf("\n<Test Case %u>: Insert Node to List!\n", ucTestIndex++);
T_OMCI_LIST_NODE *pPrevNode = OmciGetListNodeByIndex(&gExampleList, );
printf("NodeData2=%d\n", *((INT16U *)OmciGetNodeData(pPrevNode)));
OmciInsertListNode(&gExampleList, pPrevNode, &aTestListData[]);
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList));
OmciPrintListNode(&gExampleList, PrintListWord); printf("\n<Test Case %u>: Remove Node from List!\n", ucTestIndex++);
T_OMCI_LIST_NODE *pDeleteNode = OmciLocateListNode(&gExampleList, &aTestListData[], CompareNodeGeneric);
OmciRemoveListNode(&gExampleList, pDeleteNode);
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList));
OmciPrintListNode(&gExampleList, PrintListWord); printf("\n<Test Case %u>: Clear List!\n", ucTestIndex++);
OmciClearList(&gExampleList);
printf("gExampleList=%p, pHead=%p, pTail=%p\n", &gExampleList,
GET_HEAD_NODE(&gExampleList), GET_TAIL_NODE(&gExampleList));
printf("OmciIsListEmpty=%u(0-Occupied; 1-Empty)\n", OmciIsListEmpty(&gExampleList));
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList)); printf("\n<Test Case %u>: Prepend Node to List!\n", ucTestIndex++);
OmciPrependListNode(&gExampleList, &aTestListData[]);
OmciPrependListNode(&gExampleList, &aTestListData[]);
OmciPrependListNode(&gExampleList, &aTestListData[]);
printf("OmciIsListEmpty=%u(0-Occupied; 1-Empty)\n", OmciIsListEmpty(&gExampleList));
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList));
OmciPrintListNode(&gExampleList, PrintListWord); T_OMCI_LIST_NODE *pListNode = NULL;
LIST_ITER_LOOP(&gExampleList, pListNode)
{
printf("%d ", *((INT16U *)GET_NODE_DATA(pListNode)));
}
printf("\n"); OmciTraverseListNode(&gExampleList, NULL, TravPrintWord);
printf("\n"); printf("\n<Test Case %u>: Destory List!\n", ucTestIndex++);
OmciDestroyList(&gExampleList);
printf("gExampleList=%p, pHead=%p, pTail=%p\n", &gExampleList,
GET_HEAD_NODE(&gExampleList), GET_TAIL_NODE(&gExampleList));
printf("gExampleList NodeNum=%u\n", OmciGetListNodeNum(&gExampleList));
printf("GetListOccupation=%u(0-Occupied; 1-Empty; 2-Null)\n", GetListOccupation(&gExampleList));
return;
} #endif

在上述测试代码中，Prepend或Append结点的代码若用OmciInsertListNode实现，如下：

OmciInsertListNode(&gExampleList, OmciGetListHead(&gExampleList), &aTestListData[]);
OmciInsertListNode(&gExampleList, OmciGetListHead(&gExampleList), &aTestListData[]);
OmciInsertListNode(&gExampleList, OmciGetListHead(&gExampleList), &aTestListData[]);
//Or
OmciInsertListNode(&gExampleList, OmciGetListTail(&gExampleList), &aTestListData[]);
OmciInsertListNode(&gExampleList, OmciGetListTail(&gExampleList), &aTestListData[]);
OmciInsertListNode(&gExampleList, OmciGetListTail(&gExampleList), &aTestListData[]);

测试结果如下所示：

<Test Case 1>: Initialization!
gExampleList=0x804bc8c, pHead=0x8b39010, pTail=0x8b39010 <Test Case 2>: Append Node to List!
OmciIsListEmpty=0(0-Occupied; 1-Empty)
gExampleList NodeNum=3
11 22 33 <Test Case 3>: Insert Node to List!
NodeData2=22
gExampleList NodeNum=4
11 22 55 33 <Test Case 4>: Remove Node from List!
gExampleList NodeNum=3
11 55 33 <Test Case 5>: Clear List!
gExampleList=0x804bc8c, pHead=0x8b39010, pTail=0x8b39010
OmciIsListEmpty=1(0-Occupied; 1-Empty)
gExampleList NodeNum=0 <Test Case 6>: Prepend Node to List!
OmciIsListEmpty=0(0-Occupied; 1-Empty)
gExampleList NodeNum=3
66 55 44
66 55 44
66 55 44 <Test Case 7>: Destory List!
gExampleList=0x804bc8c, pHead=(nil), pTail=(nil)
gExampleList NodeNum=0
[GetListOccupation(140)]Null Pointer: pList->pHead!
GetListOccupation=2(0-Occupied; 1-Empty; 2-Null)

四附注

迷途指针(Dangling pointer，亦称悬垂指针)和野指针(Wild pointer)

迷途指针：所指向的对象被释放或收回，但该指针仍指向原对象的内存地址(想象被强拆后无家可归的人...)。
野指针：指针在使用之前未进行必要的初始化(未显式初始化的静态指针不是野指针)。

可见，迷途指针和野指针均指向不合法的对象，应禁止读写其指向的内存。野指针简单且易于处理，以下主要讨论迷途指针。

在C语言中，当指针所指向的动态内存被显式地释放(free)后，该指针就成为迷途指针。若通过迷途指针访问或修改已释放的动态分配内存，则可能引发难以排查的故障(尤其当原对象内存分配作他用时)。若指针是函数内的自动变量，函数退出时会被自动销毁；否则，最好在释放动态内存后将该指针置空(NULL)。虽然将迷途指针重新置空的做法可能隐藏诸如double free之类的逻辑问题，但却使得对它的读写错误更容易暴露(尤其是在多线程环境中)。
在C语言中，可通过下述两种free替代版本来尽可能避免迷途指针错误：

#define SAFE_FREE((pointer)) do{ \
if(pointer != NULL){ \
free(pointer); \
pointer = NULL; \
}while(); void SafeFree(void **pointer)
{
if(pointer != NULL)
{
free(*pointer);
*pointer = NULL;
}
}

然而，当指向动态分配内存的指针存在多个副本且散布程序各处时，该技术不会置空其他指针变量，从而导致释放后指针行为的不一致。因此，编码者应保证每个指针都有其明确的用途和生存期。

注意，因为C语言的值传递特性，现有的free库函数内不可能将入参指针置空。若要达到置空的目的，必须传入二级指针，如SafeFree。但SafeFree必然与其内存分配版本(如SafeAlloc)的入参类型不一致，这会增加使用者出错的机率。而由上面的讨论可知，即使置空当前入参指针，也无法清除其副本。因此，最好由调用者自行决定如何置空。至于作者倾向于free还是SafeFree，可参考《关于Linux系统basename函数缺陷的思考》一文，或者试想下逐级释放的顺序性。
另一种常见的迷途指针产生于试图返回栈上分配的局部变量的地址。详见《已释放的栈内存》一文。

正文

说明