Some system related basic functions for Raspberry Pis. More...

#include "sysBasic.h"

Functions
uint8_t	errLogIsStd (void)
	Error log (errLog) is standard stream or outLog.

int	formatDec2Digs (char *targTxt, uint32_t value)
	Format number as two digit decimal number with leading zeroes. More...

int	formatDec3Digs (char *targTxt, uint32_t value)
	Format number as three digit decimal number with leading zeroes. More...

int	formatTmTim (char rTmTxt, struct tm rTm)
	Format broken down real time and date as standard text. More...

int	formatTmTiMs (char rTmTxt, struct tm rTm, int millis)
	Format broken down real time clock+ms as standard text. More...

uint8_t	isFNaN (float const val)
	Floating point NaN. More...

uint8_t	littleEndian ()
	Actual runtime / architecture is little endian. More...

void	logEventText (char const *txt)
	Log an event/log message on outLog. More...

void	monoTimeInit (timespec *timer)
	Absolute timer initialisation. More...

uint8_t	outLogIsStd (void)
	Event log (outLog) is standard stream.

void	printNamRevDat (void)
	Print the program name, SVN revision and date. More...

void	printRevDat (void)
	Print the program SVN revision and date. More...

char const *	progDat ()
	The program date. More...

char const *	progNam ()
	The program name. More...

char const *	progNamB ()
	The program name with blank. More...

char const *	progRev ()
	The program revision. More...

size_t	strlcat (char dest, char const src, size_t num)
	String concatenation with limit. More...

size_t	strlcpy (char dest, char const src, size_t const num)
	String copy with limit. More...

int	switchErrorLog (char const *const errFilNam)
	Switch errlog to other file. More...

int	switchEventLog (char const *const logFilNam)
	Switch outLog to other file. More...

void	timeAddNs (timespec *t1, long ns)
	Add a ns increment to a time overwriting it. More...

int	timeStep (timespec *timeSp, unsigned int micros)
	A delay to an absolute step specified in number of ��s to a given time. More...

void	updateReaLocalTime (void)
	Update local real time. More...

Variables
timespec	actRTime
	Actual time (structure, real time clock).

struct tm	actRTm
	Actual time (broken down structure / local). More...

float const	cosDiY [192]
	Cosine of day in year, look up. More...

int16_t const	cosDiY60 [192]
	Cosine of day in year * 60. More...

char const	dec2digs [128][2]
	Format two digit decimal, leading zero, by lookup. More...

char const	dec3digs [1024][4]
	Format three digit decimal, leading zero, 0-terminated, by lookup. More...

char const	dow [9][4]
	English weekdays, two letter abbreviation. More...

FILE *	errLog
	Error log output. More...

char const	fType [16][8]
	Translation of directory entry typed to 8 char text. More...

char const *const	lckPiGpioPth
	Common path to a lock file for GpIO use. More...

__time_t	localMidnight
	Actual local midnight. More...

uint32_t	noLgdEvnt
	Number of events logged. More...

FILE *	outLog
	Event log output. More...

uint8_t	progNamLen
	char progNamPure[] = PROGNAME;

int	retCode
	Basic start-up function failure. More...

int	todayInYear
	Today's day in year. More...

int	useErrLogFiles
	Log on files. More...

uint8_t	useOutLog4errLog
	Use outLog for errors too. More...

__time_t	utcMidnight
	Actual (local) UTC midnight. More...

char const	zif2charMod10 [44]
	The digits 0..9 repeated as 44 characters. More...

Detailed Description

Some system related basic functions for Raspberry Pis.

Copyright  (c)  2020   Albrecht Weinert
weinert-automation.de      a-weinert.de
 
    /         /      /\
   /         /___   /  \      |
   \        /____\ /____\ |  _|__
    \  /\  / \    /      \|   |
     \/  \/   \__/        \__/|_                                 

Revision history

Rev. 253 9.10.2023
Rev.  105 06.02.2018 : new (transfered parts from sysutil.c)
Rev.  108 12.02.2018 : parts moved out, one event file; Started to get
                      Doxygen usable. Note: Not yet done.
Rev. 147 16.06.2018 : time handling enhanced improved
Rev. 155 27.06.2018 : time handling debugged
Rev. 164 11.07.2018 : sunset/sunrise location parameters; string functions
Rev. 229 23.07.2020 : UTF 8 BOM for log and error file

cross-compile by:

arm-linux-gnueabihf-gcc -DMCU=BCM2837 -I./include -c -o weRasp/sysBasic.o weRasp/sysBasic.c

For documentation see the include file sysBasic.h

Function Documentation

◆ progNam()

char const * progNam ( )

The program name.

Returns: the program's name as pure text, "homeDoorPhone", e.g.

◆ progNamB()

char const * progNamB ( )

The program name with blank.

Same as progNam but with at least one trailing blank or so many blanks to get a minimal length of 17, , "homeDoorPhone ", e.g.

Returns: the program's name with trailing blank(s)

◆ progRev()

char const * progRev ( )

The program revision.

Returns: the program's SVN revision as pure text, "0", "341" e.g.

◆ progDat()

char const * progDat ( )

The program date.

Returns: the program's SVN date "2020-07-23" e.g., length 10

◆ printRevDat()

void printRevDat ( void )

Print the program SVN revision and date.

This function prints a line in the form (4 leading blanks)

Revision 229 (2020-07-23)

to outLog

◆ printNamRevDat()

void printNamRevDat ( void )

Print the program name, SVN revision and date.

This function prints a line in the form (4 leading blanks)

theLittleProg R. 229 (2020-07-23)

to outLog

◆ isFNaN()

uint8_t isFNaN ( float const val )

Floating point NaN.

Parameters

val	the floating point value to be checked for IEEE754 NaN

Returns: 0xFF (true) when not a number, else 0

◆ littleEndian()

uint8_t littleEndian ( )

Actual runtime / architecture is little endian.

This boolean function is evaluated by char* to int comparison.

To save runtime resources use the marco PLATFlittlE instead, which would fall back to littleEndian() (this function) when no target platform informations on endianness are available.

Returns: true when platform is little endian (evaluated at run time)

◆ switchErrorLog()

int switchErrorLog ( char const *const errFilNam )

Switch errlog to other file.

Parameters

errFilNam the name of the file to switch to; NULL or empty: switch (back) to stderr

Returns: 96 : file name can't be opened for append, old state kept; 97 : useOutLog4errLog is ON, nothing done 0 : OK

◆ switchEventLog()

int switchEventLog ( char const *const logFilNam )

Switch outLog to other file.

If useOutLog4errLog is ON the errLog file will point to the same named file on success.

Parameters

logFilNam the name of the file to switch to; NULL or empty: switch (back) to stdout

Returns: 96 : file name can't be opened for append; old state kept.

◆ logEventText()

void logEventText ( char const * txt )

Log an event/log message on outLog.

If txt is not null it will be output to outLog and outLog will be flushed. No line feed will be appended; the text is put as is.

Parameters

txt	text to be output; n.b not LF appended and not counted as line

◆ monoTimeInit()

void monoTimeInit ( timespec * timer )

Absolute timer initialisation.

This function sets the time structure provided to the current absolute monotonic ABS_MONOTIME (default: CLOCK_MONOTONIC).

Note: Error returns, suppressed here, cannot occur, as long as the time library functions and used clock IDs are implemented. Otherwise all else timing done here would fail completely.

Parameters

timer the time structure to be used (never NULL!)

◆ timeStep()

int timeStep	(	timespec *	timeSp,
		unsigned int	micros
	)

A delay to an absolute step specified in number of ��s to a given time.

This function does an absolute monotonic real time delay until timer += micros;

Chaining this calls can give absolute triggers relative to a given start. One must initialise the time structure timespec before every start of a new cycle chain. Afterwards the structure time must not be written to. See timeAddNs, ABS_MONOTIME and monoTimeInit (or clock_gettime).

Chaining absolute delays accomplishes long term exact periods respectively cycles. See also explanations in ABS_MONOTIME (default: CLOCK_MONOTONIC).

Parameters

timeSp	the time structure to be used (never NULL!)
micros	delay in ��s (recommended 100��s .. 1h)

Returns: sleep's return value if of interest (0: uninterrupted)

◆ timeAddNs()

void timeAddNs	(	timespec *	t1,
		long	ns
	)

Add a ns increment to a time overwriting it.

Parameters

t1	the time structure to add to (not NULL!, will be modified)
ns	the increment in nanoseconds

◆ updateReaLocalTime()

void updateReaLocalTime ( void )

Update local real time.

This function initialises / updates both actRTime and actRTm.

◆ strlcpy()

size_t strlcpy	(	char *	dest,
		char const *	src,
		size_t const	num
	)

String copy with limit.

This function copies at most num - 1 characters from src to dst. If not terminated by a 0 from src, dest[num-1] will be set 0. Hence, except for num == 0, dest will be 0-terminated.

The value returned is the length of string src; if this value is not less than num truncation occurred.

Hint: This function resembles the one from bsd/string.h usually not available with standard Linuxes and Raspbians .

Parameters

dest	the character array to copy to; must not be shorter than num
src	the string to copy from
num	the maximum allowed string length of dest

Returns: the length of src

◆ strlcat()

size_t strlcat	(	char *	dest,
		char const *	src,
		size_t	num
	)

String concatenation with limit.

This function appends at most num - 1 characters from src to the end of dest. If not terminated by a 0 from src, dest[num-1] will be set 0. Hence, except for num == 0, dest will be 0-terminated.

The value returned is the length of string src (if no truncation occurred).

Hint: This function resembles the one from bsd/string.h usually not available with standard Linuxes and Raspbians .

Parameters

dest	the character array to copy to; must not be shorter than num
src	the string to copy from
num	the maximum allowed string length of dest

Returns: the length of src

◆ formatDec2Digs()

int formatDec2Digs	(	char *	targTxt,
		uint32_t	value
	)

Format number as two digit decimal number with leading zeroes.

The format is: 00 to 99

The length is always 2. There is no trailing character zero appended.
returned is the number of leading zeroes in the range 0 o 1. N.B. the value 0 yielding "00" is considered to have one leading zero.

See also: dec2digs formatDec3Digs

Parameters

targTxt	pointer to the target text buffer, must have place for 3 characters (!)
value	the value to be formatted; values outside 0 .. 999 will yield incorrect results

Returns: the number of leading zeroes (0 or 1)

◆ formatDec3Digs()

int formatDec3Digs	(	char *	targTxt,
		uint32_t	value
	)

Format number as three digit decimal number with leading zeroes.

The format is: 000 to 999

The length is always 3. There is no trailing character zero appended.
returned is the number of leading zeroes in the range 0 to 2. N.B. the value 0 yielding "000" is considered to have 2 leading zeroes.

See also: dec3digs formatDec2Digs

Parameters

targTxt	pointer to the target text buffer, must have place for 3 characters (!)
value	the value to be formatted; values outside 0 .. 999 will yield incorrect results

Returns: the number of leading zeroes (0..2)

◆ formatTmTim()

int formatTmTim	(	char *	rTmTxt,
		struct tm *	rTm
	)

Format broken down real time and date as standard text.

The format is: Fr 2017-10-20 13:55:12 UTC+20 ................0123456789x123456789v123456789t The length is 29. See formatTmTiMs() for a longer format with 3 digit ms.

Parameters

rTmTxt	pointer to the target text buffer, must have place for 30 characters (!)
rTm	pointer to broken down real time; NULL will take actRTm

Returns: the number of characters put (should be 28) or 0: error (rTmTxT NULL)

◆ formatTmTiMs()

int formatTmTiMs	(	char *	rTmTxt,
		struct tm *	rTm,
		int	millis
	)

Format broken down real time clock+ms as standard text.

/code The format is: Fr 2017-10-20 13:55:12.987 UTC+20 ................0123456789x123456789v123456789t123 +3 ................0123456789x123456789v123456789t /endcode The length is 33. See formatTmTim() for a shorter format without ms.

Parameters

rTmTxt	pointer to the target text buffer, must have place for 34 characters (!)
rTm	pointer to broken down real time; NULL will take actRTm
millis	milliseconds 0..999 supplement to rTm

Returns: the number of characters put (should be 32) or 0: error (rTmTxT NULL)

Variable Documentation

◆ retCode

int retCode

Basic start-up function failure.

Allows for compact code without saving the (error) return:
if (openLock(lckPiGpioPth, ON)) return retCode;

Storage for return/error codes. Used by: openLock(char const *, uint8_t) theCyclistStart(int) theCyclistWaitEnd()

Value: 0: OK, else: error

◆ lckPiGpioPth

char const* const lckPiGpioPth

Common path to a lock file for GpIO use.

Programs using GPIO in any form usually (and forced by some libraries) have to do this exclusively. This is implemented here by locking a file named /home/pi/bin/.lockPiGpio
Make the lock file by: touch /home/pi/bin/.lockPiGpio

Without locking this file those programs must not start.
So, deleting this file inhibits the start even by cron etc.

◆ useErrLogFiles

int useErrLogFiles

Log on files.

If true (default) logging and errors go to files or one file, otherwise to console

◆ outLog

FILE* outLog

Event log output.

default: standard output; may be put to a file.

◆ noLgdEvnt

uint32_t noLgdEvnt

Number of events logged.

Counter for lines put to or events logged on outLog.

◆ useOutLog4errLog

uint8_t useOutLog4errLog

Use outLog for errors too.

When set true errLog will be set to outLog when using files. In this case there is just one event log file. Hence, doubling the same entry to both errLog and outLog should be avoided.

◆ errLog

FILE* errLog

Error log output.

default: standard error; may be put to a file.

◆ actRTm

struct tm actRTm

Actual time (broken down structure / local).

This structure is initialised may be updated by some timing and cyclic functions. See initStartRTime() and others.

◆ todayInYear

int todayInYear

Today's day in year.

The value should be set at start (will be by updateReaLocalTime()) and updated at midnight.

◆ utcMidnight

__time_t utcMidnight

Actual (local) UTC midnight.

This is the actual "local" UTC midnight. "Local" means that on early hours, i.e. those within zone offset, UTC midnight will be corrected to the next (east of Greenwich) respectively previous day (west). The rationale is to point to the same day or date at day time (around Europe).
Or, to put it simple, utcMidnight is to be set so, that the equation
local Midnight = utcMidnight - UTCoffset
holds.

The value will will be set correctly by updateReaLocalTime(). It should be updated at day change (if used).

◆ localMidnight

__time_t localMidnight

Actual local midnight.

This is the UTC Linux timestamp of the actual day's / time's local midnight. See also utcMidnight for explanations.

Note: On days with DST changes this value will shift within the day. It's mostly better to make calculations relative to day start — sunrise and sunset e.g. — relative to UTC midnight.

◆ cosDiY

float const cosDiY[192]

Cosine of day in year, look up.

This lookup table provides the cosine by the day of the year without resource eating floating point arithmetic or math.h. The rationale is the approximate calculation of sunrise and sunset times based on earliest, latest and delta for any given location within the arctic circles.

The length of the look up table is abundant 192. According to cosine's periodic properties it shall be used in the range 0..183 by applying the following operations to the day in year value
absolute when < 0,
modulo FOURYEARS when >= FOURYEARS,
modulo 365 when >= 365 and
x = 365 - x when > 190.

Note: These rules are implemented in the function cosDay() and in the function cosDay60() using the look up table cosDiY60

◆ cosDiY60

int16_t const cosDiY60[192]

Cosine of day in year * 60.

This look up table is the same as cosDiY, except the values being multiplied by 60 which includes minutes to seconds conversion, avoiding a multiplication and all floating point operations for some applications.

lenght: 192

◆ dow

char const dow[9][4]

English weekdays, two letter abbreviation.

Monday (Mo) is 1; Sunday (Su) is 7 or, also, 0.

◆ dec2digs

char const dec2digs[128][2]

Format two digit decimal, leading zero, by lookup.

"00" .. "99" + "00", "_1" .. "_7"

◆ dec3digs

char const dec3digs[1024][4]

Format three digit decimal, leading zero, 0-terminated, by lookup.

"000" .. "999" + "000" .. "023"

◆ zif2charMod10

char const zif2charMod10[44]

The digits 0..9 repeated as 44 characters.

By using a number 0..43 as index this will give modulo 10 respectively the last decimal digit as character.

◆ fType

char const fType[16][8]

Translation of directory entry typed to 8 char text.

direntry.d_type as index in the range 0..15 gives an 8 character short type text. Note: Only 0, 1, 2, 4, 6, 8, 10, 12 and 14 are defined d_type values. The undefined ones give undef3 .. undefF

Functions

Variables

Detailed Description

Function Documentation

◆ progNam()

◆ progNamB()

◆ progRev()

◆ progDat()

◆ printRevDat()

◆ printNamRevDat()

◆ isFNaN()

◆ littleEndian()

◆ switchErrorLog()

◆ switchEventLog()

◆ logEventText()

◆ monoTimeInit()

◆ timeStep()

◆ timeAddNs()

◆ updateReaLocalTime()

◆ strlcpy()

◆ strlcat()

◆ formatDec2Digs()

◆ formatDec3Digs()

◆ formatTmTim()

◆ formatTmTiMs()

Variable Documentation

◆ retCode

◆ lckPiGpioPth

◆ useErrLogFiles

◆ outLog

◆ noLgdEvnt

◆ useOutLog4errLog

◆ errLog

◆ actRTm

◆ todayInYear

◆ utcMidnight

◆ localMidnight

◆ cosDiY

◆ cosDiY60

◆ dow

◆ dec2digs

◆ dec3digs

◆ zif2charMod10

◆ fType