| Current File : //usr/share/man/man2/swapctl.2 |
'\" te
.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
.TH swapctl 2 "25 Sep 1997" "SunOS 5.11" "System Calls"
.SH NAME
swapctl \- manage swap space
.SH SYNOPSIS
.LP
.nf
#include <sys/stat.h>
#include <sys/swap.h>
\fBint\fR \fBswapctl\fR(\fBint\fR \fIcmd\fR, \fBvoid *\fR\fIarg\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBswapctl()\fR function adds, deletes, or returns information about swap resources. \fIcmd\fR specifies one of the following options contained in <\fBsys/swap.h\fR>:
.sp
.in +2
.nf
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 */
.fi
.in -2
.sp
.LP
When \fBSC_ADD\fR or \fBSC_REMOVE\fR is specified, \fIarg\fR is a pointer to a \fBswapres\fR structure containing the following members:
.sp
.in +2
.nf
char *sr_name; /* pathname of resource */
off_t sr_start; /* offset to start of swap area */
off_t sr_length; /* length of swap area */
.fi
.in -2
.sp
.LP
The \fBsr_start\fR and \fBsr_length\fR members are specified in 512-byte blocks. A swap resource can only be removed by specifying the same values for the \fBsr_start\fR and \fBsr_length\fR members as were specified when it was added. Swap resources need not be removed in the order in which they were added.
.sp
.LP
When \fBSC_LIST\fR is specified, \fIarg\fR is a pointer to a \fBswaptable\fR structure containing the following members:
.sp
.in +2
.nf
int swt_n; /* number of swapents following */
struct swapent swt_ent[]; /* array of swt_n swapents */
.fi
.in -2
.sp
.LP
A \fBswapent\fR structure contains the following members:
.sp
.in +2
.nf
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 */
.fi
.in -2
.sp
.LP
The \fBSC_LIST\fR function causes \fBswapctl()\fR to return at most \fBswt_n\fR entries. The return value of \fBswapctl()\fR is the number actually returned. The \fBST_INDEL\fR bit is turned on in \fBste_flags\fR if the swap file is in the process of being deleted.
.sp
.LP
When \fBSC_GETNSWP\fR is specified, \fBswapctl()\fR returns as its value the number of swap resources in use. \fIarg\fR is ignored for this operation.
.sp
.LP
The \fBSC_ADD\fR and \fBSC_REMOVE\fR functions will fail if calling process does not have appropriate privileges.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the function \fBswapctl()\fR returns a value of \fB0\fR for \fBSC_ADD\fR or \fBSC_REMOVE\fR, the number of \fBstruct\fR \fBswapent\fR entries actually returned for \fBSC_LIST\fR, or the number of swap resources in use for \fBSC_GETNSWP\fR. Upon failure, the function \fBswapctl()\fR returns a value of \fB\(mi1\fR and sets \fBerrno\fR to indicate an error.
.SH ERRORS
.sp
.LP
Under the following conditions, the function \fBswapctl()\fR fails and sets \fBerrno\fR to:
.sp
.ne 2
.mk
.na
\fB\fBEEXIST\fR\fR
.ad
.RS 16n
.rt
Part of the range specified by \fBsr_start\fR and \fBsr_length\fR is already being used for swapping on the specified resource (\fBSC_ADD\fR).
.RE
.sp
.ne 2
.mk
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 16n
.rt
Either \fIarg\fR, \fBsr_name\fR, or \fBste_path\fR points to an illegal address.
.RE
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 16n
.rt
The specified function value is not valid, the path specified is not a swap resource (\fBSC_REMOVE\fR), part of the range specified by \fBsr_start\fR and \fBsr_length\fR lies outside the resource specified (\fBSC_ADD\fR), or the specified swap area is less than one page (\fBSC_ADD\fR).
.RE
.sp
.ne 2
.mk
.na
\fB\fBEISDIR\fR\fR
.ad
.RS 16n
.rt
The path specified for \fBSC_ADD\fR is a directory.
.RE
.sp
.ne 2
.mk
.na
\fB\fBELOOP\fR\fR
.ad
.RS 16n
.rt
Too many symbolic links were encountered in translating the pathname provided to \fBSC_ADD\fR or \fBSC_REMOVE\fR.
.RE
.sp
.ne 2
.mk
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
.rt
The length of a component of the path specified for \fBSC_ADD\fR or \fBSC_REMOVE\fR exceeds \fBNAME_MAX\fR characters or the length of the path exceeds \fBPATH_MAX\fR characters and \fB_POSIX_NO_TRUNC\fR is in effect.
.RE
.sp
.ne 2
.mk
.na
\fB\fBENOENT\fR\fR
.ad
.RS 16n
.rt
The pathname specified for \fBSC_ADD\fR or \fBSC_REMOVE\fR does not exist.
.RE
.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 16n
.rt
An insufficient number of \fBstruct\fR \fBswapent\fR structures were provided to \fBSC_LIST\fR, or there were insufficient system storage resources available during an \fBSC_ADD\fR or \fBSC_REMOVE\fR, or the system would not have enough swap space after an \fBSC_REMOVE\fR.
.RE
.sp
.ne 2
.mk
.na
\fB\fBENOSYS\fR\fR
.ad
.RS 16n
.rt
The pathname specified for \fBSC_ADD\fR or \fBSC_REMOVE\fR is not a file or block special device.
.RE
.sp
.ne 2
.mk
.na
\fB\fBENOTDIR\fR\fR
.ad
.RS 16n
.rt
Pathname provided to \fBSC_ADD\fR or \fBSC_REMOVE\fR contained a component in the path prefix that was not a directory.
.RE
.sp
.ne 2
.mk
.na
\fB\fBEPERM\fR\fR
.ad
.RS 16n
.rt
The {\fBPRIV_SYS_MOUNT\fR} was not asserted in the effective set of the calling process.
.RE
.sp
.ne 2
.mk
.na
\fB\fBEROFS\fR\fR
.ad
.RS 16n
.rt
The pathname specified for \fBSC_ADD\fR is a read-only file system.
.RE
.sp
.LP
Additionally, the \fBswapctl()\fR function will fail for 32-bit interfaces if:
.sp
.ne 2
.mk
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
.rt
The amount of swap space configured on the machine is too large to be represented by a 32-bit quantity.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRThe usage of the \fBSC_GETNSWP\fR and \fBSC_LIST\fR commands.
.sp
.LP
The following example demonstrates the usage of the \fBSC_GETNSWP\fR and \fBSC_LIST\fR commands.
.sp
.in +2
.nf
#include <sys/stat.h>
#include <sys/swap.h>
#include <stdio.h>
#define MAXSTRSIZE 80
main(argc, argv)
int argc;
char *argv[];
{
swaptbl_t *s;
int i, n, num;
char *strtab; /* string table for path names */
again:
if ((num = swapctl(SC_GETNSWP, 0)) == -1) {
perror("swapctl: GETNSWP");
exit(1);
}
if (num == 0) {
fprintf(stderr, "No Swap Devices Configured\en");
exit(2);
}
/* allocate swaptable for num+1 entries */
if ((s = (swaptbl_t *)
malloc(num * sizeof(swapent_t) +
sizeof(struct swaptable))) ==
(void *) 0) {
fprintf(stderr, "Malloc Failed\en");
exit(3);
}
/* allocate num+1 string holders */
if ((strtab = (char *)
malloc((num + 1) * MAXSTRSIZE)) == (void *) 0) {
fprintf(stderr, "Malloc Failed\en");
exit(3);
}
/* initialize string pointers */
for (i = 0; i < (num + 1); i++) {
s->swt_ent[i].ste_path = strtab + (i * MAXSTRSIZE);
}
s->swt_n = num + 1;
if ((n = swapctl(SC_LIST, s)) < 0) {
perror("swapctl");
exit(1);
}
if (n > num) { /* more were added */
free(s);
free(strtab);
goto again;
}
for (i = 0; i < n; i++)
printf("%s %ld\en",
s->swt_ent[i].ste_path, s->swt_ent[i].ste_pages);
}
.fi
.in -2
.SH SEE ALSO
.sp
.LP
\fBprivileges\fR(5)