Author: Mugabi Siro

Category: General Linux

Summary:

This entry describes in-kernel API for basic C library functions. Linux 3.11.0 was used for reference.

Tags: linux

Background

The kernel is a stand-alone piece of code that is not linked against the standard (userspace) C library. Since the need to harness certain C library functionality, such as string conversion and manipulation, often arises when writing kernel code, the kernel provides its own implementations of basic C library functions. Nevertheless, the behaviour of some of these functions may not conform to that defined by the ISO/ANSI C standard. In addition, some of the functions described here do not exist in the standard.

Note that some architectures may even provide optimised versions of some of these generic in-kernel C library functions. In such cases, the optimised versions are used by default. Also note that the API of these in-kernel C library functions is generally stable. For very legitimate reasons, a lot of the in-kernel API gets altered over time. Check out Documentation/stable_api_nonesense.txt.

This material is based on the Linux 3.11 Kernel sources. References to header files and other sources e.g. include/linux/kenrel.h, are with respect to the root of the kernel source tree. Notation such as <linux/string.h> implies include/linux/string.h.

Formatted Output

This family of C library functions produce output under the control of a format string that specifies how subsequent variable-length arguments are converted for output. The kernel implements sprintf, snprintf, scnprintf, vsprintf, vsnprintf and vscnprintf. These functions write a formatted string to an input buffer. The kernel also exports printk (its version of printf) which outputs to the console.

Technically, while printk can be considered as part of this family of library functions, it really is an entire framework on its own - unlike other library functions which are merely routines. The framework includes kernel configuration options and also exports (filesystem) interfaces that allow administrative/programmatic control of printk behaviour. Various subsystems, e.g. debugging frameworks and diagnostic interfaces, are affected by printk settings. For this reason, printk is discussed separately here.

This family of functions is defined in lib/vsprintf.c, with function prototypes declared in include/linux/kernel.h.

sprintf

Format a string and place it in a buffer

int sprintf (char *buf, const char *fmt, ...);

Function argument description

  • buf The buffer to place the result into

  • fmt The format string to use

  • ... Arguments for the format string

Return value

  • This function returns the number of characters written into buf.

Notes:

  • Use snprintf or scnprintf instead in order to avoid buffer overflows.

snprintf

Format a string and place it in a buffer

int snprintf (char *buf, size_t size, const char *fmt, ...);

Function argument description

  • buf The buffer to place the result into

  • size The size of the buffer, including the trailing null space

  • fmt The format string to use

  • ... Arguments for the format string

Return value

  • The return value is the number of characters which would be generated for the given input, excluding the trailing null, as per ISO C99. If the return is greater than or equal to size, the resulting string is truncated.

Notes

  • See the vsnprintf's "Notes" (below) for format string extensions over C99.

scnprintf

Format a string and place it in a buffer

int scnprintf (char *buf, size_t size, const char *fmt, ...);

Function argument description

  • buf The buffer to place the results into

  • size The size of the buffer, including the trailing null space

  • fmt The format string to use

  • ... Arguments for the format string

Return value

  • The return value is the number of characters written into buf not including the trailing \0.

  • If size is equal to 0, the function returns 0.

vsprintf

Format a string and place it in a buffer

int vsprintf (char *buf, const char *fmt, va_list args);

Function argument description

  • buf The buffer to place the result into

  • fmt The format string to use

  • args Arguments for the format string

Return value

  • The function returns the number of characters written into buf.

Notes

  • If not dealing with a va_list, consider using sprintf instead. Consider using vsnprintf or vscnprintf instead in order to avoid buffer overflows. See vsnprintf's "Notes" (below) for format string extensions over C99.

vsnprintf

Format a string and place it in a buffer

int vsnprintf (char *buf, size_t size, const char *fmt, va_list args);

Function argument description

  • buf, fmt and args same as vsprintf.

  • size The size of the buffer, including the trailing null space.

Return value

  • This function returns the number of characters which would be generated for the given input, excluding the \0, as per ISO C99. To have the exact number of characters written into buf as return value (not including the trailing \0), use vscnprintf instead. If the return is greater than or equal to size, the resulting string is truncated.

Notes

  • If not dealing with a va_list, consider using snprintf.

  • This function follows C99 vsnprintf, but has some extensions:

    %pS output the name of a text symbol with offset

    %ps output the name of a text symbol without offset

    %pF output the name of a function pointer with its offset

    %pf output the name of a function pointer without its offset

    %pB output the name of a backtrace symbol with its offset

    %pR output the address range in a struct resource with decoded flags

    %pr output the address range in a struct resource with raw flags

    %pM output a 6-byte MAC address with colons

    %pMR output a 6-byte MAC address with colons in reversed order

    %pMF output a 6-byte MAC address with dashes

    %pm output a 6-byte MAC address without colons

    %pmR output a 6-byte MAC address without colons in reversed order

    %pI4 print an IPv4 address without leading zeros

    %pi4 print an IPv4 address with leading zeros

    %pI6 print an IPv6 address with colons

    %pi6 print an IPv6 address without colons

    %pI6c print an IPv6 address as specified by RFC 5952

    %pIS depending on sa_family of struct sockaddr * print IPv4/IPv6 address

    %piS depending on sa_family of struct sockaddr * print IPv4/IPv6 address

    %pU[bBlL] print a UUID/GUID in big or little endian using lower or upper case.

    %ph[CDN] a variable-length hex string with a separator (supports up to 64 bytes of the input)

    %n is ignored

vscnprintf

Format a string and place it in a buffer

int vscnprintf (char *buf, size_t size, const char *fmt, va_list args);

Function argument description

  • Same as vsnprintf.

Return value

  • This function returns the number of characters which have been written into the buf excluding the trailing '\0'. If size is equal to 0, the function returns 0.

Notes

  • See vsnprintf's "Notes" (above) for format string extensions over C99

Formatted String Conversion

These functions are defined in lib/vsprintf.c. Function prototypes declared in include/linux/kernel.h.

sscanf

Unformat a buffer into a list of arguments

int sscanf (const char *buf, const char *fmt, ...);

Function argument description

  • buf Input buffer

  • fmt Formatting of buffer

  • ... Resulting arguments

vsscanf

Unformat a buffer into a list of arguments

int vsscanf (const char *buf, const char *fmt, va_list args);

Function argument description

  • buf Input buffer

  • fmt format of buffer

  • args arguments

String to Integer Conversion

There are two sets of implementations:

Function prototypes declared in include/linux/kernel.h

kstrtol

Convert a string to a signed long

int kstrtol(const char *s, unsigned int base, long *res);

Function argument description

  • s The start of the null-terminated string. The string may also include a single newline before its terminating null. The first character may be a plus sign (+) but not a minus (-).

  • base The number base to use. The maximum supported is 16. If the base is given as 0, then conventional semantics will be used to detect the base of the string: Hexadecimal if it begins with 0x, Octal if it begins with 0, decimal otherwise.

  • res Where to write the result of the conversion on success.

Return Value

  • Return 0 on success, -ERANGE on overflow and -EINVAL on parsing error.

Notes:

  • This function is A.K.A strict_strtol and is defined in include/linux/kernel.h.

kstrtoll

Convert a string to a long long

int kstrtoll(const char *s, unsigned int base, long long *res);

Function argument description

  • Same as kstrtol

Return Value

  • Same as kstrtol

Notes:

  • This function is A.K.A strict_strtoll and is defined in lib/kstrtox.c

kstrtoul

Convert a string to an unsigned long.

int kstrtoul(const char *s, unsigned int base, unsigned long *res);

Function argument description

  • Same as kstrtol

Return value

  • Same as kstrtol

Notes:

  • This function is A.K.A strict_kstrtoul and is defined in include/linux/kernel.h

kstrtoull

Convert a string to an unsigned long long

int kstrtoull(const char *s, unsigned int base, unsigned long long *res);

Function argument description

  • Same as kstrtol

Return value

  • Same as kstrtol

Notes:

  • This function is A.K.A strict_strtoull and is defined in lib/kstrtox.c

Obsolete Set

These functions are defined in lib/vsprintf.c. Function prototypes declared in include/linux/kernel.h.

simple_strtol

Convert a string to a signed long

long simple_strtol (const char *cp, char **endp, unsigned int base);

Function argument description

  • cp The start of the string

  • endp A pointer to the end of the parsed string will be placed here

  • base The number base to use

simple_strtoll

Convert a string to a signed long long

long long simple_strtoll (const char *cp, char **endp, unsigned int base);

Function argument description

  • Same as simple_strtol

simple_strtoul

Convert a sting to an unsigned long

unsigned long long simple_strtoul (const char *cp, char **endp, unsigned int base);

Function argument description

  • Same as simple_strtol

simple_strtoull

Convert a string to an unsigned long long

unsigned long long simple_strtoull (const char *cp, char **endp, unsigned int base);

Function argument description

  • Same as simple_strtol

String Manipulation

The generic versions are defined in lib/string.c. The optimized versions should generally be found as inline/assembly code in arch/ARCH/include/asm/string*.h and arch/ARCH/lib/.

The function prototypes are declared in include/linux/string.h

strcpy

Copy a NULL terminated string

char *strcpy(char *dest, const char *src);

Function argument description

  • dest where to copy the string to
  • src where to copy the string from

strncpy

Copy a length-limited, NULL-terminated string

char *strncpy(char *dest, const char *src, size_t count);

Function argument description

  • dest Where to copy the string to
  • src Where to copy the string from
  • count The maximum number of bytes to copy

Notes:

  • The result is not NULL-terminated if the source exceeds count bytes. For this, use strncat instead.
  • In the case where the length of src is less than that of count, the remainder of dest will be padded with NULL.

strlcpy

Copy a NULL-terminated string into a sized buffer

size_t strlcpy(char *dest, const char *src, size_t size);

Function argument description

  • dest Where to copy the string
  • src Where to copy the string from
  • size Size of destination buffer

Notes:

  • This function is compatible with BSD: The result is always a valid NULL-terminated string that fits in the buffer (unless, of course, the buffer size is zero). It does not pad out the result like strncpy does.

strcat

Append one NULL-terminated string to another

char *strcat(char *dest, const char *src);

Function argument description

  • dest Append one NULL-terminated string to another
  • src The string to append to it

strncat

Append a length-limited, NULL-terminated string to another

char *strncat(char *dest, const char *src, size_t count);

Function argument description

  • dest The string to be appended
  • src The string to append to it
  • count The maximum number of bytes to copy

Notes:

  • In contrast to strncpy, this function ensures that the result is terminated.

strlcat

Append a length-limited, NULL-terminated string to another

size_t strlcat(char *dest, const char *src, size_t count);

Function argument description

  • dest The string to be appended to
  • src The string to append to it
  • count The size of the destination buffer

strcmp

Case sensitive comparison of two strings

int strcmp(const char *cs, const char *ct);

Function argument description

  • cs One string
  • ct Another string

Return value

  • This function returns -1, 0 or 1 if cs is found, respectively, to be less than, to match, or be greater than ct.

Notes

  • If performing comparisons with sysfs input strings, use sysfs_streq instead.

strncmp

Case sensitive, length-limited string comparison

int strncmp(const char *cs, const char *ct, size_t count);

Function argument description

  • cs One string
  • ct Another string
  • count The maximum number of bytes to compare

Return value

  • Same as strcmp.

Notes

  • This function only compares the first count characters of cs.

strnicmp

Case insensitive, length-limited string comparison

int strnicmp(const char *s1, const char *s2, size_t len);

Function argument description

  • s1 One string

  • s2 The other string

  • len The maximum number of characters to compare

Return value

  • This function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

Notes

  • This function only compares the first len bytes of s1.

strcasecmp

Case insensitive comparison of two strings

int strcasecmp(const char *s1, const char *s2);

Function argument description

  • s1 One string

  • s2 The other string

Return value

  • This function returns an integer less than, equal to, or greater than zero if cs is found, respectively, to be less than, to match, or be greater than ct

strncasecmp

Case insesitive, length-limited string comparison

int strncasecmp (const char *s1, const char *s2, size_t n);

Function argument description

  • s1 One string

  • s2 The other string

  • n The maximum number of characters to compare

Return value

  • Same as strcasecmp

Notes

  • This function only compares the first n bytes of s1

strchr

Find the first occurence of a character in a string

char *strchr(const char *s, int c);

Function argument description

  • s The string to be searched
  • c The character to search for

Return value

  • This function returns a pointer to the matched character or NULL if the character is not found.

strnchr

Find a character in a length limited string

char *strnchr(const char *s, size_t count, int c);

Function argument description

  • s The string to be searched
  • count The number of characters to be searched
  • c The character to search for

    char strnchr(const char s, size_t count, int c);

Return value

  • This function returns a pointer to the matched character; NULL if the character is not found.

strrchr

Find the last occurence of a character in a string

char *strrchr(const char *s, int c);

Function argument description

  • s The string to be searched
  • c The character to be searched for

Return value

  • This function returns a pointer to the matched character or NULL if the character is not found.

strstr

Find the first substring in a NULL-terminated string

char *strstr(const char *s1, const char *s2);

Function argument description

  • s1 The string to be searched for

  • s2 The string to search for

Return value

  • This function returns a pointer to the beginning of the substring, or NULL if the substring is not found.

Notes

  • The terminating null bytes (\0) are not compared.

strnstr

Find the first substring in a length-limited string

char *strnstr(const char *s1, const char *s2, size_t len);

Function argument description

  • s1 The string to be searched

  • s2 The string to search for

  • len The maximum number of characters to search

Return value

  • Same as strstr

Notes

  • Only the first len bytes of s1 are searched.

strlen

Find the length of a string

size_t strlen(const char *s);

Function argument description

  • s The string to be sized

Return value

  • This function returns the number of characters in in s.

Notes:

  • This function calculates the length of the string s, not including the terminating \0 character.

strnlen

Find the length of a length-limited string

size_t strnlen(const char *s, size_t count);

Function argument description

  • s The string to be sized
  • count The maximum number of bytes to search

Return value

  • This function returns strlen(s) if the number of characters in s is less than count; Otherwise, it returns a maximum value of count.

strim

Removes leading and trailing whitespace from s

char *strim(char *s);

Function argument description

  • s The string to be stripped.

Return value

  • This function returns a pointer to the first non-whitespace character in s

Notes:

  • The first trailing whitespace is replaced with a NULL-terminator in the given string s.

strspn

Calculate the length of the initial substring of s which only contain letters in accept

size_t strspn(const char *s, const char *accept);

Function argument description

  • s The string to be searched

  • accept The string to search for

Return value

  • This function returns the number of characters in the initial substring of s which consist only of characters from accept.

strcspn

Calculate the length of the initial substring of s which does not contain letters in reject

size_t strcspn (const char *s, const char *reject);

Function argument description

  • s The string to be searched

  • reject The string to avoid

Return value

  • This function returns the number of characters in the initial substring of s which are not in the string reject.

strpbrk

Find the first occurrence of a set of characters

char *strpbrk(const char *cs, const char *ct);

Function argument description

  • cs The string to be searched

  • ct The characters to search for

Return value

  • This function returns a pointer to the character in cs that matches one of the characters in ct, or NULL if no such character is found.

strsep

Split a string into tokens

char *strsep(char **s, const char *ct);

Function argument description

  • s The string to be searched

  • ct A delimiter that separates tokens

Return value

  • This function returns a token (a pointer to a null-terminated string in *s delimited by ct). The delimiter is not included in the token.

Notes

  • This function is inovked iteratively to extract individual tokens in *s. On each invocation, strsep updates *s to point after the token, ready for the next call. Eventually, *s is made NULL when no more tokens are left. In the case no delimeter is found, strsep returns the entire string *s as the token, and *s is updated to NULL. On the invocation when *s is NULL, this function simply returns NULL.

  • This function replaces strtok.

strtobool

Convert common user inputs into boolean values

int strtobool(const char *s, boot *res);

Function argument description

  • s Input string

  • res Result

Return value

  • This function returns zero if, and only if s[0] is Y, y, 1, N, n or 0. Otherwise, it returns -EINVAL.

Notes

  • The value pointed to by res is updated upon finding a match. In other words, res will be equal to true if, and only if s[0] is Y,y or 1 and set to false if, and only if s[0] is N, n, or 0.

skip_spaces

Removes leading whitespace from str

char *skip_spaces(const char *str);

Function argument description

  • str The string to be stripped.

Return value

  • Returns a pointer to the first non-whitespace character in str

sysfs_streq

Case-sensitive comparison of two strings.

bool sysfs_streq(const char *s1, const char *s2);

Function argument description

  • s1 One string

  • s2 Another string

Return value

  • This returns true if, and only if two strings are equal; false otherwise.

Notes

  • This function treats both NULL and newline-then-NULL as equivalent string terminations. sysfs_streq meant for use with sysfs input strings, which generally terminate with newlines but are compared against values without newlines. Otherwise, for general string comparison, use the strcmp family of functions instead.

General Object Manipulation

These functions are defined in lib/string.c. Function prototypes in <linux/string.h>.

memcpy

Copy one area of memory to another

void *memcpy(void *dest, const void *src, size_t count);

Function argument description

  • dest Where to copy to

  • src Where to copy from

  • count The size of the area

Return value

  • This function returns a pointer to dest.

Notes

  • This function should not be used to access IO space. Use memcpy_toio( ) or memcpy_fromio( ) instead. The generic versions of these functions/macros are defined in <asm-generic/io.h> and arch-specific versions generally in arch/ARCH/include/asm/io.h.

  • Unlike memmove, this function does not perform copies with overlapping areas.

memmove

Copy one area of memory to another

void *memmove(void *dest, const void *src, size_t count);

Function argument description

  • dest Where to copy to

  • src Where to copy from

  • count The size of the area

Return value

  • This function returns a pointer to dest.

Notes

  • This function performs copies with overlapping areas.

memset

Fll a region of memory with the given value

void *memset(void *s, int c, size_t count);

Function argument description

  • s Pointer to the start of the area

  • c The byte to fill the area

  • count The size of the area

Return value

  • This function returns a pointer to s.

  • When accessing IO space, use memset_io instead. The generic version of memset_io is defined in <asm-generic/io.h> and the arch-specific version generally in arch/ARCH/include/asm/io.h.

memcmp

Compare two areas of memory

int memcmp(const void *cs, const void *ct, size_t count);

Function argument description

  • cs One area of memory

  • ctAnother area of memory

  • count The size of the area

Return value

  • If the two areas contain identical byte values, this function returns 0. Otherwise, this function returns a non-zero integer value.

memscan

Find a character in an area of memory

void *memscan(void *addr, int c, size_t size);

Function argument description

  • addr The memory area

  • c The byte to search for

  • size The size of the area

Return value

  • This function returns the address of the first occurence of c, or 1 byte past the area if c is not found.

memchr

Find a character in an area of memory

void *memchr(const void *s, int c, size_t n);

Function argument description

  • s The memory area

  • c The byte to search for

  • n The size of the area

Return value

  • This function returns the first occurence of c, or NULL if c is not found.

memchr_inv

Find an unmatching character in an area of memory

void *memchr_inv(const void *start, int c, size_t bytes);

Function argument description

  • start The memory area

  • c Find a character other than c

  • bytes The size of the area

Return value

  • This function returns the address of the first character other than c, or NULL if the whole buffer contains just c.

Character Class Tests

The following macros are defined in include/linux/ctype.h:

isalnum(c)
isalpha(c)
iscntrl(c)
isdigit(c)
isgraph(c)
islower(c)
isprint(c)
ispunct(c)
isspace(c)
isupper(c)
isxdigit(c)
isascii(c)
toascii(c)
tolower(c)
toupper(c)

Note that the behaviour of some of these utilities may differ slightly from that defined by the ISO/ANSI C standard.

Resources