hpux man page for swapctl

swapctl(2)							System Calls Manual							swapctl(2)

NAME
       swapctl - manage and configure system swap space

SYNOPSIS
PARAMETERS
       cmd	 Specifies the operation to be performed, which includes: adding a resource, deleting a resource reservation, and listing the swap
		 resources.

		 Add a new swap resource to the system.

		 List the swap devices on the system.
				Currently only the primary swap for the next boot will be listed, if it was configured by See  the  section  below
				for more details.

		 Remove the swap device configured on the system.
				Currently the file system swap removal is not supported.  See the section below for more details.

       arg	 Specifies  a  pointer	to a structure and is dependent on the type of command specified by the cmd parameter.	See below for more
		 information.

DESCRIPTION
       The system call manages system swap space by adding or deleting swap resources or returning information	about  swap  resources.   The  cmd
       parameter determines the value of the arg parameter.

       Each  of  these	commands  accepts/returns  information in a structure pointed to by the arg parameter.	The following sections discuss the
       information that should be passed in to the system call.  They also explain the information contained in these structures after a  success-
       ful return.

   The SC_ADD Command
       For  the  command, arg parameter is a pointer to the structure with some of the following members, depending on which type of swap is being
       configured:

       where the fields are as follows:

	      sr_flag	     is one of the following:

			     o (primary swap device for the next boot)

			     o (swap device for current boot)

			     o (swap file system for the current boot)

			     See the flag field description below for details on the usage.

	      *sr_name	     Provides the pathname of the resource that is being added.

	      sr_start	     Specifies, in 1 kilobyte blocks, the starting offset of the swap resource area.

	      sr_length      Specifies, in 1 kilobyte blocks, the length of the swap area.  Value of 0 means configure the entire device, starting
			     from the offset.

	      sr_priority    Indicates the order in which the swap space from the device or file system is used.  It has a range of 0 (highest) to
			     10 (lowest).  Swap space is taken from the lower-numbered systems first.

	      sr_min	     (Needed for file system swap only.)  Indicates the minimum number of file system blocks the  swap	system	will  take
			     from the file system.

	      sr_lim	     (Needed for file system swap only.)  Indicates the maximum number of file system blocks the swap system is allowed to
			     take from the file system.

	      sr_res	     (Needed for file system swap only.)  Indicates the number of file system blocks that are reserved for swap system use
			     only.

       For the command, depending on the sr_flag type, the following members of structure need to be passed in.

       The  flag  is  used to change the primary swap configuration for the next boot.	This change will only take place after the next boot.  The
       changed configuration will remain effective until it is changed again using this option.

       The sr_priority for the primary swap for the next boot should always be set to 1.  Other priority values are considered invalid.

       A value of -1 for sr_start implies a presence of a file system on the swap device and swap area to start immediately after that.

       The length of the device swap to be configured should at least be kilobytes in size.  The length is always rounded down to be a multiple of

       A VxVM or LVM-based logical volume should be created with contiguous layout to be configured as a primary swap device.  For LVM-based  sys-
       tems only the logical volumes within the root volume group can be configured as a primary swap device.

       For  a  pre-existing  directory	swap, a value of -1 for sr_min, sr_lim, sr_res, or sr_priority will keep the value unchanged.  This can be
       used to change selective values without affecting others.  For example, if priority of a pre-existing directory swap needs  to  be  changed
       without affecting the values of sr_min, sr_lim, or sr_res, one can specify the new priority value and pass -1 for other arguments.

       The  size  for the file system blocks mentioned above is the preferred file system block size.  The preferred file system block size can be
       obtained by the call.

   The SC_REMOVE Command
       For the command, arg parameter is a pointer to the structure with the following members:

       where the fields are as follows:

	      sr_flag	     is one of the following:

			     o (primary swap device for the next boot)

			     o (swap device for current boot)

	      *sr_name	     Pathname of the resource that is being removed.

	      sr_start	     Starting offset that was specified with the command.

	      sr_length      Length of swap device that was specified with the command.

       The sr_name, sr_start, and sr_length should be the same values that were used with the command.	The for the next boot  primary	swap  will
       only  work if the primary swap device was configured using the command.	A primary swap device that has been configured for swap by methods
       other than can not be altered by the command.

       When using the and commands, the calling process fails if the appropriate privileges do not exist for the operation.

   The SC_LIST Command
       For the command, arg parameter is a pointer to the structure with following members:

       where:

	      swt_n	     Specifies the maximum entries that will be returned by

	      swt_ent	     Is an array of swt_n Currently the command can be used to list the primary swap configured  for  next  boot,  so  the
			     array size for the structures is 1.

	      swt_flag	     sr_flag is

			     The flag indicates that the swap resource that is marked as swap for the next boot be listed.  This will only work if
			     the primary swap device was configured using the command.	Devices that have been configured for use by methods other
			     than can not be listed by the command.

       The structure will return the information in the following fields:

       Before  is  issued,  allocate  memory to all of the ste_path pointers.  Ensure that each of the areas allocated is at least bytes long.	is
       defined in

       The fields are defined as follows:

	      *ste_path      Specifies the name of the swap device.

	      ste_dev	     Specifies the device number corresponding to the ste_path.

	      ste_priority   Specifies the priority at which the device was configured.

	      ste_start      Specifies in 512-byte blocks, the starting block to begin swapping.

	      ste_length     Specifies in 512-byte blocks, the length of the swap area.

	      ste_dev	     Specifies the device number corresponding to the ste_path.

       The command for now only lists the primary swap device that is configured for next boot.  The interface has to be used to get the  list	of
       all other swap resources.

RETURN VALUES
       On  success,  the system call returns 0 when used with the or commands.	For the command, the number of entries actually returned indicates
       success.

       On error, the system call returns a value of -1 and sets to indicate the error.

ERRORS
       If the system call fails, is set to one of the following:

	      A component of the
			     sr_name prefix denies search permission.

	      The input device pointer to be
			     sr_name has a logical volume on it.

	      For	     the device associated with sr_name already has swap turned on.

	      The device associated with
			     sr_name is already in use.

	      For primary swap configuration, indicates that a swap device is
			     already configured as primary swap for next boot.	It should be removed using the command before a  new  one  can	be
			     added.

	      Unable to read the device associated with
			     sr_name.

	      Unable to read or write to the kernel registry services (see
			     krs(5)).

	      Specifies that the structure pointed to by the
			     arg  parameter  or swt_ent field of struct, or one of the fields sr_name or ste_path is outside the allocated address
			     space.

	      Invalid input parameter passed in.

	      Indicates that the LVM device passed in for
			     is not early boot accessible or is a non-contiguous logical volume

	      The path used with the
			     command is not a swap resource.

	      The range indicated by the
			     sr_start and sr_length fields for the command is outside the resource specified.

	      Indicates that the pathname used with the
			     or commands has too many symbolic links to correctly translate the pathname.

	      Indicates that the length or path used with the
			     or command exceeds the maximum allowed with in effect.

	      Indicates that a invalid pathname was specified with either the
			     or commands.

	      Indicates that the primary swap was not set using the
			     command when using with the command to list primary swap.

	      Indicates that the path used with the
			     command for adding device swap is not a block device file.

	      Indicates that the path used with the
			     command for adding file system swap is not a directory.

	      The device associated with
			     sr_name could not be opened.

	      Indicates that insufficient privileges do not exist for the operation.

	      Indicates that a read-only file system was specified by the path for the
			     command.

EXAMPLES
       The following example adds, lists and removes a primary swap device for next boot:

	      #include <sys/swap.h>
	      #include <stdio.h>

	      int main() {
		      int rv;

		      swapres_t swp;
		      swaptable_t swt;
		      swapent_t swent;

		      char path[1024] = "/dev/disk/disk12 ";
		      char ret_path[1024];

		      bzero(ret_path, 1024);

		      /* add a new primary swap for next boot */
		      swp.sr_flag = SW_PRIMARY | SW_NEXTBOOT;
		      swp.sr_name = path;
		      swp.sr_start = 0;
		      swp.sr_length = 0; /* 0 len implies, use the entire dev */
		      swp.sr_priority = 1;

		      rv = swapctl(SC_ADD, (void *)&swp);
		      if (rv) {
			      perror("swapctl/SC_ADD failed");
			      exit(1);
		      }

		      /* list the swap device configured above */
		      swent.ste_path = path;

		      swt.swt_n = 1;
		      swt.swt_flags = SW_PRIMARY | SW_NEXTBOOT;
		      swt.swt_ent = &swent;

		      rv = swapctl(SC_LIST, (void *)&swt);
		      if (rv != 1) { /* returns the number of swap devices returned */
			      printf("swapctl/SC_LIST returned: %d 
", rv);
			      perror("swapctl/SC_LIST failed");
			      exit(2);
		      }

		      printf("Primary swap for next boot: %s 
", swent.ste_path);

		      /* Remove the above configured primary swap */
		      swp.sr_flag = SW_PRIMARY | SW_NEXTBOOT;
		      swp.sr_name = path; /* same path as used for SC_ADD */
		      swp.sr_start = 0; /* same start as used for SC_ADD */
		      swp.sr_length = 0; /* same length as used for SC_ADD */
		      swp.sr_priority = 1;

		      rv = swapctl(SC_REMOVE, (void *)&swp);
		      if (rv) {
			      perror("swapctl/SC_REMOVE failed");
			      exit(3);
		      }

		      return 0;
	      }

WARNINGS
       If is used for configuring primary swap, other methods for configuring primary swap like and system configuration files (see  lvlnboot(1M),
       vxvmboot(1M),  and  system(4)),	and PA HP-UX boot loader mechanism will become ineffective.  In other words, if a device is configured for
       primary swap using then other device(s) that are configured for primary swap using the above mentioned methods will not be effective.

       The and system configuration file methods for configuring swap are deprecated and will be obsoleted in future releases.

AUTHOR
       was developed by HP.

SEE ALSO
       hpux(1M), lvlnboot(1M), vxvmboot(1M), swapctl(2), system(4), swchunk(5).

																	swapctl(2)