'\" 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 #include \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 #include #include #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)