High Level Library Interface (API)
The High Level Library Interface is a unified Application Programming Interface (API) to access system call routines and dynamic memory management functions from application programs. The ExpL language allows applications to access the OS routines only through the library interface. The syntax for the call to the library function in ExpL is :
t = exposcall(fun_code, arg1, arg2, arg3);
Depending on the fun_code the control is transferred to the system call routines and the dynamic memory management functions (see below) .
| Library Function / System Call | Function Code | Argument 1 | Argument 2 | Argument 3 | Return value |
|---|---|---|---|---|---|
| Create | "Create" | File Name | Permission * | - | 0 - Success/File already exists | -1 - No free inode table entry |
| Open | "Open" | File Name | - | - | File Descriptor - Success | -1 - File Not found or file is not data file or root file | -2 - System has reached its limit of open files | -3 - Process has reached its limit of resources |
| Close | "Close" | File Descriptor | - | - | 0 - Success | -1 - File Descriptor is invalid |
| Delete | "Delete" | File Name | - | - | 0 - Success/File does not exist | -1 - Permission Denied | -2 - File is open |
| Write | "Write" | File Descriptor (-2 for terminal) | Word to be written | - | 0 - Success | -1 - File Descriptor given is invalid | -2 - No disk space | -3 - Permission denied |
| Read | "Read" | File Descriptor (-1 for terminal) | Variable name (to which data is to be read) | - | 0 - Success | -1 - File Descriptor given is invalid | -2 - File pointer has reached the end of file |
| Seek | "Seek" | File Descriptor | Offset | - | 0 - Success | -1 - File Descriptor is invalid | -2 - Offset moves File pointer outside file |
| Fork | "Fork" | - | - | - | PID - Success (in parent process) | 0 - Success (in child process) | -1 - Failure (in parent process), Number of processes has reached maximum limit |
| Exec | "Exec" | File Name | - | - | -1 - File not found or file is not executable | -2 - Out of memory or disk swap space |
| Exit | "Exit" | - | - | - | - |
| Getpid | "Getpid" | - | - | - | current PID - Success |
| Getppid | "Getppid" | - | - | - | parent PID - Success |
| Wait | "Wait" | Process Identifier | - | - | 0 - Success | -1 - Given PID is invalid or it is PID of invoking process |
| Signal | "Signal" | - | - | - | 0 - Success |
| Semget | "Semget" | - | - | - | SEMID - Success | -1 - Process has reached its limit of resources | -2 - Number of semaphores has reached its maximum |
| Semrelease | "Semrelease" | Semaphore Descriptor | - | - | 0 - Success | -1 - Invalid SEMID |
| SemLock | "SemLock" | Semaphore Descriptor | - | - | 0 - Success or semaphore is already locked by the current process | -1 - invalid SEMID |
| SemUnLock | "SemUnLock" | Semaphore Descriptor | - | - | 0 - Success | -1 - Invalid SEMID | -2 - Semaphore was not locked by the calling process |
| Shutdown | "Shutdown" | - | - | - | -1 - Permission denied |
| Newusr | "Newusr" | User name | Password | - | 0 - Success | -1 - User already exists | -2 - Permission denied | -3 - No. of users have reached the system limit. |
| Remusr | "Remusr" | User name | - | - | 0 - Success | -1 - User does not exist | -2 - Permission denied | -3 - Undeleted files exist for the user |
| Setpwd | "Setpwd" | User name | New Password | - | 0 - Success | -1 - Unauthorised attempt to change password | -2 - The user does not exist. |
| Getuname | "Getuname" | User ID | - | - | User Name - Success | -1 - Invalid User ID |
| Getuid | "Getuid" | User name | - | - | User ID - Success | -1 - Invalid username |
| Login | "Login" | User name | Password | - | 0 - Success | -1 - Invalid username or password | -2 - Permission denied |
| Logout | "Logout" | - | - | - | -1 - permission denied |
| Test0 | "Test0" | Unspecified | Unspecified | Unspecified | - |
| Test1 | "Test1" | Unspecified | Unspecified | Unspecified | - |
| Test2 | "Test2" | Unspecified | Unspecified | Unspecified | - |
| Test3 | "Test3" | Unspecified | Unspecified | Unspecified | - |
| Test4 ** | "Test4" | Unspecified | Unspecified | Unspecified | - |
| Test5 ** | "Test5" | Unspecified | Unspecified | Unspecified | - |
| Test6 ** | "Test6" | Unspecified | Unspecified | Unspecified | - |
| Test7 ** | "Test7" | Unspecified | Unspecified | Unspecified | - |
| Initialize | "Heapset" | - | - | - | 0 - Success | -1 - Failure |
| Alloc | "Alloc" | Size | - | - | Allocated address in Heap - Success | -1 - No allocation |
| Free | "Free" | Pointer | - | - | 0 - Success | -1 - Failure |
*If the file is created with EXCLUSIVE permissions, then write and delete system calls will fail when executed by any user other than the owner or the root (see here).
** These System Calls are available only on eXpOS running on NEXSM (a two-core extension of XSM) machine.
Note : According to syntax of exposcall(), it needs four arguments. These arguments are func_code, arg1, arg2, arg3. func_code is necessary for every exposcall() to recognize the Library function/System call. The remaining number of arguments varies according to Library interface specification of the corresponding func_code. Even if exposcall() is invoked with more number of arguments than required for a particular Library function/System call, they are ignored.
Examples to use above mentioned Library functions/system calls :
-
To open a file named example.dat, ExpL library interface call is
fd=exposcall("Open","example.dat");Here return value is stored in variable fd, which is file descriptor for file example.dat on success.
-
From above example, variable 'fd' contains file descriptor for file example.dat. To write the value stored in variable 'num' to this file, ExpL library interface call is
temp=exposcall("Write",fd,num); //return value stored in tempTo write to terminal, use -2 as first argument. Note that expressions such as 2 + 3, num * 34 are not valid as second argument for write system call.
temp=exposcall("Write",fd,num+2); //Invalid library interface call -
Alloc is a library function, which is predefined in ExpL library. It is a dynamic memory management routine. It allocates memory for variables of user defined type in ExpL. ExpL library interface call to allocate memory for variable 'data', which requires 3 words of memory is
data=exposcall("Alloc",3);The present library routine alloc allocates 8 words for any variable irrespective of the size mentioned in its alloc exposcall(). So, do not define a user defined type having more than 8 fields. Remember to call library function Intialize using exposcall() once before invoking first alloc in any ExpL program.
The description of the system calls can be seen here. The dynamic memory management routines are described below.
Dynamic Memory Routines
Arguments: None
Return Value:
| 0 | Success |
| -1 | Failure |
Description: Intitalizes the heap data structures and sets up the heap area of the process. It is the applications responsibility to invoke Initialize() before the first use of Alloc(). The behaviour of Alloc() and Free() when invoked without an Intialize() operation is undefined. Any memory allocated before an Intialize() operation will be reclaimed for future allocation.
Arguments: Size (Integer)
Return Value:
| Allocated address in Heap | Success |
| -1 | No allocation |
Description: The Alloc operation takes size (integer) as an input and when successful, allocates contiguous words (in the heap) equal to the size specified and returns the address of the allocated memory.The present implementation of library routine alloc allocates 8 words for any variable irrespective of the size mentioned in its alloc exposcall(). So, do not define a user defined type having more than 8 fields.
Arguments: Pointer (Integer)
Return Value:
| 0 | Success |
| -1 | Failure |
Description: The Free operation takes a pointer (i.e., an integer memory address) of a previously allocated memory block and returns it to the heap memory pool. If the pointer does not correspond to a valid reference to the beginning of a previously allocated memory block, the behaviour of Free is not defined.
