Cross-platform C SDK logo

Cross-platform C SDK

Osbs

❮ Back
Next ❯
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

There is no neat distinction between operating system software and the software that runs on top of it. Jim Allchin


Functions

uint32_t(*FPtr_thread_main (...))
voidosbs_start (void)
voidosbs_finish (void)
platform_tosbs_platform (void)
win_tosbs_windows (void)
endian_tosbs_endian (void)

Types and Constants

enumplatform_t
enumdevice_t
enumwin_t
enumendian_t
enumweek_day_t
enummonth_t
enumfile_type_t
enumfile_mode_t
enumferror_t
enumperror_t
enumserror_t
structDate
structDir
structFile
structMutex
structProc
structProcOpt
structThread
structSocket
structSockOpt

osbs (Operating System Basic Services) is a portable wrapper that allows applications to communicate with the operating system core at the level of processes, memory, files, networks, clocks, etc. This communication is carried out through a series of system calls (Figure 1) which vary according to the operating system for which we are programming. It is the non-graphic lowest level API to communicate with hardware devices and access the machine resources. Below are the device drivers managed directly by the kernel, to which applications have access denied.

Schema showing how the osbs library connects with the hardware through system calls.
Figure 1: System calls are the gateway to the operating system kernel.

Darwin, the macOS kernel, and Linux are Unix-like systems, therefore, they share the same system calls (with subtle differences). But Windows presents a radically different architecture and function set. The NAppGUI osbs library is nothing more than a small wrapper that internally handles these differences and provides a common way to access the same resources on different platforms (Figure 2). It only depends on Sewer and its functionalities have been divided into different modules:


1. Standard C library

The C standard library (cstdlib) is not part of the C language, but implements functions of great utility for the developer that solve typical programming problems. Any C programmer has used it more or less and its study is usually linked to learning the language itself (Figure 3).

"The C Standard Library" book cover.
Figure 3: A complete reference to the C library is found in the P.J.Plauger book.

This library is located halfway between the application and system calls and provides a portable API for file access, dynamic memory, I/O, time, etc (Figure 4). It also implements mathematical functions, conversion, search, string management, etc. In one way or another, NAppGUI integrates its functionality into osbs, so it's not necessary (or advisable) to use cstdlib directly in the application layer. The reasons that have motivated this design decision can be summarized in:

Schema showing the osbs library in relation to the standard C library.
Figure 4: The functionality of the C library has been integrated in osbs, avoiding its direct use in applications.
  • Small differences: Unix-like systems do not support the secure cstdlib versions implemented by Microsoft (strcpy_s() and others). The use of classical functions (without the suffix _s) is insecure and will trigger annoying warnings in Visual Studio.
  • Security: Related to the previous one, osbs avoids buffer overflow vulnerabilities in the processing of memory blocks and strings.
  • Duplicity: Much of the functionality of cstdlib is already implemented in osbs using direct system calls (files, dynamic memory, I/O, time, etc.)
  • Completeness: The cstdlib functions related to files (fopen() and others) do not include support for directory management. Files and directories presents a complete API based on system calls.
  • Performance: In certain cases, especially in mathematical functions and memory management, it may be interesting to change the implementation of cstdlib to an improved one. All applications will benefit from the change, without having to modify your code.
  • Clarity: The behavior of some cstdlib functions is not entirely clear and can lead to confusion. For example, strtoul has a very particular functioning that we must remember every time we use it.
  • 1
    2
    3
    4
    5
    6
    7
    
    char *s1 = "-56";
    char *s2 = "asCr";
    char *s3 = "467Xd";
    int v1, v2, v3;
    v1 = strtoul(s1, NULL, 10); // v1 = 4294967240, errno = OK
    v2 = strtoul(s2, NULL, 10); // v2 = 0, errno = OK
    v3 = strtoul(s3, NULL, 10); // v3 = 467, errno = OK
    
  • Style: The use of osbs functions does not break the aesthetics of an application written with NAppGUI.
  • 1
    2
    3
    4
    5
    6
    7
    
    real32_t a1 = 1.43f;
    real64_t a2 = .38;
    real32_t c = (real32_t)cosf((float)a1);
    real64_t t = (real64_t)tan((double)a2);
    ...
    real32_t c = bmath_cosf(a1);
    real64_t t = bmath_tand(a2);
    
  • Independence: NAppGUI internally uses a very small subset of cstdlib functions. It is possible that in the future we will make our own implementations and completely disconnect the support of the standard library.

enum platform_t

Operating systems supported by NAppGUI.

enum platform_t
{
    ekWINDOWS,
    ekMACOS,
    ekLINUX,
    ekIOS
};
ekWINDOWS

Microsoft Windows.

ekMACOS

Apple macOS.

ekLINUX

GNU/Linux.

ekIOS

Apple iOS.


enum device_t

Device type.

enum device_t
{
    ekDESKTOP,
    ekPHONE,
    ekTABLET
};
ekDESKTOP

Desktop or laptop computer.

ekPHONE

Phone.

ekTABLET

Tablet.


enum win_t

Microsoft Windows versions.

enum win_t
{
    ekWIN_9x,
    ekWIN_NT4,
    ekWIN_2K,
    ekWIN_XP,
    ekWIN_XP1,
    ekWIN_XP2,
    ekWIN_XP3,
    ekWIN_VI,
    ekWIN_VI1,
    ekWIN_VI2,
    ekWIN_7,
    ekWIN_71,
    ekWIN_8,
    ekWIN_81,
    ekWIN_10,
    ekWIN_NO
};
ekWIN_9x

Windows 95, 98 or ME.

ekWIN_NT4

Windows NT4.

ekWIN_2K

Windows 2000.

ekWIN_XP

Windows XP.

ekWIN_XP1

Windows XP Service Pack 1.

ekWIN_XP2

Windows XP Service Pack 2.

ekWIN_XP3

Windows XP Service Pack 3.

ekWIN_VI

Windows Vista.

ekWIN_VI1

Windows Vista Service Pack 1.

ekWIN_VI2

Windows Vista Service Pack 2.

ekWIN_7

Windows 7.

ekWIN_71

Windows 7 Service Pack 1.

ekWIN_8

Windows 8.

ekWIN_81

Windows 8 Service Pack 1.

ekWIN_10

Windows 10.

ekWIN_NO

The system is not Windows.


enum endian_t

Represents the Byte order, or how multi-byte data is stored in memory.

enum endian_t
{
    ekLITEND,
    ekBIGEND
};
ekLITEND

Little endian. The lowest byte first.

ekBIGEND

Big endian. The highest byte first.


enum week_day_t

Weekday.

enum week_day_t
{
    ekSUNDAY,
    ekMONDAY,
    ekTUESDAY,
    ekWEDNESDAY,
    ekTHURSDAY,
    ekFRIDAY,
    ekSATURDAY
};
ekSUNDAY

Sunday.

ekMONDAY

Monday.

ekTUESDAY

Tuesday.

ekWEDNESDAY

Wednesday.

ekTHURSDAY

Thursday.

ekFRIDAY

Friday.

ekSATURDAY

Saturday.


enum month_t

Month.

enum month_t
{
    ekJANUARY,
    ekFEBRUARY,
    ekMARCH,
    ekAPRIL,
    ekMAY,
    ekJUNE,
    ekJULY,
    ekAUGUST,
    ekSEPTEMBER,
    ekOCTOBER,
    ekNOVEMBER,
    ekDECEMBER
};
ekJANUARY

January.

ekFEBRUARY

February.

ekMARCH

March.

ekAPRIL

April.

ekMAY

May.

ekJUNE

June.

ekJULY

July.

ekAUGUST

August.

ekSEPTEMBER

September.

ekOCTOBER

October.

ekNOVEMBER

November.

ekDECEMBER

December.


enum file_type_t

File type.

enum file_type_t
{
    ekARCHIVE,
    ekDIRECTORY,
    ekOTHERFILE
};
ekARCHIVE

Ordinary file.

ekDIRECTORY

Directory.

ekOTHERFILE

Another type of file reserved for the operating system (devices, pipes, etc.)


enum file_mode_t

Different ways to open a file.

enum file_mode_t
{
    ekREAD,
    ekWRITE,
    ekAPPEND
};
ekREAD

Read only.

ekWRITE

Read and write.

ekAPPEND

Writing at the end of the file.


enum ferror_t

Error codes manipulating files.

enum ferror_t
{
    ekFEXISTS,
    ekFNOPATH,
    ekFNOFILE,
    ekFBIGNAME,
    ekFNOFILES,
    ekFNOEMPTY,
    ekFNOACCESS,
    ekFLOCK,
    ekFBIG,
    ekFUNDEF,
    ekFOK
};
ekFEXISTS

The file already exists.

ekFNOPATH

The directory does not exist.

ekFNOFILE

The file does not exists.

ekFBIGNAME

The name of the file exceeds the capacity of the buffer to store it.

ekFNOFILES

There are no more files when we travel through a directory. bfile_dir_get.

ekFNOEMPTY

You are trying to delete a non-empty directory. hfile_dir_destroy.

ekFNOACCESS

The file can not be accessed (possibly due to lack of permissions).

ekFLOCK

The file is being used by another process.

ekFBIG

The file is so big. It may appear in functions that can not handle files larger than 4Gb.

ekFUNDEF

There is no more information about the error.

ekFOK

There is no error.


enum perror_t

Error codes working with processes.

enum perror_t
{
    ekPPIPE,
    ekPEXEC,
    ekPOK
};
ekPPIPE

Error in the standard I/O channel.

ekPEXEC

Error when launching the process. Surely the command is invalid.

ekPOK

There is no error.


enum serror_t

Error code in network communications.

enum serror_t
{
    ekSNONET,
    ekSNOHOST,
    ekSTIMEOUT,
    ekSSTREAM,
    ekSUNDEF,
    ekSOK
};
ekSNONET

There is no Internet connection on the device.

ekSNOHOST

Unable to connect to the remote server.

ekSTIMEOUT

The maximum wait time for the connection has been exceeded.

ekSSTREAM

Error in the I/O channel when reading or writing.

ekSUNDEF

There is no more information about the error.

ekSOK

There is no error.


struct Date

Public structure that contains the fields of a time stamp (date + time) for direct access.

struct Date
{
    int16_t year;
    uint8_t month;
    uint8_t wday;
    uint8_t mday;
    uint8_t hour;
    uint8_t minute;
    uint8_t second;
};
year

Year.

month

The month (1-12). month_t.

wday

The day of the week (0-6). week_day_t.

mday

The day of the month (1-31).

hour

The hour (0-23).

minute

The minute (0-59).

second

The second (0-59).


struct Dir

Represents an open directory, by which you can browse. bfile_dir_open.

struct Dir;

struct File

File handler on disk. bfile_open.

struct File;

struct Mutex

Mutual exclusion mechanism ( mutex) used to control concurrent access to a resource. Locks.

struct Mutex;

struct Proc

Represents a running process, with which the main program can communicate using the standard I/O channels. bproc_exec.

struct Proc;

struct ProcOpt

Process execution options.

struct ProcOpt
{
    uint32_t unused;
};
unused

For future requirements.


struct Thread

Represents a thread of execution, launched from the main process. bthread_create.

struct Thread;

struct Socket

Handler of network connection. bsocket_connect.

struct Socket;

struct SockOpt

Options for creating a socket.

struct SockOpt
{
    uint32_t rcvtimeo_ms;
    uint32_t sndtimeo_ms;
};
rcvtimeo_ms

Maximum waiting time for a connection (timeout), on the receiver side. 0=without timeout.

sndtimeo_ms

timeout, on the client side. 0=without timeout.


FPtr_thread_main

Prototype of a thread start function (thread main). bthread_create.

uint32_t
(*FPtr_thread_main)(type *data);
data

Data passed to the thread main function.

Return

The thread return value.


osbs_start ()

Start osbs library, reserving space for global internal structures.

void
osbs_start(void);

osbs_finish ()

Ends osbs library, freeing space from global internal structures.

void
osbs_finish(void);

osbs_platform ()

Get the operating system in which the application is running.

platform_t
osbs_platform(void);

Return

The platform.


osbs_windows ()

Get the Windows version.

win_t
osbs_windows(void);

Return

The Microsoft Windows version.


osbs_endian ()

Get the Byte order of the running platform.

endian_t
osbs_endian(void);

Return

The byte order of multi-byte data types.

❮ Back
Next ❯