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
>
> 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
>>>
>>>
>>
