device_names(3K) DG/UX R4.11MU05 device_names(3K)
NAME
devicenames: dnparsedevicename - parse device names
SYNOPSIS
#include "/usr/src/uts/aviion/ii/idn.h"
statustype dnparsedevicename (
charptrtype name, /*READONLY*/
charptrtype format, /*READONLY*/
charptrtype defaultparams, /*READONLY*/
...
)
DESCRIPTION
This routine is used by device drivers to parse device name strings
non-destructively according to the rules below.
The format string is a scanf(3S)-like format string that name must
match for this routine to return successfully. Two types of format
specifiers are available for format: "%x" (for hexadecimal numbers)
and "%s" (for strings). See the discussion below for details about
the differences between this routine's interpretation of format spec
ifiers and scanf(3S)'s interpretation of them.
The defaultparams string indicates how any missing parameter fields
in name get expanded during the attempt to match format. This string
is a comma-separated list of zero or more default values. Note that
it is quite permissible to have a "%s" field's default value be the
empty string (that is, no default). However, string default values
can only be simple strings, not nested device names in their own
right. We don't want to encourage using anything but the empty string
as a default for parent bus device names.
The variadic parameters provide the pointer arguments into which the
corresponding values parsed from name will be saved. The variadic
parameter corresponding to a "%x" conversion specification must be of
type uint32ptrtype (pointing to the uint32type location where the
parsed number will be stored). The variadic parameter corresponding
to a "%s" conversion specification must be of type charptrtype
(pointing to the character buffer where the parsed string will be
stored). For "%s" conversions, there is yet another variadic parame
ter immediately following the character buffer pointer: a
uint32type argument known as the "field width" - the maximum number
of characters in name that can be safely stored into the character
buffer. It is up to the caller to guarantee that the buffer argu
ments for "%s" directives contain at least 1 + fieldwidth bytes of
storage (the extra byte is required for the terminating null charac
ter).
The format string follows normal scanf(3S) scanning rules, with the
following exceptions and special features:
· An attempt to match a string to a "%x" specifier continues until
a punctuation character ('(', ')' or ',') is encountered in the
name.
· An attempt to match a string to a "%s" specifier continues until
either an entire nested device name (including all its punctua
tion, even the terminating ")") has been consumed, or failing
that, until another punctuation character (')' or ',') is encoun
tered in the name. Note that it is up to the caller to ensure
that the character buffer into which the parent bus name "%s" pa
rameter is parsed is large enough to hold any parent bus device
name. This can be guaranteed by making that buffer as large as
the maximum permissible device name length.
· If any parenthesized list in name contains fewer commas than dic
tated by format, then any missing commas are considered to be
present just before the list's closing parenthesis when parsing
is attempted.
· If a parameter is still missing even after all defaults have been
applied, it gets the appropriate type of null value: 0 for "%x",
and "" for "%s". Parameters that have dynamically determined de
fault values (e.g., an Ethernet address whose default value is
determined by reading a controller register) should use a "%s"
specifier with a null string default, so that the driver-specific
name-parsing routine can then plug in the real default after
calling this function.
· The pointer argument for a "%x" directive must point to a
uint32type variable. Since there are only 32 bits of storage in
such variables, the field-width for "%x" fields should never be
more than 8 characters. If a parameter in name contains a run of
more than 8 digits, that parameter should be parsed as a "%s"
string.
DIAGNOSTICS
The following return statuses are possible:
DNENXIONAMETOOLONG: name's length (including the terminating
null character, and after expanding out defaults) exceeded
DNDEVICENAMELENGTHMAX.
DNENXIONAMEMALFORMED: name was missing some generic component
(mnemonic, enclosing parentheses), or its parentheses did not bal
ance.
DNENXIOFORMATINVALID: format was malformed or contained an un
known "%" directive.
DNENXIONUMERICPARAMINVALID: name contained a numeric parameter
that included some non-digit characters.
DNENXIOPARAMTOOLONG: name contained a string parameter that was
too long for the buffer intended to receive it, or a numeric parame
ter that was longer than 8 hexadecimal digits.
DNENXIONAMEDOESNOTMATCHFORMAT: name contained some extra pa
rameters not present in format, or did not use the same device
mnemonic as format.
OK: name had the same mnemonic as format and was successfully parsed
according to format's fields, so that the variadic parameters were
all set to the proper values.
EXAMPLES
The following example parses a name for the sd (SCSI Disk) device
driver. The first parameter in such a name is a nested device name
representing the name of the disk's parent SCSI bus; it has no de
fault. The second and third parameters are numeric and both default
to 0; they represent the SCSI ID and SCSI LUN, respectively, of the
disk unit in question.
char nameformat = "sd(%s,%x,%x)";
char namedefaults = ",0,0";
charptrtype devicename;
char parentbusname [DNDEVICENAMELENGTHMAX];
uint32type scsiid;
uint32type scsilun;
status = dnparsedevicename (devicename, nameformat, namedefaults,
parentbusname, sizeof(parentbusname) - 1;
&scsiid, &scsilun);
SEE ALSO
deviceconfiguration(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)