.if n .pH g2.swapctl @(#)swapctl	40.15 of 10/10/89
.\" Copyright 1989 AT&T
.\"ident	"@(#)svid_rt:rt_os/swapctl	1.2"
.\" @(#)swapctl 1.4 88/09/26 SMI;
'\" macro stdmacro
.\" Sun's swapctl.3
'\"macro stdmacro
.nr X
.if \nX=0 .ds x} swapctl 2 "" "\&"
.if \nX=1 .ds x} swapctl 2 ""
.if \nX=2 .ds x} swapctl 2 "" "\&"
.if \nX=3 .ds x} swapctl "" "" "\&"
.TH \*(x}
.if '\*p'' \{\
.ds N
.ds p
.ds P
.SH NAME
\f4swapctl\f1 \- manage swap space
.SH SYNOPSIS
.nf
.ft 4
#include <sys/stat.h>
#include <sys/swap.h>
.sp0.5
int swapctl(int cmd, void *arg);
.ft 1
.fi
.SH DESCRIPTION
\f4swapctl\f1 adds, 
deletes, or returns information about swap resources.
\f2cmd\f1
specifies one of the following options
contained in
\f4<sys/swap.h>\f1:
.P
.ta .5i 2.0i
.nf
.ft 4
.sp .5
	SC_ADD	/* add a resource for swapping */
	SC_LIST	/* list the resources for swapping */
	SC_REMOVE	/* remove a resource for swapping */
	SC_GETNSWP	/* return number of swap resources */
.sp .5
.ft 1
.fi
.P
When
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1
is specified,
\f2arg\f1
is a pointer to a
\f4swapres\f1
structure containing the following members:
.P
.ft 4
.nf
.ta .5i 1i 2i
.sp .5
	char	*sr_name;	/* pathname of resource */
	off_t	sr_start;	/* offset to start of swap area */
	off_t	sr_length;	/* length of swap area */
.sp .5
.ft 1
.fi
.P
\f4sr_start\fP and \f4sr_length\fP are specified in 512-byte blocks.
.P
When
\f4SC_LIST\f1
is specified,
\f2arg\f1
is a pointer to a
\f4swaptable\f1
structure containing the following members:
.P
.ft 4
.nf
.ta .5i 1i 2i
.sp .5
	int	swt_n;		/* number of swapents following */
	struct	swapent swt_ent[];	/* array of swt_n swapents */
.sp .5
.ft 1
.fi
.P
A \f4swapent\f1 structure contains the following members:
.P
.ft 4
.nf
.ta .5i 1i 2i
.sp .5
	char	*ste_path;	/* name of the swap file */
	off_t	ste_start;	/* starting block for swapping */
	off_t	ste_length;	/* length of swap area */
	long	ste_pages;	/* number of pages for swapping */
	long	ste_free;	/* number of ste_pages free */
	long	ste_flags;	/* ST_INDEL bit set if swap file */
				/* is now being deleted */
.sp .5
.ft 1
.fi
.P
\f4SC_LIST\f1
causes
\f4swapctl\f1
to return at most
\f4swt_n\f1
entries.
The return value of
\f4swapctl\f1
is the number actually returned.
The \f4ST_INDEL\fP bit is turned on in \f4ste_flags\fP if
the swap file is in the process of being deleted.
.P
When
\f4SC_GETNSWP\f1
is specified,
\f4swapctl\f1
returns as its value the number of swap resources in use.
\f2arg\f1
is ignored for this operation.
.P
The \f4SC_ADD\f1 and \f4SC_REMOVE\f1 functions will fail
if calling process does not have appropriate privileges.
.SH RETURN VALUE
Upon successful completion, the function \f4swapctl\f1 returns 
a value of \f40\f1 for \f4SC_ADD\f1 or \f4SC_REMOVE\f1,
the number of \f4struct\f1 \f4swapent\f1 entries actually returned 
for \f4SC_LIST\f1, or
the number of swap resources in use for \f4SC_GETNSWP\f1.
Upon failure, the function \f4swapctl\f1 returns a value 
of \f4\-1\f1 and sets \f4errno\f1 to indicate an error.
.SH ERRORS
Under the following conditions,
the function \f4swapctl\f1 fails and sets \f4errno\f1 to:
.TP 1.25i
\f4EEXIST\f1
Part of the range specified by \f4sr_start\fP and \f4sr_length\fP
is already being used for swapping on the specified resource
(\f4SC_ADD\f1).
.TP
\f4EFAULT\fP
.IR arg ,
\f4sr_name\fP, or \f4ste_path\fP points outside the allocated address space.
.TP
\f4EINVAL\f1
The specified function value is not valid,
the path specified is not a swap resource (\f4SC_REMOVE\fP),
part of the range specified by \f4sr_start\fP and \f4sr_length\fP
lies outside the resource specified (\f4SC_ADD\fP),
or
the specified swap area is less than one page (\f4SC_ADD\fP).
.TP
\f4EISDIR\f1
The path specified for
\f4SC_ADD\f1
is a directory.
.TP
\f4ELOOP\f1
Too many symbolic links were encountered in translating the pathname
provided to
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1 .
.TP
\f4ENAMETOOLONG\f1
The length of a component of the path
specified for
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1
exceeds \f4{NAME_MAX}\f1
characters or the length of the path exceeds \f4{PATH_MAX}\f1 characters
and \f4{_POSIX_NO_TRUNC}\f1 is in effect.
.TP
\f4ENOENT\f1
The pathname specified for
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1
does not exist.
.TP
\f4ENOMEM\f1
An insufficient number of
\f4struct\f1
\f4swapent\f1
structures were provided to
\f4SC_LIST\f1,
or there were insufficient system storage resources available during an
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1,
or the system would not have enough swap space after an
\f4SC_REMOVE\fP.
.TP
\f4ENOSYS\fP
The pathname specified for \f4SC_ADD\fP or \f4SC_REMOVE\fP is not a file or block special device.
.TP
\f4ENOTDIR\f1
Pathname provided to
\f4SC_ADD\f1
or
\f4SC_REMOVE\f1
contained a component in the path prefix that was not a directory.
.TP
\f4EPERM\f1
The process does not have appropriate privileges.
.TP
\f4EROFS\fP
The pathname specified for \f4SC_ADD\fP is a read-only file system.
.Ee
