use pointer to struct or not when using typedef in C [duplicate]

Question

In order to define a new datatype in C for example a type for linked list
one can use one of the following definitions

struct list_node {
    int x;
    struct list_node * next;
};

//1
typedef struct list_node list1;
//2
typedef struct list_node *list2;

From what I have seen the common practice is the first definition.

The question is if the second definition is also an acceptable practice. In which cases if any should one prefer the second over the first? Provided that the variables that we use are pointers to struct list_node is it possible to do the same operations with both types? What are the advantages of the first?

Answer 1

I would require API users to type the "*", i.e. typedef the struct, not a pointer to the struct. This is the widely-used style in GLib, which is one of the more popular C stacks.

It works out well because it is important to know whether you have a pointer to a struct or the struct itself. For example, can you store NULL in a variable of the type? If you hide that an object is a pointer, you have to create a special NIL_NODE or other value to replace NULL. If you just make it a pointer, then people can treat it like one.

Another important benefit is the ability to put the actual struct definition somewhere private, i.e. in the .c file instead of in the header. You can put just the typedef in the header, while keeping the struct itself opaque to API users. This requires people to only use the exported methods that you provide to manipulate the struct. It also means you don't have to rebuild the world if you change the struct fields.

Yet another reason to take this path is that sometimes you do want a struct that can be copied, and you still want to typedef it. Take a thing like GdkPoint:

  typedef struct {
     int x, y;
  } GdkPoint;

Here it's useful to allow direct struct access, like:

 GdkPoint point = { 10, 10 };
 GdkPoint copy = point;
 do_stuff_with_point(&copy);

However, if your convention is that the "GdkPoint" typedef would be a pointer, you're going to have to be inconsistent.

Code is just clearer if you can tell what's a pointer and what isn't, and code is better encapsulated if you don't put struct definitions in the header (for structs that represent abstract, opaque data types, which is maybe the most common kind).

My default template for a C data type is something like this in the header:

typedef struct MyType MyType;
 MyType* my_type_new(void);
 void    my_type_unref(MyType *t);
 void    my_type_ref(MyType *t);

Then the actual "struct MyType" in the .c file, along with the new, the unref, and any operations on the type.

The exception would be for types such as Point, Rectangle, Color where it's "plain old data" and direct field access is desired; another variation is to have a my_type_free() instead of _unref() if you don't need refcounting.

Anyhow, this is one style, basically the GLib style, that's widely-used and is known to work well.