Use snprintf. It’s even provided with a compatibility module if the target host doesn’t have it natively.

If you use snprintf to load some value into a buffer, make sure you provide the format string. Don’t use user-provided format strings, since that’s an easy way to open yourself up to an exploit.

Don’t use strcat. We have a neat wrapper for snprintf called snprintfcat that allows you to append to char * with a format string and all the usual string length checking of snprintf.

Don’t call syslog() directly. Use upslog_with_errno() and upslogx(). They may write to the syslog, stderr, or both as appropriate. This means you don’t have to worry about whether you’re running in the background or not.

upslog_with_errno prints your message plus the string expansion of errno. upslogx just prints the message.

fatal_with_errno and fatalx work the same way, but they exit(EXIT_FAILURE) afterwards. Don’t call exit() directly.

upsdebug_with_errno(), upsdebugx() and upsdebug_hex() use the global nut_debug_level so you don’t have to mess around with printfs yourself. Use them.

xmalloc, xcalloc, xrealloc and xstrdup all check the results of the base calls before continuing, so you don’t have to. Don’t use the raw calls directly.

The configuration parser, called parseconf, is now up to its fourth major version. It has multiple entry points, and can handle many different jobs. It’s usually used for parsing files, but it can also take input a line at a time or even a character at a time.

You must initialize a context buffer with pconf_init before using any other parseconf function. pconf_encode is the only exception, since it operates on a buffer you supply and is an auxiliary function.

Escaping special characters and quoting multiple-word elements is all handled by the state machine. Using the same code for all config files avoids code duplication.

Drivers may have their own data files, such as lists of hardware, mapping tables, or similar. The difference between a data file and a config file is that users should never be expected to edit a data file under normal circumstances. This technique might be used to add more hardware support to a driver without recompiling.

This is already handled by autoconf, so just include "timehead.h" and you will get the right headers on every system.

Another thing to notice is that the indenting happens with tabs instead of spaces. This lets everyone have their personal tab-width setting without inflicting much pain on other developers. If you use a space, then you’ve fixed the spacing in stone and have really annoyed half of the people out there.

If you write something that uses spaces, you may get away with it in a driver that’s relatively secluded. However, if I have to work on that code, expect it to get reformatted according to the above.

Patches to existing code that don’t conform to the coding style being used in that file will probably be dropped. If it’s something we really need, it will be grudgingly reformatted before being included.

When in doubt, have a look at Linus’s take on this topic in the Linux kernel - Documentation/CodingStyle. He’s done a far better job of explaining this.

It is better to have lines that are longer than 80 characters than to wrap lines in random places. This makes it easier to work with tools such as "grep", and it also lets each developer choose their own window size and tab setting without being stuck to one particular choice.

Of course, this does not mean that lines should be made unnecessarily long when there is a better alternative (see the note on pretentiousVariableNamingSchemes above). Certainly there should not be more than one statement per line. Please do not use

if (condition) break;

but use the following:

if (condition) {
        break;
}

We like code that uses const and static liberally. If you don’t need to expose a function or global variable to the outside world, static is your friend. If nobody should edit the contents of some buffer that’s behind a pointer, const keeps them honest.

We always compile with -Wall, so things like const and static help you find implementation flaws. Functions that attempt to modify a constant or access something outside their scope will throw a warning or even fail to compile in some cases. This is what we want.

If you use a goto, expect us to drop it when our head stops spinning. It gives us flashbacks to the very old code we wrote. We’ve tried to clean up our act, and you should make the effort as well.

We’re not making a blanket statement about gotos, since everything probably has at least one good use. There are a few cases where a goto is more efficient than any other approach, but you probably won’t encounter them very often in this software.

There are parts of the source tree that do not yet conform to these specs. Part of this is due to the fact that the coding style has been evolving slightly over the course of the project. Some of the code you see in these directories is 5 years old, and things have gotten cleaner since then. Don’t worry - it’ll get cleaned up the next time something in the vicinity gets a visit.

We can’t say enough good things about valgrind. If you do anything with dynamic memory in your code, you need to use this. Just compile with -g and start the program inside valgrind. Run it through the suspected area and then exit cleanly. valgrind will tell you if you’ve done anything dodgy like freeing regions twice, reading uninitialized memory, or if you’ve leaked memory anywhere.

For more information, refer to the Valgrind project.

The summary: please be kind to our eyes. There’s a lot of stuff in here, and many people have put a lot of time and energy to improve it.

The git svn tool synchronizes a Git repository with a SVN repository.

In many cases, NUT developers will not need access to the entire repository history - a snapshot starting at the most recent revision will work nicely:

git svn clone --revision HEAD svn://svn.debian.org/nut/trunk nut-git

From the resulting nut-git directory, you may use all of the Git commands to record your changes, and even create new branches for working on different aspects of the code.

Git offers a little more flexibility than the ‘svn update` command. You may fetch other developers’ changes from SVN into your repository, but hold off on actually combining them with your branch until you have compared the two branches (for instance, with gitk --all).

To import the new SVN revisions, simply run the following command from any directory under your Git checkout (nut-git in the example above). Note that this only changes the history stored in your repository - it does not touch your checked-out files.

git svn fetch

Initially, the Git master branch tracks the SVN trunk. The git svn command updates the remotes/trunk reference every time you run git svn fetch, but it does not adjust the master branch automatically. To update your master branch with new SVN revisions, you can run the following commands:

git checkout master
git svn fetch   # (optional; this gets commits other than on your current branch)
git svn rebase

You may create as many branches as you like in your local Git repository. When using git svn, the preferred way to combine your changes with SVN changes is to use git rebase on your local branch. This re-applies your branch’s changes to the new SVN changes, much as though your branch were a series of patches.

        git checkout master
        git branch my-new-feature
        git checkout my-new-feature

        # Hack away

        git add changed-file.c
        git commit

        # Someone committed something to SVN. Fetch it.

        git svn fetch
        git rebase remotes/trunk

You are encouraged to use git rebase -i on your private Git branches to separate your changes into logical changes.

From there, you can generate patches for the Tracker, or the nut-upsdev list.

If you are new to Git, but are familiar with SVN, the following link may be of use.

Synchronizing a Mercurial repository against the NUT SVN repository should be similar in spirit to the Git method discussed above. This wiki page discusses your options.

We would welcome any feedback about this process on the nut-upsdev mailing list.