unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



dsfmgr(8)							    dsfmgr(8)



NAME

  dsfmgr - Manages device special files	in the /dev directory and their	asso-
  ciated databases

SYNOPSIS

  /sbin/dsfmgr [-QSxV] -a class	dir_name [entry_type [mode]]

  dsfmgr [-QSxV] -a category  s_1  s_2 s_3 dev_dir flags node_type mode	pre-
  fix

  dsfmgr [-QSxV] -r class dir_name ...

  dsfmgr [-QSxV] -r category s_1 s_2 s_3

  dsfmgr [-QSxV] -a  | -r  cfginfo any_data ...

  dsfmgr [-QSxVF] -c  |	-d  dir_name ...

  dsfmgr [-QSxVF] -D  |	-p  [dir_name/]	 node_name ...

  dsfmgr [-QSxVF] -R  {	cluster_hwid | local_hwid | hwid } {hwid_number}

  dsfmgr [-QSxVF] -e  |	-m  base_name_1	{base_name_2, instance}	 ...

  dsfmgr [-QSxVF] -n  |	-o  node_name ...

  dsfmgr [-QSxVF] -C  |	-k  | -K  | -O	| -v

  dsfmgr [-QSxV] -N

  dsfmgr [-xV] -s  | -h

  dsfmgr [-EVx]	-f    filename	| - | --

OPTIONS

  -a  Adds an entry to the database files controlled by	dsfmgr.	 This command
      can be used on three different files as follows:

      class dir_name[entry_type[mode]]
	  The class option is used to add an entry to the device special file
	  directory definition file. This option requires a directory name to
	  be specified,	such as	disk or	tape. You can optionally specify the
	  full path of the directory, such as /dev/sound.  If only the direc-
	  tory name is specified, the full path	is the specified directory
	  preceded by dev. The entry_type can be l (the	default) or c for
	  local	or cluster. The	mode specifies protection for the directory
	  as a 3 digit octal value.  The default protection is 755.

      category
	  The category option is used to add an	entry to the device special
	  file definition file.	 The following information is required:

	    +  Three search strings for	s_1 to s_3 that	enable a unique	dev-
	       ice to be selected.

	    +  A target	device directory, such as /dev/tape.

	    +  The instance width.  A value of 1 to 15 specifies the minimum
	       number of digits	for the	instance width number.	A value	of 0
	       (zero) means that there is no number.

      cfginfo
	  [Internal Use	Only.] The cfginfo option is used to add an entry to
	  the hardware configuration information file.

  -r  Removes an existing entry	from one of the	database files controlled by
      dsfmgr. This command can be used on three	different files:

      class
	  When the class option	is specified, the entry	is removed from	the
	  device special file directory	definition file. This requires a
	  class	name to	be specified, such as disk or scanner.

      category
	  When the category option is specified, the entry is removed from
	  the device special file definition file.  Three search strings for
	  s_n must be specified.

      cfginfo
	  [Internal Use	Only.] When the	cfginfo	option is specified the	entry
	  is removed from the hardware configuration information file.

  -c  Creates a	device directory such as /sound	named by the class entry in
      the device class directory database file.

  -d  Deletes the specified device directory that is named by a	corresponding
      class entry in the device	class directory	database file.

  -D  Deletes the device special file for the named node. Optionally, specify
      a	directory name,	such as	/dev/tape. The node_name can be	either
      specific,	such as	dsk21b,	or have	a wildcard suffix such as dsk21*.  If
      the wildcard character is	to be interpreted by the command shell,	it
      must be protected.

  -R  Removes the kernel record	of the device special file status entries for
      the specified device. Use	the hwmgr command to determine the hardware
      identifier (HWID)	of the target device (or devices). See hwmgr(8). You
      must supply one of the following parameters and the hardware identifier
      (an integer).

      cluster_hwid
	      The cluster-wide hardware	identifier (HWID), to operate on
	      cluster-wide devices.

      local _hwid
	      The the local hardware identifier	(HWID),	specified a device on
	      the local	system

      hwid    A	hardware identifier, which removes the specified device	from
	      all locations.

      See EXAMPLES .

  -E  Echoes commands.	This option is useful if the input is redirected to a
      file on stdin, as	described in the -f option.

  -f  Specifies	a source from which dsfmgr commands can	be read:

      file_name
	  The specified	file containing	dsfmgr commands

      -	(single	dash)
	  Standard input

      -- (double dash)
	  The controlling terminal

      Using the	-E option echoes commands as they are read.

  -n  Creates a	new device special file	for the	named node. The	node_name can
      be either	specific, such as dsk21b, or have a wildcard suffix such as
      dsk21*.

  -o  Creates one device special file in the previous (legacy) format, such
      as rz*, for the existing named device.  The node_name should be the
      device special file name in the correct format such as fd0a. This
      option is	not available in a clustered environment.

      This option is the only available	method of creating individual tape
      device special files, in the format -o tzn. You cannot use the -O	to
      create all tape device special files, but	you can	use the	-O option to
      create all rz* format device special files.

  -p  Deletes device special files named with the previous (legacy) rz*, or
      tz* format for the existing named	device(s). Optionally, specify a
      directory	name, such as /dev. The	node_name can be either	specific,
      such as rz13b or it can have a wildcard in place of the partition
      letter, such as rz13*. If	the wildcard character is to be	interpreted
      by the shell, it must be preceded	by the escape character.

  -e  Exchanges	the device special files for the named nodes. Use this option
      to reassign device special files between nodes by	exchanging or "swap-
      ping" them. The base_name	is the device name and instance, such as
      dsk0. Devices must be of the same	type and the first named device	must
      be an active (known) device.

  -m  Moves the	device special file for	one named node to another. Use this
      option to	reassign device	special	files, such as assigning the device
      special files from a failed disk device to its replacement. Devices
      must be of the same type.

  -v  Verifies the following:

	+  The device class directory default database

	+  The device category to class	directory default database

	+  The /dev directory structure

	+  The /dev nodes

  -N  Sets new base names into the kernel. If you also specify the -x option,
      old nodenames are	set in the dfsl	database:
	   #  dsfmgr -Nx
	   dsfmgr: NOTE: updating kernel basenames and old devnames for	system at /

  -C  Creates all device directories such as /dev/disk or /dev/tape, as
      specified	in the device special file directory definition	file, includ-
      ing symbolic links.  This	command	displays a list	of all directories
      created, or a full pathname if verbose mode is specified.

  -k  Creates all device special files for newly-added devices.	 When a
      device is	added to the system, this command is used to initially create
      the default device special files for that	device.

  -K  Creates all device special files.	This command is	used to	create all
      device special files for all devices detected.  This option runs
      automatically at system start up,	creating all the device	special	files
      known by the system.

  -O  Creates all device special files in the previous (legacy)	format,	such
      as rz*.  This option is not available in a clustered environment.

      To create	tape devices, use the -o tzn option.

  -s  Displays the following data from the database:

	+  The contents	of the Device Class Directory Default Database file,
	   /etc/dcdd.dat, showing scope	(local or cluster), mode (protection,
	   in octal), and class	name.

	+  The contents	of the Category	to Class-Directory, Prefix Database
	   file, /etc/dccd.dat,	showing:

	     --	# - The	entry number

	     --	String 1 - The device category,	such as	disk or	tape

	     --	String 2 - The names of	the devices found in each category,
		such as	generic	or cdrom for disks

	     --	String 3 - Whether the device is block,	character, rewind, or
		norewind

	     --	directory - The	/dev subdirectory in which the device special
		files are located

	     --	iw - The instance width	(the minimum number of digits for the
		instance)

	     --	t - The	type, which can	be block or character

	     --	mode - The current protection on the subdirectory, in octal
		(such as 755)

	     --	prefix - The device special file prefix, such as dsk, tape or
		cdrom

	+  Device Directory Tree, a listing of the class directories that
	   exist under dev.

	+  Dev Nodes, a	listing	of the individual device special files for
	   each	device.

	+  Old Device Nodes, a listing of the previous (legacy)	format of
	   individual device special files, which will show names using	the
	   rz* or tz* format.

  -h  Displays help information	on the command syntax. The -h -x options
      display a	list of	the extended information including:

	+  A description of the	supported environment variables

	+  The default setting of the supported	environment variables

	+  The current values of the supported environment variables, if any
	   have	been modified from the default value

	+  A list of useful extended commands that are currently supported,
	   such	as:


		# dsfmgr -x -d delete_locks
		# dsfmgr -x -c default_tree

	   The first command removes any dsfmgr	locks.	The second creates
	   the default directory tree for all files used by dsfmgr (normally
	   only	done by	installation routines).

  Dependent Options


  The following	options	are supported only for specific	command	options	as
  indicated in the SYNOPSIS section.

  -F  Automatically fixes any problems found in	the database on	/dev tree.
      For example, if you use the -v option and	it detects missing device
      special files for	a device node, specifying the -F option	causes the
      files to be created.

  -Q  Quits the	command	on error, implementing any changes up to the point of
      the error.  The default is to proceed and	ignore all errors that are
      not fatal.

  -S  Silent mode.  The	command	displays no information	about its operations.
      This option disables the -V option.

  -x  Extended function, format, and information. Most commands	will display
      more detailed information	when you use the -x.

  -V  Verbose mode. The	command	displays additional detailed information
      about what it did	(disables the -S option).

  Definitions


  Note the following terms used	in the context of dsfmgr:

  Scope	  Whether a device is available	only locally or	to other processors
	  on a cluster.	Can be l for local and c for cluster.

  Mode	  The protection of the	directory (See chmod(1)).

  Class	  A set	of related devices, such as disk, rdisk, tape, or ntape.

  Directory
	  The device directory where a device special file for a class in
	  located. Such	as disk, rdisk,	tape, and ntape	under the /dev direc-
	  tory.

  Instance Width or iw
	  A value of 1 to 15 specifies the minimum number of digits for	the
	  instance width number.  A value of 0 (zero) means that there is no
	  number.

  # or Instance	(number)
	  A sequential decimal number allocated	to each	device special file
	  basename.

  Prefix  The first part of a base name, such as dsk, cdrom, floppy, tape,
	  tty, lp.  The	prefix unknown is a reserved prefix used to capture
	  all nonconfigured devices, which are created in the directory
	  /dev/none.

  Basename
	  The base name	of a device consists of	the prefix and instance, such
	  as dsk21.

  Nodename
	  Identifies a subdivision of a	device such as a disk partition.  It
	  can be either	specific consisting of the base	name and suffix	such
	  as dsk21b, or	a wildcard node	name such as dsk21*.  When used	with
	  the dsfmgr command:

	  node_name1
	      Can be basename[*], such as dsk2*

	  node_name2
	      Can be [prefix]instance, such as dsk12 or	12

DESCRIPTION

  Use the dsfmgr command to manage device special files	using the file naming
  format introduced in Version 5.0.  You also use the dsfmgr command to
  create and maintain device special files according to	the previous (legacy)
  device naming	format (rz* for	disks or tz* for tapes).  On single systems,
  previous device special files	can coexist with the new device	special
  files, and are located in their traditional directory, /dev. Coexistence is
  not supported	on clustered systems.

  File Naming Convention


  The file naming convention specifies device names and	device special files
  as follows:

  Class
      A	class of devices is grouped according to a common physical feature of
      the devices, such	as disk, ntape,	or scanner.  This name is used as the
      subdirectory file	name for the group of devices, such as /dev/ntape.

  Device name
      A	device is a discrete system component, such as a disk or tape, each
      of which has a unique name. The device name consists of a	prefix,
      instance,	and suffix. A device name exists for each type of device in a
      class.  For example, under the class of disk there are devices named
      dsk, floppy, and cdrom. The prefix, instance, and	suffix are optional,
      but at least one element must exist for every device. These elements
      are defined as follows:

      Prefix  A	single prefix exists for each type of device in	a class, such
	      as dsk, floppy, and cdrom.

      Instance
	      The instance number is a decimal number assigned to a specific
	      device. For example, cdrom0 or cdrom3. The combination of	the
	      prefix and the instance make the basename	for a device.

      Suffix  The suffix is a string defined by	the device driver that is
	      appended to the basename.	The suffix varies depending on the
	      type of device as	follows:

	      disk device name suffix
		  The suffix is	an alphabetic character	in the range a to h
		  that identifies the partition	being addressed.  For exam-
		  ple, dsk12a refers to	partition a on hard disk device
		  instance 12.

	      tape device name suffix
		  The suffix is	an underscore followed by the chracter d (_d)
		  and an integer that identifies the storage density of	the
		  tape device.	For example, tape1_d0 refers to	the density
		  entry	0 (zero) on tape device	1.  The	density	suffix con-
		  forms	to the entries for the device in the DDR database
		  file,	/etc/ddr.dbase

  Basename
      Each individual device has a base	name comprised of its device name and
      a	sequential (decimal) instance number.  For example, dsk12 and cdrom3.
      These names identify the discrete	devices	to the system and to any pro-
      grams that manipulate device names.

  Device Special Files
      For each device, one or more device special files	exists in one or more
      class subdirectories. For	example, /dev/disk/dsk13c. Class directories
      exist for	disk and tape device special files as described	in the Direc-
      tory Hierarchy section.

  See System Administration for	more information on device names and device
  special files, and a definitive list of the supported	device names. Usage
  examples, such as moving devices, are	also supplied in that guide.

  Directory Hierarchy


  New device special files are located in a directory hierarchy	starting at
  /dev which is	a Context-Dependent Symbolic Link (CDSL) directory.  See Sys-
  tem Administration for information on	CDSLs.

  When the operating system is installed, device special files are created
  for the existing disk	and tape devices as follows:

  /dev/disk
      Block disk device	special	files.	Disk device special files have a dif-
      ferent prefix for	hard disks, floppy diskettes, and CD-ROM devices.

  /dev/rdisk
      Raw (character) disk device special files.

  /dev/ntape
      Nonrewind	tape device special files.

  /dev/tape
      Rewind tape device special files.

  Using	dsfmgr


  Normally, dsfmgr runs	automatically during system startup. Hardware manage-
  ment procedures poll the system for all devices, finding any devices added
  since	the system was last booted. For	the purposes of	system administra-
  tion,	you might need to run it manually to:

    +  Create device special files according to	the previous (legacy) naming
       format.	For example, if	you have scripts that use the old format, you
       can create the legacy device special files to support the scripts
       until you can modify your scripts to comply with	the revised device
       naming format.

    +  Recreate	or reassign device names, such as when a device	fails and
       must be replaced.

    +  Verify or examine the device special file data, if device files or
       databases are lost or corrupted.


  Developers and vendors of device drivers can use dsfmgr to create an
  environment for developing and testing a device driver, or for adding	new
  classes of devices to	a system. The following	additional features are
  available:

    +  Create and add a	new class of devices, or remove	an existing device
       from the	database

    +  Create or delete	the class directories under /dev

    +  Create or delete	device special files according to the revised naming
       convention, and any required class directories if they do not already
       exist

    +  Create device special files according to	the legacy (rz*, tz*) naming
       convention

    +  Display the contents of the existing database entries and device	spe-
       cial file assignments

ERRORS

  Input	or fatal errors	will cause termination.	Errors that are	not fatal
  will cause termination only if the -Q	option is set. The following error
  values and messages will be displayed:

  EACCES
      There is a session ID mismatch. This is an internal error, which should
      be escalated via Technical Support.

  EBADF
      An incorrect inode type was specified.

      The database is corrupt. Use the -v (verify) and -F (fix)	options	to
      correct it.

  EEXIST
      The target of the	operation already exists, specify a different target.

  EFAULT
      A	kdsreq error occurred.	The device node	for which the ACK was issued
      was not found. This is an	internal error,	which should be	escalated via
      Technical	Support.

  EINVAL
      An incorrect input value was specified.  Specify a correct value.

  ENODEV
      The specified device record was not found	in the status database.

  ENOENT
      This general "no entry" error can	indicate one of	the following prob-
      lems:

	+  There was a problem accessing the databases,	the inode was not
	   found.

	+  During a database lookup, the specified entry was not found.

	+  When	removing a class, category, or cfginfo,	the specified entry
	   was not found.

	+  When	creating or deleting a directory, the specified	entry was not
	   found.

  ENOLCK
      This error indicates that	a lock is in place, possibly by	another
      instance of dsfmgr.

  ENOMEM
      This error occurs	during a malloc, indicating a memory problem (no
      memory).

  ENOSYS
      This error occurs	during a kdsreq, indicating that the function code is
      unknown. This is an internal error, which	should be escalated via
      Technical	Support.

  ENXIO
      This error indicates that	there was inconsistent data, or	data was not
      found in the dcc or dcd databases. If this error is seen when making a
      device node, it indicates	that the new device node was not found after
      it was made.

  EROFS
      The specified file system	is read-only.

  ESTALE
      The session id is	incorrect.

EXAMPLES

   1.  The following example adds the class disk in verbose mode:


	    # dsfmgr -V	-a class disk
	    ADD_ENTRY: "    l  0755  disk"

       The message indicates that a nonclustered device	with a default mode
       of 0755 was added.

   2.  The following example verifies the current database:


	    # dsfmgr -v
	    dsfmgr: verify all datum for system	at /

	    Device Class Directory Default Database:
		OK.

	    Device Category to Class Directory Database:
		OK.

	    Dev	directory structure:
		OK.

	    Dev	Nodes:

	      Errors:  0

	    Total errors:  0

   3.  The following example verifies and fixes	errors in the current data-
       base:


	    # dsfmgr -V	-F -v
	    dsfmgr: verify with	fix all	datum for system at /

	    Device Class Directory Default Database:
		OK.

	    Device Category to Class Directory Database:
		OK.

	    Dev	directory structure:
		OK.

	    Dev	Nodes:
		WARNING: node not found	in log:	/dev/tty00
		WARNING: device	node does not exist: /dev/tty01
		mknod( "/dev/tty01", 020666, 2300001 ) = 0
		WARNING: node not found	in log:	/dev/lp0
		OK.

	    Total warnings:   3

   4.  The following command displays the current contents of the database:


	    # dsfmgr -s
	    dsfmgr: show all datum for system at /

   5.  This example shows how you remove the kernel record of a	a device spe-
       cial file name. You might need to do this if a device is	removed	and
       the hardware database is	not updated correctly. Alternatively, you
       might want to preserve the previous device special file names for a
       device after the	system configuration is	changed.

       The following command shows how you might restore previous device spe-
       cial file names after a configuration change. This example assumes
       that you	know the previous device names and HWIDs

	a.  Assuming that the former device name was dsk0, and the new device
	    name is dsk5, use the /sbin/hwmgr command to delete	the old	data-
	    base entries for each device. Specify the former HWID for a	dev-
	    ice	as shown in the	following example:


		 # # /sbin/hwmgr delete	component -id 25

	b.  After the component	is removed, you	can delete the kernel's
	    record its device special files as follows:


		 # /sbin/dsfmgr	-R delete hwid 25
		 -dsk0a	-dsk0b -dsk0c -dsk0d ... dsk0h

	c.  You	can now	move the existing device special files to their	new
	    locations as follows:


		 #  /sbin/dsfmgr -m dsk5 dsk0



FILES

  /dev
      Location of the device files and subdirectories.

  /dev/disk, /dev/ntape, /dev/rdisk, /dev/tape
      The default device class subdirectories, containing device special
      files for	the named devices.

  /etc/cfginfo
      [Internal	use only.] The default configuration file.

  /etc/dccd.dat, /etc/dcdd.dat
      Device database files.

  /etc/dfsl.dat, /etc/dfsc.dat
      Status information.


SEE ALSO

  Commands: hwmgr(8), mknod(8)

  System Administration