diff options
Diffstat (limited to 'lib/kernel/doc')
| -rw-r--r-- | lib/kernel/doc/src/Makefile | 22 | ||||
| -rw-r--r-- | lib/kernel/doc/src/code.xml | 13 | ||||
| -rw-r--r-- | lib/kernel/doc/src/erl_ddll.xml | 159 | ||||
| -rw-r--r-- | lib/kernel/doc/src/error_logger.xml | 5 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 6 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_sctp.xml | 41 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_tcp.xml | 57 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_udp.xml | 57 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 85 | ||||
| -rw-r--r-- | lib/kernel/doc/src/os.xml | 43 |
10 files changed, 285 insertions, 203 deletions
diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile index 214e994889..78e5f7bc26 100644 --- a/lib/kernel/doc/src/Makefile +++ b/lib/kernel/doc/src/Makefile @@ -155,18 +155,18 @@ $(SPECDIR)/specs_zlib_stub.xml: include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs - $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf - $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf - $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(HTMLDIR)/* \ - $(RELSYSDIR)/doc/html - $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) - $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 - $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 - $(INSTALL_DIR) $(RELEASE_PATH)/man/man4 - $(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4 - $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 - $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6 + "$(RELSYSDIR)/doc/html" + $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" + $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man4" + $(INSTALL_DATA) $(MAN4_FILES) "$(RELEASE_PATH)/man/man4" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man6" + $(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6" release_spec: diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index ee687511a3..bb111a2242 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -728,16 +728,13 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), </desc> </func> <func> - <name>is_module_native(Module) -> boolean() | undefined</name> + <name name="is_module_native" arity="1"/> <fsummary>Test whether a module has native code</fsummary> - <type> - <v>Module = module()</v> - </type> <desc> - <p>This function returns <c>true</c> if <c>Module</c> is + <p>This function returns <c>true</c> if <c><anno>Module</anno></c> is name of a loaded module that has native code loaded, and - <c>false</c> if <c>Module</c> is loaded but does not have - native. If <c>Module</c> is not loaded, this function returns + <c>false</c> if <c><anno>Module</anno></c> is loaded but does not have + native. If <c><anno>Module</anno></c> is not loaded, this function returns <c>undefined</c>.</p> </desc> </func> diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml index 1911fb628e..26db11cfcd 100644 --- a/lib/kernel/doc/src/erl_ddll.xml +++ b/lib/kernel/doc/src/erl_ddll.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2011</year> + <year>1997</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -182,11 +182,8 @@ </datatypes> <funcs> <func> - <name>demonitor(MonitorRef) -> ok</name> + <name name="demonitor" arity="1"/> <fsummary>Remove a monitor for a driver</fsummary> - <type> - <v>MonitorRef = reference()</v> - </type> <desc> <p>Removes a driver monitor in much the same way as <seealso marker="erts:erlang#erlang:demonitor/1">erlang:demonitor/1</seealso> does with process @@ -232,24 +229,19 @@ </desc> </func> <func> - <name>info(Name, Tag) -> Value</name> + <name name="info" arity="2"/> <fsummary>Retrieve specific information about one driver</fsummary> - <type> - <v>Name = string() | atom()</v> - <v>Tag = processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload</v> - <v>Value = term()</v> - </type> <desc> <p>This function returns specific information about one aspect - of a driver. The <c>Tag</c> parameter specifies which aspect - to get information about. The <c>Value</c> return differs + of a driver. The <c><anno>Tag</anno></c> parameter specifies which aspect + to get information about. The <c><anno>Value</anno></c> return differs between different tags:</p> <taglist> <tag><em>processes</em></tag> <item> <p>Return all processes containing <seealso marker="#users">users</seealso> of the specific drivers - as a list of tuples <c>{pid(),int()}</c>, where the - <c>int()</c> denotes the number of users in the process + as a list of tuples <c>{pid(),integer() >= 0}</c>, where the + <c>integer()</c> denotes the number of users in the process <c>pid()</c>.</p> </item> <tag><em>driver_options</em></tag> @@ -261,16 +253,16 @@ </item> <tag><em>port_count</em></tag> <item> - <p>Return the number of ports (an <c>int()</c>) using the driver.</p> + <p>Return the number of ports (an <c>integer >= 0()</c>) using the driver.</p> </item> <tag><em>linked_in_driver</em></tag> <item> - <p>Return a <c>bool()</c>, being <c>true</c> if the driver is a + <p>Return a <c>boolean()</c>, being <c>true</c> if the driver is a statically linked in one and <c>false</c> otherwise.</p> </item> <tag><em>permanent</em></tag> <item> - <p>Return a <c>bool()</c>, being <c>true</c> if the driver has made + <p>Return a <c>boolean()</c>, being <c>true</c> if the driver has made itself permanent (and is <em>not</em> a statically linked in driver). <c>false</c> otherwise.</p> </item> @@ -278,14 +270,14 @@ <item> <p>Return a list of all processes having monitors for <c>loading</c> active, each process returned as - <c>{pid(),int()}</c>, where the <c>int()</c> is the + <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the number of monitors held by the process <c>pid()</c>.</p> </item> <tag><em>awaiting_unload</em></tag> <item> <p>Return a list of all processes having monitors for <c>unloading</c> active, each process returned as - <c>{pid(),int()}</c>, where the <c>int()</c> is the + <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the number of monitors held by the process <c>pid()</c>.</p> </item> </taglist> @@ -377,41 +369,34 @@ </desc> </func> <func> - <name>monitor(Tag, Item) -> MonitorRef</name> + <name name="monitor" arity="2"/> <fsummary>Create a monitor for a driver</fsummary> - <type> - <v>Tag = driver </v> - <v>Item = {Name, When}</v> - <v>Name = atom() | string()</v> - <v>When = loaded | unloaded | unloaded_only</v> - <v>MonitorRef = reference()</v> - </type> <desc> <p>This function creates a driver monitor and works in many ways as the function <seealso marker="erts:erlang#erlang:monitor/2">erlang:monitor/2</seealso>, does for processes. When a driver changes state, the monitor results in a monitor-message being sent to the calling - process. The <c>MonitorRef</c> returned by this function is + process. The <c><anno>MonitorRef</anno></c> returned by this function is included in the message sent.</p> <p>As with process monitors, each driver monitor set will only generate <em>one single message</em>. The monitor is "destroyed" after the message is sent and there is then no need to call <seealso marker="#demonitor/1">demonitor/1</seealso>.</p> - <p>The <c>MonitorRef</c> can also be used in subsequent calls + <p>The <c><anno>MonitorRef</anno></c> can also be used in subsequent calls to <seealso marker="#demonitor/1">demonitor/1</seealso> to remove a monitor.</p> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Tag</em></tag> + <tag><em><anno>Tag</anno></em></tag> <item> <p>The monitor tag is always <c>driver</c> as this function can only be used to create driver monitors. In the future, driver monitors will be integrated with process monitors, why this parameter has to be given for consistence.</p> </item> - <tag><em>Item</em></tag> + <tag><em><anno>Item</anno></em></tag> <item> - <p>The <c>Item</c> parameter specifies which driver one + <p>The <c><anno>Item</anno></c> parameter specifies which driver one wants to monitor (the name of the driver) as well as which state change one wants to monitor. The parameter is a tuple of arity two whose first element is the @@ -588,22 +573,8 @@ </desc> </func> <func> - <name>try_load(Path, Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc}</name> + <name name="try_load" arity="3"/> <fsummary>Load a driver</fsummary> - <type> - <v>Path = Name = string() | atom()</v> - <v>OptionList = [ Option ]</v> - <v>Option = {driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption}</v> - <v>DriverOptionList = [ DriverOption ]</v> - <v>DriverOption = kill_ports</v> - <v>MonitorOption = pending_driver | pending</v> - <v>ReloadOption = pending_driver | pending</v> - <v>Status = loaded | already_loaded | PendingStatus </v> - <v>PendingStatus = pending_driver | pending_process</v> - <v>Ref = reference()</v> - <v>ErrorDesc = ErrorAtom | OpaqueError</v> - <v>ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process</v> - </type> <desc> <p>This function provides more control than the <c>load/2</c>/<c>reload/2</c> and @@ -655,65 +626,65 @@ <p>When the function returns <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>, one might want to get information about when the driver is <em>actually</em> loaded. This can - be achieved by using the <c>{monitor, PendingOption}</c> option.</p> + be achieved by using the <c>{monitor, <anno>MonitorOption</anno>}</c> option.</p> <p>When monitoring is requested, and a corresponding <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would be - returned, the function will instead return a tuple <c>{ok, PendingStatus, reference()}</c> and the process will, at a later + returned, the function will instead return a tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c> and the process will, at a later time when the driver actually gets loaded, get a monitor message. The monitor message one can expect is described in the <seealso marker="#monitor/2">monitor/2</seealso> function description. </p> <note> <p>Note that in case of loading, monitoring can - <em>not</em> only get triggered by using the <c>{reload, ReloadOption}</c> option, but also in special cases where + <em>not</em> only get triggered by using the <c>{reload, <anno>ReloadOption</anno>}</c> option, but also in special cases where the load-error is transient, why <c>{monitor, pending_driver}</c> should be used under basically <em>all</em> real world circumstances!</p> </note> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Path</em></tag> + <tag><em><anno>Path</anno></em></tag> <item> <p>The filesystem path to the directory where the driver object file is situated. The filename of the object file (minus extension) must correspond to the driver name (used in the name parameter) and the driver must identify itself with the very same name. The - <c>Path</c> might be provided as an <em>io_list</em>, - meaning it can be a list of other io_lists, characters + <c><anno>Path</anno></c> might be provided as an <em>iolist()</em>, + meaning it can be a list of other <c>iolist()</c>s, characters (eight bit integers) or binaries, all to be flattened into a sequence of characters.</p> - <p>The (possibly flattened) <c>Path</c> parameter must be + <p>The (possibly flattened) <c><anno>Path</anno></c> parameter must be consistent throughout the system, a driver should, by all <seealso marker="#users">users</seealso>, be loaded - using the same <em>literal</em><c>Path</c>. The + using the same <em>literal</em><c><anno>Path</anno></c>. The exception is when <em>reloading</em> is requested, in - which case the <c>Path</c> may be specified + which case the <c><anno>Path</anno></c> may be specified differently. Note that all <seealso marker="#users">users</seealso> trying to load the - driver at a later time will need to use the <em>new</em><c>Path</c> if the <c>Path</c> is changed using a + driver at a later time will need to use the <em>new</em><c><anno>Path</anno></c> if the <c><anno>Path</anno></c> is changed using a <c>reload</c> option. This is yet another reason to have <em>only one loader</em> of a driver one wants to upgrade in a running system! </p> </item> - <tag><em>Name</em></tag> + <tag><em><anno>Name</anno></em></tag> <item> <p>The name parameter is the name of the driver to be used in subsequent calls to <seealso marker="erts:erlang#open_port/2">open_port</seealso>. The - name can be specified either as an <c>io_list()</c> or + name can be specified either as an <c>iolist()</c> or as an <c>atom()</c>. The name given when loading is used to find the actual object file (with the - help of the <c>Path</c> and the system implied + help of the <c><anno>Path</anno></c> and the system implied extension suffix, i.e. <c>.so</c>). The name by which the driver identifies itself must also be consistent - with this <c>Name</c> parameter, much as a beam-file's + with this <c><anno>Name</anno></c> parameter, much as a beam-file's module name much correspond to its filename.</p> </item> - <tag><em>OptionList</em></tag> + <tag><em><anno>OptionList</anno></em></tag> <item> <p>A number of options can be specified to control the loading operation. The options are given as a list of two-tuples, the tuples having the following values and meanings:</p> <taglist> - <tag><em>{driver_options, DriverOptionsList}</em></tag> + <tag><em>{driver_options, <anno>DriverOptionList</anno>}</em></tag> <item> <p>This option is to provide options that will change its general behavior and will "stick" to the driver @@ -729,14 +700,14 @@ when the last <seealso marker="#users">user</seealso> calls <seealso marker="#try_unload/2">try_unload/2</seealso>, or the last process having loaded the driver exits.</p> </item> - <tag><em>{monitor, MonitorOption}</em></tag> + <tag><em>{monitor, <anno>MonitorOption</anno>}</em></tag> <item> - <p>A <c>MonitorOption</c> tells <c>try_load/3</c> to + <p>A <c><anno>MonitorOption</anno></c> tells <c>try_load/3</c> to trigger a driver monitor under certain conditions. When the monitor is triggered, the - function will return a three-tuple <c>{ok, PendingStatus, reference()}</c>, where the <c>reference()</c> is + function will return a three-tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c>, where the <c>reference()</c> is the monitor ref for the driver monitor.</p> - <p>Only one <c>MonitorOption</c> can be specified and + <p>Only one <c><anno>MonitorOption</anno></c> can be specified and it is either the atom <c>pending</c>, which means that a monitor should be created whenever a load operation is delayed, and the atom @@ -747,7 +718,7 @@ is present for completeness, it is very well defined which reload-options might give rise to which delays. It might, however, be a good idea to use the - same <c>MonitorOption</c> as the <c>ReloadOption</c> + same <c><anno>MonitorOption</anno></c> as the <c><anno>ReloadOption</anno></c> if present.</p> <p>If reloading is not requested, it might still be useful to specify the <c>monitor</c> option, as @@ -760,12 +731,12 @@ <c>{monitor, pending_driver}</c> in production code (see the monitor discussion above). </p> </item> - <tag><em>{reload,RealoadOption}</em></tag> + <tag><em>{reload,<anno>ReloadOption</anno>}</em></tag> <item> <p>This option is used when one wants to <em>reload</em> a driver from disk, most often in a code upgrade scenario. Having a <c>reload</c> option - also implies that the <c>Path</c> parameter need + also implies that the <c><anno>Path</anno></c> parameter need <em>not</em> be consistent with earlier loads of the driver.</p> <p>To reload a driver, the process needs to have previously @@ -814,9 +785,9 @@ <tag><em>{error,inconsistent}</em></tag> <item> <p>The driver has already been loaded with either other - <c>DriverOptions</c> or a different <em>literal</em><c>Path</c> argument.</p> + <c><anno>DriverOptionList</anno></c> or a different <em>literal</em><c>Path</c> argument.</p> <p>This can happen even if a <c>reload</c> option is given, - if the <c>DriverOptions</c> differ from the current.</p> + if the <c>DriverOptionList</c> differ from the current.</p> </item> <tag><em>{error, permanent}</em></tag> <item> @@ -830,19 +801,19 @@ </item> <tag><em>{error, pending_reload}</em></tag> <item> - <p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, ReloadOption}</c> option was given.</p> + <p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, <anno>ReloadOption</anno>}</c> option was given.</p> </item> <tag><em>{error, not_loaded_by_this_process}</em></tag> <item> <p>Appears when the <c>reload</c> option is given. The - driver <c>Name</c> is present in the system, but there is no + driver <c><anno>Name</anno></c> is present in the system, but there is no <seealso marker="#users">user</seealso> of it in this process.</p> </item> <tag><em>{error, not_loaded}</em></tag> <item> <p>Appears when the <c>reload</c> option is given. The - driver <c>Name</c> is not in the system. Only drivers + driver <c><anno>Name</anno></c> is not in the system. Only drivers loaded by this process can be reloaded.</p> </item> </taglist> @@ -856,18 +827,8 @@ </desc> </func> <func> - <name>try_unload(Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom}</name> + <name name="try_unload" arity="2"/> <fsummary>Unload a driver</fsummary> - <type> - <v>Name = string() | atom()</v> - <v>OptionList = [ Option ]</v> - <v>Option = {monitor, MonitorOption} | kill_ports</v> - <v>MonitorOption = pending_driver | pending</v> - <v>Status = unloaded | PendingStatus </v> - <v>PendingStatus = pending_driver | pending_process</v> - <v>Ref = reference()</v> - <v>ErrorAtom = linked_in_driver | not_loaded | not_loaded_by_this_process | permanent</v> - </type> <desc> <p>This is the low level function to unload (or decrement reference counts of) a driver. It can be used to force port @@ -948,15 +909,15 @@ </taglist> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Name</em></tag> + <tag><em><anno>Name</anno></em></tag> <item> <p>The name parameter is the name of the driver to be unloaded. The name can be specified either as an - <c>io_list()</c> or as an <c>atom()</c>. </p> + <c>iolist()</c> or as an <c>atom()</c>. </p> </item> - <tag><em>OptionList</em></tag> + <tag><em><anno>OptionList</anno></em></tag> <item> - <p>The <c>OptionList</c> argument can be used to specify + <p>The <c><anno>OptionList</anno></c> argument can be used to specify certain behavior regarding ports as well as triggering monitors under certain conditions:</p> <taglist> @@ -972,10 +933,10 @@ unloads, one should use the driver option <c>kill_ports</c> when loading the driver instead.</p> </item> - <tag><em>{monitor, MonitorOption}</em></tag> + <tag><em>{monitor, <anno>MonitorOption</anno>}</em></tag> <item> <p>This option creates a driver monitor if the condition - given in <c>MonitorOptions</c> is true. The valid + given in <c><anno>MonitorOption</anno></c> is true. The valid options are:</p> <taglist> <tag><em>pending_driver</em></tag> @@ -989,7 +950,7 @@ <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>.</p> </item> </taglist> - <p>The <c>pending_driver</c> <c>MonitorOption</c> is by far + <p>The <c>pending_driver</c> <c><anno>MonitorOption</anno></c> is by far the most useful and it has to be used to ensure that the driver has really been unloaded and the ports closed whenever the <c>kill_ports</c> option is used or the @@ -1016,11 +977,11 @@ </item> <tag><em>{error, not_loaded}</em></tag> <item> - <p>The driver <c>Name</c> is not present in the system.</p> + <p>The driver <c><anno>Name</anno></c> is not present in the system.</p> </item> <tag><em>{error, not_loaded_by_this_process}</em></tag> <item> - <p>The driver <c>Name</c> is present in the system, but + <p>The driver <c><anno>Name</anno></c> is present in the system, but there is no <seealso marker="#users">user</seealso> of it in this process. </p> <p>As a special case, drivers can be unloaded from @@ -1088,12 +1049,8 @@ </desc> </func> <func> - <name>loaded_drivers() -> {ok, Drivers}</name> + <name name="loaded_drivers" arity="0"/> <fsummary>List loaded drivers</fsummary> - <type> - <v>Drivers = [Driver]</v> - <v>Driver = string()</v> - </type> <desc> <p>Returns a list of all the available drivers, both (statically) linked-in and dynamically loaded ones.</p> diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index ec3274965a..cd86b364f6 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -127,11 +127,8 @@ ok</pre> </desc> </func> <func> - <name>warning_map() -> Tag</name> + <name name="warning_map" arity="0"/> <fsummary>Return the current mapping for warning events</fsummary> - <type> - <v>Tag = error | warning | info</v> - </type> <desc> <p>Returns the current mapping for warning events. Events sent using <c>warning_msg/1,2</c> or <c>warning_report/1,2</c> diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 772eff13cc..b2a259080d 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -412,7 +412,7 @@ </desc> </func> <func> - <name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name> + <name name="file_info" arity="1"/> <fsummary>Get information about a file (deprecated)</fsummary> <desc> <p>This function is obsolete. Use <c>read_file_info/1,2</c> @@ -598,7 +598,7 @@ </desc> </func> <func> - <name>native_name_encoding() -> latin1 | utf8</name> + <name name="native_name_encoding" arity="0"/> <fsummary>Return the VM's configured filename encoding.</fsummary> <desc> <p>This function returns the configured default file name encoding to use for raw file names. Generally an application supplying file names raw (as binaries), should obey the character encoding returned by this function.</p> diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml index 579b7f1f74..e327a4f907 100644 --- a/lib/kernel/doc/src/gen_sctp.xml +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -123,7 +123,7 @@ <p>Completely closes the socket and all associations on it. The unsent data is flushed as in <c>eof/2</c>. The <c>close/1</c> call is blocking or otherwise depending of the value of - the <seealso marker="#option-linger">linger</seealso> socket + the <seealso marker="inet#option-linger">linger</seealso> socket <seealso marker="#options">option</seealso>. If <c>close</c> does not linger or linger timeout expires, the call returns and the data is flushed in the background.</p> @@ -309,8 +309,8 @@ <seealso marker="#option-active">passive</seealso> mode, with <anno>SockType</anno> <c>seqpacket</c>, and with reasonably large - <seealso marker="#option-sndbuf">kernel</seealso> and driver - <seealso marker="#option-buffer">buffers.</seealso></p> + <seealso marker="inet#option-sndbuf">kernel</seealso> and driver + <seealso marker="inet#option-buffer">buffers.</seealso></p> </desc> </func> <func> @@ -530,19 +530,8 @@ SCTP data interleaved with other inter-process messages.</p> </item> </list> - <marker id="option-buffer"></marker> </item> - <tag><c>{buffer, integer()}</c></tag> - <item> - <p>Determines the size of the user-level software buffer used by - the SCTP driver. Not to be confused with <c>sndbuf</c> - and <c>recbuf</c> options which correspond to - the kernel socket buffers. It is recommended - to have <c>val(buffer) >= max(val(sndbuf),val(recbuf))</c>. - In fact, the <c>val(buffer)</c> is automatically set to - the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p> - </item> - <tag><c>{tos, integer()}</c></tag> + <tag><c>{tos, integer()}</c></tag> <item> <p>Sets the Type-Of-Service field on the IP datagrams being sent, to the given value, which effectively determines a prioritization @@ -567,19 +556,8 @@ <c>{IP,Port}</c> of the socket can be re-used immediately: no waiting in the CLOSE_WAIT state is performed (may be required for high-throughput servers).</p> - <marker id="option-linger"></marker> - </item> - <tag><c>{linger, {true|false, integer()}</c></tag> - <item> - <p>Determines the timeout in seconds for flushing unsent data in the - <c>gen_sctp:close/1</c> socket call. If the 1st component of the value - tuple is <c>false</c>, the 2nd one is ignored, which means that - <c>gen_sctp:close/1</c> returns immediately not waiting - for data to be flushed. Otherwise, the 2nd component is - the flushing time-out in seconds.</p> - <marker id="option-sndbuf"></marker> </item> - <tag><c>{sndbuf, integer()}</c></tag> + <tag><c>{sndbuf, integer()}</c></tag> <item> <p>The size, in bytes, of the *kernel* send buffer for this socket. Sending errors would occur for datagrams larger than @@ -593,6 +571,15 @@ <c>val(sndbuf)</c>. Setting this option also adjusts the size of the driver buffer (see <c>buffer</c> above).</p> </item> + + <tag><c>{sctp_module, module()}</c></tag> + <item> <p> + Override which callback module is used. Defaults to + <c>inet_sctp</c> for IPv4 and <c>inet6_sctp</c> for IPv6. + </p> + </item> + + <tag><c>{sctp_rtoinfo, #sctp_rtoinfo{}}</c></tag> <item> <pre> #sctp_rtoinfo{ diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml index cf97607af1..11a0843c10 100644 --- a/lib/kernel/doc/src/gen_tcp.xml +++ b/lib/kernel/doc/src/gen_tcp.xml @@ -96,37 +96,47 @@ do_recv(Sock, Bs) -> can be either a hostname, or an IP address.</p> <p>The available options are:</p> <taglist> - <tag><c>list</c></tag> - <item> - <p>Received <c>Packet</c> is delivered as a list.</p> - </item> - <tag><c>binary</c></tag> - <item> - <p>Received <c>Packet</c> is delivered as a binary.</p> - </item> - <tag><c>{ip, ip_address()}</c></tag> + <tag><c>{ip, ip_address()}</c></tag> <item> <p>If the host has several network interfaces, this option specifies which one to use.</p> </item> - <tag><c>{port, Port}</c></tag> + + <tag><c>{ifaddr, ip_address()}</c></tag> <item> - <p>Specify which local port number to use.</p> - </item> + <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option + specifies which one to use.</p> + </item> + <tag><c>{fd, integer() >= 0}</c></tag> <item> <p>If a socket has somehow been connected without using <c>gen_tcp</c>, use this option to pass the file descriptor for it.</p> </item> - <tag><c>inet6</c></tag> + + <tag><c>inet</c></tag> <item> + <p>Set up the socket for IPv4.</p> + </item> + + <tag><c>inet6</c></tag> + <item> <p>Set up the socket for IPv6.</p> </item> - <tag><c>inet</c></tag> + + <tag><c>{port, Port}</c></tag> <item> - <p>Set up the socket for IPv4.</p> + <p>Specify which local port number to use.</p> </item> + + <tag><c>{tcp_module, module()}</c></tag> + <item> <p> + Override which callback module is used. Defaults to + <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6. + </p> + </item> + <tag><c>Opt</c></tag> <item> <p>See @@ -197,6 +207,13 @@ do_recv(Sock, Bs) -> <c>gen_tcp</c>, use this option to pass the file descriptor for it.</p> </item> + + <tag><c>{ifaddr, ip_address()}</c></tag> + <item> + <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option + specifies which one to use.</p> + </item> + <tag><c>inet6</c></tag> <item> <p>Set up the socket for IPv6.</p> @@ -205,6 +222,14 @@ do_recv(Sock, Bs) -> <item> <p>Set up the socket for IPv4.</p> </item> + + <tag><c>{tcp_module, module()}</c></tag> + <item> <p> + Override which callback module is used. Defaults to + <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6. + </p> + </item> + <tag><c>Opt</c></tag> <item> <p>See @@ -299,7 +324,7 @@ do_recv(Sock, Bs) -> <c><anno>Socket</anno></c>. The controlling process is the process which receives messages from the socket. If called by any other process than the current controlling process, - <c>{error, eperm}</c> is returned.</p> + <c>{error, not_owner}</c> is returned.</p> </desc> </func> <func> diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml index daa9b7d887..726dc30546 100644 --- a/lib/kernel/doc/src/gen_udp.xml +++ b/lib/kernel/doc/src/gen_udp.xml @@ -72,6 +72,14 @@ <p>If the host has several network interfaces, this option specifies which one to use.</p> </item> + + <tag><c>{ifaddr, ip_address()}</c></tag> + <item> + <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option + specifies which one to use.</p> + </item> + + <tag><c>{fd, integer() >= 0}</c></tag> <item> <p>If a socket has somehow been opened without using @@ -86,6 +94,51 @@ <item> <p>Set up the socket for IPv4.</p> </item> + + <tag><c>{udp_module, module()}</c></tag> + <item> <p> + Override which callback module is used. Defaults to + <c>inet_udp</c> for IPv4 and <c>inet6_udp</c> for IPv6. + </p> + </item> + + <tag><c>{multicast_if, Address}</c></tag> + <item> + <p>Set the local device for a multicast socket.</p> + </item> + + <tag><c>{multicast_loop, true | false}</c></tag> + <item> + <p> + When <c>true</c> sent multicast packets will be looped back to the local + sockets. + </p> + </item> + + <tag><c>{multicast_ttl, Integer}</c></tag> + <item> + <p> + The <c>multicast_ttl</c> option changes the time-to-live (TTL) for + outgoing multicast datagrams in order to control the scope of the + multicasts. + </p> + <p> + Datagrams with a TTL of 1 are not forwarded beyond the local + network. + <br />Default: 1 + </p> + </item> + + <tag><c>{add_membership, {MultiAddress, InterfaceAddress}}</c></tag> + <item> + <p>Join a multicast group. </p> + </item> + + <tag><c>{drop_membership, {MultiAddress, InterfaceAddress}}</c></tag> + <item> + <p>Leave multicast group.</p> + </item> + <tag><c>Opt</c></tag> <item> <p>See @@ -136,7 +189,9 @@ <desc> <p>Assigns a new controlling process <c><anno>Pid</anno></c> to <c><anno>Socket</anno></c>. The controlling process is the process which - receives messages from the socket.</p> + receives messages from the socket. If called by any other + process than the current controlling process, + <c>{error, not_owner}</c> is returned.</p> </desc> </func> <func> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index bf6c4cfb1a..32b4a429dd 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -445,10 +445,24 @@ fe80::204:acff:fe17:bf38 flow control; the other side will not be able send faster than the receiver can read.</p> </item> + <tag><c>{broadcast, Boolean}</c>(UDP sockets)</tag> <item> <p>Enable/disable permission to send broadcasts.</p> + <marker id="option-buffer"></marker> </item> + + <tag><c>{buffer, Size}</c></tag> + <item> + <p>Determines the size of the user-level software buffer used by + the driver. Not to be confused with <c>sndbuf</c> + and <c>recbuf</c> options which correspond to + the kernel socket buffers. It is recommended + to have <c>val(buffer) >= max(val(sndbuf),val(recbuf))</c>. + In fact, the <c>val(buffer)</c> is automatically set to + the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p> + </item> + <tag><c>{delay_send, Boolean}</c></tag> <item> <p>Normally, when an Erlang process sends to a socket, @@ -463,10 +477,19 @@ fe80::204:acff:fe17:bf38 real property of the socket. Needless to say it is an implementation specific option. Default is <c>false</c>.</p> </item> + + <tag><c>{deliver, port | term}</c></tag> + <item> <p> When <c>{active, true}</c> delivers data on the forms + <c>port</c> : <c>{S, {data, [H1,..Hsz | Data]}}</c> or + <c>term</c> : <c>{tcp, S, [H1..Hsz | Data]}</c>. + </p> + </item> + <tag><c>{dontroute, Boolean}</c></tag> <item> <p>Enable/disable routing bypass for outgoing messages.</p> </item> + <tag><c>{exit_on_close, Boolean}</c></tag> <item> <p>By default this option is set to <c>true</c>.</p> @@ -476,6 +499,7 @@ fe80::204:acff:fe17:bf38 <seealso marker="gen_tcp#shutdown/2">gen_tcp:shutdown/2</seealso> to shutdown the write side.</p> </item> + <tag><c>{header, Size}</c></tag> <item> <p>This option is only meaningful if the <c>binary</c> @@ -487,6 +511,15 @@ fe80::204:acff:fe17:bf38 example <c>Size == 2</c>, the data received will match <c>[Byte1,Byte2|Binary]</c>.</p> </item> + + <tag><c>{high_watermark, Size}</c></tag> + <item> <p> + Sender is forced busy if sent and enqueued data + reaches the highwater mark. + <br /> Default: 8192 kB. + </p> + </item> + <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag> <item> <p>Enables/disables periodic transmission on a connected @@ -494,7 +527,43 @@ fe80::204:acff:fe17:bf38 the other end does not respond, the connection is considered broken and an error message will be sent to the controlling process. Default disabled.</p> + <marker id="option-linger"></marker> </item> + + <tag><c>{linger, {true|false, Seconds}}</c></tag> + <item> + <p>Determines the timeout in seconds for flushing unsent data in the + <c>close/1</c> socket call. If the 1st component of the value + tuple is <c>false</c>, the 2nd one is ignored, which means that + <c>close/1</c> returns immediately not waiting + for data to be flushed. Otherwise, the 2nd component is + the flushing time-out in seconds.</p> + </item> + + <tag><c>{low_watermark, Size}</c></tag> + <item> <p> + If the port has reached its <c>high_watermark</c> it will + force busy onto senders. When the port data queue reaches the + <c>low_watermark</c> callers are no longer forced busy. + <br /> Default: 4096 kB. + </p> + </item> + + <tag><c>{mode, Mode :: binary | list}</c></tag> + <item> + <p>Received <c>Packet</c> is delivered as defined by Mode.</p> + </item> + + <tag><c>list</c></tag> + <item> + <p>Received <c>Packet</c> is delivered as a list.</p> + </item> + + <tag><c>binary</c></tag> + <item> + <p>Received <c>Packet</c> is delivered as a binary.</p> + </item> + <tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag> <item> <p>If <c>Boolean == true</c>, the <c>TCP_NODELAY</c> option @@ -578,6 +647,16 @@ fe80::204:acff:fe17:bf38 indicated length are accepted and not considered invalid due to internal buffer limitations.</p> </item> + + <tag><c>{priority, Priority}</c></tag> + <item> <p>Set the protocol-defined priority for all packets to be sent + on this socket.</p> + </item> + + <tag><c>{raw, Protocol, OptionNum, ValueBin}</c></tag> + <item> <p>See below.</p> + </item> + <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag> <item> <p>Sets the max number of UDP packets to read without @@ -589,7 +668,7 @@ fe80::204:acff:fe17:bf38 high the system can become unresponsive due to UDP packet flooding.</p> </item> - <tag><c>{recbuf, Integer}</c></tag> + <tag><c>{recbuf, Size}</c></tag> <item> <p>Gives the size of the receive buffer to use for the socket.</p> @@ -618,9 +697,10 @@ fe80::204:acff:fe17:bf38 returns <c>{error,timeout}</c>. The recommended setting is <c>true</c> which will automatically close the socket. Default is <c>false</c> due to backward compatibility.</p> + <marker id="option-sndbuf"></marker> </item> - <tag><c>{sndbuf, Integer}</c></tag> + <tag><c>{sndbuf, Size}</c></tag> <item> <p>Gives the size of the send buffer to use for the socket.</p> </item> @@ -639,6 +719,7 @@ fe80::204:acff:fe17:bf38 not implemented. Use with caution.</p> </item> </taglist> + <p>In addition to the options mentioned above, <em>raw</em> option specifications can be used. The raw options are specified as a tuple of arity four, beginning with the tag diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index e94119845a..621ca6e9ee 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2011</year> + <year>1997</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -73,7 +73,7 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> </desc> </func> <func> - <name>getenv() -> [string()]</name> + <name name="getenv" arity="0"/> <fsummary>List all environment variables</fsummary> <desc> <p>Returns a list of all environment variables. @@ -83,55 +83,40 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> </desc> </func> <func> - <name>getenv(VarName) -> Value | false</name> + <name name="getenv" arity="1"/> <fsummary>Get the value of an environment variable</fsummary> - <type> - <v>VarName = string() </v> - <v>Value = string()</v> - </type> <desc> - <p>Returns the <c>Value</c> of the environment variable - <c>VarName</c>, or <c>false</c> if the environment variable + <p>Returns the <c><anno>Value</anno></c> of the environment variable + <c><anno>VarName</anno></c>, or <c>false</c> if the environment variable is undefined.</p> </desc> </func> <func> - <name>getpid() -> Value </name> + <name name="getpid" arity="0"/> <fsummary>Return the process identifier of the emulator process</fsummary> - <type> - <v>Value = string()</v> - </type> <desc> <p>Returns the process identifier of the current Erlang emulator in the format most commonly used by the operating system - environment. <c>Value</c> is returned as a string containing + environment. <c><anno>Value</anno></c> is returned as a string containing the (usually) numerical identifier for a process. On Unix, this is typically the return value of the <c>getpid()</c> - system call. On VxWorks, <c>Value</c> contains the task id - (decimal notation) of the Erlang task. On Windows, + system call. On Windows, the process id as returned by the <c>GetCurrentProcessId()</c> system call is used.</p> </desc> </func> <func> - <name>putenv(VarName, Value) -> true</name> + <name name="putenv" arity="2"/> <fsummary>Set a new value for an environment variable</fsummary> - <type> - <v>VarName = string() </v> - <v>Value = string()</v> - </type> <desc> - <p>Sets a new <c>Value</c> for the environment variable - <c>VarName</c>.</p> + <p>Sets a new <c><anno>Value</anno></c> for the environment variable + <c><anno>VarName</anno></c>.</p> </desc> </func> <func> - <name>timestamp() -> Timestamp</name> + <name name="timestamp" arity="0"/> + <type_desc variable="Timestamp">Timestamp = {MegaSecs, Secs, MicroSecs}</type_desc> <fsummary>Returna a timestamp from the OS in the erlang:now/0 format</fsummary> - <type> - <v>Timestamp = {MegaSecs, Secs, MicroSecs} = <seealso marker="erts:erlang#type-timestamp">erlang:timestamp()</seealso></v> - <v>MegaSecs = Secs = MicroSecs = integer() >= 0</v> - </type> <desc> <p>Returns a tuple in the same format as <seealso marker="erts:erlang#now/0">erlang:now/0</seealso>. The difference is that this function returns what the operating system thinks (a.k.a. the wall clock time) without any attempts at time correction. The result of two different calls to this function is <em>not</em> guaranteed to be different.</p> <p>The most obvious use for this function is logging. The tuple can be used together with the function <seealso marker="stdlib:calendar#now_to_universal_time/1">calendar:now_to_universal_time/1</seealso> @@ -168,8 +153,6 @@ format_utc_timestamp() -> Solaris 1 and 2, it will be <c>sunos</c>.</p> <p>In Windows, <c><anno>Osname</anno></c> will be either <c>nt</c> (on Windows NT), or <c>windows</c> (on Windows 95).</p> - <p>On VxWorks the OS family alone is returned, that is - <c>vxworks</c>.</p> <note> <p>Think twice before using this function. Use the <c>filename</c> module if you want to inspect or build |