+1
On a minor nit/suggestion, wouldn't it be simpler to just add the
functions to the existing ddi_strtol page. (I noticed ddi_strtoul is a
separate page as well. It seems kind of wasteful though, since mainly
these functions only differ in a relatively small detail.)
-- Garrett
Gerald Jelinek wrote:
> 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
>
>
