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