8.7.4 General Guidelines for Writing Mule-Aware Code

This section contains some general guidance on how to write Mule-aware code, as well as some pitfalls you should avoid.

Never use char and char *.

In SXEmacs, the use of char and char * is almost always a mistake. If you want to manipulate an Emacs character from “C”, use Emchar. If you want to examine a specific octet in the internal format, use Bufbyte. If you want a Lisp-visible character, use a Lisp_Object and make_char. If you want a pointer to move through the internal text, use Bufbyte *. Also note that you almost certainly do not need Emchar *.

Be careful not to confuse Charcount, Bytecount, and Bufpos.

The whole point of using different types is to avoid confusion about the use of certain variables. Lest this effect be nullified, you need to be careful about using the right types.

Always convert external data

It is extremely important to always convert external data, because SXEmacs can crash if unexpected 8bit sequences are copied to its internal buffers literally.

This means that when a system function, such as readdir, returns a string, you may need to convert it using one of the conversion macros described in the previous chapter, before passing it further to Lisp.

Actually, most of the basic system functions that accept ’\0’-terminated string arguments, like stat() and open(), have been encapsulated so that they are they always do internal to external conversion themselves. This means you must pass internally encoded data, typically the XSTRING_DATA of a Lisp_String to these functions. This is actually a design bug, since it unexpectedly changes the semantics of the system functions. A better design would be to provide separate versions of these system functions that accepted Lisp_Objects which were lisp strings in place of their current char * arguments.

int stat_lisp (Lisp_Object path, struct stat *buf); /* Implement me */

Also note that many internal functions, such as make_string, accept Bufbytes, which removes the need for them to convert the data they receive. This increases efficiency because that way external data needs to be decoded only once, when it is read. After that, it is passed around in internal format.