Index: stable/9/lib/libc/db/man/hash.3 =================================================================== --- stable/9/lib/libc/db/man/hash.3 (revision 290886) +++ stable/9/lib/libc/db/man/hash.3 (revision 290887) @@ -1,196 +1,196 @@ .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)hash.3 8.6 (Berkeley) 8/18/94 .\" $FreeBSD$ .\" .Dd August 18, 1994 .Dt HASH 3 .Os .Sh NAME .Nm hash .Nd "hash database access method" .Sh SYNOPSIS .In sys/types.h .In db.h .Sh DESCRIPTION The routine .Fn dbopen is the library interface to database files. One of the supported file formats is .Nm files. The general description of the database access methods is in .Xr dbopen 3 , this manual page describes only the .Nm specific information. .Pp The .Nm data structure is an extensible, dynamic hashing scheme. .Pp The access method specific data structure provided to .Fn dbopen is defined in the .In db.h include file as follows: .Bd -literal typedef struct { u_int bsize; u_int ffactor; u_int nelem; u_int cachesize; - u_int32_t (*hash)(const void *, size_t); + uint32_t (*hash)(const void *, size_t); int lorder; } HASHINFO; .Ed .Pp The elements of this structure are as follows: .Bl -tag -width indent .It Va bsize The .Va bsize element defines the .Nm table bucket size, and is, by default, 4096 bytes. It may be preferable to increase the page size for disk-resident tables and tables with large data items. .It Va ffactor The .Va ffactor element indicates a desired density within the .Nm table. It is an approximation of the number of keys allowed to accumulate in any one bucket, determining when the .Nm table grows or shrinks. The default value is 8. .It Va nelem The .Va nelem element is an estimate of the final size of the .Nm table. If not set or set too low, .Nm tables will expand gracefully as keys are entered, although a slight performance degradation may be noticed. The default value is 1. .It Va cachesize A suggested maximum size, in bytes, of the memory cache. This value is .Em only advisory, and the access method will allocate more memory rather than fail. .It Va hash The .Va hash element is a user defined .Nm function. Since no .Nm function performs equally well on all possible data, the user may find that the built-in .Nm function does poorly on a particular data set. User specified .Nm functions must take two arguments (a pointer to a byte string and a length) and return a 32-bit quantity to be used as the .Nm value. .It Va lorder The byte order for integers in the stored database metadata. The number should represent the order as an integer; for example, big endian order would be the number 4,321. If .Va lorder is 0 (no order is specified) the current host order is used. If the file already exists, the specified value is ignored and the value specified when the tree was created is used. .El .Pp If the file already exists (and the .Dv O_TRUNC flag is not specified), the values specified for the .Va bsize , ffactor , lorder and .Va nelem arguments are ignored and the values specified when the tree was created are used. .Pp If a .Nm function is specified, .Fn hash_open will attempt to determine if the .Nm function specified is the same as the one with which the database was created, and will fail if it is not. .Pp Backward compatible interfaces to the older .Em dbm and .Em ndbm routines are provided, however these interfaces are not compatible with previous file formats. .Sh ERRORS The .Nm access method routines may fail and set .Va errno for any of the errors specified for the library routine .Xr dbopen 3 . .Sh SEE ALSO .Xr btree 3 , .Xr dbopen 3 , .Xr mpool 3 , .Xr recno 3 .Rs .%T "Dynamic Hash Tables" .%A Per-Ake Larson .%R "Communications of the ACM" .%D April 1988 .Re .Rs .%T "A New Hash Package for UNIX" .%A Margo Seltzer .%R "USENIX Proceedings" .%D Winter 1991 .Re .Sh BUGS Only big and little endian byte order is supported. Index: stable/9/lib/libc/gen/arc4random.3 =================================================================== --- stable/9/lib/libc/gen/arc4random.3 (revision 290886) +++ stable/9/lib/libc/gen/arc4random.3 (revision 290887) @@ -1,127 +1,127 @@ .\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $ .\" Copyright 1997 Niels Provos .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Niels Provos. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Manual page, using -mandoc macros .\" $FreeBSD$ .\" .Dd April 15, 1997 .Dt ARC4RANDOM 3 .Os .Sh NAME .Nm arc4random , .Nm arc4random_buf , .Nm arc4random_uniform , .Nm arc4random_stir , .Nm arc4random_addrandom .Nd arc4 random number generator .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h -.Ft u_int32_t +.Ft uint32_t .Fn arc4random "void" .Ft void .Fn arc4random_buf "void *buf" "size_t nbytes" -.Ft u_int32_t -.Fn arc4random_uniform "u_int32_t upper_bound" +.Ft uint32_t +.Fn arc4random_uniform "uint32_t upper_bound" .Ft void .Fn arc4random_stir "void" .Ft void .Fn arc4random_addrandom "unsigned char *dat" "int datlen" .Sh DESCRIPTION The .Fn arc4random function uses the key stream generator employed by the arc4 cipher, which uses 8*8 8 bit S-Boxes. The S-Boxes can be in about .if t 2\u\s71700\s10\d .if n (2**1700) states. The .Fn arc4random function returns pseudo-random numbers in the range of 0 to .if t 2\u\s731\s10\d\(mi1, .if n (2**32)\(mi1, and therefore has twice the range of .Xr rand 3 and .Xr random 3 . .Pp .Fn arc4random_buf function fills the region .Fa buf of length .Fa nbytes with ARC4-derived random data. .Pp .Fn arc4random_uniform will return a uniformly distributed random number less than .Fa upper_bound . .Fn arc4random_uniform is recommended over constructions like .Dq Li arc4random() % upper_bound as it avoids "modulo bias" when the upper bound is not a power of two. .Pp The .Fn arc4random_stir function reads data from .Pa /dev/urandom and uses it to permute the S-Boxes via .Fn arc4random_addrandom . .Pp There is no need to call .Fn arc4random_stir before using .Fn arc4random functions family, since they automatically initialize themselves. .Sh EXAMPLES The following produces a drop-in replacement for the traditional .Fn rand and .Fn random functions using .Fn arc4random : .Pp .Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))" .Sh SEE ALSO .Xr rand 3 , .Xr random 3 , .Xr srandomdev 3 .Sh HISTORY .Pa RC4 has been designed by RSA Data Security, Inc. It was posted anonymously to the USENET and was confirmed to be equivalent by several sources who had access to the original cipher. Since .Pa RC4 used to be a trade secret, the cipher is now referred to as .Pa ARC4 . Index: stable/9/lib/libc/net/nsdispatch.3 =================================================================== --- stable/9/lib/libc/net/nsdispatch.3 (revision 290886) +++ stable/9/lib/libc/net/nsdispatch.3 (revision 290887) @@ -1,259 +1,259 @@ .\" $NetBSD: nsdispatch.3,v 1.8 1999/03/22 19:44:53 garbled Exp $ .\" .\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Luke Mewburn. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 4, 2010 .Dt NSDISPATCH 3 .Os .Sh NAME .Nm nsdispatch .Nd name-service switch dispatcher routine .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In stdarg.h .In nsswitch.h .Ft int .Fo nsdispatch .Fa "void *retval" .Fa "const ns_dtab dtab[]" .Fa "const char *database" .Fa "const char *method_name" .Fa "const ns_src defaults[]" .Fa "..." .Fc .Sh DESCRIPTION The .Fn nsdispatch function invokes the methods specified in .Va dtab in the order given by .Xr nsswitch.conf 5 for the database .Va database until a successful entry is found. .Pp .Va retval is passed to each method to modify as necessary, to pass back results to the caller of .Fn nsdispatch . .Pp Each method has the function signature described by the typedef: .Pp .Ft typedef int .Fn \*(lp*nss_method\*(rp "void *retval" "void *mdata" "va_list *ap" ; .Pp .Va dtab is an array of .Va ns_dtab structures, which have the following format: .Bd -literal -offset indent typedef struct _ns_dtab { const char *src; nss_method method; void *mdata; } ns_dtab; .Ed .Bd -ragged -offset indent The .Fa dtab array should consist of one entry for each source type that is implemented, with .Va src as the name of the source, .Va method as a function which handles that source, and .Va mdata as a handle on arbitrary data to be passed to the method. The last entry in .Va dtab should contain .Dv NULL values for .Va src , .Va method , and .Va mdata . .Ed .Pp Additionally, methods may be implemented in NSS modules, in which case they are selected using the .Fa database and .Fa method_name arguments along with the configured source. (The methods supplied via .Fa dtab take priority over those implemented in NSS modules in the event of a conflict.) .Pp .Va defaults contains a list of default sources to try if .Xr nsswitch.conf 5 is missing or corrupted, or if there is no relevant entry for .Va database . It is an array of .Va ns_src structures, which have the following format: .Bd -literal -offset indent typedef struct _ns_src { const char *src; - u_int32_t flags; + uint32_t flags; } ns_src; .Ed .Bd -ragged -offset indent The .Fa defaults array should consist of one entry for each source to be configured by default indicated by .Va src , and .Va flags set to the criterion desired (usually .Dv NS_SUCCESS ; refer to .Sx Method return values for more information). The last entry in .Va defaults should have .Va src set to .Dv NULL and .Va flags set to 0. .Pp For convenience, a global variable defined as: .Dl extern const ns_src __nsdefaultsrc[]; exists which contains a single default entry for the source .Sq files that may be used by callers which do not require complicated default rules. .Ed .Pp .Sq Va ... are optional extra arguments, which are passed to the appropriate method as a variable argument list of the type .Vt va_list . .Ss Valid source types While there is support for arbitrary sources, the following #defines for commonly implemented sources are available: .Bl -column NSSRC_COMPAT compat -offset indent .It Sy "#define value" .It Dv NSSRC_FILES Ta """files"" .It Dv NSSRC_DB Ta """db"" .It Dv NSSRC_DNS Ta """dns"" .It Dv NSSRC_NIS Ta """nis"" .It Dv NSSRC_COMPAT Ta """compat"" .El .Pp Refer to .Xr nsswitch.conf 5 for a complete description of what each source type is. .Pp .Ss Method return values The .Vt nss_method functions must return one of the following values depending upon status of the lookup: .Bl -column "Return value" "Status code" .It Sy "Return value Status code" .It Dv NS_SUCCESS Ta success .It Dv NS_NOTFOUND Ta notfound .It Dv NS_UNAVAIL Ta unavail .It Dv NS_TRYAGAIN Ta tryagain .It Dv NS_RETURN Ta -none- .El .Pp Refer to .Xr nsswitch.conf 5 for a complete description of each status code. .Pp The .Fn nsdispatch function returns the value of the method that caused the dispatcher to terminate, or .Dv NS_NOTFOUND otherwise. .Sh NOTES .Fx Ns 's .Lb libc provides stubs for compatibility with NSS modules written for the .Tn GNU C Library .Nm nsswitch interface. However, these stubs only support the use of the .Dq Li passwd and .Dq Li group databases. .Sh SEE ALSO .Xr hesiod 3 , .Xr stdarg 3 , .Xr nsswitch.conf 5 , .Xr yp 8 .Sh HISTORY The .Fn nsdispatch function first appeared in .Fx 5.0 . It was imported from the .Nx Project, where it appeared first in .Nx 1.4 . Support for NSS modules first appeared in .Fx 5.1 . .Sh AUTHORS Luke Mewburn .Aq lukem@netbsd.org wrote this freely-distributable name-service switch implementation, using ideas from the .Tn ULTRIX svc.conf(5) and .Tn Solaris nsswitch.conf(4) manual pages. The .Fx Project added the support for threads and NSS modules, and normalized the uses of .Fn nsdispatch within the standard C library. Index: stable/9/lib/libc/rpc/rpc.3 =================================================================== --- stable/9/lib/libc/rpc/rpc.3 (revision 290886) +++ stable/9/lib/libc/rpc/rpc.3 (revision 290887) @@ -1,517 +1,517 @@ .\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4 .\" Copyright 1989 AT&T .\" $NetBSD: rpc.3,v 1.10 2000/06/02 23:11:12 fvdl Exp $ .\" $FreeBSD$ .Dd May 7, 1993 .Dt RPC 3 .Os .Sh NAME .Nm rpc .Nd library routines for remote procedure calls .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In rpc/rpc.h .In netconfig.h .Sh DESCRIPTION These routines allow C language programs to make procedure calls on other machines across a network. First, the client sends a request to the server. On receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. .Pp All RPC routines require the header .In rpc/rpc.h . Routines that take a .Vt "struct netconfig" also require that .In netconfig.h be included. .Sh Nettype Some of the high-level RPC interface routines take a .Fa nettype string as one of the arguments (for example, .Fn clnt_create , .Fn svc_create , .Fn rpc_reg , .Fn rpc_call ) . This string defines a class of transports which can be used for a particular application. .Pp The .Fa nettype argument can be one of the following: .Bl -tag -width datagram_v .It netpath Choose from the transports which have been indicated by their token names in the .Ev NETPATH environment variable. .Ev NETPATH is unset or .Dv NULL , it defaults to .Qq visible . .Qq netpath is the default .Fa nettype . .It visible Choose the transports which have the visible flag (v) set in the .Pa /etc/netconfig file. .It circuit_v This is same as .Qq visible except that it chooses only the connection oriented transports (semantics .Qq tpi_cots or .Qq tpi_cots_ord ) from the entries in the .Pa /etc/netconfig file. .It datagram_v This is same as .Qq visible except that it chooses only the connectionless datagram transports (semantics .Qq tpi_clts ) from the entries in the .Pa /etc/netconfig file. .It circuit_n This is same as .Qq netpath except that it chooses only the connection oriented datagram transports (semantics .Qq tpi_cots or .Qq tpi_cots_ord ) . .It datagram_n This is same as .Qq netpath except that it chooses only the connectionless datagram transports (semantics .Qq tpi_clts ) . .It udp This refers to Internet UDP, both version 4 and 6. .It tcp This refers to Internet TCP, both version 4 and 6. .El .Pp If .Fa nettype is .Dv NULL , it defaults to .Qq netpath . The transports are tried in left to right order in the .Ev NETPATH variable or in top to down order in the .Pa /etc/netconfig file. .Sh Derived Types The derived types used in the RPC interfaces are defined as follows: .Bd -literal - typedef u_int32_t rpcprog_t; - typedef u_int32_t rpcvers_t; - typedef u_int32_t rpcproc_t; - typedef u_int32_t rpcprot_t; - typedef u_int32_t rpcport_t; - typedef int32_t rpc_inline_t; + typedef uint32_t rpcprog_t; + typedef uint32_t rpcvers_t; + typedef uint32_t rpcproc_t; + typedef uint32_t rpcprot_t; + typedef uint32_t rpcport_t; + typedef int32_t rpc_inline_t; .Ed .Sh "Data Structures" Some of the data structures used by the RPC package are shown below. .Sh "The AUTH Structure" .Bd -literal /* * Authentication info. Opaque to client. */ struct opaque_auth { enum_t oa_flavor; /* flavor of auth */ caddr_t oa_base; /* address of more auth stuff */ u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ }; /* * Auth handle, interface to client side authenticators. */ typedef struct { struct opaque_auth ah_cred; struct opaque_auth ah_verf; struct auth_ops { void (*ah_nextverf)(\|); int (*ah_marshal)(\|); /* nextverf & serialize */ int (*ah_validate)(\|); /* validate verifier */ int (*ah_refresh)(\|); /* refresh credentials */ void (*ah_destroy)(\|); /* destroy this structure */ } *ah_ops; caddr_t ah_private; } AUTH; .Ed .Sh "The CLIENT Structure" .Bd -literal /* * Client rpc handle. * Created by individual implementations. * Client is responsible for initializing auth. */ typedef struct { AUTH *cl_auth; /* authenticator */ struct clnt_ops { enum clnt_stat (*cl_call)(); /* call remote procedure */ void (*cl_abort)(); /* abort a call */ void (*cl_geterr)(); /* get specific error code */ bool_t (*cl_freeres)(); /* frees results */ void (*cl_destroy)(); /* destroy this structure */ bool_t (*cl_control)(); /* the ioctl() of rpc */ } *cl_ops; caddr_t cl_private; /* private stuff */ char *cl_netid; /* network identifier */ char *cl_tp; /* device name */ } CLIENT; .Ed .Sh "The SVCXPRT structure" .Bd -literal enum xprt_stat { XPRT_DIED, XPRT_MOREREQS, XPRT_IDLE }; /* * Server side transport handle */ typedef struct { int xp_fd; /* file descriptor for the server handle */ u_short xp_port; /* obsolete */ const struct xp_ops { bool_t (*xp_recv)(); /* receive incoming requests */ enum xprt_stat (*xp_stat)(); /* get transport status */ bool_t (*xp_getargs)(); /* get arguments */ bool_t (*xp_reply)(); /* send reply */ bool_t (*xp_freeargs)(); /* free mem allocated for args */ void (*xp_destroy)(); /* destroy this struct */ } *xp_ops; int xp_addrlen; /* length of remote addr. Obsolete */ struct sockaddr_in xp_raddr; /* Obsolete */ const struct xp_ops2 { bool_t (*xp_control)(); /* catch-all function */ } *xp_ops2; char *xp_tp; /* transport provider device name */ char *xp_netid; /* network identifier */ struct netbuf xp_ltaddr; /* local transport address */ struct netbuf xp_rtaddr; /* remote transport address */ struct opaque_auth xp_verf; /* raw response verifier */ caddr_t xp_p1; /* private: for use by svc ops */ caddr_t xp_p2; /* private: for use by svc ops */ caddr_t xp_p3; /* private: for use by svc lib */ int xp_type /* transport type */ } SVCXPRT; .Ed .Sh "The svc_reg structure" .Bd -literal struct svc_req { rpcprog_t rq_prog; /* service program number */ rpcvers_t rq_vers; /* service protocol version */ rpcproc_t rq_proc; /* the desired procedure */ struct opaque_auth rq_cred; /* raw creds from the wire */ caddr_t rq_clntcred; /* read only cooked cred */ SVCXPRT *rq_xprt; /* associated transport */ }; .Ed .Sh "The XDR structure" .Bd -literal /* * XDR operations. * XDR_ENCODE causes the type to be encoded into the stream. * XDR_DECODE causes the type to be extracted from the stream. * XDR_FREE can be used to release the space allocated by an XDR_DECODE * request. */ enum xdr_op { XDR_ENCODE=0, XDR_DECODE=1, XDR_FREE=2 }; /* * This is the number of bytes per unit of external data. */ #define BYTES_PER_XDR_UNIT (4) #define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) / BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT) /* * A xdrproc_t exists for each data type which is to be encoded or * decoded. The second argument to the xdrproc_t is a pointer to * an opaque pointer. The opaque pointer generally points to a * structure of the data type to be decoded. If this points to 0, * then the type routines should allocate dynamic storage of the * appropriate size and return it. * bool_t (*xdrproc_t)(XDR *, caddr_t *); */ typedef bool_t (*xdrproc_t)(); /* * The XDR handle. * Contains operation which is being applied to the stream, * an operations vector for the particular implementation */ typedef struct { enum xdr_op x_op; /* operation; fast additional param */ struct xdr_ops { bool_t (*x_getlong)(); /* get a long from underlying stream */ bool_t (*x_putlong)(); /* put a long to underlying stream */ bool_t (*x_getbytes)(); /* get bytes from underlying stream */ bool_t (*x_putbytes)(); /* put bytes to underlying stream */ u_int (*x_getpostn)(); /* returns bytes off from beginning */ bool_t (*x_setpostn)(); /* lets you reposition the stream */ long * (*x_inline)(); /* buf quick ptr to buffered data */ void (*x_destroy)(); /* free privates of this xdr_stream */ } *x_ops; caddr_t x_public; /* users' data */ caddr_t x_private; /* pointer to private data */ caddr_t x_base; /* private used for position info */ u_int x_handy; /* extra private word */ } XDR; /* * The netbuf structure. This structure is defined in on SysV * systems, but NetBSD / FreeBSD do not use XTI. * * Usually, buf will point to a struct sockaddr, and len and maxlen * will contain the length and maximum length of that socket address, * respectively. */ struct netbuf { unsigned int maxlen; unsigned int len; void *buf; }; /* * The format of the address and options arguments of the XTI t_bind call. * Only provided for compatibility, it should not be used other than * as an argument to svc_tli_create(). */ struct t_bind { struct netbuf addr; unsigned int qlen; }; .Ed .Sh "Index to Routines" The following table lists RPC routines and the manual reference pages on which they are described: .Pp .Bl -tag -width "authunix_create_default()" -compact .It Em "RPC Routine" .Em "Manual Reference Page" .Pp .It Fn auth_destroy .Xr rpc_clnt_auth 3 .It Fn authdes_create .Xr rpc_soc 3 .It Fn authnone_create .Xr rpc_clnt_auth 3 .It Fn authsys_create .Xr rpc_clnt_auth 3 .It Fn authsys_create_default .Xr rpc_clnt_auth 3 .It Fn authunix_create .Xr rpc_soc 3 .It Fn authunix_create_default .Xr rpc_soc 3 .It Fn callrpc .Xr rpc_soc 3 .It Fn clnt_broadcast .Xr rpc_soc 3 .It Fn clnt_call .Xr rpc_clnt_calls 3 .It Fn clnt_control .Xr rpc_clnt_create 3 .It Fn clnt_create .Xr rpc_clnt_create 3 .It Fn clnt_create_timed .Xr rpc_clnt_create 3 .It Fn clnt_create_vers .Xr rpc_clnt_create 3 .It Fn clnt_create_vers_timed .Xr rpc_clnt_create 3 .It Fn clnt_destroy .Xr rpc_clnt_create 3 .It Fn clnt_dg_create .Xr rpc_clnt_create 3 .It Fn clnt_freeres .Xr rpc_clnt_calls 3 .It Fn clnt_geterr .Xr rpc_clnt_calls 3 .It Fn clnt_pcreateerror .Xr rpc_clnt_create 3 .It Fn clnt_perrno .Xr rpc_clnt_calls 3 .It Fn clnt_perror .Xr rpc_clnt_calls 3 .It Fn clnt_raw_create .Xr rpc_clnt_create 3 .It Fn clnt_spcreateerror .Xr rpc_clnt_create 3 .It Fn clnt_sperrno .Xr rpc_clnt_calls 3 .It Fn clnt_sperror .Xr rpc_clnt_calls 3 .It Fn clnt_tli_create .Xr rpc_clnt_create 3 .It Fn clnt_tp_create .Xr rpc_clnt_create 3 .It Fn clnt_tp_create_timed .Xr rpc_clnt_create 3 .It Fn clnt_udpcreate .Xr rpc_soc 3 .It Fn clnt_vc_create .Xr rpc_clnt_create 3 .It Fn clntraw_create .Xr rpc_soc 3 .It Fn clnttcp_create .Xr rpc_soc 3 .It Fn clntudp_bufcreate .Xr rpc_soc 3 .It Fn get_myaddress .Xr rpc_soc 3 .It Fn pmap_getmaps .Xr rpc_soc 3 .It Fn pmap_getport .Xr rpc_soc 3 .It Fn pmap_rmtcall .Xr rpc_soc 3 .It Fn pmap_set .Xr rpc_soc 3 .It Fn pmap_unset .Xr rpc_soc 3 .It Fn registerrpc .Xr rpc_soc 3 .It Fn rpc_broadcast .Xr rpc_clnt_calls 3 .It Fn rpc_broadcast_exp .Xr rpc_clnt_calls 3 .It Fn rpc_call .Xr rpc_clnt_calls 3 .It Fn rpc_reg .Xr rpc_svc_calls 3 .It Fn svc_create .Xr rpc_svc_create 3 .It Fn svc_destroy .Xr rpc_svc_create 3 .It Fn svc_dg_create .Xr rpc_svc_create 3 .It Fn svc_dg_enablecache .Xr rpc_svc_calls 3 .It Fn svc_fd_create .Xr rpc_svc_create 3 .It Fn svc_fds .Xr rpc_soc 3 .It Fn svc_freeargs .Xr rpc_svc_reg 3 .It Fn svc_getargs .Xr rpc_svc_reg 3 .It Fn svc_getcaller .Xr rpc_soc 3 .It Fn svc_getreq .Xr rpc_soc 3 .It Fn svc_getreqset .Xr rpc_svc_calls 3 .It Fn svc_getrpccaller .Xr rpc_svc_calls 3 .It Fn svc_kerb_reg .Xr kerberos_rpc 3 .It Fn svc_raw_create .Xr rpc_svc_create 3 .It Fn svc_reg .Xr rpc_svc_calls 3 .It Fn svc_register .Xr rpc_soc 3 .It Fn svc_run .Xr rpc_svc_reg 3 .It Fn svc_sendreply .Xr rpc_svc_reg 3 .It Fn svc_tli_create .Xr rpc_svc_create 3 .It Fn svc_tp_create .Xr rpc_svc_create 3 .It Fn svc_unreg .Xr rpc_svc_calls 3 .It Fn svc_unregister .Xr rpc_soc 3 .It Fn svc_vc_create .Xr rpc_svc_create 3 .It Fn svcerr_auth .Xr rpc_svc_err 3 .It Fn svcerr_decode .Xr rpc_svc_err 3 .It Fn svcerr_noproc .Xr rpc_svc_err 3 .It Fn svcerr_noprog .Xr rpc_svc_err 3 .It Fn svcerr_progvers .Xr rpc_svc_err 3 .It Fn svcerr_systemerr .Xr rpc_svc_err 3 .It Fn svcerr_weakauth .Xr rpc_svc_err 3 .It Fn svcfd_create .Xr rpc_soc 3 .It Fn svcraw_create .Xr rpc_soc 3 .It Fn svctcp_create .Xr rpc_soc 3 .It Fn svcudp_bufcreate .Xr rpc_soc 3 .It Fn svcudp_create .Xr rpc_soc 3 .It Fn xdr_accepted_reply .Xr rpc_xdr 3 .It Fn xdr_authsys_parms .Xr rpc_xdr 3 .It Fn xdr_authunix_parms .Xr rpc_soc 3 .It Fn xdr_callhdr .Xr rpc_xdr 3 .It Fn xdr_callmsg .Xr rpc_xdr 3 .It Fn xdr_opaque_auth .Xr rpc_xdr 3 .It Fn xdr_rejected_reply .Xr rpc_xdr 3 .It Fn xdr_replymsg .Xr rpc_xdr 3 .It Fn xprt_register .Xr rpc_svc_calls 3 .It Fn xprt_unregister .Xr rpc_svc_calls 3 .El .Sh FILES .Bl -tag -width /etc/netconfig .It Pa /etc/netconfig .El .Sh SEE ALSO .Xr getnetconfig 3 , .Xr getnetpath 3 , .Xr rpcbind 3 , .Xr rpc_clnt_auth 3 , .Xr rpc_clnt_calls 3 , .Xr rpc_clnt_create 3 , .Xr rpc_svc_calls 3 , .Xr rpc_svc_create 3 , .Xr rpc_svc_err 3 , .Xr rpc_svc_reg 3 , .Xr rpc_xdr 3 , .Xr xdr 3 , .Xr netconfig 5 Index: stable/9/lib/libc/rpc/rpc_clnt_create.3 =================================================================== --- stable/9/lib/libc/rpc/rpc_clnt_create.3 (revision 290886) +++ stable/9/lib/libc/rpc/rpc_clnt_create.3 (revision 290887) @@ -1,514 +1,514 @@ .\" @(#)rpc_clnt_create.3n 1.36 93/08/31 SMI; from SVr4 .\" Copyright 1989 AT&T .\" @(#)rpc_clnt_create 1.5 89/07/24 SMI; .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. .\" $NetBSD: rpc_clnt_create.3,v 1.2 2000/06/20 00:53:08 fvdl Exp $ .\" $FreeBSD$ .Dd May 7, 1993 .Dt RPC_CLNT_CREATE 3 .Os .Sh NAME .Nm rpc_clnt_create , .Nm clnt_control , .Nm clnt_create , .Nm clnt_create_timed , .Nm clnt_create_vers , .Nm clnt_create_vers_timed , .Nm clnt_destroy , .Nm clnt_dg_create , .Nm clnt_pcreateerror , .Nm clnt_raw_create , .Nm clnt_spcreateerror , .Nm clnt_tli_create , .Nm clnt_tp_create , .Nm clnt_tp_create_timed , .Nm clnt_vc_create , .Nm rpc_createerr .Nd "library routines for dealing with creation and manipulation of" .Vt CLIENT handles .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In rpc/rpc.h .Ft bool_t .Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info" .Ft "CLIENT *" .Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" .Ft "CLIENT *" .Fn clnt_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" "const struct timeval *timeout" .Ft "CLIENT *" .Fn clnt_create_vers "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype" .Ft "CLIENT *" .Fn clnt_create_vers_timed "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype" "const struct timeval *timeout" .Ft void .Fn clnt_destroy "CLIENT *clnt" .Ft "CLIENT *" .Fn clnt_dg_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz" .Ft void .Fn clnt_pcreateerror "const char *s" .Ft "char *" .Fn clnt_spcreateerror "const char *s" .Ft "CLIENT *" .Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum" .Ft "CLIENT *" .Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz" .Ft "CLIENT *" .Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" .Ft "CLIENT *" .Fn clnt_tp_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct timeval *timeout" .Ft "CLIENT *" .Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "u_int sendsz" "u_int recvsz" .Sh DESCRIPTION RPC library routines allow C language programs to make procedure calls on other machines across the network. First a .Vt CLIENT handle is created and then the client calls a procedure to send a request to the server. On receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends a reply. .Sh Routines .Bl -tag -width YYYYYYY .It Fn clnt_control A function macro to change or retrieve various information about a client object. The .Fa req argument indicates the type of operation, and .Fa info is a pointer to the information. For both connectionless and connection-oriented transports, the supported values of .Fa req and their argument types and what they do are: .Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout" .It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout" .It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout" .El .Pp Note: if you set the timeout using .Fn clnt_control , the timeout argument passed by .Fn clnt_call is ignored in all subsequent calls. .Pp Note: If you set the timeout value to 0, .Fn clnt_control immediately returns an error .Pq Dv RPC_TIMEDOUT . Set the timeout argument to 0 for batching calls. .Bl -column CLSET_FD_NCLOSE "struct timeval *" .It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address" .It Dv CLGET_FD Ta "int *" Ta "get fd from handle" .It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy" .It Dv CLSET_FD_NCLOSE Ta void Ta "do not close fd on destroy" -.It Dv CLGET_VERS Ta "u_int32_t *" Ta "get RPC program version" -.It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version" -.It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call" -.It Dv CLSET_XID Ta "u_int32_t *" Ta "set XID of next call" +.It Dv CLGET_VERS Ta "uint32_t *" Ta "get RPC program version" +.It Dv CLSET_VERS Ta "uint32_t *" Ta "set RPC program version" +.It Dv CLGET_XID Ta "uint32_t *" Ta "get XID of previous call" +.It Dv CLSET_XID Ta "uint32_t *" Ta "set XID of next call" .El .Pp The following operations are valid for connectionless transports only: .Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout" .It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout" .It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout" .It Dv CLSET_CONNECT Ta Vt "int *" Ta use Xr connect 2 .El .Pp The retry timeout is the time that RPC waits for the server to reply before retransmitting the request. The .Fn clnt_control function returns .Dv TRUE on success and .Dv FALSE on failure. .It Fn clnt_create Generic client creation routine for program .Fa prognum and version .Fa versnum . The .Fa host argument identifies the name of the remote host where the server is located. The .Fa nettype argument indicates the class of transport protocol to use. The transports are tried in left to right order in .Ev NETPATH environment variable or in top to bottom order in the netconfig database. The .Fn clnt_create function tries all the transports of the .Fa nettype class available from the .Ev NETPATH environment variable and the netconfig database, and chooses the first successful one. A default timeout is set and can be modified using .Fn clnt_control . This routine returns .Dv NULL if it fails. The .Fn clnt_pcreateerror routine can be used to print the reason for failure. .Pp Note: .Fn clnt_create returns a valid client handle even if the particular version number supplied to .Fn clnt_create is not registered with the .Xr rpcbind 8 service. This mismatch will be discovered by a .Fn clnt_call later (see .Xr rpc_clnt_calls 3 ) . .It Fn clnt_create_timed Generic client creation routine which is similar to .Fn clnt_create but which also has the additional argument .Fa timeout that specifies the maximum amount of time allowed for each transport class tried. In all other respects, the .Fn clnt_create_timed call behaves exactly like the .Fn clnt_create call. .It Fn clnt_create_vers Generic client creation routine which is similar to .Fn clnt_create but which also checks for the version availability. The .Fa host argument identifies the name of the remote host where the server is located. The .Fa nettype argument indicates the class transport protocols to be used. If the routine is successful it returns a client handle created for the highest version between .Fa vers_low and .Fa vers_high that is supported by the server. The .Fa vers_outp argument is set to this value. That is, after a successful return .Fa vers_low <= .Fa *vers_outp <= .Fa vers_high . If no version between .Fa vers_low and .Fa vers_high is supported by the server then the routine fails and returns .Dv NULL . A default timeout is set and can be modified using .Fn clnt_control . This routine returns .Dv NULL if it fails. The .Fn clnt_pcreateerror routine can be used to print the reason for failure. Note: .Fn clnt_create returns a valid client handle even if the particular version number supplied to .Fn clnt_create is not registered with the .Xr rpcbind 8 service. This mismatch will be discovered by a .Fn clnt_call later (see .Xr rpc_clnt_calls 3 ) . However, .Fn clnt_create_vers does this for you and returns a valid handle only if a version within the range supplied is supported by the server. .It Fn clnt_create_vers_timed Generic client creation routine which is similar to .Fn clnt_create_vers but which also has the additional argument .Fa timeout that specifies the maximum amount of time allowed for each transport class tried. In all other respects, the .Fn clnt_create_vers_timed call behaves exactly like the .Fn clnt_create_vers call. .It Fn clnt_destroy A function macro that destroys the client's RPC handle. Destruction usually involves deallocation of private data structures, including .Fa clnt itself. Use of .Fa clnt is undefined after calling .Fn clnt_destroy . If the RPC library opened the associated file descriptor, or .Dv CLSET_FD_CLOSE was set using .Fn clnt_control , the file descriptor will be closed. The caller should call .Fn auth_destroy "clnt->cl_auth" (before calling .Fn clnt_destroy ) to destroy the associated .Vt AUTH structure (see .Xr rpc_clnt_auth 3 ) . .It Fn clnt_dg_create This routine creates an RPC client for the remote program .Fa prognum and version .Fa versnum ; the client uses a connectionless transport. The remote program is located at address .Fa svcaddr . The .Fa fildes argument is an open and bound file descriptor. This routine will resend the call message in intervals of 15 seconds until a response is received or until the call times out. The total time for the call to time out is specified by .Fn clnt_call (see .Fn clnt_call in .Xr rpc_clnt_calls 3 ) . The retry time out and the total time out periods can be changed using .Fn clnt_control . The user may set the size of the send and receive buffers with the .Fa sendsz and .Fa recvsz arguments; values of 0 choose suitable defaults. This routine returns .Dv NULL if it fails. .It Fn clnt_pcreateerror Print a message to standard error indicating why a client RPC handle could not be created. The message is prepended with the string .Fa s and a colon, and appended with a newline. .It Fn clnt_spcreateerror Like .Fn clnt_pcreateerror , except that it returns a string instead of printing to the standard error. A newline is not appended to the message in this case. Warning: returns a pointer to a buffer that is overwritten on each call. .It Fn clnt_raw_create This routine creates an RPC client handle for the remote program .Fa prognum and version .Fa versnum . The transport used to pass messages to the service is a buffer within the process's address space, so the corresponding RPC server should live in the same address space; (see .Fn svc_raw_create in .Xr rpc_svc_create 3 ) . This allows simulation of RPC and measurement of RPC overheads, such as round trip times, without any kernel or networking interference. This routine returns .Dv NULL if it fails. The .Fn clnt_raw_create function should be called after .Fn svc_raw_create . .It Fn clnt_tli_create This routine creates an RPC client handle for the remote program .Fa prognum and version .Fa versnum . The remote program is located at address .Fa svcaddr . If .Fa svcaddr is .Dv NULL and it is connection-oriented, it is assumed that the file descriptor is connected. For connectionless transports, if .Fa svcaddr is .Dv NULL , .Dv RPC_UNKNOWNADDR error is set. The .Fa fildes argument is a file descriptor which may be open, bound and connected. If it is .Dv RPC_ANYFD , it opens a file descriptor on the transport specified by .Fa netconf . If .Fa fildes is .Dv RPC_ANYFD and .Fa netconf is .Dv NULL , a .Dv RPC_UNKNOWNPROTO error is set. If .Fa fildes is unbound, then it will attempt to bind the descriptor. The user may specify the size of the buffers with the .Fa sendsz and .Fa recvsz arguments; values of 0 choose suitable defaults. Depending upon the type of the transport (connection-oriented or connectionless), .Fn clnt_tli_create calls appropriate client creation routines. This routine returns .Dv NULL if it fails. The .Fn clnt_pcreateerror routine can be used to print the reason for failure. The remote rpcbind service (see .Xr rpcbind 8 ) is not consulted for the address of the remote service. .It Fn clnt_tp_create Like .Fn clnt_create except .Fn clnt_tp_create tries only one transport specified through .Fa netconf . The .Fn clnt_tp_create function creates a client handle for the program .Fa prognum , the version .Fa versnum , and for the transport specified by .Fa netconf . Default options are set, which can be changed using .Fn clnt_control calls. The remote rpcbind service on the host .Fa host is consulted for the address of the remote service. This routine returns .Dv NULL if it fails. The .Fn clnt_pcreateerror routine can be used to print the reason for failure. .It Fn clnt_tp_create_timed Like .Fn clnt_tp_create except .Fn clnt_tp_create_timed has the extra argument .Fa timeout which specifies the maximum time allowed for the creation attempt to succeed. In all other respects, the .Fn clnt_tp_create_timed call behaves exactly like the .Fn clnt_tp_create call. .It Fn clnt_vc_create This routine creates an RPC client for the remote program .Fa prognum and version .Fa versnum ; the client uses a connection-oriented transport. The remote program is located at address .Fa svcaddr . The .Fa fildes argument is an open and bound file descriptor. The user may specify the size of the send and receive buffers with the .Fa sendsz and .Fa recvsz arguments; values of 0 choose suitable defaults. This routine returns .Dv NULL if it fails. The address .Fa svcaddr should not be .Dv NULL and should point to the actual address of the remote program. The .Fn clnt_vc_create function does not consult the remote rpcbind service for this information. .It Xo .Vt "struct rpc_createerr" Va rpc_createerr ; .Xc A global variable whose value is set by any RPC client handle creation routine that fails. It is used by the routine .Fn clnt_pcreateerror to print the reason for the failure. .El .Sh SEE ALSO .Xr rpc 3 , .Xr rpc_clnt_auth 3 , .Xr rpc_clnt_calls 3 , .Xr rpcbind 8 Index: stable/9/lib/libc/sys/getdirentries.2 =================================================================== --- stable/9/lib/libc/sys/getdirentries.2 (revision 290886) +++ stable/9/lib/libc/sys/getdirentries.2 (revision 290887) @@ -1,185 +1,185 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 .\" $FreeBSD$ .\" .Dd May 3, 1995 .Dt GETDIRENTRIES 2 .Os .Sh NAME .Nm getdirentries , .Nm getdents .Nd "get directory entries in a file system independent format" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In dirent.h .Ft int .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" .Ft int .Fn getdents "int fd" "char *buf" "int nbytes" .Sh DESCRIPTION The .Fn getdirentries and .Fn getdents system calls read directory entries from the directory referenced by the file descriptor .Fa fd into the buffer pointed to by .Fa buf , in a file system independent format. Up to .Fa nbytes of data will be transferred. The .Fa nbytes argument must be greater than or equal to the block size associated with the file, see .Xr stat 2 . Some file systems may not support these system calls with buffers smaller than this size. .Pp The data in the buffer is a series of .Vt dirent structures each containing the following entries: .Bd -literal -offset indent -u_int32_t d_fileno; -u_int16_t d_reclen; -u_int8_t d_type; -u_int8_t d_namlen; +uint32_t d_fileno; +uint16_t d_reclen; +uint8_t d_type; +uint8_t d_namlen; char d_name[MAXNAMELEN + 1]; /* see below */ .Ed .Pp The .Fa d_fileno entry is a number which is unique for each distinct file in the file system. Files that are linked by hard links (see .Xr link 2 ) have the same .Fa d_fileno . The .Fa d_reclen entry is the length, in bytes, of the directory record. The .Fa d_type entry is the type of the file pointed to by the directory record. The file type values are defined in .Fa . The .Fa d_name entry contains a null terminated file name. The .Fa d_namlen entry specifies the length of the file name excluding the null byte. Thus the actual size of .Fa d_name may vary from 1 to .Dv MAXNAMELEN \&+ 1. .Pp Entries may be separated by extra space. The .Fa d_reclen entry may be used as an offset from the start of a .Fa dirent structure to the next structure, if any. .Pp The actual number of bytes transferred is returned. The current position pointer associated with .Fa fd is set to point to the next block of entries. The pointer may not advance by the number of bytes returned by .Fn getdirentries or .Fn getdents . A value of zero is returned when the end of the directory has been reached. .Pp The .Fn getdirentries system call writes the position of the block read into the location pointed to by .Fa basep . Alternatively, the current position pointer may be set and retrieved by .Xr lseek 2 . The current position pointer should only be set to a value returned by .Xr lseek 2 , a value returned in the location pointed to by .Fa basep .Fn ( getdirentries only) or zero. .Sh RETURN VALUES If successful, the number of bytes actually transferred is returned. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn getdirentries system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid file descriptor open for reading. .It Bq Er EFAULT Either .Fa buf or .Fa basep point outside the allocated address space. .It Bq Er EINVAL The file referenced by .Fa fd is not a directory, or .Fa nbytes is too small for returning a directory entry or block of entries, or the current position pointer is invalid. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO .Xr lseek 2 , .Xr open 2 .Sh HISTORY The .Fn getdirentries system call first appeared in .Bx 4.4 . The .Fn getdents system call first appeared in .Fx 3.0 . Index: stable/9/lib/libc/sys/nfssvc.2 =================================================================== --- stable/9/lib/libc/sys/nfssvc.2 (revision 290886) +++ stable/9/lib/libc/sys/nfssvc.2 (revision 290887) @@ -1,258 +1,258 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)nfssvc.2 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" .Dd June 9, 1993 .Dt NFSSVC 2 .Os .Sh NAME .Nm nfssvc .Nd NFS services .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In sys/time.h .In nfs/rpcv2.h .In nfsserver/nfs.h .In unistd.h .Ft int .Fn nfssvc "int flags" "void *argstructp" .Sh DESCRIPTION The .Fn nfssvc system call is used by the NFS daemons to pass information into and out of the kernel and also to enter the kernel as a server daemon. The .Fa flags argument consists of several bits that show what action is to be taken once in the kernel and the .Fa argstructp points to one of three structures depending on which bits are set in flags. .Pp On the client side, .Xr nfsiod 8 calls .Fn nfssvc with the .Fa flags argument set to .Dv NFSSVC_BIOD and .Fa argstructp set to .Dv NULL to enter the kernel as a block I/O server daemon. For .Tn NQNFS , .Xr mount_nfs 8 calls .Fn nfssvc with the .Dv NFSSVC_MNTD flag, optionally or'd with the flags .Dv NFSSVC_GOTAUTH and .Dv NFSSVC_AUTHINFAIL along with a pointer to a .Bd -literal struct nfsd_cargs { char *ncd_dirp; /* Mount dir path */ uid_t ncd_authuid; /* Effective uid */ int ncd_authtype; /* Type of authenticator */ int ncd_authlen; /* Length of authenticator string */ u_char *ncd_authstr; /* Authenticator string */ int ncd_verflen; /* and the verifier */ u_char *ncd_verfstr; NFSKERBKEY_T ncd_key; /* Session key */ }; .Ed .Pp structure. The initial call has only the .Dv NFSSVC_MNTD flag set to specify service for the mount point. If the mount point is using Kerberos, then the .Xr mount_nfs 8 utility will return from .Fn nfssvc with .Va errno == .Er ENEEDAUTH whenever the client side requires an ``rcmd'' authentication ticket for the user. The .Xr mount_nfs 8 utility will attempt to get the Kerberos ticket, and if successful will call .Fn nfssvc with the flags .Dv NFSSVC_MNTD and .Dv NFSSVC_GOTAUTH after filling the ticket into the ncd_authstr field and setting the ncd_authlen and ncd_authtype fields of the nfsd_cargs structure. If .Xr mount_nfs 8 failed to get the ticket, .Fn nfssvc will be called with the flags .Dv NFSSVC_MNTD , .Dv NFSSVC_GOTAUTH and .Dv NFSSVC_AUTHINFAIL to denote a failed authentication attempt. .Pp On the server side, .Fn nfssvc is called with the flag .Dv NFSSVC_NFSD and a pointer to a .Bd -literal struct nfsd_srvargs { struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ uid_t nsd_uid; /* Effective uid mapped to cred */ - u_int32_t nsd_haddr; /* Ip address of client */ + uint32_t nsd_haddr; /* Ip address of client */ struct ucred nsd_cr; /* Cred. uid maps to */ int nsd_authlen; /* Length of auth string (ret) */ u_char *nsd_authstr; /* Auth string (ret) */ int nsd_verflen; /* and the verifier */ u_char *nsd_verfstr; struct timeval nsd_timestamp; /* timestamp from verifier */ - u_int32_t nsd_ttl; /* credential ttl (sec) */ + uint32_t nsd_ttl; /* credential ttl (sec) */ NFSKERBKEY_T nsd_key; /* Session key */ }; .Ed .Pp to enter the kernel as an .Xr nfsd 8 daemon. Whenever an .Xr nfsd 8 daemon receives a Kerberos authentication ticket, it will return from .Fn nfssvc with .Va errno == .Er ENEEDAUTH . The .Xr nfsd 8 utility will attempt to authenticate the ticket and generate a set of credentials on the server for the ``user id'' specified in the field nsd_uid. This is done by first authenticating the Kerberos ticket and then mapping the Kerberos principal to a local name and getting a set of credentials for that user via .Xr getpwnam 3 and .Xr getgrouplist 3 . If successful, the .Xr nfsd 8 utility will call .Fn nfssvc with the .Dv NFSSVC_NFSD and .Dv NFSSVC_AUTHIN flags set to pass the credential mapping in nsd_cr into the kernel to be cached on the server socket for that client. If the authentication failed, .Xr nfsd 8 calls .Fn nfssvc with the flags .Dv NFSSVC_NFSD and .Dv NFSSVC_AUTHINFAIL to denote an authentication failure. .Pp The master .Xr nfsd 8 server daemon calls .Fn nfssvc with the flag .Dv NFSSVC_ADDSOCK and a pointer to a .Bd -literal struct nfsd_args { int sock; /* Socket to serve */ caddr_t name; /* Client address for connection based sockets */ int namelen;/* Length of name */ }; .Ed .Pp to pass a server side .Tn NFS socket into the kernel for servicing by the .Xr nfsd 8 daemons. .Sh RETURN VALUES Normally .Fn nfssvc does not return unless the server is terminated by a signal when a value of 0 is returned. Otherwise, -1 is returned and the global variable .Va errno is set to specify the error. .Sh ERRORS .Bl -tag -width Er .It Bq Er ENEEDAUTH This special error value is really used for authentication support, particularly Kerberos, as explained above. .It Bq Er EPERM The caller is not the super-user. .El .Sh SEE ALSO .Xr mount_nfs 8 , .Xr nfsd 8 , .Xr nfsiod 8 .Sh HISTORY The .Fn nfssvc system call first appeared in .Bx 4.4 . .Sh BUGS The .Fn nfssvc system call is designed specifically for the .Tn NFS support daemons and as such is specific to their requirements. It should really return values to indicate the need for authentication support, since .Er ENEEDAUTH is not really an error. Several fields of the argument structures are assumed to be valid and sometimes to be unchanged from a previous call, such that .Fn nfssvc must be used with extreme care. Index: stable/9/lib/libc/sys =================================================================== --- stable/9/lib/libc/sys (revision 290886) +++ stable/9/lib/libc/sys (revision 290887) Property changes on: stable/9/lib/libc/sys ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libc/sys:r231564 Index: stable/9/lib/libc =================================================================== --- stable/9/lib/libc (revision 290886) +++ stable/9/lib/libc (revision 290887) Property changes on: stable/9/lib/libc ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libc:r231564 Index: stable/9/lib/libcam/cam.3 =================================================================== --- stable/9/lib/libcam/cam.3 (revision 290886) +++ stable/9/lib/libcam/cam.3 (revision 290887) @@ -1,425 +1,425 @@ .\" .\" Copyright (c) 1998 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 10, 1998 .Dt CAM 3 .Os .Sh NAME .Nm cam_open_device , .Nm cam_open_spec_device , .Nm cam_open_btl , .Nm cam_open_pass , .Nm cam_close_device , .Nm cam_close_spec_device , .Nm cam_getccb , .Nm cam_send_ccb , .Nm cam_freeccb , .Nm cam_path_string , .Nm cam_device_dup , .Nm cam_device_copy , .Nm cam_get_device .Nd CAM user library .Sh LIBRARY .Lb libcam .Sh SYNOPSIS .In stdio.h .In camlib.h .Ft struct cam_device * .Fo cam_open_device .Fa "const char *path" .Fa "int flags" .Fc .Ft struct cam_device * .Fo cam_open_spec_device .Fa "const char *dev_name" .Fa "int unit" .Fa "int flags" .Fa "struct cam_device *device" .Fc .Ft struct cam_device * .Fo cam_open_btl .Fa "path_id_t path_id" .Fa "target_id_t target_id" .Fa "lun_id_t target_lun" .Fa "int flags" .Fa "struct cam_device *device" .Fc .Ft struct cam_device * .Fo cam_open_pass .Fa "const char *path" .Fa "int flags" .Fa "struct cam_device *device" .Fc .Ft void .Fo cam_close_device .Fa "struct cam_device *dev" .Fc .Ft void .Fo cam_close_spec_device .Fa "struct cam_device *dev" .Fc .Ft union ccb * .Fo cam_getccb .Fa "struct cam_device *dev" .Fc .Ft int .Fo cam_send_ccb .Fa "struct cam_device *device" .Fa "union ccb *ccb" .Fc .Ft void .Fo cam_freeccb .Fa "union ccb *ccb" .Fc .Ft char * .Fo cam_path_string .Fa "struct cam_device *dev" .Fa "char *str" .Fa "int len" .Fc .Ft struct cam_device * .Fo cam_device_dup .Fa "struct cam_device *device" .Fc .Ft void .Fo cam_device_copy .Fa "struct cam_device *src" .Fa "struct cam_device *dst" .Fc .Ft int .Fo cam_get_device .Fa "const char *path" .Fa "char *dev_name" .Fa "int devnamelen" .Fa "int *unit" .Fc .Sh DESCRIPTION The CAM library consists of a number of functions designed to aid in programming with the CAM subsystem. This man page covers the basic set of library functions. More functions are documented in the man pages listed below. .Pp Many of the CAM library functions use the .Va cam_device structure: .Bd -literal struct cam_device { char device_path[MAXPATHLEN+1];/* * Pathname of the * device given by the * user. This may be * null if the user * states the device * name and unit number * separately. */ char given_dev_name[DEV_IDLEN+1];/* * Device name given by * the user. */ - u_int32_t given_unit_number; /* + uint32_t given_unit_number; /* * Unit number given by * the user. */ char device_name[DEV_IDLEN+1];/* * Name of the device, * e.g. 'pass' */ - u_int32_t dev_unit_num; /* Unit number of the passthrough + uint32_t dev_unit_num; /* Unit number of the passthrough * device associated with this * particular device. */ char sim_name[SIM_IDLEN+1];/* * Controller name, e.g.'ahc' */ - u_int32_t sim_unit_number; /* Controller unit number */ - u_int32_t bus_id; /* Controller bus number */ + uint32_t sim_unit_number; /* Controller unit number */ + uint32_t bus_id; /* Controller bus number */ lun_id_t target_lun; /* Logical Unit Number */ target_id_t target_id; /* Target ID */ path_id_t path_id; /* System SCSI bus number */ - u_int16_t pd_type; /* type of peripheral device */ + uint16_t pd_type; /* type of peripheral device */ struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ - u_int8_t serial_num[252]; /* device serial number */ - u_int8_t serial_num_len; /* length of the serial number */ - u_int8_t sync_period; /* Negotiated sync period */ - u_int8_t sync_offset; /* Negotiated sync offset */ - u_int8_t bus_width; /* Negotiated bus width */ + uint8_t serial_num[252]; /* device serial number */ + uint8_t serial_num_len; /* length of the serial number */ + uint8_t sync_period; /* Negotiated sync period */ + uint8_t sync_offset; /* Negotiated sync offset */ + uint8_t bus_width; /* Negotiated bus width */ int fd; /* file descriptor for device */ }; .Ed .Pp .Fn cam_open_device takes as arguments a string describing the device it is to open, and .Ar flags suitable for passing to .Xr open 2 . The "path" passed in may actually be most any type of string that contains a device name and unit number to be opened. The string will be parsed by .Fn cam_get_device into a device name and unit number. Once the device name and unit number are determined, a lookup is performed to determine the passthrough device that corresponds to the given device. .Pp .Fn cam_open_spec_device opens the .Xr pass 4 device that corresponds to the device name and unit number passed in. The .Ar flags should be flags suitable for passing to .Xr open 2 . The .Ar device argument is optional. The user may supply pre-allocated space for the .Va cam_device structure. If the .Ar device argument is .Va NULL , .Fn cam_open_spec_device will allocate space for the .Va cam_device structure using .Xr malloc 3 . .Pp .Fn cam_open_btl is similar to .Fn cam_open_spec_device , except that it takes a .Tn SCSI bus, target and logical unit instead of a device name and unit number as arguments. The .Va path_id argument is the CAM equivalent of a .Tn SCSI bus number. It represents the logical bus number in the system. The .Ar flags should be flags suitable for passing to .Xr open 2 . As with .Fn cam_open_spec_device , the .Fa device argument is optional. .Pp .Fn cam_open_pass takes as an argument the .Fa path of a .Xr pass 4 device to open. No translation or lookup is performed, so the path passed in must be that of a CAM .Xr pass 4 device. The .Fa flags should be flags suitable for passing to .Xr open 2 . The .Fa device argument, as with .Fn cam_open_spec_device and .Fn cam_open_btl , should be NULL if the user wants the CAM library to allocate space for the .Va cam_device structure. .Fn cam_close_device frees the .Va cam_device structure allocated by one of the above open() calls, and closes the file descriptor to the passthrough device. This routine should not be called if the user allocated space for the .Va cam_device structure. Instead, the user should call .Fn cam_close_spec_device . .Pp .Fn cam_close_spec_device merely closes the file descriptor opened in one of the open() routines described above. This function should be called when the .Va cam_device structure was allocated by the caller, rather than the CAM library. .Pp .Fn cam_getccb allocates a CCB using .Xr malloc 3 and sets fields in the CCB header using values from the .Va cam_device structure. .Pp .Fn cam_send_ccb sends the given .Va ccb to the .Fa device described in the .Va cam_device structure. .Pp .Fn cam_freeccb frees CCBs allocated by .Fn cam_getccb . .Pp .Fn cam_path_string takes as arguments a .Va cam_device structure, and a string with length .Fa len . It creates a colon-terminated printing prefix string similar to the ones used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". .Fn cam_path_string will place at most .Fa len Ns \-1 characters into .Ar str . The .Ar len Ns 'th character will be the terminating .Ql \e0 . .Pp .Fn cam_device_dup operates in a fashion similar to .Xr strdup 3 . It allocates space for a .Va cam_device structure and copies the contents of the passed-in .Fa device structure to the newly allocated structure. .Pp .Fn cam_device_copy copies the .Fa src structure to .Fa dst . .Pp .Fn cam_get_device takes a .Fa path argument containing a string with a device name followed by a unit number. It then breaks the string down into a device name and unit number, and passes them back in .Fa dev_name and .Fa unit , respectively. .Fn cam_get_device can handle strings of the following forms, at least: .Pp .Bl -tag -width 1234 -compact .It /dev/foo1 .It foo0 .It nsa2 .El .Pp .Fn cam_get_device is provided as a convenience function for applications that need to provide functionality similar to .Fn cam_open_device . .Sh RETURN VALUES .Fn cam_open_device , .Fn cam_open_spec_device , .Fn cam_open_btl , and .Fn cam_open_pass return a pointer to a .Va cam_device structure, or NULL if there was an error. .Pp .Fn cam_getccb returns an allocated and partially initialized CCB, or NULL if allocation of the CCB failed. .Pp .Fn cam_send_ccb returns a value of -1 if an error occurred, and .Va errno is set to indicate the error. .Pp .Fn cam_path_string returns a filled printing prefix string as a convenience. This is the same .Fa str that is passed into .Fn cam_path_string . .Pp .Fn cam_device_dup returns a copy of the .Va device passed in, or NULL if an error occurred. .Pp .Fn cam_get_device returns 0 for success, and -1 to indicate failure. .Pp If an error is returned from one of the base CAM library functions described here, the reason for the error is generally printed in the global string .Va cam_errbuf which is .Dv CAM_ERRBUF_SIZE characters long. .Sh SEE ALSO .Xr cam_cdbparse 3 , .Xr pass 4 , .Xr camcontrol 8 .Sh HISTORY The CAM library first appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS .Fn cam_open_device does not check to see if the .Fa path passed in is a symlink to something. It also does not check to see if the .Fa path passed in is an actual .Xr pass 4 device. The former would be rather easy to implement, but the latter would require a definitive way to identify a device node as a .Xr pass 4 device. .Pp Some of the functions are possibly mis-named or poorly named. Index: stable/9/lib/libcam/cam_cdbparse.3 =================================================================== --- stable/9/lib/libcam/cam_cdbparse.3 (revision 290886) +++ stable/9/lib/libcam/cam_cdbparse.3 (revision 290887) @@ -1,567 +1,567 @@ .\" .\" Copyright (c) 1998 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .\" This man page borrows heavily from the old scsi(3) man page, which had .\" the following copyright: .\" .\" Copyright (c) 1994 HD Associates (hd@world.std.com) .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by HD Associates .\" 4. Neither the name of the HD Associates nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY HD ASSOCIATES``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL HD ASSOCIATES OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" .Dd October 13, 1998 .Dt CAM_CDBPARSE 3 .Os .Sh NAME .Nm csio_build , .Nm csio_build_visit , .Nm csio_decode , .Nm csio_decode_visit , .Nm buff_decode , .Nm buff_decode_visit , .Nm csio_encode , .Nm csio_encode_visit , .Nm buff_encode_visit .Nd CAM user library SCSI buffer parsing routines .Sh LIBRARY .Lb libcam .Sh SYNOPSIS .In stdio.h .In camlib.h .Ft int .Fo csio_build .Fa "struct ccb_scsiio *csio" -.Fa "u_int8_t *data_ptr" -.Fa "u_int32_t dxfer_len" -.Fa "u_int32_t flags" +.Fa "uint8_t *data_ptr" +.Fa "uint32_t dxfer_len" +.Fa "uint32_t flags" .Fa "int retry_count" .Fa "int timeout" .Fa "const char *cmd_spec" .Fa "..." .Fc .Ft int .Fo csio_build_visit .Fa "struct ccb_scsiio *csio" -.Fa "u_int8_t *data_ptr" -.Fa "u_int32_t dxfer_len" -.Fa "u_int32_t flags" +.Fa "uint8_t *data_ptr" +.Fa "uint32_t dxfer_len" +.Fa "uint32_t flags" .Fa "int retry_count" .Fa "int timeout" .Fa "const char *cmd_spec" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Ft int .Fo csio_decode .Fa "struct ccb_scsiio *csio" .Fa "const char *fmt" .Fa "..." .Fc .Ft int .Fo csio_decode_visit .Fa "struct ccb_scsiio *csio" .Fa "const char *fmt" .Fa "void (*arg_put)(void *hook" .Fa "int letter" .Fa "void *val" .Fa "int count" .Fa "char *name)" .Fa "void *puthook" .Fc .Ft int .Fo buff_decode -.Fa "u_int8_t *buff" +.Fa "uint8_t *buff" .Fa "size_t len" .Fa "const char *fmt" .Fa "..." .Fc .Ft int .Fo buff_decode_visit -.Fa "u_int8_t *buff" +.Fa "uint8_t *buff" .Fa "size_t len" .Fa "const char *fmt" .Fa "void (*arg_put)(void *, int, void *, int, char *)" .Fa "void *puthook" .Fc .Ft int .Fo csio_encode .Fa "struct ccb_scsiio *csio" .Fa "const char *fmt" .Fa "..." .Fc .Ft int .Fo csio_encode_visit .Fa "struct ccb_scsiio *csio" .Fa "const char *fmt" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Ft int .Fo buff_encode_visit -.Fa "u_int8_t *buff" +.Fa "uint8_t *buff" .Fa "size_t len" .Fa "const char *fmt" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Sh DESCRIPTION The CAM buffer/CDB encoding and decoding routines provide a relatively easy migration path for userland .Tn SCSI applications written with the similarly-named .Va scsireq_ Ns * functions from the old .Fx .Tn SCSI layer. .Pp These functions may be used in new applications, but users may find it easier to use the various SCSI CCB building functions included with the .Xr cam 3 library. (e.g.\& .Fn cam_fill_csio , .Fn scsi_start_stop , and .Fn scsi_read_write ) .Pp .Fn csio_build builds up a .Va ccb_scsiio structure based on the information provided in the variable argument list. It gracefully handles a NULL .Fa data_ptr argument passed to it. .Pp .Fa dxfer_len is the length of the data phase; the data transfer direction is determined by the .Fa flags argument. .Pp .Fa data_ptr is the data buffer used during the .Tn SCSI data phase. If no data is to be transferred for the .Tn SCSI command in question, this should be set to NULL. If there is data to transfer for the command, this buffer must be at least .Fa dxfer_len long. .Pp .Fa flags are the flags defined in .In cam/cam_ccb.h : .Bd -literal /* Common CCB header */ /* CAM CCB flags */ typedef enum { CAM_CDB_POINTER = 0x00000001,/* The CDB field is a pointer */ CAM_QUEUE_ENABLE = 0x00000002,/* SIM queue actions are enabled */ CAM_CDB_LINKED = 0x00000004,/* CCB contains a linked CDB */ CAM_SCATTER_VALID = 0x00000010,/* Scatter/gather list is valid */ CAM_DIS_AUTOSENSE = 0x00000020,/* Disable autosense feature */ CAM_DIR_RESV = 0x00000000,/* Data direction (00:reserved) */ CAM_DIR_IN = 0x00000040,/* Data direction (01:DATA IN) */ CAM_DIR_OUT = 0x00000080,/* Data direction (10:DATA OUT) */ CAM_DIR_NONE = 0x000000C0,/* Data direction (11:no data) */ CAM_DIR_MASK = 0x000000C0,/* Data direction Mask */ CAM_SOFT_RST_OP = 0x00000100,/* Use Soft reset alternative */ CAM_ENG_SYNC = 0x00000200,/* Flush resid bytes on complete */ CAM_DEV_QFRZDIS = 0x00000400,/* Disable DEV Q freezing */ CAM_DEV_QFREEZE = 0x00000800,/* Freeze DEV Q on execution */ CAM_HIGH_POWER = 0x00001000,/* Command takes a lot of power */ CAM_SENSE_PTR = 0x00002000,/* Sense data is a pointer */ CAM_SENSE_PHYS = 0x00004000,/* Sense pointer is physical addr*/ CAM_TAG_ACTION_VALID = 0x00008000,/* Use the tag action in this ccb*/ CAM_PASS_ERR_RECOVER = 0x00010000,/* Pass driver does err. recovery*/ CAM_DIS_DISCONNECT = 0x00020000,/* Disable disconnect */ CAM_SG_LIST_PHYS = 0x00040000,/* SG list has physical addrs. */ CAM_MSG_BUF_PHYS = 0x00080000,/* Message buffer ptr is physical*/ CAM_SNS_BUF_PHYS = 0x00100000,/* Autosense data ptr is physical*/ CAM_DATA_PHYS = 0x00200000,/* SG/Buffer data ptrs are phys. */ CAM_CDB_PHYS = 0x00400000,/* CDB pointer is physical */ CAM_ENG_SGLIST = 0x00800000,/* SG list is for the HBA engine */ /* Phase cognizant mode flags */ CAM_DIS_AUTOSRP = 0x01000000,/* Disable autosave/restore ptrs */ CAM_DIS_AUTODISC = 0x02000000,/* Disable auto disconnect */ CAM_TGT_CCB_AVAIL = 0x04000000,/* Target CCB available */ CAM_TGT_PHASE_MODE = 0x08000000,/* The SIM runs in phase mode */ CAM_MSGB_VALID = 0x20000000,/* Message buffer valid */ CAM_STATUS_VALID = 0x40000000,/* Status buffer valid */ CAM_DATAB_VALID = 0x80000000,/* Data buffer valid */ /* Host target Mode flags */ CAM_TERM_IO = 0x20000000,/* Terminate I/O Message sup. */ CAM_DISCONNECT = 0x40000000,/* Disconnects are mandatory */ CAM_SEND_STATUS = 0x80000000,/* Send status after data phase */ } ccb_flags; .Ed .Pp Multiple flags should be ORed together. Any of the CCB flags may be used, although it is worth noting several important ones here: .Bl -tag -width CAM_PASS_ERR_RECOVER .It Dv CAM_DIR_IN This indicates that the operation in question is a read operation. i.e., data is being read from the .Tn SCSI device to the user-supplied buffer. .It Dv CAM_DIR_OUT This indicates that the operation is a write operation. i.e., data is being written from the user-supplied buffer to the device. .It Dv CAM_DIR_NONE This indicates that there is no data to be transferred for this command. .It Dv CAM_DEV_QFRZDIS This flag disables device queue freezing as an error recovery mechanism. .It Dv CAM_PASS_ERR_RECOVER This flag tells the .Xr pass 4 driver to enable error recovery. The default is to not perform error recovery, which means that the retry count will not be honored without this flag, among other things. .It Dv CAM_DATA_PHYS This indicates that the address contained in .Fa data_ptr is a physical address, not a virtual address. .El .Pp The .Fa retry_count tells the kernel how many times to retry the command in question. The retry count is ignored unless the .Xr pass 4 driver is told to enable error recovery via the .Dv CAM_PASS_ERR_RECOVER flag. .Pp The .Fa timeout tells the kernel how long to wait for the given command to complete. If the timeout expires and the command has not completed, the CCB will be returned from the kernel with an appropriate error status. .Pp .Fa cmd_spec is a CDB format specifier used to build up the SCSI CDB. This text string is made up of a list of field specifiers. Field specifiers specify the value for each CDB field (including indicating that the value be taken from the next argument in the variable argument list), the width of the field in bits or bytes, and an optional name. White space is ignored, and the pound sign ('#') introduces a comment that ends at the end of the current line. .Pp The optional name is the first part of a field specifier and is in curly braces. The text in curly braces in this example are the names: .Dl "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page" .Pp This field specifier has two one bit fields and one six bit field. The second one bit field is the constant value 0 and the first one bit field and the six bit field are taken from the variable argument list. Multi byte fields are swapped into the SCSI byte order in the CDB and white space is ignored. .Pp When the field is a hex value or the letter v, (e.g., .Fa "1A" or .Fa "v" ) then a single byte value is copied to the next unused byte of the CDB. When the letter .Fa v is used the next integer argument is taken from the variable argument list and that value used. .Pp A constant hex value followed by a field width specifier or the letter .Fa v followed by a field width specifier (e.g., .Fa 3:4 , .Fa 3:b4 , .Fa 3:i3 , .Fa v:i3 ) specifies a field of a given bit or byte width. Either the constant value or (for the V specifier) the next integer value from the variable argument list is copied to the next unused bits or bytes of the CDB. .Pp A decimal number or the letter .Fa b followed by a decimal number field width indicates a bit field of that width. The bit fields are packed as tightly as possible beginning with the high bit (so that it reads the same as the SCSI spec), and a new byte of the CDB is started whenever a byte fills completely or when an .Fa i field is encountered. .Pp A field width specifier consisting of the letter .Fa i followed by either 1, 2, 3 or 4 indicates a 1, 2, 3 or 4 byte integral value that must be swapped into SCSI byte order (MSB first). .Pp For the .Fa v field specifier the next integer argument is taken from the variable argument list and that value is used swapped into SCSI byte order. .Pp .Fn csio_build_visit operates similarly to .Fn csio_build , except that the values to substitute for variable arguments in .Fa cmd_spec are retrieved via the .Fn arg_get function passed in to .Fn csio_build_visit instead of via .Xr stdarg 3 . The .Fn arg_get function takes two arguments: .Bl -tag -width field_name .It Fa gethook is passed into the .Fn arg_get function at each invocation. This enables the .Fn arg_get function to keep some state in between calls without using global or static variables. .It Fa field_name is the field name supplied in .Fa fmt , if any. .El .Pp .Fn csio_decode is used to decode information from the data in phase of the SCSI transfer. .Pp The decoding is similar to the command specifier processing of .Fn csio_build except that the data is extracted from the data pointed to by .Fa csio->data_ptr . The stdarg list should be pointers to integers instead of integer values. A seek field type and a suppression modifier are added. The .Fa * suppression modifier (e.g., .Fa *i3 or .Fa *b4 ) suppresses assignment from the field and can be used to skip over bytes or bits in the data, without having to copy them to a dummy variable in the arg list. .Pp The seek field type .Fa s permits you to skip over data. This seeks to an absolute position .Pq Fa s3 or a relative position .Pq Fa s+3 in the data, based on whether or not the presence of the '+' sign. The seek value can be specified as .Fa v and the next integer value from the argument list will be used as the seek value. .Pp .Fn csio_decode_visit operates like .Fn csio_decode except that instead of placing the decoded contents of the buffer in variadic arguments, the decoded buffer contents are returned to the user via the .Fn arg_put function that is passed in. The .Fn arg_put function takes several arguments: .Bl -tag -width letter .It Fa hook The "hook" is a mechanism to allow the .Fn arg_put function to save state in between calls. .It Fa letter is the letter describing the format of the argument being passed into the function. .It Fa val is a void pointer to the value being passed into the function. .It Fa count is the size of the value being passed into the .Fn arg_put function. The argument format determines the unit of measure. .It Fa name This is a text description of the field, if one was provided in the .Fa fmt . .El .Pp .Fn buff_decode decodes an arbitrary data buffer using the method described above for .Fn csio_decode . .Pp .Fn buff_decode_visit decodes an arbitrary data buffer using the method described above for .Fn csio_decode_visit . .Pp .Fn csio_encode encodes the .Fa data_ptr portion (not the CDB!) of a .Va ccb_scsiio structure, using the method described above for .Fn csio_build . .Pp .Fn csio_encode_visit encodes the .Fa data_ptr portion (not the CDB!) of a .Va ccb_scsiio structure, using the method described above for .Fn csio_build_visit . .Pp .Fn buff_encode_visit encodes an arbitrary data pointer, using the method described above for .Fn csio_build_visit . .Sh RETURN VALUES .Fn csio_build , .Fn csio_build_visit , .Fn csio_encode , .Fn csio_encode_visit , and .Fn buff_encode_visit return the number of fields processed. .Pp .Fn csio_decode , .Fn csio_decode_visit , .Fn buff_decode , and .Fn buff_decode_visit return the number of assignments performed. .Sh SEE ALSO .Xr cam 3 , .Xr pass 4 , .Xr camcontrol 8 .Sh HISTORY The CAM versions of these functions are based upon similar functions implemented for the old .Fx .Tn SCSI layer. The encoding/decoding functions in the old .Tn SCSI code were written by Peter Dufault. .Pp Many systems have comparable interfaces to permit a user to construct a SCSI command in user space. .Pp The old .Va scsireq data structure was almost identical to the SGI /dev/scsi data structure. If anyone knows the name of the authors it should go here; Peter Dufault first read about it in a 1989 Sun Expert magazine. .Pp The new CCB data structures are derived from the CAM-2 and CAM-3 specifications. .Pp .An Peter Dufault implemented a clone of SGI's interface in .Bx 386 that led to the original .Fx .Tn SCSI library and the related kernel ioctl. If anyone needs that for compatibility contact dufault@hda.com. .Sh AUTHORS Kenneth Merry implemented the CAM versions of these encoding and decoding functions. This current work is based upon earlier work by Peter Dufault. .Sh BUGS There should probably be a function that encodes both the CDB and the data buffer portions of a .Tn SCSI CCB. I discovered this while implementing the arbitrary command execution code in .Xr camcontrol 8 , but I have not yet had time to implement such a function. .Pp Some of the CCB flag descriptions really do not belong here. Rather they belong in a generic CCB man page. Since that man page has not yet been written, the shorter descriptions here will have to suffice. Index: stable/9/lib/libcam =================================================================== --- stable/9/lib/libcam (revision 290886) +++ stable/9/lib/libcam (revision 290887) Property changes on: stable/9/lib/libcam ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libcam:r231564 Index: stable/9/lib/libdevstat/devstat.3 =================================================================== --- stable/9/lib/libdevstat/devstat.3 (revision 290886) +++ stable/9/lib/libdevstat/devstat.3 (revision 290887) @@ -1,795 +1,795 @@ .\" .\" Copyright (c) 1998, 1999, 2001 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 18, 2003 .Dt DEVSTAT 3 .Os .Sh NAME .Nm devstat , .Nm devstat_getnumdevs , .Nm devstat_getgeneration , .Nm devstat_getversion , .Nm devstat_checkversion , .Nm devstat_getdevs , .Nm devstat_selectdevs , .Nm devstat_buildmatch , .Nm devstat_compute_statistics , .Nm devstat_compute_etime .Nd device statistics utility library .Sh LIBRARY .Lb libdevstat .Sh SYNOPSIS .In devstat.h .Ft int .Fn devstat_getnumdevs "kvm_t *kd" .Ft long .Fn devstat_getgeneration "kvm_t *kd" .Ft int .Fn devstat_getversion "kvm_t *kd" .Ft int .Fn devstat_checkversion "kvm_t *kd" .Ft int .Fn devstat_getdevs "kvm_t *kd" "struct statinfo *stats" .Ft int .Fo devstat_selectdevs .Fa "struct device_selection **dev_select" .Fa "int *num_selected" .Fa "int *num_selections" .Fa "long *select_generation" .Fa "long current_generation" .Fa "struct devstat *devices" .Fa "int numdevs" .Fa "struct devstat_match *matches" .Fa "int num_matches" .Fa "char **dev_selections" .Fa "int num_dev_selections" .Fa "devstat_select_mode select_mode" .Fa "int maxshowdevs" .Fa "int perf_select" .Fc .Ft int .Fo devstat_buildmatch .Fa "char *match_str" .Fa "struct devstat_match **matches" .Fa "int *num_matches" .Fc .Ft int .Fo devstat_compute_statistics .Fa "struct devstat *current" .Fa "struct devstat *previous" .Fa "long double etime" .Fa "..." .Fc .Ft "long double" .Fo devstat_compute_etime .Fa "struct bintime *cur_time" .Fa "struct bintime *prev_time" .Fc .Sh DESCRIPTION The .Nm library is a library of helper functions for dealing with the kernel .Xr devstat 9 interface, which is accessible to users via .Xr sysctl 3 and .Xr kvm 3 . All functions that take a .Vt "kvm_t *" as first argument can be passed .Dv NULL instead of a kvm handle as this argument, which causes the data to be read via .Xr sysctl 3 . Otherwise, it is read via .Xr kvm 3 using the supplied handle. The .Fn devstat_checkversion function should be called with each kvm handle that is going to be used (or with .Dv NULL if .Xr sysctl 3 is going to be used). .Pp The .Fn devstat_getnumdevs function returns the number of devices registered with the .Nm subsystem in the kernel. .Pp The .Fn devstat_getgeneration function returns the current generation of the .Nm list of devices in the kernel. .Pp The .Fn devstat_getversion function returns the current kernel .Nm version. .Pp The .Fn devstat_checkversion function checks the userland .Nm version against the kernel .Nm version. If the two are identical, it returns zero. Otherwise, it prints an appropriate error in .Va devstat_errbuf and returns \-1. .Pp The .Fn devstat_getdevs function fetches the current list of devices and statistics into the supplied .Vt statinfo structure. The .Vt statinfo structure can be found in .In devstat.h : .Bd -literal -offset indent struct statinfo { long cp_time[CPUSTATES]; long tk_nin; long tk_nout; struct devinfo *dinfo; long double snap_time; }; .Ed .Pp The .Fn devstat_getdevs function expects the .Vt statinfo structure to be allocated, and it also expects the .Va dinfo subelement to be allocated and zeroed prior to the first invocation of .Fn devstat_getdevs . The .Va dinfo subelement is used to store state between calls, and should not be modified after the first call to .Fn devstat_getdevs . The .Va dinfo subelement contains the following elements: .Bd -literal -offset indent struct devinfo { struct devstat *devices; - u_int8_t *mem_ptr; + uint8_t *mem_ptr; long generation; int numdevs; }; .Ed .Pp The .Va kern.devstat.all .Xr sysctl 8 variable contains an array of .Nm structures, but at the head of the array is the current .Nm generation. The reason the generation is at the head of the buffer is so that userland software accessing the .Nm statistics information can atomically get both the statistics information and the corresponding generation number. If client software were forced to get the generation number via a separate .Xr sysctl 8 variable (which is available for convenience), the list of devices could change between the time the client gets the generation and the time the client gets the device list. .Pp The .Va mem_ptr subelement of the .Vt devinfo structure is a pointer to memory that is allocated, and resized if necessary, by .Fn devstat_getdevs . The devices subelement of the .Vt devinfo structure is basically a pointer to the beginning of the array of devstat structures from the .Va kern.devstat.all .Xr sysctl 8 variable (or the corresponding values read via .Xr kvm 3 ) . The generation subelement of the .Vt devinfo structure contains the corresponding generation number. The .Va numdevs subelement of the .Vt devinfo structure contains the current number of devices registered with the kernel .Nm subsystem. .Pp The .Fn devstat_selectdevs function selects devices to display based upon a number of criteria: .Bl -tag -width indent .It specified devices Specified devices are the first selection priority. These are generally devices specified by name by the user e.g.\& .Li da0 , da1 , cd0 . .It match patterns These are pattern matching expressions generated by .Fn devstat_buildmatch from user input. .It performance If performance mode is enabled, devices will be sorted based on the .Va bytes field in the .Vt device_selection structure passed in to .Fn devstat_selectdevs . The .Va bytes value currently must be maintained by the user. In the future, this may be done for him in a .Nm library routine. If no devices have been selected by name or by pattern, the performance tracking code will select every device in the system, and sort them by performance. If devices have been selected by name or pattern, the performance tracking code will honor those selections and will only sort among the selected devices. .It order in the devstat list If the selection mode is set to .Dv DS_SELECT_ADD , and if there are still less than .Fa maxshowdevs devices selected, .Fn devstat_selectdevs will automatically select up to .Fa maxshowdevs devices. .El .Pp The .Fn devstat_selectdevs function performs selections in four different modes: .Bl -tag -width ".Dv DS_SELECT_ADDONLY" .It Dv DS_SELECT_ADD In .Dq add mode, .Fn devstat_selectdevs will select any unselected devices specified by name or matching pattern. It will also select more devices, in devstat list order, until the number of selected devices is equal to .Fa maxshowdevs or until all devices are selected. .It Dv DS_SELECT_ONLY In .Dq only mode, .Fn devstat_selectdevs will clear all current selections, and will only select devices specified by name or by matching pattern. .It Dv DS_SELECT_REMOVE In .Dq remove mode, .Fn devstat_selectdevs will remove devices specified by name or by matching pattern. It will not select any additional devices. .It Dv DS_SELECT_ADDONLY In .Dq "add only" mode, .Fn devstat_selectdevs will select any unselected devices specified by name or matching pattern. In this respect it is identical to .Dq add mode. It will not, however, select any devices other than those specified. .El .Pp In all selection modes, .Fn devstat_selectdevs will not select any more than .Fa maxshowdevs devices. One exception to this is when you are in .Dq top mode and no devices have been selected. In this case, .Fn devstat_selectdevs will select every device in the system. Client programs must pay attention to selection order when deciding whether to pay attention to a particular device. This may be the wrong behavior, and probably requires additional thought. .Pp The .Fn devstat_selectdevs function handles allocation and resizing of the .Fa dev_select structure passed in by the client. The .Fn devstat_selectdevs function uses the .Fa numdevs and .Fa current_generation fields to track the current .Nm generation and number of devices. If .Fa num_selections is not the same as .Fa numdevs or if .Fa select_generation is not the same as .Fa current_generation , .Fn devstat_selectdevs will resize the selection list as necessary, and re-initialize the selection array. .Pp The .Fn devstat_buildmatch function takes a comma separated match string and compiles it into a .Vt devstat_match structure that is understood by .Fn devstat_selectdevs . Match strings have the following format: .Pp .D1 Ar device , Ns Ar type , Ns Ar if .Pp The .Fn devstat_buildmatch function takes care of allocating and reallocating the match list as necessary. Currently known match types include: .Bl -tag -width indent .It device type: .Bl -tag -width ".Li enclosure" -compact .It Li da Direct Access devices .It Li sa Sequential Access devices .It Li printer Printers .It Li proc Processor devices .It Li worm Write Once Read Multiple devices .It Li cd CD devices .It Li scanner Scanner devices .It Li optical Optical Memory devices .It Li changer Medium Changer devices .It Li comm Communication devices .It Li array Storage Array devices .It Li enclosure Enclosure Services devices .It Li floppy Floppy devices .El .It interface: .Bl -tag -width ".Li enclosure" -compact .It Li IDE Integrated Drive Electronics devices .It Li SCSI Small Computer System Interface devices .It Li other Any other device interface .El .It passthrough: .Bl -tag -width ".Li enclosure" -compact .It Li pass Passthrough devices .El .El .Pp The .Fn devstat_compute_statistics function provides complete statistics calculation. There are four arguments for which values .Em must be supplied: .Fa current , .Fa previous , .Fa etime , and the terminating argument for the varargs list, .Dv DSM_NONE . For most applications, the user will want to supply valid .Vt devstat structures for both .Fa current and .Fa previous . In some instances, for instance when calculating statistics since system boot, the user may pass in a .Dv NULL pointer for the .Fa previous argument. In that case, .Fn devstat_compute_statistics will use the total stats in the .Fa current structure to calculate statistics over .Fa etime . For each statistics to be calculated, the user should supply the proper enumerated type (listed below), and a variable of the indicated type. All statistics are either integer values, for which a -.Vt u_int64_t +.Vt uint64_t is used, or floating point, for which a .Vt "long double" is used. The statistics that may be calculated are: .Bl -tag -width ".Dv DSM_TRANSFERS_PER_SECOND_OTHER" .It Dv DSM_NONE type: N/A .Pp This .Em must be the last argument passed to .Fn devstat_compute_statistics . It is an argument list terminator. .It Dv DSM_TOTAL_BYTES type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of bytes transferred between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TOTAL_BYTES_READ .It Dv DSM_TOTAL_BYTES_WRITE .It Dv DSM_TOTAL_BYTES_FREE type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of bytes in transactions of the specified type between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TOTAL_TRANSFERS type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of transfers between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TOTAL_TRANSFERS_OTHER .It Dv DSM_TOTAL_TRANSFERS_READ .It Dv DSM_TOTAL_TRANSFERS_WRITE .It Dv DSM_TOTAL_TRANSFERS_FREE type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of transactions of the specified type between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TOTAL_BLOCKS type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of blocks transferred between the acquisition of .Fa previous and .Fa current . This number is in terms of the blocksize reported by the device. If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It Dv DSM_TOTAL_BLOCKS_READ .It Dv DSM_TOTAL_BLOCKS_WRITE .It Dv DSM_TOTAL_BLOCKS_FREE type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The total number of blocks of the specified type between the acquisition of .Fa previous and .Fa current . This number is in terms of the blocksize reported by the device. If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It Dv DSM_KB_PER_TRANSFER type: .Vt "long double *" .Pp The average number of kilobytes per transfer between the acquisition of .Fa previous and .Fa current . .It Dv DSM_KB_PER_TRANSFER_READ .It Dv DSM_KB_PER_TRANSFER_WRITE .It Dv DSM_KB_PER_TRANSFER_FREE type: .Vt "long double *" .Pp The average number of kilobytes in the specified type transaction between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TRANSFERS_PER_SECOND type: .Vt "long double *" .Pp The average number of transfers per second between the acquisition of .Fa previous and .Fa current . .It Dv DSM_TRANSFERS_PER_SECOND_OTHER .It Dv DSM_TRANSFERS_PER_SECOND_READ .It Dv DSM_TRANSFERS_PER_SECOND_WRITE .It Dv DSM_TRANSFERS_PER_SECOND_FREE type: .Vt "long double *" .Pp The average number of transactions of the specified type per second between the acquisition of .Fa previous and .Fa current . .It Dv DSM_MB_PER_SECOND type: .Vt "long double *" .Pp The average number of megabytes transferred per second between the acquisition of .Fa previous and .Fa current . .It Dv DSM_MB_PER_SECOND_READ .It Dv DSM_MB_PER_SECOND_WRITE .It Dv DSM_MB_PER_SECOND_FREE type: .Vt "long double *" .Pp The average number of megabytes per second in the specified type of transaction between the acquisition of .Fa previous and .Fa current . .It Dv DSM_BLOCKS_PER_SECOND type: .Vt "long double *" .Pp The average number of blocks transferred per second between the acquisition of .Fa previous and .Fa current . This number is in terms of the blocksize reported by the device. If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It Dv DSM_BLOCKS_PER_SECOND_READ .It Dv DSM_BLOCKS_PER_SECOND_WRITE .It Dv DSM_BLOCKS_PER_SECOND_FREE type: .Vt "long double *" .Pp The average number of blocks per second in the specified type of transaction between the acquisition of .Fa previous and .Fa current . This number is in terms of the blocksize reported by the device. If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It Dv DSM_MS_PER_TRANSACTION type: .Vt "long double *" .Pp The average duration of transactions between the acquisition of .Fa previous and .Fa current . .It Dv DSM_MS_PER_TRANSACTION_OTHER .It Dv DSM_MS_PER_TRANSACTION_READ .It Dv DSM_MS_PER_TRANSACTION_WRITE .It Dv DSM_MS_PER_TRANSACTION_FREE type: .Vt "long double *" .Pp The average duration of transactions of the specified type between the acquisition of .Fa previous and .Fa current . .It Dv DSM_BUSY_PCT type: .Vt "long double *" .Pp The percentage of time the device had one or more transactions outstanding between the acquisition of .Fa previous and .Fa current . .It Dv DSM_QUEUE_LENGTH type: -.Vt "u_int64_t *" +.Vt "uint64_t *" .Pp The number of not yet completed transactions at the time when .Fa current was acquired. .It Dv DSM_SKIP type: N/A .Pp If you do not need a result from .Fn devstat_compute_statistics , just put .Dv DSM_SKIP as first (type) parameter and .Dv NULL as second parameter. This can be useful in scenarios where the statistics to be calculated are determined at run time. .El .Pp The .Fn devstat_compute_etime function provides an easy way to find the difference in seconds between two .Vt bintime structures. This is most commonly used in conjunction with the time recorded by the .Fn devstat_getdevs function (in .Vt "struct statinfo" ) each time it fetches the current .Nm list. .Sh RETURN VALUES The .Fn devstat_getnumdevs , .Fn devstat_getgeneration , and .Fn devstat_getversion function return the indicated sysctl variable, or \-1 if there is an error fetching the variable. .Pp The .Fn devstat_checkversion function returns 0 if the kernel and userland .Nm versions match. If they do not match, it returns \-1. .Pp The .Fn devstat_getdevs and .Fn devstat_selectdevs functions return \-1 in case of an error, 0 if there is no error, and 1 if the device list or selected devices have changed. A return value of 1 from .Fn devstat_getdevs is usually a hint to re-run .Fn devstat_selectdevs because the device list has changed. .Pp The .Fn devstat_buildmatch function returns \-1 for error, and 0 if there is no error. .Pp The .Fn devstat_compute_etime function returns the computed elapsed time. .Pp The .Fn devstat_compute_statistics function returns \-1 for error, and 0 for success. .Pp If an error is returned from one of the .Nm library functions, the reason for the error is generally printed in the global string .Va devstat_errbuf which is .Dv DEVSTAT_ERRBUF_SIZE characters long. .Sh SEE ALSO .Xr systat 1 , .Xr kvm 3 , .Xr sysctl 3 , .Xr iostat 8 , .Xr rpc.rstatd 8 , .Xr sysctl 8 , .Xr vmstat 8 , .Xr devstat 9 .Sh HISTORY The .Nm statistics system first appeared in .Fx 3.0 . The new interface (the functions prefixed with .Li devstat_ ) first appeared in .Fx 5.0 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS There should probably be an interface to de-allocate memory allocated by .Fn devstat_getdevs , .Fn devstat_selectdevs , and .Fn devstat_buildmatch . .Pp The .Fn devstat_selectdevs function should probably not select more than .Fa maxshowdevs devices in .Dq top mode when no devices have been selected previously. .Pp There should probably be functions to perform the statistics buffer swapping that goes on in most of the clients of this library. .Pp The .Vt statinfo and .Vt devinfo structures should probably be cleaned up and thought out a little more. Index: stable/9/lib/libradius/libradius.3 =================================================================== --- stable/9/lib/libradius/libradius.3 (revision 290886) +++ stable/9/lib/libradius/libradius.3 (revision 290887) @@ -1,598 +1,598 @@ .\" Copyright 1998 Juniper Networks, Inc. .\" Copyright 2009 Alexander Motin . .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 5, 2009 .Dt LIBRADIUS 3 .Os .Sh NAME .Nm libradius .Nd RADIUS client/server library .Sh SYNOPSIS .In radlib.h .Ft "struct rad_handle *" .Fn rad_acct_open "void" .Ft int .Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" .Ft "struct rad_handle *" .Fn rad_auth_open "void" .Ft void .Fn rad_close "struct rad_handle *h" .Ft int .Fn rad_config "struct rad_handle *h" "const char *file" .Ft int .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv" .Ft int .Fn rad_create_request "struct rad_handle *h" "int code" .Ft int .Fn rad_create_response "struct rad_handle *h" "int code" .Ft "struct in_addr" .Fn rad_cvt_addr "const void *data" -.Ft u_int32_t +.Ft uint32_t .Fn rad_cvt_int "const void *data" .Ft char * .Fn rad_cvt_string "const void *data" "size_t len" .Ft int .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len" .Ft int -.Fn rad_get_vendor_attr "u_int32_t *vendor" "const void **data" "size_t *len" +.Fn rad_get_vendor_attr "uint32_t *vendor" "const void **data" "size_t *len" .Ft int .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv" .Ft int .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr" .Ft int .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len" .Ft int -.Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value" +.Fn rad_put_int "struct rad_handle *h" "int type" "uint32_t value" .Ft int .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str" .Ft int .Fn rad_put_message_authentic "struct rad_handle *h" .Ft int .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr" .Ft int .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len" .Ft int -.Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "u_int32_t value" +.Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "uint32_t value" .Ft int .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str" .Ft ssize_t .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len" .Ft int .Fn rad_receive_request "struct rad_handle *h" .Ft int .Fn rad_send_request "struct rad_handle *h" .Ft int .Fn rad_send_response "struct rad_handle *h" .Ft "struct rad_handle *" .Fn rad_server_open "int fd" .Ft "const char *" .Fn rad_server_secret "struct rad_handle *h" .Ft "void" .Fn rad_bind_to "struct rad_handle *h" "in_addr_t addr" .Ft u_char * .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen" .Ft u_char * .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len" .Ft "const char *" .Fn rad_strerror "struct rad_handle *h" .Sh DESCRIPTION The .Nm library implements the Remote Authentication Dial In User Service (RADIUS). RADIUS, defined in RFCs 2865 and 2866, allows clients to perform authentication and accounting by means of network requests to remote servers. .Ss Initialization To use the library, an application must first call .Fn rad_auth_open , .Fn rad_acct_open or .Fn rad_server_open to obtain a .Vt "struct rad_handle *" , which provides the context for subsequent operations. The former function is used for RADIUS authentication and the latter is used for RADIUS accounting. Calls to .Fn rad_auth_open , .Fn rad_acct_open and .Fn rad_server_open always succeed unless insufficient virtual memory is available. If the necessary memory cannot be allocated, the functions return .Dv NULL . For compatibility with earlier versions of this library, .Fn rad_open is provided as a synonym for .Fn rad_auth_open . .Pp Before issuing any RADIUS requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call .Fn rad_config . .Fn rad_config causes the library to read a configuration file whose format is described in .Xr radius.conf 5 . The pathname of the configuration file is passed as the .Fa file argument to .Fn rad_config . This argument may also be given as .Dv NULL , in which case the standard configuration file .Pa /etc/radius.conf is used. .Fn rad_config returns 0 on success, or \-1 if an error occurs. .Pp The library can also be configured programmatically by calls to .Fn rad_add_server . The .Fa host parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. The .Fa port parameter specifies the UDP port to contact on the server. If .Fa port is given as 0, the library looks up the .Ql radius/udp or .Ql radacct/udp service in the network .Xr services 5 database, and uses the port found there. If no entry is found, the library uses the standard RADIUS ports, 1812 for authentication and 1813 for accounting. The shared secret for the server host is passed to the .Fa secret parameter. It may be any .Dv NUL Ns -terminated string of bytes. The RADIUS protocol ignores all but the leading 128 bytes of the shared secret. The timeout for receiving replies from the server is passed to the .Fa timeout parameter, in units of seconds. The maximum number of repeated requests to make before giving up is passed into the .Fa max_tries parameter. .Fn rad_add_server returns 0 on success, or \-1 if an error occurs. .Pp .Fn rad_add_server may be called multiple times, and it may be used together with .Fn rad_config . At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server's .Fa max_tries limit has been reached. .Ss Creating a RADIUS Request A RADIUS request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, call .Fn rad_create_request . In addition to the usual .Vt "struct rad_handle *" , this function takes a .Fa code parameter which specifies the type of the request. Most often this will be .Dv RAD_ACCESS_REQUEST . .Fn rad_create_request returns 0 on success, or \-1 on if an error occurs. .Pp After the request has been created with .Fn rad_create_request , attributes can be attached to it. This is done through calls to .Fn rad_put_addr , .Fn rad_put_int , and .Fn rad_put_string . Each accepts a .Fa type parameter identifying the attribute, and a value which may be an Internet address, an integer, or a .Dv NUL Ns -terminated string, respectively. Alternatively, .Fn rad_put_vendor_addr , .Fn rad_put_vendor_int or .Fn rad_put_vendor_string may be used to specify vendor specific attributes. Vendor specific definitions may be found in .In radlib_vs.h .Pp The library also provides a function .Fn rad_put_attr which can be used to supply a raw, uninterpreted attribute. The .Fa data argument points to an array of bytes, and the .Fa len argument specifies its length. .Pp It is possible adding the Message-Authenticator to the request. This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579). This attribute must be present in any packet that includes an EAP-Message attribute. It can be added by using the .Fn rad_put_message_authentic function. The .Nm library calculates the HMAC-MD5 hash implicitly before sending the request. If the Message-Authenticator was found inside the response packet, then the packet is silently dropped, if the validation failed. In order to get this feature, the library should be compiled with OpenSSL support. .Pp The .Fn rad_put_X functions return 0 on success, or \-1 if an error occurs. .Ss Sending the Request and Receiving the Response After the RADIUS request has been constructed, it is sent either by means of .Fn rad_send_request or by a combination of calls to .Fn rad_init_send_request and .Fn rad_continue_send_request . .Pp The .Fn rad_send_request function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary. If a valid response is received, .Fn rad_send_request returns the RADIUS code which specifies the type of the response. This will typically be .Dv RAD_ACCESS_ACCEPT , .Dv RAD_ACCESS_REJECT , or .Dv RAD_ACCESS_CHALLENGE . If no valid response is received, .Fn rad_send_request returns \-1. .Pp As an alternative, if you do not wish to block waiting for a response, .Fn rad_init_send_request and .Fn rad_continue_send_request may be used instead. If a reply is received from the RADIUS server or a timeout occurs, these functions return a value as described for .Fn rad_send_request . Otherwise, a value of zero is returned and the values pointed to by .Fa fd and .Fa tv are set to the descriptor and timeout that should be passed to .Xr select 2 . .Pp .Fn rad_init_send_request must be called first, followed by repeated calls to .Fn rad_continue_send_request as long as a return value of zero is given. Between each call, the application should call .Xr select 2 , passing .Fa *fd as a read descriptor and timing out after the interval specified by .Fa tv . When .Xr select 2 returns, .Fn rad_continue_send_request should be called with .Fa selected set to a non-zero value if .Xr select 2 indicated that the descriptor is readable. .Pp Like RADIUS requests, each response may contain zero or more attributes. After a response has been received successfully by .Fn rad_send_request or .Fn rad_continue_send_request , its attributes can be extracted one by one using .Fn rad_get_attr . Each time .Fn rad_get_attr is called, it gets the next attribute from the current response, and stores a pointer to the data and the length of the data via the reference parameters .Fa data and .Fa len , respectively. Note that the data resides in the response itself, and must not be modified. A successful call to .Fn rad_get_attr returns the RADIUS attribute type. If no more attributes remain in the current response, .Fn rad_get_attr returns 0. If an error such as a malformed attribute is detected, \-1 is returned. .Pp If .Fn rad_get_attr returns .Dv RAD_VENDOR_SPECIFIC , .Fn rad_get_vendor_attr may be called to determine the vendor. The vendor specific RADIUS attribute type is returned. The reference parameters .Fa data and .Fa len (as returned from .Fn rad_get_attr ) are passed to .Fn rad_get_vendor_attr , and are adjusted to point to the vendor specific attribute data. .Pp The common types of attributes can be decoded using .Fn rad_cvt_addr , .Fn rad_cvt_int , and .Fn rad_cvt_string . These functions accept a pointer to the attribute data, which should have been obtained using .Fn rad_get_attr and optionally .Fn rad_get_vendor_attr . In the case of .Fn rad_cvt_string , the length .Fa len must also be given. These functions interpret the attribute as an Internet address, an integer, or a string, respectively, and return its value. .Fn rad_cvt_string returns its value as a .Dv NUL Ns -terminated string in dynamically allocated memory. The application should free the string using .Xr free 3 when it is no longer needed. .Pp If insufficient virtual memory is available, .Fn rad_cvt_string returns .Dv NULL . .Fn rad_cvt_addr and .Fn rad_cvt_int cannot fail. .Pp The .Fn rad_request_authenticator function may be used to obtain the Request-Authenticator attribute value associated with the current RADIUS server according to the supplied rad_handle. The target buffer .Fa buf of length .Fa len must be supplied and should be at least 16 bytes. The return value is the number of bytes written to .Fa buf or \-1 to indicate that .Fa len was not large enough. .Pp The .Fn rad_server_secret returns the secret shared with the current RADIUS server according to the supplied rad_handle. .Pp The .Fn rad_bind_to assigns a source address for all requests to the current RADIUS server. .Pp The .Fn rad_demangle function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys. The return value is .Dv NULL on failure, or the plaintext attribute. This value should be freed using .Xr free 3 when it is no longer needed. .Pp The .Fn rad_demangle_mppe_key function demangles the send- and recv-keys when using MPPE (see RFC 2548). The return value is .Dv NULL on failure, or the plaintext attribute. This value should be freed using .Xr free 3 when it is no longer needed. .Ss Obtaining Error Messages Those functions which accept a .Vt "struct rad_handle *" argument record an error message if they fail. The error message can be retrieved by calling .Fn rad_strerror . The message text is overwritten on each new error for the given .Vt "struct rad_handle *" . Thus the message must be copied if it is to be preserved through subsequent library calls using the same handle. .Ss Cleanup To free the resources used by the RADIUS library, call .Fn rad_close . .Ss Server operation Server mode operates much alike to client mode, except packet send and receive steps are swapped. To operate as server you should obtain server context with .Fn rad_server_open function, passing opened and bound UDP socket file descriptor as argument. You should define allowed clients and their secrets using .Fn rad_add_server function. port, timeout and max_tries arguments are ignored in server mode. You should call .Fn rad_receive_request function to receive request from client. If you do not want to block on socket read, you are free to use any poll(), select() or non-blocking sockets for the socket. Received request can be parsed with same parsing functions as for client. To respond to the request you should call .Fn rad_create_response and fill response content with same packet writing functions as for client. When packet is ready, it should be sent with .Fn rad_send_response . .Sh RETURN VALUES The following functions return a non-negative value on success. If they detect an error, they return \-1 and record an error message which can be retrieved using .Fn rad_strerror . .Pp .Bl -item -offset indent -compact .It .Fn rad_add_server .It .Fn rad_config .It .Fn rad_create_request .It .Fn rad_create_response .It .Fn rad_get_attr .It .Fn rad_put_addr .It .Fn rad_put_attr .It .Fn rad_put_int .It .Fn rad_put_string .It .Fn rad_put_message_authentic .It .Fn rad_init_send_request .It .Fn rad_continue_send_request .It .Fn rad_send_request .It .Fn rad_send_response .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they are unable to allocate sufficient virtual memory, they return .Dv NULL , without recording an error message. .Pp .Bl -item -offset indent -compact .It .Fn rad_acct_open .It .Fn rad_auth_open .It .Fn rad_server_open .It .Fn rad_cvt_string .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they fail, they return .Dv NULL , with recording an error message. .Pp .Bl -item -offset indent -compact .It .Fn rad_demangle .It .Fn rad_demangle_mppe_key .El .Sh FILES .Bl -tag -width indent .It Pa /etc/radius.conf .El .Sh SEE ALSO .Xr radius.conf 5 .Rs .%A "C. Rigney, et al" .%T "Remote Authentication Dial In User Service (RADIUS)" .%O "RFC 2865" .Re .Rs .%A "C. Rigney" .%T "RADIUS Accounting" .%O "RFC 2866" .Re .Rs .%A G. Zorn .%T "Microsoft Vendor-specific RADIUS attributes" .%O RFC 2548 .Re .Rs .%A C. Rigney, et al .%T "RADIUS extensions" .%O RFC 2869 .Re .Sh AUTHORS .An -nosplit This software was originally written by .An John Polstra , and donated to the .Fx project by Juniper Networks, Inc. .An Oleg Semyonov subsequently added the ability to perform RADIUS accounting. Later additions and changes by .An Michael Bretterklieber . Server mode support was added by .An Alexander Motin . Index: stable/9/lib/libradius =================================================================== --- stable/9/lib/libradius (revision 290886) +++ stable/9/lib/libradius (revision 290887) Property changes on: stable/9/lib/libradius ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libradius:r231564 Index: stable/9/lib =================================================================== --- stable/9/lib (revision 290886) +++ stable/9/lib (revision 290887) Property changes on: stable/9/lib ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib:r231564 Index: stable/9/sbin/bsdlabel/bsdlabel.8 =================================================================== --- stable/9/sbin/bsdlabel/bsdlabel.8 (revision 290886) +++ stable/9/sbin/bsdlabel/bsdlabel.8 (revision 290887) @@ -1,500 +1,500 @@ .\" Copyright (c) 1987, 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Symmetric Computer Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd October 1, 2013 .Dt BSDLABEL 8 .Os .Sh NAME .Nm bsdlabel .Nd read and write BSD label .Sh SYNOPSIS .Nm .Op Fl A .Ar disk | Fl f Ar file .Nm .Fl w .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Ar disk | Fl f Ar file .Op Ar type .Nm .Fl e .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Ar disk | Fl f Ar file .Nm .Fl R .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Op Fl f .Ar disk | Fl f Ar file .Ar protofile .Sh DESCRIPTION The .Nm utility installs, examines or modifies the .Bx label on a disk partition, or on a file containing a partition image. In addition, .Nm can install bootstrap code. .Ss Disk Device Name When specifying the device (i.e., when the .Fl f option is not used), the .Pa /dev/ path prefix may be omitted; the .Nm utility will automatically prepend it. .Ss General Options The .Fl A option enables processing of the historical parts of the .Bx label. If the option is not given, suitable values are set for these fields. .Pp The .Fl f option tells .Nm that the program will operate on a file instead of a disk partition. .Pp The .Fl n option stops the .Nm program right before the disk would have been modified, and displays the result instead of writing it. .Pp The .Fl m Ar machine argument forces .Nm to use a layout suitable for a different architecture. Current valid values are .Cm i386 , amd64 , ia64 , and .Cm pc98 . If this option is omitted, .Nm will use a layout suitable for the current machine. .Ss Reading the Disk Label To examine the label on a disk drive, use the form .Pp .Nm .Op Fl A .Op Fl m Ar machine .Ar disk .Pp .Ar disk represents the disk in question, and may be in the form .Pa da0 or .Pa /dev/da0 . It will display the partition layout. .Ss Writing a Standard Label To write a standard label, use the form .Pp .Nm .Fl w .Op Fl \&An .Op Fl m Ar machine .Ar disk .Op Ar type .Pp If the drive .Ar type is specified, the entry of that name in the .Xr disktab 5 file is used; otherwise, or if the type is specified as 'auto', a default layout is used. .Ss Editing an Existing Disk Label To edit an existing disk label, use the form .Pp .Nm .Fl e .Op Fl \&An .Op Fl m Ar machine .Ar disk .Pp This command opens the disk label in the default editor, and when the editor exits, the label is validated and if OK written to disk. .Ss Restoring a Disk Label From a File To restore a disk label from a file, use the form .Pp .Nm .Fl R .Op Fl \&An .Op Fl m Ar machine .Ar disk protofile .Pp The .Nm utility is capable of restoring a disk label that was previously saved in a file in .Tn ASCII format. The prototype file used to create the label should be in the same format as that produced when reading or editing a label. Comments are delimited by .Ql # and newline. .Ss Installing Bootstraps If the .Fl B option is specified, bootstrap code will be read from the file .Pa /boot/boot and written to the disk. The .Fl b Ar boot option allows a different file to be used. .Sh FILES .Bl -tag -width ".Pa /etc/disktab" -compact .It Pa /boot/boot Default boot image. .It Pa /etc/disktab Disk description file. .El .Sh SAVED FILE FORMAT The .Nm utility uses an .Tn ASCII version of the label when examining, editing, or restoring a disk label. The format is: .Bd -literal -offset 4n 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 81920 16 4.2BSD 2048 16384 5128 b: 1091994 81936 swap c: 1173930 0 unused 0 0 # "raw" part, don't edit .Ed .Pp If the .Fl A option is specified, the format is: .Bd -literal -offset 4n # /dev/da1c: type: SCSI disk: da0s1 label: flags: bytes/sector: 512 sectors/track: 51 tracks/cylinder: 19 sectors/cylinder: 969 cylinders: 1211 sectors/unit: 1173930 rpm: 3600 interleave: 1 trackskew: 0 cylinderskew: 0 headswitch: 0 # milliseconds track-to-track seek: 0 # milliseconds drivedata: 0 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 81920 16 4.2BSD 1024 8192 16 b: 160000 81936 swap c: 1173930 0 unused 0 0 # "raw" part, don't edit .Ed .Pp Lines starting with a .Ql # mark are comments. .Pp The partition table can have up to 8 entries. It contains the following information: .Bl -tag -width indent .It Ar # The partition identifier is a single letter in the range .Ql a to .Ql h . By convention, partition .Ql c is reserved to describe the entire disk. .It Ar size The size of the partition in sectors, .Cm K (kilobytes - 1024), .Cm M (megabytes - 1024*1024), .Cm G (gigabytes - 1024*1024*1024), .Cm % (percentage of free space .Em after removing any fixed-size partitions other than partition .Ql c ) , or .Cm * (all remaining free space .Em after fixed-size and percentage partitions). For partition .Ql c , a size of .Cm * indicates the entire disk. Lowercase versions of suffixes .Cm K , M , and .Cm G are allowed. Size and suffix should be specified without any spaces between them. .Pp Example: 2097152, 1G, 1024M and 1048576K are all the same size (assuming 512-byte sectors). .It Ar offset The offset of the start of the partition from the beginning of the drive in sectors, or .Cm * to have .Nm calculate the correct offset to use (the end of the previous partition plus one, ignoring partition .Ql c ) . For partition .Ql c , .Cm * will be interpreted as an offset of 0. The first partition should start at offset 16, because the first 16 sectors are reserved for metadata. .It Ar fstype Describes the purpose of the partition. The above example shows all currently used partition types. For .Tn UFS file systems and .Xr ccd 4 partitions, use type .Cm 4.2BSD . For Vinum drives, use type .Cm vinum . Other common types are .Cm swap and .Cm unused . By convention, partition .Ql c represents the entire slice and should be of type .Cm unused , though .Nm does not enforce this convention. The .Nm utility also knows about a number of other partition types, none of which are in current use. (See the definitions starting with .Dv FS_UNUSED in .In sys/disklabel.h for more details.) .It Ar fsize For .Cm 4.2BSD file systems only, the fragment size; see .Xr newfs 8 . .It Ar bsize For .Cm 4.2BSD file systems only, the block size; see .Xr newfs 8 . .It Ar bps/cpg For .Cm 4.2BSD file systems, the number of cylinders in a cylinder group; see .Xr newfs 8 . .El .Sh EXAMPLES Display the label for the first slice of the .Pa da0 disk, as obtained via .Pa /dev/da0s1 : .Pp .Dl "bsdlabel da0s1" .Pp Save the in-core label for .Pa da0s1 into the file .Pa savedlabel . This file can be used with the .Fl R option to restore the label at a later date: .Pp .Dl "bsdlabel da0s1 > savedlabel" .Pp Create a label for .Pa da0s1 : .Pp .Dl "bsdlabel -w /dev/da0s1" .Pp Read the label for .Pa da0s1 , edit it, and install the result: .Pp .Dl "bsdlabel -e da0s1" .Pp Read the on-disk label for .Pa da0s1 , edit it, and display what the new label would be (in sectors). It does .Em not install the new label either in-core or on-disk: .Pp .Dl "bsdlabel -e -n da0s1" .Pp Write a default label on .Pa da0s1 . Use another .Nm Fl e command to edit the partitioning and file system information: .Pp .Dl "bsdlabel -w da0s1" .Pp Restore the on-disk and in-core label for .Pa da0s1 from information in .Pa savedlabel : .Pp .Dl "bsdlabel -R da0s1 savedlabel" .Pp Display what the label would be for .Pa da0s1 using the partition layout in .Pa label_layout . This is useful for determining how much space would be allotted for various partitions with a labeling scheme using .Cm % Ns -based or .Cm * partition sizes: .Pp .Dl "bsdlabel -R -n da0s1 label_layout" .Pp Install a new bootstrap on .Pa da0s1 . The boot code comes from .Pa /boot/boot : .Pp .Dl "bsdlabel -B da0s1" .Pp Install a new label and bootstrap. The bootstrap code comes from the file .Pa newboot in the current working directory: .Pp .Dl "bsdlabel -w -B -b newboot /dev/da0s1" .Pp Completely wipe any prior information on the disk, creating a new bootable disk with a .Tn DOS partition table containing one slice, covering the whole disk. Initialize the label on this slice, then edit it. The .Xr dd 1 commands are optional, but may be necessary for some .Tn BIOS Ns es to properly recognize the disk: .Bd -literal -offset indent dd if=/dev/zero of=/dev/da0 bs=512 count=32 fdisk -BI da0 dd if=/dev/zero of=/dev/da0s1 bs=512 count=32 bsdlabel -w -B da0s1 bsdlabel -e da0s1 .Ed .Pp This is an example disk label that uses some of the new partition size types such as .Cm % , M , G , and .Cm * , which could be used as a source file for .Dq Li "bsdlabel -R ada0s1 new_label_file" : .Bd -literal -offset 4n # /dev/ada0s1: 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 400M 16 4.2BSD 4096 16384 75 # (Cyl. 0 - 812*) b: 1G * swap c: * * unused e: 204800 * 4.2BSD f: 5g * 4.2BSD g: * * 4.2BSD .Ed .Sh DIAGNOSTICS The kernel device drivers will not allow the size of a disk partition to be decreased or the offset of a partition to be changed while it is open. .Sh COMPATIBILITY Due to the use of an -.Vt u_int32_t +.Vt uint32_t to store the number of sectors, .Bx labels are restricted to a maximum of 2^32-1 sectors. This usually means 2TB of disk space. Larger disks should be partitioned using another method such as .Xr gpart 8 . .Pp The various .Bx Ns s all use slightly different versions of .Bx labels and are not generally compatible. .Sh SEE ALSO .Xr ccd 4 , .Xr geom 4 , .Xr md 4 , .Xr disktab 5 , .Xr boot0cfg 8 , .Xr fdisk 8 , .Xr gpart 8 , .Xr newfs 8 Index: stable/9/sbin/bsdlabel =================================================================== --- stable/9/sbin/bsdlabel (revision 290886) +++ stable/9/sbin/bsdlabel (revision 290887) Property changes on: stable/9/sbin/bsdlabel ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/bsdlabel:r231564 Index: stable/9/sbin/newfs_msdos/newfs_msdos.8 =================================================================== --- stable/9/sbin/newfs_msdos/newfs_msdos.8 (revision 290886) +++ stable/9/sbin/newfs_msdos/newfs_msdos.8 (revision 290887) @@ -1,241 +1,241 @@ .\" Copyright (c) 1998 Robert Nordier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2015 .Dt NEWFS_MSDOS 8 .Os .Sh NAME .Nm newfs_msdos .Nd construct a new MS-DOS (FAT) file system .Sh SYNOPSIS .Nm .Op Fl N .Op Fl @ Ar offset .Op Fl B Ar boot .Op Fl C Ar create-size .Op Fl F Ar FAT-type .Op Fl I Ar VolumeId .Op Fl L Ar label .Op Fl O Ar OEM .Op Fl S Ar sector-size .Op Fl a Ar FAT-size .Op Fl b Ar block-size .Op Fl c Ar cluster-size .Op Fl e Ar DirEnts .Op Fl f Ar format .Op Fl h Ar heads .Op Fl i Ar info .Op Fl k Ar backup .Op Fl m Ar media .Op Fl n Ar FATs .Op Fl o Ar hidden .Op Fl r Ar reserved .Op Fl s Ar total .Op Fl u Ar track-size .Ar special .Op Ar disktype .Sh DESCRIPTION The .Nm utility creates a FAT12, FAT16, or FAT32 file system on device or file named .Ar special , using .Xr disktab 5 entry .Ar disktype to determine geometry, if required. .Pp If .Ar special does not contain a .Ar / and .Fl C is not used, it is assumed to be a device name and .Ar /dev/ is prepended to the name to construct the actual device name. To work a file in the current directory use .Ar ./filename .Pp The options are as follow: .Bl -tag -width indent .It Fl N Do not create a file system: just print out parameters. .It Fl @ Ar offset Build the filesystem at the specified offset in bytes in the device or file. A suffix s, k, m, g (lower or upper case) appended to the offset specifies that the number is in sectors, kilobytes, megabytes or gigabytes, respectively. .It Fl B Ar boot Get bootstrap from file. .It Fl C Ar create-size Create the image file with the specified size. A suffix character appended to the size is interpreted as for the .Fl @ option. The file is created by truncating any existing file with the same name and resizing it to the requested size. If the file system supports sparse files, the space occupied on disk may be smaller than the size specified as parameter. .It Fl F Ar FAT-type FAT type (one of 12, 16, or 32). .It Fl I Ar VolumeID Volume ID, a 32 bit number in decimal or hexadecimal (0x...) format. .It Fl L Ar label Volume label (up to 11 characters). The label should consist of only those characters permitted in regular DOS (8+3) filenames. .It Fl O Ar OEM OEM string (up to 8 characters). The default is .Qq Li "BSD4.4 " . .It Fl S Ar sector-size Number of bytes per sector. Acceptable values are powers of 2 in the range 512 through 32768, inclusive. .It Fl a Ar FAT-size Number of sectors per FAT. .It Fl b Ar block-size File system block size (bytes per cluster). This should resolve to an acceptable number of sectors per cluster (see below). .It Fl c Ar cluster-size Sectors per cluster. Acceptable values are powers of 2 in the range 1 through 128. If the block or cluster size are not specified, the code uses a cluster between 512 bytes and 32K depending on the filesystem size. .It Fl e Ar DirEnts Number of root directory entries (FAT12 and FAT16 only). .It Fl f Ar format Specify a standard (floppy disk) format. The standard formats are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200, 1232, 1440, 2880. .It Fl h Ar heads Number of drive heads. .It Fl i Ar info Location of the file system info sector (FAT32 only). A value of 0xffff signifies no info sector. .It Fl k Ar backup Location of the backup boot sector (FAT32 only). A value of 0xffff signifies no backup sector. .It Fl m Ar media Media descriptor (acceptable range 0xf0 to 0xff). .It Fl n Ar FATs Number of FATs. Acceptable values are 1 to 16 inclusive. The default is 2. .It Fl o Ar hidden Number of hidden sectors. .It Fl r Ar reserved Number of reserved sectors. .It Fl s Ar total File system size. .It Fl u Ar track-size Number of sectors per track. .El .Sh NOTES If some parameters (e.g. size, number of sectors, etc.) are not specified through options or disktype, the program tries to generate them automatically. In particular, the size is determined as the device or file size minus the offset specified with the .Fl @ option. When the geometry is not available, it is assumed to be 63 sectors, 255 heads. The size is then rounded to become a multiple of the track size and avoid complaints by some filesystem code. .Pp FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter Block)" in the first of the "reserved" sectors which precede the actual file system. For reference purposes, this structure is presented below. .Bd -literal struct bsbpb { - u_int16_t bpbBytesPerSec; /* [-S] bytes per sector */ - u_int8_t bpbSecPerClust; /* [-c] sectors per cluster */ - u_int16_t bpbResSectors; /* [-r] reserved sectors */ - u_int8_t bpbFATs; /* [-n] number of FATs */ - u_int16_t bpbRootDirEnts; /* [-e] root directory entries */ - u_int16_t bpbSectors; /* [-s] total sectors */ - u_int8_t bpbMedia; /* [-m] media descriptor */ - u_int16_t bpbFATsecs; /* [-a] sectors per FAT */ - u_int16_t bpbSecPerTrack; /* [-u] sectors per track */ - u_int16_t bpbHeads; /* [-h] drive heads */ - u_int32_t bpbHiddenSecs; /* [-o] hidden sectors */ - u_int32_t bpbHugeSectors; /* [-s] big total sectors */ + uint16_t bpbBytesPerSec; /* [-S] bytes per sector */ + uint8_t bpbSecPerClust; /* [-c] sectors per cluster */ + uint16_t bpbResSectors; /* [-r] reserved sectors */ + uint8_t bpbFATs; /* [-n] number of FATs */ + uint16_t bpbRootDirEnts; /* [-e] root directory entries */ + uint16_t bpbSectors; /* [-s] total sectors */ + uint8_t bpbMedia; /* [-m] media descriptor */ + uint16_t bpbFATsecs; /* [-a] sectors per FAT */ + uint16_t bpbSecPerTrack; /* [-u] sectors per track */ + uint16_t bpbHeads; /* [-h] drive heads */ + uint32_t bpbHiddenSecs; /* [-o] hidden sectors */ + uint32_t bpbHugeSectors; /* [-s] big total sectors */ }; /* FAT32 extensions */ struct bsxbpb { - u_int32_t bpbBigFATsecs; /* [-a] big sectors per FAT */ - u_int16_t bpbExtFlags; /* control flags */ - u_int16_t bpbFSVers; /* file system version */ - u_int32_t bpbRootClust; /* root directory start cluster */ - u_int16_t bpbFSInfo; /* [-i] file system info sector */ - u_int16_t bpbBackup; /* [-k] backup boot sector */ + uint32_t bpbBigFATsecs; /* [-a] big sectors per FAT */ + uint16_t bpbExtFlags; /* control flags */ + uint16_t bpbFSVers; /* file system version */ + uint32_t bpbRootClust; /* root directory start cluster */ + uint16_t bpbFSInfo; /* [-i] file system info sector */ + uint16_t bpbBackup; /* [-k] backup boot sector */ }; .Ed .Sh LIMITATION The maximum file size is 4GB, even if the file system itself is bigger. .Sh EXIT STATUS Exit status is 0 on success and 1 on error. .Sh EXAMPLES Create a file system, using default parameters, on .Pa /dev/ada0s1 : .Bd -literal -offset indent newfs_msdos /dev/ada0s1 .Ed .Pp Create a standard 1.44M file system, with volume label .Ar foo , on .Pa /dev/fd0 : .Bd -literal -offset indent newfs_msdos -f 1440 -L foo fd0 .Ed .Pp Create a 30MB image file, with the FAT partition starting 63 sectors within the image file: .Bd -literal -offset indent newfs_msdos -C 30M -@63s ./somefile .Ed .Sh SEE ALSO .Xr disktab 5 , .Xr disklabel 8 , .Xr fdisk 8 , .Xr newfs 8 .Sh HISTORY The .Nm utility first appeared in .Fx 3.0 . .Sh AUTHORS .An Robert Nordier Aq rnordier@FreeBSD.org . Index: stable/9/sbin/newfs_msdos =================================================================== --- stable/9/sbin/newfs_msdos (revision 290886) +++ stable/9/sbin/newfs_msdos (revision 290887) Property changes on: stable/9/sbin/newfs_msdos ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/newfs_msdos:r231564 Index: stable/9/sbin =================================================================== --- stable/9/sbin (revision 290886) +++ stable/9/sbin (revision 290887) Property changes on: stable/9/sbin ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin:r231564 Index: stable/9/share/man/man4/agp.4 =================================================================== --- stable/9/share/man/man4/agp.4 (revision 290886) +++ stable/9/share/man/man4/agp.4 (revision 290887) @@ -1,177 +1,177 @@ .\" Copyright (c) 2001 Yar Tikhiy .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 28, 2007 .Dt AGP 4 .Os .Sh NAME .Nm agp .Nd "generic interface to the Accelerated Graphics Port (AGP)" .Sh SYNOPSIS .Cd "device agp" .Sh DESCRIPTION The .Nm driver provides uniform, abstract methods for controlling the following devices: .Pp .Bl -tag -width "NVIDIA:" -compact .It Ali: M1541, M1621 and M1671 host to AGP bridges .It AMD: 751, 761 and 762 host to AGP bridges .It ATI: RS100, RS200, RS250 and RS300 AGP bridges .It Intel: i820, i840, i845, i850, and i860 host to AGP bridges .It Intel: i810, i810-DC100, i810E, i815, 830M, 845G, 845M, 852GM, 852GME, 855GM, 855GME, 865G, 915G and 915GM SVGA controllers .It Intel: 82443BX, 82443GX, 82443LX, 82815, 82820, 82830, 82840, 82845, 82845G, 82850, 82855, 82855GM, 82860, 82865, 82875P, E7205 and E7505 host to AGP bridges .It NVIDIA: nForce and nForce2 AGP controllers .It SiS: 530, 540, 550, 620, 630, 645, 645DX, 648, 650, 651, 655, 661, 730, 735, 740, 741, 745, 746, 760 and 5591 host to AGP bridges .It VIA: 3296, 82C597, 82C598, 82C691, 82C694X, 82C8363, 8235, 8237, 8361, 8367, 8371, 8377, 8501, 8601, 862x, 8633, 8653, 8703, 8753, 8754, 8763, 8783, KT880, PM800, PM880, PN800, PN880, PT880, XM266 and XN266 host to PCI bridges .El .Pp The most common application of .Nm is for running .Xr X 7 on the Intel i81x controllers. .Sh IOCTLS The following .Xr ioctl 2 operations can be performed on .Pa /dev/agpgart , which are defined in .In sys/agpio.h : .Bl -tag -width indent .It Dv AGPIOC_INFO Returns state of the .Nm system. The result is a pointer to the following structure: .Bd -literal typedef struct _agp_info { agp_version version; /* version of the driver */ - u_int32_t bridge_id; /* bridge vendor/device */ - u_int32_t agp_mode; /* mode info of bridge */ + uint32_t bridge_id; /* bridge vendor/device */ + uint32_t agp_mode; /* mode info of bridge */ off_t aper_base; /* base of aperture */ size_t aper_size; /* size of aperture */ size_t pg_total; /* max pages (swap + system) */ size_t pg_system; /* max pages (system) */ size_t pg_used; /* current pages used */ } agp_info; .Ed .It Dv AGPIOC_ACQUIRE Acquire control of the AGP chipset for use by this client. Returns .Er EBUSY if the AGP chipset is already acquired by another client. .It Dv AGPIOC_RELEASE Release control of the AGP chipset. This does not unbind or free any allocated memory, which is the responsibility of the client to handle if necessary. .It Dv AGPIOC_SETUP Enable the AGP hardware with the relevant mode. This .Xr ioctl 2 takes the following structure: .Bd -literal typedef struct _agp_setup { - u_int32_t agp_mode; /* mode info of bridge */ + uint32_t agp_mode; /* mode info of bridge */ } agp_setup; .Ed .Pp The mode bits are defined in .In sys/agpio.h . .It Dv AGPIOC_ALLOCATE Allocate physical memory suitable for mapping into the AGP aperture. This .Xr ioctl 2 takes the following structure: .Bd -literal typedef struct _agp_allocate { int key; /* tag of allocation */ size_t pg_count; /* number of pages */ - u_int32_t type; /* 0 == normal, other devspec */ - u_int32_t physical; /* device specific (some devices + uint32_t type; /* 0 == normal, other devspec */ + uint32_t physical; /* device specific (some devices * need a phys address of the * actual page behind the gatt * table) */ } agp_allocate; .Ed .Pp Returns a handle to the allocated memory. .It Dv AGPIOC_DEALLOCATE Free the previously allocated memory associated with the handle passed. .It Dv AGPIOC_BIND Bind the allocated memory at given offset with the AGP aperture. Returns .Er EINVAL if the memory is already bound or the offset is not at AGP page boundary. This .Xr ioctl 2 takes the following structure: .Bd -literal typedef struct _agp_bind { int key; /* tag of allocation */ off_t pg_start; /* starting page to populate */ } agp_bind; .Ed .Pp The tag of allocation is the handle returned by .Dv AGPIOC_ALLOCATE . .It Dv AGPIOC_UNBIND Unbind memory from the AGP aperture. Returns .Er EINVAL if the memory is not bound. This .Xr ioctl 2 takes the following structure: .Bd -literal typedef struct _agp_unbind { int key; /* tag of allocation */ - u_int32_t priority; /* priority for paging out */ + uint32_t priority; /* priority for paging out */ } agp_unbind; .Ed .El .Sh FILES .Bl -tag -width ".Pa /dev/agpgart" -compact .It Pa /dev/agpgart AGP device node. .El .Sh SEE ALSO .Xr X 7 Pq Pa ports/x11/xorg .Sh HISTORY The .Nm driver first appeared in .Fx 4.1 . Index: stable/9/share/man/man4/icmp6.4 =================================================================== --- stable/9/share/man/man4/icmp6.4 (revision 290886) +++ stable/9/share/man/man4/icmp6.4 (revision 290887) @@ -1,265 +1,265 @@ .\" $KAME: icmp6.4,v 1.6 2004/12/27 05:30:56 itojun Exp $ .\" $OpenBSD: icmp6.4,v 1.19 2004/12/23 20:33:03 jaredy Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 7, 2012 .Dt ICMP6 4 .Os .Sh NAME .Nm icmp6 .Nd Internet Control Message Protocol for IPv6 .Sh SYNOPSIS .In sys/socket.h .In netinet/in.h .In netinet/icmp6.h .Ft int .Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6 .Sh DESCRIPTION ICMPv6 is the error and control message protocol used by IPv6 and the IPv6 protocol family (see .Xr ip6 4 and .Xr inet6 4 ) . It may be accessed through a .Dq raw socket for network monitoring and diagnostic functions. .Pp The .Fa proto parameter to the .Xr socket 2 call to create an ICMPv6 socket may be obtained from .Xr getprotobyname 3 . ICMPv6 sockets are connectionless, and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, though the .Xr connect 2 call may also be used to fix the destination for future packets (in which case .Xr read 2 or .Xr recv 2 and .Xr write 2 or .Xr send 2 system calls may be used). .Pp Outgoing packets automatically have an IPv6 header prepended to them (based on the destination address). Incoming packets on the socket are received with the IPv6 header and any extension headers removed. .Ss Types ICMPv6 messages are classified according to the type and code fields present in the ICMPv6 header. The abbreviations for the types and codes may be used in rules in .Xr pf.conf 5 . The following types are defined: .Bl -column x xxxxxxxxxxxx -offset indent .It Sy Num Ta Sy Abbrev. Ta Sy Description .It 1 Ta unreach Ta "Destination unreachable" .It 2 Ta toobig Ta "Packet too big" .It 3 Ta timex Ta "Time exceeded" .It 4 Ta paramprob Ta "Invalid IPv6 header" .It 128 Ta echoreq Ta "Echo service request" .It 129 Ta echorep Ta "Echo service reply" .It 130 Ta groupqry Ta "Group membership query" .It 130 Ta listqry Ta "Multicast listener query" .It 131 Ta grouprep Ta "Group membership report" .It 131 Ta listenrep Ta "Multicast listener report" .It 132 Ta groupterm Ta "Group membership termination" .It 132 Ta listendone Ta "Multicast listener done" .It 133 Ta routersol Ta "Router solicitation" .It 134 Ta routeradv Ta "Router advertisement" .It 135 Ta neighbrsol Ta "Neighbor solicitation" .It 136 Ta neighbradv Ta "Neighbor advertisement" .It 137 Ta redir Ta "Shorter route exists" .It 138 Ta routrrenum Ta "Route renumbering" .It 139 Ta fqdnreq Ta "FQDN query" .It 139 Ta niqry Ta "Node information query" .It 139 Ta wrureq Ta "Who-are-you request" .It 140 Ta fqdnrep Ta "FQDN reply" .It 140 Ta nirep Ta "Node information reply" .It 140 Ta wrurep Ta "Who-are-you reply" .It 200 Ta mtraceresp Ta "mtrace response" .It 201 Ta mtrace Ta "mtrace messages" .El .Pp The following codes are defined: .Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent .It Sy Num Ta Sy Abbrev. Ta Sy Type Ta .Sy Description .It 0 Ta noroute-unr Ta unreach Ta "No route to destination" .It 1 Ta admin-unr Ta unreach Ta "Administratively prohibited" .It 2 Ta beyond-unr Ta unreach Ta "Beyond scope of source address" .It 2 Ta notnbr-unr Ta unreach Ta "Not a neighbor (obsolete)" .It 3 Ta addr-unr Ta unreach Ta "Address unreachable" .It 4 Ta port-unr Ta unreach Ta "Port unreachable" .It 0 Ta transit Ta timex Ta "Time exceeded in transit" .It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly" .It 0 Ta badhead Ta paramprob Ta "Erroneous header field" .It 1 Ta nxthdr Ta paramprob Ta "Unrecognized next header" .It 2 Ta "" Ta redir Ta "Unrecognized option" .It 0 Ta redironlink Ta redir Ta "Redirection to on-link node" .It 1 Ta redirrouter Ta redir Ta "Redirection to better router" .El .Ss Headers All ICMPv6 messages are prefixed with an ICMPv6 header. This header corresponds to the .Vt icmp6_hdr structure and has the following definition: .Bd -literal -offset indent struct icmp6_hdr { - u_int8_t icmp6_type; /* type field */ - u_int8_t icmp6_code; /* code field */ - u_int16_t icmp6_cksum; /* checksum field */ + uint8_t icmp6_type; /* type field */ + uint8_t icmp6_code; /* code field */ + uint16_t icmp6_cksum; /* checksum field */ union { - u_int32_t icmp6_un_data32[1]; /* type-specific */ - u_int16_t icmp6_un_data16[2]; /* type-specific */ - u_int8_t icmp6_un_data8[4]; /* type-specific */ + uint32_t icmp6_un_data32[1]; /* type-specific */ + uint16_t icmp6_un_data16[2]; /* type-specific */ + uint8_t icmp6_un_data8[4]; /* type-specific */ } icmp6_dataun; } __packed; #define icmp6_data32 icmp6_dataun.icmp6_un_data32 #define icmp6_data16 icmp6_dataun.icmp6_un_data16 #define icmp6_data8 icmp6_dataun.icmp6_un_data8 #define icmp6_pptr icmp6_data32[0] /* parameter prob */ #define icmp6_mtu icmp6_data32[0] /* packet too big */ #define icmp6_id icmp6_data16[0] /* echo request/reply */ #define icmp6_seq icmp6_data16[1] /* echo request/reply */ #define icmp6_maxdelay icmp6_data16[0] /* mcast group membership*/ .Ed .Pp .Va icmp6_type describes the type of the message. Suitable values are defined in .Aq Pa netinet/icmp6.h . .Va icmp6_code describes the sub-type of the message and depends on .Va icmp6_type . .Va icmp6_cksum contains the checksum for the message and is filled in by the kernel on outgoing messages. The other fields are used for type-specific purposes. .Ss Filters Because of the extra functionality of ICMPv6 in comparison to ICMPv4, a larger number of messages may be potentially received on an ICMPv6 socket. Input filters may therefore be used to restrict input to a subset of the incoming ICMPv6 messages so only interesting messages are returned by the .Xr recv 2 family of calls to an application. .Pp The .Vt icmp6_filter structure may be used to refine the input message set according to the ICMPv6 type. By default, all messages types are allowed on newly created raw ICMPv6 sockets. The following macros may be used to refine the input set: .Bl -tag -width Ds .It Fn "void ICMP6_FILTER_SETPASSALL" "struct icmp6_filter *filterp" Allow all incoming messages. .Va filterp is modified to allow all message types. .It Fn "void ICMP6_FILTER_SETBLOCKALL" "struct icmp6_filter *filterp" Ignore all incoming messages. .Va filterp is modified to ignore all message types. .It Xo .Ft void .Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp" .Xc Allow ICMPv6 messages with the given .Fa type . .Va filterp is modified to allow such messages. .It Xo .Ft void .Fn ICMP6_FILTER_SETBLOCK" "int type" "struct icmp6_filter *filterp" .Xc Ignore ICMPv6 messages with the given .Fa type . .Va filterp is modified to ignore such messages. .It Xo .Ft int .Fn ICMP6_FILTER_WILLPASS" "int type" "const struct icmp6_filter *filterp" .Xc Determine if the given filter will allow an ICMPv6 message of the given type. .It Xo .Ft int .Fn ICMP6_FILTER_WILLBLOCK" "int type" "const struct icmp6_filter *filterp" .Xc Determine if the given filter will ignore an ICMPv6 message of the given type. .El .Pp The .Xr getsockopt 2 and .Xr setsockopt 2 calls may be used to obtain and install the filter on ICMPv6 sockets at option level .Dv IPPROTO_ICMPV6 and name .Dv ICMP6_FILTER with a pointer to the .Vt icmp6_filter structure as the option value. .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr setsockopt 2 , .Xr socket 2 , .Xr getprotobyname 3 , .Xr inet6 4 , .Xr ip6 4 , .Xr netintro 4 .Rs .%A W. Stevens .%A M. Thomas .%T Advanced Sockets API for IPv6 .%N RFC 2292 .%D February 1998 .Re .Rs .%A A. Conta .%A S. Deering .%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ "Protocol Version 6 (IPv6) Specification" .%N RFC 2463 .%D December 1998 .Re Index: stable/9/share/man/man4/ip6.4 =================================================================== --- stable/9/share/man/man4/ip6.4 (revision 290886) +++ stable/9/share/man/man4/ip6.4 (revision 290887) @@ -1,701 +1,701 @@ .\" $KAME: ip6.4,v 1.23 2005/01/11 05:56:25 itojun Exp $ .\" $OpenBSD: ip6.4,v 1.21 2005/01/06 03:50:46 itojun Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 13, 2011 .Dt IP6 4 .Os .Sh NAME .Nm ip6 .Nd Internet Protocol version 6 (IPv6) network layer .Sh SYNOPSIS .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET6 SOCK_RAW proto .Sh DESCRIPTION The IPv6 network layer is used by the IPv6 protocol family for transporting data. IPv6 packets contain an IPv6 header that is not provided as part of the payload contents when passed to an application. IPv6 header options affect the behavior of this protocol and may be used by high-level protocols (such as the .Xr tcp 4 and .Xr udp 4 protocols) as well as directly by .Dq raw sockets , which process IPv6 messages at a lower-level and may be useful for developing new protocols and special-purpose applications. .Ss Header All IPv6 packets begin with an IPv6 header. When data received by the kernel are passed to the application, this header is not included in buffer, even when raw sockets are being used. Likewise, when data are sent to the kernel for transmit from the application, the buffer is not examined for an IPv6 header: the kernel always constructs the header. To directly access IPv6 headers from received packets and specify them as part of the buffer passed to the kernel, link-level access .Po .Xr bpf 4 , for example .Pc must instead be utilized. .Pp The header has the following definition: .Bd -literal -offset indent struct ip6_hdr { union { struct ip6_hdrctl { - u_int32_t ip6_un1_flow; /* 20 bits of flow ID */ - u_int16_t ip6_un1_plen; /* payload length */ - u_int8_t ip6_un1_nxt; /* next header */ - u_int8_t ip6_un1_hlim; /* hop limit */ + uint32_t ip6_un1_flow; /* 20 bits of flow ID */ + uint16_t ip6_un1_plen; /* payload length */ + uint8_t ip6_un1_nxt; /* next header */ + uint8_t ip6_un1_hlim; /* hop limit */ } ip6_un1; - u_int8_t ip6_un2_vfc; /* version and class */ + uint8_t ip6_un2_vfc; /* version and class */ } ip6_ctlun; struct in6_addr ip6_src; /* source address */ struct in6_addr ip6_dst; /* destination address */ } __packed; #define ip6_vfc ip6_ctlun.ip6_un2_vfc #define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow #define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen #define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt #define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim #define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim .Ed .Pp All fields are in network-byte order. Any options specified (see .Sx Options below) must also be specified in network-byte order. .Pp .Va ip6_flow specifies the flow ID. .Va ip6_plen specifies the payload length. .Va ip6_nxt specifies the type of the next header. .Va ip6_hlim specifies the hop limit. .Pp The top 4 bits of .Va ip6_vfc specify the class and the bottom 4 bits specify the version. .Pp .Va ip6_src and .Va ip6_dst specify the source and destination addresses. .Pp The IPv6 header may be followed by any number of extension headers that start with the following generic definition: .Bd -literal -offset indent struct ip6_ext { - u_int8_t ip6e_nxt; - u_int8_t ip6e_len; + uint8_t ip6e_nxt; + uint8_t ip6e_len; } __packed; .Ed .Ss Options IPv6 allows header options on packets to manipulate the behavior of the protocol. These options and other control requests are accessed with the .Xr getsockopt 2 and .Xr setsockopt 2 system calls at level .Dv IPPROTO_IPV6 and by using ancillary data in .Xr recvmsg 2 and .Xr sendmsg 2 . They can be used to access most of the fields in the IPv6 header and extension headers. .Pp The following socket options are supported: .Bl -tag -width Ds .\" .It Dv IPV6_OPTIONS .It Dv IPV6_UNICAST_HOPS Fa "int *" Get or set the default hop limit header field for outgoing unicast datagrams sent on this socket. .\" .It Dv IPV6_RECVOPTS Fa "int *" .\" Get or set the status of whether all header options will be .\" delivered along with the datagram when it is received. .\" .It Dv IPV6_RECVRETOPTS Fa "int *" .\" Get or set the status of whether header options will be delivered .\" for reply. .\" .It Dv IPV6_RECVDSTADDR Fa "int *" .\" Get or set the status of whether datagrams are received with .\" destination addresses. .\" .It Dv IPV6_RETOPTS .\" Get or set IPv6 options. .It Dv IPV6_MULTICAST_IF Fa "u_int *" Get or set the interface from which multicast packets will be sent. For hosts with multiple interfaces, each multicast transmission is sent from the primary network interface. The interface is specified as its index as provided by .Xr if_nametoindex 3 . A value of zero specifies the default interface. .It Dv IPV6_MULTICAST_HOPS Fa "int *" Get or set the default hop limit header field for outgoing multicast datagrams sent on this socket. This option controls the scope of multicast datagram transmissions. .Pp Datagrams with a hop limit of 1 are not forwarded beyond the local network. Multicast datagrams with a hop limit of zero will not be transmitted on any network but may be delivered locally if the sending host belongs to the destination group and if multicast loopback (see below) has not been disabled on the sending socket. Multicast datagrams with a hop limit greater than 1 may be forwarded to the other networks if a multicast router (such as .Xr mrouted 8 Pq Pa ports/net/mrouted ) is attached to the local network. .It Dv IPV6_MULTICAST_LOOP Fa "u_int *" Get or set the status of whether multicast datagrams will be looped back for local delivery when a multicast datagram is sent to a group to which the sending host belongs. .Pp This option improves performance for applications that may have no more than one instance on a single host (such as a router daemon) by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing program) or for which the sender does not belong to the destination group (such as a time-querying program). .Pp A multicast datagram sent with an initial hop limit greater than 1 may be delivered to the sending host on a different interface from that on which it was sent if the host belongs to the destination group on that other interface. The multicast loopback control option has no effect on such delivery. .It Dv IPV6_JOIN_GROUP Fa "struct ipv6_mreq *" Join a multicast group. A host must become a member of a multicast group before it can receive datagrams sent to the group. .Bd -literal struct ipv6_mreq { struct in6_addr ipv6mr_multiaddr; unsigned int ipv6mr_interface; }; .Ed .Pp .Va ipv6mr_interface may be set to zeroes to choose the default multicast interface or to the index of a particular multicast-capable interface if the host is multihomed. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. .Pp If the multicast address is unspecified (i.e., all zeroes), messages from all multicast addresses will be accepted by this group. Note that setting to this value requires superuser privileges. .It Dv IPV6_LEAVE_GROUP Fa "struct ipv6_mreq *" Drop membership from the associated multicast group. Memberships are automatically dropped when the socket is closed or when the process exits. .It Dv IPV6_PORTRANGE Fa "int *" Get or set the allocation policy of ephemeral ports for when the kernel automatically binds a local address to this socket. The following values are available: .Pp .Bl -tag -width IPV6_PORTRANGE_DEFAULT -compact .It Dv IPV6_PORTRANGE_DEFAULT Use the regular range of non-reserved ports (varies, see .Xr ip 4 ) . .It Dv IPV6_PORTRANGE_HIGH Use a high range (varies, see .Xr ip 4 ) . .It Dv IPV6_PORTRANGE_LOW Use a low, reserved range (600\-1023, see .Xr ip 4 ) . .El .It Dv IPV6_PKTINFO Fa "int *" Get or set whether additional information about subsequent packets will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The information is stored in the following structure in the ancillary data returned: .Bd -literal struct in6_pktinfo { struct in6_addr ipi6_addr; /* src/dst IPv6 address */ unsigned int ipi6_ifindex; /* send/recv if index */ }; .Ed .It Dv IPV6_HOPLIMIT Fa "int *" Get or set whether the hop limit header field from subsequent packets will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The value is stored as an .Vt int in the ancillary data returned. .\" .It Dv IPV6_NEXTHOP Fa "int *" .\" Get or set whether the address of the next hop for subsequent .\" packets will be provided as ancillary data along with the payload in .\" subsequent .\" .Xr recvmsg 2 .\" calls. .\" The option is stored as a .\" .Vt sockaddr .\" structure in the ancillary data returned. .\" .Pp .\" This option requires superuser privileges. .It Dv IPV6_HOPOPTS Fa "int *" Get or set whether the hop-by-hop options from subsequent packets will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The option is stored in the following structure in the ancillary data returned: .Bd -literal struct ip6_hbh { - u_int8_t ip6h_nxt; /* next header */ - u_int8_t ip6h_len; /* length in units of 8 octets */ + uint8_t ip6h_nxt; /* next header */ + uint8_t ip6h_len; /* length in units of 8 octets */ /* followed by options */ } __packed; .Ed .Pp The .Fn inet6_option_space routine and family of routines may be used to manipulate this data. .Pp This option requires superuser privileges. .It Dv IPV6_DSTOPTS Fa "int *" Get or set whether the destination options from subsequent packets will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The option is stored in the following structure in the ancillary data returned: .Bd -literal struct ip6_dest { - u_int8_t ip6d_nxt; /* next header */ - u_int8_t ip6d_len; /* length in units of 8 octets */ + uint8_t ip6d_nxt; /* next header */ + uint8_t ip6d_len; /* length in units of 8 octets */ /* followed by options */ } __packed; .Ed .Pp The .Fn inet6_option_space routine and family of routines may be used to manipulate this data. .Pp This option requires superuser privileges. .It Dv IPV6_TCLASS Fa "int *" Get or set the value of the traffic class field used for outgoing datagrams on this socket. The value must be between \-1 and 255. A value of \-1 resets to the default value. .It Dv IPV6_RECVTCLASS Fa "int *" Get or set the status of whether the traffic class header field will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The header field is stored as a single value of type .Vt int . .It Dv IPV6_RTHDR Fa "int *" Get or set whether the routing header from subsequent packets will be provided as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. The header is stored in the following structure in the ancillary data returned: .Bd -literal struct ip6_rthdr { - u_int8_t ip6r_nxt; /* next header */ - u_int8_t ip6r_len; /* length in units of 8 octets */ - u_int8_t ip6r_type; /* routing type */ - u_int8_t ip6r_segleft; /* segments left */ + uint8_t ip6r_nxt; /* next header */ + uint8_t ip6r_len; /* length in units of 8 octets */ + uint8_t ip6r_type; /* routing type */ + uint8_t ip6r_segleft; /* segments left */ /* followed by routing-type-specific data */ } __packed; .Ed .Pp The .Fn inet6_option_space routine and family of routines may be used to manipulate this data. .Pp This option requires superuser privileges. .It Dv IPV6_PKTOPTIONS Fa "struct cmsghdr *" Get or set all header options and extension headers at one time on the last packet sent or received on the socket. All options must fit within the size of an mbuf (see .Xr mbuf 9 ) . Options are specified as a series of .Vt cmsghdr structures followed by corresponding values. .Va cmsg_level is set to .Dv IPPROTO_IPV6 , .Va cmsg_type to one of the other values in this list, and trailing data to the option value. When setting options, if the length .Va optlen to .Xr setsockopt 2 is zero, all header options will be reset to their default values. Otherwise, the length should specify the size the series of control messages consumes. .Pp Instead of using .Xr sendmsg 2 to specify option values, the ancillary data used in these calls that correspond to the desired header options may be directly specified as the control message in the series of control messages provided as the argument to .Xr setsockopt 2 . .It Dv IPV6_CHECKSUM Fa "int *" Get or set the byte offset into a packet where the 16-bit checksum is located. When set, this byte offset is where incoming packets will be expected to have checksums of their data stored and where outgoing packets will have checksums of their data computed and stored by the kernel. A value of \-1 specifies that no checksums will be checked on incoming packets and that no checksums will be computed or stored on outgoing packets. The offset of the checksum for ICMPv6 sockets cannot be relocated or turned off. .It Dv IPV6_V6ONLY Fa "int *" Get or set whether only IPv6 connections can be made to this socket. For wildcard sockets, this can restrict connections to IPv6 only. .\"With .\".Ox .\"IPv6 sockets are always IPv6-only, so the socket option is read-only .\"(not modifiable). .It Dv IPV6_FAITH Fa "int *" Get or set the status of whether .Xr faith 4 connections can be made to this socket. .It Dv IPV6_USE_MIN_MTU Fa "int *" Get or set whether the minimal IPv6 maximum transmission unit (MTU) size will be used to avoid fragmentation from occurring for subsequent outgoing datagrams. .It Dv IPV6_AUTH_LEVEL Fa "int *" Get or set the .Xr ipsec 4 authentication level. .It Dv IPV6_ESP_TRANS_LEVEL Fa "int *" Get or set the ESP transport level. .It Dv IPV6_ESP_NETWORK_LEVEL Fa "int *" Get or set the ESP encapsulation level. .It Dv IPV6_IPCOMP_LEVEL Fa "int *" Get or set the .Xr ipcomp 4 level. .El .Pp The .Dv IPV6_PKTINFO , .\" .Dv IPV6_NEXTHOP , .Dv IPV6_HOPLIMIT , .Dv IPV6_HOPOPTS , .Dv IPV6_DSTOPTS , and .Dv IPV6_RTHDR options will return ancillary data along with payload contents in subsequent .Xr recvmsg 2 calls with .Va cmsg_level set to .Dv IPPROTO_IPV6 and .Va cmsg_type set to respective option name value (e.g., .Dv IPV6_HOPTLIMIT ) . These options may also be used directly as ancillary .Va cmsg_type values in .Xr sendmsg 2 to set options on the packet being transmitted by the call. The .Va cmsg_level value must be .Dv IPPROTO_IPV6 . For these options, the ancillary data object value format is the same as the value returned as explained for each when received with .Xr recvmsg 2 . .Pp Note that using .Xr sendmsg 2 to specify options on particular packets works only on UDP and raw sockets. To manipulate header options for packets on TCP sockets, only the socket options may be used. .Pp In some cases, there are multiple APIs defined for manipulating an IPv6 header field. A good example is the outgoing interface for multicast datagrams, which can be set by the .Dv IPV6_MULTICAST_IF socket option, through the .Dv IPV6_PKTINFO option, and through the .Va sin6_scope_id field of the socket address passed to the .Xr sendto 2 system call. .Pp Resolving these conflicts is implementation dependent. This implementation determines the value in the following way: options specified by using ancillary data (i.e., .Xr sendmsg 2 ) are considered first, options specified by using .Dv IPV6_PKTOPTIONS to set .Dq sticky options are considered second, options specified by using the individual, basic, and direct socket options (e.g., .Dv IPV6_UNICAST_HOPS ) are considered third, and options specified in the socket address supplied to .Xr sendto 2 are the last choice. .Ss Multicasting IPv6 multicasting is supported only on .Dv AF_INET6 sockets of type .Dv SOCK_DGRAM and .Dv SOCK_RAW , and only on networks where the interface driver supports multicasting. Socket options (see above) that manipulate membership of multicast groups and other multicast options include .Dv IPV6_MULTICAST_IF , .Dv IPV6_MULTICAST_HOPS , .Dv IPV6_MULTICAST_LOOP , .Dv IPV6_LEAVE_GROUP , and .Dv IPV6_JOIN_GROUP . .Ss Raw Sockets Raw IPv6 sockets are connectionless and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, although the .Xr connect 2 call may be used to fix the destination address for future outgoing packets so that .Xr send 2 may instead be used and the .Xr bind 2 call may be used to fix the source address for future outgoing packets instead of having the kernel choose a source address. .Pp By using .Xr connect 2 or .Xr bind 2 , raw socket input is constrained to only packets with their source address matching the socket destination address if .Xr connect 2 was used and to packets with their destination address matching the socket source address if .Xr bind 2 was used. .Pp If the .Ar proto argument to .Xr socket 2 is zero, the default protocol .Pq Dv IPPROTO_RAW is used for outgoing packets. For incoming packets, protocols recognized by kernel are .Sy not passed to the application socket (e.g., .Xr tcp 4 and .Xr udp 4 ) except for some ICMPv6 messages. The ICMPv6 messages not passed to raw sockets include echo, timestamp, and address mask requests. If .Ar proto is non-zero, only packets with this protocol will be passed to the socket. .Pp IPv6 fragments are also not passed to application sockets until they have been reassembled. If reception of all packets is desired, link-level access (such as .Xr bpf 4 ) must be used instead. .Pp Outgoing packets automatically have an IPv6 header prepended to them (based on the destination address and the protocol number the socket was created with). Incoming packets are received by an application without the IPv6 header or any extension headers. .Pp Outgoing packets will be fragmented automatically by the kernel if they are too large. Incoming packets will be reassembled before being sent to the raw socket, so packet fragments or fragment headers will never be seen on a raw socket. .Sh EXAMPLES The following determines the hop limit on the next packet received: .Bd -literal struct iovec iov[2]; u_char buf[BUFSIZ]; struct cmsghdr *cm; struct msghdr m; int found, optval; u_char data[2048]; /* Create socket. */ (void)memset(&m, 0, sizeof(m)); (void)memset(&iov, 0, sizeof(iov)); iov[0].iov_base = data; /* buffer for packet payload */ iov[0].iov_len = sizeof(data); /* expected packet length */ m.msg_name = &from; /* sockaddr_in6 of peer */ m.msg_namelen = sizeof(from); m.msg_iov = iov; m.msg_iovlen = 1; m.msg_control = (caddr_t)buf; /* buffer for control messages */ m.msg_controllen = sizeof(buf); /* * Enable the hop limit value from received packets to be * returned along with the payload. */ optval = 1; if (setsockopt(s, IPPROTO_IPV6, IPV6_HOPLIMIT, &optval, sizeof(optval)) == -1) err(1, "setsockopt"); found = 0; while (!found) { if (recvmsg(s, &m, 0) == -1) err(1, "recvmsg"); for (cm = CMSG_FIRSTHDR(&m); cm != NULL; cm = CMSG_NXTHDR(&m, cm)) { if (cm->cmsg_level == IPPROTO_IPV6 && cm->cmsg_type == IPV6_HOPLIMIT && cm->cmsg_len == CMSG_LEN(sizeof(int))) { found = 1; (void)printf("hop limit: %d\en", *(int *)CMSG_DATA(cm)); break; } } } .Ed .Sh DIAGNOSTICS A socket operation may fail with one of the following errors returned: .Bl -tag -width EADDRNOTAVAILxx .It Bq Er EISCONN when trying to establish a connection on a socket which already has one or when trying to send a datagram with the destination address specified and the socket is already connected. .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is specified, and the socket has not been connected. .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure. .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .It Bq Er EACCES when an attempt is made to create a raw IPv6 socket by a non-privileged process. .El .Pp The following errors specific to IPv6 may occur when setting or getting header options: .Bl -tag -width EADDRNOTAVAILxx .It Bq Er EINVAL An unknown socket option name was given. .It Bq Er EINVAL An ancillary data object was improperly formed. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr setsockopt 2 , .Xr socket 2 , .\" .Xr inet6_option_space 3 , .\" .Xr inet6_rthdr_space 3 , .Xr if_nametoindex 3 , .Xr bpf 4 , .Xr icmp6 4 , .Xr ip 4 , .Xr inet6 4 , .Xr netintro 4 , .Xr tcp 4 , .Xr udp 4 .Rs .%A W. Stevens .%A M. Thomas .%T Advanced Sockets API for IPv6 .%R RFC 2292 .%D February 1998 .Re .Rs .%A S. Deering .%A R. Hinden .%T Internet Protocol, Version 6 (IPv6) Specification .%R RFC 2460 .%D December 1998 .Re .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC 2553 .%D March 1999 .Re .Rs .%A W. Stevens .%A B. Fenner .%A A. Rudoff .%T UNIX Network Programming, third edition .Re .Sh STANDARDS Most of the socket options are defined in RFC 2292 or RFC 2553. The .Dv IPV6_V6ONLY socket option is defined in RFC 3493 Section 5.3. The .Dv IPV6_PORTRANGE socket option and the conflict resolution rule are not defined in the RFCs and should be considered implementation dependent. Index: stable/9/share/man/man4/mem.4 =================================================================== --- stable/9/share/man/man4/mem.4 (revision 290886) +++ stable/9/share/man/man4/mem.4 (revision 290887) @@ -1,211 +1,211 @@ .\" Copyright (c) 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mem.4 5.3 (Berkeley) 5/2/91 .\" $FreeBSD$ .\" .Dd October 3, 2004 .Dt MEM 4 .Os .Sh NAME .Nm mem , .Nm kmem .Nd memory files .Sh SYNOPSIS .Cd "device mem" .Sh DESCRIPTION The special file .Pa /dev/mem is an interface to the physical memory of the computer. Byte offsets in this file are interpreted as physical memory addresses. Reading and writing this file is equivalent to reading and writing memory itself. Only offsets within the bounds of .Pa /dev/mem are allowed. .Pp Kernel virtual memory is accessed through the interface .Pa /dev/kmem in the same manner as .Pa /dev/mem . Only kernel virtual addresses that are currently mapped to memory are allowed. .Pp On .Tn ISA the .Tn I/O memory space begins at physical address 0x000a0000 and runs to 0x00100000. The per-process data size for the current process is .Dv UPAGES long, and ends at virtual address 0xf0000000. .Sh IOCTL INTERFACE Several architectures allow attributes to be associated with ranges of physical memory. These attributes can be manipulated via .Fn ioctl calls performed on .Pa /dev/mem . Declarations and data types are to be found in .In sys/memrange.h . .Pp The specific attributes, and number of programmable ranges may vary between architectures. The full set of supported attributes is: .Bl -tag -width indent .It Dv MDF_UNCACHEABLE The region is not cached. .It Dv MDF_WRITECOMBINE Writes to the region may be combined or performed out of order. .It Dv MDF_WRITETHROUGH Writes to the region are committed synchronously. .It Dv MDF_WRITEBACK Writes to the region are committed asynchronously. .It Dv MDF_WRITEPROTECT The region cannot be written to. .El .Pp Memory ranges are described by .Vt struct mem_range_desc : .Bd -literal -offset indent -u_int64_t mr_base; /\(** physical base address \(**/ -u_int64_t mr_len; /\(** physical length of region \(**/ +uint64_t mr_base; /\(** physical base address \(**/ +uint64_t mr_len; /\(** physical length of region \(**/ int mr_flags; /\(** attributes of region \(**/ char mr_owner[8]; .Ed .Pp In addition to the region attributes listed above, the following flags may also be set in the .Fa mr_flags field: .Bl -tag -width indent .It MDF_FIXBASE The region's base address cannot be changed. .It MDF_FIXLEN The region's length cannot be changed. .It MDF_FIRMWARE The region is believed to have been established by the system firmware. .It MDF_ACTIVE The region is currently active. .It MDF_BOGUS We believe the region to be invalid or otherwise erroneous. .It MDF_FIXACTIVE The region cannot be disabled. .It MDF_BUSY The region is currently owned by another process and may not be altered. .El .Pp Operations are performed using .Fa struct mem_range_op : .Bd -literal -offset indent struct mem_range_desc *mo_desc; int mo_arg[2]; .Ed .Pp The .Dv MEMRANGE_GET ioctl is used to retrieve current memory range attributes. If .Va mo_arg[0] is set to 0, it will be updated with the total number of memory range descriptors. If greater than 0, the array at .Va mo_desc will be filled with a corresponding number of descriptor structures, or the maximum, whichever is less. .Pp The .Dv MEMRANGE_SET ioctl is used to add, alter and remove memory range attributes. A range with the .Dv MDF_FIXACTIVE flag may not be removed; a range with the .Dv MDF_BUSY flag may not be removed or updated. .Pp .Va mo_arg[0] should be set to .Dv MEMRANGE_SET_UPDATE to update an existing or establish a new range, or to .Dv MEMRANGE_SET_REMOVE to remove a range. .Sh RETURN VALUES .Bl -tag -width Er .It Bq Er EOPNOTSUPP Memory range operations are not supported on this architecture. .It Bq Er ENXIO No memory range descriptors are available (e.g.\& firmware has not enabled any). .It Bq Er EINVAL The memory range supplied as an argument is invalid or overlaps another range in a fashion not supported by this architecture. .It Bq Er EBUSY An attempt to remove or update a range failed because the range is busy. .It Bq Er ENOSPC An attempt to create a new range failed due to a shortage of hardware resources (e.g.\& descriptor slots). .It Bq Er ENOENT An attempt to remove a range failed because no range matches the descriptor base/length supplied. .It Bq Er EPERM An attempt to remove a range failed because the range is permanently enabled. .El .Sh FILES .Bl -tag -width /dev/kmem -compact .It Pa /dev/mem .It Pa /dev/kmem .El .Sh SEE ALSO .Xr kvm 3 , .Xr memcontrol 8 .Sh HISTORY The .Nm mem and .Nm kmem files appeared in .At v6 . The ioctl interface for memory range attributes was added in .Fx 3.2 . .Sh BUGS Busy range attributes are not yet managed correctly. .Pp This device is required for all users of .Xr kvm 3 to operate. Index: stable/9/share/man/man4/mtio.4 =================================================================== --- stable/9/share/man/man4/mtio.4 (revision 290886) +++ stable/9/share/man/man4/mtio.4 (revision 290887) @@ -1,315 +1,315 @@ .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mtio.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd February 11, 1996 .Dt MTIO 4 .Os .Sh NAME .Nm mtio .Nd FreeBSD magtape interface .Sh DESCRIPTION The special files named .Pa /dev/[n]sa* refer to SCSI tape drives, which may be attached to the system. .Pa /dev/[n]sa*.ctl are control devices that can be used to issue ioctls to the SCSI tape driver to set parameters that are required to last beyond the unmounting of a tape. .Pp The rewind devices automatically rewind when the last requested read, write or seek has finished, or the end of the tape has been reached. The letter .Ql n is usually prepended to the name of the no-rewind devices. .Pp Tapes can be written with either fixed length records or variable length records. See .Xr sa 4 for more information. Two end-of-file markers mark the end of a tape, and one end-of-file marker marks the end of a tape file. If the tape is not to be rewound it is positioned with the head in between the two tape marks, where the next write will over write the second end-of-file marker. .Pp All of the magtape devices may be manipulated with the .Xr mt 1 command. .Pp A number of .Xr ioctl 2 operations are available on raw magnetic tape. The following definitions are from .In sys/mtio.h : .Bd -literal #ifndef _SYS_MTIO_H_ #define _SYS_MTIO_H_ #ifndef _KERNEL #include #endif #include /* * Structures and definitions for mag tape io control commands */ /* structure for MTIOCTOP - mag tape op command */ struct mtop { short mt_op; /* operations defined below */ daddr_t mt_count; /* how many of them */ }; /* operations */ #define MTWEOF 0 /* write an end-of-file record */ #define MTFSF 1 /* forward space file */ #define MTBSF 2 /* backward space file */ #define MTFSR 3 /* forward space record */ #define MTBSR 4 /* backward space record */ #define MTREW 5 /* rewind */ #define MTOFFL 6 /* rewind and put the drive offline */ #define MTNOP 7 /* no operation, sets status only */ #define MTCACHE 8 /* enable controller cache */ #define MTNOCACHE 9 /* disable controller cache */ #if defined(__FreeBSD__) /* Set block size for device. If device is a variable size dev */ /* a non zero parameter will change the device to a fixed block size */ /* device with block size set to that of the parameter passed in. */ /* Resetting the block size to 0 will restore the device to a variable */ /* block size device. */ #define MTSETBSIZ 10 /* Set density values for device. Sets the value for the opened mode only. */ #define MTSETDNSTY 11 #define MTERASE 12 /* erase to EOM */ #define MTEOD 13 /* Space to EOM */ #define MTCOMP 14 /* select compression mode 0=off, 1=def */ #define MTRETENS 15 /* re-tension tape */ #define MTWSS 16 /* write setmark(s) */ #define MTFSS 17 /* forward space setmark */ #define MTBSS 18 /* backward space setmark */ #define MT_COMP_ENABLE 0xffffffff #define MT_COMP_DISABLED 0xfffffffe #define MT_COMP_UNSUPP 0xfffffffd /* * Values in mt_dsreg that say what the device is doing */ #define MTIO_DSREG_NIL 0 /* Unknown */ #define MTIO_DSREG_REST 1 /* Doing Nothing */ #define MTIO_DSREG_RBSY 2 /* Communicating with tape (but no motion) */ #define MTIO_DSREG_WR 20 /* Writing */ #define MTIO_DSREG_FMK 21 /* Writing Filemarks */ #define MTIO_DSREG_ZER 22 /* Erasing */ #define MTIO_DSREG_RD 30 /* Reading */ #define MTIO_DSREG_FWD 40 /* Spacing Forward */ #define MTIO_DSREG_REV 41 /* Spacing Reverse */ #define MTIO_DSREG_POS 42 /* Hardware Positioning (direction unknown) */ #define MTIO_DSREG_REW 43 /* Rewinding */ #define MTIO_DSREG_TEN 44 /* Retensioning */ #define MTIO_DSREG_UNL 45 /* Unloading */ #define MTIO_DSREG_LD 46 /* Loading */ #endif /* __FreeBSD__ */ /* structure for MTIOCGET - mag tape get status command */ struct mtget { short mt_type; /* type of magtape device */ /* the following two registers are grossly device dependent */ short mt_dsreg; /* ``drive status'' register */ short mt_erreg; /* ``error'' register */ /* end device-dependent registers */ short mt_resid; /* residual count */ #if defined (__FreeBSD__) daddr_t mt_blksiz; /* presently operating blocksize */ daddr_t mt_density; /* presently operating density */ - u_int32_t mt_comp; /* presently operating compression */ + uint32_t mt_comp; /* presently operating compression */ daddr_t mt_blksiz0; /* blocksize for mode 0 */ daddr_t mt_blksiz1; /* blocksize for mode 1 */ daddr_t mt_blksiz2; /* blocksize for mode 2 */ daddr_t mt_blksiz3; /* blocksize for mode 3 */ daddr_t mt_density0; /* density for mode 0 */ daddr_t mt_density1; /* density for mode 1 */ daddr_t mt_density2; /* density for mode 2 */ daddr_t mt_density3; /* density for mode 3 */ /* the following are not yet implemented */ - u_int32_t mt_comp0; /* compression type for mode 0 */ - u_int32_t mt_comp1; /* compression type for mode 1 */ - u_int32_t mt_comp2; /* compression type for mode 2 */ - u_int32_t mt_comp3; /* compression type for mode 3 */ + uint32_t mt_comp0; /* compression type for mode 0 */ + uint32_t mt_comp1; /* compression type for mode 1 */ + uint32_t mt_comp2; /* compression type for mode 2 */ + uint32_t mt_comp3; /* compression type for mode 3 */ /* end not yet implemented */ #endif daddr_t mt_fileno; /* relative file number of current position */ daddr_t mt_blkno; /* relative block number of current position */ }; /* structure for MTIOCERRSTAT - tape get error status command */ /* really only supported for SCSI tapes right now */ struct scsi_tape_errors { /* * These are latched from the last command that had a SCSI * Check Condition noted for these operations. The act * of issuing an MTIOCERRSTAT unlatches and clears them. */ - u_int8_t io_sense[32]; /* Last Sense Data For Data I/O */ + uint8_t io_sense[32]; /* Last Sense Data For Data I/O */ u_int32_t io_resid; /* residual count from last Data I/O */ - u_int8_t io_cdb[16]; /* Command that Caused the Last Data Sense */ - u_int8_t ctl_sense[32]; /* Last Sense Data For Control I/O */ + uint8_t io_cdb[16]; /* Command that Caused the Last Data Sense */ + uint8_t ctl_sense[32]; /* Last Sense Data For Control I/O */ u_int32_t ctl_resid; /* residual count from last Control I/O */ - u_int8_t ctl_cdb[16]; /* Command that Caused the Last Control Sense */ + uint8_t ctl_cdb[16]; /* Command that Caused the Last Control Sense */ /* * These are the read and write cumulative error counters. * (how to reset cumulative error counters is not yet defined). * (not implemented as yet but space is being reserved for them) */ struct { - u_int32_t retries; /* total # retries performed */ - u_int32_t corrected; /* total # corrections performed */ - u_int32_t processed; /* total # corrections successful */ - u_int32_t failures; /* total # corrections/retries failed */ - u_int64_t nbytes; /* total # bytes processed */ + uint32_t retries; /* total # retries performed */ + uint32_t corrected; /* total # corrections performed */ + uint32_t processed; /* total # corrections successful */ + uint32_t failures; /* total # corrections/retries failed */ + uint64_t nbytes; /* total # bytes processed */ } wterr, rderr; }; union mterrstat { struct scsi_tape_errors scsi_errstat; char _reserved_padding[256]; }; /* * Constants for mt_type byte. These are the same * for controllers compatible with the types listed. */ #define MT_ISTS 0x01 /* TS-11 */ #define MT_ISHT 0x02 /* TM03 Massbus: TE16, TU45, TU77 */ #define MT_ISTM 0x03 /* TM11/TE10 Unibus */ #define MT_ISMT 0x04 /* TM78/TU78 Massbus */ #define MT_ISUT 0x05 /* SI TU-45 emulation on Unibus */ #define MT_ISCPC 0x06 /* SUN */ #define MT_ISAR 0x07 /* SUN */ #define MT_ISTMSCP 0x08 /* DEC TMSCP protocol (TU81, TK50) */ #define MT_ISCY 0x09 /* CCI Cipher */ #define MT_ISCT 0x0a /* HP 1/4 tape */ #define MT_ISFHP 0x0b /* HP 7980 1/2 tape */ #define MT_ISEXABYTE 0x0c /* Exabyte */ #define MT_ISEXA8200 0x0c /* Exabyte EXB-8200 */ #define MT_ISEXA8500 0x0d /* Exabyte EXB-8500 */ #define MT_ISVIPER1 0x0e /* Archive Viper-150 */ #define MT_ISPYTHON 0x0f /* Archive Python (DAT) */ #define MT_ISHPDAT 0x10 /* HP 35450A DAT drive */ #define MT_ISMFOUR 0x11 /* M4 Data 1/2 9track drive */ #define MT_ISTK50 0x12 /* DEC SCSI TK50 */ #define MT_ISMT02 0x13 /* Emulex MT02 SCSI tape controller */ /* mag tape io control commands */ #define MTIOCTOP _IOW('m', 1, struct mtop) /* do a mag tape op */ #define MTIOCGET _IOR('m', 2, struct mtget) /* get tape status */ /* these two do not appear to be used anywhere */ #define MTIOCIEOT _IO('m', 3) /* ignore EOT error */ #define MTIOCEEOT _IO('m', 4) /* enable EOT error */ /* * When more SCSI-3 SSC (streaming device) devices are out there * that support the full 32 byte type 2 structure, we'll have to * rethink these ioctls to support all the entities they haul into * the picture (64 bit blocks, logical file record numbers, etc..). */ -#define MTIOCRDSPOS _IOR('m', 5, u_int32_t) /* get logical blk addr */ -#define MTIOCRDHPOS _IOR('m', 6, u_int32_t) /* get hardware blk addr */ -#define MTIOCSLOCATE _IOW('m', 5, u_int32_t) /* seek to logical blk addr */ -#define MTIOCHLOCATE _IOW('m', 6, u_int32_t) /* seek to hardware blk addr */ +#define MTIOCRDSPOS _IOR('m', 5, uint32_t) /* get logical blk addr */ +#define MTIOCRDHPOS _IOR('m', 6, uint32_t) /* get hardware blk addr */ +#define MTIOCSLOCATE _IOW('m', 5, uint32_t) /* seek to logical blk addr */ +#define MTIOCHLOCATE _IOW('m', 6, uint32_t) /* seek to hardware blk addr */ #define MTIOCERRSTAT _IOR('m', 7, union mterrstat) /* get tape errors */ /* * Set EOT model- argument is number of filemarks to end a tape with. * Note that not all possible values will be accepted. */ -#define MTIOCSETEOTMODEL _IOW('m', 8, u_int32_t) +#define MTIOCSETEOTMODEL _IOW('m', 8, uint32_t) /* Get current EOT model */ -#define MTIOCGETEOTMODEL _IOR('m', 8, u_int32_t) +#define MTIOCGETEOTMODEL _IOR('m', 8, uint32_t) #ifndef _KERNEL #define DEFTAPE "/dev/nsa0" #endif #ifdef _KERNEL /* * minor device number */ #define T_UNIT 003 /* unit selection */ #define T_NOREWIND 004 /* no rewind on close */ #define T_DENSEL 030 /* density select */ #define T_800BPI 000 /* select 800 bpi */ #define T_1600BPI 010 /* select 1600 bpi */ #define T_6250BPI 020 /* select 6250 bpi */ #define T_BADBPI 030 /* undefined selection */ #endif #endif /* !_SYS_MTIO_H_ */ .Ed .Sh FILES .Bl -tag -width /dev/[n]sa* -compact .It Pa /dev/[n]sa* .El .Sh SEE ALSO .Xr mt 1 , .Xr tar 1 , .Xr ast 4 , .Xr sa 4 .Sh HISTORY The .Nm manual appeared in .Bx 4.2 . An i386 version first appeared in .Fx 2.2 . .Sh BUGS The status should be returned in a device independent format. .Pp The special file naming should be redone in a more consistent and understandable manner. Index: stable/9/share/man/man4/natm.4 =================================================================== --- stable/9/share/man/man4/natm.4 (revision 290886) +++ stable/9/share/man/man4/natm.4 (revision 290887) @@ -1,101 +1,101 @@ .\" $FreeBSD$ .\" .Dd December 29, 1997 .Dt NATM 4 .Os .Sh NAME .Nm natm .Nd Native Mode ATM protocol layer .Sh DESCRIPTION The .Bx ATM software comes with a .Em native mode ATM protocol layer which provides socket level access to AAL0 and AAL5 virtual circuits. To enable this protocol layer, add .Dl options NATM to your kernel configuration file and re-make the kernel (do not forget to do .Dq make clean ) . .Sh NATM API The NATM layer uses a .Vt struct sockaddr_natm to specify a virtual circuit: .Bd -literal -offset indent struct sockaddr_natm { - u_int8_t snatm_len; /* length */ - u_int8_t snatm_family; /* AF_NATM */ + uint8_t snatm_len; /* length */ + uint8_t snatm_family; /* AF_NATM */ char snatm_if[IFNAMSIZ]; /* interface name */ - u_int16_t snatm_vci; /* vci */ - u_int8_t snatm_vpi; /* vpi */ + uint16_t snatm_vci; /* vci */ + uint8_t snatm_vpi; /* vpi */ }; .Ed .Pp To create an AAL5 connection to a virtual circuit with VPI 0, VCI 201 one would use the following: .Bd -literal -offset indent struct sockaddr_natm snatm; int s, r; s = socket(AF_NATM, SOCK_STREAM, PROTO_NATMAAL5); /* note: PROTO_NATMAAL0 is AAL0 */ if (s < 0) { perror("socket"); exit(1); } bzero(&snatm, sizeof(snatm)); snatm.snatm_len = sizeof(snatm); snatm.snatm_family = AF_NATM; sprintf(snatm.snatm_if, "en0"); snatm.snatm_vci = 201; snatm.snatm_vpi = 0; r = connect(s, (struct sockaddr *)&snatm, sizeof(snatm)); if (r < 0) { perror("connect"); exit(1); } /* s now connected to ATM! */ .Ed .Pp The .Fn socket call simply creates an unconnected NATM socket. The .Fn connect call associates an unconnected NATM socket with a virtual circuit and tells the driver to enable that virtual circuit for receiving data. After the .Fn connect call one can .Fn read or .Fn write to the socket to perform ATM I/O. .Sh Internal NATM operation Internally, the NATM protocol layer keeps a list of all active virtual circuits on the system in .Dv natm_pcbs . This includes circuits currently being used for IP to prevent NATM and IP from clashing over virtual circuit usage. .Pp When a virtual circuit is enabled for receiving data, the NATM protocol layer passes the address of the protocol control block down to the driver as a receive .Dq handle . When inbound data arrives, the driver passes the data back with the appropriate receive handle. The NATM layer uses this to avoid the overhead of a protocol control block lookup. This allows us to take advantage of the fact that ATM has already demultiplexed the data for us. .Sh SEE ALSO .Xr en 4 , .Xr fatm 4 , .Xr hatm 4 , .Xr natmip 4 , .Xr patm 4 .Sh AUTHORS .An Chuck Cranor of Washington University implemented the NATM protocol layer along with the EN ATM driver in 1996 for .Nx . .Sh CAVEATS The NATM protocol support is subject to change as the ATM protocols develop. Users should not depend on details of the current implementation, but rather the services exported. Index: stable/9/share/man/man4/net80211.4 =================================================================== --- stable/9/share/man/man4/net80211.4 (revision 290886) +++ stable/9/share/man/man4/net80211.4 (revision 290887) @@ -1,1318 +1,1318 @@ .\"- .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\"" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGES. .\" .\" $FreeBSD$ .\" .Dd July 10, 2009 .Dt NET80211 4 .Os .Sh NAME .Nm net80211 .Nd standard interface to IEEE 802.11 devices .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In net/if.h .In net/ethernet.h .In net80211/ieee80211_ioctl.h .Sh DESCRIPTION This section describes the standard programming interface to configure and retrieve status information for IEEE 802.11 devices that depend on the .Xr wlan 4 module for operation. The interface is via one of the following .Xr ioctl 2 calls on a socket: .Bl -tag -width ".Dv SIOCG80211" .It Dv SIOCG80211 Get configuration or status information. .It Dv SIOCS80211 Set configuration information. .El .Pp These requests are made via a modified .Vt ifreq structure. This structure is defined as follows: .Bd -literal struct ieee80211req { char i_name[IFNAMSIZ]; /* if_name, e.g. "wi0" */ - u_int16_t i_type; /* req type */ + uint16_t i_type; /* req type */ int16_t i_val; /* Index or simple value */ int16_t i_len; /* Index or simple value */ void *i_data; /* Extra data */ }; .Ed .Pp Requests that are not supported by the underlying device return -1 and set the global variable errno to .Er EOPNOTSUPP . .Dv SIOCG80211 requests that return data to an application place small values in .Va i_val or in a user-specified buffer pointed to by .Va i_data . When an indirect buffer is used .Va i_len specifies how large the indirect buffer is and on return it is set by the system to the actual amount of data returned. .Dv SIOCS80211 requests use a similar scheme with data passed to the system taken either from .Va i_val or an indirect buffer pointed to by .Va i_data . .Pp For .Dv SIOCG80211 the following values of .Va i_type are valid: .Bl -tag -width indent .It Dv IEEE80211_IOC_AMPDU Return whether or not AMPDU is enabled in .Va i_val . AMPDU is an aggregation scheme that is part of the 802.11n specification and is used only when operating on an HT channel. The value returned is one of: 0 (AMPDU disabled), 1 (AMPDU enabled for transmit), 2 (AMPDU enabled for receive), and 3 (AMPDU enabled for transmit and receive). The 802.11n specification says a compliant station must receive AMPDU but may not support transmitting AMPDU frames. Disabling AMPDU receive is mainly useful for testing and working around bugs. .It Dv IEEE80211_IOC_AMPDU_DENSITY Return the minimum density for bursting AMPDU frames in .Va i_val . The value returned is one of: 0 (no time restriction), 1 (1/4 usec), 2 (1/2 usec), 3 (1 usec), 4 (2 usec), 5 (4 usec), 6 (8 usec), and 7 (16 usec). .It Dv IEEE80211_IOC_AMPDU_LIMIT Return the limit on the size of AMPDU frames in .Va i_val . The value returned is one of: 0 (8 kilobytes), 1 (16 kilobytes), 2 (32 kilobytes), and 3 (64 kilobytes). .It Dv IEEE80211_IOC_AMSDU Return whether or not AMSDU is enabled in .Va i_val . AMSDU is an aggregation scheme that is part of the 802.11n specification and is used only when operating on an HT channel. The value returned is one of: 0 (AMSDU disabled), 1 (AMSDU enabled for transmit), 2 (AMSDU enabled for receive), and 3 (AMSDU enabled for transmit and receive). The 802.11n specification says a compliant station must receive AMSDU but may not support transmitting AMSDU frames. Disabling AMSDU receive is mainly useful for testing and working around bugs. .It Dv IEEE80211_IOC_AMSDU_LIMIT Return the limit on the size of AMSDU frames in .Va i_val . The value returned is one of: 3839 (bytes) and 7935 (bytes). Note these values are specified by 802.11n; arbitrary values are not allowed. .It Dv IEEE80211_IOC_APBRIDGE Return whether AP bridging is enabled in .Va i_val . Normally packets sent between stations associated to the same access point are delivered without going through system layers that do packet filtering; when AP bridging is disabled packets are passed up the system to be forwarded using some other mechanism. This value will be non-zero when AP bridging is enabled and otherwise zero. .It Dv IEEE80211_IOC_APPIE Return an application information element via .Va i_data . Application IE's are maintained for many 802.11 frames; the request must identify the frame to return an IE for in .Va i_val . For example, to retrieve the IE sent in each Beacon frame .Va i_val would be set to .Va IEEE80211_FC0_SUBTYPE_BEACON | IEEE80211_FC0_TYPE_MGT . If no information element is installed then .Er EINVAL is returned. If the data buffer for returning data is too small to hold the information element the value is truncated; this permits querying the presence of data by requesting zero bytes of data be returned. .It Dv IEEE80211_IOC_AUTHMODE Return the current authentication mode in .Va i_val . Valid values are .Dv IEEE80211_AUTH_NONE (no authentication), .Dv IEEE80211_AUTH_OPEN (open authentication), .Dv IEEE80211_AUTH_SHARED (shared key authentication), .Dv IEEE80211_AUTH_8021X (802.1x only authentication), and .Dv IEEE80211_AUTH_WPA (WPA/802.11i/802.1x authentication). .It Dv IEEE80211_IOC_BEACON_INTERVAL Return the time between Beacon frames (in TU) in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN Return whether background scanning is enabled in .Va i_val . When this value is non-zero and operating in station mode the station will periodically leave the current channel and scan for neighboring stations. See also .Dv IEEE80211_IOC_BGSCAN_IDLE and .Dv IEEE80211_IOC_BGSCAN_INTERVAL . .It Dv IEEE80211_IOC_BGSCAN_IDLE Return in .Va i_val the minimum time (msecs) a station must be idle (i.e. not transmitting or receiving frames) before it will do a background scan. See also .Dv IEEE80211_IOC_BGSCAN_INTERVAL . .It Dv IEEE80211_IOC_BGSCAN_INTERVAL Return in .Va i_val the minimum time (seconds) between background scan operations. See also .Dv IEEE80211_IOC_BGSCAN_IDLE . .It Dv IEEE80211_IOC_BMISSTHRESHOLD Return in .Va i_val the number of consecutive missed Beacon frames before the system will attempt to roam to a different/better access point. .It Dv IEEE80211_IOC_BSSID Return the MAC address for the current BSS identifier via .Va i_data . When the interface is running, the bssid is either the value configured locally (e.g. for an IBSS network started by the local station) or the value adopted when joining an existing network. For WDS interfaces this value is the address of the remote station. When the interface is not running, the bssid returned is the desired bssid, if any, that has been configured. .It Dv IEEE80211_IOC_BURST Return whether or not packet bursting is enabled in .Va i_val . If this value is non-zero then the system will try to send packets closely spaced to improve throughput. .It Dv IEEE80211_IOC_CHANINFO Return the set of available channels via .Va i_data . Note this data should be used by user applications to map between channel specifications (frequency and attributes) and IEEE channel numbers as user applications may not have the necessary information to do this directly (e.g. for 900MHz radios, operation in the Public Safety Band). .It Dv IEEE80211_IOC_CHANLIST Return the current list of usable channels via .Va i_data . The channel list is returned as a bit vector with bit N set to 1 if IEEE channel number N is available for use. .It Dv IEEE80211_IOC_CHANNEL Return the IEEE channel number of the current channel in .Va i_val . Note this request is deprecated; use .Dv IEEE80211_IOC_CURCHAN instead. .It Dv IEEE80211_IOC_COUNTERMEASURES Return whether TKIP Countermeasures are enabled in .Va i_val . This value will be non-zero when Countermeasures are enabled and otherwise zero. .It Dv IEEE80211_IOC_CURCHAN Return information for the current channel via .Va i_data . This information includes the IEEE channel number, the frequency, and attributes that describe the operating constraints (e.g. Passive Scan, DFS, usage restrictions). .It Dv IEEE80211_IOC_DEVCAPS Return device capabilities in the data buffer pointed at by .Va i_data . The buffer must be large enough to return the number of available channels but otherwise may be made small to limit how much information is returned. .It Dv IEEE80211_IOC_DFS Return whether or not Dynamic Frequency Selection (DFS) is enabled in .Va i_val . DFS embodies several facilities including detection of overlapping radar signals, dynamic transmit power control, and channel selection according to a least-congested criteria. DFS support is mandatory for some 5GHz frequencies in certain locales (e.g. ETSI). By default DFS is enabled according to the regulatory definitions and the current country code, regdomain, and channel. .It Dv IEEE80211_IOC_DOTD Return whether or not 802.11d support is enabled in .Va i_val . When 802.11d is enabled in station mode, Beacon frames that advertise a country code different than the currently configured country code will cause an event to be dispatched to user applications. This event can be used by the station to adopt that country code and operate according to the associated regulatory constraints. When operating as an access point with 802.11d enabled the Beacon and ProbeResponse frames transmitted will advertise the current regulatory domain settings. .It Dv IEEE80211_IOC_DOTH Return whether 802.11h support is enabled in .Va i_val . When 802.11h is enabled Beacon and ProbeResponse frames will have the SpectrumMgt bit set in the capabilities field and country and power constraint information elements will be present. 802.11h support also includes handling Channel Switch Announcements (CSA) which are a mechanism to coordinate channel changes by an access point. By default 802.11h is enabled if the device is capable. .It Dv IEEE80211_IOC_DROPUNENCRYPTED Return, in .Va i_val , whether unencrypted packets transmit/received should be discarded. This value will be zero if unencrypted packets will be accepted and non-zero if they are to be discarded. .It Dv IEEE80211_IOC_DTIM_PERIOD Return the period (in beacon intervals) between DTIM events in .Va i_val . .It Dv IEEE80211_IOC_DWDS Return, in .Va i_val , whether or not Dynamic WDS support is enabled. Dynamic WDS is a facility by which packets may be tunneled over normal Infrastructure BSS associations using 4-address (WDS) frames. .It Dv IEEE80211_IOC_FF Return, in .Va i_val , whether Atheros fast-frames support is enabled. Fast-frames is a non-standard protocol extension that aggregates multiple frames to improve throughput. Note that enabling fast-frames support does not guarantee use; the client and access point must negotiate its use. .It Dv IEEE80211_IOC_FRAGTHRESHOLD Return, in .Va i_val , the threshold (in bytes) for enabling fragmentation frames. Packets larger than this value will automatically be split into multiple fragmented frames that are sent one after the other. .It Dv IEEE80211_IOC_GREENFIELD Return, in .Va i_val , whether or not Greenfield preamble use is enabled. This setting is meaningful only when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_HIDESSID Return, in .Va i_val , whether SSID hiding/cloaking is enabled. SSID hiding is only meaningful when operating as an access point. When this is enabled Beacon frames do not include the SSID and ProbeRequest frames are not answered unless they include the AP's SSID. This value will be non-zero when SSID hiding is enabled and otherwise zero. .It Dv IEEE80211_IOC_HTCOMPAT Return, in .Va i_val , whether or not 802.11n compatibility support is enabled. The 802.11n protocol specification went through several incompatible iterations. Some vendors implemented 11n support to older specifications that will not interoperate with a purely 11n-compliant station. In particular the information elements included in management frames for old devices are different. When compatibility support is enabled both standard and compatible data will be provided and/or accepted. .It Dv IEEE80211_IOC_HTCONF Return the setting for automatic promotion of HT channels in .Va i_val . Promotion happens when the system must select a channel and may choose between legacy, HT20, and HT40 operation (e.g. when scanning). Valid values are: 0 (do not promote, use legacy), 1 (promote to HT20), and 2 (promote to HT40). .It Dv IEEE80211_IOC_HTPROTMODE Return, in .Va i_val , the technique used to protect HT frames in a mixed 802.11n network. Valid values are: .Dv IEEE80211_PROTMODE_OFF (no protection enabled) and .Dv IEEE80211_PROTMODE_RTSCTS (send RTS and wait for CTS). .It Dv IEEE80211_IOC_HWMP_MAXHOPS Return the maximum acceptable hop count in an HWMP path in .Va i_val . .It Dv IEEE80211_IOC_HWMP_ROOTMODE Return the setting for Mesh root mode operation in .Va i_val . Valid values are: .Dv IEEE80211_HWMP_ROOTMODE_DISABLED (root mode is disabled), .Dv IEEE80211_HWMP_ROOTMODE_NORMAL (send broadcast Path Request frames), .Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE (send broadcast Path Request frames and force replies) and .Dv IEEE80211_HWMP_ROOTMODE_RANN (send broadcast Root Announcement (RANN) frames). .It Dv IEEE80211_IOC_INACTIVITY Return whether or not the system handles inactivity processing in .Va i_val . When inactivity processing is enabled the system will track stations that have not transmitted frames and periodically probe them to check if they are still present. Stations that are inactive and do not respond to probes are dropped. .It Dv IEEE80211_IOC_MACCMD Return information about the state of the MAC address access control list (ACL) system. There are two requests supported: .Dv IEEE80211_MACCMD_POLICY (to retrieve the current policy in .Va i_val ), and .Dv IEEE80211_MACCMD_LIST to retrieve the list installed/active ACL's via .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_MESH_AP Return whether or not Mesh AP support is enabled in .Va i_val . .It Dv IEEE80211_IOC_MESH_ID Return the Mesh ID in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_FWRD Return whether or not packet forwarding support is enabled in .Va i_val . .It Dv IEEE80211_IOC_MESH_PP_METRIC Return the link metric protocol in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_PP_PATH Return the path selection protocol in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_RTCMD Return information about the state of the Mesh routing tables. One request is supported: .Dv IEEE80211_MESH_RTCMD_LIST to retrieve the contents of the routing table in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_TTL Return, in .Va i_val , the Mesh Time To Live (TTL) setting installed in packets transmitted by this mesh node. .It Dv IEEE80211_IOC_NUMSSIDS Return the number of SSIDs supported in .Va i_val . .It Dv IEEE80211_IOC_NUMWEPKEYS Return the number of WEP keys supported in .Va i_val . .It Dv IEEE80211_IOC_POWERSAVE Return the current powersaving mode in .Va i_val . Valid values are .Dv IEEE80211_POWERSAVE_OFF (power save operation is disabled) and .Dv IEEE80211_POWERSAVE_ON (power save operation is enabled). .It Dv IEEE80211_IOC_POWERSAVESLEEP Return the powersave sleep time in TU in .Va i_val . This value is also termed the listen interval and represents the maximum time a station will sleep before waking to retrieve packets buffered by an access point. .It Dv IEEE80211_IOC_PRIVACY Return the current MLME setting for PRIVACY in .Va i_val . When PRIVACY is enabled all data packets must be encrypted. This value will be zero if PRIVACY is disabled and non-zero when PRIVACY is enabled. .It Dv IEEE80211_IOC_PROTMODE Return the current 802.11g protection mode in .Va i_val . Protection is the mechanism used to safeguard 802.11b stations operating on an 802.11g network. Valid values are .Dv IEEE80211_PROTMODE_OFF (no protection enabled), .Dv IEEE80211_PROTMODE_CTS (send CTS to yourself), and .Dv IEEE80211_PROTMODE_RTSCTS (send RTS and wait for CTS). .It Dv IEEE80211_IOC_PUREG Return whether ``pure 11g'' mode is enabled in .Va i_val . This setting is meaningful only for access point operation; when non-zero, 802.11b stations will not be allowed to associate. .It Dv IEEE80211_IOC_PUREN Return whether ``pure 11n'' mode is enabled in .Va i_val . This setting is meaningful only for access point operation; when non-zero, legacy (non-11n capable) stations will not be allowed to associate. .It Dv IEEE80211_IOC_REGDOMAIN Return the regulatory state in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_RIFS Return whether or not Reduced InterFrame Spacing (RIFS) is enabled in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_ROAM Return station roaming parameters in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_ROAMING Return the current roaming mode in .Va i_val . Roaming mode specifies which entity controls operation of the MLME state machine when operating as a station in an Infrastructure BSS. Valid values are: .Dv IEEE80211_ROAMING_DEVICE (driver/firmware is in control), .Dv IEEE80211_ROAMING_AUTO (host 802.11 layer is in control), and .Dv IEEE80211_ROAMING_MANUAL (application is in control). .It Dv IEEE80211_IOC_RTSTHRESHOLD Return the threshold (in bytes) for enabling transmission of RTS frames in .Va i_val . Packets larger than this value will automatically have an RTS frame sent preceding it to reduce the likelihood of packet loss. .It Dv IEEE80211_IOC_SCAN_RESULTS Return the current contents of the scan cache in the data area pointed to by .Va i_data . .It Dv IEEE80211_IOC_SCANVALID Return in .Va i_val how long (in seconds) results from a scan operation will be considered valid. When scan results are no longer valid and they are needed (e.g. to roam) the system will initiate a scan operation to replenish the scan cache. .It Dv IEEE80211_IOC_SHORTGI Return whether or not Short Guard Interval (SGI) is enabled in .Va i_val . Note SGI is only used when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_SMPS Return the Spatial Multiplexing Power Save (SMPS) setting in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. Valid values are: .Dv IEEE80211_HTCAP_SMPS_DYNAMIC (Dynamic SMPS is enabled), .Dv IEEE80211_HTCAP_SMPS_ENA (Static SMPS is enabled), and .Dv IEEE80211_HTCAP_SMPS_OFF (SMPS is disabled). .It Dv IEEE80211_IOC_SSID Return the requested SSID in the buffer pointed to by .Va i_data . If .Va i_val is \(>= 0 then the request refers to the configured value for that slot. Generally, 0 is the only valid value, but some interfaces support more SSIDs. .It Dv IEEE80211_IOC_STA_INFO Return information about the current state of the specified station(s) via .Va i_data . The MAC address of a single station may be passed in or, if the broadcast address is supplied, information about all stations will be returned. If a single station is requested and the MAC address is unknown then .Er ENOENT will be returned. .It Dv IEEE80211_IOC_STA_STATS Return collected statistics for the specified station via .Va i_data . The MAC address of the desired station is passed in; if it is unknown .Er ENOENT will be returned. .It Dv IEEE80211_IOC_STA_VLAN Return any VLAN tag assigned to a station via .Va i_data . .It Dv IEEE80211_IOC_TDMA_SLOT Return the slot number for the station in .Va i_val . Slot number zero is the master station in a TDMA network. .It Dv IEEE80211_IOC_TDMA_SLOTCNT Return the count of slots in the TDMA network in .Va i_val . .It Dv IEEE80211_IOC_TDMA_SLOTLEN Return the length (in usecs) of the TDMA slot assigned to each station in the network in .Va i_val . .It Dv IEEE80211_IOC_TDMA_BINTERVAL Return the number of superframes between Beacon frames in .Va i_val . A TDMA network with N slots and slot length T has a superframe of NxT. .It Dv IEEE80211_IOC_TSN Return whether or not Transitional Security Network (TSN) is enabled in .Va i_val . .It Dv IEEE80211_IOC_TURBOP Return whether Atheros Dynamic Turbo mode is enabled in .Va i_val . Dynamic Turbo mode is a non-standard protocol extension available only on Atheros devices where channel width is dynamically changed between 20MHz and 40MHz. Note that enabling Dynamic Turbo mode support does not guarantee use; both client and access point must use Atheros devices and support must be enabled on both sides. .It Dv IEEE80211_IOC_TXPARAMS Return transmit parameters in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_TXPOWER Return the transmit power limit in .5 dBm units in .Va i_val . This value represents the effective maximum and is calculated according to the maximum power allowed by local regulations, any user-specified power limit, and the maximum power the device is capable of. .It Dv IEEE80211_IOC_TXPOWMAX Return the user-specified maximum transmit power in .5 dBm units in .Va i_val . The maximum setting is applied after any regulatory cap. .It Dv IEEE80211_IOC_WEP Return the current WEP status in .Va i_val . Valid values are: .Dv IEEE80211_WEP_ON (enabled for all packets sent and received), .Dv IEEE80211_WEP_OFF (disabled), and .Dv IEEE80211_WEP_MIXED (enabled for transmit and receive but also willing to receive unencrypted frames). This request is deprecated; use .Dv IEEE80211_IOC_PRIVACY and .Dv IEEE80211_IOC_UNENCRYPTED instead. .It Dv IEEE80211_IOC_WEPKEY Return the requested WEP key via .Va i_data . The key number is specified in .Va i_val and may be 0-3. If the device does not support returning the WEP key or the user is not root then the key may be returned as all zeros. This request is deprecated in favor of .Dv IEEE80211_IOC_WPAKEY . .It Dv IEEE80211_IOC_WEPTXKEY Return the number of the WEP key used for transmission in .Va i_val . .It Dv IEEE80211_IOC_WME Return whether 802.11e/WME/WMM support is enabled in .Va i_val . This value will be non-zero when support is enabled and otherwise zero. .It Dv IEEE80211_IOC_WME_CWMIN Return the WME CWmin setting (log2) for the specified Access Class (AC) in .Va i_val . The AC is passed in through .Va i_len together with an optional IEEE80211_WMEPARAM_BSS flag to indicate if the parameter for the BSS or the channel is desired. If WME is not supported then .Er EINVAL will be returned. .It Dv IEEE80211_IOC_WME_CWMAX Return the WME CWmax setting (log2) for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_AIFS Return the WME AIFS setting for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_TXOPLIMIT Return the WME TxOpLimit (msec) for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_ACM Return the WME Admission Control Mechanism (ACM) setting for the specified Access Class (AC) in .Va i_val . This value is meaningful only for the BSS (not channel). See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_ACKPOLICY Return the WME ACK Policy setting for the specified Access Class (AC) in .Va i_val . When this value is zero frames will be transmitted without waiting for an Acknowledgement. This value is meaningful only for the channel (not BSS). See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WPA Return the WPA configuration in .Va i_val . Valid values are 0 (WPA is not enabled), 1 (WPA1 is enabled), 2 (WPA2/802.11i is enabled), and 3 (WPA1 and WPA2/802.11i are both enabled). .It Dv IEEE80211_IOC_WPAIE Return any WPA information element for an associated station via .Va i_data . The request passed in through .Va i_data identifies the MAC address of the desired station. If an RSN (802.11i) element is present it is returned; otherwise any WPA element is returned. Note this request is deprecated; use .Dv IEEE80211_IOC_WPAIE2 instead. .It Dv IEEE80211_IOC_WPAIE2 Return any WPA information elements for an associated station via .Va i_data . The request passed in through .Va i_data identifies the MAC address of the desired station. One or both of RSN (802.11i) and WPA elements may be returned. .It Dv IEEE80211_IOC_WPAKEY Return the requested cryptographic key in the buffer pointed to by .Va i_data . The key number is specified in .Va i_val and may be 0-3. A key number of zero is used to retrieve a station's unicast cipher key when operating with WPA enabled. If the user is not root then the key data returned is all zeros. .It Dv IEEE80211_IOC_WPS Return whether or not Wi-FI Protected Setup (WPS) is enabled in .Va i_val . .El .Pp For .Dv SIOCS80211 the following values of .Va i_type are valid. Note that changing a value on an interface that is running may cause the interface to be .Sq reset . Resets may be handled without altering the state if the parameter does not affect the MLME state (e.g. RTS threshold), but in some cases the interface may need to scan for a new network or clear state (including any associated stations); in that case the interface is said to be .Sq restarted (it is equivalent to marking the interface down and back up). The information below identifies whether changing a value affects the state of a running interface. .Bl -tag -width indent .It Dv IEEE80211_IOC_ADDMAC Add an entry to the MAC address Access Control List (ACL) database using the value pointed to by .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_AMPDU Set whether or not AMPDU is enabled for transmit and/or receive using the value in .Va i_val . This request causes a running interface operating on an HT channel to be reset. See .Dv IEEE80211_IOC_AMPDU above for details. .It Dv IEEE80211_IOC_AMPDU_DENSITY Set the minimum density for bursting AMPDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMPDU_DENSITY above for details. .It Dv IEEE80211_IOC_AMPDU_LIMIT Set the limit on the size of AMPDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMPDU_LIMIT above for details. .It Dv IEEE80211_IOC_AMSDU Set whether or not AMSDU is enabled for transmit and/or receive using the value in .Va i_val . This request causes a running interface operating on an HT channel to be reset. See .Dv IEEE80211_IOC_AMSDU above for details. .It Dv IEEE80211_IOC_AMSDU_LIMIT Set the limit on the size of AMSDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMSDU_LIMIT above for details. .It Dv IEEE80211_IOC_APBRIDGE Set whether AP bridging is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_APBRIDGE above for details. .It Dv IEEE80211_IOC_APPIE Set an application information element using the data pointed to by .Va i_data . This request causes a running interface to be restarted if the WPA information element is changed. See .Dv IEEE80211_IOC_APPIE above for details. .It Dv IEEE80211_IOC_AUTHMODE Set the current authentication mode using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_AUTHMODE above for details. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BEACON_INTERVAL Set the time between Beacon frames (in TU) to the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BGSCAN Set whether background scanning is enabled using the value in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN_IDLE Set the minimum time (in msecs) a station must be idle before it will do a background scan to the value in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN_INTERVAL Set the minimum time (seconds) between background scan operations to the value in .Va i_val . .It Dv IEEE80211_IOC_BMISSTHRESHOLD Set the number of consecutive missed Beacon frames before the system will attempt to roam to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_BSSID Set the 802.11 MAC address for the desired BSS identifier according to .Va i_data . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BURST Set whether or not packet bursting is enabled using the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_CHANNEL Set the desired/current channel to the value given by .Va i_val . This request causes a running interface to immediately change to the specified channel if possible; otherwise the interface will be restarted. Note this request is deprecated; use .Dv IEEE80211_IOC_CURCHAN instead. .It Dv IEEE80211_IOC_CHANLIST Set the list of available channels using the channel list pointed to by .Va i_data . The channel list is a bit vector with bit N set to 1 if IEEE channel number N is available for use. The specified channel list is checked against the set of supported channels and any channels not supported are silently ignored. If the intersection of the channel list and the supported channels is empty .Er EINVAL is returned. Note the current channel may be marked invalid after installing a new channel list. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_COUNTERMEASURES Set whether TKIP Countermeasures are enabled using the value in .Va i_val . This request can only be used when the authentication mode is set WPA; otherwise .Er EOPNOTSUPP will be returned. .It Dv IEEE80211_IOC_CURCHAN Set the current channel using the information referenced by .Va i_data . This request causes a running interface to immediately change to the specified channel if possible; otherwise the interface will be restarted. .It Dv IEEE80211_IOC_DELKEY Delete the key specified by the information referenced by .Va i_data . .It Dv IEEE80211_IOC_DELMAC Remove an entry in the MAC address Access Control List (ACL) database using the value pointed to by .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_DFS Set whether or not Dynamic Frequency Selection (DFS) is enabled using the value in .Va i_val . This request will fail with .Er EINVAL if 802.11h support is not enabled. See .Dv IEEE80211_IOC_DFS above for details. .It Dv IEEE80211_IOC_DOTD Set whether or not 802.11d support is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_DOTD above for details. .It Dv IEEE80211_IOC_DOTH Return whether 802.11h support is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_DOTH above for details. .It Dv IEEE80211_IOC_DROPUNENCRYPTED Set whether unencrypted packets transmit/received should be discarded using the value in .Va i_val . .It Dv IEEE80211_IOC_DTIM_PERIOD Set the period (in beacon intervals) between DTIM events to the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_DWDS Set whether or not Dynamic WDS support is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_DWDS above for details. .It Dv IEEE80211_IOC_FF Set whether Atheros fast-frames support is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_FF above for details. .It Dv IEEE80211_IOC_FRAGTHRESHOLD Set the threshold (in bytes) for enabling fragmentation frames using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_FRAGTHRESHOLD above for details. .It Dv IEEE80211_IOC_GREENFIELD Set whether or not Greenfield preamble use is enabled using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_GREENFIELD above for details. .It Dv IEEE80211_IOC_HIDESSID Set whether SSID hiding/cloaking is enabled using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_HIDESSID above for details. .It Dv IEEE80211_IOC_HTCOMPAT Set whether or not 802.11n compatibility support is enabled using the value in .Va i_val . This request causes a running interface to be reset if operating on HT channel. See .Dv IEEE80211_IOC_HTCOMPAT above for details. .It Dv IEEE80211_IOC_HTCONF Set automatic promotion of HT channels using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_HTCONF above for details. .It Dv IEEE80211_IOC_HTPROTMODE Set the technique used to protect HT frames in a mixed 802.11n network using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_HTPROTMODE above for details. .It Dv IEEE80211_IOC_HWMP_MAXHOPS Set the maximum acceptable hop count in an HWMP path according to .Va i_val . Values must be in the range [0-255]. .It Dv IEEE80211_IOC_HWMP_ROOTMODE Set the Mesh root mode operation according to .Va i_val . Valid values are .Dv IEEE80211_HWMP_ROOTMODE_DISABLED (root mode is disabled), .Dv IEEE80211_HWMP_ROOTMODE_NORMAL (send broadcast Path Request frames), .Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE (send broadcast Path Request frames and force replies) and .Dv IEEE80211_HWMP_ROOTMODE_RANN (send broadcast Root Announcement (RANN) frames). .It Dv IEEE80211_IOC_INACTIVITY Set whether or not the system handles inactivity processing using the value in .Va i_val . When inactivity processing is enabled the system will track stations that have not transmitted frames and periodically probe them to check if they are still present. Stations that are inactive and do not respond to probes are dropped. .It Dv IEEE80211_IOC_MACCMD Change the state of the MAC address Access Control List (ACL) system. There are several requests supported: .Dv IEEE80211_MACCMD_POLICY_OPEN (set the current policy to disable ACL use), .Dv IEEE80211_MACCMD_POLICY_ALLOW (set the current policy to allow only addresses listed in the database), .Dv IEEE80211_MACCMD_POLICY_DENY (set the current policy to deny addresses listed in the database), .Dv IEEE80211_MACCMD_POLICY_RADUS (set the current policy to enable use of a RADIUS backend), .Dv IEEE80211_MACCMD_FLUSH (flush all addresses from the database), and .Dv IEEE80211_MACCMD_DETACH (detach the ACL subsystem, disabling it). The .Xr wlan_acl 4 module must be installed or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_MESH_AP Set whether or not Mesh AP support is enabled using .Va i_val . .It Dv IEEE80211_IOC_MESH_FWRD Set whether or not packet forwarding support is enabled using .Va i_val . .It Dv IEEE80211_IOC_MESH_ID Set the Mesh ID using the value pointed to by .Va i_data . A Mesh ID can be up to .Dv IEEE80211_MESHID_LEN bytes long. .It Dv IEEE80211_IOC_MESH_PP_METRIC Set the link metric protocol using the value pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_PP_PATH Set the path selection protocol using the value pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_RTCMD Manipulate the state of the Mesh routing tables. Several requests are supported: .Dv IEEE80211_MESH_RTCMD_FLUSH (flush the contents of the routing table), .Dv IEEE80211_MESH_RTCMD_ADD (add an entry for the MAC address specified in .Va i_data and start the Peer discovery process), and .Dv IEEE80211_MESH_RTCMD_DELETE (delete the entry corresponding to the MAC address specified in .Va i_data ). .It Dv IEEE80211_IOC_MESH_TTL Set the Mesh Time To Live (TTL) setting installed in packets transmitted by this mesh node using .Va i_val . .It Dv IEEE80211_IOC_MLME Explicitly control the MLME state machine for a station using the MLME request pointed to by .Va i_data . There are several MLME operations supported: .Dv IEEE80211_MLME_ASSOC (request association to an access point), .Dv IEEE80211_MLME_DIASSOC (diassociate the specified station), .Dv IEEE80211_MLME_DEAUTH (deauthenticate the specified station), .Dv IEEE80211_MLME_AUHORIZE (mark the specified station authorized to pass data frames), .Dv IEEE80211_MLME_UNAUTHORIZE (revoke the specified station's ability to pass data frames), and .Dv IEEE80211_MLME_AUTH (request authentication to an access point). Note when this facility is used for stations operating in infrastructure mode the roaming mode should be set to manual. .It Dv IEEE80211_IOC_POWERSAVE Set the current powersaving mode to the value in .Va i_val . See .Dv IEEE80211_IOC_POWERSAVE above for valid values. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_POWERSAVESLEEP Set the powersave sleep time in TU to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_PRIVACY Set the current MLME setting for PRIVACY using the value in .Va i_val . See .Dv IEEE80211_IOC_PRIVACY above for details. .It Dv IEEE80211_IOC_PROTMODE Set the current 802.11g protection mode to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_PROTMODE above for details. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_PUREG Set whether ``pure 11g'' mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_PUREG above for details. .It Dv IEEE80211_IOC_PUREN Set whether ``pure 11n'' mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_PUREN above for details. .It Dv IEEE80211_IOC_REGDOMAIN Set the regulatory state using the data referenced by .Va i_data . This request can only be issued when all interfaces cloned from the underlying physical device are marked down; otherwise .Er EBUSY is returned. Note the new regulatory data may invalidate any desired channel. .It Dv IEEE80211_IOC_RIFS Set whether or not Reduced InterFrame Spacing (RIFS) is enabled using the value in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_ROAM Set station roaming parameters using the data pointed to by .Va i_data . .It Dv IEEE80211_IOC_ROAMING Set the current roaming mode to the value in .Va i_val . See .Dv IEEE80211_IOC_ROAMING above for details. .It Dv IEEE80211_IOC_RTSTHRESHOLD Set the threshold (in bytes) for enabling transmission of RTS frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_RTSTHRESHOLD above for details. .It Dv IEEE80211_IOC_SCANVALID Set the age (in seconds) that results from a scan operation will be considered valid. When scan results are no longer valid and they are needed (e.g. to roam) the system will initiate a scan operation to replenish the scan cache. .It Dv IEEE80211_IOC_SCAN_REQ Request a scan operation using the parameters pointed to by .Va i_val . The underlying device must be running or .Er ENXIO will be returned. Values for .Va sr_duration , .Va sr_mindwell , and .Va sr_maxdwell shorter than 1 clock tick are rounded up to a tick. If more SSID's are supplied than the system is capable of handling the extra ones are silently ignored. If a scan operation is already in progress the request will be (silently) ignored. .It Dv IEEE80211_IOC_SCAN_CANCEL Cancel any pending/active scan operation. .It Dv IEEE80211_IOC_SHORTGI Set whether or not Short Guard Interval (SGI) is enabled using the value in .Va i_val . Note SGI is only used when operating on an HT (802.11n) channel. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_SMPS Set the Spatial Multiplexing Power Save (SMPS) setting to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_SMPS above for details. .It Dv IEEE80211_IOC_SSID Set the desired SSID using the value pointed to by .Va i_data . The string may be at most IEEE80211_NWID_LEN bytes. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_STA_STATS Clear accumulated statistics for the specified station. .It Dv IEEE80211_IOC_STA_VLAN Set the VLAN tag for the specified station using the information pointed to by .Va i_data . .It Dv IEEE80211_IOC_TDMA_BINTERVAL Set the interval between Beacon frames to the value in .Va i_val . Values must be positive. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TDMA_SLOT Set the current TDMA slot to the value in .Va i_val . Values must be in the range [0-slotcnt]. Slot 0 identifies the master in the TDMA network; if it running it will immediately start sending Beacon frames. .It Dv IEEE80211_IOC_TDMA_SLOTCNT Set the number of slots in the TDMA network to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TDMA_SLOTLEN Set the length of the TDMA slot assigned to each station in the network to the value in .Va i_val . Slot lengths must be in the range 200 usecs to 1024 milliseconds (though values outside the range 1-200ms are unlikely to work well). This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TSN Set whether or not Transitional Security Network (TSN) is enabled using the value in .Va i_val . .It Dv IEEE80211_IOC_TURBOP Set whether Atheros Dynamic Turbo mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_TXPARAMS Set transmit parameters using the data pointed to be .Va i_data . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_TXPOWER Set the maximum transmit power limit in .5 dBm units to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_WEP Set the current WEP mode to the value in .Va i_val . See .Dv IEEE80211_IOC_WEP above for valid values. This request causes a running interface to be restarted. Note this request is deprecated; use .Dv IEEE80211_IOC_PRIVACY and .Dv IEEE80211_IOC_DROPUNENCRYPTED instead. .It Dv IEEE80211_IOC_WEPKEY Set the WEP key indicated by .Va i_val using the data pointed to by .Va i_data . Note this request is deprecated; use .Dv IEEE80211_IOC_WPAKEY instead. .It Dv IEEE80211_IOC_WEPTXKEY Set the default transmit key used for transmission to the value in .Va i_val . .It Dv IEEE80211_IOC_WME Set whether or not WME/WMM support is enabled using the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_WME_ACKPOLICY Set the WME ACK Policy for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_ACM Set the WME Admission Control Mechanism for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_AIFS Set the WME AIFS parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_CWMAX Set the WME CWmax parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_CWMIN Set the WME CWmin parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_TXOPLIMIT Set the WME TxOpLimit parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WPA Set the WPA configuration using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_WPA above for details. .It Dv IEEE80211_IOC_WPAKEY Set the requested cryptographic key using data in the buffer pointed to by .Va i_data . See .Dv IEEE80211_IOC_WPAKEY for details. .It Dv IEEE80211_IOC_WPS Set whether or not Wi-FI Protected Setup (WPS) is enabled using the value in .Va i_val . .El .Sh SEE ALSO .Xr ioctl 2 , .Xr wlan 4 , .Xr wlan_acl 4 , .Xr wlan_xauth 4 , .Xr ifconfig 8 , .Xr hostapd 8 , .Xr wpa_supplicant 8 . Index: stable/9/share/man/man4/ng_async.4 =================================================================== --- stable/9/share/man/man4/ng_async.4 (revision 290886) +++ stable/9/share/man/man4/ng_async.4 (revision 290887) @@ -1,173 +1,173 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_async.8,v 1.6 1999/01/25 23:46:25 archie Exp $ .\" .Dd January 19, 1999 .Dt NG_ASYNC 4 .Os .Sh NAME .Nm ng_async .Nd asynchronous framing netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_async.h .Sh DESCRIPTION The .Nm async node type performs conversion between synchronous frames and asynchronous frames, as defined for the PPP protocol in RFC 1662. Asynchronous framing uses flag bytes and octet-stuffing to simulate a frame oriented connection over an octet-oriented asynchronous serial line. .Pp The node transmits and receives asynchronous data on the .Dv async hook. Mbuf boundaries of incoming data are ignored. Once a complete packet has been received, it is decoded and stripped of all framing bytes, and transmitted out the .Dv sync hook as a single frame. .Pp Synchronous frames are transmitted and received on the .Dv sync hook. Packets received on this hook are encoded as asynchronous frames and sent out on .Dv async . Received packets should start with the address and control fields, or the PPP protocol field if address and control field compression is employed, and contain no checksum field. If the first four bytes are .Dv "0xff 0x03 0xc0 0x21" (an LCP protocol frame) then complete control character escaping is enabled for that frame (in PPP, LCP packets are always sent with no address and control field compression and all control characters escaped). .Pp This node supports .Dq flag sharing for packets transmitted on .Dv async . This is an optimization where the trailing flag byte of one frame is shared with the opening flag byte of the next. Flag sharing between frames is disabled after one second of transmit idle time. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width foobar .It Dv async Asynchronous connection. Typically this hook would be connected to a .Xr ng_tty 4 node, which handles transmission of serial data over a tty device. .It Dv sync Synchronous connection. This hook sends and receives synchronous frames. For PPP, these frames should contain address, control, and protocol fields, but no checksum field. Typically this hook would be connected to an individual link hook of a .Xr ng_ppp 4 type node. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_ASYNC_CMD_GET_STATS This command returns a .Dv "struct ng_async_stat" containing node statistics for packet, octet, and error counts. .It Dv NGM_ASYNC_CMD_CLR_STATS Clears the node statistics. .It Dv NGM_ASYNC_CMD_SET_CONFIG Sets the node configuration, which is described by a .Dv "struct ng_async_cfg" : .Bd -literal -offset 4n struct ng_async_cfg { u_char enabled; /* Turn encoding on/off */ - u_int16_t amru; /* Max receive async frame len */ - u_int16_t smru; /* Max receive sync frame len */ - u_int32_t accm; /* ACCM encoding */ + uint16_t amru; /* Max receive async frame len */ + uint16_t smru; /* Max receive sync frame len */ + uint32_t accm; /* ACCM encoding */ }; .Ed .Pp The .Dv enabled field enables or disables all encoding/decoding functions (default disabled). When disabled, the node operates in simple .Dq pass through mode. The .Dv amru and .Dv smru fields are the asynchronous and synchronous MRU (maximum receive unit) values, respectively. These both default to 1600; note that the async MRU applies to the incoming frame length after asynchronous decoding. The .Dv accm field is the asynchronous character control map, which controls the escaping of characters 0x00 thorough 0x1f (default 0xffffffff). .It Dv NGM_ASYNC_CMD_GET_CONFIG This command returns the current configuration structure. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ppp 4 , .Xr ng_tty 4 , .Xr ngctl 8 .Rs .%A W. Simpson .%T "PPP in HDLC-link Framing" .%O RFC 1662 .Re .Rs .%A W. Simpson .%T "The Point-to-Point Protocol (PPP)" .%O RFC 1661 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: stable/9/share/man/man4/ng_bridge.4 =================================================================== --- stable/9/share/man/man4/ng_bridge.4 (revision 290886) +++ stable/9/share/man/man4/ng_bridge.4 (revision 290887) @@ -1,213 +1,213 @@ .\" Copyright (c) 2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd May 5, 2010 .Dt NG_BRIDGE 4 .Os .Sh NAME .Nm ng_bridge .Nd Ethernet bridging netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_bridge.h .Sh DESCRIPTION The .Nm bridge node type performs Ethernet bridging over one or more links. Each link (represented by a connected hook) is used to transmit and receive raw Ethernet frames. As packets are received, the node learns which link each host resides on. Packets unicast to a known host are directed out the appropriate link only, and other links are spared the traffic. This behavior is in contrast to a hub, which always forwards every received packet to every other link. .Sh LOOP DETECTION The .Nm bridge node incorporates a simple loop detection algorithm. A loop is when two ports are connected to the same physical medium. Loops are important to avoid because of packet storms, which severely degrade performance. A packet storm results when the same packet is sent and received over and over again. If a host is detected on link A, and is then detected on link B within a certain time period after first being detected on link A, then link B is considered to be a looped back link. The time period is called the minimum stable time. .Pp A looped back link will be temporarily muted, i.e., all traffic received on that link is ignored. .Sh IPFW PROCESSING Processing of IP packets via the .Xr ipfirewall 4 mechanism on a per-link basis is not yet implemented. .Sh HOOKS This node type supports up to .Dv NG_BRIDGE_MAX_LINKS hooks. Each connected hook represents a bridged link. The hooks are named .Dv link0 , .Dv link1 , etc. Typically these hooks are connected to the .Dv lower hooks of one or more .Xr ng_ether 4 nodes. To connect the host machine to a bridged network, simply connect the .Dv upper hook of an .Xr ng_ether 4 node to the bridge node. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_BRIDGE_SET_CONFIG Set the node configuration. This command takes a .Dv "struct ng_bridge_config" as an argument: .Bd -literal -offset 0n /* Node configuration structure */ struct ng_bridge_config { u_char ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */ u_char debugLevel; /* debug level */ - u_int32_t loopTimeout; /* link loopback mute time */ - u_int32_t maxStaleness; /* max host age before nuking */ - u_int32_t minStableAge; /* min time for a stable host */ + uint32_t loopTimeout; /* link loopback mute time */ + uint32_t maxStaleness; /* max host age before nuking */ + uint32_t minStableAge; /* min time for a stable host */ }; .Ed .Pp The .Dv ipfw array enables .Xr ipfirewall 4 processing of IP packets received on the corresponding links. The .Dv debugLevel field sets the debug level on the node. At level of 2 or greater, detected loops are logged. The default level is 1. .Pp The .Dv loopTimeout determines how long (in seconds) a looped link is muted. The default is 60 seconds. The .Dv maxStaleness parameter determines how long a period of inactivity before a host's entry is forgotten. The default is 15 minutes. The .Dv minStableAge determines how quickly a host must jump from one link to another before we declare a loopback condition. The default is one second. .Pp .It Dv NGM_BRIDGE_GET_CONFIG Returns the current configuration as a .Dv "struct ng_bridge_config" . .It Dv NGM_BRIDGE_RESET Causes the node to forget all hosts and unmute all links. The node configuration is not changed. .It Dv NGM_BRIDGE_GET_STATS This command takes a four byte link number as an argument and returns a .Dv "struct ng_bridge_link_stats" containing statistics for the corresponding link, which must be currently connected: .Bd -literal -offset 0n /* Statistics structure (one for each link) */ struct ng_bridge_link_stats { - u_int64_t recvOctets; /* total octets rec'd on link */ - u_int64_t recvPackets; /* total pkts rec'd on link */ - u_int64_t recvMulticasts; /* multicast pkts rec'd on link */ - u_int64_t recvBroadcasts; /* broadcast pkts rec'd on link */ - u_int64_t recvUnknown; /* pkts rec'd with unknown dest addr */ - u_int64_t recvRunts; /* pkts rec'd less than 14 bytes */ - u_int64_t recvInvalid; /* pkts rec'd with bogus source addr */ - u_int64_t xmitOctets; /* total octets xmit'd on link */ - u_int64_t xmitPackets; /* total pkts xmit'd on link */ - u_int64_t xmitMulticasts; /* multicast pkts xmit'd on link */ - u_int64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ - u_int64_t loopDrops; /* pkts dropped due to loopback */ - u_int64_t loopDetects; /* number of loop detections */ - u_int64_t memoryFailures; /* times couldn't get mem or mbuf */ + uint64_t recvOctets; /* total octets rec'd on link */ + uint64_t recvPackets; /* total pkts rec'd on link */ + uint64_t recvMulticasts; /* multicast pkts rec'd on link */ + uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ + uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ + uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ + uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ + uint64_t xmitOctets; /* total octets xmit'd on link */ + uint64_t xmitPackets; /* total pkts xmit'd on link */ + uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ + uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ + uint64_t loopDrops; /* pkts dropped due to loopback */ + uint64_t loopDetects; /* number of loop detections */ + uint64_t memoryFailures; /* times couldn't get mem or mbuf */ }; .Ed .It Dv NGM_BRIDGE_CLR_STATS This command takes a four byte link number as an argument and clears the statistics for that link. .It Dv NGM_BRIDGE_GETCLR_STATS Same as .Dv NGM_BRIDGE_GET_STATS , but also atomically clears the statistics as well. .It Dv NGM_BRIDGE_GET_TABLE Returns the current host mapping table used to direct packets, in a .Dv "struct ng_bridge_host_ary" . .It Dv NGM_BRIDGE_SET_PERSISTENT This command sets the persistent flag on the node, and takes no arguments. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. Setting the persistent flag via a .Dv NGM_BRIDGE_SET_PERSISTENT control message disables automatic node shutdown when the last hook gets disconnected. .Sh FILES .Bl -tag -width XXXXXXXX -compact .It Pa /usr/share/examples/netgraph/ether.bridge Example script showing how to set up a bridging network .El .Sh SEE ALSO .Xr if_bridge 4 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_hub 4 , .Xr ng_one2many 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.2 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: stable/9/share/man/man4/ng_btsocket.4 =================================================================== --- stable/9/share/man/man4/ng_btsocket.4 (revision 290886) +++ stable/9/share/man/man4/ng_btsocket.4 (revision 290887) @@ -1,354 +1,354 @@ .\" Copyright (c) 2001-2002 Maksim Yevmenkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: ng_btsocket.4,v 1.7 2003/05/21 19:37:35 max Exp $ .\" $FreeBSD$ .\" .Dd July 8, 2002 .Dt NG_BTSOCKET 4 .Os .Sh NAME .Nm ng_btsocket .Nd Bluetooth sockets layer .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In sys/bitstring.h .In netgraph/bluetooth/include/ng_hci.h .In netgraph/bluetooth/include/ng_l2cap.h .In netgraph/bluetooth/include/ng_btsocket.h .Sh DESCRIPTION The .Nm module implements three Netgraph node types. Each type in its turn implements one protocol within .Dv PF_BLUETOOTH domain. .Sh Dv BLUETOOTH_PROTO_HCI Sh protocol .Ss Dv SOCK_RAW Ss HCI sockets Implemented by .Nm btsock_hci_raw Netgraph type. Raw HCI sockets allow sending of raw HCI command datagrams only to correspondents named in .Xr send 2 calls. Raw HCI datagrams (HCI commands, events and data) are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. Raw HCI sockets can also be used to control HCI nodes. .Pp The Bluetooth raw HCI socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for raw HCI sockets */ struct sockaddr_hci { u_char hci_len; /* total length */ u_char hci_family; /* address family */ char hci_node[16]; /* HCI node name */ }; .Ed .Pp Raw HCI sockets support a number of .Xr ioctl 2 requests such as: .Bl -tag -width indent .It Dv SIOC_HCI_RAW_NODE_GET_STATE Returns current state for the HCI node. .It Dv SIOC_HCI_RAW_NODE_INIT Turn on .Dq inited bit for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_DEBUG Returns current debug level for the HCI node. .It Dv SIOC_HCI_RAW_NODE_SET_DEBUG Sets current debug level for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_BUFFER Returns current state of data buffers for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_BDADDR Returns BD_ADDR for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_FEATURES Returns the list of features supported by hardware for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_STAT Returns various statistic counters for the HCI node. .It Dv SIOC_HCI_RAW_NODE_RESET_STAT Resets all statistic counters for the HCI node to zero. .It Dv SIOC_HCI_RAW_NODE_FLUSH_NEIGHBOR_CACHE Remove all neighbor cache entries for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE Returns content of the neighbor cache for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL and SCO links) for the HCI node. .It SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK Returns current link policy settings mask for the HCI node. .It SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK Sets current link policy settings mask for the HCI node. .It SIOC_HCI_RAW_NODE_GET_PACKET_MASK Returns current packet mask for the HCI node. .It SIOC_HCI_RAW_NODE_SET_PACKET_MASK Sets current packet mask for the HCI node. .It SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH Returns current value of the role switch parameter for the HCI node. .It SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH Sets new value of the role switch parameter for the HCI node. .El .Pp The .Va net.bluetooth.hci.sockets.raw.ioctl_timeout variable, that can be examined and set via .Xr sysctl 8 , controls the control request timeout (in seconds) for raw HCI sockets. .Pp Raw HCI sockets support filters. The application can filter certain HCI datagram types. For HCI event datagrams the application can set additional filter. The raw HCI socket filter defined as follows: .Bd -literal -offset indent /* * Raw HCI socket filter. * * For packet mask use (1 << (HCI packet indicator - 1)) * For event mask use (1 << (Event - 1)) */ struct ng_btsocket_hci_raw_filter { bitstr_t bit_decl(packet_mask, 32); bitstr_t bit_decl(event_mask, (NG_HCI_EVENT_MASK_SIZE * 8)); }; .Ed .Pp The .Dv SO_HCI_RAW_FILTER option defined at .Dv SOL_HCI_RAW level can be used to obtain via .Xr getsockopt 2 or change via .Xr setsockopt 2 raw HCI socket's filter. .Sh Dv BLUETOOTH_PROTO_L2CAP Sh protocol The Bluetooth L2CAP socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for L2CAP sockets */ struct sockaddr_l2cap { u_char l2cap_len; /* total length */ u_char l2cap_family; /* address family */ - u_int16_t l2cap_psm; /* Protocol/Service Multiplexor */ + uint16_t l2cap_psm; /* Protocol/Service Multiplexor */ bdaddr_t l2cap_bdaddr; /* address */ }; .Ed .Ss Dv SOCK_RAW Ss L2CAP sockets Implemented by .Nm btsock_l2c_raw Netgraph type. Raw L2CAP sockets do not provide access to raw L2CAP datagrams. These sockets used to control L2CAP nodes and to issue special L2CAP requests such as .Dv ECHO_REQUEST and .Dv GET_INFO request. .Pp Raw L2CAP sockets support number of .Xr ioctl 2 requests such as: .Bl -tag -width indent .It Dv SIOC_L2CAP_NODE_GET_FLAGS Returns current state for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_DEBUG Returns current debug level for the L2CAP node. .It Dv SIOC_L2CAP_NODE_SET_DEBUG Sets current debug level for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL links) for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_CHAN_LIST Returns list of active channels for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO Returns current value of the auto disconnect timeout for the L2CAP node. .It Dv SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO Sets current value of the auto disconnect timeout for the L2CAP node. .It Dv SIOC_L2CAP_L2CA_PING Issues L2CAP .Dv ECHO_REQUEST . .It Dv SIOC_L2CAP_L2CA_GET_INFO Issues L2CAP .Dv GET_INFO request. .El .Pp The .Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout variable, that can be examined and set via .Xr sysctl 8 , controls the control request timeout (in seconds) for raw L2CAP sockets. .Ss Dv SOCK_SEQPACKET Ss L2CAP sockets Implemented by .Nm btsock_l2c Netgraph type. L2CAP sockets are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default, L2CAP sockets are created active; to create a passive socket, the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Pp L2CAP sockets support .Dq "wildcard addressing" . In this case, socket must be bound to .Dv NG_HCI_BDADDR_ANY address. Note that PSM (Protocol/Service Multiplexor) field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and PSM (Protocol/Service Multiplexor). .Pp L2CAP sockets support number of options defined at .Dv SOL_L2CAP level which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 : .Bl -tag -width indent .It Dv SO_L2CAP_IMTU Get (set) maximum payload size the local socket is capable of accepting. .It Dv SO_L2CAP_OMTU Get maximum payload size the remote socket is capable of accepting. .It Dv SO_L2CAP_IFLOW Get incoming flow specification for the socket. .Bf -emphasis Not implemented. .Ef .It Dv SO_L2CAP_OFLOW Get (set) outgoing flow specification for the socket. .Bf -emphasis Not implemented. .Ef .It Dv SO_L2CAP_FLUSH Get (set) value of the flush timeout. .Bf -emphasis Not implemented. .Ef .El .Sh Dv BLUETOOTH_PROTO_RFCOMM Sh protocol The Bluetooth RFCOMM socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for RFCOMM sockets */ struct sockaddr_rfcomm { u_char rfcomm_len; /* total length */ u_char rfcomm_family; /* address family */ bdaddr_t rfcomm_bdaddr; /* address */ - u_int8_t rfcomm_channel; /* channel */ + uint8_t rfcomm_channel; /* channel */ }; .Ed .Ss Dv SOCK_STREAM Ss RFCOMM sockets Note that RFCOMM sockets do not have associated Netgraph node type. RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. RFCOMM sockets are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default, RFCOMM sockets are created active; to create a passive socket, the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Pp RFCOMM sockets support .Dq "wildcard addressing" . In this case, socket must be bound to .Dv NG_HCI_BDADDR_ANY address. Note that RFCOMM channel field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and RFCOMM channel. .Pp The following options, which can be tested with .Xr getsockopt 2 call, are defined at .Dv SOL_RFCOMM level for RFCOMM sockets: .Bl -tag -width indent .It Dv SO_RFCOMM_MTU Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM channel. Note that application still can write/read bigger chunks to/from the socket. .It Dv SO_RFCOMM_FC_INFO Return the flow control information for the underlying RFCOMM channel. .El .Pp The .Va net.bluetooth.rfcomm.sockets.stream.timeout variable, that can be examined and set via .Xr sysctl 8 , controls the connection timeout (in seconds) for RFCOMM sockets. .Sh HOOKS These node types support hooks with arbitrary names (as long as they are unique) and always accept hook connection requests. .Sh NETGRAPH CONTROL MESSAGES These node types support the generic control messages. .Sh SHUTDOWN These nodes are persistent and cannot be shut down. .Sh SEE ALSO .Xr btsockstat 1 , .Xr socket 2 , .Xr netgraph 4 , .Xr ng_bluetooth 4 , .Xr ng_hci 4 , .Xr ng_l2cap 4 , .Xr ngctl 8 , .Xr sysctl 8 .Sh HISTORY The .Nm module was implemented in .Fx 5.0 . .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report if found. Index: stable/9/share/man/man4/ng_car.4 =================================================================== --- stable/9/share/man/man4/ng_car.4 (revision 290886) +++ stable/9/share/man/man4/ng_car.4 (revision 290887) @@ -1,214 +1,214 @@ .\" Copyright (c) 2005 Nuno Antunes .\" Copyright (c) 2007 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 11, 2007 .Dt NG_CAR 4 .Os .Sh NAME .Nm ng_car .Nd Committed Access Rate netgraph node type .Sh SYNOPSIS .In netgraph/ng_car.h .Sh DESCRIPTION The .Nm car node type limits traffic flowing through it using: .Pp .Bl -bullet -compact .It Single rate three color marker as described in RFC 2697, .It Two rate three color marker as described in RFC 2698, .It RED-like rate limit algorithm used by Cisco, .It Traffic shaping with RED. .El .Sh HOOKS This node type supports the following hooks: .Bl -tag -width indent .It Va upper Hook leading to upper layer protocols. .It Va lower Hook leading to lower layer protocols. .El .Pp Traffic flowing from .Va upper to .Va lower is considered .Sy downstream traffic. Traffic flowing from .Va lower to .Va upper is considered .Sy upstream traffic. .Sh MODES OF OPERATION Each hook can operate in one of the following modes: .Bl -tag -width indent .It Dv NG_CAR_SINGLE_RATE Single rate three color marker as described in RFC 2697. Committed burst packets are counted as green, extended burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR (Committed Information Rate) speed. When it is full, exceeded burst getting refilled. .It Dv NG_CAR_DOUBLE_RATE Two rate three color marker as described in RFC 2698. Committed burst packets are counted as green, peak burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR speed. Peak burst getting refilled with PIR (Peak Information Rate) speed at the same time. .It Dv NG_CAR_RED Similar to .Dv NG_CAR_SINGLE_RATE , but with different understanding of extended burst. When normal burst exceeded and extended burst is used, packets are counted red with probability equal to part of extended burst consumed. Extended burst getting refilled first. When it is full, committed burst getting refilled. This behavior is similar to RED active queue management algorithm. .Pp This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE. .It Dv NG_CAR_SHAPE Committed burst packets are counted as green, exceeding packets are delayed by queue with RED management and counted as yellow. Packets dropped by queue counted as red. Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%. .Pp Traffic shaping is much more polite to the TCP traffic than rate limit on links with bandwidth * delay product less than 6-8 TCP segments, but it consumes additional system resources for queue processing. .El By default, all information rates are measured in bits per second and bursts are measured in bytes. But when NG_CAR_COUNT_PACKETS option is enabled, rates are measured in packets per second and bursts are in packets. .Sh CONTROL MESSAGES This node type supports the generic control messages and the following specific messages. .Bl -tag -width indent .It Dv NGM_CAR_SET_CONF Pq Li setconf Set node configuration to the specified at .Vt "struct ng_car_bulkconf" .It Dv NGM_CAR_GET_CONF Pq Li getconf Return current node configuration as .Vt "struct ng_car_bulkconf" .Bd -literal struct ng_car_hookconf { - u_int64_t cbs; /* Committed burst size */ - u_int64_t ebs; /* Exceeded/Peak burst size */ - u_int64_t cir; /* Committed information rate */ - u_int64_t pir; /* Peak information rate */ - u_int8_t green_action; /* Action for green packets */ - u_int8_t yellow_action; /* Action for yellow packets */ - u_int8_t red_action; /* Action for red packets */ - u_int8_t mode; /* operation mode */ - u_int8_t opt; /* mode options */ + uint64_t cbs; /* Committed burst size */ + uint64_t ebs; /* Exceeded/Peak burst size */ + uint64_t cir; /* Committed information rate */ + uint64_t pir; /* Peak information rate */ + uint8_t green_action; /* Action for green packets */ + uint8_t yellow_action; /* Action for yellow packets */ + uint8_t red_action; /* Action for red packets */ + uint8_t mode; /* operation mode */ + uint8_t opt; /* mode options */ }; /* possible actions (..._action) */ enum { NG_CAR_ACTION_FORWARD = 1, NG_CAR_ACTION_DROP }; /* operation modes (mode) */ enum { NG_CAR_SINGLE_RATE = 0, NG_CAR_DOUBLE_RATE, NG_CAR_RED, NG_CAR_SHAPE }; /* mode options (opt) */ #define NG_CAR_COUNT_PACKETS 2 struct ng_car_bulkconf { struct ng_car_hookconf upstream; struct ng_car_hookconf downstream; }; .Ed .It Dv NGM_CAR_GET_STATS Pq Li getstats Return node statistics as .Vt "struct ng_car_bulkstats" .Bd -literal struct ng_car_hookstats { - u_int64_t passed_pkts; - u_int64_t droped_pkts; - u_int64_t green_pkts; - u_int64_t yellow_pkts; - u_int64_t red_pkts; - u_int64_t errors; + uint64_t passed_pkts; + uint64_t droped_pkts; + uint64_t green_pkts; + uint64_t yellow_pkts; + uint64_t red_pkts; + uint64_t errors; }; struct ng_car_bulkstats { struct ng_car_hookstats upstream; struct ng_car_hookstats downstream; }; .Ed .It Dv NGM_CAR_CLR_STATS Pq Li clrstats Clear node statistics. .It Dv NGM_CAR_GETCLR_STATS Pq Li getclrstats Atomically return and clear node statistics. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s and incoming packet rate to 5000pps. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer fxp0: car lower lower name fxp0:lower fxp0_car connect fxp0: fxp0_car: upper upper msg fxp0_car: setconf { downstream={ cir=20000000 cbs=2500000 ebs=2500000 greenAction=1 yellowAction=1 redAction=2 mode=2 } upstream={ cir=5000 cbs=100 ebs=100 greenAction=1 yellowAction=1 redAction=2 mode=2 opt=2 } } SEQ .Ed .Sh SEE ALSO .Xr netgraph 4 , .Xr ngctl 8 .Rs .%A J. Heinanen .%T "A Single Rate Three Color Marker" .%O RFC 2697 .Re .Rs .%A J. Heinanen .%T "A Two Rate Three Color Marker" .%O RFC 2698 .Re .Sh AUTHORS .An Nuno Antunes Aq nuno.antunes@gmail.com .An Alexander Motin Aq mav@FreeBSD.org .Sh BUGS At this moment only DROP and FORWARD actions are implemented. Index: stable/9/share/man/man4/ng_ccatm.4 =================================================================== --- stable/9/share/man/man4/ng_ccatm.4 (revision 290886) +++ stable/9/share/man/man4/ng_ccatm.4 (revision 290887) @@ -1,324 +1,324 @@ .\" .\" Copyright (c) 2001-2004 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" Copyright (c) 2005 .\" Hartmut Brandt. .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 10, 2005 .Dt NG_CCATM 4 .Os .Sh NAME .Nm ng_ccatm .Nd "ATM Call Control netgraph node type" .Sh SYNOPSIS .In netnatm/unimsg.h .In netnatm/msg/unistruct.h .In netnatm/sig/unidef.h .In netnatm/api/unisap.h .In netnatm/api/atmapi.h .In netnatm/api/ccatm.h .In netgraph.h .In netgraph/ng_uni.h .In netgraph/ng_ccatm.h .Sh DESCRIPTION The .Nm node implements the API specified by the ATM Forum for access to ATM services (see ATM-Forum document .Pa af-saa-0108 ) . This document specifies the semantics of the API, not the exact language binding. For this reason, it is expected that this implementation is neither compile-time nor binary compatible with other implementations of this API. It should, however, be fairly straightforward to convert between different API implementations. .Pp This node is usually stacked on top of one or more UNI nodes (see .Xr ng_uni 4 ) . Each of these hooks appears as a .Dq port to the user of the node. It also has one hook connected to the ILMI daemon for management purposes. .Pp The node is removed when it receives a .Dv NGM_SHUTDOWN messages or when all hooks are disconnected. .Sh HOOKS The node understands a number of hooks with predefined names and an unlimited number of hooks for user connections. The predefined names are: .Bl -tag -width ".Va orphans" .It Va uni Ns Ar NNN These hooks stack the .Nm node on top of a UNI stack. The node expects the interface on these hooks to conform to the upper interface specified in .Xr ng_uni 4 . These hooks are forced into queuing mode, so that there are no circular calls from call control to UNI and UNI back to call control. The .Ar NNN in the hook name is the decimal port number and should not be zero. The port number is a 32-bit unsigned integer. .It Va manage This hook should be connected to the ILMI daemon. No data is ever sent on this hook and all received data is discarded. The hook is used to send control messages along. .It Va dump On receipt of a .Dv NGM_CCATM_DUMP command a textual description of the current state of the node is sent out of this hook. This text is sent as one large message consisting of more than one .Vt mbuf . .El .Pp All other hook names are taken to be user hooks and correspond to an ATM endpoint as specified in the ATM Forum document. The interface on these hooks is defined in .In atmapi.h and uses a structure .Bd -literal struct ccatm_op { - u_int32_t op; /* request code */ + uint32_t op; /* request code */ u_char data[]; /* optional data */ }; .Ed .Pp This structure is followed directly by the data for the operation. The opcode is one of the following: .Bd -literal enum atmop { ATMOP_RESP, ATMOP_ABORT_CONNECTION, ATMOP_ACCEPT_INCOMING_CALL, ATMOP_ADD_PARTY, ATMOP_ADD_PARTY_REJECT, ATMOP_ADD_PARTY_SUCCESS, ATMOP_ARRIVAL_OF_INCOMING_CALL, ATMOP_CALL_RELEASE, ATMOP_CONNECT_OUTGOING_CALL, ATMOP_DROP_PARTY, ATMOP_GET_LOCAL_PORT_INFO, ATMOP_P2MP_CALL_ACTIVE, ATMOP_P2P_CALL_ACTIVE, ATMOP_PREPARE_INCOMING_CALL, ATMOP_PREPARE_OUTGOING_CALL, ATMOP_QUERY_CONNECTION_ATTRIBUTES, ATMOP_REJECT_INCOMING_CALL, ATMOP_SET_CONNECTION_ATTRIBUTES, ATMOP_WAIT_ON_INCOMING_CALL, ATMOP_SET_CONNECTION_ATTRIBUTES_X, ATMOP_QUERY_CONNECTION_ATTRIBUTES_X, ATMOP_QUERY_STATE }; .Ed .Pp These codes correspond directly to the operations specified in the ATM Forum document with the following exceptions: .Bl -tag -width indent .It Dv ATMOP_RESP As discussed in .Xr ng_uni 4 , this is used to .Dq synchronify the interface. The argument is a .Bd -literal struct atm_resp { int32_t resp; uint32_t data; /* type of attached data */ }; .Ed .Pp If the response code .Va resp is zero, the node has accepted the user request. If something goes wrong, .Va resp contains an error code. For requests that return data, .Va data contains a code describing the type of data and the data itself starts immediately after the structure. .It Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES_X This is the same as .Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES except that it allows to query several attributes within one request. .It Dv ATMOP_SET_CONNECTION_ATTRIBUTES_X This is the same as .Dv ATMOP_SET_CONNECTION_ATTRIBUTES except that it allows to set several attributes within one request. The list of attributes is followed directly by the attributes in the same order as they appear in the list. .El .Pp If a user hook is disconnected, an active connection on that hook is released. Incoming connections waiting to be accepted are reoffered to other listening hooks or rejected. .Sh CONTROL MESSAGES Besides the generic messages the node understands the following special messages: .Bl -tag -width indent .It Dv NGM_CCATM_DUMP This causes the internal state of the node to be dumped in ASCII to the .Va dump hook. .It Dv NGM_CCATM_STOP This message causes all connections on that port to be aborted (not released!\&) and all ATM endpoints which are bound to that port to be closed. It stops processing of all messages from the UNI stack on that port UNI stack. The argument is a .Bd -literal struct ngm_ccatm_port { uint32_t port; }; .Ed .Pp .It Dv NGM_CCATM_START Start processing on the port. The argument is a .Vt ngm_ccatm_port structure. .It Dv NGM_CCATM_CLEAR This message takes a .Vt ngm_ccatm_port structure and clears all prefixes and addresses on that port. If the port number is zero, all ports are cleared. .It Dv NGM_CCATM_GET_ADDRESSES Get the list of all registered addresses on the given port. The argument is a .Vt ngm_ccatm_port structure and the result is a .Vt ngm_ccatm_get_addresses structure: .Bd -literal struct ngm_ccatm_get_addresses { uint32_t count; struct ngm_ccatm_address_req addr[0]; }; struct ngm_ccatm_address_req { - u_int32_t port; + uint32_t port; struct uni_addr addr; }; .Ed .Pp If the .Va port field is zero in the request, all addresses on all ports are returned. If it is not zero, only the addresses on that port are reported. The number of addresses is returned in the .Va count field. .It Dv NGM_CCATM_ADDRESS_REGISTERED This message is used by ILMI to inform the .Nm node that a previous address registration request was successful. This causes the node to activate that address. The argument to the message is a .Vt ngm_ccatm_address_req structure. .It Dv NGM_CCATM_ADDRESS_UNREGISTERED This message is used by ILMI to inform the .Nm node that an address has been unregistered. The node clears that address from its tables. The argument is a .Vt ngm_ccatm_address_req structure. .It Dv NGM_CCATM_SET_PORT_PARAM This request sets the parameters on the given port. The argument is a .Bd -literal struct ngm_ccatm_atm_port { uint32_t port; /* port for which to set parameters */ uint32_t pcr; /* port peak cell rate */ uint32_t max_vpi_bits; uint32_t max_vci_bits; uint32_t max_svpc_vpi; uint32_t max_svcc_vpi; uint32_t min_svcc_vci; uint8_t esi[6]; uint32_t num_addr; }; .Ed .Pp This should be used only by ILMI and when that port is stopped and the address and prefix tables of that port are empty. The .Va num_addr field is ignored. .It Dv NGM_CCATM_GET_PORT_PARAM Retrieve the parameters of the given port. The argument is a .Vt ngm_ccatm_port and the result a .Vt ngm_ccatm_atm_port . .It Dv NGM_CCATM_GET_PORTLIST Get a list of all available ports on that node. This is returned as a .Bd -literal struct ngm_ccatm_portlist { uint32_t nports; uint32_t ports[]; }; .Ed .It Dv NGM_CCATM_GETSTATE Return the state of a port. The argument is a .Vt "struct ngm_ccatm_port" and the return values as a .Vt uint32_t . .It Dv NGM_CCATM_SETLOG This requests sets a new logging level and returns the previous one. The argument is either a .Vt uint32_t in which case it specifies the new logging level, or may be empty in which case just the old level is returned as a .Vt uint32_t . .It Dv NGM_CCATM_RESET Reset the node. This is allowed only if the number of user hooks and connected UNI stacks is zero. .It Dv NGM_CCATM_GET_EXSTAT Return extended status information from the node. .El .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_uni 4 , .Xr ngctl 8 .Sh AUTHORS .An Harti Brandt Aq harti@FreeBSD.org Index: stable/9/share/man/man4/ng_cisco.4 =================================================================== --- stable/9/share/man/man4/ng_cisco.4 (revision 290886) +++ stable/9/share/man/man4/ng_cisco.4 (revision 290887) @@ -1,184 +1,184 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_cisco.8,v 1.5 1999/01/25 23:46:26 archie Exp $ .\" .Dd January 19, 1999 .Dt NG_CISCO 4 .Os .Sh NAME .Nm ng_cisco .Nd Cisco HDLC protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In netgraph/ng_cisco.h .Sh DESCRIPTION The .Nm cisco node type performs encapsulation and de-encapsulation of packets using the Cisco HDLC protocol. This is a fairly simple protocol for the transmission of packets across high speed synchronous lines. Each packet is prepended with an Ethertype, indicating the protocol. There is also a .Dq keep alive and an .Dq inquire capability. .Pp The .Dv downstream hook should connect to the synchronous line. On the other side of the node are the .Dv inet , .Dv inet6 , .Dv atalk , and .Dv ipx hooks, which transmit and receive raw IP, IPv6, AppleTalk, and IPX packets, respectively. Typically these hooks would connect to the corresponding hooks on an .Xr ng_iface 4 type node. .Sh IP Configuration In order to function properly for IP traffic, the node must be informed of the local IP address and netmask setting. This is because the protocol includes an .Dq inquire packet which we must be prepared to answer. There are two ways to accomplish this, manually and automatically. .Pp Whenever such an inquire packet is received, the node sends a .Dv NGM_CISCO_GET_IPADDR control message to the peer node connected to the .Dv inet hook (if any). If the peer responds, then that response is used. This is the automatic method. .Pp If the peer does not respond, the node falls back on its cached value for the IP address and netmask. This cached value can be set at any time with a .Dv NGM_CISCO_SET_IPADDR message, and this is the manual method. .Pp If the .Dv inet hook is connected to the .Dv inet hook of an .Xr ng_iface 4 node, as is usually the case, then configuration is automatic as the .Xr ng_iface 4 understands the .Dv NGM_CISCO_GET_IPADDR message. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width foobarbazio .It Dv downstream The connection to the synchronous line. .It Dv inet IP hook. .It Dv inet6 IPv6 hook. .It Dv atalk AppleTalk hook. .It Dv ipx IPX hook .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_CISCO_SET_IPADDR This command takes an array of two .Dv "struct in_addr" arguments. The first is the IP address of the corresponding interface and the second is the netmask. .It Dv NGM_CISCO_GET_IPADDR This command returns the IP configuration in the same format used by .Dv NGM_CISCO_SET_IPADDR . This command is also .Em sent by this node type to the .Dv inet peer whenever an IP address inquiry packet is received. .It Dv NGM_CISCO_GET_STATUS Returns a .Dv "struct ngciscostat" : .Bd -literal -offset 4n struct ngciscostat { - u_int32_t seq_retries; /* # unack'd retries */ - u_int32_t keepalive_period; /* in seconds */ + uint32_t seq_retries; /* # unack'd retries */ + uint32_t keepalive_period; /* in seconds */ }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_iface 4 , .Xr ngctl 8 .Rs .%A D. Perkins .%T "Requirements for an Internet Standard Point-to-Point Protocol" .%O RFC 1547 .Re .Sh LEGAL .Tn Cisco is a trademark of Cisco Systems, Inc. .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org , .An Archie Cobbs Aq archie@FreeBSD.org .Sh BUGS Not all of the functionality has been implemented. For example, the node does not support querying the remote end for its IP address and netmask. Index: stable/9/share/man/man4/ng_etf.4 =================================================================== --- stable/9/share/man/man4/ng_etf.4 (revision 290886) +++ stable/9/share/man/man4/ng_etf.4 (revision 290887) @@ -1,154 +1,154 @@ .\" .\" Copyright (c) 2001, FreeBSD Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice unmodified, this list of conditions, and the following .\" disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 16, 2006 .Dt NG_ETF 4 .Os .Sh NAME .Nm ng_etf .Nd Ethertype filtering netgraph node type .Sh SYNOPSIS .In netgraph.h .In netgraph/ng_etf.h .Sh DESCRIPTION The .Nm etf node type multiplexes and filters data between hooks on the basis of the ethertype found in an Ethernet header, presumed to be in the first 14 bytes of the data. Incoming Ethernet frames are accepted on the .Em downstream hook and if the ethertype matches a value which the node has been configured to filter, the packet is forwarded out the hook which was identified at the time that value was configured. If it does not match a configured value, it is passed to the .Em nomatch hook. If the .Em nomatch hook is not connected, the packet is dropped. .Pp Packets travelling in the other direction (towards the .Em downstream hook) are also examined and filtered. If a packet has an ethertype that matches one of the values configured into the node, it must have arrived in on the hook for which that value was configured, otherwise it will be discarded. Ethertypes of values other than those configured by the control messages must have arrived via the .Em nomatch hook. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Em downstream" .It Em downstream Typically this hook would be connected to a .Xr ng_ether 4 node, using the .Em lower hook. .It Em nomatch Typically this hook would also be connected to an .Xr ng_ether 4 type node using the .Em upper hook. .It Aq Em "any legal name" Any other hook name will be accepted and can be used as the match target of an ethertype. Typically this hook would be attached to a protocol handling node that requires and generates packets with a particular set of ethertypes. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width 4n .It Dv NGM_ETF_GET_STATUS This command returns a .Vt "struct ng_etfstat" containing node statistics for packet counts. .It Dv NGM_ETF_SET_FILTER Sets the a new ethertype filter into the node and specifies the hook to and from which packets of that type should use. The hook and ethertype are specified in a structure of type .Vt "struct ng_etffilter" : .Bd -literal -offset 4n struct ng_etffilter { char matchhook[NG_HOOKSIZ]; /* hook name */ - u_int16_t ethertype; /* catch these */ + uint16_t ethertype; /* catch these */ }; .Ed .El .Sh EXAMPLES Using .Xr ngctl 8 it is possible to set a filter in place from the command line as follows: .Bd -literal -offset 4n #!/bin/sh ETHER_IF=fxp0 MATCH1=0x834 MATCH2=0x835 cat </tmp/xwert # Make a new ethertype filter and attach to the Ethernet lower hook. # first remove left over bits from last time. shutdown ${ETHER_IF}:lower mkpeer ${ETHER_IF}: etf lower downstream # Give it a name to easily refer to it. name ${ETHER_IF}:lower etf # Connect the nomatch hook to the upper part of the same interface. # All unmatched packets will act as if the filter is not present. connect ${ETHER_IF}: etf: upper nomatch DONE ngctl -f /tmp/xwert # something to set a hook to catch packets and show them. echo "Unrecognised packets:" nghook -a etf: newproto & # Filter two random ethertypes to that hook. ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} } ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} } .Ed .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ngctl 8 , .Xr nghook 8 .Sh HISTORY The .Nm node type was implemented in .Fx 5.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org Index: stable/9/share/man/man4/ng_hci.4 =================================================================== --- stable/9/share/man/man4/ng_hci.4 (revision 290886) +++ stable/9/share/man/man4/ng_hci.4 (revision 290887) @@ -1,387 +1,387 @@ .\" Copyright (c) 2001-2002 Maksim Yevmenkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: ng_hci.4,v 1.3 2003/05/21 19:37:35 max Exp $ .\" $FreeBSD$ .\" .Dd June 25, 2002 .Dt NG_HCI 4 .Os .Sh NAME .Nm ng_hci .Nd Netgraph node type that is also a Bluetooth Host Controller Interface (HCI) layer .Sh SYNOPSIS .In sys/types.h .In netgraph/bluetooth/include/ng_hci.h .Sh DESCRIPTION The .Nm hci node type is a Netgraph node type that implements Bluetooth Host Controller Interface (HCI) layer as per chapter H1 of the Bluetooth Specification Book v1.1. .Sh INTRODUCTION TO BLUETOOTH Bluetooth is a short-range radio link intended to replace the cable(s) connecting portable and/or fixed electronic devices. Bluetooth operates in the unlicensed ISM band at 2.4 GHz. The Bluetooth protocol uses a combination of circuit and packet switching. Bluetooth can support an asynchronous data channel, up to three simultaneous synchronous voice channels, or a channel which simultaneously supports asynchronous data and synchronous voice. Each voice channel supports a 64 kb/s synchronous (voice) channel in each direction. The asynchronous channel can support maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in the return direction), or 433.9 kb/s symmetric. .Pp The Bluetooth system provides a point-to-point connection (only two Bluetooth units involved), or a point-to-multipoint connection. In the point-to-multipoint connection, the channel is shared among several Bluetooth units. Two or more units sharing the same channel form a .Dq piconet . One Bluetooth unit acts as the master of the piconet, whereas the other unit(s) acts as slave(s). Up to seven slaves can be active in the piconet. In addition, many more slaves can remain locked to the master in a so-called parked state. These parked slaves cannot be active on the channel, but remain synchronized to the master. Both for active and parked slaves, the channel access is controlled by the master. .Pp Multiple piconets with overlapping coverage areas form a .Dq scatternet . Each piconet can only have a single master. However, slaves can participate in different piconets on a time-division multiplex basis. In addition, a master in one piconet can be a slave in another piconet. The piconets shall not be frequency-synchronized. Each piconet has its own hopping channel. .Ss Time Slots The channel is divided into time slots, each 625 usec in length. The time slots are numbered according to the Bluetooth clock of the piconet master. The slot numbering ranges from 0 to 2^27 -1 and is cyclic with a cycle length of 2^27. In the time slots, master and slave can transmit packets. .Ss SCO Link The SCO link is a symmetric, point-to-point link between the master and a specific slave. The SCO link reserves slots and can therefore be considered as a circuit-switched connection between the master and the slave. The SCO link typically supports time-bounded information like voice. The master can support up to three SCO links to the same slave or to different slaves. A slave can support up to three SCO links from the same master, or two SCO links if the links originate from different masters. SCO packets are never retransmitted. .Ss ACL Link In the slots not reserved for SCO links, the master can exchange packets with any slave on a per-slot basis. The ACL link provides a packet-switched connection between the master and all active slaves participating in the piconet. Both asynchronous and isochronous services are supported. Between a master and a slave only a single ACL link can exist. For most ACL packets, packet retransmission is applied to assure data integrity. .Sh HOST CONTROLLER INTERFACE (HCI) The HCI provides a command interface to the baseband controller and link manager, and access to hardware status and control registers. This interface provides a uniform method of accessing the Bluetooth baseband capabilities. .Pp The HCI layer on the Host exchanges data and commands with the HCI firmware on the Bluetooth hardware. The Host Controller Transport Layer (i.e., physical bus) driver provides both HCI layers with the ability to exchange information with each other. .Pp The Host will receive asynchronous notifications of HCI events independent of which Host Controller Transport Layer is used. HCI events are used for notifying the Host when something occurs. When the Host discovers that an event has occurred it will then parse the received event packet to determine which event occurred. The next sections specify the HCI packet formats. .Ss HCI Command Packet .Bd -literal -offset indent #define NG_HCI_CMD_PKT 0x01 typedef struct { - u_int8_t type; /* MUST be 0x1 */ - u_int16_t opcode; /* OpCode */ - u_int8_t length; /* parameter(s) length in bytes */ + uint8_t type; /* MUST be 0x1 */ + uint16_t opcode; /* OpCode */ + uint8_t length; /* parameter(s) length in bytes */ } __attribute__ ((packed)) ng_hci_cmd_pkt_t; .Ed .Pp The HCI command packet is used to send commands to the Host Controller from the Host. When the Host Controller completes most of the commands, a Command Complete event is sent to the Host. Some commands do not receive a Command Complete event when they have been completed. Instead, when the Host Controller receives one of these commands the Host Controller sends a Command Status event back to the Host when it has begun to execute the command. Later on, when the actions associated with the command have finished, an event that is associated with the sent command will be sent by the Host Controller to the Host. .Ss HCI Event Packet .Bd -literal -offset indent #define NG_HCI_EVENT_PKT 0x04 typedef struct { - u_int8_t type; /* MUST be 0x4 */ - u_int8_t event; /* event */ - u_int8_t length; /* parameter(s) length in bytes */ + uint8_t type; /* MUST be 0x4 */ + uint8_t event; /* event */ + uint8_t length; /* parameter(s) length in bytes */ } __attribute__ ((packed)) ng_hci_event_pkt_t; .Ed .Pp The HCI event packet is used by the Host Controller to notify the Host when events occur. .Ss HCI ACL Data Packet .Bd -literal -offset indent #define NG_HCI_ACL_DATA_PKT 0x02 typedef struct { - u_int8_t type; /* MUST be 0x2 */ - u_int16_t con_handle; /* connection handle + PB + BC flags */ - u_int16_t length; /* payload length in bytes */ + uint8_t type; /* MUST be 0x2 */ + uint16_t con_handle; /* connection handle + PB + BC flags */ + uint16_t length; /* payload length in bytes */ } __attribute__ ((packed)) ng_hci_acldata_pkt_t; .Ed .Pp HCI ACL data packets are used to exchange ACL data between the Host and Host Controller. .Ss HCI SCO Data Packet .Bd -literal -offset indent #define NG_HCI_SCO_DATA_PKT 0x03 typedef struct { - u_int8_t type; /* MUST be 0x3 */ - u_int16_t con_handle; /* connection handle + reserved bits */ - u_int8_t length; /* payload length in bytes */ + uint8_t type; /* MUST be 0x3 */ + uint16_t con_handle; /* connection handle + reserved bits */ + uint8_t length; /* payload length in bytes */ } __attribute__ ((packed)) ng_hci_scodata_pkt_t; .Ed .Pp HCI SCO data packets are used to exchange SCO data between the Host and Host Controller. .Sh HCI INITIALIZATION On initialization, HCI control application must issue the following HCI commands (in any order). .Bl -tag -width indent .It Dv Read_BD_ADDR To obtain BD_ADDR of the Bluetooth unit. .It Dv Read_Local_Supported_Features To obtain the list of features supported by Bluetooth unit. .It Dv Read_Buffer_Size To determine the maximum size of HCI ACL and SCO HCI data packets (excluding header) that can be sent from the Host to the Host Controller. There are also two additional return parameters that specify the total number of HCI ACL and SCO data packets that the Host Controller can have waiting for transmission in its buffers. .El .Pp As soon as HCI initialization has been successfully performed, HCI control application must turn on .Dq inited bit for the node. Once HCI node has been initialized all upstream hooks will receive a .Dv NGM_HCI_NODE_UP Netgraph message defined as follows. .Bd -literal -offset indent #define NGM_HCI_NODE_UP 112 /* HCI -> Upper */ typedef struct { - u_int16_t pkt_size; /* max. ACL/SCO packet size (w/o hdr) */ - u_int16_t num_pkts; /* ACL/SCO packet queue size */ - u_int16_t reserved; /* place holder */ + uint16_t pkt_size; /* max. ACL/SCO packet size (w/o hdr) */ + uint16_t num_pkts; /* ACL/SCO packet queue size */ + uint16_t reserved; /* place holder */ bdaddr_t bdaddr; /* bdaddr */ } ng_hci_node_up_ep; .Ed .Sh HCI FLOW CONTROL HCI layer performs flow control on baseband connection basis (i.e., ACL and SCO link). Each baseband connection has .Dq "connection handle" and queue of outgoing data packets. Upper layers protocols are allowed to send up to .Dv ( num_pkts \- .Dv pending ) packets at one time. HCI layer will send .Dv NGM_HCI_SYNC_CON_QUEUE Netgraph messages to inform upper layers about current queue state for each connection handle. The .Dv NGM_HCI_SYNC_CON_QUEUE Netgraph message is defined as follows. .Bd -literal -offset indent #define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI -> Upper */ typedef struct { - u_int16_t con_handle; /* connection handle */ - u_int16_t completed; /* number of completed packets */ + uint16_t con_handle; /* connection handle */ + uint16_t completed; /* number of completed packets */ } ng_hci_sync_con_queue_ep; .Ed .Sh HOOKS This node type supports the following hooks: .Bl -tag -width indent .It Dv drv Bluetooth Host Controller Transport Layer hook. Single HCI packet contained in single .Vt mbuf structure. .It Dv acl Upper layer protocol/node is connected to the hook. Single HCI ACL data packet contained in single .Vt mbuf structure. .It Dv sco Upper layer protocol/node is connected to the hook. Single HCI SCO data packet contained in single .Vt mbuf structure. .It Dv raw Raw hook. Every HCI frame (including HCI command frame) that goes in or out will be delivered to the hook. Usually the Bluetooth raw HCI socket layer is connected to the hook. Single HCI frame contained in single .Vt mbuf structure. .El .Sh BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES) .Bl -tag -width indent .It Dv NGM_HCI_LP_CON_REQ Requests the lower protocol to create a connection. If a physical link to the remote device does not exist, this message must be sent to the lower protocol (baseband) to establish the physical connection. .It Dv NGM_HCI_LP_DISCON_REQ Requests the lower protocol (baseband) to terminate a connection. .It Dv NGM_HCI_LP_CON_CFM Confirms success or failure of the .Dv NGM_HCI_LP_CON_REQ request to establish a lower layer (baseband) connection. This includes passing the authentication challenge if authentication is required to establish the physical link. .It Dv NGM_HCI_LP_CON_IND Indicates the lower protocol (baseband) has successfully established incoming connection. .It Dv NGM_HCI_LP_CON_RSP A response accepting or rejecting the previous connection indication request. .It Dv NGM_HCI_LP_DISCON_IND Indicates the lower protocol (baseband) has terminated connection. This could be a response to .Dv NGM_HCI_LP_DISCON_REQ or a timeout event. .It Dv NGM_HCI_LP_QOS_REQ Requests the lower protocol (baseband) to accommodate a particular QoS parameter set. .It Dv NGM_HCI_LP_QOS_CFM Confirms success or failure of the request for a given quality of service. .It Dv NGM_HCI_LP_QOS_IND Indicates the lower protocol (baseband) has detected a violation of the QoS agreement. .El .Sh NETGRAPH CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_HCI_NODE_GET_STATE Returns current state for the node. .It Dv NGM_HCI_NODE_INIT Turn on .Dq inited bit for the node. .It Dv NGM_HCI_NODE_GET_DEBUG Returns an integer containing the current debug level for the node. .It Dv NGM_HCI_NODE_SET_DEBUG This command takes an integer argument and sets current debug level for the node. .It Dv NGM_HCI_NODE_GET_BUFFER Returns current state of data buffers. .It Dv NGM_HCI_NODE_GET_BDADDR Returns BD_ADDR as cached in the node. .It Dv NGM_HCI_NODE_GET_FEATURES Returns the list of features supported by hardware (as cached by the node). .It Dv NGM_HCI_NODE_GET_NEIGHBOR_CACHE Returns content of the neighbor cache. .It Dv NGM_HCI_NODE_FLUSH_NEIGHBOR_CACHE Remove all neighbor cache entries. .It Dv NGM_HCI_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL and SCO links). .It Dv NGM_HCI_NODE_GET_STAT Returns various statistic counters. .It Dv NGM_HCI_NODE_RESET_STAT Resets all statistic counters to zero. .It NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK Sets current link policy settings mask. After the new ACL connection is created the HCI node will try set link policy for the ACL connection. By default, every supported Link Manager (LM) mode will be enabled. User can override this by setting link policy settings mask which specifies LM modes to be enabled. .It NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK Returns current link policy settings mask. .It NGM_HCI_NODE_SET_PACKET_MASK Sets current packet mask. When new baseband (ACL or SCO) connection is created the HCI node will specify every packet type supported by the device. User can override this by setting packet mask which specifies packet types to be used for new baseband connections. .It NGM_HCI_NODE_GET_PACKET_MASK Returns current packet mask. .It NGM_HCI_NODE_SET_ROLE_SWITCH Sets the value of the role switch. Role switch is enabled when this value is not zero. This is the default state. Note that actual role switch at Bluetooth link level will only be performed if hardware supports role switch and it was enabled. .It NGM_HCI_NODE_GET_ROLE_SWITCH Returns the value of the role switch for the node. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr hccontrol 8 , .Xr ngctl 8 .Sh HISTORY The .Nm hci node type was implemented in .Fx 5.0 . .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report if found. Index: stable/9/share/man/man4/ng_l2cap.4 =================================================================== --- stable/9/share/man/man4/ng_l2cap.4 (revision 290886) +++ stable/9/share/man/man4/ng_l2cap.4 (revision 290887) @@ -1,422 +1,422 @@ .\" Copyright (c) 2001-2002 Maksim Yevmenkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: ng_l2cap.4,v 1.4 2003/09/14 23:37:52 max Exp $ .\" $FreeBSD$ .\" .Dd July 4, 2002 .Dt NG_L2CAP 4 .Os .Sh NAME .Nm ng_l2cap .Nd Netgraph node type that implements Bluetooth Logical Link Control and Adaptation Protocol (L2CAP) .Sh SYNOPSIS .In sys/types.h .In netgraph/bluetooth/include/ng_hci.h .In netgraph/bluetooth/include/ng_l2cap.h .Sh DESCRIPTION The .Nm l2cap node type is a Netgraph node type that implements Bluetooth Logical Link Control and Adaptation Protocol as per chapter D of the Bluetooth Specification Book v1.1. .Pp L2CAP provides connection-oriented and connectionless data services to upper layer protocols with protocol multiplexing capability, segmentation and reassembly operation, and group abstractions. L2CAP permits higher level protocols and applications to transmit and receive L2CAP data packets up to 64 kilobytes in length. .Ss L2CAP Assumptions .Bl -enum -offset indent .It The ACL link between two units is set up. The Baseband provides orderly delivery of data packets, although there might be individual packet corruption and duplicates. No more than one ACL link exists between any two devices. .It The Baseband always provides the impression of full-duplex communication channels. This does not imply that all L2CAP communications are bi-directional. Multicasts and unidirectional traffic (e.g., video) do not require duplex channels. .It L2CAP provides a reliable channel using the mechanisms available at the Baseband layer. The Baseband always performs data integrity checks when requested and resends data until it has been successfully acknowledged or a timeout occurs. As acknowledgements may be lost, timeouts may occur even after the data has been successfully sent. .El .Sh L2CAP GENERAL OPERATION The Logical Link Control and Adaptation Protocol (L2CAP) is based around the concept of .Dq channels . Each channel is bound to a single protocol in a many-to-one fashion. Multiple channels can be bound to the same protocol, but a channel cannot be bound to multiple protocols. Each L2CAP packet received on a channel is directed to the appropriate higher level protocol. .Pp Each one of the end-points of an L2CAP channel is referred to by a channel identifier. Channel identifiers (CIDs) are local names representing a logical channel end-point on the device. Identifiers from 0x0001 to 0x003F are reserved for specific L2CAP functions. The null identifier (0x0000) is defined as an illegal identifier and must never be used as a destination end-point. All L2CAP signalling commands are sent to CID 0x0001. CID 0x0002 is reserved for group-oriented channel. The same CID must not be reused as a local L2CAP channel endpoint for multiple simultaneous L2CAP channels between a local device and some remote device. .Pp CID assignment is relative to a particular device and a device can assign CIDs independently from other devices. Thus, even if the same CID value has been assigned to (remote) channel endpoints by several remote devices connected to a single local device, the local device can still uniquely associate each remote CID with a different device. .Ss Channel Operational States .Bl -tag -width indent .It Dv NG_L2CAP_CLOSED In this state, there is no channel associated with this CID. This is the only state when a link level connection (Baseband) may not exist. Link disconnection forces all other states into the .Dv NG_L2CAP_CLOSED state. .It Dv NG_L2CAP_W4_L2CAP_CON_RSP In this state, the CID represents a local end-point and an L2CAP Connect Request message has been sent referencing this endpoint and it is now waiting for the corresponding L2CAP Connect Response message. .It Dv NG_L2CAP_W4_L2CA_CON_RSP In this state, the remote end-point exists and an L2CAP Connect Request has been received by the local L2CAP entity. An L2CA Connect Indication has been sent to the upper layer and the part of the local L2CAP entity processing the received L2CAP Connect Request waits for the corresponding response. The response may require a security check to be performed. .It Dv NG_L2CAP_CONFIG In this state, the connection has been established but both sides are still negotiating the channel parameters. The Configuration state may also be entered when the channel parameters are being renegotiated. Prior to entering the .Dv NG_L2CAP_CONFIG state, all outgoing data traffic is suspended since the traffic parameters of the data traffic are to be renegotiated. Incoming data traffic is accepted until the remote channel endpoint has entered the .Dv NG_L2CAP_CONFIG state. In the .Dv NG_L2CAP_CONFIG state, both sides will issue L2CAP Configuration Request messages if only defaults are being used, a null message will be sent. If a large amount of parameters need to be negotiated, multiple messages will be sent to avoid any MTU limitations and negotiate incrementally. Moving from the .Dv NG_L2CAP_CONFIG state to the .Dv NG_L2CAP_OPEN state requires both sides to be ready. An L2CAP entity is ready when it has received a positive response to its final request and it has positively responded to the final request from the remote device. .It Dv NG_L2CAP_OPEN In this state, the connection has been established and configured, and data flow may proceed. .It Dv NG_L2CAP_W4_L2CAP_DISCON_RSP In this state, the connection is shutting down and an L2CAP Disconnect Request message has been sent. This state is now waiting for the corresponding response. .It Dv NG_L2CAP_W4_L2CA_DISCON_RSP In this state, the connection on the remote endpoint is shutting down and an L2CAP Disconnect Request message has been received. An L2CA Disconnect Indication has been sent to the upper layer to notify the owner of the CID that the remote endpoint is being closed. This state is now waiting for the corresponding response from the upper layer before responding to the remote endpoint. .El .Ss Protocol Multiplexing L2CAP supports protocol multiplexing because the Baseband Protocol does not support any .Dq type field identifying the higher layer protocol being multiplexed above it. L2CAP is able to distinguish between upper layer protocols such as the Service Discovery Protocol, RFCOMM and Telephony Control. .Ss Segmentation and Reassembly The data packets defined by the Baseband Protocol are limited in size. Large L2CAP packets must be segmented into multiple smaller Baseband packets prior to their transmission over the air. Similarly, multiple received Baseband packets may be reassembled into a single larger L2CAP packet. .Ss Quality of Service The L2CAP connection establishment process allows the exchange of information regarding the quality of service (QoS) expected between two Bluetooth units. .Ss Groups The Baseband Protocol supports the concept of a piconet, a group of devices synchronously hopping together using the same clock. The L2CAP group abstraction permits implementations to efficiently map protocol groups on to piconets. .Pp The following features are outside the scope of L2CAP responsibilities: .Bl -dash -offset indent .It L2CAP does not transport audio designated for SCO links. .It L2CAP does not enforce a reliable channel or ensure data integrity, that is, L2CAP performs no retransmissions or checksum calculations. .It L2CAP does not support a reliable multicast channel. .It L2CAP does not support the concept of a global group name. .El .Sh HOOKS This node type supports the following hooks: .Bl -tag -width indent .It Dv hci Bluetooth Host Controller Interface downstream hook. .It Dv l2c Upper layer protocol upstream hook. Usually the Bluetooth L2CAP socket layer is connected to the hook. .It Dv ctl Control hook. Usually the Bluetooth raw L2CAP sockets layer is connected to the hook. .El .Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES) Bluetooth specification says that L2CA request must block until response is ready. L2CAP node uses .Va token field from Netgraph message header to match L2CA request and response. The upper layer protocol must populate .Va token . L2CAP node will queue request and start processing. Later, when response is ready or timeout has occurred, L2CAP node will create new Netgraph message, set .Va token and .Dv NFG_RESP flag and send message to the upper layer. Note that L2CA indication messages will not populate .Va token and will not set .Dv NGF_RESP flag. There is no reason for this, because they are just notifications and do not require acknowledgment. .Bl -tag -width indent .It Dv NGM_L2CAP_L2CA_CON Requests the creation of a channel representing a logical connection to a physical address. Input parameters are the target protocol (PSM) and remote device's 48-bit address (BD_ADDR). Output parameters are the local CID (LCID) allocated by the local L2CAP entity, and Result of the request. If Result indicates a pending notification, the Status value may contain more information of what processing is delaying the establishment of the connection. .It Dv NGM_L2CAP_L2CA_CON_IND This message includes the parameters for the address of the remote device that issued the connection request, the local CID representing the channel being requested, the Identifier contained in the request, and the PSM value the request is targeting. .It Dv NGM_L2CAP_L2CA_CON_RSP Issues a response to a connection request event indication. Input parameters are the remote device's 48-bit address, Identifier sent in the request, local CID, the Response code, and the Status attached to the Response code. The output parameter is the Result of the service request. This primitive must be called no more than once after receiving the indication. .It Dv NGM_L2CAP_L2CA_CFG Requests the initial configuration (or reconfiguration) of a channel to a new set of channel parameters. Input parameters are the local CID endpoint, new incoming receivable MTU (InMTU), new outgoing flow spec-ification, and flush and link timeouts. Output parameters are the Result, accepted incoming MTU (InMTU), the remote side's flow requests, and flush and link timeouts. .It Dv NGM_L2CAP_L2CA_CFG_IND This message includes the parameters indicating the local CID of the channel the request has been sent to, the outgoing MTU size (maximum packet that can be sent across the channel) and the flowspec describing the characteristics of the incoming data. All other channel parameters are set to their default values if not provided by the remote device. .It Dv NGM_L2CAP_L2CA_CFG_RSP Issues a response to a configuration request event indication. Input parameters include the local CID of the endpoint being configured, outgoing transmit MTU (which may be equal or less to the OutMTU parameter in the configuration indication event) and the accepted flowspec for incoming traffic. The output parameter is the Result value. .It Dv NGM_L2CAP_L2CA_QOS_IND This message includes the parameter indicating the address of the remote Bluetooth device where the QoS contract has been violated. .It Dv NGM_L2CAP_L2CA_DISCON Requests the disconnection of the channel. Input parameter is the CID representing the local channel endpoint. Output parameter is Result. Result is zero if an L2CAP Disconnect Response is received, otherwise a non-zero value is returned. Once disconnection has been requested, no process will be able to successfully read or write from the CID. .It Dv NGM_L2CAP_L2CA_DISCON_IND This message includes the parameter indicating the local CID the request has been sent to. .It Dv NGM_L2CAP_L2CA_WRITE Response to transfer of data request. Actual data must be received from appropriate upstream hook and must be prepended with header defined as follows. .Bd -literal -offset indent /* L2CA data packet header */ typedef struct { - u_int32_t token; /* token to use in L2CAP_L2CA_WRITE */ - u_int16_t length; /* length of the data */ - u_int16_t lcid; /* local channel ID */ + uint32_t token; /* token to use in L2CAP_L2CA_WRITE */ + uint16_t length; /* length of the data */ + uint16_t lcid; /* local channel ID */ } __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t; .Ed .Pp The output parameters are Result and Length of data written. .It Dv NGM_L2CAP_L2CA_GRP_CREATE Requests the creation of a CID to represent a logical connection to multiple devices. Input parameter is the PSM value that the outgoing connectionless traffic is labelled with, and the filter used for incoming traffic. Output parameter is the CID representing the local endpoint. On creation, the group is empty but incoming traffic destined for the PSM value is readable. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_CLOSE The use of this message closes down a Group. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_ADD_MEMBER Requests the addition of a member to a group. The input parameter includes the CID representing the group and the BD_ADDR of the group member to be added. The output parameter Result confirms the success or failure of the request. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_REM_MEMBER Requests the removal of a member from a group. The input parameters include the CID representing the group and BD_ADDR of the group member to be removed. The output parameter Result confirms the success or failure of the request. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_MEMBERSHIP Requests a report of the members of a group. The input parameter CID represents the group being queried. The output parameter Result confirms the success or failure of the operation. If the Result is successful, BD_ADDR_Lst is a list of the Bluetooth addresses of the N members of the group. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_PING Initiates an L2CA Echo Request message and the reception of the corresponding L2CAP Echo Response message. The input parameters are remote Bluetooth device BD_ADDR, Echo Data and Length of the echo data. The output parameters are Result, Echo Data and Length of the echo data. .It Dv NGM_L2CAP_L2CA_GET_INFO Initiates an L2CA Information Request message and the reception of the corresponding L2CAP Info Response message. The input parameters are remote Bluetooth device BD_ADDR and Information Type. The output parameters are Result, Information Data and Size of the information data. .It Dv NGM_L2CAP_L2CA_ENABLE_CLT Request to disable (enable) the reception of connectionless packets. The input parameter is the PSM value indicating service that should be blocked (unblocked) and Enable flag. .El .Sh NETGRAPH CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_L2CAP_NODE_GET_FLAGS Returns current state for the node. .It Dv NGM_L2CAP_NODE_GET_DEBUG Returns an integer containing the current debug level for the node. .It Dv NGM_L2CAP_NODE_SET_DEBUG This command takes an integer argument and sets current debug level for the node. .It Dv NGM_L2CAP_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL links). .It Dv NGM_L2CAP_NODE_GET_CHAN_LIST Returns list of active L2CAP channels. .It Dv NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO Returns an integer containing the current value of the auto disconnect timeout (in sec). .It Dv NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO This command accepts an integer and sets the value of the auto disconnect timeout (in sec). The special value of 0 (zero) disables auto disconnect timeout. .El .Sh SHUTDOWN This node shuts down upon receipt of an .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr l2control 8 , .Xr l2ping 8 , .Xr ngctl 8 .Sh HISTORY The .Nm l2cap node type was implemented in .Fx 5.0 . .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report if found. Index: stable/9/share/man/man4/ng_l2tp.4 =================================================================== --- stable/9/share/man/man4/ng_l2tp.4 (revision 290886) +++ stable/9/share/man/man4/ng_l2tp.4 (revision 290887) @@ -1,330 +1,330 @@ .\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd August 2, 2004 .Dt NG_L2TP 4 .Os .Sh NAME .Nm ng_l2tp .Nd L2TP protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_l2tp.h .Sh DESCRIPTION The .Nm l2tp node type implements the encapsulation layer of the L2TP protocol as described in RFC 2661. This includes adding the L2TP packet header for outgoing packets and verifying and removing it for incoming packets. The node maintains the L2TP sequence number state and handles control session packet acknowledgment and retransmission. .Sh HOOKS The .Nm l2tp node type supports the following hooks: .Pp .Bl -tag -compact -offset indent -width ".Dv session_hhhh" .It Dv lower L2TP frames. .It Dv ctrl Control packets. .It Dv session_hhhh Session 0xhhhh data packets. .El .Pp L2TP control and data packets are transmitted to, and received from, the L2TP peer via the .Dv lower hook. Typically this hook would be connected to the .Dv "inet/dgram/udp" hook of an .Xr ng_ksocket 4 node for L2TP over UDP. .Pp The .Dv ctrl hook connects to the local L2TP management entity. L2TP control messages (without any L2TP headers) are transmitted and received on this hook. Messages written to this hook are guaranteed to be delivered to the peer reliably, in order, and without duplicates. .Pp Packets written to the .Dv ctrl hook must contain a two byte session ID prepended to the frame (in network order). This session ID is copied to the outgoing L2TP header. Similarly, packets read from the .Dv ctrl hook will have the received session ID prepended. .Pp Once an L2TP session has been created, the corresponding session hook may be used to transmit and receive the session's data frames: for the session with session ID .Dv 0xabcd , the hook is named .Dv session_abcd . .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_L2TP_SET_CONFIG This command updates the configuration of the node. It takes a .Vt "struct ng_l2tp_config" as an argument: .Bd -literal /* Configuration for a node */ struct ng_l2tp_config { u_char enabled; /* enables traffic flow */ u_char match_id; /* tunnel id must match 'tunnel_id' */ - u_int16_t tunnel_id; /* local tunnel id */ - u_int16_t peer_id; /* peer's tunnel id */ - u_int16_t peer_win; /* peer's max recv window size */ - u_int16_t rexmit_max; /* max retransmits before failure */ - u_int16_t rexmit_max_to; /* max delay between retransmits */ + uint16_t tunnel_id; /* local tunnel id */ + uint16_t peer_id; /* peer's tunnel id */ + uint16_t peer_win; /* peer's max recv window size */ + uint16_t rexmit_max; /* max retransmits before failure */ + uint16_t rexmit_max_to; /* max delay between retransmits */ }; .Ed .Pp The .Va enabled field enables packet processing. Each time this field is changed back to zero the sequence number state is reset. In this way, reuse of a node is possible. .Pp The .Va tunnel_id field configures the local tunnel ID for the control connection. The .Va match_id field determines how incoming L2TP packets with a tunnel ID field different from .Va tunnel_id are handled. If .Va match_id is non-zero, they will be dropped; otherwise, they will be dropped only if the tunnel ID is non-zero. Typically .Va tunnel_id is set to the local tunnel ID as soon as it is known and .Va match_id is set to non-zero after receipt of the SCCRP or SCCCN control message. .Pp The peer's tunnel ID should be set in .Va peer_id as soon as it is learned, typically after receipt of a SCCRQ or SCCRP control message. This value is copied into the L2TP header for outgoing packets. .Pp The .Va peer_win field should be set from the .Dq "Receive Window Size" AVP received from the peer. The default value for this field is one; zero is an invalid value. As long as .Va enabled is non-zero, this value may not be decreased. .Pp The .Va rexmit_max and .Va rexmit_max_to fields configure packet retransmission. .Va rexmit_max_to is the maximum retransmission delay between packets, in seconds. The retransmit delay will start at a small value and increase exponentially up to this limit. The .Va rexmit_max sets the maximum number of times a packet will be retransmitted without being acknowledged before a failure condition is declared. Once a failure condition is declared, each additional retransmission will cause the .Nm l2tp node to send a .Dv NGM_L2TP_ACK_FAILURE control message back to the node that sent the last .Dv NGM_L2TP_SET_CONFIG . Appropriate action should then be taken to shutdown the control connection. .It Dv NGM_L2TP_GET_CONFIG Returns the current configuration as a .Vt "struct ng_l2tp_config" . .It Dv NGM_L2TP_SET_SESS_CONFIG This control message configures a single data session. The corresponding hook must already be connected before sending this command. The argument is a .Vt "struct ng_l2tp_sess_config" : .Bd -literal /* Configuration for a session hook */ struct ng_l2tp_sess_config { - u_int16_t session_id; /* local session id */ - u_int16_t peer_id; /* peer's session id */ + uint16_t session_id; /* local session id */ + uint16_t peer_id; /* peer's session id */ u_char control_dseq; /* we control data sequencing? */ u_char enable_dseq; /* enable data sequencing? */ u_char include_length; /* include length field? */ }; .Ed .Pp The .Va session_id and .Va peer_id fields configure the local and remote session IDs, respectively. .Pp The .Va control_dseq and .Va enable_dseq fields determine whether sequence numbers are used with L2TP data packets. If .Va enable_dseq is zero, then no sequence numbers are sent and incoming sequence numbers are ignored. Otherwise, sequence numbers are included on outgoing packets and checked on incoming packets. .Pp If .Va control_dseq is non-zero, then the setting of .Va enable_dseq will never change except by another .Dv NGM_L2TP_SET_SESS_CONFIG control message. If .Va control_dseq is zero, then the peer controls whether sequence numbers are used: if an incoming L2TP data packet contains sequence numbers, .Va enable_dseq is set to one, and conversely if an incoming L2TP data packet does not contain sequence numbers, .Va enable_dseq is set to zero. The current value of .Va enable_dseq is always accessible via the .Dv NGM_L2TP_GET_SESS_CONFIG control message (see below). Typically an LNS would set .Va control_dseq to one while a LAC would set .Va control_dseq to zero (if the Sequencing Required AVP were not sent), thus giving control of data packet sequencing to the LNS. .Pp The .Va include_length field determines whether the L2TP header length field is included in outgoing L2TP data packets. For incoming packets, the L2TP length field is always checked when present. .It Dv NGM_L2TP_GET_SESS_CONFIG This command takes a two byte session ID as an argument and returns the current configuration for the corresponding data session as a .Vt "struct ng_l2tp_sess_config" . The corresponding session hook must be connected. .It Dv NGM_L2TP_GET_STATS This command returns a .Vt "struct ng_l2tp_stats" containing statistics of the L2TP tunnel. .It Dv NGM_L2TP_CLR_STATS This command clears the statistics for the L2TP tunnel. .It Dv NGM_L2TP_GETCLR_STATS Same as .Dv NGM_L2TP_GET_STATS , but also atomically clears the statistics as well. .It Dv NGM_L2TP_GET_SESSION_STATS This command takes a two byte session ID as an argument and returns a .Vt "struct ng_l2tp_session_stats" containing statistics for the corresponding data session. The corresponding session hook must be connected. .It Dv NGM_L2TP_CLR_SESSION_STATS This command takes a two byte session ID as an argument and clears the statistics for that data session. The corresponding session hook must be connected. .It Dv NGM_L2TP_GETCLR_SESSION_STATS Same as .Dv NGM_L2TP_GET_SESSION_STATS , but also atomically clears the statistics as well. .It Dv NGM_L2TP_SET_SEQ This command sets the sequence numbers of a not yet enabled node. It takes a .Vt "struct ng_l2tp_seq_config" as argument, where .Va xack and .Va nr respectively .Va ns and .Va rack must be the same. This option is particularly useful if one receives and processes the first packet entirely in userspace and wants to hand over further processing to the node. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ng_ppp 4 , .Xr ng_pptpgre 4 , .Xr ngctl 8 .Rs .%A W. Townsley .%A A. Valencia .%A A. Rubens .%A G. Pall .%A G. Zorn .%A B. Palter .%T "Layer Two Tunneling Protocol L2TP" .%O RFC 2661 .Re .Sh HISTORY The .Nm l2tp node type was developed at Packet Design, LLC, .Pa http://www.packetdesign.com/ . .Sh AUTHORS .An Archie Cobbs Aq archie@packetdesign.com Index: stable/9/share/man/man4/ng_mppc.4 =================================================================== --- stable/9/share/man/man4/ng_mppc.4 (revision 290886) +++ stable/9/share/man/man4/ng_mppc.4 (revision 290887) @@ -1,194 +1,194 @@ .\" Copyright (c) 1996-2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Whistle: ng_mppc.8,v 1.1 1999/12/08 20:20:39 archie Exp $ .\" $FreeBSD$ .\" .Dd December 8, 1999 .Dt NG_MPPC 4 .Os .Sh NAME .Nm ng_mppc .Nd Microsoft MPPC/MPPE compression and encryption netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_mppc.h .Sh DESCRIPTION The .Nm mppc node type implements the Microsoft Point-to-Point Compression (MPPC) and Microsoft Point-to-Point Encryption (MPPE) sub-protocols of the PPP protocol. These protocols are often used in conjunction with the Point-to-Point Tunneling Protocol (PPTP). .Pp The node has two hooks, .Dv "comp" for compression and .Dv "decomp" for decompression. Typically one or both of these hooks would be connected to the .Xr ng_ppp 4 node type hook of the same name. Each direction of traffic flow is independent of the other. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -compact -width vjc_vjuncomp .It Dv comp Connection to .Xr ng_ppp 4 .Dv "comp" hook. Incoming frames are compressed and/or encrypted, and sent back out the same hook. .It Dv decomp Connection to .Xr ng_ppp 4 .Dv "decomp" hook. Incoming frames are decompressed and/or decrypted, and sent back out the same hook. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_MPPC_CONFIG_COMP This command resets and configures the node for a session in the outgoing traffic direction (i.e., for compression and/or encryption). This command takes a .Dv "struct ng_mppc_config" as an argument: .Bd -literal -offset 0n /* Length of MPPE key */ #define MPPE_KEY_LEN 16 /* MPPC/MPPE PPP negotiation bits */ #define MPPC_BIT 0x00000001 /* mppc compression bits */ #define MPPE_40 0x00000020 /* use 40 bit key */ #define MPPE_56 0x00000080 /* use 56 bit key */ #define MPPE_128 0x00000040 /* use 128 bit key */ #define MPPE_BITS 0x000000e0 /* mppe encryption bits */ #define MPPE_STATELESS 0x01000000 /* use stateless mode */ #define MPPC_VALID_BITS 0x010000e1 /* possibly valid bits */ /* Configuration for a session */ struct ng_mppc_config { u_char enable; /* enable */ - u_int32_t bits; /* config bits */ + uint32_t bits; /* config bits */ u_char startkey[MPPE_KEY_LEN]; /* start key */ }; .Ed The .Dv enabled field enables traffic flow through the node. The .Dv bits field contains the bits as negotiated by the Compression Control Protocol (CCP) in PPP. The .Dv startkey is only necessary if MPPE was negotiated, and must be equal to the session start key as defined for MPPE. This key is based on the MS-CHAP credentials used at link authentication time. .It Dv NGM_MPPC_CONFIG_DECOMP This command resets and configures the node for a session in the incoming traffic direction (i.e., for decompression and/or decryption). This command takes a .Dv "struct ng_mppc_config" as an argument. .It Dv NGM_MPPC_RESETREQ This message contains no arguments, and is bi-directional. If an error is detected during decompression, this message is sent by the node to the originator of the .Dv NGM_MPPC_CONFIG_DECOMP message that initiated the session. The receiver should respond by sending a PPP CCP Reset-Request to the peer. .Pp This message may also be received by this node type when a CCP Reset-Request is received by the local PPP entity. The node will respond by flushing its outgoing compression and encryption state so the remote side can resynchronize. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks have been disconnected. .Sh COMPILATION The kernel options .Dv NETGRAPH_MPPC_COMPRESSION and .Dv NETGRAPH_MPPC_ENCRYPTION are supplied to selectively compile in either or both capabilities. At least one of these must be defined, or else this node type is useless. .Pp The MPPC protocol requires proprietary compression code available from Hi/Fn (formerly STAC). These files must be obtained elsewhere and added to the kernel sources before this node type will compile with the .Dv NETGRAPH_MPPC_COMPRESSION option. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ppp 4 , .Xr ngctl 8 .Rs .%A G. Pall .%T "Microsoft Point-To-Point Compression (MPPC) Protocol" .%O RFC 2118 .Re .Rs .%A G. S. Pall .%A G. Zorn .%T "Microsoft Point-To-Point Encryption (MPPE) Protocol" .%O draft-ietf-pppext-mppe-04.txt .Re .Rs .%A K. Hamzeh .%A G. Pall .%A W. Verthein .%A J. Taarud .%A W. Little .%A G. Zorn .%T "Point-to-Point Tunneling Protocol (PPTP)" .%O RFC 2637 .Re .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org .Sh BUGS In PPP, encryption should be handled by the Encryption Control Protocol (ECP) rather than CCP. However, Microsoft combined both compression and encryption into their ``compression'' algorithm, which is confusing. Index: stable/9/share/man/man4/ng_one2many.4 =================================================================== --- stable/9/share/man/man4/ng_one2many.4 (revision 290886) +++ stable/9/share/man/man4/ng_one2many.4 (revision 290887) @@ -1,277 +1,277 @@ .\" Copyright (c) 2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd March 1, 2011 .Dt NG_ONE2MANY 4 .Os .Sh NAME .Nm ng_one2many .Nd packet multiplexing netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_one2many.h .Sh DESCRIPTION The .Nm one2many provides a simple mechanism for routing packets over several links in a one-to-many (and in the reverse direction, many-to-one) fashion. There is a single hook named .Dv one , and multiple hooks named .Dv many0 , .Dv many1 , etc. Packets received on any of the .Dv many hooks are forwarded out the .Dv one hook. Packets received on the .Dv one hook are forwarded out one or more of the .Dv many hooks; which hook(s) is determined by the node's configured transmit algorithm. Packets are not altered in any way. .Pp Each of the connected many links may be considered to be up or down. Packets are never delivered out a many hook that is down. How a link is determined to be up or down depends on the node's configured link failure detection algorithm. .Pp Before an interface or link can be plumbed into a group, its status must be marked as being .Dq up . This is normally setup during the initial boot stages by .Xr rc.conf 5 . It is also possible to change an interface's status to .Dq up by using the .Xr ifconfig 8 utility. .Sh TRANSMIT ALGORITHMS .Bl -tag -width foo .It Dv NG_ONE2MANY_XMIT_ROUNDROBIN Packets are delivered out the many hooks in sequential order. Each packet goes out on a different .Dv many hook. .It Dv NG_ONE2MANY_XMIT_ALL Packets are delivered out all the .Dv many hooks. Each packet goes out each .Dv many hook. .It Dv NG_ONE2MANY_XMIT_FAILOVER Packets are delivered out the first active .Dv many hook. .El .Pp In the future other algorithms may be added as well. .Sh LINK FAILURE DETECTION The node distinguishes between active and failed links. Data is sent only to active links. The following link failure detection algorithms are available: .Bl -tag -width indent .It Dv NG_ONE2MANY_FAIL_MANUAL The node is explicitly told which of the links are up via the .Dv NGM_ONE2MANY_SET_CONFIG control message (see below). Newly connected links are down until configured otherwise. .It Dv NG_ONE2MANY_FAIL_NOTIFY The node listens to flow control message from .Va many hooks, and considers link failed if .Dv NGM_LINK_IS_DOWN is received. If the .Dv NGM_LINK_IS_UP message is received, node considers link active. .El .Pp In the future other algorithms may be added as well. .Pp When all links are considered failed, node sends the .Dv NGM_LINK_IS_DOWN message towards the .Va one hook. When at least one link comes up, node sends the .Dv NGM_LINK_IS_UP message towards the .Va one hook. .Sh HOOKS This node type supports up to .Dv NG_ONE2MANY_MAX_LINKS hooks named .Dv many0 , .Dv many1 , etc., plus a single hook named .Dv one . .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_ONE2MANY_SET_CONFIG Sets the node configuration using a .Dv "struct ng_one2many_link_config" as the control message argument: .Bd -literal /* Node configuration structure */ struct ng_one2many_config { - u_int32_t xmitAlg; /* how to distribute packets */ - u_int32_t failAlg; /* how to detect link failure */ + uint32_t xmitAlg; /* how to distribute packets */ + uint32_t failAlg; /* how to detect link failure */ u_char enabledLinks[NG_ONE2MANY_MAX_LINKS]; }; .Ed .Pp Currently, the valid settings for the .Dv xmitAlg field are .Dv NG_ONE2MANY_XMIT_ROUNDROBIN (default) or .Dv NG_ONE2MANY_XMIT_ALL . The valid settings for .Dv failAlg are .Dv NG_ONE2MANY_FAIL_MANUAL (default) or .Dv NG_ONE2MANY_FAIL_NOTIFY . .It Dv NGM_ONE2MANY_GET_CONFIG Returns the current node configuration in a .Dv "struct ng_one2many_link_config" . .It Dv NGM_ONE2MANY_GET_STATS This command takes a 32 bit link number as an argument and returns a .Dv "struct ng_one2many_link_stats" containing statistics for the corresponding .Dv many link, which may or may not be currently connected: .Bd -literal /* Statistics structure (one for each link) */ struct ng_one2many_link_stats { - u_int64_t recvOctets; /* total octets rec'd on link */ - u_int64_t recvPackets; /* total pkts rec'd on link */ - u_int64_t xmitOctets; /* total octets xmit'd on link */ - u_int64_t xmitPackets; /* total pkts xmit'd on link */ + uint64_t recvOctets; /* total octets rec'd on link */ + uint64_t recvPackets; /* total pkts rec'd on link */ + uint64_t xmitOctets; /* total octets xmit'd on link */ + uint64_t xmitPackets; /* total pkts xmit'd on link */ }; .Ed .Pp To access statistics for the .Dv one link, use the link number .Dv -1 . .It Dv NGM_ONE2MANY_CLR_STATS This command takes a 32 bit link number as an argument and clears the statistics for that link. .It Dv NGM_ONE2MANY_GETCLR_STATS Same as .Dv NGM_ONE2MANY_GET_STATS , but also atomically clears the statistics for the link as well. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES The following commands will set up Ethernet interfaces .Dv fxp0 to deliver packets alternating over the physical interfaces corresponding to networking interfaces .Dv fxp0 through .Dv fxp3 : .Bd -literal # Plumb nodes together ngctl mkpeer fxp0: one2many upper one ngctl connect fxp0: fxp0:upper lower many0 ngctl connect fxp1: fxp0:upper lower many1 ngctl connect fxp2: fxp0:upper lower many2 ngctl connect fxp3: fxp0:upper lower many3 # Allow fxp1 through fxp3 to xmit/recv fxp0 frames ngctl msg fxp1: setpromisc 1 ngctl msg fxp2: setpromisc 1 ngctl msg fxp3: setpromisc 1 ngctl msg fxp1: setautosrc 0 ngctl msg fxp2: setautosrc 0 ngctl msg fxp3: setautosrc 0 # Configure all four links as up ngctl msg fxp0:upper \\ setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }" # Bring up interface ifconfig fxp0 192.168.1.1 netmask 0xfffffffc .Ed .Pp With a similar setup on a peer machine (using the address 192.168.1.2), a point-to-point Ethernet connection with four times normal bandwidth is achieved. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_bridge 4 , .Xr ng_ether 4 , .Xr ng_hub 4 , .Xr ifconfig 8 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.2 . .Sh AUTHORS .An -nosplit The .Nm one2many netgraph node (with round-robin algorithm) was written by .An Archie Cobbs .Aq archie@FreeBSD.org . The all algorithm was added by .An Rogier R. Mulhuijzen .Aq drwilco@drwilco.net . .Sh BUGS More transmit and link failure algorithms should be supported. A good candidate is Cisco's Etherchannel. Index: stable/9/share/man/man4/ng_ppp.4 =================================================================== --- stable/9/share/man/man4/ng_ppp.4 (revision 290886) +++ stable/9/share/man/man4/ng_ppp.4 (revision 290887) @@ -1,462 +1,462 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_ppp.8,v 1.3 1999/01/25 23:46:27 archie Exp $ .\" .Dd September 24, 2012 .Dt NG_PPP 4 .Os .Sh NAME .Nm ng_ppp .Nd PPP protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_ppp.h .Sh DESCRIPTION The .Nm ppp node type performs multiplexing for the PPP protocol. It handles only packets that contain data, and forwards protocol negotiation and control packets to a separate controlling entity (e.g., a user-land daemon). This approach combines the fast dispatch of kernel implementations with the configuration flexibility of a user-land implementations. The PPP node type directly supports multi-link PPP, Van Jacobson compression, PPP compression, PPP encryption, and the IP, IPX, and AppleTalk protocols. A single PPP node corresponds to one PPP multi-link bundle. .Pp There is a separate hook for each PPP link in the bundle, plus several hooks corresponding to the directly supported protocols. For compression and encryption, separate attached nodes are required to do the actual work. The node type used will of course depend on the algorithm negotiated. There is also a .Dv bypass hook which is used to handle any protocol not directly supported by the node. This includes all of the control protocols: LCP, IPCP, CCP, etc. Typically this node is connected to a user-land daemon via a .Xr ng_socket 4 type node. .Sh ENABLING FUNCTIONALITY In general, the PPP node enables a specific link or functionality when (a) a .Dv NGM_PPP_SET_CONFIG message has been received which enables it, and (b) the corresponding hook(s) are connected. This allows the controlling entity to use either method (a) or (b) (or both) to control the node's behavior. When a link is connected but disabled, traffic can still flow on the link via the .Dv bypass hook (see below). .Sh LINK HOOKS During normal operation, the individual PPP links are connected to hooks .Dv link0 , .Dv link1 , etc. Up to .Dv NG_PPP_MAX_LINKS links are supported. These device-independent hooks transmit and receive full PPP frames, which include the PPP protocol, address, control, and information fields, but no checksum or other link-specific fields. .Pp On outgoing frames, when protocol compression has been enabled and the protocol number is suitable for compression, the protocol field will be compressed (i.e., sent as one byte instead of two). Either compressed or uncompressed protocol fields are accepted on incoming frames. Similarly, if address and control field compression has been enabled for the link, the address and control fields will be omitted (except for LCP frames as required by the standards). Incoming frames have the address and control fields stripped automatically if present. .Pp Since all negotiation is handled outside the PPP node, the links should not be connected and enabled until the corresponding link has reached the network phase (i.e., LCP negotiation and authentication have completed successfully) and the PPP node has been informed of the link parameters via the .Dv NGM_PPP_LINK_CONFIG message. .Pp When a link is connected but disabled, all received frames are forwarded directly out the .Dv bypass hook, and conversely, frames may be transmitted via the .Dv bypass hook as well. This mode is appropriate for the link authentication phase. As soon as the link is enabled, the PPP node will begin processing frames received on the link. .Sh COMPRESSION AND ENCRYPTION Compression is supported via two hooks, .Dv compress and .Dv decompress . Compression and decompression can be enabled by toggling the .Vt enableCompression and .Vt enableDecompression fields of the node configuration structure. (See below.) If .Vt enableCompression is set to .Dv NG_PPP_COMPRESS_SIMPLE , then all outgoing frames are sent to the .Dv compress hook and all packets received on this hook are expected to be compressed, so the COMPD tag is put on them unconditionally. If .Vt enableCompression is set to .Dv NG_PPP_COMPRESS_FULL , then packets received on the .Dv compress hook are resent as is. The compressor node should put the tag, if the packet was compressed. If .Vt enableDecompression is set to .Dv NG_PPP_DECOMPRESS_SIMPLE , then the node will sent to the .Dv decompress hook only those frames, that are marked with the COMPD tag. If .Vt enableDecompression is set to .Dv NG_PPP_DECOMPRESS_FULL , then the node will sent all incoming packets to the .Dv decompress hook. Compression and decompression can be completely disabled by setting the .Vt enableCompression and .Vt enableDecompression fields to the .Dv NG_PPP_COMPRESS_NONE and .Dv NG_PPP_DECOMPRESS_NONE , respectively. .Pp Encryption works exactly analogously via the .Dv encrypt and .Dv decrypt nodes. Data is always compressed before being encrypted, and decrypted before being decompressed. .Pp Only bundle-level compression and encryption is directly supported; link-level compression and encryption can be handled transparently by downstream nodes. .Sh VAN JACOBSON COMPRESSION When all of the .Dv vjc_ip , .Dv vjc_vjcomp , .Dv vjc_vjuncomp , and .Dv vjc_vjip hooks are connected, and the corresponding configuration flag is enabled, Van Jacobson compression and/or decompression will become active. Normally these hooks connect to the corresponding hooks of a single .Xr ng_vjc 4 node. The PPP node is compatible with the .Dq pass through modes of the .Xr ng_vjc 4 node type. .Sh BYPASS HOOK When a frame is received on a link with an unsupported protocol, or a protocol which is disabled or for which the corresponding hook is unconnected, the PPP node forwards the frame out the .Dv bypass hook, prepended with a four byte prefix. This first two bytes of the prefix indicate the link number on which the frame was received (in network order). For such frames received over the bundle (i.e., encapsulated in the multi-link protocol), the special link number .Dv NG_PPP_BUNDLE_LINKNUM is used. After the two byte link number is the two byte PPP protocol number (also in network order). The PPP protocol number is two bytes long even if the original frame was protocol compressed. .Pp Conversely, any data written to the .Dv bypass hook is assumed to be in this same format. The four byte header is stripped off, the PPP protocol number is prepended (possibly compressed), and the frame is delivered over the desired link. If the link number is .Dv NG_PPP_BUNDLE_LINKNUM the frame will be delivered over the multi-link bundle; or, if multi-link is disabled, over the (single) PPP link. .Pp Typically when the controlling entity receives an unexpected packet on the .Dv bypass hook it responds either by dropping the frame (if it is not ready for the protocol) or with an LCP protocol reject (if it does not recognize or expect the protocol). .Sh MULTILINK OPERATION To enable multi-link PPP, the corresponding configuration flag must be set and at least one link connected. The PPP node will not allow more than one link to be connected if multi-link is not enabled, nor will it allow certain multi-link settings to be changed while multi-link operation is active (e.g., short sequence number header format). .Pp Since packets are sent as fragments across multiple individual links, it is important that when a link goes down the PPP node is notified immediately, either by disconnecting the corresponding hook or disabling the link via the .Dv NGM_PPP_SET_CONFIG control message. .Pp Each link has configuration parameters for latency (specified in milliseconds) and bandwidth (specified in tens of bytes per second). The PPP node can be configured for .Em round-robin or .Em optimized packet delivery. .Pp When configured for round-robin delivery, the latency and bandwidth values are ignored and the PPP node simply sends each frame as a single fragment, alternating frames across all the links in the bundle. This scheme has the advantage that even if one link fails silently, some packets will still get through. It has the disadvantage of sub-optimal overall bundle latency, which is important for interactive response time, and sub-optimal overall bundle bandwidth when links with different bandwidths exist in the same bundle. .Pp When configured for optimal delivery, the PPP node distributes the packet across the links in a way that minimizes the time it takes for the completed packet to be received by the far end. This involves taking into account each link's latency, bandwidth, and current queue length. Therefore these numbers should be configured as accurately as possible. The algorithm does require some computation, so may not be appropriate for very slow machines and/or very fast links. .Pp As a special case, if all links have identical latency and bandwidth, then the above algorithm is disabled (because it is unnecessary) and the PPP node simply fragments frames into equal sized portions across all of the links. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -compact -width vjc_vjuncomp .It Dv link Individual PPP link number .Dv .It Dv compress Connection to compression engine .It Dv decompress Connection to decompression engine .It Dv encrypt Connection to encryption engine .It Dv decrypt Connection to decryption engine .It Dv vjc_ip Connection to .Xr ng_vjc 4 .Dv ip hook .It Dv vjc_vjcomp Connection to .Xr ng_vjc 4 .Dv vjcomp hook .It Dv vjc_vjuncomp Connection to .Xr ng_vjc 4 .Dv vjuncomp hook .It Dv vjc_vjip Connection to .Xr ng_vjc 4 .Dv vjip hook .It Dv inet IP packet data .It Dv ipv6 IPv6 packet data .It Dv atalk AppleTalk packet data .It Dv ipx IPX packet data .It Dv bypass Bypass hook; frames have a four byte header consisting of a link number and a PPP protocol number. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_PPP_SET_CONFIG This command configures all aspects of the node. This includes enabling multi-link PPP, encryption, compression, Van Jacobson compression, and IP, IPv6, AppleTalk, and IPX packet delivery. It includes per-link configuration, including enabling the link, setting latency and bandwidth parameters, and enabling protocol field compression. Note that no link or functionality is active until the corresponding hook is also connected. This command takes a .Dv "struct ng_ppp_node_conf" as an argument: .Bd -literal -offset 0n /* Per-link config structure */ struct ng_ppp_link_conf { u_char enableLink; /* enable this link */ u_char enableProtoComp;/* enable protocol field compression */ u_char enableACFComp; /* enable addr/ctrl field compression */ - u_int16_t mru; /* peer MRU */ - u_int32_t latency; /* link latency (in milliseconds) */ - u_int32_t bandwidth; /* link bandwidth (in bytes/second) */ + uint16_t mru; /* peer MRU */ + uint32_t latency; /* link latency (in milliseconds) */ + uint32_t bandwidth; /* link bandwidth (in bytes/second) */ }; /* Bundle config structure */ struct ng_ppp_bund_conf { - u_int16_t mrru; /* multilink peer MRRU */ + uint16_t mrru; /* multilink peer MRRU */ u_char enableMultilink; /* enable multilink */ u_char recvShortSeq; /* recv multilink short seq # */ u_char xmitShortSeq; /* xmit multilink short seq # */ u_char enableRoundRobin; /* xmit whole packets */ u_char enableIP; /* enable IP data flow */ u_char enableIPv6; /* enable IPv6 data flow */ u_char enableAtalk; /* enable AppleTalk data flow */ u_char enableIPX; /* enable IPX data flow */ u_char enableCompression; /* enable PPP compression */ u_char enableDecompression; /* enable PPP decompression */ u_char enableEncryption; /* enable PPP encryption */ u_char enableDecryption; /* enable PPP decryption */ u_char enableVJCompression; /* enable VJ compression */ u_char enableVJDecompression; /* enable VJ decompression */ }; struct ng_ppp_node_conf { struct ng_ppp_bund_conf bund; struct ng_ppp_link_conf links[NG_PPP_MAX_LINKS]; }; .Ed .Pp .It Dv NGM_PPP_GET_CONFIG Returns the current configuration as a .Dv "struct ng_ppp_node_conf" . .It Dv NGM_PPP_GET_LINK_STATS This command takes a two byte link number as an argument and returns a .Dv "struct ng_ppp_link_stat" containing statistics for the corresponding link. Here .Dv NG_PPP_BUNDLE_LINKNUM is a valid link number corresponding to the multi-link bundle. .It Dv NGM_PPP_GET_LINK_STATS64 Same as NGM_PPP_GET_LINK_STATS but returns .Dv "struct ng_ppp_link_stat64" containing 64bit counters. .It Dv NGM_PPP_CLR_LINK_STATS This command takes a two byte link number as an argument and clears the statistics for that link. .It Dv NGM_PPP_GETCLR_LINK_STATS Same as .Dv NGM_PPP_GET_LINK_STATS , but also atomically clears the statistics as well. .It Dv NGM_PPP_GETCLR_LINK_STATS64 Same as NGM_PPP_GETCLR_LINK_STATS but returns .Dv "struct ng_ppp_link_stat64" containing 64bit counters. .El .Pp This node type also accepts the control messages accepted by the .Xr ng_vjc 4 node type. When received, these messages are simply forwarded to the adjacent .Xr ng_vjc 4 node, if any. This is particularly useful when the individual PPP links are able to generate .Dv NGM_VJC_RECV_ERROR messages (see .Xr ng_vjc 4 for a description). .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_async 4 , .Xr ng_iface 4 , .Xr ng_mppc 4 , .Xr ng_pppoe 4 , .Xr ng_vjc 4 , .Xr ngctl 8 .Rs .%A W. Simpson .%T "The Point-to-Point Protocol (PPP)" .%O RFC 1661 .Re .Rs .%A K. Sklower .%A B. Lloyd .%A G. McGregor .%A D. Carr .%A T. Coradetti .%T "The PPP Multilink Protocol (MP)" .%O RFC 1990 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: stable/9/share/man/man4/ng_pppoe.4 =================================================================== --- stable/9/share/man/man4/ng_pppoe.4 (revision 290886) +++ stable/9/share/man/man4/ng_pppoe.4 (revision 290887) @@ -1,521 +1,521 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ .\" .Dd September 15, 2015 .Dt NG_PPPOE 4 .Os .Sh NAME .Nm ng_pppoe .Nd RFC 2516 PPPoE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In net/ethernet.h .In netgraph.h .In netgraph/ng_pppoe.h .Sh DESCRIPTION The .Nm pppoe node type performs the PPPoE protocol. It is used in conjunction with the .Xr netgraph 4 extensions to the Ethernet framework to divert and inject Ethernet packets to and from a PPP agent (which is not specified). .Pp The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPoE module. The only statistics presently available are the total packet counts for input and output. This node does not yet support the .Dv NGM_TEXT_STATUS control message. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width [unspecified] .It Dv ethernet The hook that should normally be connected to an .Xr ng_ether 4 node. Once connected, .Nm will send a message down this hook to determine Ethernet address of the underlying node. Obtained address will be stored and then used for outgoing datagrams. .It Dv debug Presently no use. .It Dv [unspecified] Any other name is assumed to be a session hook that will be connected to a PPP client agent, or a PPP server agent. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width 3n .It Dv NGM_PPPOE_GET_STATUS This command returns status information in a .Dv "struct ngpppoestat" : .Bd -literal -offset 4n struct ngpppoestat { u_int packets_in; /* packets in from Ethernet */ u_int packets_out; /* packets out towards Ethernet */ }; .Ed .It Dv NGM_TEXT_STATUS This generic message returns a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Tell a nominated newly created hook that its session should enter the state machine as a client. It must be newly created and a service name can be given as an argument. It is legal to specify a zero-length service name, this is common on some DSL setups. It is possible to request a connection to a specific access concentrator by its name using the "AC-Name\\Service-Name" syntax. A session request packet will be broadcasted on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_LISTEN Tell a nominated newly created hook that its session should enter the state machine as a server listener. The argument given is the name of the service to listen for. A zero-length service name will match all requests for service. A matching service request packet will be passed unmodified back to the process responsible for starting the service. It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Tell a nominated newly created hook that its session should enter the state machine as a server. The argument given is the name of the service to offer. A zero-length service is legal. The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook (see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine that eventually answers the request. When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data structure shown below. .El .Pp The three commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_init_data { char hook[NG_HOOKSIZ]; /* hook to monitor on */ - u_int16_t data_len; /* service name length */ + uint16_t data_len; /* service name length */ char data[0]; /* init data goes here */ }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_SUCCESS This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports successful Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_PPPOE_FAIL This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports failed Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message. .It Dv NGM_PPPOE_CLOSE This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports a request to close a session. It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this message. At present this message is not yet used and a .Dv NGM_PPPOE_FAIL message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the above messages, and reports the Access Concentrator Name. .El .Pp The four commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_sts { char hook[NG_HOOKSIZ]; }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_GETMODE This command returns the current compatibility mode of the node as a string. .Tn ASCII form of this message is .Qq Li pppoe_getmode . The following keywords can be returned: .Bl -tag -width 3n .It Qq standard The node operates according to RFC 2516. .It Qq 3Com When .Nm is a PPPoE client, it initiates a session encapsulating packets into incorrect 3Com ethertypes. This compatibility option does not affect server mode. In server mode .Nm supports both modes simultaneously, depending on the ethertype, the client used when connecting. .It Qq D-Link When .Nm is a PPPoE server serving only specific Service-Name(s), it will respond to a PADI requests with empty Service-Name tag, returning all available Service-Name(s) on node. This option is necessary for compatibility with D-Link DI-614+ and DI-624+ SOHO routers as clients, when serving only specific Service-Name. This compatibility option does not affect client mode. .El .It Dv NGM_PPPOE_SETMODE Configure node to the specified mode. The string argument is required. This command understands the same keywords that are returned by the .Dv NGM_PPPOE_GETMODE command. .Tn ASCII form of this message is .Qq Li pppoe_setmode . For example, the following command will configure the node to initiate the next session in the proprietary 3Com mode: .Bd -literal -offset indent ngctl msg fxp0:orphans pppoe_setmode '"3Com"' .Ed .It Dv NGM_PPPOE_SETENADDR Set the node Ethernet address for outgoing datagrams. This message is important when a node has failed to obtain an Ethernet address from its peer on the .Dv ethernet hook, or when user wants to override this address with another one. .Tn ASCII form of this message is .Qq Li setenaddr . .It Dv NGM_PPPOE_SETMAXP Pq Ic setmaxp Set the node PPP-Max-Payload value as described in RFC 4638. This message applies only to a client configuration. .Tn ASCII form of this message is .Qq Li setmaxp . .Pp Data structure returned to client is: .Bd -literal -offset 4n struct ngpppoe_maxp { char hook[NG_HOOKSIZ]; uint16_t data; }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, when all session have been disconnected or when the .Dv ethernet hook is disconnected. .Sh EXAMPLES The following code uses .Dv libnetgraph to set up a .Nm node and connect it to both a socket node and an Ethernet node. It can handle the case of when a .Nm node is already attached to the Ethernet. It then starts a client session. .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd); int main() { int fd1, fd2; setup("xl0", NULL, "fred", &fd1, &fd2); sleep (30); } static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd) { struct ngm_connect ngc; /* connect */ struct ngm_mkpeer mkp; /* mkpeer */ /******** nodeinfo stuff **********/ u_char rbuf[2 * 1024]; struct ng_mesg *const resp = (struct ng_mesg *) rbuf; struct hooklist *const hlist = (struct hooklist *) resp->data; struct nodeinfo *const ninfo = &hlist->nodeinfo; int ch, no_hooks = 0; struct linkinfo *link; struct nodeinfo *peer; /****message to connect PPPoE session*****/ struct { struct ngpppoe_init_data idata; char service[100]; } message; /********tracking our little graph ********/ char path[100]; char source_ID[NG_NODESIZ]; char pppoe_node_name[100]; int k; /* * Create the data and control sockets */ if (NgMkSockNode(NULL, cfd, dfd) < 0) { return (errno); } /* * find the ether node of the name requested by asking it for * it's inquiry information. */ if (strlen(ethername) > 16) return (EINVAL); sprintf(path, "%s:", ethername); if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, NGM_LISTHOOKS, NULL, 0) < 0) { return (errno); } /* * the command was accepted so it exists. Await the reply (It's * almost certainly already waiting). */ if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { return (errno); } /** * The following is available about the node: * ninfo->name (string) * ninfo->type (string) - * ninfo->id (u_int32_t) - * ninfo->hooks (u_int32_t) (count of hooks) + * ninfo->id (uint32_t) + * ninfo->hooks (uint32_t) (count of hooks) * check it is the correct type. and get it's ID for use * with mkpeer later. */ if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, strlen(NG_ETHER_NODE_TYPE)) != 0) { return (EPROTOTYPE); } sprintf(source_ID, "[%08x]:", ninfo->id); /* * look for a hook already attached. */ for (k = 0; k < ninfo->hooks; k++) { /** * The following are available about each hook. * link->ourhook (string) * link->peerhook (string) * peer->name (string) * peer->type (string) - * peer->id (u_int32_t) - * peer->hooks (u_int32_t) + * peer->id (uint32_t) + * peer->hooks (uint32_t) */ link = &hlist->link[k]; peer = &hlist->link[k].nodeinfo; /* Ignore debug hooks */ if (strcmp("debug", link->ourhook) == 0) continue; /* If the orphans hook is attached, use that */ if (strcmp(NG_ETHER_HOOK_ORPHAN, link->ourhook) == 0) { break; } /* the other option is the 'divert' hook */ if (strcmp("NG_ETHER_HOOK_DIVERT", link->ourhook) == 0) { break; } } /* * See if we found a hook there. */ if (k < ninfo->hooks) { if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { /* * If it's a type PPPoE, we skip making one * ourself, but we continue, using * the existing one. */ sprintf(pppoe_node_name, "[%08x]:", peer->id); } else { /* * There is already someone hogging the data, * return an error. Some day we'll try * daisy-chaining.. */ return (EBUSY); } } else { /* * Try make a node of type PPPoE against node "ID" * On hook NG_ETHER_HOOK_ORPHAN. */ snprintf(mkp.type, sizeof(mkp.type), "%s", NG_PPPOE_NODE_TYPE); snprintf(mkp.ourhook, sizeof(mkp.ourhook), "%s", NG_ETHER_HOOK_ORPHAN); snprintf(mkp.peerhook, sizeof(mkp.peerhook), "%s", NG_PPPOE_HOOK_ETHERNET); /* Send message */ if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { return (errno); } /* * Work out a name for the new node. */ sprintf(pppoe_node_name, "%s:%s", source_ID, NG_ETHER_HOOK_ORPHAN); } /* * We now have a PPPoE node attached to the Ethernet * card. The Ethernet is addressed as ethername: The PPPoE * node is addressed as pppoe_node_name: attach to it. * Connect socket node to specified node Use the same hook * name on both ends of the link. */ snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { return (errno); } #ifdef NONSTANDARD /* * In some cases we are speaking to 3Com hardware, so * configure node to non-standard mode. */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { return (errno); } #endif /* * Send it a message telling it to start up. */ bzero(&message, sizeof(message)); snprintf(message.idata.hook, sizeof(message.idata.hook), "%s", sessname); if (service == NULL) { message.idata.data_len = 0; } else { snprintf(message.idata.data, sizeof(message.idata.data), "%s", service); message.idata.data_len = strlen(service); } /* Tell session/hook to start up as a client */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, sizeof(message.idata) + message.idata.data_len) < 0) { return (errno); } return (0); } .Ed .Sh SEE ALSO .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_ppp 4 , .Xr ng_socket 4 , .Xr ngctl 8 , .Xr ppp 8 .Rs .%A L. Mamakos .%A K. Lidl .%A J. Evarts .%A D. Carrel .%A D. Simone .%A R. Wheeler .%T "A Method for transmitting PPP over Ethernet (PPPoE)" .%O RFC 2516 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org Index: stable/9/share/man/man4/ng_pptpgre.4 =================================================================== --- stable/9/share/man/man4/ng_pptpgre.4 (revision 290886) +++ stable/9/share/man/man4/ng_pptpgre.4 (revision 290887) @@ -1,178 +1,178 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_pptpgre.8,v 1.2 1999/12/08 00:20:53 archie Exp $ .\" .Dd March 29, 2008 .Dt NG_PPTPGRE 4 .Os .Sh NAME .Nm ng_pptpgre .Nd PPTP GRE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_pptpgre.h .Sh DESCRIPTION The .Nm pptpgre node type performs Generic Routing Encapsulation (GRE) over IP for the PPTP protocol as specified by RFC 2637. This involves packet encapsulation, sequencing, acknowledgement, and an adaptive timeout sliding window mechanism. This node type does not handle any of the TCP control protocol or call negotiation defined by PPTP. .Pp This node type expects to receive complete IP packets, including the IP header, on the .Dq Li lower hook, but it transmits outgoing frames without any IP header. The typical use for this node type would be to connect the .Dq Li upper hook to one of the link hooks of a .Xr ng_ppp 4 node, and the .Dq Li lower hook to the .Dq Li "inet/raw/gre" hook of a .Xr ng_ksocket 4 node. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -compact -width ".Li session_hhhh" .It Li session_hhhh Session 0xhhhh data packets to the upper protocol layers .It Li upper Same as session_hhhh, but for single session with configurable cid (legacy) .It Li lower Connection to the lower protocol layers .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_PPTPGRE_SET_CONFIG This command resets and configures hook for a session. If corresponding session_hhhh hook is not connected, upper hook will be configured. This command takes a .Vt "struct ng_pptpgre_conf" as an argument: .Bd -literal /* Configuration for a session */ struct ng_pptpgre_conf { u_char enabled; /* enables traffic flow */ u_char enableDelayedAck; /* enables delayed acks */ u_char enableAlwaysAck; /* always send ack with data */ u_char enableWindowing; /* enable windowing algorithm */ - u_int16_t cid; /* my call id */ - u_int16_t peerCid; /* peer call id */ - u_int16_t recvWin; /* peer recv window size */ - u_int16_t peerPpd; /* peer packet processing delay + uint16_t cid; /* my call id */ + uint16_t peerCid; /* peer call id */ + uint16_t recvWin; /* peer recv window size */ + uint16_t peerPpd; /* peer packet processing delay (in 1/10 of a second) */ }; .Ed .Pp The .Va enabled field enables traffic flow through the node. The .Va enableDelayedAck field enables delayed acknowledgement (maximum 250 milliseconds), which is a useful optimization and should generally be turned on. .Va enableAlwaysAck field enables sending acknowledgements with every data packet, which is probably helpful as well. .Pp .Va enableWindowing enables the PPTP packet windowing mechanism specified by the protocol. Disabling this will cause the node to violate the protocol, possibly confusing other PPTP peers, but often results in better performance. The windowing mechanism is a design error in the PPTP protocol; L2TP, the successor to PPTP, removes it. .Pp The remaining fields are as supplied by the PPTP virtual call setup process. .It Dv NGM_PPTPGRE_GET_CONFIG Takes two byte argument as cid and returns the current configuration as a .Vt "struct ng_pptpgre_conf" . .It Dv NGM_PPTPGRE_GET_STATS This command returns a .Vt "struct ng_pptpgre_stats" containing various node statistics. .It Dv NGM_PPTPGRE_CLR_STATS This command resets the node statistics. .It Dv NGM_PPTPGRE_GETCLR_STATS This command atomically gets and resets the node statistics, returning a .Vt "struct ng_pptpgre_stats" . .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ng_ppp 4 , .Xr ngctl 8 .Rs .%A K. Hamzeh .%A G. Pall .%A W. Verthein .%A J. Taarud .%A W. Little .%A G. Zorn .%T "Point-to-Point Tunneling Protocol (PPTP)" .%O RFC 2637 .Re .Rs .%A S. Hanks .%A T. \&Li .%A D. Farinacci .%A P. Traina .%T "Generic Routing Encapsulation over IPv4 networks" .%O RFC 1702 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org .Sh BUGS The node should not expect incoming GRE packets to have an IP header. This behavior is inherited from the (converse) behavior of raw IP sockets. An intermediate node that strips IP headers in one direction should be used instead. Index: stable/9/share/man/man4/ppi.4 =================================================================== --- stable/9/share/man/man4/ppi.4 (revision 290886) +++ stable/9/share/man/man4/ppi.4 (revision 290887) @@ -1,107 +1,107 @@ .\" Copyright (c) 1997 .\" Michael Smith .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer as .\" the first lines of this file unmodified. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 2, 1998 .Dt PPI 4 .Os .Sh NAME .Nm ppi .Nd "user-space interface to ppbus parallel 'geek' port" .Sh SYNOPSIS .Cd "device ppi" .Pp Minor numbering: unit numbers correspond directly to ppbus numbers. .Pp .In dev/ppbus/ppi.h .In dev/ppbus/ppbconf.h .Sh DESCRIPTION The .Nm driver provides a convenient means for user applications to manipulate the state of the parallel port, enabling easy low-speed I/O operations without the security problems inherent with the use of the .Pa /dev/io interface. .Sh PROGRAMMING INTERFACE All I/O on the .Nm interface is performed using .Fn ioctl calls. Each command takes a single -.Ft u_int8_t +.Ft uint8_t argument, transferring one byte of data. The following commands are available: .Bl -tag -width indent .It Dv PPIGDATA , PPISDATA Get and set the contents of the data register. .It Dv PPIGSTATUS , PPISSTATUS Get and set the contents of the status register. .It Dv PPIGCTRL , PPISCTRL Get and set the contents of the control register. The following defines correspond to bits in this register. Setting a bit in the control register drives the corresponding output low. .Bl -tag -width indent -compact .It Dv STROBE .It Dv AUTOFEED .It Dv nINIT .It Dv SELECTIN .It Dv PCD .El .It Dv PPIGEPP , PPISEPP Get and set the contents of the EPP control register. .It Dv PPIGECR , PPISECR Get and set the contents of the ECP control register. .It Dv PPIGFIFO , PPISFIFO Read and write the ECP FIFO (8-bit operations only). .El .Sh EXAMPLES To present the value 0x5a to the data port, drive STROBE low and then high again, the following code fragment can be used: .Bd -literal -compact int fd; - u_int8_t val; + uint8_t val; val = 0x5a; ioctl(fd, PPISDATA, &val); ioctl(fd, PPIGCTRL, &val); val |= STROBE; ioctl(fd, PPISCTRL, &val); val &= ~STROBE; ioctl(fd, PPISCTRL, &val); .Ed .Sh BUGS The inverse sense of signals is confusing. .Pp The .Fn ioctl interface is slow, and there is no way (yet) to chain multiple operations together. .Pp The headers required for user applications are not installed as part of the standard system. Index: stable/9/share/man/man4 =================================================================== --- stable/9/share/man/man4 (revision 290886) +++ stable/9/share/man/man4 (revision 290887) Property changes on: stable/9/share/man/man4 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man4:r231564 Index: stable/9/share/man/man5/fs.5 =================================================================== --- stable/9/share/man/man5/fs.5 (revision 290886) +++ stable/9/share/man/man5/fs.5 (revision 290887) @@ -1,450 +1,450 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)fs.5 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd October 31, 2006 .Dt FS 5 .Os .Sh NAME .Nm fs , .Nm inode .Nd format of file system volume .Sh SYNOPSIS .In sys/param.h .In ufs/ffs/fs.h .Pp .In sys/types.h .In sys/lock.h .In sys/extattr.h .In sys/acl.h .In ufs/ufs/quota.h .In ufs/ufs/dinode.h .In ufs/ufs/extattr.h .Sh DESCRIPTION The files .In fs.h and .In inode.h declare several structures, defined variables and macros which are used to create and manage the underlying format of file system objects on random access devices (disks). .Pp The block size and number of blocks which comprise a file system are parameters of the file system. Sectors beginning at .Dv BBLOCK and continuing for .Dv BBSIZE are used for a disklabel and for some hardware primary and secondary bootstrapping programs. .Pp The actual file system begins at sector .Dv SBLOCK with the .Em super-block that is of size .Dv SBLOCKSIZE . The following structure describes the super-block and is from the file .In ufs/ffs/fs.h : .Bd -literal /* * Super block for an FFS filesystem. */ struct fs { int32_t fs_firstfield; /* historic filesystem linked list, */ int32_t fs_unused_1; /* used for incore super blocks */ int32_t fs_sblkno; /* offset of super-block in filesys */ int32_t fs_cblkno; /* offset of cyl-block in filesys */ int32_t fs_iblkno; /* offset of inode-blocks in filesys */ int32_t fs_dblkno; /* offset of first data after cg */ int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ int32_t fs_old_time; /* last time written */ int32_t fs_old_size; /* number of blocks in fs */ int32_t fs_old_dsize; /* number of data blocks in fs */ int32_t fs_ncg; /* number of cylinder groups */ int32_t fs_bsize; /* size of basic blocks in fs */ int32_t fs_fsize; /* size of frag blocks in fs */ int32_t fs_frag; /* number of frags in a block in fs */ /* these are configuration parameters */ int32_t fs_minfree; /* minimum percentage of free blocks */ int32_t fs_old_rotdelay; /* num of ms for optimal next block */ int32_t fs_old_rps; /* disk revolutions per second */ /* these fields can be computed from the others */ int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ int32_t fs_fshift; /* ``numfrags'' calc number of frags */ /* these are configuration parameters */ int32_t fs_maxcontig; /* max number of contiguous blks */ int32_t fs_maxbpg; /* max number of blks per cyl group */ /* these fields can be computed from the others */ int32_t fs_fragshift; /* block to frag shift */ int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ int32_t fs_sbsize; /* actual size of super block */ int32_t fs_spare1[2]; /* old fs_csmask */ /* old fs_csshift */ int32_t fs_nindir; /* value of NINDIR */ int32_t fs_inopb; /* value of INOPB */ int32_t fs_old_nspf; /* value of NSPF */ /* yet another configuration parameter */ int32_t fs_optim; /* optimization preference, see below */ int32_t fs_old_npsect; /* # sectors/track including spares */ int32_t fs_old_interleave; /* hardware sector interleave */ int32_t fs_old_trackskew; /* sector 0 skew, per track */ int32_t fs_id[2]; /* unique filesystem id */ /* sizes determined by number of cylinder groups and their sizes */ int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */ int32_t fs_cssize; /* size of cyl grp summary area */ int32_t fs_cgsize; /* cylinder group size */ int32_t fs_spare2; /* old fs_ntrak */ int32_t fs_old_nsect; /* sectors per track */ int32_t fs_old_spc; /* sectors per cylinder */ int32_t fs_old_ncyl; /* cylinders in filesystem */ int32_t fs_old_cpg; /* cylinders per group */ int32_t fs_ipg; /* inodes per group */ int32_t fs_fpg; /* blocks per group * fs_frag */ /* this data must be re-computed after crashes */ struct csum fs_old_cstotal; /* cylinder summary information */ /* these fields are cleared at mount time */ int8_t fs_fmod; /* super block modified flag */ int8_t fs_clean; /* filesystem is clean flag */ int8_t fs_ronly; /* mounted read-only flag */ int8_t fs_old_flags; /* old FS_ flags */ u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ u_char fs_volname[MAXVOLLEN]; /* volume name */ - u_int64_t fs_swuid; /* system-wide uid */ + uint64_t fs_swuid; /* system-wide uid */ int32_t fs_pad; /* due to alignment of fs_swuid */ /* these fields retain the current block allocation info */ int32_t fs_cgrotor; /* last cg searched */ void *fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs buffers */ - u_int8_t *fs_contigdirs; /* # of contiguously allocated dirs */ + uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */ struct csum *fs_csp; /* cg summary info buffer for fs_cs */ int32_t *fs_maxcluster; /* max cluster in each cyl group */ u_int *fs_active; /* used by snapshots to track fs */ int32_t fs_old_cpc; /* cyl per cycle in postbl */ int32_t fs_maxbsize; /* maximum blocking factor permitted */ int64_t fs_unrefs; /* number of unreferenced inodes */ int64_t fs_sparecon64[16]; /* old rotation block list head */ int64_t fs_sblockloc; /* byte offset of standard superblock */ struct csum_total fs_cstotal; /* cylinder summary information */ ufs_time_t fs_time; /* last time written */ int64_t fs_size; /* number of blocks in fs */ int64_t fs_dsize; /* number of data blocks in fs */ ufs2_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ int64_t fs_pendingblocks; /* blocks in process of being freed */ int32_t fs_pendinginodes; /* inodes in process of being freed */ int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ int32_t fs_avgfilesize; /* expected average file size */ int32_t fs_avgfpdir; /* expected # of files per directory */ int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ int32_t fs_sparecon32[26]; /* reserved for future constants */ int32_t fs_flags; /* see FS_ flags below */ int32_t fs_contigsumsize; /* size of cluster summary array */ int32_t fs_maxsymlinklen; /* max length of an internal symlink */ int32_t fs_old_inodefmt; /* format of on-disk inodes */ - u_int64_t fs_maxfilesize; /* maximum representable file size */ + uint64_t fs_maxfilesize; /* maximum representable file size */ int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */ int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */ int32_t fs_state; /* validate fs_clean field */ int32_t fs_old_postblformat; /* format of positional layout tables */ int32_t fs_old_nrpos; /* number of rotational positions */ int32_t fs_spare5[2]; /* old fs_postbloff */ /* old fs_rotbloff */ int32_t fs_magic; /* magic number */ }; /* * Filesystem identification */ #define FS_UFS1_MAGIC 0x011954 /* UFS1 fast filesystem magic number */ #define FS_UFS2_MAGIC 0x19540119 /* UFS2 fast filesystem magic number */ #define FS_OKAY 0x7c269d38 /* superblock checksum */ #define FS_42INODEFMT -1 /* 4.2BSD inode format */ #define FS_44INODEFMT 2 /* 4.4BSD inode format */ /* * Preference for optimization. */ #define FS_OPTTIME 0 /* minimize allocation time */ #define FS_OPTSPACE 1 /* minimize disk fragmentation */ .Ed .Pp Each disk drive contains some number of file systems. A file system consists of a number of cylinder groups. Each cylinder group has inodes and data. .Pp A file system is described by its super-block, which in turn describes the cylinder groups. The super-block is critical data and is replicated in each cylinder group to protect against catastrophic loss. This is done at file system creation time and the critical super-block data does not change, so the copies need not be referenced further unless disaster strikes. .Pp Addresses stored in inodes are capable of addressing fragments of `blocks'. File system blocks of at most size .Dv MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, each of which is addressable; these pieces may be .Dv DEV_BSIZE , or some multiple of a .Dv DEV_BSIZE unit. .Pp Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last data block of a small file is allocated as only as many fragments of a large block as are necessary. The file system format retains only a single pointer to such a fragment, which is a piece of a single large block that has been divided. The size of such a fragment is determinable from information in the inode, using the .Fn blksize fs ip lbn macro. .Pp The file system records space availability at the fragment level; to determine block availability, aligned fragments are examined. .Pp The root inode is the root of the file system. Inode 0 cannot be used for normal purposes and historically bad blocks were linked to inode 1, thus the root inode is 2 (inode 1 is no longer used for this purpose, however numerous dump tapes make this assumption, so we are stuck with it). .Pp The .Fa fs_minfree element gives the minimum acceptable percentage of file system blocks that may be free. If the freelist drops below this level only the super-user may continue to allocate blocks. The .Fa fs_minfree element may be set to 0 if no reserve of free blocks is deemed necessary, however severe performance degradations will be observed if the file system is run at greater than 90% full; thus the default value of .Fa fs_minfree is 10%. .Pp Empirically the best trade-off between block fragmentation and overall disk utilization at a loading of 90% comes with a fragmentation of 8, thus the default fragment size is an eighth of the block size. .Pp The element .Fa fs_optim specifies whether the file system should try to minimize the time spent allocating blocks, or if it should attempt to minimize the space fragmentation on the disk. If the value of fs_minfree (see above) is less than 10%, then the file system defaults to optimizing for space to avoid running out of full sized blocks. If the value of minfree is greater than or equal to 10%, fragmentation is unlikely to be problematical, and the file system defaults to optimizing for time. .Pp .Em Cylinder group related limits : Each cylinder keeps track of the availability of blocks at different rotational positions, so that sequential blocks can be laid out with minimum rotational latency. With the default of 8 distinguished rotational positions, the resolution of the summary information is 2ms for a typical 3600 rpm drive. .Pp The element .Fa fs_old_rotdelay gives the minimum number of milliseconds to initiate another disk transfer on the same cylinder. It is used in determining the rotationally optimal layout for disk blocks within a file; the default value for .Fa fs_old_rotdelay is 2ms. .Pp Each file system has a statically allocated number of inodes. An inode is allocated for each .Dv NBPI bytes of disk space. The inode allocation strategy is extremely conservative. .Pp .Dv MINBSIZE is the smallest allowable block size. With a .Dv MINBSIZE of 4096 it is possible to create files of size 2^32 with only two levels of indirection. .Dv MINBSIZE must be big enough to hold a cylinder group block, thus changes to .Pq Fa struct cg must keep its size within .Dv MINBSIZE . Note that super-blocks are never more than size .Dv SBLOCKSIZE . .Pp The path name on which the file system is mounted is maintained in .Fa fs_fsmnt . .Dv MAXMNTLEN defines the amount of space allocated in the super-block for this name. The limit on the amount of summary information per file system is defined by .Dv MAXCSBUFS . For a 4096 byte block size, it is currently parameterized for a maximum of two million cylinders. .Pp Per cylinder group information is summarized in blocks allocated from the first cylinder group's data blocks. These blocks are read in from .Fa fs_csaddr (size .Fa fs_cssize ) in addition to the super-block. .Pp .Sy N.B. : .Fn sizeof "struct csum" must be a power of two in order for the .Fn fs_cs macro to work. .Pp The .Em "Super-block for a file system" : The size of the rotational layout tables is limited by the fact that the super-block is of size .Dv SBLOCKSIZE . The size of these tables is .Em inversely proportional to the block size of the file system. The size of the tables is increased when sector sizes are not powers of two, as this increases the number of cylinders included before the rotational pattern repeats .Pq Fa fs_cpc . The size of the rotational layout tables is derived from the number of bytes remaining in .Pq Fa struct fs . .Pp The number of blocks of data per cylinder group is limited because cylinder groups are at most one block. The inode and free block tables must fit into a single block after deducting space for the cylinder group structure .Pq Fa struct cg . .Pp The .Em Inode : The inode is the focus of all file activity in the .Ux file system. There is a unique inode allocated for each active file, each current directory, each mounted-on file, text file, and the root. An inode is `named' by its device/i-number pair. For further information, see the include file .In ufs/ufs/inode.h . .Pp The format of an external attribute is defined by the extattr structure: .Bd -literal struct extattr { int32_t ea_length; /* length of this attribute */ int8_t ea_namespace; /* name space of this attribute */ int8_t ea_contentpadlen; /* padding at end of attribute */ int8_t ea_namelength; /* length of attribute name */ char ea_name[1]; /* null-terminated attribute name */ /* extended attribute content follows */ }; .Ed .Pp Several macros are defined to manipulate these structures. Each macro takes a pointer to an extattr structure. .Bl -tag -width ".Dv EXTATTR_SET_LENGTHS(eap, size)" .It Dv EXTATTR_NEXT(eap) Returns a pointer to the next extended attribute following .Fa eap . .It Dv EXTATTR_CONTENT(eap) Returns a pointer to the extended attribute content referenced by .Fa eap . .It Dv EXTATTR_CONTENT_SIZE(eap) Returns the size of the extended attribute content referenced by .Fa eap . .It Dv EXTATTR_SET_LENGTHS(eap, size) Called with the size of the attribute content after initializing the attribute name to calculate and set the .Fa ea_length , .Fa ea_namelength , and .Fa ea_contentpadlen fields of the extended attribute structure. .El .Pp The following code identifies an ACL: .Bd -literal if (eap->ea_namespace == EXTATTR_NAMESPACE_SYSTEM && !strcmp(eap->ea_name, POSIX1E_ACL_ACCESS_EXTATTR_NAME) { aclp = EXTATTR_CONTENT(eap); acllen = EXTATTR_CONTENT_SIZE(eap); ... } .Ed .Pp The following code creates an extended attribute containing a copy of a structure .Fa mygif : .Bd -literal eap->ea_namespace = EXTATTR_NAMESPACE_USER; strcpy(eap->ea_name, "filepic.gif"); EXTATTR_SET_LENGTHS(eap, sizeof(struct mygif)); memcpy(EXTATTR_CONTENT(eap), &mygif, sizeof(struct mygif)); .Ed .Sh HISTORY A super-block structure named filsys appeared in .At v6 . The file system described in this manual appeared in .Bx 4.2 . Index: stable/9/share/man/man5 =================================================================== --- stable/9/share/man/man5 (revision 290886) +++ stable/9/share/man/man5 (revision 290887) Property changes on: stable/9/share/man/man5 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man5:r231564 Index: stable/9/share/man/man9/MD5.9 =================================================================== --- stable/9/share/man/man9/MD5.9 (revision 290886) +++ stable/9/share/man/man9/MD5.9 (revision 290887) @@ -1,78 +1,78 @@ .\" $OpenBSD: md5.9,v 1.1 1996/04/17 21:40:14 mickey Exp $ .\" .\" Copyright (c) 1996 Michael Shalayeff .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Michael Shalayeff .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 17, 1996 .Dt MD5 9 .Os .Sh NAME .Nm MD5 , .Nm MD5Init , .Nm MD5Transform .Nd message digest routines .Sh SYNOPSIS .In sys/types.h .In sys/md5.h .Ft void .Fn MD5Init "MD5_CTX *buf" .Ft void -.Fn MD5Transform "u_int32_t buf[4]" "const unsigned char block[64]" +.Fn MD5Transform "uint32_t buf[4]" "const unsigned char block[64]" .Sh DESCRIPTION The .Nm module implements the RSA Data Security, Inc.\& MD5 Message-Digest Algorithm (MD5). It produces 128-bit MD5 Digest of data. .Bl -hang -width MD5Transformxxx .It Pa MD5Init must be called just before .Fn MD5Transform will be used to produce a digest. The .Fa buf argument is the storage for the digest being produced on subsequent calls to the .Fn MD5Transform routine. .It Pa MD5Transform is the core of the MD5 algorithm, this alters an existing MD5 hash kept in .Fa buf to reflect the addition of 64 characters of new data passed in .Fa block argument. .El .Sh COPYRIGHTS The code for MD5 transform was taken from Colin Plumb's implementation, which has been placed in the public domain. The MD5 cryptographic checksum was devised by Ronald Rivest, and is documented in RFC 1321, "The MD5 Message Digest Algorithm". Index: stable/9/share/man/man9/bios.9 =================================================================== --- stable/9/share/man/man9/bios.9 (revision 290886) +++ stable/9/share/man/man9/bios.9 (revision 290887) @@ -1,182 +1,182 @@ .\" $FreeBSD$ .\" .\" Copyright (c) 1997 Michael Smith .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd August 9, 2005 .Dt BIOS 9 .Os .Sh NAME .Nm bios_sigsearch , .Nm bios32_SDlookup , .Nm bios32 , .Nm bios_oem_strings .Nd interact with PC BIOS .Sh SYNOPSIS .In sys/param.h .In vm/vm.h .In vm/pmap.h .In machine/param.h .In machine/pmap.h .In machine/pc/bios.h -.Ft u_int32_t -.Fn bios_sigsearch "u_int32_t start" "u_char *sig" "int siglen" "int paralen" "int sigofs" +.Ft uint32_t +.Fn bios_sigsearch "uint32_t start" "u_char *sig" "int siglen" "int paralen" "int sigofs" .Ft int .Fn bios32_SDlookup "struct bios32_SDentry *ent" .Ft int .Fn bios32 "struct bios_regs *br" "u_int offset" "u_short segment" .Fn BIOS_PADDRTOVADDR "addr" .Fn BIOS_VADDRTOPADDR "addr" .Vt extern struct bios32_SDentry PCIbios ; .Vt extern struct SMBIOS_table SMBIOStable ; .Vt extern struct DMI_table DMItable ; .Ft int .Fn bios_oem_strings "struct bios_oem *oem" "u_char *buffer" "size_t maxlen" .Bd -literal struct bios_oem_signature { char * anchor; /* search anchor string in BIOS memory */ size_t offset; /* offset from anchor (may be negative) */ size_t totlen; /* total length of BIOS string to copy */ }; struct bios_oem_range { u_int from; /* shouldn't be below 0xe0000 */ u_int to; /* shouldn't be above 0xfffff */ }; struct bios_oem { struct bios_oem_range range; struct bios_oem_signature signature[]; }; .Ed .Sh DESCRIPTION These functions provide a general-purpose interface for dealing with the BIOS functions and data encountered on x86 PC-architecture systems. .Bl -tag -width 20n .It Fn bios_sigsearch Searches the BIOS address space for a service signature, usually an uppercase ASCII sequence surrounded by underscores. The search begins at .Fa start , or at the beginning of the BIOS if .Fa start is zero. .Fa siglen bytes of the BIOS image and .Fa sig are compared at .Fa sigofs bytes offset from the current location. If no match is found, the current location is incremented by .Fa paralen bytes and the search repeated. If the signature is found, its effective physical address is returned. If no signature is found, zero is returned. .It Fn bios_oem_strings Searches a given BIOS memory range for one or more strings, and composes a printable concatenation of those found. The routine expects a structure describing the BIOS address .Fa range (within .Li 0xe0000 - .Li 0xfffff ) , and a { .Dv NULL , Li 0 , 0 } -terminated array of .Vt bios_oem_signature structures which define the .Va anchor string, an .Va offset from the beginning of the match (which may be negative), and .Va totlen number of bytes to be collected from BIOS memory starting at that offset. Unmatched anchors are ignored, whereas matches are copied from BIOS memory starting at their corresponding .Vt offset with unprintable characters being replaced with space, and consecutive spaces being suppressed. This composed string is stored in .Fa buffer up to the given .Fa maxlen bytes (including trailing .Ql \e0 , and any trailing space suppressed). If an error is encountered, i.e.\& trying to read out of said BIOS range, other invalid input, or .Fa buffer overflow, a negative integer is returned, otherwise the length of the composed string is returned. In particular, a return value of 0 means that none of the given anchor strings were found in the specified BIOS memory range. .It Fn BIOS_VADDRTOPADDR Returns the effective physical address which corresponds to the kernel virtual address .Fa addr . .It Fn BIOS_PADDRTOVADDR Returns the kernel virtual address which corresponds to the effective physical address .Fa addr . .It SMBIOStable If not NULL, points to a .Ft struct SMBIOS_table structure containing information read from the System Management BIOS table during system startup. .It DMItable If not NULL, points to a .Ft struct DMI_table structure containing information read from the Desktop Management Interface parameter table during system startup. .El .Sh BIOS32 At system startup, the BIOS is scanned for the BIOS32 Service Directory (part of the PCI specification), and the existence of the directory is recorded. This can then be used to locate other services. .Bl -tag -width 20n .It Fn bios32_SDlookup Attempts to locate the BIOS32 service matching the 4-byte identifier passed in the .Fa ident field of the .Fa ent argument. .It Fn bios32 Calls a bios32 function. This presumes that the function is capable of working within the kernel segment (normally the case). The virtual address of the entrypoint is supplied in .Fa entry and the register arguments to the function are supplied in .Fa args . .It PCIbios If not NULL, points to a .Ft struct bios32_SDentry structure describing the PCI BIOS entrypoint which was found during system startup. .El Index: stable/9/share/man/man9/bus_space.9 =================================================================== --- stable/9/share/man/man9/bus_space.9 (revision 290886) +++ stable/9/share/man/man9/bus_space.9 (revision 290887) @@ -1,1715 +1,1715 @@ .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $ .\" .\" Copyright (c) 2005 M. Warner Losh. All Rights Reserved. .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Christopher G. Demetriou. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 13, 2005 .Dt BUS_SPACE 9 .Os .Sh NAME .Nm bus_space , .Nm bus_space_barrier , .Nm bus_space_copy_region_1 , .Nm bus_space_copy_region_2 , .Nm bus_space_copy_region_4 , .Nm bus_space_copy_region_8 , .Nm bus_space_copy_region_stream_1 , .Nm bus_space_copy_region_stream_2 , .Nm bus_space_copy_region_stream_4 , .Nm bus_space_copy_region_stream_8 , .Nm bus_space_free , .Nm bus_space_map , .Nm bus_space_read_1 , .Nm bus_space_read_2 , .Nm bus_space_read_4 , .Nm bus_space_read_8 , .Nm bus_space_read_multi_1 , .Nm bus_space_read_multi_2 , .Nm bus_space_read_multi_4 , .Nm bus_space_read_multi_8 , .Nm bus_space_read_multi_stream_1 , .Nm bus_space_read_multi_stream_2 , .Nm bus_space_read_multi_stream_4 , .Nm bus_space_read_multi_stream_8 , .Nm bus_space_read_region_1 , .Nm bus_space_read_region_2 , .Nm bus_space_read_region_4 , .Nm bus_space_read_region_8 , .Nm bus_space_read_region_stream_1 , .Nm bus_space_read_region_stream_2 , .Nm bus_space_read_region_stream_4 , .Nm bus_space_read_region_stream_8 , .Nm bus_space_read_stream_1 , .Nm bus_space_read_stream_2 , .Nm bus_space_read_stream_4 , .Nm bus_space_read_stream_8 , .Nm bus_space_set_multi_1 , .Nm bus_space_set_multi_2 , .Nm bus_space_set_multi_4 , .Nm bus_space_set_multi_8 , .Nm bus_space_set_multi_stream_1 , .Nm bus_space_set_multi_stream_2 , .Nm bus_space_set_multi_stream_4 , .Nm bus_space_set_multi_stream_8 , .Nm bus_space_set_region_1 , .Nm bus_space_set_region_2 , .Nm bus_space_set_region_4 , .Nm bus_space_set_region_8 , .Nm bus_space_set_region_stream_1 , .Nm bus_space_set_region_stream_2 , .Nm bus_space_set_region_stream_4 , .Nm bus_space_set_region_stream_8 , .Nm bus_space_subregion , .Nm bus_space_unmap , .Nm bus_space_write_1 , .Nm bus_space_write_2 , .Nm bus_space_write_4 , .Nm bus_space_write_8 , .Nm bus_space_write_multi_1 , .Nm bus_space_write_multi_2 , .Nm bus_space_write_multi_4 , .Nm bus_space_write_multi_8 , .Nm bus_space_write_multi_stream_1 , .Nm bus_space_write_multi_stream_2 , .Nm bus_space_write_multi_stream_4 , .Nm bus_space_write_multi_stream_8 , .Nm bus_space_write_region_1 , .Nm bus_space_write_region_2 , .Nm bus_space_write_region_4 , .Nm bus_space_write_region_8 , .Nm bus_space_write_region_stream_1 , .Nm bus_space_write_region_stream_2 , .Nm bus_space_write_region_stream_4 , .Nm bus_space_write_region_stream_8 , .Nm bus_space_write_stream_1 , .Nm bus_space_write_stream_2 , .Nm bus_space_write_stream_4 , .Nm bus_space_write_stream_8 .Nd "bus space manipulation functions" .Sh SYNOPSIS .In machine/bus.h .Ft int .Fo bus_space_map .Fa "bus_space_tag_t space" "bus_addr_t address" .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep" .Fc .Ft void .Fo bus_space_unmap .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" .Fc .Ft int .Fo bus_space_subregion .Fa "bus_space_tag_t space" "bus_space_handle_t handle" .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" .Fc .Ft int .Fo bus_space_alloc .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" .Fc .Ft void .Fo bus_space_free .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" .Fc -.Ft u_int8_t +.Ft uint8_t .Fo bus_space_read_1 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int16_t +.Ft uint16_t .Fo bus_space_read_2 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int32_t +.Ft uint32_t .Fo bus_space_read_4 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int64_t +.Ft uint64_t .Fo bus_space_read_8 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int8_t +.Ft uint8_t .Fo bus_space_read_stream_1 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int16_t +.Ft uint16_t .Fo bus_space_read_stream_2 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int32_t +.Ft uint32_t .Fo bus_space_read_stream_4 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc -.Ft u_int64_t +.Ft uint64_t .Fo bus_space_read_stream_8 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" .Fc .Ft void .Fo bus_space_write_1 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int8_t value" +.Fa "bus_size_t offset" "uint8_t value" .Fc .Ft void .Fo bus_space_write_2 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int16_t value" +.Fa "bus_size_t offset" "uint16_t value" .Fc .Ft void .Fo bus_space_write_4 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int32_t value" +.Fa "bus_size_t offset" "uint32_t value" .Fc .Ft void .Fo bus_space_write_8 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int64_t value" +.Fa "bus_size_t offset" "uint64_t value" .Fc .Ft void .Fo bus_space_write_stream_1 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int8_t value" +.Fa "bus_size_t offset" "uint8_t value" .Fc .Ft void .Fo bus_space_write_stream_2 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int16_t value" +.Fa "bus_size_t offset" "uint16_t value" .Fc .Ft void .Fo bus_space_write_stream_4 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int32_t value" +.Fa "bus_size_t offset" "uint32_t value" .Fc .Ft void .Fo bus_space_write_stream_8 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" -.Fa "bus_size_t offset" "u_int64_t value" +.Fa "bus_size_t offset" "uint64_t value" .Fc .Ft void .Fo bus_space_barrier .Fa "bus_space_tag_t space" "bus_space_handle_t handle" .Fa "bus_size_t offset" "bus_size_t length" "int flags" .Fc .Ft void .Fo bus_space_read_region_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_region_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_region_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_1 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_2 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_4 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_8 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_stream_1 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_stream_2 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_stream_4 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_copy_region_stream_8 .Fa "bus_space_tag_t space" .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_region_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_read_multi_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_write_multi_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_stream_1 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_stream_2 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_stream_4 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bus_space_set_multi_stream_8 .Fa "bus_space_tag_t space" -.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" .Fa "bus_size_t count" .Fc .Sh DESCRIPTION The .Nm functions exist to allow device drivers machine-independent access to bus memory and register areas. All of the functions and types described in this document can be used by including the .In machine/bus.h header file. .Pp Many common devices are used on multiple architectures, but are accessed differently on each because of architectural constraints. For instance, a device which is mapped in one system's I/O space may be mapped in memory space on a second system. On a third system, architectural limitations might change the way registers need to be accessed (e.g.\& creating a non-linear register space). In some cases, a single driver may need to access the same type of device in multiple ways in a single system or architecture. The goal of the .Nm functions is to allow a single driver source file to manipulate a set of devices on different system architectures, and to allow a single driver object file to manipulate a set of devices on multiple bus types on a single architecture. .Pp Not all busses have to implement all functions described in this document, though that is encouraged if the operations are logically supported by the bus. Unimplemented functions should cause compile-time errors if possible. .Pp All of the interface definitions described in this document are shown as function prototypes and discussed as if they were required to be functions. Implementations are encouraged to implement prototyped (type-checked) versions of these interfaces, but may implement them as macros if appropriate. Machine-dependent types, variables, and functions should be marked clearly in .In machine/bus.h to avoid confusion with the machine-independent types and functions, and, if possible, should be given names which make the machine-dependence clear. .Sh CONCEPTS AND GUIDELINES Bus spaces are described by bus space tags, which can be created only by machine-dependent code. A given machine may have several different types of bus space (e.g.\& memory space and I/O space), and thus may provide multiple different bus space tags. Individual busses or devices on a machine may use more than one bus space tag. For instance, ISA devices are given an ISA memory space tag and an ISA I/O space tag. Architectures may have several different tags which represent the same type of space, for instance because of multiple different host bus interface chipsets. .Pp A range in bus space is described by a bus address and a bus size. The bus address describes the start of the range in bus space. The bus size describes the size of the range in bytes. Busses which are not byte addressable may require use of bus space ranges with appropriately aligned addresses and properly rounded sizes. .Pp Access to regions of bus space is facilitated by use of bus space handles, which are usually created by mapping a specific range of a bus space. Handles may also be created by allocating and mapping a range of bus space, the actual location of which is picked by the implementation within bounds specified by the caller of the allocation function. .Pp All of the bus space access functions require one bus space tag argument, at least one handle argument, and at least one offset argument (a bus size). The bus space tag specifies the space, each handle specifies a region in the space, and each offset specifies the offset into the region of the actual location(s) to be accessed. Offsets are given in bytes, though busses may impose alignment constraints. The offset used to access data relative to a given handle must be such that all of the data being accessed is in the mapped region that the handle describes. Trying to access data outside that region is an error. .Pp Because some architectures' memory systems use buffering to improve memory and device access performance, there is a mechanism which can be used to create .Dq barriers in the bus space read and write stream. There are three types of barriers: read, write, and read/write. All reads started to the region before a read barrier must complete before any reads after the read barrier are started. (The analogous requirement is true for write barriers.) Read/write barriers force all reads and writes started before the barrier to complete before any reads or writes after the barrier are started. Correctly-written drivers will include all appropriate barriers, and assume only the read/write ordering imposed by the barrier operations. .Pp People trying to write portable drivers with the .Nm functions should try to make minimal assumptions about what the system allows. In particular, they should expect that the system requires bus space addresses being accessed to be naturally aligned (i.e., base address of handle added to offset is a multiple of the access size), and that the system does alignment checking on pointers (i.e., pointer to objects being read and written must point to properly-aligned data). .Pp The descriptions of the .Nm functions given below all assume that they are called with proper arguments. If called with invalid arguments or arguments that are out of range (e.g.\& trying to access data outside of the region mapped when a given handle was created), undefined behaviour results. In that case, they may cause the system to halt, either intentionally (via panic) or unintentionally (by causing a fatal trap of by some other means) or may cause improper operation which is not immediately fatal. Functions which return .Ft void or which return data read from bus space (i.e., functions which do not obviously return an error code) do not fail. They could only fail if given invalid arguments, and in that case their behaviour is undefined. Functions which take a count of bytes have undefined results if the specified .Fa count is zero. .Sh TYPES Several types are defined in .In machine/bus.h to facilitate use of the .Nm functions by drivers. .Ss Vt bus_addr_t The .Vt bus_addr_t type is used to describe bus addresses. It must be an unsigned integral type capable of holding the largest bus address usable by the architecture. This type is primarily used when mapping and unmapping bus space. .Ss Vt bus_size_t The .Vt bus_size_t type is used to describe sizes of ranges in bus space. It must be an unsigned integral type capable of holding the size of the largest bus address range usable on the architecture. This type is used by virtually all of the .Nm functions, describing sizes when mapping regions and offsets into regions when performing space access operations. .Ss Vt bus_space_tag_t The .Vt bus_space_tag_t type is used to describe a particular bus space on a machine. Its contents are machine-dependent and should be considered opaque by machine-independent code. This type is used by all .Nm functions to name the space on which they are operating. .Ss Vt bus_space_handle_t The .Vt bus_space_handle_t type is used to describe a mapping of a range of bus space. Its contents are machine-dependent and should be considered opaque by machine-independent code. This type is used when performing bus space access operations. .Sh MAPPING AND UNMAPPING BUS SPACE This section is specific to the .Nx version of these functions and may or may not apply to the .Fx version. .Pp Bus space must be mapped before it can be used, and should be unmapped when it is no longer needed. The .Fn bus_space_map and .Fn bus_space_unmap functions provide these capabilities. .Pp Some drivers need to be able to pass a subregion of already-mapped bus space to another driver or module within a driver. The .Fn bus_space_subregion function allows such subregions to be created. .Ss Fn bus_space_map space address size flags handlep The .Fn bus_space_map function maps the region of bus space named by the .Fa space , address , and .Fa size arguments. If successful, it returns zero and fills in the bus space handle pointed to by .Fa handlep with the handle that can be used to access the mapped region. If unsuccessful, it will return non-zero and leave the bus space handle pointed to by .Fa handlep in an undefined state. .Pp The .Fa flags argument controls how the space is to be mapped. Supported flags include: .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE" .It Dv BUS_SPACE_MAP_CACHEABLE Try to map the space so that accesses can be cached and/or prefetched by the system. If this flag is not specified, the implementation should map the space so that it will not be cached or prefetched. .Pp This flag must have a value of 1 on all implementations for backward compatibility. .It Dv BUS_SPACE_MAP_LINEAR Try to map the space so that its contents can be accessed linearly via normal memory access methods (e.g.\& pointer dereferencing and structure accesses). This is useful when software wants to do direct access to a memory device, e.g.\& a frame buffer. If this flag is specified and linear mapping is not possible, the .Fn bus_space_map call should fail. If this flag is not specified, the system may map the space in whatever way is most convenient. .El .Pp Not all combinations of flags make sense or are supported with all spaces. For instance, .Dv BUS_SPACE_MAP_CACHEABLE may be meaningless when used on many systems' I/O port spaces, and on some systems .Dv BUS_SPACE_MAP_LINEAR without .Dv BUS_SPACE_MAP_CACHEABLE may never work. When the system hardware or firmware provides hints as to how spaces should be mapped (e.g.\& the PCI memory mapping registers' .Dq prefetchable bit), those hints should be followed for maximum compatibility. On some systems, requesting a mapping that cannot be satisfied (e.g.\& requesting a non-cacheable mapping when the system can only provide a cacheable one) will cause the request to fail. .Pp Some implementations may keep track of use of bus space for some or all bus spaces and refuse to allow duplicate allocations. This is encouraged for bus spaces which have no notion of slot-specific space addressing, such as ISA and VME, and for spaces which coexist with those spaces (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and I/O spaces). .Pp Mapped regions may contain areas for which there is no device on the bus. If space in those areas is accessed, the results are bus-dependent. .Ss Fn bus_space_unmap space handle size The .Fn bus_space_unmap function unmaps a region of bus space mapped with .Fn bus_space_map . When unmapping a region, the .Fa size specified should be the same as the size given to .Fn bus_space_map when mapping that region. .Pp After .Fn bus_space_unmap is called on a handle, that handle is no longer valid. (If copies were made of the handle they are no longer valid, either.) .Pp This function will never fail. If it would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, .Fn bus_space_unmap will never return. .Ss Fn bus_space_subregion space handle offset size nhandlep The .Fn bus_space_subregion function is a convenience function which makes a new handle to some subregion of an already-mapped region of bus space. The subregion described by the new handle starts at byte offset .Fa offset into the region described by .Fa handle , with the size give by .Fa size , and must be wholly contained within the original region. .Pp If successful, .Fn bus_space_subregion returns zero and fills in the bus space handle pointed to by .Fa nhandlep . If unsuccessful, it returns non-zero and leaves the bus space handle pointed to by .Fa nhandlep in an undefined state. In either case, the handle described by .Fa handle remains valid and is unmodified. .Pp When done with a handle created by .Fn bus_space_subregion , the handle should be thrown away. Under no circumstances should .Fn bus_space_unmap be used on the handle. Doing so may confuse any resource management being done on the space, and will result in undefined behaviour. When .Fn bus_space_unmap or .Fn bus_space_free is called on a handle, all subregions of that handle become invalid. .Sh ALLOCATING AND FREEING BUS SPACE This section is specific to the .Nx version of these functions and may or may not apply to the .Fx version. .Pp Some devices require or allow bus space to be allocated by the operating system for device use. When the devices no longer need the space, the operating system should free it for use by other devices. The .Fn bus_space_alloc and .Fn bus_space_free functions provide these capabilities. .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \ flags addrp handlep The .Fn bus_space_alloc function allocates and maps a region of bus space with the size given by .Fa size , corresponding to the given constraints. If successful, it returns zero, fills in the bus address pointed to by .Fa addrp with the bus space address of the allocated region, and fills in the bus space handle pointed to by .Fa handlep with the handle that can be used to access that region. If unsuccessful, it returns non-zero and leaves the bus address pointed to by .Fa addrp and the bus space handle pointed to by .Fa handlep in an undefined state. .Pp Constraints on the allocation are given by the .Fa reg_start , reg_end , alignment , and .Fa boundary parameters. The allocated region will start at or after .Fa reg_start and end before or at .Fa reg_end . The .Fa alignment constraint must be a power of two, and the allocated region will start at an address that is an even multiple of that power of two. The .Fa boundary constraint, if non-zero, ensures that the region is allocated so that .Fa "first address in region" / .Fa boundary has the same value as .Fa "last address in region" / .Fa boundary . If the constraints cannot be met, .Fn bus_space_alloc will fail. It is an error to specify a set of constraints that can never be met (for example, .Fa size greater than .Fa boundary ) . .Pp The .Fa flags parameter is the same as the like-named parameter to .Fn bus_space_map , the same flag values should be used, and they have the same meanings. .Pp Handles created by .Fn bus_space_alloc should only be freed with .Fn bus_space_free . Trying to use .Fn bus_space_unmap on them causes undefined behaviour. The .Fn bus_space_subregion function can be used on handles created by .Fn bus_space_alloc . .Ss Fn bus_space_free space handle size The .Fn bus_space_free function unmaps and frees a region of bus space mapped and allocated with .Fn bus_space_alloc . When unmapping a region, the .Fa size specified should be the same as the size given to .Fn bus_space_alloc when allocating the region. .Pp After .Fn bus_space_free is called on a handle, that handle is no longer valid. (If copies were made of the handle, they are no longer valid, either.) .Pp This function will never fail. If it would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, .Fn bus_space_free will never return. .Sh READING AND WRITING SINGLE DATA ITEMS The simplest way to access bus space is to read or write a single data item. The .Fn bus_space_read_N and .Fn bus_space_write_N families of functions provide the ability to read and write 1, 2, 4, and 8 byte data items on busses which support those access sizes. .Ss Fn bus_space_read_1 space handle offset .Ss Fn bus_space_read_2 space handle offset .Ss Fn bus_space_read_4 space handle offset .Ss Fn bus_space_read_8 space handle offset The .Fn bus_space_read_N family of functions reads a 1, 2, 4, or 8 byte data item from the offset specified by .Fa offset into the region specified by .Fa handle of the bus space specified by .Fa space . The location being read must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data item being read. On some systems, not obeying this requirement may cause incorrect data to be read, on others it may cause a system crash. .Pp Read operations done by the .Fn bus_space_read_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_write_1 space handle offset value .Ss Fn bus_space_write_2 space handle offset value .Ss Fn bus_space_write_4 space handle offset value .Ss Fn bus_space_write_8 space handle offset value The .Fn bus_space_write_N family of functions writes a 1, 2, 4, or 8 byte data item to the offset specified by .Fa offset into the region specified by .Fa handle of the bus space specified by .Fa space . The location being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data item being written. On some systems, not obeying this requirement may cause incorrect data to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Sh BARRIERS In order to allow high-performance buffering implementations to avoid bus activity on every operation, read and write ordering should be specified explicitly by drivers when necessary. The .Fn bus_space_barrier function provides that ability. .Ss Fn bus_space_barrier space handle offset length flags The .Fn bus_space_barrier function enforces ordering of bus space read and write operations for the specified subregion (described by the .Fa offset and .Fa length parameters) of the region named by .Fa handle in the space named by .Fa space . .Pp The .Fa flags argument controls what types of operations are to be ordered. Supported flags are: .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE" .It Dv BUS_SPACE_BARRIER_READ Synchronize read operations. .It Dv BUS_SPACE_BARRIER_WRITE Synchronize write operations. .El .Pp Those flags can be combined (or-ed together) to enforce ordering on both read and write operations. .Pp All of the specified type(s) of operation which are done to the region before the barrier operation are guaranteed to complete before any of the specified type(s) of operation done after the barrier. .Pp Example: Consider a hypothetical device with two single-byte ports, one write-only input port (at offset 0) and a read-only output port (at offset 1). Operation of the device is as follows: data bytes are written to the input port, and are placed by the device on a stack, the top of which is read by reading from the output port. The sequence to correctly write two data bytes to the device then read those two data bytes back would be: .Bd -literal /* * t and h are the tag and handle for the mapped device's * space. */ bus_space_write_1(t, h, 0, data0); bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ bus_space_write_1(t, h, 0, data1); bus_space_barrier(t, h, 0, 2, BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */ ndata1 = bus_space_read_1(t, h, 1); bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ ndata0 = bus_space_read_1(t, h, 1); /* data0 == ndata0, data1 == ndata1 */ .Ed .Pp The first barrier makes sure that the first write finishes before the second write is issued, so that two writes to the input port are done in order and are not collapsed into a single write. This ensures that the data bytes are written to the device correctly and in order. .Pp The second barrier makes sure that the writes to the output port finish before any of the reads to the input port are issued, thereby making sure that all of the writes are finished before data is read. This ensures that the first byte read from the device really is the last one that was written. .Pp The third barrier makes sure that the first read finishes before the second read is issued, ensuring that data is read correctly and in order. .Pp The barriers in the example above are specified to cover the absolute minimum number of bus space locations. It is correct (and often easier) to make barrier operations cover the device's whole range of bus space, that is, to specify an offset of zero and the size of the whole region. .Sh REGION OPERATIONS Some devices use buffers which are mapped as regions in bus space. Often, drivers want to copy the contents of those buffers to or from memory, e.g.\& into mbufs which can be passed to higher levels of the system or from mbufs to be output to a network. In order to allow drivers to do this as efficiently as possible, the .Fn bus_space_read_region_N and .Fn bus_space_write_region_N families of functions are provided. .Pp Drivers occasionally need to copy one region of a bus space to another, or to set all locations in a region of bus space to contain a single value. The .Fn bus_space_copy_region_N family of functions and the .Fn bus_space_set_region_N family of functions allow drivers to perform these operations. .Ss Fn bus_space_read_region_1 space handle offset datap count .Ss Fn bus_space_read_region_2 space handle offset datap count .Ss Fn bus_space_read_region_4 space handle offset datap count .Ss Fn bus_space_read_region_8 space handle offset datap count The .Fn bus_space_read_region_N family of functions reads .Fa count 1, 2, 4, or 8 byte data items from bus space starting at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space and writes them into the array specified by .Fa datap . Each successive data item is read from an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which function is used). All locations being read must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being read and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be read, on others it may cause a system crash. .Pp Read operations done by the .Fn bus_space_read_region_N functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. There is no way to insert barriers between reads of individual bus space locations executed by the .Fn bus_space_read_region_N functions. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_write_region_1 space handle offset datap count .Ss Fn bus_space_write_region_2 space handle offset datap count .Ss Fn bus_space_write_region_4 space handle offset datap count .Ss Fn bus_space_write_region_8 space handle offset datap count The .Fn bus_space_write_region_N family of functions reads .Fa count 1, 2, 4, or 8 byte data items from the array specified by .Fa datap and writes them to bus space starting at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space . Each successive data item is written to an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which function is used). All locations being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_region_N functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. There is no way to insert barriers between writes of individual bus space locations executed by the .Fn bus_space_write_region_N functions. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \ dstoffset count .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \ dstoffset count .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \ dstoffset count .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \ dstoffset count The .Fn bus_space_copy_region_N family of functions copies .Fa count 1, 2, 4, or 8 byte data items in bus space from the area starting at byte offset .Fa srcoffset in the region specified by .Fa srchandle of the bus space specified by .Fa space to the area starting at byte offset .Fa dstoffset in the region specified by .Fa dsthandle in the same bus space. Each successive data item read or written has an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which function is used). All locations being read and written must lie within the bus space region specified by their respective handles. .Pp For portability, the starting addresses of the regions specified by the each handle plus its respective offset should be a multiple of the size of data items being copied. On some systems, not obeying this requirement may cause incorrect data to be copied, on others it may cause a system crash. .Pp Read and write operations done by the .Fn bus_space_copy_region_N functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. There is no way to insert barriers between reads or writes of individual bus space locations executed by the .Fn bus_space_copy_region_N functions. .Pp Overlapping copies between different subregions of a single region of bus space are handled correctly by the .Fn bus_space_copy_region_N functions. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_set_region_1 space handle offset value count .Ss Fn bus_space_set_region_2 space handle offset value count .Ss Fn bus_space_set_region_4 space handle offset value count .Ss Fn bus_space_set_region_8 space handle offset value count The .Fn bus_space_set_region_N family of functions writes the given .Fa value to .Fa count 1, 2, 4, or 8 byte data items in bus space starting at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space . Each successive data item has an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which function is used). All locations being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being written. On some systems, not obeying this requirement may cause incorrect data to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_set_region_N functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. There is no way to insert barriers between writes of individual bus space locations executed by the .Fn bus_space_set_region_N functions. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES Some devices implement single locations in bus space which are to be read or written multiple times to communicate data, e.g.\& some ethernet devices' packet buffer FIFOs. In order to allow drivers to manipulate these types of devices as efficiently as possible, the .Fn bus_space_read_multi_N , .Fn bus_space_set_multi_N , and .Fn bus_space_write_multi_N families of functions are provided. .Ss Fn bus_space_read_multi_1 space handle offset datap count .Ss Fn bus_space_read_multi_2 space handle offset datap count .Ss Fn bus_space_read_multi_4 space handle offset datap count .Ss Fn bus_space_read_multi_8 space handle offset datap count The .Fn bus_space_read_multi_N family of functions reads .Fa count 1, 2, 4, or 8 byte data items from bus space at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space and writes them into the array specified by .Fa datap . Each successive data item is read from the same location in bus space. The location being read must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being read and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be read, on others it may cause a system crash. .Pp Read operations done by the .Fn bus_space_read_multi_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. Because the .Fn bus_space_read_multi_N functions read the same bus space location multiple times, they place an implicit read barrier between each successive read of that bus space location. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_write_multi_1 space handle offset datap count .Ss Fn bus_space_write_multi_2 space handle offset datap count .Ss Fn bus_space_write_multi_4 space handle offset datap count .Ss Fn bus_space_write_multi_8 space handle offset datap count The .Fn bus_space_write_multi_N family of functions reads .Fa count 1, 2, 4, or 8 byte data items from the array specified by .Fa datap and writes them into bus space at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space . Each successive data item is written to the same location in bus space. The location being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_multi_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. Because the .Fn bus_space_write_multi_N functions write the same bus space location multiple times, they place an implicit write barrier between each successive write of that bus space location. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Ss Fn bus_space_set_multi_1 space handle offset value count .Ss Fn bus_space_set_multi_2 space handle offset value count .Ss Fn bus_space_set_multi_4 space handle offset value count .Ss Fn bus_space_set_multi_8 space handle offset value count The .Fn bus_space_set_multi_N writes .Fa value into bus space at byte offset .Fa offset in the region specified by .Fa handle of the bus space specified by .Fa space , .Fa count times. The location being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_set_multi_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier function. Because the .Fn bus_space_set_multi_N functions write the same bus space location multiple times, they place an implicit write barrier between each successive write of that bus space location. .Pp These functions will never fail. If they would fail (e.g.\& because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return. .Sh STREAM FUNCTIONS Most of the .Nm functions imply a host byte-order and a bus byte-order and take care of any translation for the caller. In some cases, however, hardware may map a FIFO or some other memory region for which the caller may want to use multi-word, yet untranslated access. Access to these types of memory regions should be with the .Fn bus_space_*_stream_N functions. .Pp .Bl -tag -compact -width Fn .It Fn bus_space_read_stream_1 .It Fn bus_space_read_stream_2 .It Fn bus_space_read_stream_4 .It Fn bus_space_read_stream_8 .It Fn bus_space_read_multi_stream_1 .It Fn bus_space_read_multi_stream_2 .It Fn bus_space_read_multi_stream_4 .It Fn bus_space_read_multi_stream_8 .It Fn bus_space_read_region_stream_1 .It Fn bus_space_read_region_stream_2 .It Fn bus_space_read_region_stream_4 .It Fn bus_space_read_region_stream_8 .It Fn bus_space_write_stream_1 .It Fn bus_space_write_stream_2 .It Fn bus_space_write_stream_4 .It Fn bus_space_write_stream_8 .It Fn bus_space_write_multi_stream_1 .It Fn bus_space_write_multi_stream_2 .It Fn bus_space_write_multi_stream_4 .It Fn bus_space_write_multi_stream_8 .It Fn bus_space_write_region_stream_1 .It Fn bus_space_write_region_stream_2 .It Fn bus_space_write_region_stream_4 .It Fn bus_space_write_region_stream_8 .It Fn bus_space_copy_region_stream_1 .It Fn bus_space_copy_region_stream_2 .It Fn bus_space_copy_region_stream_4 .It Fn bus_space_copy_region_stream_8 .It Fn bus_space_set_multi_stream_1 .It Fn bus_space_set_multi_stream_2 .It Fn bus_space_set_multi_stream_4 .It Fn bus_space_set_multi_stream_8 .It Fn bus_space_set_region_stream_1 .It Fn bus_space_set_region_stream_2 .It Fn bus_space_set_region_stream_4 .It Fn bus_space_set_region_stream_8 .El .Pp These functions are defined just as their non-stream counterparts, except that they provide no byte-order translation. .Sh COMPATIBILITY The current .Nx version of the .Nm interface specification differs slightly from the original specification that came into wide use and .Fx adopted. A few of the function names and arguments have changed for consistency and increased functionality. .Sh SEE ALSO .Xr bus_dma 9 .Sh HISTORY The .Nm functions were introduced in a different form (memory and I/O spaces were accessed via different sets of functions) in .Nx 1.2 . The functions were merged to work on generic .Dq spaces early in the .Nx 1.3 development cycle, and many drivers were converted to use them. This document was written later during the .Nx 1.3 development cycle, and the specification was updated to fix some consistency problems and to add some missing functionality. .Pp The manual page was then adapted to the version of the interface that .Fx imported for the CAM SCSI drivers, plus subsequent evolution. The .Fx .Nm version was imported in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm interfaces were designed and implemented by the .Nx developer community. Primary contributors and implementors were .An Chris Demetriou , .An Jason Thorpe , and .An Charles Hannum , but the rest of the .Nx developers and the user community played a significant role in development. .Pp .An Justin Gibbs ported these interfaces to .Fx . .Pp .An Chris Demetriou wrote this manual page. .Pp .An Warner Losh modified it for the .Fx implementation. .Sh BUGS This manual may not completely and accurately document the interface, and many parts of the interface are unspecified. Index: stable/9/share/man/man9/crypto.9 =================================================================== --- stable/9/share/man/man9/crypto.9 (revision 290886) +++ stable/9/share/man/man9/crypto.9 (revision 290887) @@ -1,665 +1,665 @@ .\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ .\" .\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) .\" .\" Copyright (c) 2000, 2001 Angelos D. Keromytis .\" .\" Permission to use, copy, and modify this software with or without fee .\" is hereby granted, provided that this entire notice is included in .\" all source code copies of any software which is or includes a copy or .\" modification of this software. .\" .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR .\" PURPOSE. .\" .\" $FreeBSD$ .\" .Dd September 19, 2007 .Dt CRYPTO 9 .Os .Sh NAME .Nm crypto .Nd API for cryptographic services in the kernel .Sh SYNOPSIS .In opencrypto/cryptodev.h .Ft int32_t -.Fn crypto_get_driverid u_int8_t +.Fn crypto_get_driverid uint8_t .Ft int -.Fn crypto_register u_int32_t int u_int16_t u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, u_int32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, u_int64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *" +.Fn crypto_register uint32_t int uint16_t uint32_t "int \*[lp]*\*[rp]\*[lp]void *, uint32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, uint64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *" .Ft int -.Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" +.Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" .Ft int -.Fn crypto_unregister u_int32_t int +.Fn crypto_unregister uint32_t int .Ft int -.Fn crypto_unregister_all u_int32_t +.Fn crypto_unregister_all uint32_t .Ft void .Fn crypto_done "struct cryptop *" .Ft void .Fn crypto_kdone "struct cryptkop *" .Ft int -.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int +.Fn crypto_newsession "uint64_t *" "struct cryptoini *" int .Ft int -.Fn crypto_freesession u_int64_t +.Fn crypto_freesession uint64_t .Ft int .Fn crypto_dispatch "struct cryptop *" .Ft int .Fn crypto_kdispatch "struct cryptkop *" .Ft int -.Fn crypto_unblock u_int32_t int +.Fn crypto_unblock uint32_t int .Ft "struct cryptop *" .Fn crypto_getreq int .Ft void .Fn crypto_freereq void .Bd -literal #define CRYPTO_SYMQ 0x1 #define CRYPTO_ASYMQ 0x2 #define EALG_MAX_BLOCK_LEN 16 struct cryptoini { int cri_alg; int cri_klen; int cri_mlen; caddr_t cri_key; - u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; + uint8_t cri_iv[EALG_MAX_BLOCK_LEN]; struct cryptoini *cri_next; }; struct cryptodesc { int crd_skip; int crd_len; int crd_inject; int crd_flags; struct cryptoini CRD_INI; #define crd_iv CRD_INI.cri_iv #define crd_key CRD_INI.cri_key #define crd_alg CRD_INI.cri_alg #define crd_klen CRD_INI.cri_klen struct cryptodesc *crd_next; }; struct cryptop { TAILQ_ENTRY(cryptop) crp_next; - u_int64_t crp_sid; + uint64_t crp_sid; int crp_ilen; int crp_olen; int crp_etype; int crp_flags; caddr_t crp_buf; caddr_t crp_opaque; struct cryptodesc *crp_desc; int (*crp_callback) (struct cryptop *); caddr_t crp_mac; }; struct crparam { caddr_t crp_p; u_int crp_nbits; }; #define CRK_MAXPARAM 8 struct cryptkop { TAILQ_ENTRY(cryptkop) krp_next; u_int krp_op; /* ie. CRK_MOD_EXP or other */ u_int krp_status; /* return status */ u_short krp_iparams; /* # of input parameters */ u_short krp_oparams; /* # of output parameters */ - u_int32_t krp_hid; + uint32_t krp_hid; struct crparam krp_param[CRK_MAXPARAM]; int (*krp_callback)(struct cryptkop *); }; .Ed .Sh DESCRIPTION .Nm is a framework for drivers of cryptographic hardware to register with the kernel so .Dq consumers (other kernel subsystems, and users through the .Pa /dev/crypto device) are able to make use of it. Drivers register with the framework the algorithms they support, and provide entry points (functions) the framework may call to establish, use, and tear down sessions. Sessions are used to cache cryptographic information in a particular driver (or associated hardware), so initialization is not needed with every request. Consumers of cryptographic services pass a set of descriptors that instruct the framework (and the drivers registered with it) of the operations that should be applied on the data (more than one cryptographic operation can be requested). .Pp Keying operations are supported as well. Unlike the symmetric operators described above, these sessionless commands perform mathematical operations using input and output parameters. .Pp Since the consumers may not be associated with a process, drivers may not .Xr sleep 9 . The same holds for the framework. Thus, a callback mechanism is used to notify a consumer that a request has been completed (the callback is specified by the consumer on a per-request basis). The callback is invoked by the framework whether the request was successfully completed or not. An error indication is provided in the latter case. A specific error code, .Er EAGAIN , is used to indicate that a session number has changed and that the request may be re-submitted immediately with the new session number. Errors are only returned to the invoking function if not enough information to call the callback is available (meaning, there was a fatal error in verifying the arguments). For session initialization and teardown there is no callback mechanism used. .Pp The .Fn crypto_newsession routine is called by consumers of cryptographic services (such as the .Xr ipsec 4 stack) that wish to establish a new session with the framework. On success, the first argument will contain the Session Identifier (SID). The second argument contains all the necessary information for the driver to establish the session. The third argument indicates whether a hardware driver (1) should be used or not (0). The various fields in the .Vt cryptoini structure are: .Bl -tag -width ".Va cri_next" .It Va cri_alg Contains an algorithm identifier. Currently supported algorithms are: .Pp .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact .It Dv CRYPTO_AES_CBC .It Dv CRYPTO_ARC4 .It Dv CRYPTO_BLF_CBC .It Dv CRYPTO_CAMELLIA_CBC .It Dv CRYPTO_CAST_CBC .It Dv CRYPTO_DES_CBC .It Dv CRYPTO_3DES_CBC .It Dv CRYPTO_SKIPJACK_CBC .It Dv CRYPTO_MD5 .It Dv CRYPTO_MD5_HMAC .It Dv CRYPTO_MD5_KPDK .It Dv CRYPTO_RIPEMD160_HMAC .It Dv CRYPTO_SHA1 .It Dv CRYPTO_SHA1_HMAC .It Dv CRYPTO_SHA1_KPDK .It Dv CRYPTO_SHA2_256_HMAC .It Dv CRYPTO_SHA2_384_HMAC .It Dv CRYPTO_SHA2_512_HMAC .It Dv CRYPTO_NULL_HMAC .It Dv CRYPTO_NULL_CBC .El .It Va cri_klen Specifies the length of the key in bits, for variable-size key algorithms. .It Va cri_mlen Specifies how many bytes from the calculated hash should be copied back. 0 means entire hash. .It Va cri_key Contains the key to be used with the algorithm. .It Va cri_iv Contains an explicit initialization vector (IV), if it does not prefix the data. This field is ignored during initialization. If no IV is explicitly passed (see below on details), a random IV is used by the device driver processing the request. .It Va cri_next Contains a pointer to another .Vt cryptoini structure. Multiple such structures may be linked to establish multi-algorithm sessions .Xr ( ipsec 4 is an example consumer of such a feature). .El .Pp The .Vt cryptoini structure and its contents will not be modified by the framework (or the drivers used). Subsequent requests for processing that use the SID returned will avoid the cost of re-initializing the hardware (in essence, SID acts as an index in the session cache of the driver). .Pp .Fn crypto_freesession is called with the SID returned by .Fn crypto_newsession to disestablish the session. .Pp .Fn crypto_dispatch is called to process a request. The various fields in the .Vt cryptop structure are: .Bl -tag -width ".Va crp_callback" .It Va crp_sid Contains the SID. .It Va crp_ilen Indicates the total length in bytes of the buffer to be processed. .It Va crp_olen On return, contains the total length of the result. For symmetric crypto operations, this will be the same as the input length. This will be used if the framework needs to allocate a new buffer for the result (or for re-formatting the input). .It Va crp_callback This routine is invoked upon completion of the request, whether successful or not. It is invoked through the .Fn crypto_done routine. If the request was not successful, an error code is set in the .Va crp_etype field. It is the responsibility of the callback routine to set the appropriate .Xr spl 9 level. .It Va crp_etype Contains the error type, if any errors were encountered, or zero if the request was successfully processed. If the .Er EAGAIN error code is returned, the SID has changed (and has been recorded in the .Va crp_sid field). The consumer should record the new SID and use it in all subsequent requests. In this case, the request may be re-submitted immediately. This mechanism is used by the framework to perform session migration (move a session from one driver to another, because of availability, performance, or other considerations). .Pp Note that this field only makes sense when examined by the callback routine specified in .Va crp_callback . Errors are returned to the invoker of .Fn crypto_process only when enough information is not present to call the callback routine (i.e., if the pointer passed is .Dv NULL or if no callback routine was specified). .It Va crp_flags Is a bitmask of flags associated with this request. Currently defined flags are: .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC" .It Dv CRYPTO_F_IMBUF The buffer pointed to by .Va crp_buf is an mbuf chain. .It Dv CRYPTO_F_IOV The buffer pointed to by .Va crp_buf is an .Vt uio structure. .It Dv CRYPTO_F_REL Must return data in the same place. .It Dv CRYPTO_F_BATCH Batch operation if possible. .It Dv CRYPTO_F_CBIMM Do callback immediately instead of doing it from a dedicated kernel thread. .It Dv CRYPTO_F_DONE Operation completed. .It Dv CRYPTO_F_CBIFSYNC Do callback immediately if operation is synchronous. .El .It Va crp_buf Points to the input buffer. On return (when the callback is invoked), it contains the result of the request. The input buffer may be an mbuf chain or a contiguous buffer, depending on .Va crp_flags . .It Va crp_opaque This is passed through the crypto framework untouched and is intended for the invoking application's use. .It Va crp_desc This is a linked list of descriptors. Each descriptor provides information about what type of cryptographic operation should be done on the input buffer. The various fields are: .Bl -tag -width ".Va crd_inject" .It Va crd_iv The field where IV should be provided when the .Dv CRD_F_IV_EXPLICIT flag is given. .It Va crd_key When the .Dv CRD_F_KEY_EXPLICIT flag is given, the .Va crd_key points to a buffer with encryption or authentication key. .It Va crd_alg An algorithm to use. Must be the same as the one given at newsession time. .It Va crd_klen The .Va crd_key key length. .It Va crd_skip The offset in the input buffer where processing should start. .It Va crd_len How many bytes, after .Va crd_skip , should be processed. .It Va crd_inject Offset from the beginning of the buffer to insert any results. For encryption algorithms, this is where the initialization vector (IV) will be inserted when encrypting or where it can be found when decrypting (subject to .Va crd_flags ) . For MAC algorithms, this is where the result of the keyed hash will be inserted. .It Va crd_flags The following flags are defined: .Bl -tag -width 3n .It Dv CRD_F_ENCRYPT For encryption algorithms, this bit is set when encryption is required (when not set, decryption is performed). .It Dv CRD_F_IV_PRESENT For encryption algorithms, this bit is set when the IV already precedes the data, so the .Va crd_inject value will be ignored and no IV will be written in the buffer. Otherwise, the IV used to encrypt the packet will be written at the location pointed to by .Va crd_inject . The IV length is assumed to be equal to the blocksize of the encryption algorithm. Some applications that do special .Dq "IV cooking" , such as the half-IV mode in .Xr ipsec 4 , can use this flag to indicate that the IV should not be written on the packet. This flag is typically used in conjunction with the .Dv CRD_F_IV_EXPLICIT flag. .It Dv CRD_F_IV_EXPLICIT For encryption algorithms, this bit is set when the IV is explicitly provided by the consumer in the .Va crd_iv field. Otherwise, for encryption operations the IV is provided for by the driver used to perform the operation, whereas for decryption operations it is pointed to by the .Va crd_inject field. This flag is typically used when the IV is calculated .Dq "on the fly" by the consumer, and does not precede the data (some .Xr ipsec 4 configurations, and the encrypted swap are two such examples). .It Dv CRD_F_KEY_EXPLICIT For encryption and authentication (MAC) algorithms, this bit is set when the key is explicitly provided by the consumer in the .Va crd_key field for the given operation. Otherwise, the key is taken at newsession time from the .Va cri_key field. .It Dv CRD_F_COMP For compression algorithms, this bit is set when compression is required (when not set, decompression is performed). .El .It Va CRD_INI This .Vt cryptoini structure will not be modified by the framework or the device drivers. Since this information accompanies every cryptographic operation request, drivers may re-initialize state on-demand (typically an expensive operation). Furthermore, the cryptographic framework may re-route requests as a result of full queues or hardware failure, as described above. .It Va crd_next Point to the next descriptor. Linked operations are useful in protocols such as .Xr ipsec 4 , where multiple cryptographic transforms may be applied on the same block of data. .El .El .Pp .Fn crypto_getreq allocates a .Vt cryptop structure with a linked list of as many .Vt cryptodesc structures as were specified in the argument passed to it. .Pp .Fn crypto_freereq deallocates a structure .Vt cryptop and any .Vt cryptodesc structures linked to it. Note that it is the responsibility of the callback routine to do the necessary cleanups associated with the opaque field in the .Vt cryptop structure. .Pp .Fn crypto_kdispatch is called to perform a keying operation. The various fields in the .Vt cryptkop structure are: .Bl -tag -width ".Va krp_callback' .It Va krp_op Operation code, such as .Dv CRK_MOD_EXP . .It Va krp_status Return code. This .Va errno Ns -style variable indicates whether lower level reasons for operation failure. .It Va krp_iparams Number if input parameters to the specified operation. Note that each operation has a (typically hardwired) number of such parameters. .It Va krp_oparams Number if output parameters from the specified operation. Note that each operation has a (typically hardwired) number of such parameters. .It Va krp_kvp An array of kernel memory blocks containing the parameters. .It Va krp_hid Identifier specifying which low-level driver is being used. .It Va krp_callback Callback called on completion of a keying operation. .El .Sh DRIVER-SIDE API The .Fn crypto_get_driverid , .Fn crypto_register , .Fn crypto_kregister , .Fn crypto_unregister , .Fn crypto_unblock , and .Fn crypto_done routines are used by drivers that provide support for cryptographic primitives to register and unregister with the kernel crypto services framework. Drivers must first use the .Fn crypto_get_driverid function to acquire a driver identifier, specifying the .Fa cc_flags as an argument (normally 0, but software-only drivers should specify .Dv CRYPTOCAP_F_SOFTWARE ) . For each algorithm the driver supports, it must then call .Fn crypto_register . The first two arguments are the driver and algorithm identifiers. The next two arguments specify the largest possible operator length (in bits, important for public key operations) and flags for this algorithm. The last four arguments must be provided in the first call to .Fn crypto_register and are ignored in all subsequent calls. They are pointers to three driver-provided functions that the framework may call to establish new cryptographic context with the driver, free already established context, and ask for a request to be processed (encrypt, decrypt, etc.); and an opaque parameter to pass when calling each of these routines. .Fn crypto_unregister is called by drivers that wish to withdraw support for an algorithm. The two arguments are the driver and algorithm identifiers, respectively. Typically, drivers for PCMCIA crypto cards that are being ejected will invoke this routine for all algorithms supported by the card. .Fn crypto_unregister_all will unregister all algorithms registered by a driver and the driver will be disabled (no new sessions will be allocated on that driver, and any existing sessions will be migrated to other drivers). The same will be done if all algorithms associated with a driver are unregistered one by one. .Pp The calling convention for the three driver-supplied routines is: .Pp .Bl -item -compact .It .Ft int -.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ; +.Fn \*[lp]*newsession\*[rp] "void *" "uint32_t *" "struct cryptoini *" ; .It .Ft int -.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ; +.Fn \*[lp]*freesession\*[rp] "void *" "uint64_t" ; .It .Ft int .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ; .It .Ft int .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ; .El .Pp On invocation, the first argument to all routines is an opaque data value supplied when the algorithm is registered with .Fn crypto_register . The second argument to .Fn newsession contains the driver identifier obtained via .Fn crypto_get_driverid . On successful return, it should contain a driver-specific session identifier. The third argument is identical to that of .Fn crypto_newsession . .Pp The .Fn freesession routine takes as arguments the opaque data value and the SID (which is the concatenation of the driver identifier and the driver-specific session identifier). It should clear any context associated with the session (clear hardware registers, memory, etc.). .Pp The .Fn process routine is invoked with a request to perform crypto processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. In case of an unrecoverable error, the error indication must be placed in the .Va crp_etype field of the .Vt cryptop structure. When the request is completed, or an error is detected, the .Fn process routine should invoke .Fn crypto_done . Session migration may be performed, as mentioned previously. .Pp In case of a temporary resource exhaustion, the .Fn process routine may return .Er ERESTART in which case the crypto services will requeue the request, mark the driver as .Dq blocked , and stop submitting requests for processing. The driver is then responsible for notifying the crypto services when it is again able to process requests through the .Fn crypto_unblock routine. This simple flow control mechanism should only be used for short-lived resource exhaustion as it causes operations to be queued in the crypto layer. Doing so is preferable to returning an error in such cases as it can cause network protocols to degrade performance by treating the failure much like a lost packet. .Pp The .Fn kprocess routine is invoked with a request to perform crypto key processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. In case of an unrecoverable error, the error indication must be placed in the .Va krp_status field of the .Vt cryptkop structure. When the request is completed, or an error is detected, the .Fn kprocess routine should invoked .Fn crypto_kdone . .Sh RETURN VALUES .Fn crypto_register , .Fn crypto_kregister , .Fn crypto_unregister , .Fn crypto_newsession , .Fn crypto_freesession , and .Fn crypto_unblock return 0 on success, or an error code on failure. .Fn crypto_get_driverid returns a non-negative value on error, and \-1 on failure. .Fn crypto_getreq returns a pointer to a .Vt cryptop structure and .Dv NULL on failure. .Fn crypto_dispatch returns .Er EINVAL if its argument or the callback function was .Dv NULL , and 0 otherwise. The callback is provided with an error code in case of failure, in the .Va crp_etype field. .Sh FILES .Bl -tag -width ".Pa sys/opencrypto/crypto.c" .It Pa sys/opencrypto/crypto.c most of the framework code .El .Sh SEE ALSO .Xr ipsec 4 , .Xr malloc 9 , .Xr sleep 9 .Sh HISTORY The cryptographic framework first appeared in .Ox 2.7 and was written by .An "Angelos D. Keromytis" Aq angelos@openbsd.org . .Sh BUGS The framework currently assumes that all the algorithms in a .Fn crypto_newsession operation must be available by the same driver. If that is not the case, session initialization will fail. .Pp The framework also needs a mechanism for determining which driver is best for a specific set of algorithms associated with a session. Some type of benchmarking is in order here. .Pp Multiple instances of the same algorithm in the same session are not supported. Note that 3DES is considered one algorithm (and not three instances of DES). Thus, 3DES and DES could be mixed in the same request. Index: stable/9/share/man/man9/device_set_flags.9 =================================================================== --- stable/9/share/man/man9/device_set_flags.9 (revision 290886) +++ stable/9/share/man/man9/device_set_flags.9 (revision 290887) @@ -1,56 +1,56 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1999 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 6, 1999 .Dt DEVICE_GET_FLAGS 9 .Os .Sh NAME .Nm device_set_flags , .Nm device_get_flags .Nd manipulate driver flags .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft void -.Fn device_set_flags "device_t dev" "u_int32_t flags" -.Ft u_int32_t +.Fn device_set_flags "device_t dev" "uint32_t flags" +.Ft uint32_t .Fn device_get_flags "device_t dev" .Sh DESCRIPTION Each device supports a set of driver-dependent flags which are often used to control device behaviour. These flags are read by calling .Fn device_get_flags and written by calling .Fn device_set_flags . .Sh SEE ALSO .Xr device 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: stable/9/share/man/man9/devstat.9 =================================================================== --- stable/9/share/man/man9/devstat.9 (revision 290886) +++ stable/9/share/man/man9/devstat.9 (revision 290887) @@ -1,455 +1,455 @@ .\" .\" Copyright (c) 1998, 1999 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 22, 1998 .Dt DEVSTAT 9 .Os .Sh NAME .Nm devstat , .Nm devstat_add_entry , .Nm devstat_end_transaction , .Nm devstat_end_transaction_bio , .Nm devstat_remove_entry , .Nm devstat_start_transaction .Nd kernel interface for keeping device statistics .Sh SYNOPSIS .In sys/devicestat.h .Ft void .Fo devstat_add_entry .Fa "struct devstat *ds" .Fa "const char *dev_name" .Fa "int unit_number" -.Fa "u_int32_t block_size" +.Fa "uint32_t block_size" .Fa "devstat_support_flags flags" .Fa "devstat_type_flags device_type" .Fa "devstat_priority priority" .Fc .Ft void .Fn devstat_remove_entry "struct devstat *ds" .Ft void .Fn devstat_start_transaction "struct devstat *ds" .Ft void .Fo devstat_end_transaction .Fa "struct devstat *ds" -.Fa "u_int32_t bytes" +.Fa "uint32_t bytes" .Fa "devstat_tag_type tag_type" .Fa "devstat_trans_flags flags" .Fc .Ft void .Fo devstat_end_transaction_bio .Fa "struct devstat *ds" .Fa "struct bio *bp" .Fc .Sh DESCRIPTION The devstat subsystem is an interface for recording device statistics, as its name implies. The idea is to keep reasonably detailed statistics while utilizing a minimum amount of CPU time to record them. Thus, no statistical calculations are actually performed in the kernel portion of the .Nm code. Instead, that is left for user programs to handle. .Pp .Fn devstat_add_entry registers a device with the .Nm subsystem. The caller is expected to have already allocated \fBand zeroed\fR the devstat structure before calling this function. .Fn devstat_add_entry takes several arguments: .Bl -tag -width device_type .It ds The .Va devstat structure, allocated and zeroed by the client. .It dev_name The device name, e.g.\& da, cd, sa. .It unit_number Device unit number. .It block_size Block size of the device, if supported. If the device does not support a block size, or if the blocksize is unknown at the time the device is added to the .Nm list, it should be set to 0. .It flags Flags indicating operations supported or not supported by the device. See below for details. .It device_type The device type. This is broken into three sections: base device type (e.g.\& direct access, CDROM, sequential access), interface type (IDE, SCSI or other) and a pass-through flag to indicate pas-through devices. See below for a complete list of types. .It priority The device priority. The priority is used to determine how devices are sorted within .Nm devstat Ns 's list of devices. Devices are sorted first by priority (highest to lowest), and then by attach order. See below for a complete list of available priorities. .El .Pp .Fn devstat_remove_entry removes a device from the .Nm subsystem. It takes the devstat structure for the device in question as an argument. The .Nm generation number is incremented and the number of devices is decremented. .Pp .Fn devstat_start_transaction registers the start of a transaction with the .Nm subsystem. The busy count is incremented with each transaction start. When a device goes from idle to busy, the system uptime is recorded in the .Va start_time field of the .Va devstat structure. .Pp .Fn devstat_end_transaction registers the end of a transaction with the .Nm subsystem. It takes four arguments: .Bl -tag -width tag_type .It ds The .Va devstat structure for the device in question. .It bytes The number of bytes transferred in this transaction. .It tag_type Transaction tag type. See below for tag types. .It flags Transaction flags indicating whether the transaction was a read, write, or whether no data was transferred. .El .Pp .Fn devstat_end_transaction_bio is a wrapper for .Fn devstat_end_transaction which pulls all the information from a .Va "struct bio" which is ready for biodone(). .Pp The .Va devstat structure is composed of the following fields: .Bl -tag -width dev_creation_time .It dev_links Each .Va devstat structure is placed in a linked list when it is registered. The .Va dev_links field contains a pointer to the next entry in the list of .Va devstat structures. .It device_number The device number is a unique identifier for each device. The device number is incremented for each new device that is registered. The device number is currently only a 32-bit integer, but it could be enlarged if someone has a system with more than four billion device arrival events. .It device_name The device name is a text string given by the registering driver to identify itself. (e.g.\& .Dq da , .Dq cd , .Dq sa , etc.) .It unit_number The unit number identifies the particular instance of the peripheral driver in question. .It bytes_written This is the number of bytes that have been written to the device. This number is currently an unsigned 64 bit integer. This will hopefully eliminate the counter wrap that would come very quickly on some systems if 32 bit integers were used. .It bytes_read This is the number of bytes that have been read from the device. .It bytes_freed This is the number of bytes that have been freed/erased on the device. .It num_reads This is the number of reads from the device. .It num_writes This is the number of writes to the device. .It num_frees This is the number of free/erase operations on the device. .It num_other This is the number of transactions to the device which are neither reads or writes. For instance, .Tn SCSI drivers often send a test unit ready command to .Tn SCSI devices. The test unit ready command does not read or write any data. It merely causes the device to return its status. .It busy_count This is the current number of outstanding transactions for the device. This should never go below zero, and on an idle device it should be zero. If either one of these conditions is not true, it indicates a problem in the way .Fn devstat_start_transaction and .Fn devstat_end_transaction are being called in client code. There should be one and only one transaction start event and one transaction end event for each transaction. .It block_size This is the block size of the device, if the device has a block size. .It tag_types This is an array of counters to record the number of various tag types that are sent to a device. See below for a list of tag types. .It dev_creation_time This is the time, as reported by .Fn getmicrotime that the device was registered. .It busy_time This is the amount of time that the device busy count has been greater than zero. This is only updated when the busy count returns to zero. .It start_time This is the time, as reported by .Fn getmicrouptime that the device busy count went from zero to one. .It last_comp_time This is the time as reported by .Fn getmicrouptime that a transaction last completed. It is used along with .Va start_time to calculate the device busy time. .It flags These flags indicate which statistics measurements are supported by a particular device. These flags are primarily intended to serve as an aid to userland programs that decipher the statistics. .It device_type This is the device type. It consists of three parts: the device type (e.g.\& direct access, CDROM, sequential access, etc.), the interface (IDE, SCSI or other) and whether or not the device in question is a pass-through driver. See below for a complete list of device types. .It priority This is the priority. This is the first parameter used to determine where to insert a device in the .Nm list. The second parameter is attach order. See below for a list of available priorities. .El .Pp Each device is given a device type. Pass-through devices have the same underlying device type and interface as the device they provide an interface for, but they also have the pass-through flag set. The base device types are identical to the .Tn SCSI device type numbers, so with .Tn SCSI peripherals, the device type returned from an inquiry is usually ORed with the .Tn SCSI interface type and the pass-through flag if appropriate. The device type flags are as follows: .Bd -literal -offset indent typedef enum { DEVSTAT_TYPE_DIRECT = 0x000, DEVSTAT_TYPE_SEQUENTIAL = 0x001, DEVSTAT_TYPE_PRINTER = 0x002, DEVSTAT_TYPE_PROCESSOR = 0x003, DEVSTAT_TYPE_WORM = 0x004, DEVSTAT_TYPE_CDROM = 0x005, DEVSTAT_TYPE_SCANNER = 0x006, DEVSTAT_TYPE_OPTICAL = 0x007, DEVSTAT_TYPE_CHANGER = 0x008, DEVSTAT_TYPE_COMM = 0x009, DEVSTAT_TYPE_ASC0 = 0x00a, DEVSTAT_TYPE_ASC1 = 0x00b, DEVSTAT_TYPE_STORARRAY = 0x00c, DEVSTAT_TYPE_ENCLOSURE = 0x00d, DEVSTAT_TYPE_FLOPPY = 0x00e, DEVSTAT_TYPE_MASK = 0x00f, DEVSTAT_TYPE_IF_SCSI = 0x010, DEVSTAT_TYPE_IF_IDE = 0x020, DEVSTAT_TYPE_IF_OTHER = 0x030, DEVSTAT_TYPE_IF_MASK = 0x0f0, DEVSTAT_TYPE_PASS = 0x100 } devstat_type_flags; .Ed .Pp Devices have a priority associated with them, which controls roughly where they are placed in the .Nm list. The priorities are as follows: .Bd -literal -offset indent typedef enum { DEVSTAT_PRIORITY_MIN = 0x000, DEVSTAT_PRIORITY_OTHER = 0x020, DEVSTAT_PRIORITY_PASS = 0x030, DEVSTAT_PRIORITY_FD = 0x040, DEVSTAT_PRIORITY_WFD = 0x050, DEVSTAT_PRIORITY_TAPE = 0x060, DEVSTAT_PRIORITY_CD = 0x090, DEVSTAT_PRIORITY_DISK = 0x110, DEVSTAT_PRIORITY_ARRAY = 0x120, DEVSTAT_PRIORITY_MAX = 0xfff } devstat_priority; .Ed .Pp Each device has associated with it flags to indicate what operations are supported or not supported. The .Va devstat_support_flags values are as follows: .Bl -tag -width DEVSTAT_NO_ORDERED_TAGS .It DEVSTAT_ALL_SUPPORTED Every statistic type is supported by the device. .It DEVSTAT_NO_BLOCKSIZE This device does not have a blocksize. .It DEVSTAT_NO_ORDERED_TAGS This device does not support ordered tags. .It DEVSTAT_BS_UNAVAILABLE This device supports a blocksize, but it is currently unavailable. This flag is most often used with removable media drives. .El .Pp Transactions to a device fall into one of three categories, which are represented in the .Va flags passed into .Fn devstat_end_transaction . The transaction types are as follows: .Bd -literal -offset indent typedef enum { DEVSTAT_NO_DATA = 0x00, DEVSTAT_READ = 0x01, DEVSTAT_WRITE = 0x02, DEVSTAT_FREE = 0x03 } devstat_trans_flags; .Ed .Pp There are four possible values for the .Va tag_type argument to .Fn devstat_end_transaction : .Bl -tag -width DEVSTAT_TAG_ORDERED .It DEVSTAT_TAG_SIMPLE The transaction had a simple tag. .It DEVSTAT_TAG_HEAD The transaction had a head of queue tag. .It DEVSTAT_TAG_ORDERED The transaction had an ordered tag. .It DEVSTAT_TAG_NONE The device does not support tags. .El .Pp The tag type values correspond to the lower four bits of the .Tn SCSI tag definitions. In CAM, for instance, the .Va tag_action from the CCB is ORed with 0xf to determine the tag type to pass in to .Fn devstat_end_transaction . .Pp There is a macro, .Dv DEVSTAT_VERSION that is defined in .In sys/devicestat.h . This is the current version of the .Nm subsystem, and it should be incremented each time a change is made that would require recompilation of userland programs that access .Nm statistics. Userland programs use this version, via the .Va kern.devstat.version .Nm sysctl variable to determine whether they are in sync with the kernel .Nm structures. .Sh SEE ALSO .Xr systat 1 , .Xr devstat 3 , .Xr iostat 8 , .Xr rpc.rstatd 8 , .Xr vmstat 8 .Sh HISTORY The .Nm statistics system appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS There may be a need for .Fn spl protection around some of the .Nm list manipulation code to ensure, for example, that the list of devices is not changed while someone is fetching the .Va kern.devstat.all .Nm sysctl variable. .Pp It is impossible with the current .Nm architecture to accurately measure time per transaction. The only feasible way to accurately measure time per transaction would be to record a timestamp for every transaction. This measurement is probably not worthwhile for most people as it would adversely affect the performance of the system and cost space to store the timestamps for individual transactions. Index: stable/9/share/man/man9/eventtimers.9 =================================================================== --- stable/9/share/man/man9/eventtimers.9 (revision 290886) +++ stable/9/share/man/man9/eventtimers.9 (revision 290887) @@ -1,236 +1,236 @@ .\" .\" Copyright (c) 2011 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 14, 2011 .Dt EVENTTIMERS 9 .Os .Sh NAME .Nm eventtimers .Nd kernel event timers subsystem .Sh SYNOPSIS .In sys/timeet.h .Bd -literal struct eventtimer; typedef int et_start_t(struct eventtimer *et, struct bintime *first, struct bintime *period); typedef int et_stop_t(struct eventtimer *et); typedef void et_event_cb_t(struct eventtimer *et, void *arg); typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); struct eventtimer { SLIST_ENTRY(eventtimer) et_all; char *et_name; int et_flags; #define ET_FLAGS_PERIODIC 1 #define ET_FLAGS_ONESHOT 2 #define ET_FLAGS_PERCPU 4 #define ET_FLAGS_C3STOP 8 #define ET_FLAGS_POW2DIV 16 int et_quality; int et_active; - u_int64_t et_frequency; + uint64_t et_frequency; struct bintime et_min_period; struct bintime et_max_period; et_start_t *et_start; et_stop_t *et_stop; et_event_cb_t *et_event_cb; et_deregister_cb_t *et_deregister_cb; void *et_arg; void *et_priv; struct sysctl_oid *et_sysctl; }; .Ed .Ft int .Fn et_register "struct eventtimer *et" .Ft int .Fn et_deregister "struct eventtimer *et" .Fn ET_LOCK .Fn ET_UNLOCK .Ft struct eventtimer * .Fn et_find "const char *name" "int check" "int want" .Ft int .Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" .Ft int .Fn et_start "struct eventtimer *et" "struct bintime *first" "struct bintime *period" .Ft int .Fn et_stop "struct eventtimer *et" .Ft int .Fn et_ban "struct eventtimer *et" .Ft int .Fn et_free "struct eventtimer *et" .Sh DESCRIPTION Event timers are responsible for generating interrupts at specified time or periodically, to run different time-based events. Subsystem consists of three main parts: .Bl -tag -width "Consumers" .It Drivers Manage hardware to generate requested time events. .It Consumers .Pa sys/kern/kern_clocksource.c uses event timers to supply kernel with .Fn hardclock , .Fn statclock and .Fn profclock time events. .It Glue code .Pa sys/sys/timeet.h , .Pa sys/kern/kern_et.c provide APIs for event timer drivers and consumers. .El .Sh DRIVER API Driver API is built around eventtimer structure. To register its functionality driver allocates that structure and calls .Fn et_register . Driver should fill following fields there: .Bl -tag -width Va .It Va et_name Unique name of the event timer for management purposes. .It Va et_flags Set of flags, describing timer capabilities: .Bl -tag -width "ET_FLAGS_PERIODIC" -compact .It ET_FLAGS_PERIODIC Periodic mode supported. .It ET_FLAGS_ONESHOT One-shot mode supported. .It ET_FLAGS_PERCPU Timer is per-CPU. .It ET_FLAGS_C3STOP Timer may stop in CPU sleep state. .It ET_FLAGS_POW2DIV Timer supports only 2^n divisors. .El .It Va et_quality Abstract value to certify whether this timecounter is better than the others. Higher value means better. .It Va et_frequency Timer oscillator's base frequency, if applicable and known. Used by consumers to predict set of possible frequencies that could be obtained by dividing it. Should be zero if not applicable or unknown. .It Va et_min_period , et_max_period Minimal and maximal reliably programmable time periods. .It Va et_start Driver's timer start function pointer. .It Va et_stop Driver's timer stop function pointer. .It Va et_priv Driver's private data storage. .El .Pp After the event timer functionality is registered, it is controlled via .Va et_start and .Va et_stop methods. .Va et_start method is called to start the specified event timer. The last two arguments are used to specify time when events should be generated. .Va first argument specifies time period before the first event generated. In periodic mode NULL value specifies that first period is equal to the .Va period argument value. .Va period argument specifies the time period between following events for the periodic mode. The NULL value there specifies the one-shot mode. At least one of these two arguments should be not NULL. When event time arrive, driver should call .Va et_event_cb callback function, passing .Va et_arg as the second argument. .Va et_stop method is called to stop the specified event timer. For the per-CPU event timers .Va et_start and .Va et_stop methods control timers associated with the current CPU. .Pp Driver may deregister its functionality by calling .Fn et_deregister . .Sh CONSUMER API .Fn et_find allows consumer to find available event timer, optionally matching specific name and/or capability flags. Consumer may read returned eventtimer structure, but should not modify it. When wanted event timer is found, .Fn et_init should be called for it, submitting .Va event and optionally .Va deregister callbacks functions, and the opaque argument .Va arg . That argument will be passed as argument to the callbacks. Event callback function will be called on scheduled time events. It is called from the hardware interrupt context, so no sleep is permitted there. Deregister callback function may be called to report consumer that the event timer functionality is no longer available. On this call, consumer should stop using event timer before the return. .Pp After the timer is found and initialized, it can be controlled via .Fn et_start and .Fn et_stop . The arguments are the same as described in driver API. Per-CPU event timers can be controlled only from specific CPUs. .Pp .Fn et_ban allows consumer to mark event timer as broken via clearing both one-shot and periodic capability flags, if it was somehow detected. .Fn et_free is the opposite to .Fn et_init . It releases the event timer for other consumers use. .Pp .Fn ET_LOCK and .Fn ET_UNLOCK macros should be used to manage .Xr mutex 9 lock around .Fn et_find , .Fn et_init and .Fn et_free calls to serialize access to the list of the registered event timers and the pointers returned by .Fn et_find . .Fn et_start and .Fn et_stop calls should be serialized in consumer's internal way to avoid concurrent timer hardware access. .Sh SEE ALSO .Xr eventtimers 4 .Sh AUTHORS .An Alexander Motin Aq mav@FreeBSD.org Index: stable/9/share/man/man9/get_cyclecount.9 =================================================================== --- stable/9/share/man/man9/get_cyclecount.9 (revision 290886) +++ stable/9/share/man/man9/get_cyclecount.9 (revision 290887) @@ -1,95 +1,95 @@ .\" Copyright (c) 2000 Mark R V Murray .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 15, 2011 .Dt GET_CYCLECOUNT 9 .Os .Sh NAME .Nm get_cyclecount .Nd get the CPU's fast counter register contents .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In machine/cpu.h -.Ft u_int64_t +.Ft uint64_t .Fn get_cyclecount "void" .Sh DESCRIPTION The .Fn get_cyclecount function uses a register available in most modern CPUs to return a value that is monotonically increasing inside each CPU. .Pp On SMP systems, there will be a number of separate monotonic sequences, one for each CPU running. The value in the SMP case is selected from one of these sequences, dependent on which CPU was scheduled to service the request. .Pp The speed and the maximum value of each counter is CPU-dependent. Some CPUs (such as the .Tn Intel 80486) do not have such a register, so .Fn get_cyclecount on these platforms returns a (monotonic) combination of numbers represented by the structure returned by .Xr binuptime 9 . .Pp The .Tn AMD64 and .Tn Intel 64 processors use the .Li TSC register. .Pp The .Tn IA64 processors use the .Li AR.ITC register. .Sh SEE ALSO .Xr binuptime 9 .Sh HISTORY The .Fn get_cyclecount function first appeared in .Fx 5.0 . .Sh AUTHORS This manual page was written by .An Mark Murray Aq markm@FreeBSD.org . Index: stable/9/share/man/man9/mbchain.9 =================================================================== --- stable/9/share/man/man9/mbchain.9 (revision 290886) +++ stable/9/share/man/man9/mbchain.9 (revision 290887) @@ -1,222 +1,222 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2001 Boris Popov .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 20, 2001 .Dt MBCHAIN 9 .Os .Sh NAME .Nm mbchain , .Nm mb_init , .Nm mb_initm , .Nm mb_done , .Nm mb_detach , .Nm mb_fixhdr , .Nm mb_reserve , .Nm mb_put_uint8 , .Nm mb_put_uint16be , .Nm mb_put_uint16le , .Nm mb_put_uint32be , .Nm mb_put_uint32le , .Nm mb_put_int64be , .Nm mb_put_int64le , .Nm mb_put_mem , .Nm mb_put_mbuf , .Nm mb_put_uio .Nd "set of functions to build an mbuf chain from various data types" .Sh SYNOPSIS .Cd options LIBMCHAIN .Li kldload libmchain .Pp .In sys/param.h .In sys/uio.h .In sys/mchain.h .Ft int .Fn mb_init "struct mbchain *mbp" .Ft void .Fn mb_initm "struct mbchain *mbp" "struct mbuf *m" .Ft void .Fn mb_done "struct mbchain *mbp" .Ft struct mbuf * .Fn mb_detach "struct mbchain *mbp" .Ft int .Fn mb_fixhdr "struct mbchain *mbp" .Ft caddr_t .Fn mb_reserve "struct mbchain *mbp" "int size" .Ft int -.Fn mb_put_uint8 "struct mbchain *mbp" "u_int8_t x" +.Fn mb_put_uint8 "struct mbchain *mbp" "uint8_t x" .Ft int -.Fn mb_put_uint16be "struct mbchain *mbp" "u_int16_t x" +.Fn mb_put_uint16be "struct mbchain *mbp" "uint16_t x" .Ft int -.Fn mb_put_uint16le "struct mbchain *mbp" "u_int16_t x" +.Fn mb_put_uint16le "struct mbchain *mbp" "uint16_t x" .Ft int -.Fn mb_put_uint32be "struct mbchain *mbp" "u_int32_t x" +.Fn mb_put_uint32be "struct mbchain *mbp" "uint32_t x" .Ft int -.Fn mb_put_uint32le "struct mbchain *mbp" "u_int32_t x" +.Fn mb_put_uint32le "struct mbchain *mbp" "uint32_t x" .Ft int .Fn mb_put_int64be "struct mbchain *mbp" "int64_t x" .Ft int .Fn mb_put_int64le "struct mbchain *mbp" "int64_t x" .Ft int .Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type" .Ft int .Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m" .Ft int .Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size" .Sh DESCRIPTION These functions are used to compose mbuf chains from various data types. The .Vt mbchain structure is used as a working context and should be initialized with a call to either .Fn mb_init or .Fn mb_initm . It has the following fields: .Bl -tag -width ".Va mb_count" .It Va "mb_top" .Pq Vt "struct mbuf *" A pointer to the top of constructed mbuf chain. .It Va mb_cur .Pq Vt "struct mbuf *" A pointer to the currently filled mbuf. .It Va mb_mleft .Pq Vt int Number of bytes left in the current mbuf. .It Va mb_count .Pq Vt int Total number of bytes placed in the mbuf chain. .It Va mb_copy .Pq Vt "mb_copy_t *" User-defined function to perform a copy into mbuf; useful if any unusual data conversion is necessary. .It Va mb_udata .Pq Vt "void *" User-supplied data which can be used in the .Va mb_copy function. .El .Pp .Fn mb_done function disposes an mbuf chain pointed to by .Fa mbp->mb_top field and sets the field to .Dv NULL . .Pp .Fn mb_detach function returns the value of .Fa mbp->mb_top field and sets its value to .Dv NULL . .Pp .Fn mb_fixhdr recalculates the length of an mbuf chain and updates the .Va m_pkthdr.len field of the first mbuf in the chain. It returns the calculated length. .Pp .Fn mb_reserve ensures that the object of the length specified by the .Fa size argument will fit in the current mbuf (mbuf allocation is performed if necessary), and advances all pointers as if the real data was placed. Returned value will point to the beginning of the reserved space. Note that the size of the object should not exceed .Dv MLEN bytes. .Pp All .Fn mb_put_* functions perform an actual copy of the data into mbuf chain. Functions which have .Cm le or .Cm be suffixes will perform conversion to the little\- or big\-endian data formats. .Pp .Fn mb_put_mem function copies .Fa size bytes of data specified by the .Fa source argument to an mbuf chain. The .Fa type argument specifies the method used to perform a copy, and can be one of the following: .Bl -tag -width ".Dv MB_MINLINE" .It Dv MB_MSYSTEM Use .Fn bcopy function. .It Dv MB_MUSER Use .Xr copyin 9 function. .It Dv MB_MINLINE Use an .Dq inline loop which does not call any function. .It Dv MB_MZERO Do not copy any data, but just fill the destination with zero bytes. .It Dv MB_MCUSTOM Call function specified by the .Fa mbp->mb_copy field. .El .Sh RETURN VALUES All .Ft int functions except .Fn mb_fixhdr return zero if successful and an error code otherwise. .Pp .Em Note : after failure of any function, an mbuf chain is left in the broken state, and only .Fn mb_done function can safely be called to destroy it. .Sh EXAMPLES .Bd -literal struct mbchain *mbp; struct mbuf *m; mb_init(mbp); mb_put_uint8(mbp, 33); mb_put_uint16le(mbp, length); m = m_copym(mbp->mb_top, 0, M_COPYALL, M_WAIT); send(m); mb_done(mbp); .Ed .Sh SEE ALSO .Xr mbuf 9 , .Xr mdchain 9 .Sh AUTHORS This manual page was written by .An Boris Popov Aq bp@FreeBSD.org . Index: stable/9/share/man/man9/mbuf_tags.9 =================================================================== --- stable/9/share/man/man9/mbuf_tags.9 (revision 290886) +++ stable/9/share/man/man9/mbuf_tags.9 (revision 290887) @@ -1,286 +1,286 @@ .\" $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $ .\" .\" The authors of this manual page are Angelos D. Keromytis .\" (angelos@cis.upenn.edu), Gleb Smirnoff , and .\" Robert Watson .\" .\" Copyright (c) 2004 Robert N. M. Watson .\" Copyright (c) 2001 Angelos D. Keromytis .\" .\" Permission to use, copy, and modify this software with or without .\" fee is hereby granted, provided that this entire notice is included .\" in all source code copies of any software which is or includes a copy .\" or modification of this software. .\" .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR .\" PURPOSE. .\" .\" $FreeBSD$ .\" .Dd January 12, 2008 .Dt MBUF_TAGS 9 .Os .Sh NAME .Nm mbuf_tags .Nd a framework for generic packet attributes .Sh SYNOPSIS .In sys/mbuf.h .Ft "struct m_tag *" -.Fn m_tag_alloc "u_int32_t cookie" "int type" "int len" "int wait" +.Fn m_tag_alloc "uint32_t cookie" "int type" "int len" "int wait" .Ft "struct m_tag *" .Fn m_tag_copy "struct m_tag *t" "int how" .Ft int .Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" "int how" .Ft void .Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" .Ft void .Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t" .Ft void .Fn m_tag_delete_nonpersistent "struct mbuf *m" .Ft "struct m_tag *" .Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *start" .Ft "struct m_tag *" .Fn m_tag_first "struct mbuf *m" .Ft void .Fn m_tag_free "struct m_tag *t" .Ft "struct m_tag *" .Fn m_tag_get "int type" "int len" "int wait" .Ft void .Fn m_tag_init "struct mbuf *m" .Ft struct m_tag * -.Fn m_tag_locate "struct mbuf *m" "u_int32_t cookie" "int type" "struct m_tag *t" +.Fn m_tag_locate "struct mbuf *m" "uint32_t cookie" "int type" "struct m_tag *t" .Ft "struct m_tag *" .Fn m_tag_next "struct mbuf *m" "struct m_tag *t" .Ft void .Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" .Ft void .Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" .Sh DESCRIPTION Mbuf tags allow additional meta-data to be associated with in-flight packets by providing a mechanism for the tagging of additional kernel memory onto packet header mbufs. Tags are maintained in chains off of the .Xr mbuf 9 header, and maintained using a series of API calls to allocate, search, and delete tags. Tags are identified using an ID and cookie that uniquely identify a class of data tagged onto the packet, and may contain an arbitrary amount of additional storage. Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as described in .Xr mac 9 , IPsec policy information as described in .Xr ipsec 4 , and packet filter tags used by .Xr pf 4 . .Pp Tags will be maintained across a variety of operations, including the copying of packet headers using facilities such as .Fn M_COPY_PKTHDR and .Fn M_MOVE_PKTHDR . Any tags associated with an mbuf header will be automatically freed when the mbuf is freed, although some subsystems will wish to delete the tags prior to that time. .Pp Packet tags are used by different kernel APIs to keep track of operations done or scheduled to happen to packets. Each packet tag can be distinguished by its type and cookie. The cookie is used to identify a specific module or API. The packet tags are attached to mbuf packet headers. .Pp The first .Fn sizeof "struct m_tag" bytes of a tag contain a .Vt "struct m_tag" : .Bd -literal struct m_tag { SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */ - u_int16_t m_tag_id; /* Tag ID */ - u_int16_t m_tag_len; /* Length of data */ - u_int32_t m_tag_cookie; /* ABI/Module ID */ + uint16_t m_tag_id; /* Tag ID */ + uint16_t m_tag_len; /* Length of data */ + uint32_t m_tag_cookie; /* ABI/Module ID */ void (*m_tag_free)(struct m_tag *); }; .Ed .Pp The .Va m_tag_link field is used to link tags together (see .Xr queue 3 for more details). The .Va m_tag_id , m_tag_len and .Va m_tag_cookie fields are set to type, length, and cookie, respectively. .Va m_tag_free points to .Fn m_tag_free_default . Following this structure are .Va m_tag_len bytes of space that can be used to store tag-specific information. Addressing this data region may be tricky. A safe way is embedding .Vt "struct m_tag" into a private data structure, as follows: .Bd -literal -offset indent struct foo { struct m_tag tag; ... }; struct foo *p = (struct foo *)m_tag_alloc(...); struct m_tag *mtag = &p->tag; .Ed .Pp Note that .Ox does not support cookies, it needs .Va m_tag_id to be globally unique. To keep compatibility with .Ox , a cookie .Dv MTAG_ABI_COMPAT is provided along with some compatibility functions. When writing an .Ox compatible code, one should be careful not to take already used tag type. Tag types are defined in .In sys/mbuf.h . .Ss Packet Tag Manipulation Functions .Bl -ohang -offset indent .It Fn m_tag_alloc cookie type len wait Allocate a new tag of type .Fa type and cookie .Fa cookie with .Va len bytes of space following the tag header itself. The .Fa wait argument is passed directly to .Xr malloc 9 . If successful, .Fn m_tag_alloc returns a memory buffer of .Pq Va len No + Fn sizeof "struct m_tag" bytes. Otherwise, .Dv NULL is returned. A compatibility function .Fn m_tag_get is also provided. .It Fn m_tag_copy tag how Allocate a copy of .Fa tag . The .Fa how argument is passed directly to .Fn m_tag_alloc . The return values are the same as in .Fn m_tag_alloc . .It Fn m_tag_copy_chain tombuf frommbuf how Allocate and copy all tags from mbuf .Fa frommbuf to mbuf .Fa tombuf . Returns 1 on success, and 0 on failure. In the latter case, mbuf .Fa tombuf loses all its tags, even previously present. .It Fn m_tag_delete mbuf tag Remove .Fa tag from .Fa mbuf Ns 's list and free it. .It Fn m_tag_delete_chain mbuf tag Remove and free a packet tag chain, starting from .Fa tag . If .Fa tag is .Dv NULL , all tags are deleted. .It Fn m_tag_delete_nonpersistent mbuf Traverse .Fa mbuf Ns 's tags and delete those which do not have the .Dv MTAG_PERSISTENT flag set. .It Fn m_tag_first mbuf Return the first tag associated with .Fa mbuf . .It Fn m_tag_free tag Free .Fa tag using its .Va m_tag_free method. The .Fn m_tag_free_default function is used by default. .It Fn m_tag_init mbuf Initialize the tag storage for packet .Fa mbuf . .It Fn m_tag_locate mbuf cookie type tag Search for a tag defined by .Fa type and .Fa cookie in .Fa mbuf , starting from position specified by .Fa tag . If the latter is .Dv NULL , then search through the whole list. Upon success, a pointer to the first found tag is returned. In either case, .Dv NULL is returned. A compatibility function .Fn m_tag_find is also provided. .It Fn m_tag_next mbuf tag Return tag next to .Fa tag in .Fa mbuf . If absent, .Dv NULL is returned. .It Fn m_tag_prepend mbuf tag Add the new tag .Fa tag at the head of the tag list for packet .Fa mbuf . .It Fn m_tag_unlink mbuf tag Remove tag .Fa tag from the list of tags of packet .Fa mbuf . .El .Sh CODE REFERENCES The tag-manipulating code is contained in the file .Pa sys/kern/uipc_mbuf2.c . Inlined functions are defined in .In sys/mbuf.h . .Sh SEE ALSO .Xr queue 3 , .Xr mbuf 9 .Sh HISTORY The packet tags first appeared in .Ox 2.9 and were written by .An Angelos D. Keromytis Aq angelos@openbsd.org . Index: stable/9/share/man/man9/mdchain.9 =================================================================== --- stable/9/share/man/man9/mdchain.9 (revision 290886) +++ stable/9/share/man/man9/mdchain.9 (revision 290887) @@ -1,211 +1,211 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2001 Boris Popov .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 28, 2001 .Dt MDCHAIN 9 .Os .Sh NAME .Nm mdchain , .Nm md_initm , .Nm md_done , .Nm md_append_record , .Nm md_next_record , .Nm md_get_uint8 , .Nm md_get_uint16 , .Nm md_get_uint16be , .Nm md_get_uint16le , .Nm md_get_uint32 , .Nm md_get_uint32be , .Nm md_get_uint32le , .Nm md_get_int64 , .Nm md_get_int64be , .Nm md_get_int64le , .Nm md_get_mem , .Nm md_get_mbuf , .Nm md_get_uio .Nd "set of functions to dissect an mbuf chain to various data types" .Sh SYNOPSIS .Cd options LIBMCHAIN .Li kldload libmchain .Pp .In sys/param.h .In sys/uio.h .In sys/mchain.h .Ft void .Fn md_initm "struct mdchain *mdp" "struct mbuf *m" .Ft void .Fn md_done "struct mdchain *mdp" .Ft void .Fn md_append_record "struct mdchain *mdp" "struct mbuf *top" .Ft int .Fn md_next_record "struct mdchain *mdp" .Ft int -.Fn md_get_uint8 "struct mdchain *mdp" "u_int8_t *x" +.Fn md_get_uint8 "struct mdchain *mdp" "uint8_t *x" .Ft int -.Fn md_get_uint16 "struct mdchain *mdp" "u_int16_t *x" +.Fn md_get_uint16 "struct mdchain *mdp" "uint16_t *x" .Ft int -.Fn md_get_uint16be "struct mdchain *mdp" "u_int16_t *x" +.Fn md_get_uint16be "struct mdchain *mdp" "uint16_t *x" .Ft int -.Fn md_get_uint16le "struct mdchain *mdp" "u_int16_t *x" +.Fn md_get_uint16le "struct mdchain *mdp" "uint16_t *x" .Ft int -.Fn md_get_uint32 "struct mdchain *mdp" "u_int32_t *x" +.Fn md_get_uint32 "struct mdchain *mdp" "uint32_t *x" .Ft int -.Fn md_get_uint32be "struct mdchain *mdp" "u_int32_t *x" +.Fn md_get_uint32be "struct mdchain *mdp" "uint32_t *x" .Ft int -.Fn md_get_uint32le "struct mdchain *mdp" "u_int32_t *x" +.Fn md_get_uint32le "struct mdchain *mdp" "uint32_t *x" .Ft int .Fn md_get_int64 "struct mdchain *mdp" "int64_t *x" .Ft int .Fn md_get_int64be "struct mdchain *mdp" "int64_t *x" .Ft int .Fn md_get_int64le "struct mdchain *mdp" "int64_t *x" .Ft int .Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type" .Ft int .Fn md_get_mbuf "struct mdchain *mdp" "int size" "struct mbuf **m" .Ft int .Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size" .Sh DESCRIPTION These functions are used to decompose mbuf chains to various data types. The .Vt mdchain structure is used as a working context and should be initialized through a call of the .Fn mb_initm function. It has the following fields: .Bl -tag -width "md_top" .It Va "md_top" .Pq Vt "struct mbuf *" A pointer to the top of the parsed mbuf chain. .It Va md_cur .Pq Vt "struct mbuf *" A pointer to the currently parsed mbuf. .It Va md_pas .Pq Vt int Offset in the current mbuf. .El .Pp The .Fn md_done function disposes of an mbuf chain pointed to by the .Fa mdp->md_top field and sets the field to .Dv NULL . .Pp The .Fn md_append_record appends a new mbuf chain using .Va m_nextpkt field to form a single linked list of mbuf chains. If the .Fa mdp->md_top field is .Dv NULL , then this function behaves exactly as the .Fn md_initm function. .Pp The .Fn md_next_record function extracts the next mbuf chain and disposes the current one, if any. For a new mbuf chain it calls the .Fn md_initm function. If there is no data left the function returns .Er ENOENT . .Pp All .Fn md_get_* functions perform an actual copy of the data from an mbuf chain. Functions which have .Cm le or .Cm be suffixes will perform conversion to the little\- or big\-endian data formats. .Pp .Fn md_get_mem function copies .Fa size bytes of data specified by the .Fa source argument from an mbuf chain. The .Fa type argument specifies the method used to perform a copy, and can be one of the following: .Bl -tag -width ".Dv MB_MINLINE" .It Dv MB_MSYSTEM Use the .Fn bcopy function. .It Dv MB_MUSER Use the .Xr copyin 9 function. .It Dv MB_MINLINE Use an .Dq inline loop which does not call any function. .El .Pp If .Fa target is .Dv NULL , an actual copy is not performed and the function just skips the given number of bytes. .Sh RETURN VALUES All .Ft int functions return zero if successful, otherwise an error code is returned. .Pp .Em Note : after failure of any function, an mbuf chain is left in the broken state and only the .Fn md_done function can safely be called to destroy it. .Sh EXAMPLES .Bd -literal struct mdchain *mdp; struct mbuf *m; -u_int16_t length; -u_int8_t byte; +uint16_t length; +uint8_t byte; receive(so, &m); md_initm(mdp, m); if (md_get_uint8(mdp, &byte) != 0 || md_get_uint16le(mdp, &length) != 0) error = EBADRPC; mb_done(mdp); .Ed .Sh SEE ALSO .Xr mbchain 9 , .Xr mbuf 9 .Sh AUTHORS This manual page was written by .An Boris Popov Aq bp@FreeBSD.org . Index: stable/9/share/man/man9/netisr.9 =================================================================== --- stable/9/share/man/man9/netisr.9 (revision 290886) +++ stable/9/share/man/man9/netisr.9 (revision 290887) @@ -1,221 +1,221 @@ .\" .\" Copyright (c) 2009 Robert N. M. Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 22, 2010 .Dt NETISR 9 .Os .Sh NAME .Nm netisr .Nd Kernel network dispatch service .Sh SYNOPSIS .In net/netisr.h .Ft void .Fn netisr_register "const struct netisr_handler *nhp" .Ft void .Fn netisr_unregister "const struct netisr_handler *nhp" .Ft int .Fn netisr_dispatch "u_int proto" "struct mbuf *m" .Ft int .Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" .Ft int .Fn netisr_queue "u_int proto" "struct mbuf *m" .Ft int .Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" .Ft void .Fn netisr_clearqdrops "const struct netisr_handler *nhp" .Ft void -.Fn netisr_getqdrops "const struct netisr_handler *nhp" "u_int64_t *qdropsp" +.Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp" .Ft void .Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" .Ft int .Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" .Ft u_int .Fn netisr_default_flow2cpu "u_int flowid" .Ft u_int .Fn netisr_get_cpucount "void" .Ft u_int .Fn netisr_get_cpuid "u_int cpunumber" .Sh DESCRIPTION The .Nm kernel interface suite allows device drivers (and other packet sources) to direct packets to protocols for directly dispatched or deferred processing. Protocol registration and work stream statistics may be monitored using .Xr netstat 1 . .Ss Protocol registration Protocols register and unregister handlers using .Fn netisr_register and .Fn netisr_unregister , and may also manage queue limits and statistics using the .Fn netisr_clearqdrops , .Fn netisr_getqdrops , .Fn netisr_getqlimit , and .Fn netisr_setqlimit . .Pp .Nm supports multi-processor execution of handlers, and relies on a combination of source ordering and protocol-specific ordering and work-placement policies to decide how do distribute work across one or more worker threads. Registering protocols will declare one of three policies: .Bl -tag -width NETISR_POLICY_SOURCE .It Dv NETISR_POLICY_SOURCE .Nm should maintain source ordering without advice from the protocol. .Nm will ignore any flow IDs present on .Vt mbuf headers for the purposes of work placement. .It Dv NETISR_POLICY_FLOW .Nm should maintain flow ordering as defined by the .Vt mbuf header flow ID field. If the protocol implements .Va nh_m2flow , then .Nm will query the protocol in the event that the .Vt mbuf doesn't have a flow ID, falling back on source ordering. .It NETISR_POLICY_CPU .Nm will entirely delegate all work placement decisions to the protocol, querying .Va nh_m2cpuid for each packet. .El .Pp Registration is declared using .Vt "struct netisr_handler" , whose fields are defined as follows: .Bl -tag -width "netisr_handler_t nh_handler" .It Vt "const char *" Va nh_name Unique character string name of the protocol, which may be included in .Xr sysctl 2 MIB names, so should not contain whitespace. .It Vt netisr_handler_t Va nh_handler Protocol handler function that will be invoked on each packet received for the protocol. .It Vt netisr_m2flow_t Va nh_m2flow Optional protocol function to generate a flow ID and set .Dv M_FLOWID for packets that do not enter .Nm with .Dv M_FLOWID defined. Will be used only with .Dv NETISR_POLICY_FLOW . .It Vt netisr_m2cpuid_t Va nh_m2cpuid Protocol function to determine what CPU a packet should be processed on. Will be used only with .Dv NETISR_POLICY_CPU . .It Vt netisr_drainedcpu_t Va nh_drainedcpu Optional callback function that will be invoked when a per-CPU queue was drained. It will never fire for directly dispatched packets. Unless fully understood, this special-purpose function should not be used. .\" In case you intend to use this please send 50 chocolate bars to each .\" of rwatson and bz and wait for an answer. .It Vt u_int Va nh_proto Protocol number used by both protocols to identify themselves to .Nm , and by packet sources to select what handler will be used to process packets. A table of supported protocol numbers appears below. For implementation reasons, protocol numbers great than 15 are currently unsupported. .It Vt u_int Va nh_qlimit The maximum per-CPU queue depth for the protocol; due to internal implementation details, the effective queue depth may be as much as twice this number. .It Vt u_int Va nh_policy The ordering and work placement policy for the protocol, as described earlier. .El .Ss Packet source interface Packet sources, such as network interfaces, may request protocol processing using the .Fn netisr_dispatch and .Fn netisr_queue interfaces. Both accept a protocol number and .Vt mbuf argument, but while .Fn netisr_queue will always execute the protocol handler asynchronously in a deferred context, .Fn netisr_dispatch will optionally direct dispatch if permitted by global and per-protocol policy. .Pp In order to provide additional load balancing and flow information, packet sources may also specify an opaque source identifier, which in practice might be a network interface number or socket pointer, using the .Fn netisr_dispatch_src and .Fn netisr_queue_src variants. .Ss Protocol number constants The follow protocol numbers are currently defined: .Bl -tag -width NETISR_ATALK1 .It Dv NETISR_IP IPv4 .It Dv NETISR_IGMP IGMPv3 loopback .It Dv NETISR_ROUTE Routing socket loopback .It Dv NETISR_AARP Appletalk AARP .It Dv NETISR_ATALK1 Appletalk phase 1 .It Dv NETISR_ATALK2 Appletalk phase 2 .It Dv NETISR_ARP ARP .It Dv NETISR_IPX IPX/SPX .It Dv NETISR_IPV6 IPv6 .It Dv NETISR_NATM ATM .It Dv NETISR_EPAIR .Xr netstat 1 , .Xr epair 4 .El .Sh AUTHORS This manual page and the .Nm implementation were written by .An Robert N. M. Watson . Index: stable/9/share/man/man9/random.9 =================================================================== --- stable/9/share/man/man9/random.9 (revision 290886) +++ stable/9/share/man/man9/random.9 (revision 290887) @@ -1,156 +1,156 @@ .\" .\" Copyright (c) 2000 .\" The Regents of the University of California. All rights reserved. .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" " .Dd September 25, 2000 .Dt RANDOM 9 .Os .Sh NAME .Nm arc4rand , .Nm arc4random , .Nm random , .Nm read_random , .Nm srandom .Nd supply pseudo-random numbers .Sh SYNOPSIS .In sys/libkern.h .Ft void .Fn srandom "u_long seed" .Ft u_long .Fn random "void" .Ft void .Fn arc4rand "void *ptr" "u_int length" "int reseed" -.Ft u_int32_t +.Ft uint32_t .Fn arc4random "void" .Pp .In sys/random.h .Ft int .Fn read_random "void *buffer" "int count" .Sh DESCRIPTION The .Fn random function will by default produce a sequence of numbers that can be duplicated by calling .Fn srandom with .Ql 1 as the .Fa seed . The .Fn srandom function may be called with any arbitrary .Fa seed value to get slightly more unpredictable numbers. It is important to remember that the .Fn random function is entirely predictable, and is therefore not of use where knowledge of the sequence of numbers may be of benefit to an attacker. .Pp The .Fn arc4rand function will return very good quality random numbers, slightly better suited for security-related purposes. The random numbers from .Fn arc4rand are seeded from the entropy device if it is available. Automatic reseeds happen after a certain timeinterval and after a certain number of bytes have been delivered. A forced reseed can be forced by passing a non-zero value in the .Fa reseed argument. .Pp The .Fn read_random function is used to return entropy directly from the entropy device if it has been loaded. If the entropy device is not loaded, then the .Fa buffer is filled with output generated by .Fn random . The .Fa buffer is filled with no more than .Fa count bytes. It is advised that .Fn read_random is not used; instead use .Fn arc4rand .Pp All the bits generated by .Fn random , .Fn arc4rand and .Fn read_random are usable. For example, .Sq Li random()&01 will produce a random binary value. .Pp The .Fn arc4random is a convenience function which calls .Fn arc4rand to return a 32 bit pseudo-random integer. .Sh RETURN VALUES The .Fn random function uses a non-linear additive feedback random number generator employing a default table of size 31 long integers to return successive pseudo-random numbers in the range from 0 to .if t 2\u\s731\s10\d\(mi1. .if n (2**31)\(mi1. The period of this random number generator is very large, approximately .if t 16\(mu(2\u\s731\s10\d\(mi1). .if n 16*((2**31)\(mi1). .Pp The .Fn arc4rand function uses the RC4 algorithm to generate successive pseudo-random bytes. The .Fn arc4random function uses .Fn arc4rand to generate pseudo-random numbers in the range from 0 to .if t 2\u\s732\s10\d\(mi1. .if n (2**32)\(mi1. .Pp The .Fn read_random function returns the number of bytes placed in .Fa buffer . .Sh AUTHORS .An Dan Moschuk wrote .Fn arc4random . .An Mark R V Murray wrote .Fn read_random . Index: stable/9/share/man/man9/rijndael.9 =================================================================== --- stable/9/share/man/man9/rijndael.9 (revision 290886) +++ stable/9/share/man/man9/rijndael.9 (revision 290887) @@ -1,135 +1,135 @@ .\" .\" Copyright (c) 2002 .\" Mark R V Murray. All rights reserved. .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" " .Dd February 6, 2002 .Dt RIJNDAEL 9 .Os .Sh NAME .Nm rijndael_makeKey , .Nm rijndael_cipherInit , .Nm rijndael_blockEncrypt , .Nm rijndael_padEncrypt , .Nm rijndael_blockDecrypt , .Nm rijndael_padDecrypt .Nd AES encryption .Sh SYNOPSIS .In sys/types.h .In crypto/rijndael.h .Ft int .Fo rijndael_makeKey .Fa "keyInstance *key" -.Fa "u_int8_t direction" +.Fa "uint8_t direction" .Fa "int keyLen" .Fa "char *keyMaterial" .Fc .Ft int .Fo rijndael_cipherInit .Fa "cipherInstance *cipher" -.Fa "u_int8_t mode" +.Fa "uint8_t mode" .Fa "char *IV" .Fc .Ft int .Fo rijndael_blockEncrypt .Fa "cipherInstance *cipher" .Fa "keyInstance *key" -.Fa "u_int8_t *input" +.Fa "uint8_t *input" .Fa "int inputLen" -.Fa "u_int8_t *outBuffer" +.Fa "uint8_t *outBuffer" .Fc .Ft int .Fo rijndael_padEncrypt .Fa "cipherInstance *cipher" .Fa "keyInstance *key" -.Fa "u_int8_t *input" +.Fa "uint8_t *input" .Fa "int inputOctets" -.Fa "u_int8_t *outBuffer" +.Fa "uint8_t *outBuffer" .Fc .Ft int .Fo rijndael_blockDecrypt .Fa "cipherInstance *cipher" .Fa "keyInstance *key" -.Fa "u_int8_t *input" +.Fa "uint8_t *input" .Fa "int inputLen" -.Fa "u_int8_t *outBuffer" +.Fa "uint8_t *outBuffer" .Fc .Ft int .Fo rijndael_padDecrypt .Fa "cipherInstance *cipher" .Fa "keyInstance *key" -.Fa "u_int8_t *input" +.Fa "uint8_t *input" .Fa "int inputOctets" -.Fa "u_int8_t *outBuffer" +.Fa "uint8_t *outBuffer" .Fc .Sh DESCRIPTION The .Fn rijndael_makeKey function is used to set up the key schedule in .Fa key . The .Fa direction (which may be .Dv DIR_ENCRYPT or .Dv DIR_DECRYPT ) specifies the intended use of the key. The length of the key (in bits) is given in .Fa keyLen , and must be 128, 192 or 256. The actual key is supplied in the buffer pointed to by .Fa keyMaterial . This material may be raw binary data, or an ASCII string containing a hexadecimal rendition of the raw binary data, dependent on a compile-time option in the .Nm sources, .Dv BINARY_KEY_MATERIAL . .Sh RETURN VALUES The .Fn rijndael_makeKey function will return .Dv BAD_KEY_INSTANCE if a .Dv NULL .Fa key is passed, .Dv BAD_KEY_DIR if .Fa direction is not .Dv DIR_ENCRYPT or .Dv DIR_DECRYPT , .Dv BAD_KEY_MAT if the key materials are not a hexadecimal string (and binary keys are not set), and .Dv TRUE otherwise. .Sh AUTHORS .An Mark R V Murray Index: stable/9/share/man/man9/zone.9 =================================================================== --- stable/9/share/man/man9/zone.9 (revision 290886) +++ stable/9/share/man/man9/zone.9 (revision 290887) @@ -1,242 +1,242 @@ .\"- .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 25, 2012 .Dt ZONE 9 .Os .Sh NAME .Nm uma_zcreate , .Nm uma_zalloc , .Nm uma_zalloc_arg , .Nm uma_zfree , .Nm uma_zfree_arg , .Nm uma_zdestroy , .Nm uma_zone_set_max, .Nm uma_zone_get_max, .Nm uma_zone_get_cur .Nd zone allocator .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In vm/uma.h .Ft uma_zone_t .Fo uma_zcreate .Fa "char *name" "int size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" -.Fa "int align" "u_int16_t flags" +.Fa "int align" "uint16_t flags" .Fc .Ft "void *" .Fn uma_zalloc "uma_zone_t zone" "int flags" .Ft "void *" .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" .Ft void .Fn uma_zfree "uma_zone_t zone" "void *item" .Ft void .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" .Ft void .Fn uma_zdestroy "uma_zone_t zone" .Ft int .Fn uma_zone_set_max "uma_zone_t zone" "int nitems" .Ft int .Fn uma_zone_get_max "uma_zone_t zone" .Ft int .Fn uma_zone_get_cur "uma_zone_t zone" .Sh DESCRIPTION The zone allocator provides an efficient interface for managing dynamically-sized collections of items of similar size. The zone allocator can work with preallocated zones as well as with runtime-allocated ones, and is therefore available much earlier in the boot process than other memory management routines. .Pp A zone is an extensible collection of items of identical size. The zone allocator keeps track of which items are in use and which are not, and provides functions for allocating items from the zone and for releasing them back (which makes them available for later use). .Pp After the first allocation of an item, it will have been cleared to zeroes, however subsequent allocations will retain the contents as of the last free. .Pp The .Fn uma_zcreate function creates a new zone from which items may then be allocated from. The .Fa name argument is a text name of the zone for debugging and stats; this memory should not be freed until the zone has been deallocated. .Pp The .Fa ctor and .Fa dtor arguments are callback functions that are called by the uma subsystem at the time of the call to .Fn uma_zalloc and .Fn uma_zfree respectively. Their purpose is to provide hooks for initializing or destroying things that need to be done at the time of the allocation or release of a resource. A good usage for the .Fa ctor and .Fa dtor callbacks might be to adjust a global count of the number of objects allocated. .Pp The .Fa uminit and .Fa fini arguments are used to optimize the allocation of objects from the zone. They are called by the uma subsystem whenever it needs to allocate or free several items to satisfy requests or memory pressure. A good use for the .Fa uminit and .Fa fini callbacks might be to initialize and destroy mutexes contained within the object. This would allow one to re-use already initialized mutexes when an object is returned from the uma subsystem's object cache. They are not called on each call to .Fn uma_zalloc and .Fn uma_zfree but rather in a batch mode on several objects. .Pp To allocate an item from a zone, simply call .Fn uma_zalloc with a pointer to that zone and set the .Fa flags argument to selected flags as documented in .Xr malloc 9 . It will return a pointer to an item if successful, or .Dv NULL in the rare case where all items in the zone are in use and the allocator is unable to grow the zone or when .Dv M_NOWAIT is specified. .Pp Items are released back to the zone from which they were allocated by calling .Fn uma_zfree with a pointer to the zone and a pointer to the item. If .Fa item is .Dv NULL , then .Fn uma_zfree does nothing. .Pp The variations .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow to specify an argument for the .Dv ctor and .Dv dtor functions, respectively. .Pp Created zones, which are empty, can be destroyed using .Fn uma_zdestroy , freeing all memory that was allocated for the zone. All items allocated from the zone with .Fn uma_zalloc must have been freed with .Fn uma_zfree before. .Pp The .Fn uma_zone_set_max function limits the number of items .Pq and therefore memory that can be allocated to .Fa zone . The .Fa nitems argument specifies the requested upper limit number of items. The effective limit is returned to the caller, as it may end up being higher than requested due to the implementation rounding up to ensure all memory pages allocated to the zone are utilised to capacity. The limit applies to the total number of items in the zone, which includes allocated items, free items and free items in the per-cpu caches. On systems with more than one CPU it may not be possible to allocate the specified number of items even when there is no shortage of memory, because all of the remaining free items may be in the caches of the other CPUs when the limit is hit. .Pp The .Fn uma_zone_get_max function returns the effective upper limit number of items for a zone. .Pp The .Fn uma_zone_get_cur function returns the approximate current occupancy of the zone. The returned value is approximate because appropriate synchronisation to determine an exact value is not performed by the implementation. This ensures low overhead at the expense of potentially stale data being used in the calculation. .Sh RETURN VALUES The .Fn uma_zalloc function returns a pointer to an item, or .Dv NULL if the zone ran out of unused items and the allocator was unable to enlarge it. .Sh SEE ALSO .Xr malloc 9 .Sh HISTORY The zone allocator first appeared in .Fx 3.0 . It was radically changed in .Fx 5.0 to function as a slab allocator. .Sh AUTHORS .An -nosplit The zone allocator was written by .An John S. Dyson . The zone allocator was rewritten in large parts by .An Jeff Roberson Aq jeff@FreeBSD.org to function as a slab allocator. .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . Changes for UMA by .An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . Index: stable/9/share/man/man9 =================================================================== --- stable/9/share/man/man9 (revision 290886) +++ stable/9/share/man/man9 (revision 290887) Property changes on: stable/9/share/man/man9 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man9:r231564 Index: stable/9/share/man =================================================================== --- stable/9/share/man (revision 290886) +++ stable/9/share/man (revision 290887) Property changes on: stable/9/share/man ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man:r231564 Index: stable/9/share =================================================================== --- stable/9/share (revision 290886) +++ stable/9/share (revision 290887) Property changes on: stable/9/share ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share:r231564 Index: stable/9/usr.bin/m4/lib/ohash_interval.3 =================================================================== --- stable/9/usr.bin/m4/lib/ohash_interval.3 (revision 290886) +++ stable/9/usr.bin/m4/lib/ohash_interval.3 (revision 290887) @@ -1,92 +1,92 @@ .\" $OpenBSD: ohash_interval.3,v 1.11 2007/05/31 19:19:30 jmc Exp $ .\" Copyright (c) 2001 Marc Espie .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd $Mdocdate: May 31 2007 $ .Dt OPEN_HASH_HELPER 3 .Os .Sh NAME .Nm ohash_interval , .Nm ohash_create_entry , .Nm ohash_qlookup , .Nm ohash_qlookupi .Nd helper functions for open hashing .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include -.Ft u_int32_t +.Ft uint32_t .Fn ohash_interval "const char *start" "const char **pend" .Ft "void *" .Fn ohash_create_entry "struct ohash_info *info" "const char *start" "const char **pend" .Ft "unsigned int" .Fn ohash_qlookupi "struct ohash *h" "const char *start" "const char **pend" .Ft "unsigned int" .Fn ohash_qlookup "struct ohash *h" "const char *start" .Sh DESCRIPTION These functions are commonly used to simplify open hashing usage, and use similar conventions. They operate indifferently on NUL-terminated strings .Po by setting .Fa *pend = .Dv NULL .Pc or memory ranges .Po delimited by .Fa start and .Fa *pend .Pc . For NUL-terminated strings, as a side effect, those functions set .Fa *pend to the terminating NUL byte. .Pp .Fn ohash_interval is a simple hashing function that yields good results on common data sets. .Pp .Fn ohash_create_entry can be used to create a new record with a given key. In that case, the alloc field of .Fa info should point to a .Xr malloc 3 Ns -like function to allocate the storage. .Pp .Fn ohash_qlookupi is a wrapper function that simply calls .Fn ohash_interval and .Fn ohash_lookup_interval . .Pp .Fn ohash_qlookup is a variation on .Fn ohash_qlookupi designed for NUL-terminated strings. .Sh SEE ALSO .Xr ohash_init 3 .Sh STANDARDS Those functions are completely non-standard and should be avoided in portable programs. .Sh HISTORY Those functions were designed and written for .Ox .Xr make 1 by Marc Espie in 1999. Index: stable/9/usr.bin/m4 =================================================================== --- stable/9/usr.bin/m4 (revision 290886) +++ stable/9/usr.bin/m4 (revision 290887) Property changes on: stable/9/usr.bin/m4 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/m4:r231564 Index: stable/9/usr.bin =================================================================== --- stable/9/usr.bin (revision 290886) +++ stable/9/usr.bin (revision 290887) Property changes on: stable/9/usr.bin ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin:r231564 Index: stable/9/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 =================================================================== --- stable/9/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 (revision 290886) +++ stable/9/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 (revision 290887) @@ -1,437 +1,437 @@ .\" .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution of this software and documentation and use in source and .\" binary forms, with or without modification, are permitted provided that .\" the following conditions are met: .\" .\" 1. Redistributions of source code or documentation must retain the above .\" copyright notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY FRAUNHOFER FOKUS .\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND .\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 14, 2003 .Dt SNMP_NETGRAPH 3 .Os .Sh NAME .Nm snmp_netgraph , .Nm snmp_node , .Nm snmp_nodename , .Nm ng_cookie_f , .Nm ng_hook_f , .Nm ng_register_cookie , .Nm ng_unregister_cookie , .Nm ng_register_hook , .Nm ng_unregister_hook , .Nm ng_unregister_module , .Nm ng_output , .Nm ng_output_node , .Nm ng_output_id , .Nm ng_dialog , .Nm ng_dialog_node , .Nm ng_dialog_id , .Nm ng_send_data , .Nm ng_mkpeer_id , .Nm ng_connect_node , .Nm ng_connect_id , .Nm ng_connect2_id , .Nm ng_connect2_tee_id , .Nm ng_rmhook , .Nm ng_rmhook_id , .Nm ng_rmhook_tee_id , .Nm ng_shutdown_id , .Nm ng_next_node_id , .Nm ng_node_id , .Nm ng_node_id_node , .Nm ng_node_name , .Nm ng_node_type , .Nm ng_peer_hook_id .Nd "netgraph module for snmpd. .Sh LIBRARY .Pq begemotSnmpdModulePath."netgraph" = "/usr/lib/snmp_netgraph.so" .Sh SYNOPSIS .In bsnmp/snmpmod.h .In bsnmp/snmp_netgraph.h .Vt extern ng_ID_t snmp_node ; .Vt extern u_char *snmp_nodename ; .Ft typedef void .Fn ng_cookie_f "const struct ng_mesg *mesg" "const char *path" "ng_ID_t id" "void *uarg" .Ft typedef void .Fn ng_hook_f "const char *hook" "const u_char *mesg" "size_t len" "void *uarg" .Ft void * -.Fn ng_register_cookie "const struct lmodule *mod" "u_int32_t cookie" "ng_ID_t id" "ng_cookie_f *func" "void *uarg" +.Fn ng_register_cookie "const struct lmodule *mod" "uint32_t cookie" "ng_ID_t id" "ng_cookie_f *func" "void *uarg" .Ft void .Fn ng_unregister_cookie "void *reg" .Ft void * .Fn ng_register_hook "const struct lmodule *mod" "const char *hook" "ng_hook_f *func" "void *uarg" .Ft void .Fn ng_unregister_hook "void *reg" .Ft void .Fn ng_unregister_module "const struct lmodule *mod" .Ft int .Fn ng_output "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_output_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_output_id "ng_ID_t node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog_id "ng_ID_t id" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_send_data "const char *hook" "const void *sndbuf" "size_t sndlen" .Ft ng_ID_t .Fn ng_mkpeer_id "ng_ID_t id" "const char *name" "const char *type" "const char *hook" "const char *peerhook" .Ft int .Fn ng_connect_node "const char *node" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect_id "ng_ID_t id" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect2_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect2_tee_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_rmhook "const char *ourhook" .Ft int .Fn ng_rmhook_id "ng_ID_t id" "const char *hook" .Ft int .Fn ng_rmhook_tee_id "ng_ID_t id" "const char *hook" .Ft int .Fn ng_shutdown_id "ng_ID_t id" .Ft ng_ID_t .Fn ng_next_node_id "ng_ID_t node" "const char *type" "const char *hook" .Ft ng_ID_t .Fn ng_node_id "const char *path" .Ft ng_ID_t .Fn ng_node_id_node "const char *node" .Ft ng_ID_t .Fn ng_node_name "ng_ID_t id" "char *name" .Ft ng_ID_t .Fn ng_node_type "ng_ID_t id" "char *type" .Ft int .Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook" .Sh DESCRIPTION The .Nm snmp_netgraph module implements a number of tables and scalars that enable remote access to the netgraph subsystem. It also exports a number of global variables and functions, that allow other modules to easily use the netgraph system. .Pp If upon start up of the module the variable .Va begemotNgControlNodeName is not empty the module opens a netgraph socket and names that socket node. If the variable is empty, the socket is created, as soon as the variable is written with a non-empty name. The socket can be closed by writing an empty string to the variable. The socket itself and its name are available in .Va snmp_node and .Va snmp_nodename . .Ss SENDING AND RECEIVING MESSAGES AND DATA There are three functions for sending control message: .Bl -tag -width ".It Fn ng_output_node" .It Fn ng_output sends a control message along the given .Fa path . .It Fn ng_output_node sends a control message to the node with name .Fa node and .It Fn ng_output_id sends a control message to the node with node id .Fa id . .El .Pp Each of these functions takes the following arguments: .Bl -tag -width ".It Fa cookie" .It Fa cookie is the node specific command cookie, .It Fa opcode is the node specific code for the operation to perform, .It Fa arg is a pointer to the message itself. This message must start with a .Vt struct ng_mesg . .It Fa arglen is the overall length of the message (header plus arguments). .El The functions return the message id that can be used to match incoming responses or -1 if an error occurs. .Pp Another class of functions is used to send a control message and to wait for a matching response. Note, that this operation blocks the daemon, so use it only if you are sure that the response will happen. There is a maximum timeout that is configurable in the MIB variable .Va begemotNgTimeout . Other messages arriving while the functions are waiting for the response are queued and delivered on the next call to the module's idle function. .Bl -tag -width ".It Fn ng_output_node" .It Fn ng_dialog sends a control message along the given .Fa path and waits for a matching response. .It Fn ng_dialog_node sends a control message to the node with name .Fa node and waits for a matching response. .It Fn ng_dialog_id sends a control message to the node with id .Fa id and waits for a matching response. .El .Pp All three functions take the same arguments as the .Fn ng_output* functions. The functions return the response message in a buffer allocated by .Xr malloc 3 or NULL in case of an error. The maximum size of the response buffer can be configured in the variable .Va begemotNgResBufSiz . .Pp A data message can be send with the function .Fn ng_send_data . This function takes the name of the .Va snmp_node Ns 's hook through which to send the data, a pointer to the message buffer and the size of the message. It returns -1 if an error happens. .Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES A module can register functions to asynchronously receive control and data message. .Pp The function .Fn ng_register_cookie registers a control message receive function. If a control message is received, that is not consumed by the dialog functions, the list of registered control message receive functions is scanned. If the cookie in the received message is the same as the .Fa cookie argument to the .Fn ng_register_cookie call and the .Fa id argument to the .Fn ng_register_cookie call was either 0 or equals the node id which sent the control message, the handler function .Fa func is called with a pointer to the received message, the hook on which the message was received (or NULL if it was received not on a hook), the id of the sender's node and the .Fa uarg argument of the registration call. The handler function should not modify the contents of the message, because more than one function may be registered to the same cookie and node id. .Pp A control message registration can be undone by calling .Fn ng_unregister_cookie with the return value of the registration call. If an error occurs while registering, .Fn ng_register_cookie returns NULL. .Pp A module can call .Fn ng_register_hook to register a callback for data messages on one of the .Va snmp_node Ns 's hooks. If a data message is received on that hook, the callback function .Fa func is called with the hook name, a pointer to the data message, the size of the message and the argument .Fa uarg to the registration function. The message should be treated as read-only. A data message registration can be undone by calling .Fn ng_unregister_hook with the return value of the registration call. If an error occurs while registering, .Fn ng_register_hook returns NULL. .Pp The function .Fn ng_unregister_module removes all control and data registrations for that module. .Ss FINDING NODES AND NODE CHARACTERISTICS .Pp The function .Fn ng_node_id returns the id of the node addressed by .Fa path or 0 if the node does not exists. .Pp The function .Fn ng_node_id_node returns the id of the node with name .Fa node or 0 if the node does not exist. .Pp The function .Fn ng_node_node retrieves the name of the node with id .Fa id and writes it to the buffer pointed to by .Fa name . This buffer should be at least .Li NG_NODESIZ bytes long. The function returns the node id or 0 if the node is not found. .Pp The function .Fn ng_node_type retrieves the name of the node with id .Fa id and writes it to the buffer pointed to by .Fa type . This buffer should be at least .Li NG_TYPESIZ bytes long. The function returns the node id or 0 if the node is not found. .Pp The function .Fn ng_peer_hook_id writes the name of the peer hook of the hook .Fa hook on the node with .Fa id to the buffer pointed to by .Fa peer_hook . The buffer should be at least .Li NG_HOOKSIZ bytes long. The function returns 0 if the node and the hook is found, -1 otherwise. The function skips intermediate tee nodes (see .Xr ng_tee 4 ) . .Pp The function .Fn ng_next_node_id returns the node id of the peer node that is on the other side of hook .Fa hook of node .Fa id . If .Fa type is not NULL, the function checks, that the peer node's type is .Fa type . The function skips intermediate tee nodes (see .Xr ng_tee 4 ) . It returns the node id of the peer node or 0 if an error occurs or the types do not match. .Ss CHANGING THE GRAPH A number of functions can be used to create or destroy nodes and hooks. .Pp The function .Fn ng_mkpeer_id creates a new node of type .Fa type whose hook .Fa peerhook will be connected to .Fa hook of node .Fa id . If .Fa name is not NULL the new node is named with this name. The function returns The node id of the new node or 0 if an error happens. .Pp The functions .Fn ng_connect_node and .Fn ng_connect_id make a new hook connecting .Fa ourhook of the modules socket node .Va snmp_node to .Fa peerhook of the node identified by id .Fa id or name .Fa node . The functions return 0 on success or -1 otherwise. .Pp The function .Fn ng_connect2_id connects hook .Fa ourhook of the node with id .Fa id to hook .Fa peerhook of the node with id .Fa peer . The functions return 0 on success or -1 otherwise. The function .Fn ng_connect2_tee_id does the same as .Fn ng_connect2_id except, that it puts an unnamed tee node between the two nodes. .Pp The function .Fn ng_rmhook removes hook .Fa hook on the module's .Va snmp_node . The function .Fn ng_rmhook_id removes hook .Fa hook on the node with id .Fa id . The function .Fn ng_rmhook_tee_id additionally shuts down all tee nodes between the node and the first non-tee peer. .Pp The function .Fn ng_shutdown_id destroys the given node. .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/bsnmp/defs/netgraph_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt This is the MIB that is implemented by this module. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh AUTHORS .An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/9/usr.sbin/bsnmpd =================================================================== --- stable/9/usr.sbin/bsnmpd (revision 290886) +++ stable/9/usr.sbin/bsnmpd (revision 290887) Property changes on: stable/9/usr.sbin/bsnmpd ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/bsnmpd:r231564 Index: stable/9/usr.sbin =================================================================== --- stable/9/usr.sbin (revision 290886) +++ stable/9/usr.sbin (revision 290887) Property changes on: stable/9/usr.sbin ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin:r231564 Index: stable/9 =================================================================== --- stable/9 (revision 290886) +++ stable/9 (revision 290887) Property changes on: stable/9 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r231564