Cross-Platform DDI Interface for Converting Strings to 64-bit Integers [PSARC/2008/740 FastTrack timeout 12/09/2008]
Jordan Vaughan
Jordan.Vaughan at Sun.COM
Mon Dec 1 16:34:22 PST 2008
On 12/01/08 15:55, Garrett D'Amore wrote:
> 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
Good point. I wouldn't mind amending the case to consolidate both
ddi_strtoll() and ddi_strtoull() manpages into a single manpage.
Jordan
>
> 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
>>
>>
>
More information about the opensolaris-arc
mailing list