EMBOSS provides basic functionality for interacting with the system and handling system-specific code. The areas covered include:
System calls for calling external applications
Code for parsing the application command line
Functions for casting one type to another
Low level file handling
Wrapper functions that call (with some modifications) standard C functions, mostly to overcome system-dependent limitations of the standard C functions
Functions to call the C function
exit with or without internal clean-up and reporting
Functions to reverse the byte order in different datatypes
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:
|Library File Documentation||Description|
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 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);
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
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, arglist 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);
exit with a success code (zero) after calling cleanup routines which report on resource usage etc.
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.
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.