Difference between revisions of "Standard library"

From Embedded Xinu
Jump to navigation Jump to search
(Added string n functions and memory functions to <string.h> summary)
m (Indented functions included in <string.h>)
Line 29: Line 29:
 
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.  The main string functions consist of:
  
'''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>
<br><code>char *strcpy(char *s1, const char *s2)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strcpy(char *s1, const char *s2)</code>
  
'''String concatenate''' - concatenate <code>s2</code> on the end of <code>s1</code>, <code>s1</code>'s space must be large enough; return <code>s1</code>
+
&nbsp;&nbsp;&nbsp;'''String concatenate''' - concatenate <code>s2</code> on the end of <code>s1</code>, <code>s1</code>'s space must be large enough; return <code>s1</code>
<br><code>char *strcat(char *s1, const char *s2)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strcat(char *s1, const char *s2)</code>
  
'''String compare''' - compares <code>s1</code> and <code>s2</code>; return <code>s1>s2</code>: >0  <code>s1==s2</code>: 0  <code>s1<s2</code>: <0
+
&nbsp;&nbsp;&nbsp;'''String compare''' - compares <code>s1</code> and <code>s2</code>; return <code>s1>s2</code>: >0  <code>s1==s2</code>: 0  <code>s1<s2</code>: <0
<br><code>int strcmp(const char *s1, const char *s2)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int strcmp(const char *s1, const char *s2)</code>
  
'''Character search''' - returns a pointer to the location in <code>s</code> at which which <code>c</code> appears
+
&nbsp;&nbsp;&nbsp;'''Character search''' - returns a pointer to the location in <code>s</code> at which which <code>c</code> appears
<br><code>char *strchr (const char *s, int c)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strchr (const char *s, int c)</code>
  
'''Reverse character search''' - returns a pointer to the location in s at which which <code>c</code> last appears
+
&nbsp;&nbsp;&nbsp;'''Reverse character search''' - returns a pointer to the location in s at which which <code>c</code> last appears
<br><code>char *strrchr(const char *s, int c)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strrchr(const char *s, int c)</code>
  
'''String length''' - returns the length of <code>s</code>
+
&nbsp;&nbsp;&nbsp;'''String length''' - returns the length of <code>s</code>
<br><code>int strlen(const char *s)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int strlen(const char *s)</code>
  
'''String search''' - returns a pointer to the location in <code>cs</code> at which <code>ct</code> appears
+
&nbsp;&nbsp;&nbsp;'''String search''' - returns a pointer to the location in <code>cs</code> at which <code>ct</code> appears
<br><code>char *strstr (const char *cs, const char *ct)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strstr (const char *cs, const char *ct)</code>
  
 
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:
  
'''String n copy''' - copies string <code>s2</code> to string <code>s1</code>, truncating or null padding to always copy <code>n</code> bytes; return <code>s1</code>
+
&nbsp;&nbsp;&nbsp;'''String n copy''' - copies string <code>s2</code> to string <code>s1</code>, truncating or null padding to always copy <code>n</code> bytes; return <code>s1</code>
<br><code>char *strncpy(char *s1, const char *s2, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strncpy(char *s1, const char *s2, int n)</code>
  
'''String n concatenate''' - concatenate at most <code>n</code> bytes of <code>s2</code> on the end of <code>s1</code>, <code>s1</code>'s space must be large enough; return <code>s1</code>
+
&nbsp;&nbsp;&nbsp;'''String n concatenate''' - concatenate at most <code>n</code> bytes of <code>s2</code> on the end of <code>s1</code>, <code>s1</code>'s space must be large enough; return <code>s1</code>
<br><code>char *strncat(char *s1, const char *s2, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>char *strncat(char *s1, const char *s2, int n)</code>
  
'''String n compare''' - compares at most <code>n</code> bytes of <code>s1</code> and <code>s2</code>; return <code>s1>s2</code>: >0  <code>s1==s2</code>: 0  <code>s1<s2</code>: <0
+
&nbsp;&nbsp;&nbsp;'''String n compare''' - compares at most <code>n</code> bytes of <code>s1</code> and <code>s2</code>; return <code>s1>s2</code>: >0  <code>s1==s2</code>: 0  <code>s1<s2</code>: <0
<br><code>int strncmp(const char *s1, const char *s2, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int strncmp(const char *s1, const char *s2, int n)</code>
  
 
The string library also includes functions for manipulating objects as character arrays:
 
The string library also includes functions for manipulating objects as character arrays:
  
'''Memory copy''' - copy <code>n</code> bytes of memory from <code>cs</code> to <code>ct</code>
+
&nbsp;&nbsp;&nbsp;'''Memory copy''' - copy <code>n</code> bytes of memory from <code>cs</code> to <code>ct</code>
<br><code>void *memcpy(void *s, const void *ct, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void *memcpy(void *s, const void *ct, int n)</code>
  
'''Memory compare''' - compare <code>n</code> bytes of memory at locations <code>cs</code> and <code>ct</code>
+
&nbsp;&nbsp;&nbsp;'''Memory compare''' - compare <code>n</code> bytes of memory at locations <code>cs</code> and <code>ct</code>
<br><code>int memcmp (const void *s1, const void *s2, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>int memcmp (const void *s1, const void *s2, int n)</code>
  
'''Memory search''' - returns a pointer to the location in memory at which which a <code>c</code> appears, starting at <code>cs</code> and searching at most <code>n</code> bytes
+
&nbsp;&nbsp;&nbsp;'''Memory search''' - returns a pointer to the location in memory at which which a <code>c</code> appears, starting at <code>cs</code> and searching at most <code>n</code> bytes
<br><code>void *memchr (const void *cs, int c, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void *memchr (const void *cs, int c, int n)</code>
  
'''Memory set''' - fill <code>n</code> bytes of memory with <code>c</code> starting at <code>n</code>
+
&nbsp;&nbsp;&nbsp;'''Memory set''' - fill <code>n</code> bytes of memory with <code>c</code> starting at <code>n</code>
<br><code>void *memset (void *s, int c, int n)</code>
+
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 +
<code>void *memset (void *s, int c, int n)</code>
  
 
== Utility Functions <stdlib.h> ==
 
== Utility Functions <stdlib.h> ==

Revision as of 15:53, 31 July 2007

Clockimportant.png This article or section needs to be updated.
Parts of this article or section have been identified as no longer being up to date.
Please update the article to reflect recent changes, and remove this template when finished.

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>

The input and output functions are currently being tested and augmented.

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

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)

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 utility functions are currently being tested and augmented.

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.

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 signal.h 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 time.h 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>

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, nor are there reasons to add these headers. 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.