set_usage(3)						     Library Functions Manual						      set_usage(3)

NAME

       set_usage - Checks whether a disk partition is in use and sets the fstype of the partition in the disk label.

LIBRARY

       Filesystem Library (libfilsys.a)
       Shared Filesystem Library (libfilsys.so)

SYNOPSIS

       #include <sys/disklabel.h>
       #include <overlap.h>

       int set_usage(
	       const char *special,
	       int fstype,
	       int Force);

PARAMETERS

       Points  to  a  special  device  file.   The  file  system type (fstype) to set for the application in the disk label. For example, UFS uses
       FS_BSDFFS and databases use FS_DB.  See <sys/disklabel.h> for a list of the supported file system types.  When  the  application  wants	to
       override a failure in the usage checks and set the fstype, Force is set to 1.

DESCRIPTION

       The  set_usage function checks whether the special device file is in use, that is, whether it contains a valid file system, is part of LSM,
       or is being used by a database or for swap space.  It also checks that the range of blocks to be used does not overlap with blocks that are
       already	in  use or marked to be in use.  If the checks succeed, this function then sets the fstype for the partition in the disk label. If
       the checks do not succeed, the fstype is not modified and an error is returned. The Force parameter can be set, so that the function  over-
       rides  a failure in the usage checking and modifies the file system type.  Note that if the specified partition or an overlapping partition
       is open, the Force parameter cannot override the usage checking.

       Before allocating a partition, an application should check that none of the overlapping partitions is in use. When an  application  uses  a
       partition,  it  should  mark  its  use by setting the fstype field in the partition map in the disk label.  The fstypes that can be set are
       listed in <sys/disklabel.h>.

EXAMPLES

       The following program illustrates the use of set_usage() and the possible error messages based on return values from set_usage().

       #define DKTYPENAMES #include <stdio.h> #include <sys/disklabel.h> #include <overlap.h>

       #define STR_ERR_OPEN 
	   "Error: %s is open and in use.
"

       #define STR_ERR_OPEN_OVERLAP 
	   "Error: Partition overlapping %s is open and in use.
"

       #define STR_ERR_INVALID_DEV 
	   "Error: %s is an invalid device or cannot be opened.
"

       #define STR_ERR_DEFAULT_FSTYPE 
	   "Error: %s is marked in the disk label as in use by %s.
"

       #define STR_WARN_FSTYPE_OVERLAP 
	   "Warning: partition(s) which overlaps %s are marked in use.
"

       #define STR_WARN_MULT_OVERLAP 
	   "Warning: %s and overlapping partition(s) are marked in use.
"

       #define STR_WARN_INVAL_DISKLBL 
	   "Warning: the disklabel for %s does not exist or is corrupted.
"

       int mark_usage(char *special, int fstype) {
	   int	  ret;
	   int	  force = 0;
	   void    do_interactive(char *);

	   ret = set_usage(special, fstype, force);

	   if (ret == 0) {
	       /*
		* Specified partition is available for use and
		* has been marked in use by "fstype".
		*/
	       return (0);
	   }

	   switch (ret) {

	   case OV_ERR_OPEN_OVERLAP:
	       /*
		* Check if the specified partition is open.
		*/
	       ret = check_usage(special, OV_CHECK_EXACT);
	       if (ret == OV_ERR_OPEN_OVERLAP)
		   fprintf(stderr, STR_ERR_OPEN, special);
	       else
		   fprintf(stderr, STR_ERR_OPEN_OVERLAP, special);
	       return (-1);

	   case OV_ERR_INVALID_DEV:
	       fprintf(stderr, STR_ERR_INVALID_DEV, special);
	       return (-1);

	   case OV_ERR_INVALID_DSKLBL:
	       fprintf(stderr, STR_WARN_INVAL_DISKLBL, special);
	       return (-1);

	   case OV_ERR_FSTYPE_OVERLAP:
	       fprintf(stderr, STR_WARN_FSTYPE_OVERLAP, special);
	       /*
		* Check if the user overrides the warning.
		*/
	       do_interactive(special);
	       force = 1;
	       ret = set_usage(special, fstype, force);
	       break;

	   case OV_ERR_MULT_FSTYPE_OVERLAP:
	       fprintf(stderr, STR_WARN_MULT_OVERLAP, special);
	       /*
		* Check if the user overrides the warning.
		*/
	       do_interactive(special);
	       force = 1;
	       ret = set_usage(special, fstype, force);
	       break;

	   }

	   return (-1); }

       void do_interactive(char *special) {
	   int c;

	   /*
	    * Check if stdin is a terminal.
	    */
	   if ( !(isatty(fileno(stdin))) ) {
	       exit(1);
	   }

	   do {
	       printf("CONTINUE? [y/n] ");
	       (void) fflush(stdout);

	       /* read input */
	       c = getc(stdin);

	       /* Skips over all chars which are not CR.  Only
		* the first character typed is significant.
		*/
	       while (c!='
' && getc(stdin)!='
'){
	       }

	       if(c == 'n' || c == 'N')
		   exit(2);
	   } while (c!='y' && c!='Y');

	   return; }

RETURN VALUES

       The set_usage function returns the following values.  Logical names for the return values are listed in parentheses.  The  checks  succeeds
       (the  specified	range  of  blocks is not open or marked for use), and the fstype field for the specified special device file was set.  The
       fstype field could not be modified, because either the specified partition or another overlapping partition is in use.  This  error  cannot
       be  overridden  by  the	Force  parameter.  Either the special device file is invalid or the device cannot be opened.  This error cannot be
       overridden by the Force parameter.  When Force is 0, this value is returned to indicate that one or more other partitions overlap with  the
       specified special device file.  When Force is 1, this value indicates that any overlapping partitions that are marked for use will be modi-
       fied to the FS_UNUSED type. The return value will then be 0.  The  specified partition and overlapping partitions  have	the  fstype  field
       set. When Force is 1, the overlapping partitions will be modified to the FS_UNUSED type. The return value will then be 0.  The disklabel is
       not present or is corrupted.  An error was encountered during the checks.  Either /etc/fdmns or /etc/fdmns/domain for an in-use domain does
       not  exist or is corrupted.  An error was encountered during the checks.  The special device file for an in-use swap device does not exist.
       This indicates a failure in updating the disk label.  When Force is 0, this value indicates that  the  specified  special  device  file	is
       marked  for use.  The return value will be the fstype set for the partition. Refer to <sys/disklabel.h> to determine the fstype that corre-
       sponds to the return value.

	      When Force is 1, this value indicates that any overlapping partitions that are marked for use will  be  modified	to  the  FS_UNUSED
	      type. The return value will then be 0.

RELATED INFORMATION

       Commands: mkfdmn(8), newfs(8), voldisk(8), swapon(8)

       Functions: check_usage(3) delim off

																      set_usage(3)