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:55:56 PST 2008
On 12/01/08 16:44, Garrett D'Amore wrote:
> Jordan Vaughan wrote:
>> 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.
>
> No need to update the case materials unless you really want to. The
> suggestion was one that can be done without affecting anything
> substantive about the case itself, and can be handled without ARC
> involvement.
>
> -- Garrett
All right, if that's the case, then I'll leave the case as is. I'm
relatively new to ARC procedures, so I didn't know whether such details
had to be faithfully reflected in the case materials.
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