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