devid_str_free man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

devid_get(3DEVID)	  Device ID Library Functions	     devid_get(3DEVID)

NAME
       devid_get,    devid_compare,    devid_deviceid_to_nmlist,   devid_free,
       devid_free_nmlist,	  devid_get_minor_name,		 devid_sizeof,
       devid_str_decode,   devid_str_free,   devid_str_encode,	devid_valid  -
       device ID interfaces for user applications

SYNOPSIS
       cc [ flag... ] file... -ldevid [ library... ]
       #include <devid.h>

       int devid_get(int fd, ddi_devid_t *retdevid);

       void devid_free(ddi_devid_t devid);

       int devid_get_minor_name(int fd, char **retminor_name);

       int devid_deviceid_to_nmlist(char *search_path, ddi_devid_t devid, char
       *minor_name, devid_nmlist_t **retlist);

       void devid_free_nmlist(devid_nmlist_t *list);

       int devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);

       size_t devid_sizeof(ddi_devid_t devid);

       int devid_valid(ddi_devid_t devid);

       char *devid_str_encode(ddi_devid_t devid, char *minor_name);

       int devid_str_decode(char *devidstr, ddi_devid_t *retdevid, char **ret‐
       minor_name);

       void devid_str_free(char *str);

DESCRIPTION
       These functions provide unique identifiers (device  IDs)	 for  devices.
       Applications  and  device  drivers  use these functions to identify and
       locate devices, independent of the device's physical connection or  its
       logical device name or number.

       The  devid_get()	 function  returns  in	retdevid the device ID for the
       device associated with the open file descriptor fd, which refers to any
       device.	It  returns an error if the device does not have an associated
       device ID. The caller must free the memory allocated for retdevid using
       the  devid_free() function.

       The  devid_free()  function  frees the space that was allocated for the
       returned devid by devid_get() and devid_str_decode().

       The devid_get_minor_name() function returns the minor name,  in	retmi‐
       nor_name,  for  the device associated with the open file descriptor fd.
       This name is specific to the particular minor number, but is  "instance
       number"	specific.  The	caller	of  this function must free the memory
       allocated for the returned retminor_name string using devid_str_free().

       The   devid_deviceid_to_nmlist()	  function   returns   an   array   of
       devid_nmlist  structures,  where	 each  entry  matches  the  devid  and
       minor_name passed in. If the minor_name specified is one of the special
       values	   (DEVID_MINOR_NAME_ALL,     DEVID_MINOR_NAME_ALL_CHR,	    or
       DEVID_MINOR_NAME_ALL_BLK) , then all minor names associated with	 devid
       which  also  meet  the  special	minor_name  filtering requirements are
       returned. The devid_nmlist  structure  contains	the  device  name  and
       device  number. The last entry of the array contains a null pointer for
       the devname and	NODEV for the device number. This  function  traverses
       the file tree, starting at search_path. For each device with a matching
       device ID and minor name tuple, a device name  and  device  number  are
       added  to  the  retlist. If no matches are found, an error is returned.
       The caller of this function must free  the  memory  allocated  for  the
       returned array with the devid_free_nmlist() function. This function may
       take a long time to complete if called with the device ID of  an	 unat‐
       tached device.

       The  devid_free_nmlist()	 function  frees  the  memory allocated by the
       devid_deviceid_to_nmlist() function.

       The devid_compare() function compares two  device  IDs  and  determines
       both  equality  and sort order. The function returns an integer greater
       than 0 if the device ID pointed to by devid1 is greater than the device
       ID  pointed  to	by devid2. It returns 0 if the device ID pointed to by
       devid1 is equal to the device ID pointed to by devid2.  It  returns  an
       integer less than 0 if the device ID pointed to by  devid1 is less than
       the device ID pointed to by devid2. This function  is  the  only	 valid
       mechanism  to  determine	 the equality of two devids. This function may
       indicate equality for arguments which by simple inspection appear  dif‐
       ferent.

       The devid_sizeof() function returns the size of devid in bytes.

       The  devid_valid() function validates the format of a devid. It returns
       1 if the format is valid, and 0 if invalid. This check may  not	be  as
       complete	 as  the  corresponding kernel function ddi_devid_valid() (see
       ddi_devid_compare(9F)).

       The devid_str_encode() function encodes a devid and minor_name  into  a
       null-terminated	ASCII  string,	returning a pointer to that string. To
       avoid shell conflicts, the devid portion of the string  is  limited  to
       uppercase  and  lowercase letters, digits, and the plus (+), minus (-),
       period (.), equals (=), underscore (_), tilde (~), and comma (,)	 char‐
       acters.	If  there  is an ASCII quote character in the binary form of a
       devid, the string representation will be in hex_id form,	 not  ascii_id
       form.  The  comma  (,) character is added for "id1," at the head of the
       string devid. If both a devid and a minor_name are  non-null,  a	 slash
       (/)is  used  to	separate  the devid from the minor_name in the encoded
       string.	If minor_name is null, only the devid is encoded. If the devid
       is null then the special string "id0" is returned. Note that you cannot
       compare the returned string against another string with	strcmp(3C)  to
       determine devid equality.  The string returned must be freed by calling
       devid_str_free().

       The devid_str_decode() function takes a string previously  produced  by
       the  devid_str_encode()	or  ddi_devid_str_encode() (see ddi_devid_com‐
       pare(9F)) function and decodes the contained device ID and minor	 name,
       allocating and returning pointers to the extracted parts via the retde‐
       vid and retminor_name arguments. If  the	 special  devidstr  "id0"  was
       specified,  the	returned device ID and minor name will both be null. A
       non-null returned devid must be freed by the caller by the devid_free()
       function.  A  non-null  returned	 minor	name  must be freed by calling
       devid_str_free().

       The devid_str_free() function frees the character  string  returned  by
       devid_str_encode()   and	  the	retminor_name	argument  returned  by
       devid_str_decode().

RETURN VALUES
       Upon successful completion, the	devid_get(),   devid_get_minor_name(),
       devid_str_decode(),  and devid_deviceid_to_nmlist() functions return 0.
       Otherwise, they return −1.

       The devid_compare() function returns the following values:

       −1	The device ID pointed to by devid1 is less than the device  ID
		pointed to by devid2.

       0	The  device ID pointed to by devid1 is equal to	 the device ID
		pointed to by devid2.

       1	The device ID pointed to by devid1 is greater than the	device
		ID pointed to by devid2.

       The  devid_sizeof()  function  returns  the  size of devid in bytes. If
       devid is null, the number of bytes that must be allocated and  initial‐
       ized to determine the size of a complete device ID is returned.

       The devid_valid() function returns 1 if the devid is valid and 0 if the
       devid is invalid.

       The devid_str_encode() function returns NULL to indicate failure. Fail‐
       ure  may	 be  caused by attempting to encode an invalid string.	If the
       return value is non-null, the caller must free the returned  string  by
       using the devid_str_free() function.

EXAMPLES
       Example	  1:	Using	 devid_get(),	 devid_get_minor_name(),   and
       devid_str_encode()

       The  following  example	shows  the   proper   use   of	  devid_get(),
       devid_get_minor_name(),	and devid_str_encode() to free the space allo‐
       cated for devid,	 minor_name and encoded devid.

       int fd;
       ddi_devid_t    devid;
       char	   *minor_name, *devidstr;
       if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
	   ...
       }
       if (devid_get(fd, &devid) != 0) {
	   ...
       }
       if (devid_get_minor_name(fd, &minor_name) != 0) {
	   ...
       }
       if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
	   ...
       }
       printf("devid %s\n", devidstr);
       devid_str_free(devidstr);
       devid_free(devid);
       devid_str_free(minor_name);

       Example 2: Using devid_deviceid_to_nmlist() and devid_free_nmlist()

       The  following  example	shows	the   proper   use   of	   devid_devi‐
       ceid_to_nmlist() and devid_free_nmlist():

       devid_nmlist_t  *list = NULL;
       int    err;
       if (devid_deviceid_to_nmlist("/dev/rdsk", devid,
	   minor_name, &list))
	       return (-1);
       /* loop through list and process device names and numbers */
       devid_free_nmlist(list);

ATTRIBUTES
       See attributes(5) for description of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT−Safe			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Stable			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       free(3C), libdevid(3LIB), attributes(5), ddi_devid_compare(9F)

SunOS 5.10			  30 Nov 2001		     devid_get(3DEVID)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net