Difference between revisions of "Standard library"

From Embedded Xinu
Jump to navigation Jump to search
m (Changed headers in <limits.h> summary)
 
(13 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{Update}}
+
The Embedded XINU standard library contains a portion of the functions defined by the ANSI standard.  The functions parallel the ANSI standard C library as closely as possible.
The Embedded XINU standard library contains a portion of the functions defined by the ANSI standard.  The functions parallel the ANSI standard C library as close as possible.
 
  
 
== Input and Output <stdio.h> ==
 
== Input and Output <stdio.h> ==
The input and output functions are currently being tested and augmented.
+
 
 +
=== Formatted output ===
 +
&nbsp;&nbsp;&nbsp;'''fprintf''' - print output to <code>dev</code> formatted according to the format string <code>fmt</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int fprintf(int dev, char *fmt, ...)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''printf''' - same as <code>fprintf (CONSOLE, ...)</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int printf(...)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''sprintf''' - same as <code>printf</code> except output is written to the string <code>str</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int sprintf(char *str, char *fmt, ...)</code>
 +
 
 +
=== Formatted input ===
 +
''This portion of the library is still unstable.''
 +
 
 +
=== Character input and output ===
 +
&nbsp;&nbsp;&nbsp;'''fgetc''' - read the next character from device <code>dev</code>; return EOF if end of file or an error occurs
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int fgetc(int dev)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''fputc''' - write a character <code>c</code> to device <code>dev</code>; return EOF if an error occurs
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int fputc(int c, int dev)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''fgets''' - return a newline-terminated string <code>s</code> of maximum length <code>n</code> from device <code>dev</code>; return NULL if end of file or an error occurs
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *fgets(char *s, int n, int dev)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''fputs''' - write a string <code>s</code> to device <code>dev</code>; return EOF if an error occurs
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int fputs(char *s, int dev)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''getchar''' - same as <code>fgetc(CONSOLE)</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int getchar()</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''putchar''' - same as <code>fputc(c,CONSOLE</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int putchar(int c)</code>
  
 
== Character Class Tests <ctype.h> ==
 
== Character Class Tests <ctype.h> ==
Line 27: Line 66:
  
 
== String Functions <string.h> ==
 
== String Functions <string.h> ==
The header <code>string.h</code> consists of functions used to compare and manipulate strings.  The main string functions consist of:
+
The header <code>string.h</code> consists of functions used to compare and manipulate strings.   
 +
 
 +
=== Str functions ===
 +
The main string functions consist of:
  
 
&nbsp;&nbsp;&nbsp;'''String copy''' - copies string <code>s2</code> to string <code>s1</code>; return <code>s1</code>
 
&nbsp;&nbsp;&nbsp;'''String copy''' - copies string <code>s2</code> to string <code>s1</code>; return <code>s1</code>
Line 56: Line 98:
 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
<code>char *strstr (const char *cs, const char *ct)</code>
 
<code>char *strstr (const char *cs, const char *ct)</code>
 +
 +
=== Strn functions ===
  
 
Some string functions are also defined with the option to specify length limitations:
 
Some string functions are also defined with the option to specify length limitations:
Line 71: Line 115:
 
<code>int strncmp(const char *s1, const char *s2, int n)</code>
 
<code>int strncmp(const char *s1, const char *s2, int n)</code>
  
 +
=== Mem functions ===
 
The string library also includes functions for manipulating objects as character arrays:
 
The string library also includes functions for manipulating objects as character arrays:
  
Line 90: Line 135:
  
 
== Utility Functions <stdlib.h> ==
 
== Utility Functions <stdlib.h> ==
The utility functions are currently being tested and augmented.
+
The <code>stdlib.h</code> header contains a wide array of utility functions for number conversion, memory allocation, and sorting.
 +
 
 +
=== Number conversion ===
 +
&nbsp;&nbsp;&nbsp;'''ASCII to integer''' - converts and ASCII value <code>p</code> to an integer
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int atoi(char *p)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''ASCII to long''' - converts and ASCII value <code>p</code> to a long
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>long atol(char *p)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Absolute value''' - returns the absolute value of the integer <code>arg</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int abs(int arg)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Long absolute value''' - returns the absolute value of the long <code>arg</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>long abs(long arg)</code>
 +
 
 +
=== Memory allocation ===
 +
&nbsp;&nbsp;&nbsp;'''Calloc''' - returns a pointer to a memory location with space for <code>nobj</code> objects each of size <code>size</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void *calloc(ulong nobj, ulong size)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Malloc''' - returns a pointer to a memory location with space for <code>size</code> bytes
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void *malloc(ulong size)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Free''' - deallocates a portion of memory starting at <code>p</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>long free(void *p)</code>
 +
 
 +
=== Miscellaneous ===
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Zero memory''' - zeroes <code>len</code> bytes of memory starting at <code>p</code>
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void bzero(void *p, int len)</code>
 +
 
 +
&nbsp;&nbsp;&nbsp;'''Random number''' - generates a random long
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>unsigned long rand(void)</code>
  
 
== Diagnostics <assert.h> ==
 
== Diagnostics <assert.h> ==
Line 97: Line 182:
 
== Variable Argument Lists <stdarg.h> ==
 
== Variable Argument Lists <stdarg.h> ==
 
Functions with a variable number of unknown type arguments rely on functions in the <code>stdarg.h</code> header to obtain the arguments provided to the function.  A variable of type <code>va_list</code> must be defined within the function to hold the variable argument list.  The variable holding the variable argument list must be initialized using the <code>va_start(va_list ap, ''lastarg'')</code> function, where <code>''lastarg''</code> is the name of the argument prior to the variable argument list in the function signature.  Arguments are obtained from the variable argument list using <code>va_arg(va_list ap, ''type'')</code>, where <code>''type''</code> specifies the expected type of the next argument in the list.  When argument reading is complete, the function <code>va_end(va_list ap)</code> is called, providing the variable argument list as an argument.
 
Functions with a variable number of unknown type arguments rely on functions in the <code>stdarg.h</code> header to obtain the arguments provided to the function.  A variable of type <code>va_list</code> must be defined within the function to hold the variable argument list.  The variable holding the variable argument list must be initialized using the <code>va_start(va_list ap, ''lastarg'')</code> function, where <code>''lastarg''</code> is the name of the argument prior to the variable argument list in the function signature.  Arguments are obtained from the variable argument list using <code>va_arg(va_list ap, ''type'')</code>, where <code>''type''</code> specifies the expected type of the next argument in the list.  When argument reading is complete, the function <code>va_end(va_list ap)</code> is called, providing the variable argument list as an argument.
 
== Signals <signal.h> ==
 
Signals are not currently implemented in the XINU standard library.  However, this portion of the library would be a beneficial addition for future releases.  The header <code>signal.h</code> provides functionality for handling conditions that arise during execution including termination and error conditions.
 
 
== Date and Time Functions <time.h> ==
 
Dates and times are not currently used in Embedded XINU.  However, this portion of the library would be a beneficial addition for future releases.  The header <code>time.h</code> provides functions for date and time formatting and determining current date and time.  This header would be more useful after the network driver is complete and Embedded XINU is able to synchronize with an time server.
 
  
 
== Implementation-defined Limits <limits.h> ==
 
== Implementation-defined Limits <limits.h> ==
 
The header <code>limits.h</code> defines maximum and minimum values for the integral C types.  The constants defined are set according to the 32-bit Mips architecture of the [[List_of_supported_platforms | supported platforms]].
 
The header <code>limits.h</code> defines maximum and minimum values for the integral C types.  The constants defined are set according to the 32-bit Mips architecture of the [[List_of_supported_platforms | supported platforms]].
  
'''Char'''
+
=== Char ===
 
* Bits in a character = 8
 
* Bits in a character = 8
 
* Maximum value of a <code>char</code> = +127
 
* Maximum value of a <code>char</code> = +127
Line 115: Line 194:
 
* Maximum value of an <code>unsigned char</code> (<code>uchar</code>) = 255
 
* Maximum value of an <code>unsigned char</code> (<code>uchar</code>) = 255
  
'''Int'''
+
=== Int ===
 
* Maximum value of an <code>int</code> = +2147483647
 
* Maximum value of an <code>int</code> = +2147483647
 
* Minimum value of an <code>int</code> = -2147483648
 
* Minimum value of an <code>int</code> = -2147483648
 
* Maximum value of an <code>unsigned int</code> = 4294967295
 
* Maximum value of an <code>unsigned int</code> = 4294967295
  
'''Long'''
+
=== Long ===
 
* Maximum value of a <code>long</code> = +2147483647
 
* Maximum value of a <code>long</code> = +2147483647
 
* Minimum value of a <code>long</code> = -2147483648
 
* Minimum value of a <code>long</code> = -2147483648
 
* Maximum value of an <code>unsigned long</code> (<code>ulong</code>) = 4294967295
 
* Maximum value of an <code>unsigned long</code> (<code>ulong</code>) = 4294967295
  
'''Short'''
+
=== Short ===
 
* Maximum value of a <code>short</code> = +32767
 
* Maximum value of a <code>short</code> = +32767
 
* Minimum value of a <code>short</code> = -32768
 
* Minimum value of a <code>short</code> = -32768
Line 131: Line 210:
  
 
== Not Implemented Headers ==
 
== Not Implemented Headers ==
Some of the ANSI standard library headers are not included in the XINU standard library, nor are there reasons to add these headers. The following headers have been excluded due to architectural limitations and lack of feasibility:
+
Some of the ANSI standard library headers are not included in the XINU standard library.  Some headers have been noted as possible later additions:
 +
* <code>signal.h</code> - provides functionality for handling conditions that arise during execution including termination and error conditions
 +
* <code>time.h</code> - provides functions for date and time formatting and determining current date and time; dates and times are not currently used in Embedded XINU, but would be more useful after the network driver is complete and Embedded XINU is able to synchronize with an time server.
 +
 
 +
The following headers have been excluded due to architectural limitations and lack of feasibility:
 
* <code>math.h</code>
 
* <code>math.h</code>
 
* <code>float.h</code>
 
* <code>float.h</code>

Latest revision as of 21:37, 24 January 2010

The Embedded XINU standard library contains a portion of the functions defined by the ANSI standard. The functions parallel the ANSI standard C library as closely as possible.

Input and Output <stdio.h>

Formatted output

   fprintf - print output to dev formatted according to the format string fmt
       int fprintf(int dev, char *fmt, ...)

   printf - same as fprintf (CONSOLE, ...)
       int printf(...)

   sprintf - same as printf except output is written to the string str
       int sprintf(char *str, char *fmt, ...)

Formatted input

This portion of the library is still unstable.

Character input and output

   fgetc - read the next character from device dev; return EOF if end of file or an error occurs
       int fgetc(int dev)

   fputc - write a character c to device dev; return EOF if an error occurs
       int fputc(int c, int dev)

   fgets - return a newline-terminated string s of maximum length n from device dev; return NULL if end of file or an error occurs
       char *fgets(char *s, int n, int dev)

   fputs - write a string s to device dev; return EOF if an error occurs
       int fputs(char *s, int dev)

   getchar - same as fgetc(CONSOLE)
       int getchar()

   putchar - same as fputc(c,CONSOLE
       int putchar(int c)

Character Class Tests <ctype.h>

Most of the macros defined in the ctype.h header are used to identify properties of specific ASCII characters. The macros return TRUE if a character is a member of a particular category, otherwise the macro returns FALSE. The following macros are defined to determine if a character has the listed property:

  • isalpha - letter
  • isupper - uppercase letter
  • islower - lowercase letter
  • isdigit - digit
  • isxdigit - hexadecimal digit
  • ishexnumber - hexadecimal digit
  • isspace - white space
  • ispunct - punctuation
  • isalnum - alphanumeric
  • isprshort - printable character that is not a letter, digit, or white space
  • isprint - printable character
  • iscntrl - control character
  • isascii

A few macros in the ctype.h header convert characters. These macros convert characters as follows:

  • toupper - convert letter to uppercase
  • tolower - convert letter to lowercase
  • toascii

String Functions <string.h>

The header string.h consists of functions used to compare and manipulate strings.

Str functions

The main string functions consist of:

   String copy - copies string s2 to string s1; return s1
       char *strcpy(char *s1, const char *s2)

   String concatenate - concatenate s2 on the end of s1, s1's space must be large enough; return s1
       char *strcat(char *s1, const char *s2)

   String compare - compares s1 and s2; return s1>s2: >0 s1==s2: 0 s1<s2: <0
       int strcmp(const char *s1, const char *s2)

   Character search - returns a pointer to the location in s at which which c appears
       char *strchr (const char *s, int c)

   Reverse character search - returns a pointer to the location in s at which which c last appears
       char *strrchr(const char *s, int c)

   String length - returns the length of s
       int strlen(const char *s)

   String search - returns a pointer to the location in cs at which ct appears
       char *strstr (const char *cs, const char *ct)

Strn functions

Some string functions are also defined with the option to specify length limitations:

   String n copy - copies string s2 to string s1, truncating or null padding to always copy n bytes; return s1
       char *strncpy(char *s1, const char *s2, int n)

   String n concatenate - concatenate at most n bytes of s2 on the end of s1, s1's space must be large enough; return s1
       char *strncat(char *s1, const char *s2, int n)

   String n compare - compares at most n bytes of s1 and s2; return s1>s2: >0 s1==s2: 0 s1<s2: <0
       int strncmp(const char *s1, const char *s2, int n)

Mem functions

The string library also includes functions for manipulating objects as character arrays:

   Memory copy - copy n bytes of memory from cs to ct
       void *memcpy(void *s, const void *ct, int n)

   Memory compare - compare n bytes of memory at locations cs and ct
       int memcmp (const void *s1, const void *s2, int n)

   Memory search - returns a pointer to the location in memory at which which a c appears, starting at cs and searching at most n bytes
       void *memchr (const void *cs, int c, int n)

   Memory set - fill n bytes of memory with c starting at n
       void *memset (void *s, int c, int n)

Utility Functions <stdlib.h>

The stdlib.h header contains a wide array of utility functions for number conversion, memory allocation, and sorting.

Number conversion

   ASCII to integer - converts and ASCII value p to an integer
       int atoi(char *p)

   ASCII to long - converts and ASCII value p to a long
       long atol(char *p)

   Absolute value - returns the absolute value of the integer arg
       int abs(int arg)

   Long absolute value - returns the absolute value of the long arg
       long abs(long arg)

Memory allocation

   Calloc - returns a pointer to a memory location with space for nobj objects each of size size
       void *calloc(ulong nobj, ulong size)

   Malloc - returns a pointer to a memory location with space for size bytes
       void *malloc(ulong size)

   Free - deallocates a portion of memory starting at p
       long free(void *p)

Miscellaneous

   Zero memory - zeroes len bytes of memory starting at p
       void bzero(void *p, int len)

   Random number - generates a random long
       unsigned long rand(void)

Diagnostics <assert.h>

A macro ASSERT(int expression) is defined in kernel.h. The ASSERT macro verifies the specified expression is true, otherwise the function containing the assert will return SYSERR. No assert.h header file is included in the Embedded XINU standard library.

Variable Argument Lists <stdarg.h>

Functions with a variable number of unknown type arguments rely on functions in the stdarg.h header to obtain the arguments provided to the function. A variable of type va_list must be defined within the function to hold the variable argument list. The variable holding the variable argument list must be initialized using the va_start(va_list ap, lastarg) function, where lastarg is the name of the argument prior to the variable argument list in the function signature. Arguments are obtained from the variable argument list using va_arg(va_list ap, type), where type specifies the expected type of the next argument in the list. When argument reading is complete, the function va_end(va_list ap) is called, providing the variable argument list as an argument.

Implementation-defined Limits <limits.h>

The header limits.h defines maximum and minimum values for the integral C types. The constants defined are set according to the 32-bit Mips architecture of the supported platforms.

Char

  • Bits in a character = 8
  • Maximum value of a char = +127
  • Minimum value of a char = -128
  • Maximum value of a signed char = +127
  • Minimum value of a signed char = -128
  • Maximum value of an unsigned char (uchar) = 255

Int

  • Maximum value of an int = +2147483647
  • Minimum value of an int = -2147483648
  • Maximum value of an unsigned int = 4294967295

Long

  • Maximum value of a long = +2147483647
  • Minimum value of a long = -2147483648
  • Maximum value of an unsigned long (ulong) = 4294967295

Short

  • Maximum value of a short = +32767
  • Minimum value of a short = -32768
  • Maximum value of an unsigned short (ushort) = 65535

Not Implemented Headers

Some of the ANSI standard library headers are not included in the XINU standard library. Some headers have been noted as possible later additions:

  • signal.h - provides functionality for handling conditions that arise during execution including termination and error conditions
  • time.h - provides functions for date and time formatting and determining current date and time; dates and times are not currently used in Embedded XINU, but would be more useful after the network driver is complete and Embedded XINU is able to synchronize with an time server.

The following headers have been excluded due to architectural limitations and lack of feasibility:

  • math.h
  • float.h
  • setjmp.h
  • locale.h
  • errno.h
  • stddef.h

References

  1. Brian Kernighan and Dennis Ritchie. The C Programming Language, second edition. Prentice Hall.