ddi_strtoul(9f)

1ddi_strtoul(9F)          Kernel Functions for Drivers          ddi_strtoul(9F)
2
3
4

NAME

6       ddi_strtoul - String conversion functions
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12       int ddi_strtoul(const char *str, char **endptr, int base,
13            unsigned long *result);
14
15

INTERFACE LEVEL

17       Solaris DDI specific (Solaris DDI)
18

PARAMETERS

20       str        Pointer to a character string to be converted.
21
22
23       endptr     Post-conversion final string of unrecognized characters.
24
25
26       base       Radix used for conversion.
27
28
29       result     Pointer to variable which contains the converted value.
30
31

DESCRIPTION

33       The  ddi_strtoul()  function converts the initial portion of the string
34       pointed to by str to a type unsigned long int representation and stores
35       the converted value in result.
36
37
38       The  function first decomposes the input string into three parts:
39
40           1.     An  initial (possibly empty) sequence of white-space charac‐
41                  ters (' ', '\t', '\n', '\r', '\f')
42
43           2.     A subject sequence interpreted as an integer represented  in
44                  some radix determined by the value of base
45
46           3.     A  final   string  of  one  or more unrecognized characters,
47                  including the terminating null byte of the input string.
48
49
50       The  ddi_strtoul()  function  then  attempts  to  convert  the  subject
51       sequence to an unsigned integer and returns the result.
52
53
54       If  the  value of base is 0, the expected form of the  subject sequence
55       is that of a decimal constant, octal constant or hexadecimal  constant,
56       any  of  which  may  be preceded by a plus ("+") or minus ("-") sign. A
57       decimal constant begins with  a  non-zero  digit,  and  consists  of  a
58       sequence  of decimal digits. An octal constant consists  of  the prefix
59       0 optionally followed by a sequence of the digits 0 to 7 only. A  hexa‐
60       decimal   constant  consists  of  the  prefix  0x  or  0X followed by a
61       sequence of the decimal digits and letters a (or A) to f  (or  F)  with
62       values 10 to 15 respectively.
63
64
65       If  the  value  of  base is between 2 and 36, the expected form of  the
66       subject sequence is a sequence of letters and  digits  representing  an
67       integer with the radix specified by base, optionally preceded by a plus
68       or minus sign. The letters from a (or A) to  z  (or  Z)  inclusive  are
69       ascribed the values 10 to 35 and only letters whose ascribed values are
70       less than that of base are permitted. If the value of base is  16,  the
71       characters  0x or 0X may optionally precede the sequence of letters and
72       digits, following the sign if present.
73
74
75       The subject sequence is defined  as the longest initial subsequence  of
76       the  input  string,  starting  with the first non-white-space character
77       that is of the expected form. The subject sequence contains no  charac‐
78       ters  if  the input string is empty or consists entirely of white-space
79       characters, or if the first non-white-space character is other  than  a
80       sign or a permissible letter or digit.
81
82
83       If the subject sequence has the expected form and the  value of base is
84       0, the sequence of characters starting with the first digit  is  inter‐
85       preted as an integer constant. If the subject sequence has the expected
86       form and the value of base is between 2 and 36, it is used as the  base
87       for  conversion, ascribing  to each letter its value as given above. If
88       the subject sequence begins with a minus sign, the value resulting from
89       the  conversion  is negated. A pointer to the final string is stored in
90       the object pointed to by endptr, provided that endptr  is  not  a  null
91       pointer.
92
93
94       If  the  subject sequence is empty or does not have the expected  form,
95       no conversion is performed and the value of str is stored in the object
96       pointed to by endptr, provided that endptr is not a null pointer.
97

RETURN VALUES

99       Upon successful completion, ddi_strtoul() returns 0 and stores the con‐
100       verted value in result. If no conversion is performed  due  to  invalid
101       base,  ddi_strtoul()  returns EINVAL and the variable pointed by result
102       is not changed.
103
104
105       If the correct value is outside the  range   of  representable  values,
106       ddi_strtoul()  returns ERANGE and the value pointed to by result is not
107       changed.
108

CONTEXT

110       The ddi_strtoul() function may be called from user, kernel or interrupt
111       context.
112