EMBOSS provides basic functionality for interacting with the system and handling system-specific code. The areas covered include:

AJAX library files for handling system calls are listed in the table (Table 6.37, “AJAX Library Files for Handling System”). Library file documentation, including a complete description of datatypes and functions, is available at:

ajsys.h/c. System functions, mostly for low level handling of files and directories and system-specific functions.

ajutil.h/c. Functions for exiting cleanly, memory cleanup, manipulate bytes and so.

There are no ACD datatypes dedicated for system handling..

There are no AJAX datatypes dedicated for system handling.

There are two functions for calling external applications. ajSysSystem will call a user executable file in the current path, whereas ajSysSystemEnv will use the environment including the PATH path that is provided within it:

void  ajSysSystem (const AjPStr str);
void  ajSysSystemEnv (const AjPStr str, char*  const env[]);

The function ajSysArglistBuild extracts the application name (name) and list of arguments (PParglist) from any application command line:

AjBool ajSysArglistBuild (const AjPStr cmdline, char** name, char*** PParglist);

The function allocates a string (name) and a null-terminated string array (PParglist) which are later freed by calling AJFREE and ajSysArglistFree:

    AjPStr cmdline = NULL;
    char **arglist = NULL;
    char *name;

    /* The command line must be assigned to a string */
    cmdline = ajStrNewC("ApplicationName arg1 arg1val arg2 arg2val")

    ajSysArglistBuild (cmdline, &name, &arglist);

    /* Do something with the name and argument list. Individual args are in arglist[0], arglist[1] etc. */

    AJFREE(name);
    ajSysArglistFree(&arglist);

Function are available for casting an integer to character types:

char  ajSysCastItoc (ajint i);    
unsigned char  ajSysCastItouc (ajint i);

Three functions are available for low level file handling.

ajSysFileWhich will search for a user-executable file in the current path whereas ajSysFileWhichEnv will use a PATH from the environment that is provided by argument. The functions returns ajTrue if the executable was found:

AjBool  ajSysFileWhich (AjPStr* Pstr);                           
AjBool  ajSysFileWhichEnv (AjPStr* Pstr, char*  const env[]);

ajSysFileUnlink is used to safely delete a file or link:

AjBool  ajSysFileUnlink (const AjPStr str);

Various functions are provided that wrap (with some modifications) standard C functions. In most cases these are provided to overcome system-dependent limitations of the standard C functions. These functions have the prefix ajSysFunc and include:

char*  ajSysFuncStrtok (const char* txt1, const char* txt2);
char*  ajSysFuncStrtokR (const char* txt1, const char* txt2, char** Ptxt, AjPStr* Pbuf);
char*  ajSysFuncFgets (char* buf, int n, FILE* fp);
char*  ajSysFuncFopen (const char* txt, const char* flags);
FILE*  ajSysFuncFdopen (ajint filedes, const char* mode);

The following functions call the C function exit. The functions embExit* (defined in embexit.h/c), called from applications code to exit the application, make use of these functions:

/* Exits with a success code (zero) after cleanup routines */
__noreturn void  ajExit (void);          

/* Exits with an unsuccessful code without flushing files or clean-up. */
__noreturn void  ajExitAbort (void);     

/* Exits with an unsuccessful code without clean-up. */
__noreturn void  ajExitBad (void);       

ajExit() calls exit with a success code (zero) after calling cleanup routines which report on resource usage etc.

ajExitAbort() calls exit with an unsuccessful code (EXIT_FAILURE defined in stdlib.h) without flushing any files. This is needed to exit from, for example, a failed system call (e.g. ajFileNewInPipe) where the parent process has open output files and the child process needs to exit without affecting them. Failure to exit this way can mean the output buffer is flushed twice. No cleanup or reporting routines are called.

ajExitBad() calls exit() with an unsuccessful code (EXIT_FAILURE). No cleanup or reporting routines are called.

The following functions all reverse the byte order in the datatype indicated:

void  ajByteRevLen2 (short* i);     /* 2 byte integer   */
void  ajByteRevLen4 (ajint* i);     /* 4 byte integer   */
void  ajByteRevLen8 (ajlong* i);    /* 8 byte integer   */
void  ajByteRevInt (ajint* sval);    /* integer          */
void  ajByteRevShort (short* ival);  /* unsigned integer */
void  ajByteRevLong (ajlong* lval);  /* long             */
void  ajByteRevUint (ajuint* ival);  /* unsigned integer  */

Finally, there are a few miscellaneous useful functions:

/* If a log file is in use then this writes run details to end of file. */
void   ajUtilLoginfo (void);                

/* Dummy function for use in debugging */
void   ajUtilCatch (void);              

/* Tests whether the host system uses big endian byte order. */
AjBool ajUtilGetBigendian (void);          

/* Returns the user's userid. */
AjBool ajUtilGetUid (AjPStr* dest);        

/* Returns a command line with all options changed by the user */
const AjPStr  ajUtilGetCmdline (void);

/* Returns the user non-default inputs in commandline form */
const AjPStr  ajUtilGetInputs (void);

/* Return the program name */
const AjPStr  ajUtilGetProgram (void);

ajUtilCatch should be called in special cases when debugging in GDB. To use, simply put a call to ajUtilCatch() into your code, and use "break ajUtilCatch" in GDB to get a traceback.