From nobody@FreeBSD.org  Sun Jul  3 21:13:33 2011
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 4D5A81065675
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  3 Jul 2011 21:13:33 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 3C6C78FC12
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  3 Jul 2011 21:13:33 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id p63LDXJ7053746
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 3 Jul 2011 21:13:33 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id p63LDXvF053740;
	Sun, 3 Jul 2011 21:13:33 GMT
	(envelope-from nobody)
Message-Id: <201107032113.p63LDXvF053740@red.freebsd.org>
Date: Sun, 3 Jul 2011 21:13:33 GMT
From: Ben Kaduk <kaduk@mit.edu>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [PATCH] general cleanup in libalias.3
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         158623
>Category:       docs
>Synopsis:       [PATCH] general cleanup in libalias.3
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    gjb
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jul 03 21:20:11 UTC 2011
>Closed-Date:    Tue Jul 26 19:06:35 UTC 2011
>Last-Modified:  Tue Jul 26 19:10:09 UTC 2011
>Originator:     Ben Kaduk
>Release:        9-current
>Organization:
MIT SIPB
>Environment:
n/a
>Description:
There were some style and grammar issues in libalias.3 that I happened to notice.
>How-To-Repeat:

>Fix:


Patch attached with submission follows:

--- libalias.3.orig	2011-07-01 18:58:15.000000000 -0400
+++ libalias.3	2011-07-03 17:08:48.000000000 -0400
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD: src/sys/netinet/libalias/libalias.3,v 1.61 2011/06/22 20:00:27 ae Exp $
 .\"
-.Dd June 22, 2011
+.Dd July 03, 2011
 .Dt LIBALIAS 3
 .Os
 .Sh NAME
@@ -52,7 +52,7 @@
 .Pp
 A certain amount of flexibility is built into the packet aliasing engine.
 In the simplest mode of operation, a many-to-one address mapping takes
-place between local network and the packet aliasing host.
+place between the local network and the packet aliasing host.
 This is known as IP masquerading.
 In addition, one-to-one mappings between local and public addresses can
 also be implemented, which is known as static NAT.
@@ -63,13 +63,13 @@
 private address/port.
 .Pp
 The packet aliasing engine was designed to operate in user space outside
-of the kernel, without any access to private kernel data structure, but
+of the kernel, without any access to private kernel data structures, but
 the source code can also be ported to a kernel environment.
 .Sh INITIALIZATION AND CONTROL
 One special function,
 .Fn LibAliasInit ,
-must always be called before any packet handling may be performed and
-the returned instance pointer passed to all the other functions.
+must always be called before any packet handling may be performed, and
+the returned instance pointer must be passed to all the other functions.
 Normally, the
 .Fn LibAliasSetAddress
 function is called afterwards, to set the default aliasing address.
@@ -118,8 +118,8 @@
 This function has no return value and is used to clear any
 resources attached to internal data structures.
 .Pp
-This functions should be called when a program stops using the aliasing
-engine; it does, amongst other things, clear out any firewall holes.
+This function should be called when a program stops using the aliasing
+engine; amongst other things, it clears out any firewall holes.
 To provide backwards compatibility and extra security, it is added to
 the
 .Xr atexit 3
@@ -135,7 +135,7 @@
 All outgoing packets are re-mapped to this address unless overridden by a
 static address mapping established by
 .Fn LibAliasRedirectAddr .
-If this function is not called, and no static rules match, an outgoing
+If this function has not been called, and no static rules match, an outgoing
 packet retains its source address.
 .Pp
 If the
@@ -150,7 +150,7 @@
 If the
 .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
 mode bit is set to zero, this function can also be used to dynamically change
-the aliasing address on a packet to packet basis (it is a low overhead call).
+the aliasing address on a packet-to-packet basis (it is a low overhead call).
 .Pp
 It is mandatory that this function be called prior to any packet handling.
 .Ed
@@ -170,7 +170,7 @@
 .It Dv PKT_ALIAS_LOG
 Enables logging into
 .Pa /var/log/alias.log .
-Each time an aliasing link is created or deleted, the log file is appended
+Each time an aliasing link is created or deleted, the log file is appended to
 with the current number of ICMP, TCP and UDP links.
 Mainly useful for debugging when the log file is viewed continuously with
 .Xr tail 1 .
@@ -186,7 +186,7 @@
 aliasing host or local network will be unaffected.
 This mode bit is useful for implementing a one-way firewall.
 .It Dv PKT_ALIAS_SAME_PORTS
-If this mode bit is set, the packet aliasing engine will attempt to leave
+If this mode bit is set, the packet-aliasing engine will attempt to leave
 the alias port numbers unchanged from the actual local port numbers.
 This can be done as long as the quintuple (proto, alias addr, alias port,
 remote addr, remote port) is unique.
@@ -211,7 +211,7 @@
 192.168.0.0  ->  192.168.255.255  (Class C subnets)
 .Ed
 .Pp
-This option is useful in the case that packet aliasing host has both
+This option is useful in the case that the packet aliasing host has both
 registered and unregistered subnets on different interfaces.
 The registered subnet is fully accessible to the outside world, so traffic
 from it does not need to be passed through the packet aliasing engine.
@@ -229,8 +229,9 @@
 .It Dv PKT_ALIAS_PUNCH_FW
 This option makes
 .Nm
-`punch holes' in an
-.Xr ipfirewall 4
+.Dq punch holes
+in an
+.Xr ipfirewall 4 -
 based firewall for FTP/IRC DCC connections.
 The holes punched are bound by from/to IP address and port; it will not be
 possible to use a hole for another connection.
@@ -240,9 +241,9 @@
 (e.g.\& kill -9),
 changing the state of the flag will clear the entire firewall range
 allocated for holes.
-This will also happen on the initial call to
-.Fn LibAliasSetFWBase .
-This call must happen prior to setting this flag.
+This clearing will also happen on the initial call to
+.Fn LibAliasSetFWBase ,
+which must happen prior to setting this flag.
 .It Dv PKT_ALIAS_REVERSE
 This option makes
 .Nm
@@ -260,9 +261,11 @@
 .It Dv PKT_ALIAS_SKIP_GLOBAL
 This option is used by
 .Pa ipfw_nat
-only. Specifying it as a flag to
+only.
+Specifying it as a flag to
 .Fn LibAliasSetMode
-has no effect. See section
+has no effect.
+See section
 .Sx NETWORK ADDRESS TRANSLATION
 in
 .Xr ipfw 8
@@ -273,10 +276,10 @@
 .Ft void
 .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
 .Bd -ragged -offset indent
-Set firewall range allocated for punching firewall holes (with the
+Set the firewall range allocated for punching firewall holes (with the
 .Dv PKT_ALIAS_PUNCH_FW
 flag).
-The range will be cleared for all rules on initialization.
+The range is cleared for all rules on initialization.
 .Ed
 .Pp
 .Ft void
@@ -302,7 +305,7 @@
 .Fn LibAliasIn
 and
 .Fn LibAliasOut ,
-comprise minimal set of functions needed for a basic IP masquerading
+comprise the minimal set of functions needed for a basic IP masquerading
 implementation.
 .Pp
 .Ft int
@@ -323,11 +326,11 @@
 The packet aliasing process was successful.
 .It Dv PKT_ALIAS_IGNORED
 The packet was ignored and not de-aliased.
-This can happen if the protocol is unrecognized, possibly an ICMP message
-type is not handled or if incoming packets for new connections are being
-ignored (if
+This can happen if the protocol is unrecognized, as for an ICMP message
+type that is not handled, or if incoming packets for new connections are being
+ignored (if the
 .Dv PKT_ALIAS_DENY_INCOMING
-mode bit was set by
+mode bit was set using
 .Fn LibAliasSetMode ) .
 .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
 This is returned when a fragment cannot be resolved because the header
@@ -418,7 +421,7 @@
 .Fn LibAliasRedirectPort
 is called, a zero reference will track this change.
 .Pp
-If the link is further set up to operate for a load sharing, then
+If the link is further set up to operate with load sharing, then
 .Fa local_addr
 and
 .Fa local_port
@@ -433,7 +436,7 @@
 .Fa remote_port
 is zero, this indicates to redirect packets originating from any remote
 port number.
-Almost always, the remote port specification will be zero, but non-zero
+The remote port specification will almost always be zero, but non-zero
 remote addresses can sometimes be useful for firewalling.
 If two calls to
 .Fn LibAliasRedirectPort
@@ -485,8 +488,9 @@
 .Fn LibAliasRedirectAddr
 is called, a zero reference will track this change.
 .Pp
-If the link is further set up to operate for a load sharing, then
+If the link is further set up to operate with load sharing, then the
 .Fa local_addr
+argument
 is ignored, and is selected dynamically from the server pool, as described in
 .Fn LibAliasAddServer
 below.
@@ -542,12 +546,12 @@
 LSNAT operates as follows.
 A client attempts to access a server by using the server virtual address.
 The LSNAT router transparently redirects the request to one of the hosts
-in server pool, selected using a real-time load sharing algorithm.
+in the server pool, using a real-time load sharing algorithm.
 Multiple sessions may be initiated from the same client, and each session
-could be directed to a different host based on load balance across server
-pool hosts at the time.
-If load share is desired for just a few specific services, the configuration
-on LSNAT could be defined to restrict load share for just the services
+could be directed to a different host based on the load balance across server
+pool hosts when the sessions are initiated.
+If load sharing is desired for just a few specific services, the configuration
+on LSNAT could be defined to restrict load sharing to just the services
 desired.
 .Pp
 Currently, only the simplest selection algorithm is implemented, where a
@@ -606,8 +610,8 @@
 is the pointer returned by either of the redirection functions.
 If an invalid pointer is passed to
 .Fn LibAliasRedirectDelete ,
-then a program crash or unpredictable operation could result, so it is
-necessary to be careful using this function.
+then a program crash or unpredictable operation could result, so
+care is needed when using this function.
 .Ed
 .Pp
 .Ft int
@@ -714,7 +718,7 @@
 .Bd -ragged -offset indent
 This function specifies that any IP packet with protocol number of
 .Fa proto
-from a given remote address to an alias address be
+from a given remote address to an alias address will be
 redirected to a specified local address.
 .Pp
 If
@@ -829,10 +833,12 @@
 "struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \
 "int alias_param" "int link_type"
 .Bd -ragged -offset indent
-This function adds new state to instance hash table.
-Zero can be specified instead of dst_address and/or dst port.
-This makes link partially specified dynamic.
-However due to hashing method such links can be resolved on inbound (ext -> int) only.
+This function adds new state to the instance hash table.
+The dst_address and/or dst_port may be given as zero, which
+introduces some dynamic character into the link, since
+LibAliasSetAddress can change the address that is used.
+However, in the current implementation, such links can only be used
+for inbound (ext -> int) traffic.
 .Ed
 .Pp
 .Ft void
@@ -1119,9 +1125,9 @@
 .Ed
 .Pp
 .Va handler_chain
-keep tracks of all the protocol handlers loaded, while
+keeps track of all the protocol handlers loaded, while
 .Va ddl_chain
-takes care of userland modules loaded.
+tracks which userland modules are loaded.
 .Pp
 .Va handler_chain
 is composed of
@@ -1143,12 +1149,12 @@
 where:
 .Bl -inset
 .It Va pri
-is the priority assigned to a protocol handler, lower
+is the priority assigned to a protocol handler; lower priority
 is better.
 .It Va dir
 is the direction of packets: ingoing or outgoing.
 .It Va proto
-says at which protocol this packet belongs: IP, TCP or UDP.
+indicates to which protocol this packet belongs: IP, TCP or UDP.
 .It Va fingerprint
 points to the fingerprint function while protohandler points
 to the protocol handler function.
@@ -1156,8 +1162,8 @@
 .Pp
 The
 .Va fingerprint
-function has the double of scope of checking if the
-incoming packet is found and if it belongs to any categories that this
+function has the dual role of checking if the
+incoming packet is found, and if it belongs to any categories that this
 module can handle.
 .Pp
 The
@@ -1172,7 +1178,8 @@
 if it meets a module hook,
 .Va handler_chain
 is searched to see if there is an handler that matches
-this type of a packet (it checks protocol and direction of packet), then if
+this type of a packet (it checks protocol and direction of packet).
+Then, if
 more than one handler is found, it starts with the module with
 the lowest priority number: it calls the
 .Va fingerprint
@@ -1211,8 +1218,8 @@
 is called.
 The
 .Fn find_handler
-function is responsible for walking out the handler
-chain, it receives as input parameters:
+function is responsible for walking the handler
+chain; it receives as input parameters:
 .Bl -tag -width indent
 .It Fa IN
 direction
@@ -1236,9 +1243,9 @@
 .Pp
 As was mentioned earlier,
 .Nm
-in userland is a bit different, cause
-care has to be taken of module handling too (avoiding duplicate load of
-module, avoiding module with same name, etc.) so
+in userland is a bit different, as
+care must be taken in module handling as well (avoiding duplicate load of
+modules, avoiding modules with same name, etc.) so
 .Va dll_chain
 was introduced.
 .Pp
@@ -1252,9 +1259,8 @@
 .Nm
 first unloads all the loaded modules, then reloads all the modules listed in
 .Pa /etc/libalias.conf :
-for every module loaded, a new entry to
-.Va dll_chain
-is added.
+for every module loaded, a new entry is added to
+.Va dll_chain .
 .Pp
 .Va dll_chain
 is composed of
@@ -1291,7 +1297,8 @@
 .Pa alias_dummy.[ch] )
 in
 .Nm
-that can be used as a skeleton for future work, here we analyse some parts of that
+that can be used as a skeleton for future work.
+Here we analyse some parts of that
 module.
 From
 .Pa alias_dummy.c :
@@ -1305,7 +1312,7 @@
 is the
 .Dq "most important thing"
 in a module
-cause it describes the handlers present and lets the outside world use
+since it describes the handlers present and lets the outside world use
 it in an opaque way.
 .Pp
 It must ALWAYS be present in every module, and it MUST retain
@@ -1348,7 +1355,7 @@
 .Ed
 When running as KLD,
 .Fn mod_handler
-register/deregister the module using
+registers/deregisters the module using
 .Fn attach_handlers
 and
 .Fn detach_handlers ,


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->gjb 
Responsible-Changed-By: gjb 
Responsible-Changed-When: Mon Jul 4 00:26:17 UTC 2011 
Responsible-Changed-Why:  
I'll take this. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=158623 
State-Changed-From-To: open->patched 
State-Changed-By: gjb 
State-Changed-When: Mon Jul 4 23:00:50 UTC 2011 
State-Changed-Why:  
Committed to HEAD (r223773).  MFC in 1 week. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=158623 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/158623: commit references a PR
Date: Mon,  4 Jul 2011 23:00:43 +0000 (UTC)

 Author: gjb (doc committer)
 Date: Mon Jul  4 23:00:26 2011
 New Revision: 223773
 URL: http://svn.freebsd.org/changeset/base/223773
 
 Log:
   - General grammar and mdoc(7) fixes. [1] [2]
   - While here, remove a paragraph about userspace operation that
     has been outdated for some time. [2]
   
   PR:		158623
   Submitted by:	Ben Kudak (kaduk % mit!edu) [1]
   Reviewed by:	glebius [2]
   MFC after:	1 week
 
 Modified:
   head/sys/netinet/libalias/libalias.3
 
 Modified: head/sys/netinet/libalias/libalias.3
 ==============================================================================
 --- head/sys/netinet/libalias/libalias.3	Mon Jul  4 22:08:04 2011	(r223772)
 +++ head/sys/netinet/libalias/libalias.3	Mon Jul  4 23:00:26 2011	(r223773)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd June 22, 2011
 +.Dd July 04, 2011
  .Dt LIBALIAS 3
  .Os
  .Sh NAME
 @@ -52,7 +52,7 @@ machine on the local network.
  .Pp
  A certain amount of flexibility is built into the packet aliasing engine.
  In the simplest mode of operation, a many-to-one address mapping takes
 -place between local network and the packet aliasing host.
 +place between the local network and the packet aliasing host.
  This is known as IP masquerading.
  In addition, one-to-one mappings between local and public addresses can
  also be implemented, which is known as static NAT.
 @@ -61,15 +61,11 @@ linked to different public addresses, co
  many-to-one mappings.
  Also, a given public address and port can be statically redirected to a
  private address/port.
 -.Pp
 -The packet aliasing engine was designed to operate in user space outside
 -of the kernel, without any access to private kernel data structure, but
 -the source code can also be ported to a kernel environment.
  .Sh INITIALIZATION AND CONTROL
  One special function,
  .Fn LibAliasInit ,
 -must always be called before any packet handling may be performed and
 -the returned instance pointer passed to all the other functions.
 +must always be called before any packet handling may be performed, and
 +the returned instance pointer must be passed to all the other functions.
  Normally, the
  .Fn LibAliasSetAddress
  function is called afterwards, to set the default aliasing address.
 @@ -118,8 +114,8 @@ prior to any packet handling.
  This function has no return value and is used to clear any
  resources attached to internal data structures.
  .Pp
 -This functions should be called when a program stops using the aliasing
 -engine; it does, amongst other things, clear out any firewall holes.
 +This function should be called when a program stops using the aliasing
 +engine; amongst other things, it clears out any firewall holes.
  To provide backwards compatibility and extra security, it is added to
  the
  .Xr atexit 3
 @@ -135,7 +131,7 @@ local area network are aliased.
  All outgoing packets are re-mapped to this address unless overridden by a
  static address mapping established by
  .Fn LibAliasRedirectAddr .
 -If this function is not called, and no static rules match, an outgoing
 +If this function has not been called, and no static rules match, an outgoing
  packet retains its source address.
  .Pp
  If the
 @@ -150,7 +146,7 @@ address may or may not change on success
  If the
  .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
  mode bit is set to zero, this function can also be used to dynamically change
 -the aliasing address on a packet to packet basis (it is a low overhead call).
 +the aliasing address on a packet-to-packet basis (it is a low overhead call).
  .Pp
  It is mandatory that this function be called prior to any packet handling.
  .Ed
 @@ -170,7 +166,7 @@ The following mode bits are defined in
  .It Dv PKT_ALIAS_LOG
  Enables logging into
  .Pa /var/log/alias.log .
 -Each time an aliasing link is created or deleted, the log file is appended
 +Each time an aliasing link is created or deleted, the log file is appended to
  with the current number of ICMP, TCP and UDP links.
  Mainly useful for debugging when the log file is viewed continuously with
  .Xr tail 1 .
 @@ -186,7 +182,7 @@ Response packets to connections or trans
  aliasing host or local network will be unaffected.
  This mode bit is useful for implementing a one-way firewall.
  .It Dv PKT_ALIAS_SAME_PORTS
 -If this mode bit is set, the packet aliasing engine will attempt to leave
 +If this mode bit is set, the packet-aliasing engine will attempt to leave
  the alias port numbers unchanged from the actual local port numbers.
  This can be done as long as the quintuple (proto, alias addr, alias port,
  remote addr, remote port) is unique.
 @@ -211,7 +207,7 @@ Standard Class A, B and C unregistered a
  192.168.0.0  ->  192.168.255.255  (Class C subnets)
  .Ed
  .Pp
 -This option is useful in the case that packet aliasing host has both
 +This option is useful in the case that the packet aliasing host has both
  registered and unregistered subnets on different interfaces.
  The registered subnet is fully accessible to the outside world, so traffic
  from it does not need to be passed through the packet aliasing engine.
 @@ -229,8 +225,9 @@ of an address change.
  .It Dv PKT_ALIAS_PUNCH_FW
  This option makes
  .Nm
 -`punch holes' in an
 -.Xr ipfirewall 4
 +.Dq punch holes
 +in an
 +.Xr ipfirewall 4 -
  based firewall for FTP/IRC DCC connections.
  The holes punched are bound by from/to IP address and port; it will not be
  possible to use a hole for another connection.
 @@ -240,9 +237,9 @@ To cater to unexpected death of a progra
  (e.g.\& kill -9),
  changing the state of the flag will clear the entire firewall range
  allocated for holes.
 -This will also happen on the initial call to
 -.Fn LibAliasSetFWBase .
 -This call must happen prior to setting this flag.
 +This clearing will also happen on the initial call to
 +.Fn LibAliasSetFWBase ,
 +which must happen prior to setting this flag.
  .It Dv PKT_ALIAS_REVERSE
  This option makes
  .Nm
 @@ -260,9 +257,11 @@ below for details.
  .It Dv PKT_ALIAS_SKIP_GLOBAL
  This option is used by
  .Pa ipfw_nat
 -only. Specifying it as a flag to
 +only.
 +Specifying it as a flag to
  .Fn LibAliasSetMode
 -has no effect. See section
 +has no effect.
 +See section
  .Sx NETWORK ADDRESS TRANSLATION
  in
  .Xr ipfw 8
 @@ -273,10 +272,10 @@ for more details.
  .Ft void
  .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
  .Bd -ragged -offset indent
 -Set firewall range allocated for punching firewall holes (with the
 +Set the firewall range allocated for punching firewall holes (with the
  .Dv PKT_ALIAS_PUNCH_FW
  flag).
 -The range will be cleared for all rules on initialization.
 +The range is cleared for all rules on initialization.
  .Ed
  .Pp
  .Ft void
 @@ -302,7 +301,7 @@ the two packet handling functions,
  .Fn LibAliasIn
  and
  .Fn LibAliasOut ,
 -comprise minimal set of functions needed for a basic IP masquerading
 +comprise the minimal set of functions needed for a basic IP masquerading
  implementation.
  .Pp
  .Ft int
 @@ -323,11 +322,11 @@ Return codes:
  The packet aliasing process was successful.
  .It Dv PKT_ALIAS_IGNORED
  The packet was ignored and not de-aliased.
 -This can happen if the protocol is unrecognized, possibly an ICMP message
 -type is not handled or if incoming packets for new connections are being
 -ignored (if
 +This can happen if the protocol is unrecognized, as for an ICMP message
 +type that is not handled, or if incoming packets for new connections are being
 +ignored (if the
  .Dv PKT_ALIAS_DENY_INCOMING
 -mode bit was set by
 +mode bit was set using
  .Fn LibAliasSetMode ) .
  .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
  This is returned when a fragment cannot be resolved because the header
 @@ -418,7 +417,7 @@ is called to change the address after
  .Fn LibAliasRedirectPort
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then
  .Fa local_addr
  and
  .Fa local_port
 @@ -433,7 +432,7 @@ Likewise, if
  .Fa remote_port
  is zero, this indicates to redirect packets originating from any remote
  port number.
 -Almost always, the remote port specification will be zero, but non-zero
 +The remote port specification will almost always be zero, but non-zero
  remote addresses can sometimes be useful for firewalling.
  If two calls to
  .Fn LibAliasRedirectPort
 @@ -485,9 +484,10 @@ is called to change the address after
  .Fn LibAliasRedirectAddr
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then the
  .Fa local_addr
 -is ignored, and is selected dynamically from the server pool, as described in
 +argument is ignored, and is selected dynamically from the server pool,
 +as described in
  .Fn LibAliasAddServer
  below.
  .Pp
 @@ -542,12 +542,12 @@ up for Load Sharing using IP Network Add
  LSNAT operates as follows.
  A client attempts to access a server by using the server virtual address.
  The LSNAT router transparently redirects the request to one of the hosts
 -in server pool, selected using a real-time load sharing algorithm.
 +in the server pool, using a real-time load sharing algorithm.
  Multiple sessions may be initiated from the same client, and each session
 -could be directed to a different host based on load balance across server
 -pool hosts at the time.
 -If load share is desired for just a few specific services, the configuration
 -on LSNAT could be defined to restrict load share for just the services
 +could be directed to a different host based on the load balance across server
 +pool hosts when the sessions are initiated.
 +If load sharing is desired for just a few specific services, the configuration
 +on LSNAT could be defined to restrict load sharing to just the services
  desired.
  .Pp
  Currently, only the simplest selection algorithm is implemented, where a
 @@ -606,8 +606,8 @@ The parameter
  is the pointer returned by either of the redirection functions.
  If an invalid pointer is passed to
  .Fn LibAliasRedirectDelete ,
 -then a program crash or unpredictable operation could result, so it is
 -necessary to be careful using this function.
 +then a program crash or unpredictable operation could result, so
 +care is needed when using this function.
  .Ed
  .Pp
  .Ft int
 @@ -714,7 +714,7 @@ access, or to restrict access to certain
  .Bd -ragged -offset indent
  This function specifies that any IP packet with protocol number of
  .Fa proto
 -from a given remote address to an alias address be
 +from a given remote address to an alias address will be
  redirected to a specified local address.
  .Pp
  If
 @@ -829,10 +829,12 @@ is the pointer to the packet to be de-al
  "struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \
  "int alias_param" "int link_type"
  .Bd -ragged -offset indent
 -This function adds new state to instance hash table.
 -Zero can be specified instead of dst_address and/or dst port.
 -This makes link partially specified dynamic.
 -However due to hashing method such links can be resolved on inbound (ext -> int) only.
 +This function adds new state to the instance hash table.
 +The dst_address and/or dst_port may be given as zero, which
 +introduces some dynamic character into the link, since
 +LibAliasSetAddress can change the address that is used.
 +However, in the current implementation, such links can only be used
 +for inbound (ext -> int) traffic.
  .Ed
  .Pp
  .Ft void
 @@ -1119,9 +1121,9 @@ SLIST_HEAD(dll_chain, dll) dll_chain ...
  .Ed
  .Pp
  .Va handler_chain
 -keep tracks of all the protocol handlers loaded, while
 +keeps track of all the protocol handlers loaded, while
  .Va ddl_chain
 -takes care of userland modules loaded.
 +tracks which userland modules are loaded.
  .Pp
  .Va handler_chain
  is composed of
 @@ -1143,12 +1145,12 @@ struct proto_handler {
  where:
  .Bl -inset
  .It Va pri
 -is the priority assigned to a protocol handler, lower
 +is the priority assigned to a protocol handler; lower priority
  is better.
  .It Va dir
  is the direction of packets: ingoing or outgoing.
  .It Va proto
 -says at which protocol this packet belongs: IP, TCP or UDP.
 +indicates to which protocol this packet belongs: IP, TCP or UDP.
  .It Va fingerprint
  points to the fingerprint function while protohandler points
  to the protocol handler function.
 @@ -1156,8 +1158,8 @@ to the protocol handler function.
  .Pp
  The
  .Va fingerprint
 -function has the double of scope of checking if the
 -incoming packet is found and if it belongs to any categories that this
 +function has the dual role of checking if the
 +incoming packet is found, and if it belongs to any categories that this
  module can handle.
  .Pp
  The
 @@ -1172,8 +1174,8 @@ When a packet enters
  if it meets a module hook,
  .Va handler_chain
  is searched to see if there is an handler that matches
 -this type of a packet (it checks protocol and direction of packet), then if
 -more than one handler is found, it starts with the module with
 +this type of a packet (it checks protocol and direction of packet).
 +Then, if more than one handler is found, it starts with the module with
  the lowest priority number: it calls the
  .Va fingerprint
  function and interprets the result.
 @@ -1211,8 +1213,8 @@ structure, then
  is called.
  The
  .Fn find_handler
 -function is responsible for walking out the handler
 -chain, it receives as input parameters:
 +function is responsible for walking the handler
 +chain; it receives as input parameters:
  .Bl -tag -width indent
  .It Fa IN
  direction
 @@ -1236,9 +1238,9 @@ supporting INcoming UDP packets.
  .Pp
  As was mentioned earlier,
  .Nm
 -in userland is a bit different, cause
 -care has to be taken of module handling too (avoiding duplicate load of
 -module, avoiding module with same name, etc.) so
 +in userland is a bit different, as
 +care must be taken in module handling as well (avoiding duplicate load of
 +modules, avoiding modules with same name, etc.) so
  .Va dll_chain
  was introduced.
  .Pp
 @@ -1252,9 +1254,8 @@ When an application calls
  .Nm
  first unloads all the loaded modules, then reloads all the modules listed in
  .Pa /etc/libalias.conf :
 -for every module loaded, a new entry to
 -.Va dll_chain
 -is added.
 +for every module loaded, a new entry is added to
 +.Va dll_chain .
  .Pp
  .Va dll_chain
  is composed of
 @@ -1291,8 +1292,8 @@ There is a module (called
  .Pa alias_dummy.[ch] )
  in
  .Nm
 -that can be used as a skeleton for future work, here we analyse some parts of that
 -module.
 +that can be used as a skeleton for future work.
 +Here we analyse some parts of that module.
  From
  .Pa alias_dummy.c :
  .Bd -literal
 @@ -1305,7 +1306,7 @@ The variable
  is the
  .Dq "most important thing"
  in a module
 -cause it describes the handlers present and lets the outside world use
 +since it describes the handlers present and lets the outside world use
  it in an opaque way.
  .Pp
  It must ALWAYS be present in every module, and it MUST retain
 @@ -1348,7 +1349,7 @@ mod_handler(module_t mod, int type, void
  .Ed
  When running as KLD,
  .Fn mod_handler
 -register/deregister the module using
 +registers/deregisters the module using
  .Fn attach_handlers
  and
  .Fn detach_handlers ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: gjb 
State-Changed-When: Tue Jul 26 19:06:12 UTC 2011 
State-Changed-Why:  
Merged to 7-stable and 8-stable.  Thanks! 


http://www.freebsd.org/cgi/query-pr.cgi?pr=158623 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/158623: commit references a PR
Date: Tue, 26 Jul 2011 19:05:25 +0000 (UTC)

 Author: gjb (doc committer)
 Date: Tue Jul 26 19:05:10 2011
 New Revision: 224459
 URL: http://svn.freebsd.org/changeset/base/224459
 
 Log:
   MFC 223773:
   
   - General grammar and mdoc(7) fixes.
   - While here, remove a paragraph about userspace operation
     that has been outdated for some time.
   
   PR:		158623
 
 Modified:
   stable/8/sys/netinet/libalias/libalias.3
 Directory Properties:
   stable/8/sys/   (props changed)
   stable/8/sys/amd64/include/xen/   (props changed)
   stable/8/sys/cddl/contrib/opensolaris/   (props changed)
   stable/8/sys/contrib/dev/acpica/   (props changed)
   stable/8/sys/contrib/pf/   (props changed)
   stable/8/sys/geom/label/   (props changed)
 
 Modified: stable/8/sys/netinet/libalias/libalias.3
 ==============================================================================
 --- stable/8/sys/netinet/libalias/libalias.3	Tue Jul 26 18:59:38 2011	(r224458)
 +++ stable/8/sys/netinet/libalias/libalias.3	Tue Jul 26 19:05:10 2011	(r224459)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd October 1, 2006
 +.Dd July 04, 2011
  .Dt LIBALIAS 3
  .Os
  .Sh NAME
 @@ -52,7 +52,7 @@ machine on the local network.
  .Pp
  A certain amount of flexibility is built into the packet aliasing engine.
  In the simplest mode of operation, a many-to-one address mapping takes
 -place between local network and the packet aliasing host.
 +place between the local network and the packet aliasing host.
  This is known as IP masquerading.
  In addition, one-to-one mappings between local and public addresses can
  also be implemented, which is known as static NAT.
 @@ -61,15 +61,11 @@ linked to different public addresses, co
  many-to-one mappings.
  Also, a given public address and port can be statically redirected to a
  private address/port.
 -.Pp
 -The packet aliasing engine was designed to operate in user space outside
 -of the kernel, without any access to private kernel data structure, but
 -the source code can also be ported to a kernel environment.
  .Sh INITIALIZATION AND CONTROL
  One special function,
  .Fn LibAliasInit ,
 -must always be called before any packet handling may be performed and
 -the returned instance pointer passed to all the other functions.
 +must always be called before any packet handling may be performed, and
 +the returned instance pointer must be passed to all the other functions.
  Normally, the
  .Fn LibAliasSetAddress
  function is called afterwards, to set the default aliasing address.
 @@ -118,8 +114,8 @@ prior to any packet handling.
  This function has no return value and is used to clear any
  resources attached to internal data structures.
  .Pp
 -This functions should be called when a program stops using the aliasing
 -engine; it does, amongst other things, clear out any firewall holes.
 +This function should be called when a program stops using the aliasing
 +engine; amongst other things, it clears out any firewall holes.
  To provide backwards compatibility and extra security, it is added to
  the
  .Xr atexit 3
 @@ -135,7 +131,7 @@ local area network are aliased.
  All outgoing packets are re-mapped to this address unless overridden by a
  static address mapping established by
  .Fn LibAliasRedirectAddr .
 -If this function is not called, and no static rules match, an outgoing
 +If this function has not been called, and no static rules match, an outgoing
  packet retains its source address.
  .Pp
  If the
 @@ -150,7 +146,7 @@ address may or may not change on success
  If the
  .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
  mode bit is set to zero, this function can also be used to dynamically change
 -the aliasing address on a packet to packet basis (it is a low overhead call).
 +the aliasing address on a packet-to-packet basis (it is a low overhead call).
  .Pp
  It is mandatory that this function be called prior to any packet handling.
  .Ed
 @@ -170,7 +166,7 @@ The following mode bits are defined in
  .It Dv PKT_ALIAS_LOG
  Enables logging into
  .Pa /var/log/alias.log .
 -Each time an aliasing link is created or deleted, the log file is appended
 +Each time an aliasing link is created or deleted, the log file is appended to
  with the current number of ICMP, TCP and UDP links.
  Mainly useful for debugging when the log file is viewed continuously with
  .Xr tail 1 .
 @@ -186,7 +182,7 @@ Response packets to connections or trans
  aliasing host or local network will be unaffected.
  This mode bit is useful for implementing a one-way firewall.
  .It Dv PKT_ALIAS_SAME_PORTS
 -If this mode bit is set, the packet aliasing engine will attempt to leave
 +If this mode bit is set, the packet-aliasing engine will attempt to leave
  the alias port numbers unchanged from the actual local port numbers.
  This can be done as long as the quintuple (proto, alias addr, alias port,
  remote addr, remote port) is unique.
 @@ -211,7 +207,7 @@ Standard Class A, B and C unregistered a
  192.168.0.0  ->  192.168.255.255  (Class C subnets)
  .Ed
  .Pp
 -This option is useful in the case that packet aliasing host has both
 +This option is useful in the case that the packet aliasing host has both
  registered and unregistered subnets on different interfaces.
  The registered subnet is fully accessible to the outside world, so traffic
  from it does not need to be passed through the packet aliasing engine.
 @@ -229,8 +225,9 @@ of an address change.
  .It Dv PKT_ALIAS_PUNCH_FW
  This option makes
  .Nm
 -`punch holes' in an
 -.Xr ipfirewall 4
 +.Dq punch holes
 +in an
 +.Xr ipfirewall 4 -
  based firewall for FTP/IRC DCC connections.
  The holes punched are bound by from/to IP address and port; it will not be
  possible to use a hole for another connection.
 @@ -240,9 +237,9 @@ To cater to unexpected death of a progra
  (e.g.\& kill -9),
  changing the state of the flag will clear the entire firewall range
  allocated for holes.
 -This will also happen on the initial call to
 -.Fn LibAliasSetFWBase .
 -This call must happen prior to setting this flag.
 +This clearing will also happen on the initial call to
 +.Fn LibAliasSetFWBase ,
 +which must happen prior to setting this flag.
  .It Dv PKT_ALIAS_REVERSE
  This option makes
  .Nm
 @@ -263,10 +260,10 @@ below for details.
  .Ft void
  .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
  .Bd -ragged -offset indent
 -Set firewall range allocated for punching firewall holes (with the
 +Set the firewall range allocated for punching firewall holes (with the
  .Dv PKT_ALIAS_PUNCH_FW
  flag).
 -The range will be cleared for all rules on initialization.
 +The range is cleared for all rules on initialization.
  .Ed
  .Pp
  .Ft void
 @@ -292,7 +289,7 @@ the two packet handling functions,
  .Fn LibAliasIn
  and
  .Fn LibAliasOut ,
 -comprise minimal set of functions needed for a basic IP masquerading
 +comprise the minimal set of functions needed for a basic IP masquerading
  implementation.
  .Pp
  .Ft int
 @@ -313,11 +310,11 @@ Return codes:
  The packet aliasing process was successful.
  .It Dv PKT_ALIAS_IGNORED
  The packet was ignored and not de-aliased.
 -This can happen if the protocol is unrecognized, possibly an ICMP message
 -type is not handled or if incoming packets for new connections are being
 -ignored (if
 +This can happen if the protocol is unrecognized, as for an ICMP message
 +type that is not handled, or if incoming packets for new connections are being
 +ignored (if the
  .Dv PKT_ALIAS_DENY_INCOMING
 -mode bit was set by
 +mode bit was set using
  .Fn LibAliasSetMode ) .
  .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
  This is returned when a fragment cannot be resolved because the header
 @@ -408,7 +405,7 @@ is called to change the address after
  .Fn LibAliasRedirectPort
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then
  .Fa local_addr
  and
  .Fa local_port
 @@ -423,7 +420,7 @@ Likewise, if
  .Fa remote_port
  is zero, this indicates to redirect packets originating from any remote
  port number.
 -Almost always, the remote port specification will be zero, but non-zero
 +The remote port specification will almost always be zero, but non-zero
  remote addresses can sometimes be useful for firewalling.
  If two calls to
  .Fn LibAliasRedirectPort
 @@ -475,9 +472,10 @@ is called to change the address after
  .Fn LibAliasRedirectAddr
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then the
  .Fa local_addr
 -is ignored, and is selected dynamically from the server pool, as described in
 +argument is ignored, and is selected dynamically from the server pool,
 +as described in
  .Fn LibAliasAddServer
  below.
  .Pp
 @@ -532,12 +530,12 @@ up for Load Sharing using IP Network Add
  LSNAT operates as follows.
  A client attempts to access a server by using the server virtual address.
  The LSNAT router transparently redirects the request to one of the hosts
 -in server pool, selected using a real-time load sharing algorithm.
 +in the server pool, using a real-time load sharing algorithm.
  Multiple sessions may be initiated from the same client, and each session
 -could be directed to a different host based on load balance across server
 -pool hosts at the time.
 -If load share is desired for just a few specific services, the configuration
 -on LSNAT could be defined to restrict load share for just the services
 +could be directed to a different host based on the load balance across server
 +pool hosts when the sessions are initiated.
 +If load sharing is desired for just a few specific services, the configuration
 +on LSNAT could be defined to restrict load sharing to just the services
  desired.
  .Pp
  Currently, only the simplest selection algorithm is implemented, where a
 @@ -596,8 +594,8 @@ The parameter
  is the pointer returned by either of the redirection functions.
  If an invalid pointer is passed to
  .Fn LibAliasRedirectDelete ,
 -then a program crash or unpredictable operation could result, so it is
 -necessary to be careful using this function.
 +then a program crash or unpredictable operation could result, so
 +care is needed when using this function.
  .Ed
  .Pp
  .Ft int
 @@ -704,7 +702,7 @@ access, or to restrict access to certain
  .Bd -ragged -offset indent
  This function specifies that any IP packet with protocol number of
  .Fa proto
 -from a given remote address to an alias address be
 +from a given remote address to an alias address will be
  redirected to a specified local address.
  .Pp
  If
 @@ -1099,9 +1097,9 @@ SLIST_HEAD(dll_chain, dll) dll_chain ...
  .Ed
  .Pp
  .Va handler_chain
 -keep tracks of all the protocol handlers loaded, while
 +keeps track of all the protocol handlers loaded, while
  .Va ddl_chain
 -takes care of userland modules loaded.
 +tracks which userland modules are loaded.
  .Pp
  .Va handler_chain
  is composed of
 @@ -1123,12 +1121,12 @@ struct proto_handler {
  where:
  .Bl -inset
  .It Va pri
 -is the priority assigned to a protocol handler, lower
 +is the priority assigned to a protocol handler; lower priority
  is better.
  .It Va dir
  is the direction of packets: ingoing or outgoing.
  .It Va proto
 -says at which protocol this packet belongs: IP, TCP or UDP.
 +indicates to which protocol this packet belongs: IP, TCP or UDP.
  .It Va fingerprint
  points to the fingerprint function while protohandler points
  to the protocol handler function.
 @@ -1136,8 +1134,8 @@ to the protocol handler function.
  .Pp
  The
  .Va fingerprint
 -function has the double of scope of checking if the
 -incoming packet is found and if it belongs to any categories that this
 +function has the dual role of checking if the
 +incoming packet is found, and if it belongs to any categories that this
  module can handle.
  .Pp
  The
 @@ -1152,8 +1150,8 @@ When a packet enters
  if it meets a module hook,
  .Va handler_chain
  is searched to see if there is an handler that matches
 -this type of a packet (it checks protocol and direction of packet), then if
 -more than one handler is found, it starts with the module with
 +this type of a packet (it checks protocol and direction of packet).
 +Then, if more than one handler is found, it starts with the module with
  the lowest priority number: it calls the
  .Va fingerprint
  function and interprets the result.
 @@ -1191,8 +1189,8 @@ structure, then
  is called.
  The
  .Fn find_handler
 -function is responsible for walking out the handler
 -chain, it receives as input parameters:
 +function is responsible for walking the handler
 +chain; it receives as input parameters:
  .Bl -tag -width indent
  .It Fa IN
  direction
 @@ -1216,9 +1214,9 @@ supporting INcoming UDP packets.
  .Pp
  As was mentioned earlier,
  .Nm
 -in userland is a bit different, cause
 -care has to be taken of module handling too (avoiding duplicate load of
 -module, avoiding module with same name, etc.) so
 +in userland is a bit different, as
 +care must be taken in module handling as well (avoiding duplicate load of
 +modules, avoiding modules with same name, etc.) so
  .Va dll_chain
  was introduced.
  .Pp
 @@ -1232,9 +1230,8 @@ When an application calls
  .Nm
  first unloads all the loaded modules, then reloads all the modules listed in
  .Pa /etc/libalias.conf :
 -for every module loaded, a new entry to
 -.Va dll_chain
 -is added.
 +for every module loaded, a new entry is added to
 +.Va dll_chain .
  .Pp
  .Va dll_chain
  is composed of
 @@ -1271,8 +1268,8 @@ There is a module (called
  .Pa alias_dummy.[ch] )
  in
  .Nm
 -that can be used as a skeleton for future work, here we analyse some parts of that
 -module.
 +that can be used as a skeleton for future work.
 +Here we analyse some parts of that module.
  From
  .Pa alias_dummy.c :
  .Bd -literal
 @@ -1285,7 +1282,7 @@ The variable
  is the
  .Dq "most important thing"
  in a module
 -cause it describes the handlers present and lets the outside world use
 +since it describes the handlers present and lets the outside world use
  it in an opaque way.
  .Pp
  It must ALWAYS be present in every module, and it MUST retain
 @@ -1328,7 +1325,7 @@ mod_handler(module_t mod, int type, void
  .Ed
  When running as KLD,
  .Fn mod_handler
 -register/deregister the module using
 +registers/deregisters the module using
  .Fn attach_handlers
  and
  .Fn detach_handlers ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/158623: commit references a PR
Date: Tue, 26 Jul 2011 19:06:15 +0000 (UTC)

 Author: gjb (doc committer)
 Date: Tue Jul 26 19:05:59 2011
 New Revision: 224460
 URL: http://svn.freebsd.org/changeset/base/224460
 
 Log:
   MFC 223773:
   
   - General grammar and mdoc(7) fixes.
   - While here, remove a paragraph about userspace operation
     that has been outdated for some time.
   
   PR:		158623
 
 Modified:
   stable/7/sys/netinet/libalias/libalias.3
 Directory Properties:
   stable/7/sys/   (props changed)
   stable/7/sys/cddl/contrib/opensolaris/   (props changed)
   stable/7/sys/contrib/dev/acpica/   (props changed)
   stable/7/sys/contrib/pf/   (props changed)
 
 Modified: stable/7/sys/netinet/libalias/libalias.3
 ==============================================================================
 --- stable/7/sys/netinet/libalias/libalias.3	Tue Jul 26 19:05:10 2011	(r224459)
 +++ stable/7/sys/netinet/libalias/libalias.3	Tue Jul 26 19:05:59 2011	(r224460)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd October 1, 2006
 +.Dd July 04, 2011
  .Dt LIBALIAS 3
  .Os
  .Sh NAME
 @@ -52,7 +52,7 @@ machine on the local network.
  .Pp
  A certain amount of flexibility is built into the packet aliasing engine.
  In the simplest mode of operation, a many-to-one address mapping takes
 -place between local network and the packet aliasing host.
 +place between the local network and the packet aliasing host.
  This is known as IP masquerading.
  In addition, one-to-one mappings between local and public addresses can
  also be implemented, which is known as static NAT.
 @@ -61,15 +61,11 @@ linked to different public addresses, co
  many-to-one mappings.
  Also, a given public address and port can be statically redirected to a
  private address/port.
 -.Pp
 -The packet aliasing engine was designed to operate in user space outside
 -of the kernel, without any access to private kernel data structure, but
 -the source code can also be ported to a kernel environment.
  .Sh INITIALIZATION AND CONTROL
  One special function,
  .Fn LibAliasInit ,
 -must always be called before any packet handling may be performed and
 -the returned instance pointer passed to all the other functions.
 +must always be called before any packet handling may be performed, and
 +the returned instance pointer must be passed to all the other functions.
  Normally, the
  .Fn LibAliasSetAddress
  function is called afterwards, to set the default aliasing address.
 @@ -118,8 +114,8 @@ prior to any packet handling.
  This function has no return value and is used to clear any
  resources attached to internal data structures.
  .Pp
 -This functions should be called when a program stops using the aliasing
 -engine; it does, amongst other things, clear out any firewall holes.
 +This function should be called when a program stops using the aliasing
 +engine; amongst other things, it clears out any firewall holes.
  To provide backwards compatibility and extra security, it is added to
  the
  .Xr atexit 3
 @@ -135,7 +131,7 @@ local area network are aliased.
  All outgoing packets are re-mapped to this address unless overridden by a
  static address mapping established by
  .Fn LibAliasRedirectAddr .
 -If this function is not called, and no static rules match, an outgoing
 +If this function has not been called, and no static rules match, an outgoing
  packet retains its source address.
  .Pp
  If the
 @@ -150,7 +146,7 @@ address may or may not change on success
  If the
  .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
  mode bit is set to zero, this function can also be used to dynamically change
 -the aliasing address on a packet to packet basis (it is a low overhead call).
 +the aliasing address on a packet-to-packet basis (it is a low overhead call).
  .Pp
  It is mandatory that this function be called prior to any packet handling.
  .Ed
 @@ -170,7 +166,7 @@ The following mode bits are defined in
  .It Dv PKT_ALIAS_LOG
  Enables logging into
  .Pa /var/log/alias.log .
 -Each time an aliasing link is created or deleted, the log file is appended
 +Each time an aliasing link is created or deleted, the log file is appended to
  with the current number of ICMP, TCP and UDP links.
  Mainly useful for debugging when the log file is viewed continuously with
  .Xr tail 1 .
 @@ -186,7 +182,7 @@ Response packets to connections or trans
  aliasing host or local network will be unaffected.
  This mode bit is useful for implementing a one-way firewall.
  .It Dv PKT_ALIAS_SAME_PORTS
 -If this mode bit is set, the packet aliasing engine will attempt to leave
 +If this mode bit is set, the packet-aliasing engine will attempt to leave
  the alias port numbers unchanged from the actual local port numbers.
  This can be done as long as the quintuple (proto, alias addr, alias port,
  remote addr, remote port) is unique.
 @@ -211,7 +207,7 @@ Standard Class A, B and C unregistered a
  192.168.0.0  ->  192.168.255.255  (Class C subnets)
  .Ed
  .Pp
 -This option is useful in the case that packet aliasing host has both
 +This option is useful in the case that the packet aliasing host has both
  registered and unregistered subnets on different interfaces.
  The registered subnet is fully accessible to the outside world, so traffic
  from it does not need to be passed through the packet aliasing engine.
 @@ -229,8 +225,9 @@ of an address change.
  .It Dv PKT_ALIAS_PUNCH_FW
  This option makes
  .Nm
 -`punch holes' in an
 -.Xr ipfirewall 4
 +.Dq punch holes
 +in an
 +.Xr ipfirewall 4 -
  based firewall for FTP/IRC DCC connections.
  The holes punched are bound by from/to IP address and port; it will not be
  possible to use a hole for another connection.
 @@ -240,9 +237,9 @@ To cater to unexpected death of a progra
  (e.g.\& kill -9),
  changing the state of the flag will clear the entire firewall range
  allocated for holes.
 -This will also happen on the initial call to
 -.Fn LibAliasSetFWBase .
 -This call must happen prior to setting this flag.
 +This clearing will also happen on the initial call to
 +.Fn LibAliasSetFWBase ,
 +which must happen prior to setting this flag.
  .It Dv PKT_ALIAS_REVERSE
  This option makes
  .Nm
 @@ -263,10 +260,10 @@ below for details.
  .Ft void
  .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
  .Bd -ragged -offset indent
 -Set firewall range allocated for punching firewall holes (with the
 +Set the firewall range allocated for punching firewall holes (with the
  .Dv PKT_ALIAS_PUNCH_FW
  flag).
 -The range will be cleared for all rules on initialization.
 +The range is cleared for all rules on initialization.
  .Ed
  .Pp
  .Ft void
 @@ -292,7 +289,7 @@ the two packet handling functions,
  .Fn LibAliasIn
  and
  .Fn LibAliasOut ,
 -comprise minimal set of functions needed for a basic IP masquerading
 +comprise the minimal set of functions needed for a basic IP masquerading
  implementation.
  .Pp
  .Ft int
 @@ -313,11 +310,11 @@ Return codes:
  The packet aliasing process was successful.
  .It Dv PKT_ALIAS_IGNORED
  The packet was ignored and not de-aliased.
 -This can happen if the protocol is unrecognized, possibly an ICMP message
 -type is not handled or if incoming packets for new connections are being
 -ignored (if
 +This can happen if the protocol is unrecognized, as for an ICMP message
 +type that is not handled, or if incoming packets for new connections are being
 +ignored (if the
  .Dv PKT_ALIAS_DENY_INCOMING
 -mode bit was set by
 +mode bit was set using
  .Fn LibAliasSetMode ) .
  .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
  This is returned when a fragment cannot be resolved because the header
 @@ -408,7 +405,7 @@ is called to change the address after
  .Fn LibAliasRedirectPort
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then
  .Fa local_addr
  and
  .Fa local_port
 @@ -423,7 +420,7 @@ Likewise, if
  .Fa remote_port
  is zero, this indicates to redirect packets originating from any remote
  port number.
 -Almost always, the remote port specification will be zero, but non-zero
 +The remote port specification will almost always be zero, but non-zero
  remote addresses can sometimes be useful for firewalling.
  If two calls to
  .Fn LibAliasRedirectPort
 @@ -475,9 +472,10 @@ is called to change the address after
  .Fn LibAliasRedirectAddr
  is called, a zero reference will track this change.
  .Pp
 -If the link is further set up to operate for a load sharing, then
 +If the link is further set up to operate with load sharing, then the
  .Fa local_addr
 -is ignored, and is selected dynamically from the server pool, as described in
 +argument is ignored, and is selected dynamically from the server pool,
 +as described in
  .Fn LibAliasAddServer
  below.
  .Pp
 @@ -532,12 +530,12 @@ up for Load Sharing using IP Network Add
  LSNAT operates as follows.
  A client attempts to access a server by using the server virtual address.
  The LSNAT router transparently redirects the request to one of the hosts
 -in server pool, selected using a real-time load sharing algorithm.
 +in the server pool, using a real-time load sharing algorithm.
  Multiple sessions may be initiated from the same client, and each session
 -could be directed to a different host based on load balance across server
 -pool hosts at the time.
 -If load share is desired for just a few specific services, the configuration
 -on LSNAT could be defined to restrict load share for just the services
 +could be directed to a different host based on the load balance across server
 +pool hosts when the sessions are initiated.
 +If load sharing is desired for just a few specific services, the configuration
 +on LSNAT could be defined to restrict load sharing to just the services
  desired.
  .Pp
  Currently, only the simplest selection algorithm is implemented, where a
 @@ -596,8 +594,8 @@ The parameter
  is the pointer returned by either of the redirection functions.
  If an invalid pointer is passed to
  .Fn LibAliasRedirectDelete ,
 -then a program crash or unpredictable operation could result, so it is
 -necessary to be careful using this function.
 +then a program crash or unpredictable operation could result, so
 +care is needed when using this function.
  .Ed
  .Pp
  .Ft int
 @@ -704,7 +702,7 @@ access, or to restrict access to certain
  .Bd -ragged -offset indent
  This function specifies that any IP packet with protocol number of
  .Fa proto
 -from a given remote address to an alias address be
 +from a given remote address to an alias address will be
  redirected to a specified local address.
  .Pp
  If
 @@ -1099,9 +1097,9 @@ SLIST_HEAD(dll_chain, dll) dll_chain ...
  .Ed
  .Pp
  .Va handler_chain
 -keep tracks of all the protocol handlers loaded, while
 +keeps track of all the protocol handlers loaded, while
  .Va ddl_chain
 -takes care of userland modules loaded.
 +tracks which userland modules are loaded.
  .Pp
  .Va handler_chain
  is composed of
 @@ -1123,12 +1121,12 @@ struct proto_handler {
  where:
  .Bl -inset
  .It Va pri
 -is the priority assigned to a protocol handler, lower
 +is the priority assigned to a protocol handler; lower priority
  is better.
  .It Va dir
  is the direction of packets: ingoing or outgoing.
  .It Va proto
 -says at which protocol this packet belongs: IP, TCP or UDP.
 +indicates to which protocol this packet belongs: IP, TCP or UDP.
  .It Va fingerprint
  points to the fingerprint function while protohandler points
  to the protocol handler function.
 @@ -1136,8 +1134,8 @@ to the protocol handler function.
  .Pp
  The
  .Va fingerprint
 -function has the double of scope of checking if the
 -incoming packet is found and if it belongs to any categories that this
 +function has the dual role of checking if the
 +incoming packet is found, and if it belongs to any categories that this
  module can handle.
  .Pp
  The
 @@ -1152,8 +1150,8 @@ When a packet enters
  if it meets a module hook,
  .Va handler_chain
  is searched to see if there is an handler that matches
 -this type of a packet (it checks protocol and direction of packet), then if
 -more than one handler is found, it starts with the module with
 +this type of a packet (it checks protocol and direction of packet).
 +Then, if more than one handler is found, it starts with the module with
  the lowest priority number: it calls the
  .Va fingerprint
  function and interprets the result.
 @@ -1191,8 +1189,8 @@ structure, then
  is called.
  The
  .Fn find_handler
 -function is responsible for walking out the handler
 -chain, it receives as input parameters:
 +function is responsible for walking the handler
 +chain; it receives as input parameters:
  .Bl -tag -width indent
  .It Fa IN
  direction
 @@ -1216,9 +1214,9 @@ supporting INcoming UDP packets.
  .Pp
  As was mentioned earlier,
  .Nm
 -in userland is a bit different, cause
 -care has to be taken of module handling too (avoiding duplicate load of
 -module, avoiding module with same name, etc.) so
 +in userland is a bit different, as
 +care must be taken in module handling as well (avoiding duplicate load of
 +modules, avoiding modules with same name, etc.) so
  .Va dll_chain
  was introduced.
  .Pp
 @@ -1232,9 +1230,8 @@ When an application calls
  .Nm
  first unloads all the loaded modules, then reloads all the modules listed in
  .Pa /etc/libalias.conf :
 -for every module loaded, a new entry to
 -.Va dll_chain
 -is added.
 +for every module loaded, a new entry is added to
 +.Va dll_chain .
  .Pp
  .Va dll_chain
  is composed of
 @@ -1271,8 +1268,8 @@ There is a module (called
  .Pa alias_dummy.[ch] )
  in
  .Nm
 -that can be used as a skeleton for future work, here we analyse some parts of that
 -module.
 +that can be used as a skeleton for future work.
 +Here we analyse some parts of that module.
  From
  .Pa alias_dummy.c :
  .Bd -literal
 @@ -1285,7 +1282,7 @@ The variable
  is the
  .Dq "most important thing"
  in a module
 -cause it describes the handlers present and lets the outside world use
 +since it describes the handlers present and lets the outside world use
  it in an opaque way.
  .Pp
  It must ALWAYS be present in every module, and it MUST retain
 @@ -1328,7 +1325,7 @@ mod_handler(module_t mod, int type, void
  .Ed
  When running as KLD,
  .Fn mod_handler
 -register/deregister the module using
 +registers/deregisters the module using
  .Fn attach_handlers
  and
  .Fn detach_handlers ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
