C语言的本质（16）——函数接口的传入参数与传出参数

如果函数接口有指针参数，既可以把指针所指向的数据传给函数使用（称为传入参数），也可以由函数填充指针所指的内存空间，传回给调用者使用（称为传出参数），例如strcpy的函数原型为

char *strcpy(char *dest, const char *src);

其中src参数是传入参数，dest参数是传出参数。有些函数的指针参数同时担当了这两种角色，如select函数。其函数原型为：

int select(int nfds, fd_set *readfds,fd_set *writefds,
        fd_set *exceptfds, struct timeval*timeout);

其中的fd_set *参数，既是传入参数又是传出参数，这称为Value-result参数。

传入参数示例：

假如我们实现一个函数，其参数通过地址来传入一个值，其原型如下：

void func(const unit_t *p);

其调用者与实现者之间的协议如下：

调用者	实现者
1、分配p所指的内存空间； 2、在p所指的内存空间中保存数据； 3、调用函数； 4、由于有const限定符，调用者可以确信p所指的内存空间不会被改变。	1、规定指针参数的类型unit_t *； 2、读取p所指的内存空间。

传出参数示例：

假如我们实现一个函数，其参数通过地址传出一个值，其原型如下：

void func(unit_t *p);

其调用者与实现者之间的协议如下：

调用者	实现者
1、分配p所指的内存空间 2、调用函数 3、读取p所指的内存空间	1、规定指针参数的类型unit_t * 2、在p所指的内存空间中保存数据

Value-result参数示例：

void func(unit_t *p);

其调用者与实现者之间的协议如下：

调用者	实现者
1、分配p所指的内存空间 2、在p所指的内存空间保存数据 3、调用函数 4、读取p所指的内存空间	1、规定指针参数的类型unit_t * 2、读取p所指的内存空间 3、改写p所指的内存空间

注意：由于传出参数和Value-result参数的函数接口完全相同，应该在文档中说明是哪种参数。

很多系统函数对于指针参数是NULL的情况有特殊规定：如果传入参数是NULL表示取缺省值，例如pthread_create(3)的pthread_attr_t *参数，也可能表示不做特别处理，例如free的参数；如果传出参数是NULL表示调用者不需要传出值，例如time(2)的参数。这些特殊规定应该在文档中写清楚。

下面是一个传出参数的完整例子：

/* populator.h */
#ifndef POPULATOR_H
#define POPULATOR_H
typedef struct {
    int number;
    char msg[20];
} unit_t;
extern void set_unit(unit_t *);
#endif

/* populator.c */
#include <string.h>
#include "populator.h"
void set_unit(unit_t *p)
{
    if (p == NULL)
         return; /* ignore NULL parameter */
    p->number = 3;
    strcpy(p->msg, "Hello World!");
}

/* main.c */
#include <stdio.h>
#include "populator.h"
int main(void)
{
    unit_t u;
    set_unit(&u);
    printf("number: %d\nmsg: %s\n", u.number, u.msg);
    return 0;
}

二级指针的参数：

二级指针也是指针，同样可以表示传入参数、传出参数或者Value-result参数，只不过该参数所指的内存空间应该解释成一个指针变量。用两层指针做传出参数的系统函数也很常见，比如pthread_join(3)的void **参数。下面看一个简单的例子。

二级指针做传出参数

/* redirect_ptr.h */
#ifndef REDIRECT_PTR_H
#define REDIRECT_PTR_H
extern void get_a_day(const char **);
#endif

这里的参数指针是const char **，有const限定符，却不是传入参数而是传出参数。

/* redirect_ptr.c */
#include "redirect_ptr.h"

static const char *msg[] ={"Sunday", "Monday", "Tuesday","Wednesday",
                            "Thursday","Friday", "Saturday"};
void get_a_day(const char **pp)
{
    static int i = 0;
    *pp = msg[i%7];
    i++;
}

/* main.c */
#include <stdio.h>
#include "redirect_ptr.h"

int main(void)
{
    const char *firstday = NULL;
    const char *secondday = NULL;
    get_a_day(&firstday);
    get_a_day(&secondday);
    printf("%s\t%s\n", firstday, secondday);
    return 0;
}

二级指针作为传出参数还有一种特别的用法，可以在函数中分配内存，调用者通过传出参数取得指向该内存的指针，一般来说，实现一个分配内存的函数就要实现一个释放内存的函数。

通过参数分配内存示例：

void alloc_unit(unit_t **pp);
void free_unit(unit_t *p);

其调用者与实现者之间的协议如下：

调用者	实现者
1、分配pp所指的指针变量的空间； 2、调用alloc_unit分配内存； 3、读取pp所指的指针变量，通过后者使用alloc_unit分配的内存； 4、调用free_unit释放内存。	1、规定指针参数的类型unit_t **； 2、alloc_unit分配unit_t的内存并初始化，为pp所指的指针变量赋值； 3、free_unit释放在alloc_unit中分配的内存

下面是一个通过二级指针参数分配内存的例子

/* para_allocator.h */
#ifndef PARA_ALLOCATOR_H
#define PARA_ALLOCATOR_H
typedef struct {
    int number;
    char *msg;
} unit_t;

extern void alloc_unit(unit_t **);
extern void free_unit(unit_t *);

#endif

/* para_allocator.c */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "para_allocator.h"

void alloc_unit(unit_t **pp)
{
    unit_t *p = malloc(sizeof(unit_t));
    if(p == NULL) {
           printf("out of memory\n");
           exit(1);
    }
    p->number = 3;
    p->msg = malloc(20);
    strcpy(p->msg, "Hello World!");
    *pp = p;
}

void free_unit(unit_t *p)
{
    free(p->msg);
    free(p);
}

/* main.c */
#include <stdio.h>
#include "para_allocator.h"

int main(void)
{
    unit_t *p = NULL;

    alloc_unit(&p);
    printf("number: %d\nmsg: %s\n", p->number, p->msg);
     free_unit(p);
    p = NULL;
    return 0;
}

二级指针参数如果是传出的，可以有两种情况：

第一种情况，传出的指针指向静态内存（比如上面的例子），或者指向已分配的动态内存（比如指向某个链表的节点）；

第二种情况是在函数中动态分配内存，然后传出的指针指向这块内存空间，这种情况下调用者应该在使用内存之后调用释放内存的函数，调用者的责任是请求分配和请求释放内存，实现者的责任是完成分配内存和释放内存的操作。由于这两种情况的函数接口相同，我们在撰写文档或添加注释时应该说明是哪一种情况。

返回值是指针的情况

返回值显然是传出的而不是传入的，如果返回值传出的是指针，和通过参数传出指针的情况类似，也分为两种情况：

第一种是传出指向静态内存或已分配的动态内存的指针；

第二种是在函数中动态分配内存并传出指向这块内存的指针，这种情况通常还要实现一个释放内存的函数，所以有和malloc对应的free。由于这两种情况的函数接口相同，应该在文档中说明是哪一种情况。

返回指向已分配内存的指针示例：

unit_t *func(void);

其调用者与实现者之间的协议如下：

调用者	实现者
1、调用函数 2、将返回值保存下来以备后用	1、规定返回值指针的类型unit_t * 2、返回一个指针

下面的例子演示返回指向已分配内存的指针

/* ret_ptr.h */
#ifndef RET_PTR_H
#define RET_PTR_H

extern char *get_a_day(int idx);

#endif

/* ret_ptr.c */
#include <string.h>
#include "ret_ptr.h"

static const char *msg[] = {"Sunday","Monday", "Tuesday", "Wednesday",
                            "Thursday","Friday", "Saturday"};

char *get_a_day(int idx)
{
    return msg[idx];
}

/* main.c */
#include <stdio.h>
#include "ret_ptr.h"

int main(void)
{
    printf("%s %s\n", get_a_day(0));
    return 0;
}

动态分配内存并返回指针示例：

unit_t *alloc_unit(void); voidfree_unit(unit_t *p);

其调用者与实现者之间的协议如下：

调用者	实现者
1、调用alloc_unit分配内存； 2、将返回值保存下来以备后用； 3、调用free_unit释放内存。	1、规定返回值指针的类型unit_t *； 2、alloc_unit分配内存并返回指向该内存的指针； 3、free_unit释放由alloc_unit分配的内存。

以下是一个完整动态分配内存并返回指针的例子

/* ret_allocator.h */
#ifndef RET_ALLOCATOR_H
#define RET_ALLOCATOR_H

typedef struct {
    int number;
    char *msg;
} unit_t;
extern unit_t *alloc_unit(void);
extern void free_unit(unit_t *);

#endif

/* ret_allocator.c */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "ret_allocator.h"

unit_t *alloc_unit(void)
{
    unit_t *p = malloc(sizeof(unit_t));
    if(p == NULL) {
           printf("out of memory\n");
           exit(1);
    }
    p->number = 3;
    p->msg = malloc(20);
    strcpy(p->msg, "Hello world!");
    return p;
}

void free_unit(unit_t *p)
{
    free(p->msg);
    free(p);
}

/* main.c */
#include <stdio.h>
#include "ret_allocator.h"

int main(void)
{
    unit_t *p = alloc_unit();

    printf("number: %d\nmsg: %s\n", p->number, p->msg);
    free_unit(p);
    p = NULL;
    return 0;
}