unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



swapctl(2)							   swapctl(2)



NAME

  swapctl - Manages the	system swap space

SYNOPSIS

  #include <&lt;sys/stat.h>&gt;
  #include <&lt;sys/swap.h>&gt;

  int swapctl(
	  int cmd,
	  void *arg );

PARAMETERS

  cmd Specifies	the operation to be performed.	Options	include	adding a
      resource,	deleting a resource, removing a	resource, or returning the
      number of	swap resources.

  arg Specifies	a pointer to a structure.  See the DESCRIPTION section for
      information on this structure.

DESCRIPTION

  The swapctl function manages the system swap space by	adding,	deleting, or
  returning information	about swap resources. The cmd parameter	that you
  select determines the	value of the arg parameter.  The following sections
  discuss the available	commands and command arguments.

  Available Commands


  The swapctl function adds, removes, or returns information on	the system
  swap space using the following values	for the	cmd parameter:

  SC_ADD
      Includes a new resource in the swap list.

  SC_LIST
      Provides a list of the resources available for swapping.

  SC_REMOVE
      Removes a	resource from the swap list.

  SC_GETNSWP
      Counts and returns the number of swap resources

      Use this command to determine how	many swapent structures	will be
      needed for a SC_LIST command request

  With the exception of	the SC_GETSNSWP	command, each of these commands
  returns information in a structure pointed to	by the arg parameter.  The
  next sections	discusses the information that is contained in these
  structures after a successful	return.






  Command Arguments


  The value of the arg parameter is specific to	the type of command specified
  by the cmd parameter.	 This section highlights the value for the arg param-
  eter as it pertains to the commands.

  If either the	SC_ADD or SC_REMOVE command is specified, the arg parameter
  is a pointer to the following	swapres	structure:

       typdef struct swapres {
	    char     sr_name;
	    off_t    sr_start;
	    off_t    sr_length;
       } swapres_t;

  The fields are defined as follows:

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

  sr_start
      Specifies	in 512-byte blocks, the	offset of the resource area from the
      start.

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

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

  If the SC_LIST command is specified, the arg parameter is a pointer to the
  following swaptable structure:

       int     swt_n;
       struct swapent  swt_ent [];

  In this structure, the field swt_n specifies the maximum entries that	will
  be returned by the swapctl function. The swt_ent field is an array of	swt_n
  swapents. The	swapent	structure is as	follows:

       typdef struct swapwent {
	    char     *ste_path;
		 off_t	  ste_start;
		 off_t	  ste_length;
		 long	 ste_pages;
		 long	 ste_free;
		 long	 ste_flags;
       } swapwent_t;

  Before the swapctl(2)	is issued, allocate memory to all of the ste_path
  pointers.  Ensure that each of the areas allocated is	at least MAXPATHLEN
  bytes	long.  MAXPATHLEN is defined in	<&lt;sys/param.h>&gt;.

  The fields are defined as follows:

  *ste_path
      Specifies	the name of the	swap file.

  ste_start
      Specifies	the starting block to begin swapping.

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

  ste_page
      Specifies	the number of pages available for swapping.

  ste_free
      Specifies	the number of pages that are free.

  ste_flags
      Sets the ST_INDEL	bit if the swap	file is	being deleted.

RETURN VALUES

  On success, the swapctl function returns zero	(0) when used with the SC_ADD
  or SC_REMOVE commands. For the SC_LIST command, the number of	struct
  swapent entries actually returned indicates success, and for SC_GETNSWP,
  the number of	swap resources in use is returned upon success.

  On error, the	swapctl	function returns a value of -1 and sets	errno to
  indicate the error.

ERRORS

  If the swapctl function fails, errno is set to one of	the following:

  [EEXIST]
      Indicates	that the range specified by the	sr_start and sr_length fields
      for the SC_ADD command is	already	in use for swapping.

  [EFAULT]
      Specifies	that the structure pointed to by the arg parameter, or one of
      the fields sr_name or ste_path is	outside	the allocated address space.

  [EINVAL]
      Specifies	one of the following:

	+  The command value is	not valid.

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

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

	+  The indicated swap area is less than	one page for the SC_ADD	com-
	   mand.

  [EISDIR]
      Indicates	that the path used with	the SC_ADD command is not a direc-
      tory.

  [ELOOP]
      Indicates	that the pathname used with the	SC_ADD or SC_REMOVE commands
      has too many symbolic links to correctly translate the pathname.

  [ENAMETOOLONG]
      Indicates	that the length	or path	used with the SC_ADD or	SC_REMOVE
      command exceeds the maximum allowed with {_POSIX_NO_TRUNC} in effect.

  [ENOENT]
      Indicates	that a nonexisting pathname was	specified with either the
      SC_ADD or	SC_REMOVE commands.

  [ENOMEM]
      Specifies	one of the following:

	+  Not enough struct swapent structures	exist for the SC_LIST com-
	   mand.

	+  Sufficient system storage resources were not	available during an
	   SC_ADD or SC_REMOVE operation.

	+  Not enough swap space would exists after an SC_REMOVE operation.

  [ENOSYS]
      Indicates	that the pathname specified for	a SC_ADD or SC_REMOVE opera-
      tion is not a filename or	special	block device.

  [ENOTDIR]
      Specifies	that the pathname used with the	SC_ADD or SC_REMOVE commands
      contained	a component in the path	that was not a directory.

  [EPERM]
      Indicates	that insufficient privileges do	not exist for the operation.

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