I am sponsoring this case for Jordan Vaughan.
Thanks,
Jerry
Template Version: @(#)sac_nextcase %I% %G% SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Cross-Platform DDI Interface for Converting Strings to 64-bit Integers
1.2. Name of Document Author/Supplier:
Author: Jordan Vaughan
1.3 Date of This Document:
01 December, 2008
4. Technical Description
Template Version: @(#)sac_nextcase %I% %G% SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Cross-Platform DDI Interface for Converting Strings to 64-bit Integers
1.2. Name of Document Author/Supplier:
Author: Jordan Vaughan
1.3 Date of This Document:
20 November, 2008
4. Technical Description
Targeting an update release of Solaris 10, therefore patch binding.
PROBLEM:
Device driver writers have no standard means of converting numerical strings to
64-bit integers in both 32- and 64-bit builds. Driver writers could use
ddi_strtol(9F) and ddi_strtoul(9F), but both produce 32-bit integers in 32-bit
driver builds. Therefore, driver writers must resort to writing their own
string conversion subroutines or linking to project- or consolidation-private
string conversion functions, such as the undocumented function idm_strtoull().
However, these solutions are cumbersome, increase the probability of generating
bugs, and create dependencies on uncommitted, undocumented kernel functions.
This case proposes to rectify this deficiency by adding two new, committed
functions to the Solaris 10 and Solaris Nevada (and thus OpenSolaris) DDI called
ddi_strtoll() and ddi_strtoull() that will convert null-terminated character
strings into signed and unsigned 64-bit integers (respectively) in both 32- and
64-bit builds.
EXPORTED INTERFACES:
FUNCTIONS:
NAME STABILITY NOTES
ddi_strtoll Committed In <sys/sunddi.h> under _KERNEL
ddi_strtoull Committed In <sys/sunddi.h> under _KERNEL
TECHNICAL DESCRIPTION:
The Solaris DDI currently provides two string-to-long-integer functions that
both kernel and driver coders can utilize: ddi_strtol(9F) and ddi_strtoul(9F).
Both functions convert strings to 32-bit integers in 32-bit builds and 64-bit
integers in 64-bit builds.
It would be preferable to provide additional functions that would convert
strings to 64-bit integers in both 32- and 64-bit builds. These functions,
ddi_strtoll() and ddi_strtoull(), would be functionally equivalent to
ddi_strtol() and ddi_strtoul() with the exception that the generated values
would be of types 'longlong_t' and 'u_longlong_t' (respectively) instead of
'long int' and 'unsigned long int'.
Given that kernel functions cannot safely utilize errno, both ddi_strtoll()
and ddi_strtoull() will differ from their userland equivalents (strtoll(3C) and
strtoull(3C)) in that the former will store their results in pointer arguments
and return error codes (whereas the latter return their results and store
error codes in errno). This behavior is identical to that of ddi_strtol()
and ddi_strtoul().
RELATED BUGIDS:
6761505 RFE: having ddi_strtoull() would be nice
RELATED ARC CASES:
PSARC/2004/321: Add strtol() and strtoul() to the DDI
REFERENCE DOCUMENTS:
ddi_strtol(9F) and ddi_strtoul(9F) man pages
Solaris Books: Writing Device Drivers (Solaris 10)
(http://docs.sun.com/app/docs/doc/816-4854)
NEW MAN PAGES:
Kernel Functions for Drivers ddi_strtoll(9F)
NAME
ddi_strtoll - String conversion functions
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_strtoll(const char *str, char **endptr, int base,
longlong_t *result);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
PARAMETERS
str Pointer to a character string to be converted.
endptr Post-conversion final string of unrecognized
characters.
base Radix used for conversion.
result Pointer to variable which contains the converted
value.
DESCRIPTION
The ddi_strtoll() function converts the initial portion of
the string pointed to by str to a type longlong_t
representation and stores the converted value in result.
The function first decomposes the input string into three
parts:
1. An initial (possibly empty) sequence of white-space
characters (' ', '\t', '\n', '\r', '\f')
2. A subject sequence interpreted as an integer
represented in some radix determined by the value
of base
3. A final string of one or more unrecognized charac-
ters, including the terminating null byte of the
input string.
The ddi_strtoll() function then attempts to convert the sub-
ject sequence to an integer and returns the result.
SunOS 5.11 Last change: 20 Nov 2008 1
Kernel Functions for Drivers ddi_strtoll(9F)
If the value of base is 0, the expected form of the subject
sequence is that of a decimal constant, octal constant or
hexadecimal constant, any of which may be preceded by a plus
("+") or minus ("-") sign. A decimal constant begins with a
non-zero digit, and consists of a sequence of decimal
digits. An octal constant consists of the prefix 0 option-
ally followed by a sequence of the digits 0 to 7 only. A
hexadecimal constant consists of the prefix 0x or 0X fol-
lowed by a sequence of the decimal digits and letters a (or
A) to f (or F) with values 10 to 15 respectively.
If the value of base is between 2 and 36, the expected form
of the subject sequence is a sequence of letters and digits
representing an integer with the radix specified by base,
optionally preceded by a plus or minus sign. The letters
from a (or A) to z (or Z) inclusive are ascribed the values
10 to 35 and only letters whose ascribed values are less
than that of base are permitted. If the value of base is 16,
the characters 0x or 0X may optionally precede the sequence
of letters and digits, following the sign if present.
The subject sequence is defined as the longest initial
subsequence of the input string, starting with the first
non-white-space character that is of the expected form. The
subject sequence contains no characters if the input string
is empty or consists entirely of white-space characters, or
if the first non-white-space character is other than a sign
or a permissible letter or digit.
If the subject sequence has the expected form and the value
of base is 0, the sequence of characters starting with the
first digit is interpreted as an integer constant. If the
subject sequence has the expected form and the value of base
is between 2 and 36, it is used as the base for conversion,
ascribing to each letter its value as given above. If the
subject sequence begins with a minus sign, the value result-
ing from the conversion is negated. A pointer to the final
string is stored in the object pointed to by endptr, pro-
vided that endptr is not a null pointer.
If the subject sequence is empty or does not have the
expected form, no conversion is performed and the value of
str is stored in the object pointed to by endptr, provided
that endptr is not a null pointer.
RETURN VALUES
Upon successful completion, ddi_strtoll() returns 0 and
stores the converted value in result. If no conversion is
SunOS 5.11 Last change: 20 Nov 2008 2
Kernel Functions for Drivers ddi_strtoll(9F)
performed due to invalid base, ddi_strtoll() returns EINVAL
and the variable pointed by result is not changed.
If the correct value is outside the range of representable
values, ddi_strtoll() returns ERANGE and the value pointed
to by result is not changed.
CONTEXT
The ddi_strtoll() function may be called from user, kernel
or interrupt context.
SEE ALSO
Writing Device Drivers
SunOS 5.11 Last change: 20 Nov 2008 3
Kernel Functions for Drivers ddi_strtoull(9F)
NAME
ddi_strtoull - String conversion functions
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_strtoull(const char *str, char **endptr, int base,
u_longlong_t *result);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
PARAMETERS
str Pointer to a character string to be converted.
endptr Post-conversion final string of unrecognized
characters.
base Radix used for conversion.
result Pointer to variable which contains the converted
value.
DESCRIPTION
The ddi_strtoull() function converts the initial portion of
the string pointed to by str to a type u_longlong_t
representation and stores the converted value in result.
The function first decomposes the input string into three
parts:
1. An initial (possibly empty) sequence of white-space
characters (' ', '\t', '\n', '\r', '\f')
2. A subject sequence interpreted as an integer
represented in some radix determined by the value
of base
3. A final string of one or more unrecognized charac-
ters, including the terminating null byte of the
input string.
The ddi_strtoull() function then attempts to convert the
subject sequence to an unsigned integer and returns the
result.
SunOS 5.11 Last change: 20 Nov 2008 1
Kernel Functions for Drivers ddi_strtoull(9F)
If the value of base is 0, the expected form of the subject
sequence is that of a decimal constant, octal constant or
hexadecimal constant, any of which may be preceded by a plus
("+") or minus ("-") sign. A decimal constant begins with a
non-zero digit, and consists of a sequence of decimal
digits. An octal constant consists of the prefix 0 option-
ally followed by a sequence of the digits 0 to 7 only. A
hexadecimal constant consists of the prefix 0x or 0X fol-
lowed by a sequence of the decimal digits and letters a (or
A) to f (or F) with values 10 to 15 respectively.
If the value of base is between 2 and 36, the expected form
of the subject sequence is a sequence of letters and digits
representing an integer with the radix specified by base,
optionally preceded by a plus or minus sign. The letters
from a (or A) to z (or Z) inclusive are ascribed the values
10 to 35 and only letters whose ascribed values are less
than that of base are permitted. If the value of base is 16,
the characters 0x or 0X may optionally precede the sequence
of letters and digits, following the sign if present.
The subject sequence is defined as the longest initial
subsequence of the input string, starting with the first
non-white-space character that is of the expected form. The
subject sequence contains no characters if the input string
is empty or consists entirely of white-space characters, or
if the first non-white-space character is other than a sign
or a permissible letter or digit.
If the subject sequence has the expected form and the value
of base is 0, the sequence of characters starting with the
first digit is interpreted as an integer constant. If the
subject sequence has the expected form and the value of base
is between 2 and 36, it is used as the base for conversion,
ascribing to each letter its value as given above. If the
subject sequence begins with a minus sign, the value result-
ing from the conversion is negated. A pointer to the final
string is stored in the object pointed to by endptr, pro-
vided that endptr is not a null pointer.
If the subject sequence is empty or does not have the
expected form, no conversion is performed and the value of
str is stored in the object pointed to by endptr, provided
that endptr is not a null pointer.
RETURN VALUES
Upon successful completion, ddi_strtoull() returns 0 and
stores the converted value in result. If no conversion is
SunOS 5.11 Last change: 20 Nov 2008 2
Kernel Functions for Drivers ddi_strtoull(9F)
performed due to invalid base, ddi_strtoull() returns EINVAL
and the variable pointed by result is not changed.
If the correct value is outside the range of representable
values, ddi_strtoull() returns ERANGE and the value pointed
to by result is not changed.
CONTEXT
The ddi_strtoull() function may be called from user, kernel
or interrupt context.
SEE ALSO
Writing Device Drivers
SunOS 5.11 Last change: 20 Nov 2008 3
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
