Skip to content

High Level Library Interface

High Level Library Interface

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 :

1) 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.

2) 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 temp

To 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

3) 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

Initialize

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.

Alloc

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.

Free

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.

Back to top