Internationalization

It is good to strive to write a reusable and portable code; however, sometimes the usefulness of the software has inadvertent limits because the language and cultural requirements of the end-user are not actively considered. Fortunately, these issues are well understood and the solution has been put in place by the GNU Translation Project. Linux provides the capability to extract culturally dependent data from the application (internationalization) and apply it to various cultures as desired (localization).

Take for example a simple "Hello World" program that just prints a short text message to the screen. Will the message be displayed in English, Spanish, Japanese, or Jamacian English? The message displayed depends if the original text has been translated and properly stored in a message catelogue for the application to use, and if the end-user has set his locale to find those messages. The setlocale in the following example, can initialize the locale base on the first nonempty value of the three environment variables LC_ALL, LC_MESSAGES, or LANG.

If the end-user sets the LANG to en_US then the program looks for U.S. english translated text found in the ghw message catelog in the /usr/share/locale/ diretory set by bindtextdomain().

Instead of printf printing a text message directly, the gettext function is called to look up the MSGID (the default text) in the current default message catalog for the current LC_MESSAGES locale. If not found, returns MSGID itself (the default text).

#include <stdio.h>
#include <locale.h>
#include <libintl.h>

int
main(int argc, char *argv[])
{
	printf("LANG=%s\n", getenv("LANG"));

	/* initialize LC_MESSAGES according to LC_ALL, LC_MESSAGES, or LANG */

	setlocale(LC_ALL, ""); 

	printf ("dirname=%s\n", 
		bindtextdomain("ghw", "/usr/share/locale/")); 

	printf("domainname=%s\n", textdomain("ghw"));

	/* Look up MSGID in the current default message catalog for the 
	 * current LC_MESSAGES locale.  If not found, returns MSGID itself 
	 * (the default text).
	 */

	printf(gettext("Hello World\n"));

	printf(gettext("The value of Open Standards is only evident to Open Minds\n"));

	printf(gettext("Good Bye\n"));

	exit(0);
}

Beware that Linux internationalization and localization has added gettext in addition to the POSIX defined catgets that is used on UNIX. The difference being, catgets uses a numeric message identifier, where gettext uses the the default text as the message identifier. The disadvantage of the former is that the numeric message identifiers of catgets can more easily get out of sync between the application and the message catalog. Text message identifiers of gettext at least have a chance of being found in the message catalog if they have be improperly moved out of sequence but not altered. For obvious reasons, never try to use both methods simultaneously from the same application or application family.

PAM

The are many different ways an application can authenticate a user with the system. Applications that hardcode either the getpwnam(3) or shadow(3) are limited to the fact they can on work on a system configure accordingly. The Pluggable Authentication Module (PAM) abstracts the mechanics of authentication from the application and it enables the local system administrator to choose how individual applications will authenticate users. Following is an example application using pam_authenticate(3):

#include <security/pam_appl.h>
#include <security/pam_misc.h>
#include <stdio.h>

static struct pam_conv conv = {
	    misc_conv,
	        NULL
};

int main(int argc, char *argv[])
{
	pam_handle_t *pamh;
	int pam_status;
	char *user;

	pam_status = pam_start("lsb_login", NULL, &conv, &pamh);
		
	if (pam_status == PAM_SUCCESS)
		pam_status = pam_authenticate(pamh, 0);

	if (pam_status == PAM_SUCCESS) {
		pam_get_item(pamh, PAM_USER, (const void **)&user);
		fprintf(stdout, "Greetings %s\n", user);
	} else {
		printf("%s\n", pam_strerror(pamh, pam_status));
	}

	pam_end(pamh, pam_status);
}

The pam_start(3) identifies the application with the specified service. After the user is vouched for by pam_authenticate(3), then the application can safely trust the users identity and priviledges.

Java

For those wanting to develop Java applications that are compatible across different JVMs should follow the Java API Specification. [1] Java is not native to Linux nor UNIX, so it is out of scope for the LSB to specify.

Applications that have Java Native Interfaces (JNI) [2] do have Linux object code that can and should be LSB conforming. JNI object code can be LSB certified.

kill(3)

Process ID -1 to kill(3) doesn't affect the calling process. This was a deliberate decision after an unpopular experiment in including the calling process in the 2.5.1 kernel. [1]

ioctl(3)

The LSB has its own definition of ioctl(3) and does not reference ISO/IEC 9945.

IP Information

With the advent of IPv6, gethostbyname(3) has been replaced with routines such as getaddrinfo(3) and getnameinfo(3). For better compatibility, these newer IPv6 functions should be used.

#include <netdb.h>
#include <stdio.h>

int main(int argc, char **argv) {

struct addrinfo *res, *r;
struct addrinfo hints;
struct sockaddr *sa;
int rc;
char * proto;

char hostbuf[NI_MAXHOST];
char servbuf[NI_MAXSERV];

	bzero(&hints,sizeof(hints));
	hints.ai_family = PF_UNSPEC;
	hints.ai_socktype = SOCK_STREAM;
	hints.ai_flags = AI_CANONNAME;

	if ((rc = getaddrinfo("www.linuxbase.org", NULL, &hints, &res))) {
		fprintf(stderr, "%s\n", gai_strerror(rc));
		exit(2);
	}

	for (r = res; r; r = r->ai_next) {

		if(r->ai_family == AF_INET6){
			inet_ntop(AF_INET6,
			&(((struct sockaddr_in6 *)r->ai_addr)->sin6_addr),
			hostbuf, sizeof(hostbuf));
			proto = "IPv6";
		} else if (r->ai_family == AF_INET) {
			inet_ntop(AF_INET,
			&(((struct sockaddr_in *)r->ai_addr)->sin_addr),
			hostbuf, sizeof(hostbuf));
			proto = "IPv4";
		}

		printf("getaddrinfo(3): %s address = %s\n", proto, hostbuf);

		bzero(hostbuf, sizeof(hostbuf)); /* clear */

		if (getnameinfo(r->ai_addr, r->ai_addrlen, 
		hostbuf, sizeof(hostbuf),
		servbuf, sizeof(servbuf), 
		NI_NAMEREQD|NI_NUMERICSERV)){
			printf("getnameinfo(3): could not find IP.\n");
		} else {
			printf("getnameinfo(3): host = %s\n", hostbuf);
		}
	}
	freeaddrinfo(res);
}

O_LARGEFILE

When available, the LSB permits Linux implementations to set O_LARGEFILE with fcntl(3). Applications should set the flag explicitly when needed, and not expect the runtime to set it by default.

#ifdef __USE_LARGEFILE64
	int oflag = fcntl(fd, F_GETFL, 0);
	if (oflag & O_LARGEFILE) {
		debug("O_LARGEFILE was implicitly set");	// BAD
	}
	oflag |= O_LARGEFILE;					// GOOD
	fcntl(fd, F_SETFL, oflag);
#endif

EISDIR(3)

If the path argument of unlink(3) specifies a directory, the implementation may return EISDIR instead of EPERM as specified by Single UNIX Specification.

#include <sys/stat.h>
#include <sys/types.h>
#include <fcntl.h>
#include <errno.h>
#include <stdio.h>

main() {

   char *newdir = "/tmp/example_dir";

   if (0 != mkdir(newdir, O_CREAT)) {
      printf("mkdir %s: %s\n", newdir, strerror(errno)); 
   }

   if (0 != unlink(newdir)) {

      switch (errno) {
         case EISDIR:
            printf("EISDIR: %s is a directory\n", newdir);
            break;
         case EPERM:
            printf("EPERM: operation not permitted for %s\n", newdir);
            break;
         default:
            perror ("unlink"); 
            break;
      }
   }
}

waitpid(3)

The LSB has deprecated the use of waitid(3). Applications should call the waitpid(3) interface as specified in the Single UNIX Specification, but implementations need not support the X/Open System Interfaces Extension (XSI) functionality of WCONTINUED or WIFCONTINUED.

#include <assert.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>

int main (void)
{
   int rc, status;
   pid_t pid;

   pid = fork();

   if (pid < 0) {
      perror("fork");
      exit(1);
   }

   if (0 == pid) {
      fprintf(stderr, "\tChild process (pid=%d) running...\n",getpid());
      sleep (10);
      fprintf(stderr, "\tChild process (pid=%d) terminating...\n",getpid());
      exit(0);
   }

   fprintf(stderr, "Parent process (pid=%d) waiting for child (pid=%d)...\n", 
      getpid(), pid);

   rc=waitpid(pid, &status, 0);

   fprintf(stderr, "Parent process (pid=%d) continuing ", getpid());
   fprintf(stderr, "after the termination of child (pid=%d).\n", pid);
   fprintf (stderr,"Status=%08X Return Code=%d\n", status, rc);

   if (rc < 0) {
      perror ("waitpid");
      exit(2);
   }

   exit(0);
}

Parsing of Command Options

The GNU getopt(3) parses command line arguments as specified by the Single UNIX Specification Version 3 when the plus sign "+" is the first character in the operation string of the third parameter.

The GNU operation string flags "W;" to enable long options, "-" to return '\1' for invalid options, and "::" to enable optional flag arguments, should not be used when trying to maintain SUSv3 consistency.

#include <unistd.h>
#include <stdio.h>

int 
main (int argc, char **argv)
{
	int aflag = 0;
	int bflag = 0;
	char *cvalue = NULL;
	int errflg = 0;
	int index, c;

	/* the plus sign is required to permanetly set POSIXLY_CORRECT */

	while ((c = getopt (argc, argv, "+abc:")) != -1)
		switch (c) {
		case 'a':
		       	aflag = 1;
			break;
		case 'b':
			bflag = 1;
			break;
		case 'c':
			cvalue = optarg;
			break;
		case ':':
			fprintf (stderr, 
				"Option -%c requires an operand\n", 
				optopt);
			errflg++;
			return 1;
		case '?':
			fprintf (stderr, "Unknown option -%c\n", optopt);
			errflg++;
			return 1;
		default:
			fprintf (stderr, "Hoplessly lost\n");
			errflg++;
			break;
		}

		if (errflg) {
			fprintf (stderr, "USAGE: %s -a -b -c file", argv[0]);
			exit(1);
		}

		printf ("aflag = %d, bflag = %d, cvalue = %s\n",
			aflag, bflag, cvalue);

		for (index = optind; index < argc; index++)
			printf ("Operand argument %s\n", argv[index]);

		exit(0);
}

LSB Dont's

This chapter is about portability eitquete. As an open systems developer, there are things you should not do. You should realize that the compromizes to follow portability outweight the short-term benefits of tuning to a specific release.

#ifdef DEBUG
#include <malloc.h>
#endif
#include <stdlib.h>