Making Unwinding Functions in C Simple: Do Not be Afraid of Using Gotos

Intro

Today I wanted to talk about unwinding and releasing resources in C functions. Let’s begin by stating that there are three main techniques for handling errors in the C programming language. Sometimes more than one technique may be used. Here is a list of them:

  • You must test the value functions return. Abnormal value indicates that some kind of error has happened and a normal value indicates that it was successful;
  • There is an external variable whose value you must check. For example, the POSIX variant of this is to have an variable called errno that changes to 0 when nothing bad happened and it has some kind of other value when an error occurs;
  • You pass a pointer to a function. The function changes the value of the variable it points to or even calls it with certain arguments if it is a function pointer depending on the result.

I have not mentioned one method but some people use atexit(3) to register functions that will be called at the end of a program which will release resources. However, this is unusual so I have not included it in the list.

This is very much related to our topic because when an error occurs, you will have to handle it. That process includes releasing the resources which were acquired before in the function. Especially if you are deep down in your function and then an error occurred, the choice that you make in how to release the resources will matter a lot so it is important to make the correct decision.

In C++ you have the destructors and so on but how are you going to do that in C?
Are you going to sprinkle all of your error paths with:

free(foo);
free(bar);

and so on? It might be your first choice to go down this route but I think a viable and preferred alternative to this is using gotos and labels. Obviously, they should be used very cautiously. It is a very powerful tool so there is a lot of peril involved and ways to abuse it so you have to be absolutely careful. For simple cases when you don’t have to release any resources a plain return works well but it is a different situation with multiple resource acquisitions. Compared with other methods, using gotos doesn’t force you to duplicate the error paths, the code distracts less from the normal path, and it is more readable. You can’t imagine how this could be true and you cannot believe me? Let me prove to you that you should use gotos in these more complex situations!

Tutorial: using gotos for cleaning up

First, you should begin by naming the goto labels according to the resources that it frees. You want to be able to discern which resource exactly is going to be freed. Also, because goto labels may be used for other purposes other than resource clean-up, it is a good idea to prefix the goto labels with “err_” to indicate that its purpose is for releasing resources when an error occurs. Due to the fact that you will have different labels for different resources that they release, they should only contain one statement after it before the next label or the final return, and only do what it actually says.

Some good examples of names: err_release_view, err_free_list, err_close_lsocket, and so on.

Order the labels in such order that resources which are acquired first are at the bottom. The order of labels which release the resources should be in the inverse order of which they were acquired.

Now whenever an error occurs, use goto to jump to that label which will release the resources that were already gotten. As a rule, you can remember this: always jump to that label which releases the most recently acquired resource. This rule makes it easy to remember.

It may remind you of the defer mechanism in Go and other programming languages where the programmer can specify a list of functions with certain arguments which will be called as soon as the function goes out of scope. We are essentially emulating the same thing with gotos. Just that the C version requires a bit more attention and carefulness.

Example code comparison

To show how readability could be improved by using this method I will present one function from the Linux kernel source code and how it was changed. This function was improved courtesy of Tobin C. Harding. Thanks!

Here is the first version which does not use gotos at all:

static int enqueue_txdev(struct ks_wlan_private *priv, unsigned char *p, unsigned long size, void (*complete_handler)(void *arg1, void *arg2), void *arg1, void *arg2)
{
  struct tx_device_buffer *sp;

  if (priv->dev_state < DEVICE_STATE_BOOT) {
    kfree(p);
    if (complete_handler)
      (*complete_handler) (arg1, arg2);
    return 1;
  }

  if ((TX_DEVICE_BUFF_SIZE - 1) <= cnt_txqbody(priv)) {
    /* in case of buffer overflow */
    DPRINTK(1, "tx buffer overflow\n");
    kfree(p);
    if (complete_handler)
      (*complete_handler) (arg1, arg2);
    return 1;
  }

  sp = &priv->tx_dev.tx_dev_buff[priv->tx_dev.qtail];
  sp->sendp = p;
  sp->size = size;
  sp->complete_handler = complete_handler;
  sp->arg1 = arg1;
  sp->arg2 = arg2;
  inc_txqtail(priv);

  return 0;
}

The version with goto:

static int enqueue_txdev(struct ks_wlan_private *priv, unsigned char *p, unsigned long size, void (*complete_handler)(void *arg1, void *arg2), void *arg1, void *arg2)
{
  struct tx_device_buffer *sp;
  int rc;

  if (priv->dev_state < DEVICE_STATE_BOOT) {
    rc = -EPERM;
    goto err_complete;
  }

  if ((TX_DEVICE_BUFF_SIZE - 1) <= cnt_txqbody(priv)) {
    /* in case of buffer overflow */
    DPRINTK(1, "tx buffer overflow\n");
    rc = -EOVERFLOW;
    goto err_complete;
  }

  sp = &priv->tx_dev.tx_dev_buff[priv->tx_dev.qtail];
  sp->sendp = p;
  sp->size = size;
  sp->complete_handler = complete_handler;
  sp->arg1 = arg1;
  sp->arg2 = arg2;
  inc_txqtail(priv);

  return 0;

err_complete:
  kfree(p);
  if (complete_handler)
    (*complete_handler) (arg1, arg2);
  return rc;
}

As we can see, the code is much more readable and the two error paths are not duplicated. The judicious use of gotos avoids the perils of producing spaghetti code. Also, don’t worry: this not the only case. The Linux kernel source has an uncountable number of such examples. It makes the code much more readable once you get used to this convention. Not to mention that the Linux kernel is one of the biggest, most complex C projects around. So you know that the developers wouldn’t make a decision to use such code constructs which would increase the complexity of the code even more.

One more thing – this cleanup code is simple and clean but imagine a situation where it is much more complex. What if something extra was done in the error path if, for example, closing a socket failed and some extra sub-system had to be informed or some other actions had to be performed? That would be quite some extra code in each path. In this case, the goto method would be so much more attractive.

Conclusion

Using gotos in your C code to clean up after errors have occurred is similar to the defer mechanism in Go. Having clean-up code in one place which may be called completely gets rid of code duplication in error paths. This in part makes the code more readable because the reader won’t be distracted by the error handling code which could possibly obscure the real path. Also, there is less possibility of errors because potentially much less code is duplicated. The gotos can be abused easily so you should be very cautious and follow the tips given in this article.

Bonus: your compiler might have an extension to help out with this

Some C compilers have extensions which help with resource cleanup. For example, the popular gcc supports the cleanup attribute which applies to variables which have automatic storage duration. If you apply this attribute, gcc will run a function with that variable as the argument. Any return value is ignored. Example usage:

void cleanup_free(void *p)

{
  free(*(void **)p);
}




void foo(void) 
{
  char __attribute__((cleanup(cleanup_free))) *bar;
  bar = malloc(128);
} 

This extra function is needed because if ordinary free(3) would be written then it  would receive a char** and, obviously, free(3) doesn’t know that it should be dereferenced one time first. If you compile this function and run it with valgrind then you will see that no memory was leaked. This is also useful with close(2) and other similar functions. However, there is one downside – if you want more granular control of what happens if, for example, close(2) fails then it is impossible with this because any return value is ignored silently.  Check out your compilers’ documentation if there is support for this kind of thing. Obviously, you should consider the alternative of writing portable code first.
Please comment if you find any errors or just want to discuss this.

On Trustworthiness of Sources While Gathering Information About Software

Read the fine manual

Time and time I see people who follow all these random online tutorials and then when something does not work they become dazed and confused. “Why this does not work? But this tutorial shows that it should work” – I see similar questions occasionally in various forms on forums and IRC. I think people do not realize that there is some kind of hierarchy of trustworthiness of information sources. We should be conscious of that hierarchy when looking for information and remember it when we notice that something is not correct or up-to-date.

In my opinion, the field of studying history has already nailed this down. They have what is called the primary and secondary sources of information.  Primary sources provide direct evidence about an event, object, person, or work of art. The latter thing is similar but they talk and analyze the primary sources [1]. It seems to me that we can draw a parallel between this and the information sources that we use to study programming. However, instead of having a simple distinction between primary and secondary sources, a hierarchy is more suitable because we are talking about researching a thing that we have in front of us at present and we can experiment with it. The only question that remains is: how does the hierarchy look like?

At first, let’s think about what kind of sources we have when we are talking about programming before making it. Personally, I can list these items:

Zeros and ones representing byte code

  • The actual machine code in the executable or the file that you are examining. This can be considered the primary source in programming. What is inside there is actually executed on your machine so you know that it cannot lie. However, it is very hard to decipher and not very informative. Thus, even though it is the most trustworthy, it is very unfriendly to the person that is trying to learn.
  • The source code that was compiled to make the executable or a file. In terms of trustworthiness it is almost as good as machine code and it is a very good source from which to learn because source code is written for humans and lets you understand everything relatively easily. The only downside is that you have to know that the executable/file that you have been actually made from that source code. Projects such as the reproducible builds [2] help with that but still that is not available everywhere and you have to be sure that the source code corresponds to that executable.
  • Empirical observation of what system calls the executable is executing, what kind of options are available, what is the output of various commands and so on. This source of information tells you what is apparently available to you as a user but you cannot be sure about what is exactly happening in all cases thus it is not so trustworthy. Also, by using this source information you cannot know what options and commands are exactly available. What if there is a hidden feature or something that is not documented in the output?
  • Standards. Now we are entering into the zone where we are not even talking about the actual file/program on your computer. Standards are much more trustworthy than the next item because they are usually governed and released by a rigorous organization such as ISO [3] or ANSI [4]. Also, a lot of deliberation and work goes into making sure everything is correct, orderly, understandable, and that there are no contradictions. On the contrary, they are not so easy to use like the next items because most of the time you have to pay to get the standard. Also, usually they use more technical parlance than the next item.
  • Documentation released by the manufacturer, vendor. Quality of information released by the original makers tend to vary a lot. However, it is usually well structured, easily understandable so it is not hard to skim and find the relevant information that you are searching for.A book with flowers
  • Books. This source of information tends to be researched more than the item that goes after this one in the list. This is due to the fact that after the book is released, you cannot change it. Also, most of assertions in books need to be backed up by quotes or citations. However, because it is not made by the original company or a group of people that made the executable/file, it is less trustworthy than the previous item. What is more, the topics of books’ chapters have a tendency to be more abstract than the manuals so sometimes it might be not so easy to find information that you are looking for when compared to official manuals.
  • Community tutorials, forums, wiki pages, articles. These are the least trustworthy because of the anonymous nature of the Internet. Anyone could write anything and you are never sure if what is written was researched well. There is a reason why no one uses web pages as serious sources of information in the academia. On the other hand, it is very accessible because almost everyone has a mobile phone or a laptop with an internet connection on it nowadays.

We can produce this picture after listing the items:

Hierarchy of Information

My point is that everyone should always keep this in mind. Also, now if someone is doing the same mistake I mentioned at the beginning, you should refer them to this article or this hierarchy. I hope this was useful. Please comment if you do not agree with anything mentioned in this post or if you want to discuss.