From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/specs/.gitignore | 1 + lib/kernel/doc/src/Makefile | 40 +- lib/kernel/doc/src/application.xml | 234 +++------ lib/kernel/doc/src/auth.xml | 51 +- lib/kernel/doc/src/code.xml | 6 + lib/kernel/doc/src/disk_log.xml | 451 ++++++++--------- lib/kernel/doc/src/erl_boot_server.xml | 44 +- lib/kernel/doc/src/erl_ddll.xml | 129 ++--- lib/kernel/doc/src/error_handler.xml | 44 +- lib/kernel/doc/src/error_logger.xml | 135 ++--- lib/kernel/doc/src/file.xml | 895 +++++++++++++-------------------- lib/kernel/doc/src/gen_sctp.xml | 237 ++++----- lib/kernel/doc/src/gen_tcp.xml | 163 +++--- lib/kernel/doc/src/gen_udp.xml | 101 ++-- lib/kernel/doc/src/global.xml | 176 +++---- lib/kernel/doc/src/global_group.xml | 157 +++--- lib/kernel/doc/src/heart.xml | 16 +- lib/kernel/doc/src/inet.xml | 193 +++---- lib/kernel/doc/src/inet_res.xml | 271 +++------- lib/kernel/doc/src/net_adm.xml | 74 +-- lib/kernel/doc/src/net_kernel.xml | 90 ++-- lib/kernel/doc/src/os.xml | 44 +- lib/kernel/doc/src/pg2.xml | 66 +-- lib/kernel/doc/src/rpc.xml | 330 ++++-------- lib/kernel/doc/src/seq_trace.xml | 95 ++-- lib/kernel/doc/src/specs.xml | 33 ++ lib/kernel/doc/src/wrap_log_reader.xml | 66 ++- 27 files changed, 1585 insertions(+), 2557 deletions(-) create mode 100644 lib/kernel/doc/specs/.gitignore create mode 100644 lib/kernel/doc/src/specs.xml (limited to 'lib/kernel/doc') diff --git a/lib/kernel/doc/specs/.gitignore b/lib/kernel/doc/specs/.gitignore new file mode 100644 index 0000000000..322eebcb06 --- /dev/null +++ b/lib/kernel/doc/specs/.gitignore @@ -0,0 +1 @@ +specs_*.xml diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile index f8c1cac8b3..de10e31d36 100644 --- a/lib/kernel/doc/src/Makefile +++ b/lib/kernel/doc/src/Makefile @@ -1,19 +1,20 @@ -# ``The contents of this file are subject to the Erlang Public License, +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1997-2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in # compliance with the License. You should have received a copy of the # Erlang Public License along with this software. If not, it can be -# retrieved via the world wide web at http://www.erlang.org/. -# +# retrieved online at http://www.erlang.org/. +# # Software distributed under the License is distributed on an "AS IS" # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See # the License for the specific language governing rights and limitations # under the License. -# -# The Initial Developer of the Original Code is Ericsson Utvecklings AB. -# Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings -# AB. All Rights Reserved.'' -# -# $Id$ +# +# %CopyrightEnd% # include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk @@ -94,19 +95,24 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf +SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) + +TOP_SPECS_FILE = specs.xml # ---------------------------------------------------- # FLAGS # ---------------------------------------------------- XML_FLAGS += +SPECS_FLAGS = -I../../include + # ---------------------------------------------------- # Targets # ---------------------------------------------------- $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ -docs: pdf html man +docs: man pdf html $(TOP_PDF_FILE): $(XML_FILES) @@ -125,8 +131,22 @@ clean clean_docs: rm -f $(MAN4DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f $(SPECDIR)/* rm -f errs core *~ +$(SPECDIR)/specs_erl_prim_loader_stub.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module erl_prim_loader_stub +$(SPECDIR)/specs_erlang_stub.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module erlang_stub +$(SPECDIR)/specs_init_stub.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module init_stub +$(SPECDIR)/specs_zlib_stub.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module zlib_stub + # ---------------------------------------------------- # Release Target # ---------------------------------------------------- diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml index 47d578a339..51a3311ec2 100644 --- a/lib/kernel/doc/src/application.xml +++ b/lib/kernel/doc/src/application.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -50,20 +50,27 @@

Refer to OTP Design Principles for more information about applications and behaviours.

+ + + + + + + + + + tuple_of(T) +

A tuple where the elements are of type T.

 + + - get_all_env() -> Env - get_all_env(Application) -> Env + + Get the configuration parameters for an application - - Application = atom() - Env = [{Par,Val}] -  Par = atom() -  Val = term() -

Returns the configuration parameters and their values for - Application. If the argument is omitted, it defaults to + Application. If the argument is omitted, it defaults to the application of the calling process.

If the specified application is not loaded, or if the process executing the call does not belong to any application, @@ -71,18 +78,12 @@ - get_all_key() -> {ok, Keys} | [] - get_all_key(Application) -> {ok, Keys} | undefined + + Get the application specification keys - - Application = atom() - Keys = [{Key,Val}] -  Key = atom() -  Val = term() -

Returns the application specification keys and their values - for Application. If the argument is omitted, it + for Application. If the argument is omitted, it defaults to the application of the calling process.

If the specified application is not loaded, the function returns undefined. If the process executing the call @@ -91,17 +92,12 @@ - get_application() -> {ok, Application} | undefined - get_application(Pid | Module) -> {ok, Application} | undefined + + Get the name of an application containing a certain process or module - - Pid = pid() - Module = atom() - Application = atom() -

Returns the name of the application to which the process - Pid or the module Module belongs. Providing no + Pid or the module Module belongs. Providing no argument is the same as calling get_application(self()).

If the specified process does not belong to any application, @@ -110,17 +106,12 @@ - get_env(Par) -> {ok, Val} | undefined - get_env(Application, Par) -> {ok, Val} | undefined + + Get the value of a configuration parameter - - Application = atom() - Par = atom() - Val = term() - -

Returns the value of the configuration parameter Par - for Application. If the application argument is +

Returns the value of the configuration parameter Par + for Application. If the application argument is omitted, it defaults to the application of the calling process.

If the specified application is not loaded, or @@ -130,17 +121,12 @@ - get_key(Key) -> {ok, Val} | undefined - get_key(Application, Key) -> {ok, Val} | undefined + + Get the value of an application specification key - - Application = atom() - Key = atom() - Val = term() -

Returns the value of the application specification key - Key for Application. If the application + Key for Application. If the application argument is omitted, it defaults to the application of the calling process.

If the specified application is not loaded, or @@ -150,45 +136,35 @@ - load(AppDescr) -> ok | {error, Reason} - load(AppDescr, Distributed) -> ok | {error, Reason} + + Load an application - - AppDescr = Application | AppSpec -  Application = atom() -  AppSpec = {application,Application,AppSpecKeys} -   AppSpec = [{Key,Val}] -    Key = atom() -    Val = term() - Distributed = {Application,Nodes} | {Application,Time,Nodes} | default -  Nodes = [node() | {node(),..,node()}] -  Time = integer() > 0 - Reason = term() - + +

Loads the application specification for an application into the application controller. It will also load the application specifications for any included applications. Note that the function does not load the actual Erlang object code.

-

The application can be given by its name Application. +

The application can be given by its name Application. In this case the application controller will search the code - path for the application resource file Application.app + path for the application resource file Application.app and load the specification it contains.

The application specification can also be given directly as a - tuple AppSpec. This tuple should have the format and + tuple AppSpec. This tuple should have the format and contents as described in app(4).

-

If Distributed == {Application,[Time,]Nodes}, +

If Distributed == {Application,[Time,]Nodes}, the application will be distributed. The argument overrides the value for the application in the Kernel configuration - parameter distributed. Application must be + parameter distributed. Application must be the name of the application (same as in the first argument). - If a node crashes and Time has been specified, then - the application controller will wait for Time + If a node crashes and Time has been specified, then + the application controller will wait for Time milliseconds before attempting to restart the application on - another node. If Time is not specified, it will + another node. If Time is not specified, it will default to 0 and the application will be restarted immediately.

-

Nodes is a list of node names where the application +

Nodes is a list of node names where the application may run, in priority from left to right. Node names can be grouped using tuples to indicate that they have the same priority. Example:

@@ -204,32 +180,22 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - loaded_applications() -> [{Application, Description, Vsn}] + Get the currently loaded applications - - Application = atom() - Description = string() - Vsn = string() -

Returns a list with information about the applications which have been loaded using load/1,2, also included - applications. Application is the application name. - Description and Vsn are the values of its + applications. Application is the application name. + Description and Vsn are the values of its description and vsn application specification keys, respectively.

 - permit(Application, Bool) -> ok | {error, Reason} + Change an application's permission to run on a node. - - Application = atom() - Bool = bool() - Reason = term() - -

Changes the permission for Application to run at +

Changes the permission for Application to run at the current node. The application must have been loaded using load/1,2 for the function to have effect.

If the permission of a loaded, but not started, application @@ -258,20 +224,14 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - set_env(Application, Par, Val) -> ok - set_env(Application, Par, Val, Timeout) -> ok + + Set the value of a configuration parameter - - Application = atom() - Par = atom() - Val = term() - Timeout = int() | infinity - -

Sets the value of the configuration parameter Par for - Application.

+

Sets the value of the configuration parameter Par for + Application.

set_env/3 uses the standard gen_server timeout - value (5000 ms). A Timeout argument can be provided + value (5000 ms). A Timeout argument can be provided if another timeout value is useful, for example, in situations where the application controller is heavily loaded.

@@ -285,20 +245,15 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - start(Application) -> ok | {error, Reason} - start(Application, Type) -> ok | {error, Reason} + + Load and start an application - - Application = atom() - Type = permanent | transient | temporary - Reason = term() - -

Starts Application. If it is not loaded, +

Starts Application. If it is not loaded, the application controller will first load it using load/1. It will make sure any included applications are loaded, but will not start them. That is assumed to be - taken care of in the code for Application.

+ taken care of in the code for Application.

The application controller checks the value of the application specification key applications, to ensure that all applications that should be started before @@ -310,7 +265,7 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] The application master starts the application by calling the application callback function Module:start/2 as defined by the application specification key mod.

-

The Type argument specifies the type of +

The Type argument specifies the type of the application. If omitted, it defaults to temporary.

If a permanent application terminates, all other @@ -331,19 +286,15 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - start_type() -> StartType | local | undefined + Get the start type of an ongoing application startup. - - StartType = normal | {takeover,Node} | {failover,Node} -  Node = node() -

This function is intended to be called by a process belonging to an application, when the application is being started, to - determine the start type which is either StartType or + determine the start type which is either StartType or local.

-

See Module:start/2 for a description of - StartType.

+

See Module:start/2 for a description of + StartType.

local is returned if only parts of the application is being restarted (by a supervisor), or if the function is called outside a startup.

@@ -352,14 +303,10 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - stop(Application) -> ok | {error, Reason} + Stop an application - - Application = atom() - Reason = term() - -

Stops Application. The application master calls +

Stops Application. The application master calls Module:prep_stop/1, if such a function is defined, and then tells the top supervisor of the application to shutdown (see supervisor(3)). This means that the entire @@ -384,16 +331,11 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - takeover(Application, Type) -> ok | {error, Reason} + Take over a distributed application - - Application = atom() - Type = permanent | transient | temporary - Reason = term() -

Performs a takeover of the distributed application - Application, which executes at another node + Application, which executes at another node Node. At the current node, the application is restarted by calling Module:start({takeover,Node},StartArgs). Module @@ -413,14 +355,10 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - unload(Application) -> ok | {error, Reason} + Unload an application - - Application = atom() - Reason = term() - -

Unloads the application specification for Application +

Unloads the application specification for Application from the application controller. It will also unload the application specifications for any included applications. Note that the function does not purge the actual Erlang @@ -428,19 +366,14 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - unset_env(Application, Par) -> ok - unset_env(Application, Par, Timeout) -> ok + + Unset the value of a configuration parameter - - Application = atom() - Par = atom() - Timeout = int() | infinity - -

Removes the configuration parameter Par and its value - for Application.

+

Removes the configuration parameter Par and its value + for Application.

unset_env/2 uses the standard gen_server - timeout value (5000 ms). A Timeout argument can be + timeout value (5000 ms). A Timeout argument can be provided if another timeout value is useful, for example, in situations where the application controller is heavily loaded.

@@ -454,23 +387,17 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] - which_applications() -> [{Application, Description, Vsn}] - which_applications(Timeout) -> [{Application, Description, Vsn}] + + Get the currently running applications - - Application = atom() - Description = string() - Vsn = string() - Timeout = int() | infinity -

Returns a list with information about the applications which - are currently running. Application is the application - name. Description and Vsn are the values of its + are currently running. Application is the application + name. Description and Vsn are the values of its description and vsn application specification keys, respectively.

which_applications/0 uses the standard - gen_server timeout value (5000 ms). A Timeout + gen_server timeout value (5000 ms). A Timeout argument can be provided if another timeout value is useful, for example, in situations where the application controller is heavily loaded.

@@ -501,7 +428,7 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] structured according to the OTP design principles as a supervision tree, this means starting the top supervisor of the tree.

-

StartType defines the type of start:

+

StartType defines the type of start:

normal if it's a normal startup. normal also if the application is distributed and @@ -532,8 +459,7 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}] Extended start of an application Phase = atom() - StartType = normal | {takeover,Node} | {failover,Node} -  Node = node() + StartType = start_type() PhaseArgs = term() Pid = pid() State = state() diff --git a/lib/kernel/doc/src/auth.xml b/lib/kernel/doc/src/auth.xml index f53fc8b29a..15d9ef0fe4 100644 --- a/lib/kernel/doc/src/auth.xml +++ b/lib/kernel/doc/src/auth.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -34,29 +34,28 @@ Cookie system, refer to Distributed Erlang in the Erlang Reference Manual.

+ + + + + - is_auth(Node) -> yes | no + Status of communication authorization (deprecated) - - Node = node() - -

Returns yes if communication with Node is - authorized. Note that a connection to Node will - be established in this case. Returns no if Node +

Returns yes if communication with Node is + authorized. Note that a connection to Node will + be established in this case. Returns no if Node does not exist or communication is not authorized (it has another cookie than auth thinks it has).

-

Use net_adm:ping(Node) +

Use net_adm:ping(Node) instead.

 - cookie() -> Cookie + Magic cookie for local node (deprecated) - - Cookie = atom() -

Use erlang:get_cookie() @@ -64,16 +63,14 @@ - cookie(TheCookie) -> true + Set the magic for the local node (deprecated) - - TheCookie = Cookie | [Cookie] - The cookie may also be given as a list with a single atom element -  Cookie = atom() - + + The cookie may also be given as a list with a single atom element. +

Use - erlang:set_cookie(node(), Cookie) + erlang:set_cookie(node(), Cookie) instead.

 @@ -82,7 +79,7 @@ Set the magic cookie for a node and verify authorization (deprecated) Node = node() - Cookie = atom() + Cookie = cookie()

Equivalent to @@ -90,18 +87,14 @@ - node_cookie(Node, Cookie) -> yes | no + Set the magic cookie for a node and verify authorization (deprecated) - - Node = node() - Cookie = atom() - -

Sets the magic cookie of Node to Cookie, and +

Sets the magic cookie of Node to Cookie, and verifies the status of the authorization. Equivalent to calling - erlang:set_cookie(Node, Cookie), followed by - auth:is_auth(Node).

+ erlang:set_cookie(Node, Cookie), followed by + auth:is_auth(Node).

 diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index 4b8f934df1..6f85388c22 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -286,6 +286,12 @@ given to set_path/1.

+ + + + + + set_path(Path) -> true | {error, What} diff --git a/lib/kernel/doc/src/disk_log.xml b/lib/kernel/doc/src/disk_log.xml index 324d4264cf..9721907162 100644 --- a/lib/kernel/doc/src/disk_log.xml +++ b/lib/kernel/doc/src/disk_log.xml @@ -179,13 +179,48 @@ reopen the log simultaneously.

+ + + + + + + + + + + + + + + + + + + + + + + + +

Chunk continuation returned by + chunk/2,3, bchunk/2,3, or chunk_step/3.

+ + + + + + + + + + + + - accessible_logs() -> {[LocalLog], [DistributedLog]} + Return the accessible disk logs on the current node. - - LocalLog = DistributedLog = term() -

The accessible_logs/0 function returns the names of the disk logs accessible on the current node. @@ -195,16 +230,13 @@ - alog(Log, Term) - balog(Log, Bytes) -> ok | {error, Reason} + + + + + + Asynchronously log an item onto a disk log. - - Log = term() - Term = term() - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log -

The alog/2 and balog/2 functions asynchronously append an item to a disk log. The function alog/2 is @@ -225,17 +257,13 @@ - alog_terms(Log, TermList) - balog_terms(Log, BytesList) -> ok | {error, Reason} + + Asynchronously log several items onto a disk log. - - Log = term() - TermList = [term()] - BytesList = [Bytes] - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log - + + + +

The alog_terms/2 and balog_terms/2 functions asynchronously append a list of items to a disk log. @@ -257,14 +285,10 @@ - block(Log) - block(Log, QueueLogRecords) -> ok | {error, Reason} + + + Block a disk log. - - Log = term() - QueueLogRecords = bool() - Reason = no_such_log | nonode | {blocked_log, Log} -

With a call to block/1,2 a process can block a log. If the blocking process is not an owner of the log, a temporary @@ -280,52 +304,32 @@ affected by the block. Any other attempt than those hitherto mentioned to update or read a blocked log suspends the calling process until the log is unblocked or returns an - error message {blocked_log, Log}, depending on - whether the value of QueueLogRecords is true - or false. The default value of QueueLogRecords + error message {blocked_log, Log}, depending on + whether the value of QueueLogRecords is true + or false. The default value of QueueLogRecords is true, which is used by block/1.

- change_header(Log, Header) -> ok | {error, Reason} + Change the head or head_func option for an owner of a disk log. - - Log = term() - Header = {head, Head} | {head_func, {M,F,A}} - Head = none | term() | binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {badarg, head} -

The change_header/2 function changes the value of the head or head_func option of a disk log.

 - change_notify(Log, Owner, Notify) -> ok | {error, Reason} + Change the notify option for an owner of a disk log. - - Log = term() - Owner = pid() - Notify = bool() - Reason = no_such_log | nonode | {blocked_log, Log} | {badarg, notify} | {not_owner, Owner} -

The change_notify/3 function changes the value of the notify option for an owner of a disk log.

- change_size(Log, Size) -> ok | {error, Reason} + Change the size of an open disk log. - - Log = term() - Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles} - MaxNoBytes = integer() > 0 - MaxNoFiles = integer() > 0 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {new_size_too_small, CurrentSize} | {badarg, size} | {file_error, FileName, FileError} -

The change_size/2 function changes the size of an open log. For a halt log it is always possible to increase the size, @@ -363,21 +367,17 @@ - chunk(Log, Continuation) - chunk(Log, Continuation, N) -> {Continuation2, Terms} | {Continuation2, Terms, Badbytes} | eof | {error, Reason} - bchunk(Log, Continuation) - bchunk(Log, Continuation, N) -> {Continuation2, Binaries} | {Continuation2, Binaries, Badbytes} | eof | {error, Reason} + + + + Read a chunk of items written to a disk log. - - Log = term() - Continuation = start | cont() - N = integer() > 0 | infinity - Continuation2 = cont() - Terms = [term()] - Badbytes = integer() - Reason = no_such_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {not_internal_wrap, Log} | {corrupt_log_file, FileName} | {file_error, FileName, FileError} - Binaries = [binary()] - + + + + + +

The chunk/2,3 and bchunk/2,3 functions make it possible to efficiently read the terms which have been @@ -394,31 +394,31 @@ individual distributed log on some other node is chosen, if such a log exists.

-

When chunk/3 is called, N controls the +

When chunk/3 is called, N controls the maximum number of terms that are read from the log in each chunk. Default is infinity, which means that all the terms contained in the 64 kilobyte chunk are read. If less than - N terms are returned, this does not necessarily mean + N terms are returned, this does not necessarily mean that the end of the file has been reached.

The chunk function returns a tuple - {Continuation2, Terms}, where Terms is a list - of terms found in the log. Continuation2 is yet + {Continuation2, Terms}, where Terms is a list + of terms found in the log. Continuation2 is yet another continuation which must be passed on to any subsequent calls to chunk. With a series of calls to chunk it is possible to extract all terms from a log.

The chunk function returns a tuple - {Continuation2, Terms, Badbytes} if the log is opened - in read-only mode and the read chunk is corrupt. Badbytes + {Continuation2, Terms, Badbytes} if the log is opened + in read-only mode and the read chunk is corrupt. Badbytes is the number of bytes in the file which were found not to be Erlang terms in the chunk. Note also that the log is not repaired. When trying to read chunks from a log opened in read-write mode, - the tuple {corrupt_log_file, FileName} is returned if the + the tuple {corrupt_log_file, FileName} is returned if the read chunk is corrupt.

chunk returns eof when the end of the log is - reached, or {error, Reason} if an error occurs. Should + reached, or {error, Reason} if an error occurs. Should a wrap log file be missing, a message is output on the error log.

When chunk/2,3 is used with wrap logs, the returned @@ -431,12 +431,8 @@ - chunk_info(Continuation) -> InfoList | {error, Reason} + Return information about a chunk continuation of a disk log. - - Continuation = cont() - Reason = {no_continuation, Continuation} -

The chunk_info/1 function returns the following pair describing the chunk continuation returned by @@ -444,29 +440,22 @@

-

{node, Node}. Terms are read from - the disk log running on Node.

+

{node, Node}. Terms are read from + the disk log running on Node.

 - chunk_step(Log, Continuation, Step) -> {ok, Continuation2} | {error, Reason} + Step forward or backward among the wrap log files of a disk log. - - Log = term() - Continuation = start | cont() - Step = integer() - Continuation2 = cont() - Reason = no_such_log | end_of_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {file_error, FileName, FileError} -

The function chunk_step can be used in conjunction with chunk/2,3 and bchunk/2,3 to search through an internally formatted wrap log. It takes as argument a continuation as returned by chunk/2,3, bchunk/2,3, or chunk_step/3, and steps forward - (or backward) Step files in the wrap log. The + (or backward) Step files in the wrap log. The continuation returned points to the first log item in the new current file.

@@ -482,11 +471,9 @@ - close(Log) -> ok | {error, Reason} + Close a disk log. - - Reason = no_such_log | nonode | {file_error, FileName, FileError} - +

The function close/1 closes a @@ -511,11 +498,8 @@ The function close/1 closes a - format_error(Error) -> Chars + Return an English description of a disk log error reply. - - Chars = [char() | Chars] -

Given the error returned by any function in this module, the function format_error returns a descriptive string @@ -524,11 +508,10 @@ The function close/1 closes a - inc_wrap_file(Log) -> ok | {error, Reason} + Change to the next wrap log file of a disk log. - - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {halt_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + +

The inc_wrap_file/1 function forces the internally formatted disk log to start logging to the @@ -543,8 +526,9 @@ The function close/1 closes a - info(Log) -> InfoList | {error, no_such_log} + Return information about a disk log. +

The info/1 function returns a list of {Tag, Value} pairs describing the log. If there is a disk log process running @@ -556,55 +540,55 @@ The function close/1 closes a

-

{name, Log}, where Log is the name of +

{name, Log}, where Log is the name of the log as given by the open/1 option name.

 -

{file, File}. For halt logs File is the - filename, and for wrap logs File is the base name.

+

{file, File}. For halt logs File is the + filename, and for wrap logs File is the base name.

 -

{type, Type}, where Type is the type of +

{type, Type}, where Type is the type of the log as given by the open/1 option type.

 -

{format, Format}, where Format is the format +

{format, Format}, where Format is the format of the log as given by the open/1 option format.

 -

{size, Size}, where Size is the size +

{size, Size}, where Size is the size of the log as given by the open/1 option size, or the size set by change_size/2. The value set by change_size/2 is reflected immediately.

 -

{mode, Mode}, where Mode is the mode +

{mode, Mode}, where Mode is the mode of the log as given by the open/1 option mode.

 -

{owners, [{pid(), Notify}]} where Notify +

{owners, [{pid(), Notify}]} where Notify is the value set by the open/1 option notify or the function change_notify/3 for the owners of the log.

 -

{users, Users} where Users is the number +

{users, Users} where Users is the number of anonymous users of the log, see the open/1 option linkto.

 -

{status, Status}, where Status is ok - or {blocked, QueueLogRecords} as set by the functions +

{status, Status}, where Status is ok + or {blocked, QueueLogRecords} as set by the functions block/1,2 and unblock/1.

 -

{node, Node}. The information returned by the +

{node, Node}. The information returned by the current invocation of the info/1 function has been - gathered from the disk log process running on Node.

+ gathered from the disk log process running on Node.

 -

{distributed, Dist}. If the log is local on - the current node, then Dist has the value local, +

{distributed, Dist}. If the log is local on + the current node, then Dist has the value local, otherwise all nodes where the log is distributed are returned as a list.

 @@ -614,16 +598,16 @@ The function close/1 closes a

-

{head, Head}. Depending of the value of +

{head, Head}. Depending of the value of the open/1 options head and head_func or set by the function change_header/2, the value - of Head is none (default), + of Head is none (default), {head, H} (head option) or {M,F,A} (head_func option).

 -

{no_written_items, NoWrittenItems}, where - NoWrittenItems is the number of items +

{no_written_items, NoWrittenItems}, where + NoWrittenItems is the number of items written to the log since the disk log process was created.

 @@ -632,7 +616,7 @@ The function close/1 closes a

-

{full, Full}, where Full is true or +

{full, Full}, where Full is true or false depending on whether the halt log is full or not.

 @@ -660,8 +644,8 @@ The function close/1 closes a size or set by change_size/2.

-

{no_overflows, {SinceLogWasOpened, SinceLastInfo}}, - where SinceLogWasOpened (SinceLastInfo) is +

{no_overflows, {SinceLogWasOpened, SinceLastInfo}}, + where SinceLogWasOpened (SinceLastInfo) is the number of times a wrap log file has been filled up and a new one opened or inc_wrap_file/1 has been called since the disk log was last opened (info/1 @@ -677,21 +661,18 @@ The function close/1 closes a - lclose(Log) - lclose(Log, Node) -> ok | {error, Reason} + + + Close a disk log on one node. - - Node = node() - Reason = no_such_log | {file_error, FileName, FileError} -

The function lclose/1 closes a local log or an individual distributed log on the current node. The function lclose/2 closes an individual distributed log on the specified node if the node is not the current one. - lclose(Log) is equivalent to - lclose(Log, node()). + lclose(Log) is equivalent to + lclose(Log, node()). See also close/1.

If there is no log with the given name @@ -700,20 +681,17 @@ The function close/1 closes a - log(Log, Term) - blog(Log, Bytes) -> ok | {error, Reason} + + Log an item onto a disk log. - - Log = term() - Term = term() - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The log/2 and blog/2 functions synchronously append a term to a disk log. They return ok or - {error, Reason} when the term has been written to + {error, Reason} when the term has been written to disk. If the log is distributed, ok is always returned, unless all nodes are down. Terms are written by means of the ordinary write() function of the @@ -736,17 +714,13 @@ The function close/1 closes a - log_terms(Log, TermList) - blog_terms(Log, BytesList) -> ok | {error, Reason} + + Log several items onto a disk log. - - Log = term() - TermList = [term()] - BytesList = [Bytes] - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The log_terms/2 and blog_terms/2 functions synchronously append a list of items to the log. The benefit @@ -769,47 +743,33 @@ The function close/1 closes a - open(ArgL) -> OpenRet | DistOpenRet + + + + + + + + + + Open a disk log file. - - ArgL = [Opt] - Opt = {name, term()} | {file, FileName}, {linkto, LinkTo} | {repair, Repair} | {type, Type} | {format, Format} | {size, Size} | {distributed, [Node]} | {notify, bool()} | {head, Head} | {head_func, {M,F,A}} | {mode, Mode} - FileName = string() | atom() - LinkTo = pid() | none - Repair = true | false | truncate - Type = halt | wrap - Format = internal | external - Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles} - MaxNoBytes = integer() > 0 - MaxNoFiles = 0 < integer() < 65000 - Rec = integer() - Bad = integer() - Head = none | term() | binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Mode = read_write | read_only - OpenRet = Ret | {error, Reason} - DistOpenRet = {[{Node, Ret}], [{BadNode, {error, DistReason}}]} - Node = BadNode = atom() - Ret = {ok, Log} | {repaired, Log, {recovered, Rec}, {badbytes, Bad}} - DistReason = nodedown | Reason - Reason = no_such_log | {badarg, Arg} | {size_mismatch, CurrentSize, NewSize} | {arg_mismatch, OptionName, CurrentValue, Value} | {name_already_open, Log} | {open_read_write, Log} | {open_read_only, Log} | {need_repair, Log} | {not_a_log_file, FileName} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} | {node_already_open, Log} - -

The ArgL parameter is a list of options which have +

The ArgL parameter is a list of options which have the following meanings:

-

{name, Log} specifies the name of the log. +

{name, Log} specifies the name of the log. This is the name which must be passed on as a parameter in all subsequent logging operations. A name must always be supplied.

-

{file, FileName} specifies the name of the +

{file, FileName} specifies the name of the file which will be used for logged terms. If this value is omitted and the name of the log is either an atom or a string, - the file name will default to lists:concat([Log, ".LOG"]) for halt logs. For wrap logs, this will be + the file name will default to lists:concat([Log, ".LOG"]) for halt logs. For wrap logs, this will be the base name of the files. Each file in a wrap log will be called .N]]>, where N is an integer. Each wrap log will also have two files called @@ -817,22 +777,22 @@ The function close/1 closes a

-

{linkto, LinkTo}. +

{linkto, LinkTo}. If - LinkTo is a pid, that pid becomes an owner of the - log. If LinkTo is none the log records + LinkTo is a pid, that pid becomes an owner of the + log. If LinkTo is none the log records that it is used anonymously by some process by incrementing the users counter. By default, the process which calls open/1 owns the log.

-

{repair, Repair}. If Repair is true, +

{repair, Repair}. If Repair is true, the current log file will be repaired, if needed. As the restoration is initiated, a message is output on the error log. If false is given, no automatic repair will be attempted. Instead, the - tuple {error, {need_repair, Log}} is returned if an + tuple {error, {need_repair, Log}} is returned if an attempt is made to open a corrupt log file. If truncate is given, the log file will be truncated, creating an empty log. Default is @@ -841,41 +801,41 @@ If

-

{type, Type} is the type of the log. Default +

{type, Type} is the type of the log. Default is halt.

-

{format, Format} specifies the format of the +

{format, Format} specifies the format of the disk log. Default is internal.

-

{size, Size} specifies the size of the log. +

{size, Size} specifies the size of the log. When a halt log has reached its maximum size, all attempts to log more items are rejected. The default size is infinity, which for halt implies that there is no - maximum size. For wrap logs, the Size parameter + maximum size. For wrap logs, the Size parameter may be either a pair - {MaxNoBytes, MaxNoFiles} or infinity. In the + {MaxNoBytes, MaxNoFiles} or infinity. In the latter case, if the files of an already existing wrap log with the same name can be found, the size is read from the existing wrap log, otherwise an error is returned. - Wrap logs write at most MaxNoBytes bytes on each file - and use MaxNoFiles files before starting all over with - the first wrap log file. Regardless of MaxNoBytes, + Wrap logs write at most MaxNoBytes bytes on each file + and use MaxNoFiles files before starting all over with + the first wrap log file. Regardless of MaxNoBytes, at least the header (if there is one) and one item is written on each wrap log file before wrapping to the next file. When opening an existing wrap log, it is not necessary to supply a value for the option Size, but any supplied value must equal the current size of the log, otherwise - the tuple {error, {size_mismatch, CurrentSize, NewSize}} + the tuple {error, {size_mismatch, CurrentSize, NewSize}} is returned.

-

{distributed, Nodes}. This option can be used for +

{distributed, Nodes}. This option can be used for adding members to a distributed disk log. The default value is [], which means that the log is local on the current node. @@ -946,10 +906,10 @@ If -

{head, Head} specifies a header to be +

{head, Head} specifies a header to be written first on the log file. If the log is a wrap - log, the item Head is written first in each new file. - Head should be a term if the format is + log, the item Head is written first in each new file. + Head should be a term if the format is internal, and a deep list of bytes (or a binary) otherwise. Default is none, which means that no header is written first on the file. @@ -966,17 +926,17 @@ If

-

{mode, Mode} specifies if the log is to be +

{mode, Mode} specifies if the log is to be opened in read-only or read-write mode. It defaults to read_write.

-

The open/1 function returns {ok, Log} if the +

The open/1 function returns {ok, Log} if the log file was successfully opened. If the file was - successfully repaired, the tuple {repaired, Log, {recovered, Rec}, {badbytes, Bad}} is returned, where - Rec is the number of whole Erlang terms found in the - file and Bad is the number of bytes in the file which + successfully repaired, the tuple {repaired, Log, {recovered, Rec}, {badbytes, Bad}} is returned, where + Rec is the number of whole Erlang terms found in the + file and Bad is the number of bytes in the file which were non-Erlang terms. If the distributed parameter was given, open/1 returns a list of successful replies and a list of erroneous replies. Each @@ -988,7 +948,7 @@ If position after the last logged item, and the logging of items will commence from there. If the format is internal and the existing file is not recognized as an internally - formatted log, a tuple {error, {not_a_log_file, FileName}} + formatted log, a tuple {error, {not_a_log_file, FileName}} is returned.

The open/1 function cannot be used for changing the @@ -1000,15 +960,15 @@ If or change_size/2. As a consequence, none of the options except name is mandatory. If some given value differs from the current value, a tuple - {error, {arg_mismatch, OptionName, CurrentValue, Value}} + {error, {arg_mismatch, OptionName, CurrentValue, Value}} is returned. Caution: an owner's attempt to open a log as owner once again is acknowledged with the return value - {ok, Log}, but the state of the disk log is not + {ok, Log}, but the state of the disk log is not affected in any way.

If a log with a given name is local on some node, and one tries to open the log distributed on the same node, - then the tuple {error, {node_already_open, Name}} is + then the tuple {error, {node_already_open, Log}} is returned. The same tuple is returned if the log is distributed on some node, and one tries to open the log locally on the same node. Opening individual distributed disk logs for the first time @@ -1036,12 +996,8 @@ If - pid2name(Pid) -> {ok, Log} | undefined + Return the name of the disk log handled by a pid. - - Log = term() - Pid = pid() -

The pid2name/1 function returns the name of the log given the pid of a disk log process on the current node, or @@ -1052,26 +1008,23 @@ If - reopen(Log, File) - reopen(Log, File, Head) - breopen(Log, File, BHead) -> ok | {error, Reason} + + + Reopen a disk log and save the old log. - - Log = term() - File = string() - Head = term() - BHead = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {same_file_name, Log} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + + +

The reopen functions first rename the log file - to File and then re-create a new log file. - In case of a wrap log, File is used as the base name + to File and then re-create a new log file. + In case of a wrap log, File is used as the base name of the renamed files. By default the header given to open/1 is written first in - the newly opened log file, but if the Head or the - BHead argument is given, this item is used instead. + the newly opened log file, but if the Head or the + BHead argument is given, this item is used instead. The header argument is used once only; next time a wrap log file is opened, the header given to open/1 is used.

@@ -1089,12 +1042,9 @@ If - sync(Log) -> ok | {error, Reason} + + Flush the contents of a disk log to the disk. - - Log = term() - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {file_error, FileName, FileError} -

The sync/1 function ensures that the contents of the log are actually written to the disk. @@ -1103,20 +1053,17 @@ If - truncate(Log) - truncate(Log, Head) - btruncate(Log, BHead) -> ok | {error, Reason} + + + Truncate a disk log. - - Log = term() - Head = term() - BHead = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The truncate functions remove all items from a disk log. - If the Head or the BHead argument is + If the Head or the BHead argument is given, this item is written first in the newly truncated log, otherwise the header given to open/1 is used. The header argument is only used once; next time a wrap log file @@ -1138,12 +1085,9 @@ If - unblock(Log) -> ok | {error, Reason} + + Unblock a disk log. - - Log = term() - Reason = no_such_log | nonode | {not_blocked, Log} | {not_blocked_by_pid, Log} -

The unblock/1 function unblocks a log. A log can only be unblocked by the blocking process. @@ -1159,4 +1103,3 @@ If wrap_log_reader(3)

- diff --git a/lib/kernel/doc/src/erl_boot_server.xml b/lib/kernel/doc/src/erl_boot_server.xml index 4e7533810e..472671a80e 100644 --- a/lib/kernel/doc/src/erl_boot_server.xml +++ b/lib/kernel/doc/src/erl_boot_server.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -49,29 +49,17 @@ - start(Slaves) -> {ok, Pid} | {error, What} + Start the boot server - - Slaves = [Host] - Host = atom() - Pid = pid() - What = term() - -

Starts the boot server. Slaves is a list of IP +

Starts the boot server. Slaves is a list of IP addresses for hosts which are allowed to use this server as a boot server.

 - start_link(Slaves) -> {ok, Pid} | {error, What} + Start the boot server and links the caller - - Slaves = [Host] - Host = atom() - Pid = pid() - What = term()() -

Starts the boot server and links to the caller. This function is used to start the server if it is included in a supervision @@ -79,37 +67,23 @@ - add_slave(Slave) -> ok | {error, What} + Add a slave to the list of allowed slaves - - Slave = Host - Host = atom() - What = term() - -

Adds a Slave node to the list of allowed slave hosts.

+

Adds a Slave node to the list of allowed slave hosts.

 - delete_slave(Slave) -> ok | {error, What} + Delete a slave from the list of allowed slaves - - Slave = Host - Host = atom() - What = void() - -

Deletes a Slave node from the list of allowed slave +

Deletes a Slave node from the list of allowed slave hosts.

 - which_slaves() -> Slaves + Return the current list of allowed slave hosts - - Slaves = [Host] - Host = atom() -

Returns the current list of allowed slave hosts.

 diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml index 9a62b45d63..f9514dda2f 100644 --- a/lib/kernel/doc/src/erl_ddll.xml +++ b/lib/kernel/doc/src/erl_ddll.xml @@ -4,7 +4,7 @@
- 19972010 + 19972011 Ericsson AB. All Rights Reserved. @@ -172,6 +172,14 @@ + + + + + + + + demonitor(MonitorRef) -> ok @@ -189,37 +197,21 @@ - info() -> AllInfoList + Retrieve information about all drivers - - AllInfoList = [ DriverInfo ] - DriverInfo = {DriverName, InfoList} - DriverName = string() - InfoList = [ InfoItem ] - InfoItem = {Tag, Value} - Tag = atom() - Value = term() - -

Returns a list of tuples {DriverName, InfoList}, where - InfoList is the result of calling info/1 for that - DriverName. Only dynamically linked in drivers are +

Returns a list of tuples {DriverName, InfoList}, where + InfoList is the result of calling info/1 for that + DriverName. Only dynamically linked in drivers are included in the list.

 - info(Name) -> InfoList + Retrieve information about one driver - - Name = string() | atom() - InfoList = [ InfoItem ] - InfoItem = {Tag, Value} - Tag = atom() - Value = term() - -

Returns a list of tuples {Tag, Value}, where - Tag is the information item and Value is the result +

Returns a list of tuples {Tag, Value}, where + Tag is the information item and Value is the result of calling info/2 with this driver name and this tag. The result being a tuple list containing all information available about a driver.

@@ -305,22 +297,18 @@ - load(Path, Name) -> ok | {error, ErrorDesc} + Load a driver - - Path = Name = string() | atom() - ErrorDesc = term() - -

Loads and links the dynamic driver Name. Path +

Loads and links the dynamic driver Name. Path is a file path to the directory containing the driver. - Name must be a sharable object/dynamic library. Two - drivers with different Path parameters cannot be - loaded under the same name. The Name is a string or + Name must be a sharable object/dynamic library. Two + drivers with different Path parameters cannot be + loaded under the same name. The Name is a string or atom containing at least one character.

-

The Name given should correspond to the filename +

The Name given should correspond to the filename of the actual dynamically loadable object file residing in - the directory given as Path, but without the + the directory given as Path, but without the extension (i.e. .so). The driver name provided in the driver initialization routine must correspond with the filename, in much the same way as erlang module names @@ -328,14 +316,14 @@

If the driver has been previously unloaded, but is still present due to open ports against it, a call to load/2 will stop the unloading and keep the driver - (as long as the Path is the same) and ok is + (as long as the Path is the same) and ok is returned. If one actually wants the object code to be reloaded, one uses reload/2 or the low-level interface try_load/3 instead. Please refer to the description of different scenarios for loading/unloading in the introduction.

If more than one process tries to load an already loaded - driver withe the same Path, or if the same process + driver withe the same Path, or if the same process tries to load it several times, the function will return ok. The emulator will keep track of the load/2 calls, so that a corresponding number of @@ -349,16 +337,16 @@ several drivers with the same name but with different Path parameters.

-

Note especially that the Path is interpreted +

Note especially that the Path is interpreted literally, so that all loaders of the same driver needs to - give the same literalPath string, even + give the same literalPath string, even though different paths might point out the same directory in the filesystem (due to use of relative paths and links).

On success, the function returns ok. On - failure, the return value is {error,ErrorDesc}, - where ErrorDesc is an opaque term to be + failure, the return value is {error,ErrorDesc}, + where ErrorDesc is an opaque term to be translated into human readable form by the format_error/1 function.

For more control over the error handling, again use the @@ -369,20 +357,16 @@ - load_driver(Path, Name) -> ok | {error, ErrorDesc} + Load a driver - - Path = Name = string() | atom() - ErrorDesc = term() -

Works essentially as load/2, but will load the driver - with options other options. All ports that are using the + with other options. All ports that are using the driver will get killed with the reason driver_unloaded when the driver is to be unloaded.

The number of loads and unloads by different users influence the actual loading and unloading of a driver file. The port killing will - therefore only happen when the lastuser unloads the driver, or the + therefore only happen when the last user unloads the driver, or the last process having loaded the driver exits.

This interface (or at least the name of the functions) is kept for backward compatibility. Using try_load/3 with @@ -551,16 +535,11 @@ - reload(Path, Name) -> ok | {error, ErrorDesc} + Replace a driver - - Path = Name = string() | atom() - ErrorDesc = pending_process | OpaqueError - OpaqueError = term() - -

Reloads the driver named Name from a possibly - different Path than was previously used. This +

Reloads the driver named Name from a possibly + different Path than was previously used. This function is used in the code change scenario described in the introduction.

If there are other users @@ -574,7 +553,7 @@

If one wants to avoid hanging on open ports, one should use the try_load/3 function instead.

-

The Name and Path parameters have exactly the +

The Name and Path parameters have exactly the same meaning as when calling the plain load/2 function.

Avoid mixing @@ -594,13 +573,8 @@ - reload_driver(Path, Name) -> ok | {error, ErrorDesc} + Replace a driver - - Path = Name = string() | atom() - ErrorDesc = pending_process | OpaqueError - OpaqueError = term() -

Works exactly as reload/2, but for drivers loaded with the load_driver/2 interface.

@@ -1066,15 +1040,11 @@ - unload(Name) -> ok | {error, ErrorDesc} + Unload a driver - - Name = string() | atom() - ErrorDesc = term() -

Unloads, or at least dereferences the driver named - Name. If the caller is the last user of the driver, and there + Name. If the caller is the last user of the driver, and there are no more open ports using the driver, the driver will actually get unloaded. In all other cases, actual unloading will be delayed until all ports are closed and there are no @@ -1084,7 +1054,7 @@ is no longer considered a user of the driver. For usage scenarios, see the description in the beginning of this document.

-

The ErrorDesc returned is an opaque value to be +

The ErrorDesc returned is an opaque value to be passed further on to the format_error/1 function. For more control over the operation, use the try_unload/2 @@ -1094,15 +1064,11 @@ - unload_driver(Name) -> ok | {error, ErrorDesc} + Unload a driver - - Name = string() | atom() - ErrorDesc = term() -

Unloads, or at least dereferences the driver named - Name. If the caller is the last user of the driver, all + Name. If the caller is the last user of the driver, all remaining open ports using the driver will get killed with the reason driver_unloaded and the driver will eventually get unloaded.

@@ -1112,7 +1078,7 @@ user. For usage scenarios, see the description in the beginning of this document.

-

The ErrorDesc returned is an opaque value to be +

The ErrorDesc returned is an opaque value to be passed further on to the format_error/1 function. For more control over the operation, use the try_unload/2 @@ -1125,7 +1091,7 @@ loaded_drivers() -> {ok, Drivers} List loaded drivers - Drivers = [Driver()] + Drivers = [Driver] Driver = string() @@ -1138,13 +1104,10 @@ - format_error(ErrorDesc) -> string() + Format an error descriptor - - ErrorDesc -- see below - -

Takes an ErrorDesc returned by load, unload or +

Takes an ErrorDesc returned by load, unload or reload functions and returns a string which describes the error or warning.

diff --git a/lib/kernel/doc/src/error_handler.xml b/lib/kernel/doc/src/error_handler.xml index 7f78322472..acbf9a2c6e 100644 --- a/lib/kernel/doc/src/error_handler.xml +++ b/lib/kernel/doc/src/error_handler.xml @@ -37,48 +37,44 @@ - undefined_function(Module, Function, Args) -> term() + Called when an undefined function is encountered - - Module = Function = atom() - Args = [term()] - A (possibly empty) list of arguments Arg1,..,ArgN - + + A (possibly empty) list of arguments Arg1,..,ArgN +

This function is evaluated if a call is made to - Module:Function(Arg1,.., ArgN) and - Module:Function/N is undefined. Note that + Module:Function(Arg1,.., ArgN) and + Module:Function/N is undefined. Note that undefined_function/3 is evaluated inside the process making the original call.

-

If Module is interpreted, the interpreter is invoked +

If Module is interpreted, the interpreter is invoked and the return value of the interpreted - Function(Arg1,.., ArgN) call is returned.

+ Function(Arg1,.., ArgN) call is returned.

Otherwise, it returns, if possible, the value of - apply(Module, Function, Args) after an attempt has been - made to autoload Module. If this is not possible, the - call to Module:Function(Arg1,.., ArgN) fails with + apply(Module, Function, Args) after an attempt has been + made to autoload Module. If this is not possible, the + call to Module:Function(Arg1,.., ArgN) fails with exit reason undef.

 - undefined_lambda(Module, Fun, Args) -> term() + Called when an undefined lambda (fun) is encountered - - Module = Function = atom() - Args = [term()] - A (possibly empty) list of arguments Arg1,..,ArgN - + + A (possibly empty) list of arguments Arg1,..,ArgN +

This function is evaluated if a call is made to - Fun(Arg1,.., ArgN) when the module defining the fun is + Fun(Arg1,.., ArgN) when the module defining the fun is not loaded. The function is evaluated inside the process making the original call.

-

If Module is interpreted, the interpreter is invoked +

If Module is interpreted, the interpreter is invoked and the return value of the interpreted - Fun(Arg1,.., ArgN) call is returned.

+ Fun(Arg1,.., ArgN) call is returned.

Otherwise, it returns, if possible, the value of - apply(Fun, Args) after an attempt has been made to - autoload Module. If this is not possible, the call + apply(Fun, Args) after an attempt has been made to + autoload Module. If this is not possible, the call fails with exit reason undef.

 diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index e107d9b746..2d95f96ac7 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -65,19 +65,20 @@ be tagged as warnings or info. Tagging them as warnings may require rewriting existing user defined event handlers.

+ + + + + - error_msg(Format) -> ok - error_msg(Format, Data) -> ok - format(Format, Data) -> ok + + + Send an standard error event to the error logger - - Format = string() - Data = [term()] -

Sends a standard error event to the error logger. - The Format and Data arguments are the same as + The Format and Data arguments are the same as the arguments of io:format/2. The event is handled by the standard event handler.

@@ -94,12 +95,8 @@ ok
 - error_report(Report) -> ok + Send a standard error report event to the error logger - - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a standard error report event to the error logger. The event is handled by the standard event handler.

@@ -119,18 +116,13 @@ ok - error_report(Type, Report) -> ok + Send a user defined error report event to the error logger - - Type = term() - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a user defined error report event to the error logger. An event handler to handle the event is supposed to have been added. The event is ignored by the standard event handler.

-

It is recommended that Report follows the same +

It is recommended that Report follows the same structure as for error_report/1.

 @@ -174,16 +166,12 @@ ok - warning_msg(Format) -> ok - warning_msg(Format, Data) -> ok + + Send a standard warning event to the error logger - - Format = string() - Data = [term()] -

Sends a standard warning event to the error logger. - The Format and Data arguments are the same as + The Format and Data arguments are the same as the arguments of io:format/2. The event is handled by the standard event handler. It is tagged either as an error, warning or info, see @@ -196,12 +184,8 @@ ok - warning_report(Report) -> ok + Send a standard warning report event to the error logger - - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a standard warning report event to the error logger. The event is handled by the standard event handler. It is @@ -210,13 +194,8 @@ ok - warning_report(Type, Report) -> ok + Send a user defined warning report event to the error logger - - Type = term() - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a user defined warning report event to the error logger. An event handler to handle the event is supposed to @@ -227,16 +206,12 @@ ok - info_msg(Format) -> ok - info_msg(Format, Data) -> ok + + Send a standard information event to the error logger - - Format = string() - Data = [term()] -

Sends a standard information event to the error logger. - The Format and Data arguments are the same as + The Format and Data arguments are the same as the arguments of io:format/2. The event is handled by the standard event handler.

@@ -253,12 +228,8 @@ ok
 - info_report(Report) -> ok + Send a standard information report event to the error logger - - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a standard information report event to the error logger. The event is handled by the standard event handler.

@@ -278,63 +249,49 @@ ok - info_report(Type, Report) -> ok + Send a user defined information report event to the error logger - - Type = term() - Report = [{Tag, Data} | term()] | string() | term() -  Tag = Data = term() -

Sends a user defined information report event to the error logger. An event handler to handle the event is supposed to have been added. The event is ignored by the standard event handler.

-

It is recommended that Report follows the same +

It is recommended that Report follows the same structure as for info_report/1.

 - add_report_handler(Handler) -> Result - add_report_handler(Handler, Args) -> Result + + Add an event handler to the error logger - - Handler, Args, Result -- see gen_event:add_handler/3 -

Adds a new event handler to the error logger. The event handler must be implemented as a gen_event callback module, see gen_event(3).

-

Handler is typically the name of the callback module - and Args is an optional term (defaults to []) passed - to the initialization callback function Module:init/1. +

Handler is typically the name of the callback module + and Args is an optional term (defaults to []) passed + to the initialization callback function Handler:init/1. The function returns ok if successful.

The event handler must be able to handle the events described below.

 - delete_report_handler(Handler) -> Result + Delete an event handler from the error logger - - Handler, Result -- see gen_event:delete_handler/3 -

Deletes an event handler from the error logger by calling - gen_event:delete_handler(error_logger, Handler, []), + gen_event:delete_handler(error_logger, Handler, []), see gen_event(3).

 - tty(Flag) -> ok + Enable or disable printouts to the tty - - Flag = bool() - -

Enables (Flag == true) or disables - (Flag == false) printout of standard events to the tty.

+

Enables (Flag == true) or disables + (Flag == false) printout of standard events to the tty.

This is done by adding or deleting the standard event handler for output to tty, thus calling this function overrides the value of the Kernel error_logger configuration @@ -342,13 +299,15 @@ ok - logfile(Request) -> ok | Filename | {error, What} + + + + + + + + Enable or disable error printouts to a file - - Request = {open, Filename} | close | filename -  Filename = atom() | string() - What = allready_have_logfile | no_log_file | term() -

Enables or disables printout of standard events to a file.

This is done by adding or deleting the standard event handler @@ -361,22 +320,22 @@ ok There can only be one active log file at a time.

Request is one of:

- {open, Filename} + {open, Filename} -

Opens the log file Filename. Returns ok if +

Opens the log file Filename. Returns ok if successful, or {error, allready_have_logfile} if logging to file is already enabled, or an error tuple if - another error occurred. For example, if Filename + another error occurred. For example, if Filename could not be opened.

 close

Closes the current log file. Returns ok, or - {error, What}.

+ {error, module_not_found}.

 filename -

Returns the name of the log file Filename, or +

Returns the name of the log file Filename, or {error, no_log_file} if logging to file is not enabled.

 diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 36fce464c5..e0feaf6ee7 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -93,47 +93,76 @@ is UTF-8...

-
- DATA TYPES - -iodata() = iolist() | binary() - iolist() = [char() | binary() | iolist()] - -io_device() - as returned by file:open/2, a process handling IO protocols - -name() = string() | atom() | DeepList | RawFilename - DeepList = [char() | atom() | DeepList] - RawFilename = binary() - If VM is in unicode filename mode, string() and char() are allowed to be > 255. - RawFilename is a filename not subject to Unicode translation, meaning that it - can contain characters not conforming to the Unicode encoding expected from the - filesystem (i.e. non-UTF-8 characters although the VM is started in Unicode - filename mode). - -posix() - an atom which is named from the POSIX error codes used in - Unix, and in the runtime libraries of most C compilers - -ext_posix() = posix() | badarg + + + + + + + + + + + + + + + + +

As returned by + file:open/2, + a process handling IO protocols.

+ + + + + +

If VM is in Unicode filename mode, string() and char() + are allowed to be > 255. + RawFilename is a filename not subject to + Unicode translation, + meaning that it can contain characters not conforming to + the Unicode encoding expected from the filesystem + (i.e. non-UTF-8 characters although the VM is started + in Unicode filename mode). +

+ + + + + +

An atom which is named from the POSIX error codes used in + Unix, and in the runtime libraries of most C compilers.

+ + + + + + + + + + + +

Must denote a valid date and time.

+ + + + + + + + + + + + -time() = {{Year, Month, Day}, {Hour, Minute, Second}} - Year = Month = Day = Hour = Minute = Second = int() - Must denote a valid date and time -
- advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason} + Predeclare an access pattern for file data - - IoDevice = io_device() - Offset = int() - Length = int() - Advise = posix_file_advise() - posix_file_advise() = normal | sequential | random | no_reuse - | will_need | dont_need - Reason = ext_posix() - +

advise/4 can be used to announce an intention to access file data in a specific pattern in the future, thus allowing the @@ -142,93 +171,58 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} - change_group(Filename, Gid) -> ok | {error, Reason} + Change group of a file - - Filename = name() - Gid = int() - Reason = ext_posix() -

Changes group of a file. See write_file_info/2.

 - change_mode(Filename, Mode) -> ok | {error, Reason} + Change permissions of a file - - Filename = name() - Mode = int() - Reason = ext_posix() -

Changes permissions of a file. See write_file_info/2.

 - change_owner(Filename, Uid) -> ok | {error, Reason} + Change owner of a file - - Filename = name() - Uid = int() - Reason = ext_posix() -

Changes owner of a file. See write_file_info/2.

 - change_owner(Filename, Uid, Gid) -> ok | {error, Reason} + Change owner and group of a file - - Filename = name() - Uid = int() - Gid = int() - Reason = ext_posix() -

Changes owner and group of a file. See write_file_info/2.

 - change_time(Filename, Mtime) -> ok | {error, Reason} + Change the modification time of a file - - Filename = name() - Mtime = time() - Reason = ext_posix() -

Changes the modification and access times of a file. See write_file_info/2.

 - change_time(Filename, Mtime, Atime) -> ok | {error, Reason} + Change the modification and last access time of a file - - Filename = name() - Mtime = Atime = time() - Reason = ext_posix() -

Changes the modification and last access times of a file. See write_file_info/2.

 - close(IoDevice) -> ok | {error, Reason} + Close a file - - IoDevice = io_device() - Reason = ext_posix() | terminated - -

Closes the file referenced by IoDevice. It mostly +

Closes the file referenced by IoDevice. It mostly returns ok, expect for some severe errors such as out of memory.

Note that if the option delayed_write was @@ -238,20 +232,13 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} - consult(Filename) -> {ok, Terms} | {error, Reason} + Read Erlang terms from a file - - Filename = name() - Terms = [term()] - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

Reads Erlang terms, separated by '.', from Filename. - Returns one of the following:

+

Reads Erlang terms, separated by '.', from + Filename. Returns one of the following:

- {ok, Terms} + {ok, Terms}

The file was successfully read.

 @@ -261,7 +248,8 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang terms in the file. Use format_error/1 to convert @@ -279,53 +267,46 @@ f.txt: {person, "kalle", 25}. - copy(Source, Destination) -> - copy(Source, Destination, ByteCount) -> {ok, BytesCopied} | {error, Reason} + + Copy file contents - - Source = Destination = io_device() | Filename | {Filename, Modes} -  Filename = name() -  Modes = [Mode] -- see open/2 - ByteCount = int() >= 0 | infinity - BytesCopied = int() - -

Copies ByteCount bytes from Source to - Destination. Source and Destination refer +

Copies ByteCount bytes from + Source to Destination. + Source and Destination refer to either filenames or IO devices from e.g. open/2. - ByteCount defaults infinity, denoting an + ByteCount defaults to infinity, denoting an infinite number of bytes.

-

The argument Modes is a list of possible modes, see - open/2, and defaults to +

The argument Modes is a list of possible modes, + see open/2, and defaults to [].

-

If both Source and Destination refer to +

If both Source and + Destination refer to filenames, the files are opened with [read, binary] and [write, binary] prepended to their mode lists, respectively, to optimize the copy.

-

If Source refers to a filename, it is opened with +

If Source refers to a filename, it is opened with read mode prepended to the mode list before the copy, and closed when done.

-

If Destination refers to a filename, it is opened +

If Destination refers to a filename, it is opened with write mode prepended to the mode list before the copy, and closed when done.

-

Returns {ok, BytesCopied} where BytesCopied is +

Returns {ok, BytesCopied} where + BytesCopied is the number of bytes that actually was copied, which may be - less than ByteCount if end of file was encountered on - the source. If the operation fails, {error, Reason} is - returned.

+ less than ByteCount if end of file was + encountered on the source. If the operation fails, + {error, Reason} is returned.

Typical error reasons: As for open/2 if a file had to be opened, and as for read/2 and write/2.

 - del_dir(Dir) -> ok | {error, Reason} + Delete a directory - - Dir = name() - Reason = ext_posix() - -

Tries to delete the directory Dir. The directory must +

Tries to delete the directory Dir. + The directory must be empty before it can be deleted. Returns ok if successful.

Typical error reasons are:

@@ -333,7 +314,7 @@ f.txt: {person, "kalle", 25}. eacces

Missing search or write permissions for the parent - directories of Dir.

+ directories of Dir.

 eexist @@ -345,8 +326,8 @@ f.txt: {person, "kalle", 25}. enotdir -

A component of Dir is not a directory. On some - platforms, enoent is returned instead.

+

A component of Dir is not a directory. + On some platforms, enoent is returned instead.

 einval @@ -357,15 +338,11 @@ f.txt: {person, "kalle", 25}. - delete(Filename) -> ok | {error, Reason} + Delete a file - - Filename = name() - Reason = ext_posix() - -

Tries to delete the file Filename. Returns ok - if successful.

+

Tries to delete the file Filename. + Returns ok if successful.

Typical error reasons are:

enoent @@ -387,30 +364,25 @@ f.txt: {person, "kalle", 25}. einval -

Filename had an improper type, such as tuple.

+

Filename had an improper type, such as tuple.

 -

In a future release, a bad type for the Filename - argument will probably generate an exception.

+

In a future release, a bad type for the + Filename argument will probably generate + an exception.

 - eval(Filename) -> ok | {error, Reason} + Evaluate Erlang expressions in a file - - Filename = name() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

Reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from - Filename. The actual result of the evaluation is not - returned; any expression sequence in the file must be there + Filename. The actual result of the evaluation + is not returned; any expression sequence in the file must be there for its side effect. Returns one of the following:

ok @@ -422,7 +394,8 @@ f.txt: {person, "kalle", 25}.

An error occurred when opening the file or reading it. See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -433,18 +406,11 @@ f.txt: {person, "kalle", 25}. - eval(Filename, Bindings) -> ok | {error, Reason} + Evaluate Erlang expressions in a file - - Filename = name() - Bindings -- see erl_eval(3) - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see eval/1 -

The same as eval/1 but the variable bindings - Bindings are used in the evaluation. See + Bindings are used in the evaluation. See erl_eval(3) about variable bindings.

 @@ -458,27 +424,19 @@ f.txt: {person, "kalle", 25}. - format_error(Reason) -> Chars + Return a descriptive string for an error reason - - Reason = atom() | {Line, Mod, Term} -  Line, Mod, Term -- see eval/1 - Chars = [char() | Chars] -

Given the error reason returned by any function in this module, returns a descriptive string of the error in English.

 - get_cwd() -> {ok, Dir} | {error, Reason} + Get the current working directory - - Dir = string() - Reason = posix() - -

Returns {ok, Dir}, where Dir is the current +

Returns {ok, Dir}, where Dir + is the current working directory of the file server.

In rare circumstances, this function can fail on Unix. @@ -496,17 +454,14 @@ f.txt: {person, "kalle", 25}. - get_cwd(Drive) -> {ok, Dir} | {error, Reason} + Get the current working directory for the drive specified - - Drive = string() -- see below - Dir = string() - Reason = ext_posix() - -

Drive should be of the form "Letter:", - for example "c:". Returns {ok, Dir} or - {error, Reason}, where Dir is the current +

Drive should be of the form + "Letter:", + for example "c:". Returns {ok, Dir} or + {error, Reason}, where Dir + is the current working directory of the drive specified.

This function returns {error, enotsup} on platforms which have no concept of current drive (Unix, for example).

@@ -514,7 +469,7 @@ f.txt: {person, "kalle", 25}. enotsup -

The operating system have no concept of drives.

+

The operating system has no concept of drives.

 eacces @@ -522,32 +477,27 @@ f.txt: {person, "kalle", 25}. einval -

The format of Drive is invalid.

+

The format of Drive is invalid.

 - list_dir(Dir) -> {ok, Filenames} | {error, Reason} + List files in a directory - - Dir = name() - Filenames = [Filename] -  Filename = string() - Reason = ext_posix() -

Lists all the files in a directory. Returns - {ok, Filenames} if successful. Otherwise, it returns - {error, Reason}. Filenames is a list of + {ok, Filenames} if successful. + Otherwise, it returns {error, Reason}. + Filenames is a list of the names of all the files in the directory. The names are not sorted.

Typical error reasons are:

eacces -

Missing search or write permissions for Dir or - one of its parent directories.

+

Missing search or write permissions for Dir + or one of its parent directories.

 enoent @@ -557,14 +507,10 @@ f.txt: {person, "kalle", 25}. - make_dir(Dir) -> ok | {error, Reason} + Make a directory - - Dir = name() - Reason = ext_posix() - -

Tries to create the directory Dir. Missing parent +

Tries to create the directory Dir. Missing parent directories are not created. Returns ok if successful.

Typical error reasons are:

@@ -572,15 +518,15 @@ f.txt: {person, "kalle", 25}. eacces

Missing search or write permissions for the parent - directories of Dir.

+ directories of Dir.

 eexist -

There is already a file or directory named Dir.

+

There is already a file or directory named Dir.

 enoent -

A component of Dir does not exist.

+

A component of Dir does not exist.

 enospc @@ -588,35 +534,33 @@ f.txt: {person, "kalle", 25}. enotdir -

A component of Dir is not a directory. On some - platforms, enoent is returned instead.

+

A component of Dir is not a directory. + On some platforms, enoent is returned instead.

 - make_link(Existing, New) -> ok | {error, Reason} + Make a hard link to a file - - Existing = New = name() - Reason = ext_posix() - -

Makes a hard link from Existing to New, on +

Makes a hard link from Existing to + New, on platforms that support links (Unix). This function returns ok if the link was successfully created, or - {error, Reason}. On platforms that do not support + {error, Reason}. On platforms that do not support links, {error,enotsup} is returned.

Typical error reasons:

eacces

Missing read or write permissions for the parent - directories of Existing or New.

+ directories of Existing or + New.

 eexist -

New already exists.

+

New already exists.

 enotsup @@ -626,30 +570,28 @@ f.txt: {person, "kalle", 25}. - make_symlink(Name1, Name2) -> ok | {error, Reason} + Make a symbolic link to a file or directory - - Name1 = Name2 = name() - Reason = ext_posix() - -

This function creates a symbolic link Name2 to - the file or directory Name1, on platforms that support - symbolic links (most Unix systems). Name1 need not +

This function creates a symbolic link Name2 to + the file or directory Name1, on platforms that + support + symbolic links (most Unix systems). Name1 need not exist. This function returns ok if the link was - successfully created, or {error, Reason}. On platforms + successfully created, or {error, Reason}. + On platforms that do not support symbolic links, {error, enotsup} is returned.

Typical error reasons:

eacces -

Missing read or write permissions for the parent - directories of Name1 or Name2.

+

Missing read or write permissions for the parent directories + of Name1 or Name2.

 eexist -

Name2 already exists.

+

Name2 already exists.

 enotsup @@ -668,22 +610,12 @@ f.txt: {person, "kalle", 25}. - open(Filename, Modes) -> {ok, IoDevice} | {error, Reason} + Open a file - - Filename = name() - Modes = [Mode] -  Mode = read | write | append | exclusive | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed | {encoding, Encoding} -   Size = Delay = int() -   Encoding = latin1 | unicode | utf8 | utf16 | {utf16, Endian} | utf32 | {utf32, Endian} -     Endian = big | little - IoDevice = io_device() - Reason = ext_posix() | system_limit - -

Opens the file Filename in the mode determined by - Modes, which may contain one or more of the following - items:

+

Opens the file Filename in the mode determined + by Modes, which may contain one or more of the + following items:

read @@ -841,23 +773,23 @@ f.txt: {person, "kalle", 25}.

Returns:

- {ok, IoDevice} + {ok, IoDevice}

The file has been opened in the requested mode. - IoDevice is a reference to the file.

+ IoDevice is a reference to the file.

 - {error, Reason} + {error, Reason}

The file could not be opened.

 -

IoDevice is really the pid of the process which +

IoDevice is really the pid of the process which handles the file. This process is linked to the process which originally opened the file. If any process to which - the IoDevice is linked terminates, the file will be - closed and the process itself will be terminated. - An IoDevice returned from this call can be used as an - argument to the IO functions (see + the IoDevice is linked terminates, the file will + be closed and the process itself will be terminated. + An IoDevice returned from this call can be used + as an argument to the IO functions (see io(3)).

In previous versions of file, modes were given @@ -897,34 +829,25 @@ f.txt: {person, "kalle", 25}. - path_consult(Path, Filename) -> {ok, Terms, FullName} | {error, Reason} + Read Erlang terms from a file - - Path = [Dir] -  Dir = name() - Filename = name() - Terms = [term()] - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

Searches the path Path (a list of directory names) - until the file Filename is found. If Filename - is an absolute filename, Path is ignored. +

Searches the path Path (a list of directory + names) until the file Filename is found. + If Filename + is an absolute filename, Path is ignored. Then reads Erlang terms, separated by '.', from the file. Returns one of the following:

- {ok, Terms, FullName} + {ok, Terms, FullName} -

The file was successfully read. FullName is +

The file was successfully read. FullName is the full name of the file.

 {error, enoent}

The file could not be found in any of the directories in - Path.

+ Path.

 {error, atom()} @@ -932,7 +855,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang terms in the file. Use format_error/1 to convert @@ -943,36 +867,28 @@ f.txt: {person, "kalle", 25}. - path_eval(Path, Filename) -> {ok, FullName} | {error, Reason} + Evaluate Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

Searches the path Path (a list of directory names) - until the file Filename is found. If Filename - is an absolute file name, Path is ignored. Then reads +

Searches the path Path (a list of directory + names) until the file Filename is found. + If Filename is an absolute file name, + Path is ignored. Then reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from the file. The actual result of evaluation is not returned; any expression sequence in the file must be there for its side effect. Returns one of the following:

- {ok, FullName} + {ok, FullName} -

The file was read and evaluated. FullName is +

The file was read and evaluated. FullName is the full name of the file.

 {error, enoent}

The file could not be found in any of the directories in - Path.

+ Path.

 {error, atom()} @@ -980,7 +896,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -991,34 +908,26 @@ f.txt: {person, "kalle", 25}. - path_open(Path, Filename, Modes) -> {ok, IoDevice, FullName} | {error, Reason} + Open a file - - Path = [Dir] -  Dir = name() - Filename = name() - Modes = [Mode] -- see open/2 - IoDevice = io_device() - FullName = string() - Reason = ext_posix() | system_limit - -

Searches the path Path (a list of directory names) - until the file Filename is found. If Filename - is an absolute file name, Path is ignored. - Then opens the file in the mode determined by Modes. +

Searches the path Path (a list of directory + names) until the file Filename is found. + If Filename + is an absolute file name, Path is ignored. + Then opens the file in the mode determined by Modes. Returns one of the following:

- {ok, IoDevice, FullName} + {ok, IoDevice, FullName}

The file has been opened in the requested mode. - IoDevice is a reference to the file and - FullName is the full name of the file.

+ IoDevice is a reference to the file and + FullName is the full name of the file.

 {error, enoent}

The file could not be found in any of the directories in - Path.

+ Path.

 {error, atom()} @@ -1028,36 +937,27 @@ f.txt: {person, "kalle", 25}. - path_script(Path, Filename) -> {ok, Value, FullName} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - Value = term() - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

Searches the path Path (a list of directory names) - until the file Filename is found. If Filename - is an absolute file name, Path is ignored. Then reads +

Searches the path Path (a list of directory + names) until the file Filename is found. + If Filename is an absolute file name, + Path is ignored. Then reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from the file. Returns one of the following:

- {ok, Value, FullName} + {ok, Value, FullName} -

The file was read and evaluated. FullName is - the full name of the file and Value the value of +

The file was read and evaluated. FullName is + the full name of the file and Value the value of the last expression.

 {error, enoent}

The file could not be found in any of the directories in - Path.

+ Path.

 {error, atom()} @@ -1065,7 +965,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -1076,42 +977,28 @@ f.txt: {person, "kalle", 25}. - path_script(Path, Filename, Bindings) -> {ok, Value, FullName} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - Bindings -- see erl_eval(3) - Value = term() - FullName = string() - Reason = posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see path_script/2 -

The same as path_script/2 but the variable bindings - Bindings are used in the evaluation. See + Bindings are used in the evaluation. See erl_eval(3) about variable bindings.

 - pid2name(Pid) -> string() | undefined + Return the name of the file handled by a pid - - Pid = pid() - -

If Pid is an IO device, that is, a pid returned from +

If Pid is an IO device, that is, a pid returned from open/2, this function returns the filename, or rather:

- {ok, Filename} + {ok, Filename}

If this node's file server is not a slave, the file was opened by this node's file server, (this implies that - Pid must be a local pid) and the file is not - closed. Filename is the filename in flat string + Pid must be a local pid) and the file is not + closed. Filename is the filename in flat string format.

 undefined @@ -1125,21 +1012,15 @@ f.txt: {person, "kalle", 25}. - position(IoDevice, Location) -> {ok, NewPosition} | {error, Reason} + Set position in a file - - IoDevice = io_device() - Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof -  Offset = int() - NewPosition = int() - Reason = ext_posix() | terminated - -

Sets the position of the file referenced by IoDevice - to Location. Returns {ok, NewPosition} (as +

Sets the position of the file referenced by IoDevice + to Location. Returns + {ok, NewPosition} (as absolute offset) if successful, otherwise - {error, Reason}. Location is one of - the following:

+ {error, Reason}. Location is + one of the following:

Offset @@ -1167,7 +1048,8 @@ f.txt: {person, "kalle", 25}. einval -

Either Location was illegal, or it evaluated to a +

Either Location was illegal, or it + evaluated to a negative offset in the file. Note that if the resulting position is a negative value, the result is an error, and after the call the file position is undefined.

@@ -1176,22 +1058,14 @@ f.txt: {person, "kalle", 25}. - pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason} + Read from a file at certain positions - - IoDevice = io_device() - LocNums = [{Location, Number}] -  Location -- see position/2 -  Number = int() - DataL = [Data] -  Data = [char()] | binary() - Reason = ext_posix() | terminated -

Performs a sequence of pread/3 in one operation, which is more efficient than calling them one at a time. - Returns {ok, [Data, ...]} or {error, Reason}, - where each Data, the result of the corresponding + Returns {ok, [Data, ...]} or + {error, Reason}, + where each Data, the result of the corresponding pread, is either a list or a binary depending on the mode of the file, or eof if the requested position was beyond end of file.

@@ -1199,76 +1073,53 @@ f.txt: {person, "kalle", 25}. - pread(IoDevice, Location, Number) -> {ok, Data} | eof | {error, Reason} + Read from a file at a certain position - - IoDevice = io_device() - Location -- see position/2 - Number = int() - Data = [char()] | binary() - Reason = ext_posix() | terminated -

Combines position/2 and read/2 in one operation, which is more efficient than calling them one at a - time. If IoDevice has been opened in raw mode, some - restrictions apply: Location is only allowed to be an + time. If IoDevice has been opened in raw mode, + some restrictions apply: Location is only allowed + to be an integer; and the current position of the file is undefined after the operation.

As the position is given as a byte-offset, special caution has to be taken when working with files where encoding is set to something else than latin1, as not every byte position will be a valid character boundary on such a file.

 - pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}} + Write to a file at certain positions - - IoDevice = io_device() - LocBytes = [{Location, Bytes}] -  Location -- see position/2 -  Bytes = iodata() - N = int() - Reason = ext_posix() | terminated -

Performs a sequence of pwrite/3 in one operation, which is more efficient than calling them one at a time. - Returns ok or {error, {N, Reason}}, where - N is the number of successful writes that was done + Returns ok or {error, {N, + Reason}}, where + N is the number of successful writes that was done before the failure.

When positioning in a file with other encoding than latin1, caution must be taken to set the position on a correct character boundary, see position/2 for details.

 - pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason} + Write to a file at a certain position - - IoDevice = io_device() - Location -- see position/2 - Bytes = iodata() - Reason = ext_posix() | terminated -

Combines position/2 and write/2 in one operation, which is more efficient than calling them one at a - time. If IoDevice has been opened in raw mode, some - restrictions apply: Location is only allowed to be an + time. If IoDevice has been opened in raw mode, + some restrictions apply: Location is only allowed + to be an integer; and the current position of the file is undefined after the operation.

When positioning in a file with other encoding than latin1, caution must be taken to set the position on a correct character boundary, see position/2 for details.

 - read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason} + Read from a file - - IoDevice = io_device() - Number = int() - Data = [char()] | binary() - Reason = ext_posix() | terminated - -

Reads Number bytes/characters from the file referenced by - IoDevice. The functions read/2, pread/3 +

Reads Number bytes/characters from the file + referenced by IoDevice. The functions + read/2, pread/3 and read_line/1 are the only ways to read from a file opened in raw mode (although they work for normally opened files, too).

@@ -1276,7 +1127,7 @@ f.txt: {person, "kalle", 25}.

Also if encoding is set to something else than latin1, the read/3 call will fail if the data contains characters larger than 255, why the io(3) module is to be preferred when reading such a file.

The function returns:

- {ok, Data} + {ok, Data}

If the file was opened in binary mode, the read bytes are returned in a binary, otherwise in a list. The list or @@ -1285,10 +1136,10 @@ f.txt: {person, "kalle", 25}. eof -

Returned if Number>0 and end of file was reached - before anything at all could be read.

+

Returned if Number>0 and end of file was + reached before anything at all could be read.

 - {error, Reason} + {error, Reason}

An error occurred.

 @@ -1307,17 +1158,14 @@ f.txt: {person, "kalle", 25}. - read_file(Filename) -> {ok, Binary} | {error, Reason} + Read a file - - Filename = name() - Binary = binary() - Reason = ext_posix() | terminated | system_limit - -

Returns {ok, Binary}, where Binary is a binary - data object that contains the contents of Filename, or - {error, Reason} if an error occurs.

+

Returns {ok, Binary}, where + Binary is a binary + data object that contains the contents of + Filename, or + {error, Reason} if an error occurs.

Typical error reasons:

enoent @@ -1346,17 +1194,13 @@ f.txt: {person, "kalle", 25}. - read_file_info(Filename) -> {ok, FileInfo} | {error, Reason} + Get information about a file - - Filename = name() - FileInfo = #file_info{} - Reason = ext_posix() -

Retrieves information about a file. Returns - {ok, FileInfo} if successful, otherwise - {error, Reason}. FileInfo is a record + {ok, FileInfo} if successful, otherwise + {error, Reason}. FileInfo + is a record file_info, defined in the Kernel include file file.hrl. Include the following directive in the module from which the function is called:

@@ -1364,7 +1208,7 @@ f.txt: {person, "kalle", 25}. -include_lib("kernel/include/file.hrl").

The record file_info contains the following fields.

- size = int() + size = integer()

Size of file in bytes.

 @@ -1391,7 +1235,7 @@ f.txt: {person, "kalle", 25}. the file or the inode was changed. In Windows, it is the create time.

- mode = int() + mode = integer()

The file permissions as the sum of the following bit values:

@@ -1422,33 +1266,33 @@ f.txt: {person, "kalle", 25}.

On Unix platforms, other bits than those listed above may be set.

 - links = int() + links = integer()

Number of links to the file (this will always be 1 for file systems which have no concept of links).

 - major_device = int() + major_device = integer()

Identifies the file system where the file is located. In Windows, the number indicates a drive as follows: 0 means A:, 1 means B:, and so on.

 - minor_device = int() + minor_device = integer()

Only valid for character devices on Unix. In all other cases, this field is zero.

 - inode = int() + inode = integer()

Gives the inode number. On non-Unix file systems, this field will be zero.

 - uid = int() + uid = integer()

Indicates the owner of the file. Will be zero for non-Unix file systems.

 - gid = int() + gid = integer()

Gives the group that the owner of the file belongs to. Will be zero for non-Unix file systems.

@@ -1474,21 +1318,16 @@ f.txt: {person, "kalle", 25}. - read_line(IoDevice) -> {ok, Data} | eof | {error, Reason} + Read a line from a file - - IoDevice = io_device() - Data = [char()] | binary() - Reason = ext_posix() | terminated -

Reads a line of bytes/characters from the file referenced by - IoDevice. Lines are defined to be delimited by the linefeed (LF, \n) character, but any carriage return (CR, \r) followed by a newline is also treated as a single LF character (the carriage return is silently ignored). The line is returned including the LF, but excluding any CR immediately followed by a LF. This behaviour is consistent with the behaviour of io:get_line/2. If end of file is reached without any LF ending the last line, a line with no trailing LF is returned.

+ IoDevice. Lines are defined to be delimited by the linefeed (LF, \n) character, but any carriage return (CR, \r) followed by a newline is also treated as a single LF character (the carriage return is silently ignored). The line is returned including the LF, but excluding any CR immediately followed by a LF. This behaviour is consistent with the behaviour of io:get_line/2. If end of file is reached without any LF ending the last line, a line with no trailing LF is returned.

The function can be used on files opened in raw mode. It is however inefficient to use it on raw files if the file is not opened with the option {read_ahead, Size} specified, why combining raw and {read_ahead, Size} is highly recommended when opening a text file for raw line oriented reading.

If encoding is set to something else than latin1, the read_line/1 call will fail if the data contains characters larger than 255, why the io(3) module is to be preferred when reading such a file.

The function returns:

- {ok, Data} + {ok, Data}

One line from the file is returned, including the trailing LF, but with CRLF sequences replaced by a single LF (see above).

If the file was opened in binary mode, the read bytes are @@ -1499,7 +1338,7 @@ f.txt: {person, "kalle", 25}.

Returned if end of file was reached before anything at all could be read.

 - {error, Reason} + {error, Reason}

An error occurred.

 @@ -1518,23 +1357,19 @@ f.txt: {person, "kalle", 25}. - read_link(Name) -> {ok, Filename} | {error, Reason} + See what a link is pointing to - - Name = name() - Filename = string() - Reason = ext_posix() - -

This function returns {ok, Filename} if Name - refers to a symbolic link or {error, Reason} otherwise. +

This function returns {ok, Filename} if + Name refers to a symbolic link or + {error, Reason} otherwise. On platforms that do not support symbolic links, the return value will be {error,enotsup}.

Typical error reasons:

einval -

Linkname does not refer to a symbolic link.

+

Name does not refer to a symbolic link.

 enoent @@ -1548,34 +1383,26 @@ f.txt: {person, "kalle", 25}. - read_link_info(Name) -> {ok, FileInfo} | {error, Reason} + Get information about a link or file - - Name = name() - FileInfo = #file_info{}, see read_file_info/1 - Reason = ext_posix() -

This function works like read_file_info/1, except that - if Name is a symbolic link, information about the link - will be returned in the file_info record and + if Name is a symbolic link, information about + the link will be returned in the file_info record and the type field of the record will be set to symlink.

-

If Name is not a symbolic link, this function returns +

If Name is not a symbolic link, this function returns exactly the same result as read_file_info/1. On platforms that do not support symbolic links, this function is always equivalent to read_file_info/1.

 - rename(Source, Destination) -> ok | {error, Reason} + Rename a file - - Source = Destination = name() - Reason = ext_posix() - -

Tries to rename the file Source to Destination. +

Tries to rename the file Source to + Destination. It can be used to move files (and directories) between directories, but it is not sufficient to specify the destination only. The destination file name must also be @@ -1593,25 +1420,28 @@ f.txt: {person, "kalle", 25}. eacces

Missing read or write permissions for the parent - directories of Source or Destination. On + directories of Source or + Destination. On some platforms, this error is given if either - Source or Destination is open.

+ Source or Destination + is open.

eexist -

Destination is not an empty directory. On some - platforms, also given when Source and - Destination are not of the same type.

+

Destination is not an empty directory. + On some platforms, also given when Source and + Destination are not of the same type.

 einval -

Source is a root directory, or Destination - is a sub-directory of Source.

+

Source is a root directory, or + Destination + is a sub-directory of Source.

 eisdir -

Destination is a directory, but Source is - not.

+

Destination is a directory, but + Source is not.

 enoent @@ -1619,35 +1449,28 @@ f.txt: {person, "kalle", 25}. enotdir -

Source is a directory, but Destination is - not.

+

Source is a directory, but + Destination is not.

 exdev -

Source and Destination are on different - file systems.

+

Source and Destination + are on different file systems.

 - script(Filename) -> {ok, Value} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Filename = name() - Value = term() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

Reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from the file. Returns one of the following:

- {ok, Value} + {ok, Value} -

The file was read and evaluated. Value is +

The file was read and evaluated. Value is the value of the last expression.

 {error, atom()} @@ -1656,7 +1479,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -1667,33 +1491,21 @@ f.txt: {person, "kalle", 25}. - script(Filename, Bindings) -> {ok, Value} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Filename = name() - Bindings -- see erl_eval(3) - Value = term() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

The same as script/1 but the variable bindings - Bindings are used in the evaluation. See + Bindings are used in the evaluation. See erl_eval(3) about variable bindings.

 - set_cwd(Dir) -> ok | {error,Reason} + Set the current working directory - - Dir = name() - Reason = ext_posix() -

Sets the current working directory of the file server to - Dir. Returns ok if successful.

+ Dir. Returns ok if successful.

Typical error reasons are:

enoent @@ -1702,8 +1514,8 @@ f.txt: {person, "kalle", 25}. enotdir -

A component of Dir is not a directory. On some - platforms, enoent is returned.

+

A component of Dir is not a directory. + On some platforms, enoent is returned.

 eacces @@ -1712,23 +1524,21 @@ f.txt: {person, "kalle", 25}. badarg -

Filename had an improper type, such as tuple.

+

Dir had an improper type, + such as tuple.

 -

In a future release, a bad type for the Filename +

In a future release, a bad type for the + Dir argument will probably generate an exception.

 - sync(IoDevice) -> ok | {error, Reason} + Synchronizes the in-memory state of a file with that on the physical medium - - IoDevice = io_device() - Reason = ext_posix() | terminated -

Makes sure that any buffers kept by the operating system (not by the Erlang runtime system) are written to disk. On @@ -1743,12 +1553,8 @@ f.txt: {person, "kalle", 25}. - datasync(IoDevice) -> ok | {error, Reason} + Synchronizes the in-memory data of a file, ignoring most of its metadata, with that on the physical medium - - IoDevice = io_device() - Reason = ext_posix() | terminated -

Makes sure that any buffers kept by the operating system (not by the Erlang runtime system) are written to disk. In @@ -1770,32 +1576,23 @@ f.txt: {person, "kalle", 25}. - truncate(IoDevice) -> ok | {error, Reason} + Truncate a file - - IoDevice = io_device() - Reason = ext_posix() | terminated - -

Truncates the file referenced by IoDevice at +

Truncates the file referenced by IoDevice at the current position. Returns ok if successful, - otherwise {error, Reason}.

+ otherwise {error, Reason}.

 - write(IoDevice, Bytes) -> ok | {error, Reason} + Write to a file - - IoDevice = io_device() - Bytes = iodata() - Reason = ext_posix() | terminated - -

Writes Bytes to the file referenced by - IoDevice. This function is the only way to write to a +

Writes Bytes to the file referenced by + IoDevice. This function is the only way to write to a file opened in raw mode (although it works for normally opened files, too). Returns ok if successful, and - {error, Reason} otherwise.

+ {error, Reason} otherwise.

If the file is opened with encoding set to something else than latin1, each byte written might result in several bytes actually being written to the file, as the byte range 0..255 might represent anything between one and four bytes depending on value and UTF encoding type.

Typical error reasons are:

@@ -1811,18 +1608,14 @@ f.txt: {person, "kalle", 25}. - write_file(Filename, Bytes) -> ok | {error, Reason} + Write a file - - Filename = name() - Bytes = iodata() - Reason = ext_posix() | terminated | system_limit - -

Writes the contents of the iodata term Bytes to the - file Filename. The file is created if it does not +

Writes the contents of the iodata term Bytes + to the file Filename. + The file is created if it does not exist. If it exists, the previous contents are - overwritten. Returns ok, or {error, Reason}.

+ overwritten. Returns ok, or {error, Reason}.

Typical error reasons are:

enoent @@ -1851,33 +1644,23 @@ f.txt: {person, "kalle", 25}. - write_file(Filename, Bytes, Modes) -> ok | {error, Reason} + Write a file - - Filename = name() - Bytes = iodata() - Modes = [Mode] -- see open/2 - Reason = ext_posix() | terminated | system_limit -

Same as write_file/2, but takes a third argument - Modes, a list of possible modes, see + Modes, a list of possible modes, see open/2. The mode flags binary and write are implicit, so they should not be used.

 - write_file_info(Filename, FileInfo) -> ok | {error, Reason} + Change information about a file - - Filename = name() - FileInfo = #file_info{} -- see also read_file_info/1 - Reason = ext_posix() -

Change file information. Returns ok if successful, - otherwise {error, Reason}. FileInfo is a record + otherwise {error, Reason}. + FileInfo is a record file_info, defined in the Kernel include file file.hrl. Include the following directive in the module from which the function is called:

@@ -1901,7 +1684,7 @@ f.txt: {person, "kalle", 25}. time). On Windows, this field is the new creation time to set for the file.

- mode = int() + mode = integer()

The file permissions as the sum of the following bit values:

@@ -1932,12 +1715,12 @@ f.txt: {person, "kalle", 25}.

On Unix platforms, other bits than those listed above may be set.

 - uid = int() + uid = integer()

Indicates the owner of the file. Ignored for non-Unix file systems.

 - gid = int() + gid = integer()

Gives the group that the owner of the file belongs to. Ignored non-Unix file systems.

diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml index fb09092f1c..5ceb82ae41 100644 --- a/lib/kernel/doc/src/gen_sctp.xml +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -4,7 +4,7 @@
- 20072010 + 20072011 Ericsson AB. All Rights Reserved. @@ -65,77 +65,71 @@ SEE ALSO AUTHORS + -
- - DATA TYPES - - - assoc_id() - + + + +

An opaque term returned in for example #sctp_paddr_change{} that identifies an association for an SCTP socket. The term is opaque except for the special value 0 that has a - meaning such as "the whole endpoint" or "all future associations".

- - - charlist() = [char()] - - - iolist() = [char() | binary()] - - - ip_address() - + meaning such as "the whole endpoint" or "all future associations". +

+ + + + + + + +

Represents an address of an SCTP socket. It is a tuple as explained in inet(3).

- - - port_number() = 0 .. 65535 - - - posix() - -

See - inet(3); POSIX Error Codes.

- - - sctp_option() - + + + + + + + + +

See + inet(3); POSIX Error Codes.

+ + + + +

One of the SCTP Socket Options.

- - sctp_socket() - + + + + +

Socket identifier returned from open/*.

- - - timeout() = int() | infinity - -

Timeout used in SCTP connect and receive calls.

- - - -
+ + + + + - abort(sctp_socket(), Assoc) -> ok | {error, posix()} + Abnormally terminate the association given by Assoc, without flushing of unsent data - - Assoc = #sctp_assoc_change{} - -

Abnormally terminates the association given by Assoc, without +

Abnormally terminates the association given by Assoc, without flushing of unsent data. The socket itself remains open. Other associations opened on this socket are still valid, and it can be used in new associations.

 - close(sctp_socket()) -> ok | {error, posix()} + Completely close the socket and all associations on it

Completely closes the socket and all associations on it. The unsent @@ -148,35 +142,26 @@ - connect(Socket, Addr, Port, Opts) -> {ok,Assoc} | {error, posix()} + Same as connect(Socket, Addr, Port, Opts, infinity). -

Same as connect(Socket, Addr, Port, Opts, infinity).

+

Same as connect(Socket, Addr, Port, Opts, infinity).

 - connect(Socket, Addr, Port, [Opt], Timeout) -> {ok, Assoc} | {error, posix()} + Establish a new association for the socket Socket, with a peer (SCTP server socket) - - Socket = sctp_socket() - Addr = ip_address() | Host - Port = port_number() - Opt = sctp_option() - Timeout = timeout() - Host = atom() | string() - Assoc = #sctp_assoc_change{} - -

Establishes a new association for the socket Socket, +

Establishes a new association for the socket Socket, with the peer (SCTP server socket) given by - Addr and Port. The Timeout, + Addr and Port. The Timeout, is expressed in milliseconds. A socket can be associated with multiple peers.

-

WARNING:Using a value of Timeout less than +

WARNING:Using a value of Timeout less than the maximum time taken by the OS to establish an association (around 4.5 minutes if the default values from RFC 4960 are used) can result in inconsistent or incorrect return values. This is especially - relevant for associations sharing the same Socket + relevant for associations sharing the same Socket (i.e. source address and port) since the controlling process blocks until connect/* returns. connect_init/* @@ -185,7 +170,7 @@

The result of connect/* is an #sctp_assoc_change{} event which contains, in particular, the new - Association ID:

+ Association ID.

   #sctp_assoc_change{
         state             = atom(),
@@ -198,13 +183,13 @@
           giving an sctp_initmsg option to connect
           as in:

         
-  connect(Socket, Ip, Port,
+  connect(Socket, Ip, Port,
         [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
                                      max_instreams=MaxInStreams}}])        

-        
All options Opt are set on the socket before the 
+        
All options Opt are set on the socket before the
           association is attempted. If an option record has got undefined
           field values, the options record is first read from the socket
-          for those values. In effect, Opt option records only 
+          for those values. In effect, Opt option records only
           define field values to change before connecting.

         
The returned outbound_streams and inbound_streams
           are the actual stream numbers on the socket, which may be different
@@ -242,27 +227,19 @@
       
     
     
-      connect_init(Socket, Addr, Port, Opts) -> ok | {error, posix()}
+      
       Same as connect_init(Socket, Addr, Port, Opts, infinity).
       
-        
Same as connect_init(Socket, Addr, Port, Opts, infinity).

+        
Same as connect_init(Socket, Addr, Port, Opts, infinity).

       
     
     
-      connect_init(Socket, Addr, Port, [Opt], Timeout) -> ok | {error, posix()}
+      
       Initiate a new association for the socket Socket, with a peer (SCTP server socket)
-      
-        Socket  = sctp_socket()
-        Addr    = ip_address() | Host
-        Port    = port_number()
-        Opt     = sctp_option()
-        Timeout = timeout()
-        Host    = atom() | string()
-      
       
-        
Initiates a new association for the socket Socket,
+        
Initiates a new association for the socket Socket,
           with the peer (SCTP server socket) given by
-          Addr and Port.

+          Addr and Port.

 	
The fundamental difference between this API
 	and connect/* is that the return value is that of the
 	underlying OS connect(2) system call. If ok is returned
@@ -275,64 +252,52 @@
 	active option.

 	
The parameters are as described
 	in connect/*, with the
-	exception of the Timeout value.

-	
The timer associated with Timeout only supervises
-	IP resolution of Addr

+	exception of the Timeout value.

+	
The timer associated with Timeout only supervises
+	IP resolution of Addr

       
     
     
-      controlling_process(sctp_socket(), pid()) -> ok
+      
       Assign a new controlling process pid to the socket
       
-        
Assigns a new controlling process Pid to Socket. Same implementation
+        
Assigns a new controlling process Pid to Socket. Same implementation
           as gen_udp:controlling_process/2.

       
     
     
-      eof(Socket, Assoc) -> ok | {error, Reason}
+      
       Gracefully terminate the association given by Assoc, with flushing of all unsent data
-      
-        Socket = sctp_socket()
-        Assoc  = #sctp_assoc_change{}
-      
       
-        
Gracefully terminates the association given by Assoc, with
+        
Gracefully terminates the association given by Assoc, with
           flushing of all unsent data. The socket itself remains open. Other
           associations opened on this socket are still valid, and it can be
           used in new associations.

       
     
     
-      listen(Socket, IsServer) -> ok | {error, Reason}
+      
       Set up a socket to listen.
-      
-        Socket   = sctp_socket()
-        IsServer = bool()
-      
       
         
Sets up a socket to listen on the IP address and port number
-          it is bound to. IsServer must be 'true' or 'false'.
+          it is bound to. IsServer must be true
+          or false.
           In the contrast to TCP, in SCTP there is no listening queue length.
-          If IsServer is 'true' the socket accepts new associations, i.e.
+          If IsServer is true the socket accepts new associations, i.e.
           it will become an SCTP server socket.

       
     
     
-      open() -> {ok, Socket} | {error, posix()}
-      open(Port) -> {ok, Socket} | {error, posix()}
-      open([Opt]) -> {ok, Socket} | {error, posix()}
-      open(Port, [Opt]) -> {ok, Socket} | {error, posix()}
+      
+      
+      
+      
       Create an SCTP socket and bind it to local addresses
-      
-        Opt  = {ip,IP} | {ifaddr,IP} | {port,Port} | sctp_option()
-        IP   = ip_address() | any | loopback
-        Port = port_number()
-      
       
         
Creates an SCTP socket and binds it to the local addresses 
-          specified by all {ip,IP} (or synonymously {ifaddr,IP})
+          specified by all {ip,IP} (or synonymously {ifaddr,IP})
           options (this feature is called SCTP multi-homing).
-          The default IP and Port are any 
+          The default IP and Port are any
           and 0, meaning bind to all local addresses on any
           one free port.

         
A default set of socket options
@@ -345,27 +310,16 @@
       
     
     
-      recv(sctp_socket()) -> {ok, {FromIP, FromPort, AncData, BinMsg}} | {error, Reason}
-      recv(sctp_socket(), timeout()) -> {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
+      
+      
       Receive a message from a socket
-      
-        FromIP   = ip_address()
-        FromPort = port_number()
-        AncData  = [#sctp_sndrcvinfo{}]
-        Data     = binary() | charlist() | #sctp_sndrcvinfo{} |
-                      #sctp_assoc_change{} | #sctp_paddr_change{} |
-                      #sctp_adaptation_event{} 
-        Reason   = posix() | #sctp_send_failed{} | #scpt_paddr_change{} |
-                      #sctp_pdapi_event{} | #sctp_remote_error{} |
-                      #sctp_shutdown_event{}
-      
       
-        
Receives the Data message from any association of the socket.
+        
Receives the Data message from any association of the socket.
           If the receive times out {error,timeout is returned.
           The default timeout is infinity.
-          FromIP and FromPort indicate the sender's address.

-        
AncData is a list of Ancillary Data items which
-          may be received along with the main Data.
+          FromIP and FromPort indicate the sender's address.

+        
AncData is a list of Ancillary Data items which
+          may be received along with the main Data.
           This list can be empty, or contain a single
           #sctp_sndrcvinfo{}
           record, if receiving of such ancillary data is enabled
@@ -375,10 +329,10 @@
           provide an easy way of determining the association and stream
           over which the message has been received.
           (An alternative way would be to get the Association ID from the
-          FromIP and FromPort using the
+          FromIP and FromPort using the
           sctp_get_peer_addr_info socket option,
           but this would still not produce the Stream number).

-        
The actual Data received may be a binary(),
+        
The actual Data received may be a binary(),
           or list() of bytes (integers in the range 0 through 255)
           depending on the socket mode, or an SCTP Event.
                     
@@ -476,15 +430,10 @@
       
     
     
-      send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
+      
       Send a message using an #sctp_sndrcvinfo{}record
-      
-        Socket     = sctp_socket()
-        SndRcvInfo = #sctp_sndrcvinfo{}
-        Data       = binary() | iolist()
-      
       
-        
Sends the Data message with all sending parameters from a
+        
Sends the Data message with all sending parameters from a
           #sctp_sndrcvinfo{} record.
           This way, the user can specify the PPID (passed to the remote end)
           and Context (passed to the local SCTP layer) which can be used
@@ -494,21 +443,15 @@
       
     
     
-      send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
+      
       Send a message over an existing association and given stream
-      
-        Socket = sctp_socket()
-        Assoc  = #sctp_assoc_change{} | assoc_id()
-        Stream = integer()
-        Data   = binary() | iolist()
-      
       
-        
Sends Data message over an existing association and given
+        
Sends Data message over an existing association and given
           stream.

       
     
     
-      error_string(integer()) -> ok | string() | undefined
+      
       Translate an SCTP error number into a string
       
         
Translates an SCTP error number from for example 
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index aa171c77c2..f1d42d9faa 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -4,7 +4,7 @@
 
   

     
-      19972010
+      19972011
       Ericsson AB. All Rights Reserved.
     
     
@@ -63,36 +63,45 @@ do_recv(Sock, Bs) ->
     
For more examples, see the examples section.

   
 
-  

-    DATA TYPES
-    
-ip_address()
-  see inet(3)
-
-posix()
-  see inet(3)
+  
+    
+      
+    
+    
+      
+      
+        
Represents an address of a TCP socket.
+          It is a tuple as explained in
+          inet(3).

+      
+    
+    
+      
+    
+    
+      
+      
+        
See 
+        inet(3); POSIX Error Codes.

+      
+    
+    
+      socket()
+      
+        
As returned by accept/1,2 and connect/3,4.

+        
+      
+    
+  
 
-socket()
-  as returned by accept/1,2 and connect/3,4
-    
-  

   
     
-      connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}
-      connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}
+      
+      
       Connect to a TCP port
-      
-        Address = string() | atom() | ip_address()
-        Port = 0..65535
-        Options = [Opt]
-         Opt -- see below
-        Timeout = int() | infinity
-        Socket = socket()
-        Reason = posix()
-      
       
-        
Connects to a server on TCP port Port on the host
-          with IP address Address. The Address argument
+        
Connects to a server on TCP port Port on the host
+          with IP address Address. The Address argument
           can be either a hostname, or an IP address.

         
The available options are:

         
@@ -127,13 +136,13 @@ socket()
           
             
Set up the socket for IPv4.

           
-          Opt
+          Opt
           
             
See
               inet:setopts/2.

           
         
-        
Packets can be sent to the returned socket Socket
+        
Packets can be sent to the returned socket Socket
           using send/2. Packets sent from the peer are delivered
           as messages:

         
@@ -148,7 +157,7 @@ socket()
         
unless {active, false} is specified in the option list
           for the socket, in which case packets are retrieved by
           calling recv/2.

-        
The optional Timeout parameter specifies a timeout in
+        
The optional Timeout parameter specifies a timeout in
           milliseconds. The default value is infinity.

         
           
The default values for options given to connect can
@@ -159,19 +168,12 @@ socket()
       
     
     
-      listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}
+      
       Set up a socket to listen on a port
-      
-        Port = 0..65535
-        Options = [Opt]
-         Opt -- see below
-        ListenSocket -- see below
-        Reason = posix()
-      
       
-        
Sets up a socket to listen on the port Port on
+        
Sets up a socket to listen on the port Port on
           the local host.

-        
If Port == 0, the underlying OS assigns an available
+        
If Port == 0, the underlying OS assigns an available
           port number, use inet:port/1 to retrieve it.

         
The available options are:

         
@@ -214,7 +216,7 @@ socket()
               inet:setopts/2.

           
         
-        
The returned socket ListenSocket can only be used in
+        
The returned socket ListenSocket can only be used in
           calls to accept/1,2.

         
           
The default values for options given to listen can
@@ -225,27 +227,23 @@ socket()
       
     
     
-      accept(ListenSocket) -> {ok, Socket} | {error, Reason}
-      accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason}
+      
+      
       Accept an incoming connection request on a listen socket
-      
-        ListenSocket -- see listen/2
-        Timeout = int() | infinity
-        Socket = socket()
-        Reason = closed | timeout | posix()
-      
+      Returned by listen/2.
+      
       
         
Accepts an incoming connection request on a listen socket.
-          Socket must be a socket returned from listen/2.
-          Timeout specifies a timeout value in ms, defaults to
+          Socket must be a socket returned from listen/2.
+          Timeout specifies a timeout value in ms, defaults to
           infinity.

-        
Returns {ok, Socket} if a connection is established,
-          or {error, closed} if ListenSocket is closed,
+        
Returns {ok, Socket} if a connection is established,
+          or {error, closed} if ListenSocket is closed,
           or {error, timeout} if no connection is established
           within the specified time. May also return a POSIX error
           value if something else goes wrong, see inet(3) for possible
           error values.

-        
Packets can be sent to the returned socket Socket
+        
Packets can be sent to the returned socket Socket
           using send/2. Packets sent from the peer are delivered
           as messages:

         
@@ -264,13 +262,8 @@ socket()
       
     
     
-      send(Socket, Packet) -> ok | {error, Reason}
+      
       Send a packet
-      
-        Socket = socket()
-        Packet = [char()] | binary()
-        Reason = posix()
-      
       
         
Sends a packet on a socket. 

         
There is no send call with timeout option, you use the
@@ -279,70 +272,52 @@ socket()
       
     
     
-      recv(Socket, Length) -> {ok, Packet} | {error, Reason}
-      recv(Socket, Length, Timeout) -> {ok, Packet} | {error, Reason}
+      
+      
       Receive a packet from a passive socket
-      
-        Socket = socket()
-        Length  = int()
-        Packet = [char()] | binary() | HttpPacket
-        Timeout = int() | infinity
-        Reason = closed | posix()
-        HttpPacket = see the description of HttpPacket in erlang:decode_packet/3
-      
+      See the description of
+         HttpPacket in 
+         erlang:decode_packet/3.
+      
       
         
This function receives a packet from a socket in passive
           mode. A closed socket is indicated by a return value
           {error, closed}.

-        
The Length argument is only meaningful when
+        
The Length argument is only meaningful when
           the socket is in raw mode and denotes the number of
-          bytes to read. If Length = 0, all available bytes are
-          returned. If Length > 0, exactly Length
+          bytes to read. If Length = 0, all available bytes are
+          returned. If Length > 0, exactly Length
           bytes are returned, or an error; possibly discarding less
-          than Length bytes of data when the socket gets closed
+          than Length bytes of data when the socket gets closed
           from the other side.

-        
The optional Timeout parameter specifies a timeout in
+        
The optional Timeout parameter specifies a timeout in
           milliseconds. The default value is infinity.

       
     
     
-      controlling_process(Socket, Pid) -> ok | {error, Reason}
+      
       Change controlling process of a socket
-      
-        Socket = socket()
-        Pid = pid()
-        Reason = closed | not_owner | posix()
-      
       
-        
Assigns a new controlling process Pid to
-          Socket. The controlling process is the process which
+        
Assigns a new controlling process Pid to
+          Socket. The controlling process is the process which
           receives messages from the socket. If called by any other
           process than the current controlling process,
           {error, eperm} is returned.

       
     
     
-      close(Socket) -> ok | {error, Reason}
+      
       Close a TCP socket
-      
-        Socket = socket()
-        Reason = posix()
-      
       
         
Closes a TCP socket.

       
     
     
-      shutdown(Socket, How) -> ok | {error, Reason}
+      
       Immediately close a socket
-      
-        Socket = socket()
-        How = read | write | read_write
-        Reason = posix()
-      
       
         
Immediately close a socket in one or two directions.

-        
How == write means closing the socket for writing,
+        
How == write means closing the socket for writing,
           reading from it is still possible.

         
To be able to handle that the peer has done a shutdown on
           the write side, the {exit_on_close, false} option
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index 71f2e9bd83..c0e783f508 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -4,7 +4,7 @@
 
   

     
-      19972009
+      19972011
       Ericsson AB. All Rights Reserved.
     
     
@@ -34,32 +34,43 @@
       with sockets using the UDP protocol.

   
 
-  

-    DATA TYPES
-    
-ip_address()
-  see inet(3)
-
-posix()
-  see inet(3)
+  
+    
+      
+    
+    
+      
+      
+        
Represents an address of a TCP socket.
+          It is a tuple as explained in
+          inet(3).

+      
+    
+    
+      
+    
+    
+      
+      
+        
See 
+        inet(3); POSIX Error Codes.

+      
+    
+    
+      socket()
+      
+        
As returned by open/1,2.

+      
+    
+  
 
-socket()
-  as returned by open/1,2
-  

   
     
-      open(Port) -> {ok, Socket} | {error, Reason}
-      open(Port, Options) -> {ok, Socket} | {error, Reason}
+      
+      
       Associate a UDP port number with the process calling it
-      
-        Port = 0..65535
-        Options = [Opt]
-         Opt -- see below
-        Socket = socket()
-        Reason = posix()
-      
       
-        
Associates a UDP port number (Port) with the calling
+        
Associates a UDP port number (Port) with the calling
           process.

         
The available options are:

         
@@ -96,7 +107,7 @@ socket()
               inet:setopts/2.

           
         
-        
The returned socket Socket is used to send packets
+        
The returned socket Socket is used to send packets
           from this port with send/4. When UDP packets arrive at
           the opened port, they are delivered as messages:

         
@@ -110,66 +121,42 @@ socket()
           binary if the option binary was specified.

         
Default value for the receive buffer option is
           {recbuf, 8192}.

-        
If Port == 0, the underlying OS assigns a free UDP
+        
If Port == 0, the underlying OS assigns a free UDP
           port, use inet:port/1 to retrieve it.

       
     
     
-      send(Socket, Address, Port, Packet) -> ok | {error, Reason}
+      
       Send a packet
-      
-        Socket = socket()
-        Address = string() | atom() | ip_address()
-        Port = 0..65535
-        Packet = [char()] | binary()
-        Reason = not_owner | posix()
-      
       
         
Sends a packet to the specified address and port.
-          The Address argument can be either a hostname, or an
+          The Address argument can be either a hostname, or an
           IP address.

       
     
     
-      recv(Socket, Length) -> {ok, {Address, Port, Packet}} | {error, Reason}
-      recv(Socket, Length, Timeout) -> {ok, {Address, Port, Packet}} | {error, Reason}
+      
+      
       Receive a packet from a passive socket
-      
-        Socket = socket()
-        Length  = int()
-        Address = ip_address()
-        Port = 0..65535
-        Packet = [char()] | binary()
-        Timeout = int() | infinity
-        Reason = not_owner | posix()
-      
       
         
This function receives a packet from a socket in passive
           mode.

-        
The optional Timeout parameter specifies a timeout in
+        
The optional Timeout parameter specifies a timeout in
           milliseconds. The default value is infinity.

       
     
     
-      controlling_process(Socket, Pid) -> ok
+      
       Change controlling process of a socket
-      
-        Socket = socket()
-        Pid = pid()
-      
       
-        
Assigns a new controlling process Pid to
-          Socket. The controlling process is the process which
+        
Assigns a new controlling process Pid to
+          Socket. The controlling process is the process which
           receives messages from the socket.

       
     
     
-      close(Socket) -> ok | {error, Reason}
+      
       Close a UDP socket
-      
-        Socket = socket()
-        Reason = not_owner | posix()
-      
       
         
Closes a UDP socket.

       
diff --git a/lib/kernel/doc/src/global.xml b/lib/kernel/doc/src/global.xml
index 077109d6c9..304a9b1d88 100644
--- a/lib/kernel/doc/src/global.xml
+++ b/lib/kernel/doc/src/global.xml
@@ -4,7 +4,7 @@
 
   

     
-      19962009
+      19962011
       Ericsson AB. All Rights Reserved.
     
     
@@ -106,45 +106,37 @@
 
   
 
+  
+    
+      
+    
+  
+
   
     
-      del_lock(Id)
-      del_lock(Id, Nodes) -> void()
+      
+      
       Delete a lock
-      
-        Id = {ResourceId, LockRequesterId}
-         ResourceId = term()
-         LockRequesterId = term()
-        Nodes = [node()]
-      
       
-        
Deletes the lock Id synchronously.

+        
Deletes the lock Id synchronously.

       
     
 
     
-      notify_all_name(Name, Pid1, Pid2) -> none
+      
       Name resolving function that notifies both pids
-      
-        Name = term()
-        Pid1 = Pid2 = pid()
-      
       
         
This function can be used as a name resolving function for
           register_name/3 and re_register_name/3. It
           unregisters both pids, and sends the message
-          {global_name_conflict, Name, OtherPid} to both
+          {global_name_conflict, Name, OtherPid} to both
           processes.

       
     
 
     
-      random_exit_name(Name, Pid1, Pid2) -> Pid1 | Pid2
+      
       Name resolving function that kills one pid
-      
-        Name = term()
-        Pid1 = Pid2 = pid()
-      
       
         
This function can be used as a name resolving function for
           register_name/3 and re_register_name/3. It
@@ -154,33 +146,27 @@
     
 
     
-      random_notify_name(Name, Pid1, Pid2) -> Pid1 | Pid2
+      
       Name resolving function that notifies one pid
-      
-        Name = term()
-        Pid1 = Pid2 = pid()
-      
       
         
This function can be used as a name resolving function for
           register_name/3 and re_register_name/3. It
           randomly chooses one of the pids for registration, and sends
-          the message {global_name_conflict, Name} to the other
+          the message {global_name_conflict, Name} to the other
           pid.

       
     
 
     
-      register_name(Name, Pid)
-      register_name(Name, Pid, Resolve) -> yes | no
+      
+      
       Globally register a name for a pid
-      
-        Name = term()
-        Pid = pid()
-        Resolve = fun() or {Module, Function} where
-          Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none
-      
+      
+      {Module, Function}
+        is also allowed
+      
       
-        
Globally associates the name Name with a pid, that is,
+        
Globally associates the name Name with a pid, that is,
           Globally notifies all nodes of a new global name in a network
           of Erlang nodes.

 
@@ -188,7 +174,7 @@
           of the globally registered names that already exist.
           The network is also informed of any global names in newly
           connected nodes. If any name clashes are discovered,
-          the Resolve function is called. Its purpose is to
+          the Resolve function is called. Its purpose is to
           decide which pid is correct. If the function crashes, or
           returns anything other than one of the pids, the name is
           unregistered. This function is called once for each name
@@ -196,7 +182,7 @@
 
         
There are three pre-defined resolve functions:
           random_exit_name/3, random_notify_name/3, and
-          notify_all_name/3. If no Resolve function is
+          notify_all_name/3. If no Resolve function is
           defined, random_exit_name is used. This means that one
           of the two registered processes will be selected as correct
           while the other is killed.

@@ -225,78 +211,63 @@
     
 
     
-      registered_names() -> [Name]
+      
       All globally registered names
-      
-        Name = term()
-      
       
         
Returns a lists of all globally registered names.

       
     
 
     
-      re_register_name(Name, Pid)
-      re_register_name(Name, Pid, Resolve) -> void()
+      
+      
       Atomically re-register a name
-      
-        Name = term()
-        Pid = pid()
-        Resolve = fun() or {Module, Function} where
-          Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none
-      
+      
+      {Module, Function}
+        is also allowed
+      
       
-        
Atomically changes the registered name Name on all
-          nodes to refer to Pid.

+        
Atomically changes the registered name Name on all
+          nodes to refer to Pid.

 
-        
The Resolve function has the same behavior as in
+        
The Resolve function has the same behavior as in
           register_name/2,3.

       
     
 
     
-      send(Name, Msg) -> Pid
+      
       Send a message to a globally registered pid
-      
-        Name = term()
-        Msg = term()
-        Pid = pid()
-      
       
-        
Sends the message Msg to the pid globally registered
-          as Name.

+        
Sends the message Msg to the pid globally registered
+          as Name.

 
-        
Failure: If Name is not a globally registered
+        
Failure: If Name is not a globally registered
           name, the calling function will exit with reason
-          {badarg, {Name, Msg}}.

+          {badarg, {Name, Msg}}.

       
     
 
     
-      set_lock(Id)
-      set_lock(Id, Nodes)
-      set_lock(Id, Nodes, Retries) -> boolean()
+      
+      
+      
       Set a lock on the specified nodes
-      
-        Id = {ResourceId, LockRequesterId}
-         ResourceId = term()
-         LockRequesterId = term()
-        Nodes = [node()]
-        Retries = int() >= 0 | infinity
-      
+      
+      
       
         
Sets a lock on the specified nodes (or on all nodes if none
-          are specified) on ResourceId for
-          LockRequesterId. If a lock already exists on
-          ResourceId for another requester than
-          LockRequesterId, and Retries is not equal to 0,
+          are specified) on ResourceId for
+          LockRequesterId. If a lock already exists on
+          ResourceId for another requester than
+          LockRequesterId, and Retries is not equal to 0,
           the process sleeps for a while and will try to execute
-          the action later. When Retries attempts have been made,
+          the action later. When Retries attempts have been made,
           false is returned, otherwise true. If
-          Retries is infinity, true is eventually
+          Retries is infinity, true is eventually
           returned (unless the lock is never released).

 
-        
If no value for Retries is given, infinity is
+        
If no value for Retries is given, infinity is
           used.

 
         
This function is completely synchronous.

@@ -315,7 +286,7 @@
           application to detect and rectify a deadlock.

 
         
-          
Some values of ResourceId should be avoided or
+          
Some values of ResourceId should be avoided or
             Erlang/OTP will not work properly. A list of resources to
             avoid: global, dist_ac,
             mnesia_table_lock, mnesia_adjust_log_writes,
@@ -326,7 +297,7 @@
     
 
     
-      sync() -> void()
+      
       Synchronize the global name server
       
         
Synchronizes the global name server with all nodes known to
@@ -335,56 +306,45 @@
           the global name server will receive global information from
           all nodes. This function can be called when new nodes are
           added to the network.

+        
The only possible error reason Reason is
+          {"global_groups definition error", Error}.

       
     
 
     
-      trans(Id, Fun)
-      trans(Id, Fun, Nodes)
-      trans(Id, Fun, Nodes, Retries) -> Res | aborted
+      
+      
+      
       Micro transaction facility
-      
-        Id = {ResourceId, LockRequesterId}
-         ResourceId = term()
-         LockRequesterId = term()
-        Fun = fun() | {M, F}
-        Nodes = [node()]
-        Retries = int() >= 0 | infinity
-        Res = term()
-      
+      
+      
       
-        
Sets a lock on Id (using set_lock/3). If this
-          succeeds, Fun() is evaluated and the result Res
+        
Sets a lock on Id (using set_lock/3). If this
+          succeeds, Fun() is evaluated and the result Res
           is returned.  Returns aborted if the lock attempt
-          failed. If Retries is set to infinity,
+          failed. If Retries is set to infinity,
           the transaction will not abort.

 
         
infinity is the default setting and will be used if 
-          no value is given for Retries.

+          no value is given for Retries.

       
     
 
     
-      unregister_name(Name) -> void()
+      
       Remove a globally registered name for a pid
-      
-        Name = term()
-      
       
-        
Removes the globally registered name Name from
+        
Removes the globally registered name Name from
           the network of Erlang nodes.

       
     
 
     
-      whereis_name(Name) -> pid() | undefined
+      
       Get the pid with a given globally registered name
-      
-        Name = term()
-      
       
         
Returns the pid with the globally registered name
-          Name. Returns undefined if the name is not
+          Name. Returns undefined if the name is not
           globally registered.

       
     
diff --git a/lib/kernel/doc/src/global_group.xml b/lib/kernel/doc/src/global_group.xml
index 4facf4a4aa..abf6178fc4 100644
--- a/lib/kernel/doc/src/global_group.xml
+++ b/lib/kernel/doc/src/global_group.xml
@@ -4,7 +4,7 @@
 
   

     
-      19982009
+      19982011
       Ericsson AB. All Rights Reserved.
     
     
@@ -42,26 +42,7 @@
       kernel(6),
       config(4):

     
-{global_groups, [GroupTuple]}
-    
Types:

-    
-      GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]}
-      GroupName = atom() (naming a global group)
-      PublishType = normal | hidden
-      Node = atom() (naming a node)
-    
-    
A GroupTuple without PublishType is the same as a
-      GroupTuple with PublishType == normal.

-    
A node started with the command line flag -hidden, see
-      erl(1), is said to be a
-      hidden node. A hidden node will establish hidden
-      connections to nodes not part of the same global group, but
-      normal (visible) connections to nodes part of the same global
-      group.

-    
A global group defined with PublishType == hidden, is
-      said to be a hidden global group. All nodes in a hidden global
-      group are hidden nodes, regardless if they are started with
-      the -hidden command line flag or not.

+{global_groups, [GroupTuple :: group_tuple()]}
     
For the processes and nodes to run smoothly using the global
       group functionality, the following criteria must be met:

     
@@ -82,14 +63,44 @@
     
In the following description, a group node is a node
       belonging to the same global group as the local node.

   
+  
+    
+      
+      
+        
A GroupTuple without PublishType is the same as a
+          GroupTuple with PublishType == normal.

+      
+    
+    
+      
+    
+    
+      
+      
+        
A node started with the command line flag -hidden, see
+          erl(1), is said to be a
+          hidden node. A hidden node will establish hidden
+          connections to nodes not part of the same global group, but
+          normal (visible) connections to nodes part of the same global
+          group.

+        
A global group defined with PublishType == hidden, is
+          said to be a hidden global group. All nodes in a hidden global
+          group are hidden nodes, regardless if they are started with
+          the -hidden command line flag or not.

+      
+    
+    
+      
+      
A registered name.

+    
+    
+      
+    
+  
   
     
-      global_groups() -> {GroupName, GroupNames} | undefined
+      
       Return the global group names
-      
-        GroupName = atom()
-        GroupNames = [GroupName]
-      
       
         
Returns a tuple containing the name of the global group
           the local node belongs to, and the list of all other known
@@ -98,53 +109,52 @@
       
     
     
-      info() -> [{Item, Info}]
+      
       Information about global groups
-      
-        Item, Info -- see below
-      
+      
+      
       
         
Returns a list containing information about the global
           groups. Each element of the list is a tuple. The order of
           the tuples is not defined.

         
-          {state, State}
+          {state, State}
           
             
If the local node is part of a global group,
-              State == synced. If no global groups are defined,
-              State == no_conf.

+              State == synced. If no global groups are defined,
+              State == no_conf.

           
-          {own_group_name, GroupName}
+          {own_group_name, GroupName}
           
             
The name (atom) of the group that the local node belongs
               to.

           
-          {own_group_nodes, Nodes}
+          {own_group_nodes, Nodes}
           
             
A list of node names (atoms), the group nodes.

           
-          {synced_nodes, Nodes}
+          {synced_nodes, Nodes}
           
             
A list of node names, the group nodes currently
               synchronized with the local node.

           
-          {sync_error, Nodes}
+          {sync_error, Nodes}
           
             
A list of node names, the group nodes with which
               the local node has failed to synchronize.

           
-          {no_contact, Nodes}
+          {no_contact, Nodes}
           
             
A list of node names, the group nodes to which there are
               currently no connections.

           
-          {other_groups, Groups}
+          {other_groups, Groups}
           
-            
Groups is a list of tuples
-              {GroupName, Nodes}, specifying the name and nodes
+            
Groups is a list of tuples
+              {GroupName, Nodes}, specifying the name and nodes
               of the other global groups.

           
-          {monitoring, Pids}
+          {monitoring, Pids}
           
             
A list of pids, specifying the processes which have
               subscribed to nodeup and nodedown messages.

@@ -153,73 +163,52 @@
       
     
     
-      monitor_nodes(Flag) -> ok 
+      
       Subscribe to node status changes
-      
-        Flag = bool()
-      
       
-        
Depending on Flag, the calling process starts
-          subscribing (Flag == true) or stops subscribing
-          (Flag == false) to node status change messages.

+        
Depending on Flag, the calling process starts
+          subscribing (Flag == true) or stops subscribing
+          (Flag == false) to node status change messages.

         
A process which has subscribed will receive the messages
           {nodeup, Node} and {nodedown, Node} when a
           group node connects or disconnects, respectively.

       
     
     
-      own_nodes() -> Nodes
+      
       Return the group nodes
-      
-        Nodes = [Node]
-         Node = node()
-      
       
         
Returns the names of all group nodes, regardless of their
           current status.

       
     
     
-      registered_names(Where) -> Names
+      
       Return globally registered names
-      
-        Where = {node, Node} | {group, GroupName}
-         Node = node()
-         GroupName = atom()
-        Names = [Name]
-         Name = atom()
-      
       
         
Returns a list of all names which are globally registered
           on the specified node or in the specified global group.

       
     
     
-      send(Name, Msg) -> pid() | {badarg, {Name, Msg}}
-      send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}
+      
+      
       Send a message to a globally registered pid
-      
-        Where = {node, Node} | {group, GroupName}
-         Node = node()
-         GroupName = atom()
-        Name = atom()
-        Msg = term()
-      
       
-        
Searches for Name, globally registered on
+        
Searches for Name, globally registered on
           the specified node or in the specified global group, or --
-          if the Where argument is not provided -- in any global
+          if the Where argument is not provided -- in any global
           group. The global groups are searched in the order in which
           they appear in the value of the global_groups
           configuration parameter.

-        
If Name is found, the message Msg is sent to
+        
If Name is found, the message Msg is sent to
           the corresponding pid. The pid is also the return value of
           the function. If the name is not found, the function returns
-          {badarg, {Name, Msg}}.

+          {badarg, {Name, Msg}}.

       
     
     
-      sync() -> ok
+      
       Synchronize the group nodes
       
         
Synchronizes the group nodes, that is, the global name
@@ -235,23 +224,17 @@
       
     
     
-      whereis_name(Name) -> pid() | undefined
-      whereis_name(Where, Name) -> pid() | undefined
+      
+      
       Get the pid with a given globally registered name
-      
-        Where = {node, Node} | {group, GroupName}
-         Node = node()
-         GroupName = atom()
-        Name = atom()
-      
       
-        
Searches for Name, globally registered on
+        
Searches for Name, globally registered on
           the specified node or in the specified global group, or -- if
-          the Where argument is not provided -- in any global
+          the Where argument is not provided -- in any global
           group. The global groups are searched in the order in which
           they appear in the value of the global_groups
           configuration parameter.

-        
If Name is found, the corresponding pid is returned.
+        
If Name is found, the corresponding pid is returned.
           If the name is not found, the function returns
           undefined.

       
diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml
index 0df699572d..e2dbcbe63d 100644
--- a/lib/kernel/doc/src/heart.xml
+++ b/lib/kernel/doc/src/heart.xml
@@ -4,7 +4,7 @@
 
   

     
-      19962009
+      19962011
       Ericsson AB. All Rights Reserved.
     
     
@@ -76,11 +76,8 @@
   
   
     
-      set_cmd(Cmd) -> ok | {error, {bad_cmd, Cmd}}
+      
       Set a temporary reboot command
-      
-        Cmd = string()
-      
       
         
Sets a temporary reboot command. This command is used if 
           a HEART_COMMAND other than the one specified with
@@ -88,12 +85,12 @@
           the system. The new Erlang runtime system will (if it
           misbehaves) use the environment variable
           HEART_COMMAND to reboot.

-        
Limitations: The length of the Cmd command string
+        
Limitations: The length of the Cmd command string
           must be less than 2047 characters.

       
     
     
-      clear_cmd() -> ok
+      
       Clear the temporary boot command
       
         
Clears the temporary boot command. If the system terminates,
@@ -101,11 +98,8 @@
       
     
     
-      get_cmd() -> {ok, Cmd}
+      
       Get the temporary reboot command
-      
-        Cmd = string()
-      
       
         
Get the temporary reboot command. If the command is cleared,
           the empty string will be returned.

diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index f05a224f33..fd843b00d9 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -4,7 +4,7 @@
 
   

     
-      19972010
+      19972011
       Ericsson AB. All Rights Reserved.
     
     
@@ -54,33 +54,6 @@ $ erl -sname test -kernel \
 inet_default_listen_options '[{delay_send,true}]'

Note that the default option {active, true} currently cannot be changed, for internal reasons.

- - -
- DATA TYPES - -#hostent{h_addr_list = [ip_address()] % list of addresses for this host - h_addrtype = inet | inet6 - h_aliases = [hostname()] % list of aliases - h_length = int() % length of address in bytes - h_name = hostname() % official name for host - The record is defined in the Kernel include file "inet.hrl" - Add the following directive to the module: - -include_lib("kernel/include/inet.hrl"). - -hostname() = atom() | string() - -ip_address() = {N1,N2,N3,N4} % IPv4 - | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6 - Ni = 0..255 - Ki = 0..65535 - -posix() - an atom which is named from the Posix error codes used in - Unix, and in the runtime libraries of most C compilers - -socket() - see gen_tcp(3), gen_udp(3)

Addresses as inputs to functions can be either a string or a tuple. For instance, the IP address 150.236.20.73 can be passed to gethostbyaddr/1 either as the string "150.236.20.73" @@ -109,24 +82,58 @@ fe80::204:acff:fe17:bf38 {ok,{192,168,42,2}} 2> inet_parse:address("FFFF::192.168.42.2"). {ok,{65535,0,0,0,0,0,49320,10754}} -

+ + + + + + +

The record is defined in the Kernel include file "inet.hrl". + Add the following directive to the module:

+-include_lib("kernel/include/inet.hrl"). + + + + + + + + + + + + + + + +

An atom which is named from the Posix error codes + used in Unix, and in the runtime libraries of most + C compilers. See + POSIX Error Codes.

+ + + + socket() +

See gen_tcp(3) + and gen_udp(3).

+ + + + + + + - close(Socket) -> ok + Close a socket of any type - - Socket = socket() -

Closes a socket of any type.

 - get_rc() -> [{Par, Val}] + Return a list of IP configuration parameters - - Par, Val -- see below -

Returns the state of the Inet configuration database in form of a list of recorded configuration parameters. (See the @@ -135,116 +142,74 @@ fe80::204:acff:fe17:bf38 - format_error(Posix) -> string() + Return a descriptive string for an error reason - - Posix = posix() -

Returns a diagnostic error string. See the section below - for possible Posix values and the corresponding + for possible Posix values and the corresponding strings.

 - getaddr(Host, Family) -> {ok, Address} | {error, posix()} + Return the IP-address for a host - - Host = ip_address() | string() | atom() - Family = inet | inet6 - Address = ip_address() - posix() = term() - -

Returns the IP-address for Host as a tuple of - integers. Host can be an IP-address, a single hostname +

Returns the IP-address for Host as a tuple of + integers. Host can be an IP-address, a single hostname or a fully qualified hostname.

 - getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()} + Return the IP-addresses for a host - - Host = ip_address() | string() | atom() - Addresses = [ip_address()] - Family = inet | inet6 - -

Returns a list of all IP-addresses for Host. - Host can be an IP-address, a single hostname or a fully +

Returns a list of all IP-addresses for Host. + Host can be an IP-address, a single hostname or a fully qualified hostname.

 - gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given address - - Address = string() | ip_address() - Hostent = #hostent{} -

Returns a hostent record given an address.

 - gethostbyname(Name) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given name - - Hostname = hostname() - Hostent = #hostent{} -

Returns a hostent record given a hostname.

 - gethostbyname(Name, Family) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given name - - Hostname = hostname() - Family = inet | inet6 - Hostent = #hostent{} -

Returns a hostent record given a hostname, restricted to the given address family.

 - gethostname() -> {ok, Hostname} + Return the local hostname - - Hostname = string() -

Returns the local hostname. Will never fail.

 - getifaddrs() -> {ok,Iflist} | {error,posix} + Return a list of interfaces and their addresses - - Iflist = {Ifname,[Ifopt]} - Ifname = string() - Ifopt = {flag,[Flag]} | {addr,Addr} | {netmask,Netmask} - | {broadaddr,Broadaddr} | {dstaddr,Dstaddr} - | {hwaddr,Hwaddr} - Flag = up | broadcast | loopback | pointtopoint - | running | multicast - Addr = Netmask = Broadadddr = Dstaddr = ip_address() - Hwaddr = [byte()] - -

Returns a list of 2-tuples containing interface names and the - interface's addresses. Ifname is a Unicode string. - Hwaddr is hardware dependent, e.g on Ethernet interfaces + interface's addresses. Ifname is a Unicode string. + Hwaddr is hardware dependent, e.g on Ethernet interfaces it is the 6-byte Ethernet address (MAC address (EUI-48 address)).

- The {addr,Addr}, {netmask,_} and {broadaddr,_} + The {addr,Addr}, {netmask,_} and {broadaddr,_} tuples are repeated in the result list iff the interface has multiple addresses. If you come across an interface that has multiple {flag,_} or {hwaddr,_} tuples you have @@ -252,8 +217,8 @@ fe80::204:acff:fe17:bf38 The {flag,_} tuple is mandatory, all other optional.

- Do not rely too much on the order of Flag atoms or - Ifopt tuples. There are some rules, though: + Do not rely too much on the order of Flag atoms or + Ifopt tuples. There are some rules, though: Immediately after {addr,_} follows {netmask,_} @@ -261,7 +226,7 @@ fe80::204:acff:fe17:bf38 Immediately thereafter follows {broadaddr,_} if the broadcast flag is not set and the - pointtopointflag is set. + pointtopoint flag is set. Any {netmask,_}, {broadaddr,_} or @@ -277,11 +242,12 @@ fe80::204:acff:fe17:bf38

On Windows, the data is fetched from quite different OS API - functions, so the Netmask and Broadaddr - values may be calculated, just as some Flag values. + functions, so the Netmask and Broadaddr + values may be calculated, just as some Flag values. You have been warned. Report flagrant bugs.

+ getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()} @@ -291,13 +257,14 @@ fe80::204:acff:fe17:bf38 Options = [Opt | RawOptReq] Opt = atom() RawOptReq = {raw, Protocol, OptionNum, ValueSpec} - Protocol = int() - OptionNum = int() + Protocol = integer() + OptionNum = integer() ValueSpec = ValueSize | ValueBin - ValueSize = int() + ValueSize = integer() ValueBin = binary() OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum, ValueBin}] +

Gets one or more options for a socket. See setopts/2 @@ -419,13 +386,8 @@ fe80::204:acff:fe17:bf38 - peername(Socket) -> {ok, {Address, Port}} | {error, posix()} + Return the address and port for the other end of a connection - - Socket = socket() - Address = ip_address() - Port = int() -

Returns the address and port for the other end of a connection.

@@ -436,20 +398,15 @@ fe80::204:acff:fe17:bf38 Return the local port number for a socket Socket = socket() - Port = int() + Port = integer()

Returns the local port number for a socket.

 - sockname(Socket) -> {ok, {Address, Port}} | {error, posix()} + Return the local address and port number for a socket - - Socket = socket() - Address = ip_address() - Port = int() -

Returns the local address and port number for a socket.

 @@ -460,8 +417,8 @@ fe80::204:acff:fe17:bf38 Socket = term() Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}] - Protocol = int() - OptionNum = int() + Protocol = integer() + OptionNum = integer() ValueBin = binary()  Opt, Val -- see below diff --git a/lib/kernel/doc/src/inet_res.xml b/lib/kernel/doc/src/inet_res.xml index d8fe23544b..bf73ccf13d 100644 --- a/lib/kernel/doc/src/inet_res.xml +++ b/lib/kernel/doc/src/inet_res.xml @@ -4,7 +4,7 @@
- 20092009 + 20092011 Ericsson AB. All Rights Reserved. @@ -76,64 +76,38 @@ query is tried for the alt_nameservers.

- - - -
- DATA TYPES -

As defined in the module - inet:

- -hostent() = #hostent{} -posix() = some atom()s -ip_address() = tuple of integers of arity 4 or 8 - +

Resolver types:

- These correspond to resolver options: - -res_option() = - [ {alt_nameservers, [ nameserver() ]} - | {edns, 0 | false} % Use EDNS - | {inet6, bool()} % Return IPv6 addresses - | {nameservers, [ nameserver() ]} % List of nameservers - | {recurse, bool()} % Request server recursion - | {retry, integer()} % UDP retries - | {timeout, integer()} % UDP query timeout - | {udp_payload_size, integer()} % EDNS payload size - | {usevc, bool()} ] % Use TCP (Virtual Circuit) - -nameserver() = {ip_address(),Port} - Port = integer(1..65535) - -res_error() = - formerr | - qfmterror | - servfail | - nxdomain | - notimp | - refused | - badvers | - timeout - - -

DNS types:

- - dns_name() = string() with no adjacent dots - -rr_type() = a | aaaa | cname | gid | hinfo | ns | mb | md | mg | mf - | minfo | mx | naptr | null | ptr | soa | spf | srv | txt - | uid | uinfo | unspec | wks - -query_type() = axfr | mailb | maila | any | rr_type() - -dns_class() = in | chaos | hs | any - + + + + + + + + + + +

DNS types:

+ + +

A string with no adjacent dots.

 + + + + + + + + + + +

This is the start of a hiearchy of opaque data structures + that can be examined with access functions in inet_dns that + return lists of {Field,Value} tuples. The arity 2 functions + just return the value for a given field. +

 dns_msg() = DnsMsg
-    This is the start of a hiearchy of opaque data structures
-    that can be examined with access functions in inet_dns
-    that return lists of {Field,Value} tuples. The arity 2
-    functions just return the value for a given field.
-
     inet_dns:msg(DnsMsg) ->
         [ {header, dns_header()}
         | {qdlist, dns_query()}
@@ -143,19 +117,21 @@ dns_msg() = DnsMsg
     inet_dns:msg(DnsMsg, header) -> dns_header() % for example
     inet_dns:msg(DnsMsg, Field) -> Value
 
-dhs_header() = DnsHeader
+dns_header() = DnsHeader
     inet_dns:header(DnsHeader) ->
         [ {id, integer()}
-        | {qr, bool()}
+        | {qr, boolean()}
         | {opcode, 'query' | iquery | status | integer()}
-        | {aa, bool()}
-        | {tc, bool()}
-        | {rd, bool()}
-        | {ra, bool()}
-        | {pr, bool()}
+        | {aa, boolean()}
+        | {tc, boolean()}
+        | {rd, boolean()}
+        | {ra, boolean()}
+        | {pr, boolean()}
         | {rcode, integer(0..16)} ]
     inet_dns:header(DnsHeader, Field) -> Value
 
+query_type() = axfr | mailb | maila | any | rr_type()
+
 dns_query() = DnsQuery
     inet_dns:dns_query(DnsQuery) ->
         [ {domain, dns_name()}
@@ -179,32 +155,6 @@ dns_rr() = DnsRr
                      | {data, dns_data()} ]
     inet_dns:rr(DnsRr, Field) -> Value
 
-dns_data() =             % for dns_type()
-    [ dns_name()         % ns, md, mf, cname, mb, mg, mr, ptr
-    | ip_address(v4)     % a
-    | ip_address(v6)     % aaaa
-    | {MName,RName,Serial,Refresh,Retry,Expiry,Minimum} % soa
-    | {ip_address(v4),Proto,BitMap} % wks
-    | {CpuString,OsString} % hinfo
-    | {RM,EM}            % minfo
-    | {Prio,dns_name()}  % mx
-    | {Prio,Weight,Port,dns_name()} % srv
-    | {Order,Preference,Flags,Services,Regexp,dns_name()} % naptr
-    | [ string() ]         % txt, spf
-    | binary() ]           % null, integer()
-MName, RName = dns_name()
-Serial, Refresh, Retry, Expiry, Minimum = integer(),
-Proto = integer()
-BitMap = binary()
-CpuString, OsString = string()
-RM = EM = dns_name()
-Prio, Weight, Port = integer()
-Order, Preference = integer()
-Flags, Services = string(),
-Regexp = string(utf8)
-
-
-
 There is an info function for the types above:
 
 inet_dns:record_type(dns_msg()) -> msg;
@@ -214,26 +164,25 @@ inet_dns:record_type(dns_rr()) -> rr;
 inet_dns:record_type(_) -> undefined.
 
 So; inet_dns:(inet_dns:record_type(X))(X) will convert
-any of these data structures into a {Field,Value} list.
-
- +any of these data structures into a {Field,Value} list.

+ + + + +

Regexp is a string with characters encoded in the + UTF-8 coding standard.

+ + + - getbyname(Name, Type) -> {ok,hostent()} | {error,Reason} - getbyname(Name, Type, Timeout) -> - {ok,hostent()} | {error,Reason} - + + Resolve a DNS record of the given type for the given host - - Name = dns_name() - Type = rr_type() - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() -

Resolve a DNS record of the given type for the given host, of class in. On success returns a hostent() record with @@ -252,17 +201,10 @@ any of these data structures into a {Field,Value} list. - gethostbyaddr(Address) -> {ok,hostent()} | {error,Reason} - gethostbyaddr(Address, Timeout) -> - {ok,hostent()} | {error,Reason} - + + Return a hostent record for the host with the given address - - Address = ip_address() - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() -

Backend functions used by @@ -273,20 +215,11 @@ any of these data structures into a {Field,Value} list. - gethostbyname(Name) -> {ok,hostent()} | Reason} - gethostbyname(Name, Family) -> - {ok,hostent()} | {error,Reason}} - - gethostbyname(Name, Family, Timeout) -> - {ok,hostent()} | {error,Reason} - + + + Return a hostent record for the host with the given name - - Name = dns_name() - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() -

Backend functions used by @@ -305,26 +238,16 @@ any of these data structures into a {Field,Value} list. - lookup(Name, Class, Type) -> [ dns_data() ] - - lookup(Name, Class, Type, Opts) -> [ dns_data() ] - - lookup(Name, Class, Type, Opts, Timeout) -> [ dns_data() ] - + + + Resolve the DNS data for the record of the given type and class for the given name - - Name = dns_name() | ip_address() - Type = rr_type() - Opts = res_option() | verbose - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() -

Resolve the DNS data for the record of the given type and class for the given name. On success filters out the answer records - with the correct Class and Type and returns + with the correct Class and Type and returns a list of their data fields. So a lookup for type any will give an empty answer since the answer records have specific types that are not any. An empty answer @@ -332,44 +255,33 @@ any of these data structures into a {Field,Value} list.

Calls resolve/2..4 with the same arguments and filters the result, so - Opts is explained there. + Opts is explained there.

- resolve(Name, Class, Type) -> {ok,dns_msg()} | Error - - resolve(Name, Class, Type, Opts) -> {ok,dns_msg()} | Error - - resolve(Name, Class, Type, Opts, Timeout) -> {ok,dns_msg()} | Error - + + + Resolve a DNS record of the given type and class for the given name - - Name = dns_name() | ip_address() - Type = rr_type() - Opts = res_option() | verbose | atom() - Timeout = integer() >= 0 | infinity - Error = {error,Reason} | {error,{Reason,dns_msg()}} - Reason = posix() | res_error() -

Resolve a DNS record of the given type and class for the given name. The returned dns_msg() can be examined using access functions in inet_db as described in DNS types.

- If Name is an ip_address(), the domain name + If Name is an ip_address(), the domain name to query for is generated as the standard reverse ".IN-ADDR.ARPA." name for an IPv4 address, or the ".IP6.ARPA." name for an IPv6 address. In this case you most probably want to use - Class = in and Type = ptr but it + Class = in and Type = ptr but it is not done automatically.

- Opts override the corresponding resolver options. + Opts override the corresponding resolver options. If the option nameservers is given, it is also assumed that it is the complete list of nameserves, so the resolver option alt_nameserves is ignored. @@ -382,14 +294,14 @@ any of these data structures into a {Field,Value} list. of queries, replies retransmissions, etc, similar to from utilities like dig, nslookup et.al.

- If Opt is an arbitrary atom it is interpreted - as {Opt,true} unless the atom string starts with - "no" making the interpretation {Opt,false}. + If Opt is an arbitrary atom it is interpreted + as {Opt,true} unless the atom string starts with + "no" making the interpretation {Opt,false}. For example: usevc is an alias for {usevc,true}, and nousevc an alias for {usevc,false}.

The inet6 option currently has no effect on this function. - You probably want to use Type = a | aaaa instead. + You probably want to use Type = a | aaaa instead.

@@ -430,24 +342,18 @@ any of these data structures into a {Field,Value} list. - nslookup(Name, Class, Type) -> {ok,dns_msg()} | {error,Reason} - - nslookup(Name, Class, Type, Timeout) -> - {ok,dns_msg()} | {error,Reason} - - nslookup(Name, Class, Type, Nameservers) -> - {ok,dns_msg()} | {error,Reason} - + + + Resolve a DNS record of the given type and class for the given name - - Name = dns_name() | ip_address() - Type = rr_type() - Nameservers = [ nameserver() ] - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() - + + + + + +

Resolve a DNS record of the given type and class for the given name.

@@ -455,22 +361,11 @@ any of these data structures into a {Field,Value} list. - nnslookup(Name, Class, Type, Nameservers) -> - {ok,dns_msg()} | {error,posix()} - - nnslookup(Name, Class, Type, Nameservers, Timeout) -> - {ok,dns_msg()} | {error,posix()} - + + Resolve a DNS record of the given type and class for the given name - - Name = dns_name() | ip_address() - Type = rr_type() - Nameservers = [ nameserver() ] - Timeout = integer() >= 0 | infinity - Reason = posix() | res_error() -

Resolve a DNS record of the given type and class for the given name.

diff --git a/lib/kernel/doc/src/net_adm.xml b/lib/kernel/doc/src/net_adm.xml index 7ec4f7f0e7..f2aac9282c 100644 --- a/lib/kernel/doc/src/net_adm.xml +++ b/lib/kernel/doc/src/net_adm.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -34,94 +34,70 @@ - dns_hostname(Host) -> {ok, Name} | {error, Host} + Official name of a host - - Host = atom() | string() - Name = string() - -

Returns the official name of Host, or - {error, Host} if no such name is found. See also +

Returns the official name of Host, or + {error, Host} if no such name is found. See also inet(3).

 - host_file() -> Hosts | {error, Reason} + Read the .hosts.erlangfile - - Hosts = [Host] -  Host = atom() - Reason = term() -

Reads the .hosts.erlang file, see the section Files below. Returns the hosts in this file as a - list, or returns {error, Reason} if the file could not - be read. See file(3) for possible values of - Reason.

+ list, or returns {error, Reason} if the file could not + be read or the Erlang terms on the file could not be interpreted.

 - localhost() -> Name + Name of the local host - - Name = string() -

Returns the name of the local host. If Erlang was started - with the -name command line flag, Name is + with the -name command line flag, Name is the fully qualified name.

 - names() -> {ok, [{Name, Port}]} | {error, Reason} - names(Host) -> {ok, [{Name, Port}]} | {error, Reason} + + Names of Erlang nodes at a host - - Name = string() - Port = int() - Reason = address | term() -

Similar to epmd -names, see epmd(1). - Host defaults to the local host. Returns the names and + Host defaults to the local host. Returns the names and associated port numbers of the Erlang nodes that epmd at the specified host has registered.

Returns {error, address} if epmd is not - running. See inet(3) for other possible values of - Reason.

+ running.

 (arne@dunn)1> net_adm:names().
 {ok,[{"arne",40262}]}
 - ping(Node) -> pong | pang + Set up a connection to a node - - Node = node() - -

Tries to set up a connection to Node. Returns +

Tries to set up a connection to Node. Returns pang if it fails, or pong if it is successful.

 - world() -> [node()] - world(Arg) -> [node()] + + + Lookup and connect to all nodes at all hosts in .hosts.erlang - - Arg = silent | verbose -

This function calls names(Host) for all hosts which are specified in the Erlang host file .hosts.erlang, collects the replies and then evaluates ping(Node) on all those nodes. Returns the list of all nodes that were, successfully pinged.

-

Arg defaults to silent. - If Arg == verbose, the function writes information about which +

Arg defaults to silent. + If Arg == verbose, the function writes information about which nodes it is pinging to stdout.

This function can be useful when a node is started, and the names of the other nodes in the network are not initially @@ -131,14 +107,10 @@ - world_list(Hosts) -> [node()] - world_list(Hosts, Arg) -> [node()] + + + Lookup and connect to all nodes at specified hosts - - Hosts = [Host] -  Host = atom() - Arg = silent | verbose -

As world/0,1, but the hosts are given as argument instead of being read from .hosts.erlang.

diff --git a/lib/kernel/doc/src/net_kernel.xml b/lib/kernel/doc/src/net_kernel.xml index a18226e779..96e2aa665d 100644 --- a/lib/kernel/doc/src/net_kernel.xml +++ b/lib/kernel/doc/src/net_kernel.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -64,50 +64,38 @@ $ erl -sname foobar - allow(Nodes) -> ok | error + Limit access to a specified set of nodes - - Nodes = [node()] -

Limits access to the specified set of nodes. Any access - attempts made from (or to) nodes not in Nodes will be + attempts made from (or to) nodes not in Nodes will be rejected.

-

Returns error if any element in Nodes is not +

Returns error if any element in Nodes is not an atom.

 - connect_node(Node) -> true | false | ignored + Establish a connection to a node - - Node = node() - -

Establishes a connection to Node. Returns true +

Establishes a connection to Node. Returns true if successful, false if not, and ignored if the local node is not alive.

 - monitor_nodes(Flag) -> ok | Error - monitor_nodes(Flag, Options) -> ok | Error + + Subscribe to node status change messages - - Flag = true | false - Options = [Option] -  Option -- see below - Error = error | {error, term()} -

The calling process subscribes or unsubscribes to node status change messages. A nodeup message is delivered to all subscribing process when a new node is connected, and a nodedown message is delivered when a node is disconnected.

-

If Flag is true, a new subscription is started. - If Flag is false, all previous subscriptions -- - started with the same Options -- are stopped. Two +

If Flag is true, a new subscription is started. + If Flag is false, all previous subscriptions -- + started with the same Options -- are stopped. Two option lists are considered the same if they contain the same set of options.

As of kernel version 2.11.4, and erts version @@ -139,23 +127,23 @@ $ erl -sname foobar

Note, that this is not guaranteed for kernel versions before 2.13.

The format of the node status change messages depends on - Options. If Options is [], which is the default, + Options. If Options is [], which is the default, the format is:

{nodeup, Node} | {nodedown, Node} Node = node() -

If Options /= [], the format is:

+

If Options /= [], the format is:

{nodeup, Node, InfoList} | {nodedown, Node, InfoList} Node = node() InfoList = [{Tag, Val}]

InfoList is a list of tuples. Its contents depends on - Options, see below.

+ Options, see below.

Also, when OptionList == [] only visible nodes, that is, nodes that appear in the result of nodes/0, are monitored.

-

Option can be any of the following:

+

Option can be any of the following:

{node_type, NodeType} @@ -209,61 +197,51 @@ $ erl -sname foobar - get_net_ticktime() -> Res + Get net_ticktime - - Res = NetTicktime | {ongoing_change_to, NetTicktime} -  NetTicktime = int() -

Gets net_ticktime (see kernel(6)).

-

Currently defined return values (Res):

+

Currently defined return values (Res):

- NetTicktime + NetTicktime -

net_ticktime is NetTicktime seconds.

+

net_ticktime is NetTicktime seconds.

 - {ongoing_change_to, NetTicktime} + {ongoing_change_to, NetTicktime}

net_kernel is currently changing - net_ticktime to NetTicktime seconds.

+ net_ticktime to NetTicktime seconds.

 - set_net_ticktime(NetTicktime) -> Res - set_net_ticktime(NetTicktime, TransitionPeriod) -> Res + + Set net_ticktime - - NetTicktime = int() > 0 - TransitionPeriod = int() >= 0 - Res = unchanged | change_initiated | {ongoing_change_to, NewNetTicktime} -  NewNetTicktime = int() > 0 -

Sets net_ticktime (see kernel(6)) to - NetTicktime seconds. TransitionPeriod defaults + NetTicktime seconds. TransitionPeriod defaults to 60.

Some definitions:

The minimum transition traffic interval (MTTI) -

minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 milliseconds.

+

minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 milliseconds.

 The transition period

The time of the least number of consecutive MTTIs - to cover TransitionPeriod seconds following + to cover TransitionPeriod seconds following the call to set_net_ticktime/2 (i.e. - ((TransitionPeriod*1000 - 1) div MTTI + 1)*MTTI + ((TransitionPeriod*1000 - 1) div MTTI + 1)*MTTI milliseconds).

 -

If , the actual +

If NetTicktime < PreviousNetTicktime]]>, the actual net_ticktime change will be done at the end of the transition period; otherwise, at the beginning. During the transition period, net_kernel will ensure that @@ -271,7 +249,7 @@ $ erl -sname foobar every MTTI millisecond.

The net_ticktime changes have to be initiated on all - nodes in the network (with the same NetTicktime) + nodes in the network (with the same NetTicktime) before the end of any transition period on any node; otherwise, connections may erroneously be disconnected.

 @@ -280,18 +258,18 @@ $ erl -sname foobar unchanged

net_ticktime already had the value of - NetTicktime and was left unchanged.

+ NetTicktime and was left unchanged.

 change_initiated

net_kernel has initiated the change of - net_ticktime to NetTicktime seconds.

+ net_ticktime to NetTicktime seconds.

 - {ongoing_change_to, NewNetTicktime} + {ongoing_change_to, NewNetTicktime}

The request was ignored; because, net_kernel was busy changing net_ticktime to - NewTicktime seconds.

+ NewNetTicktime seconds.

 @@ -315,7 +293,7 @@ $ erl -sname foobar - stop() -> ok | {error, not_allowed | not_found} + Turn a node into a non-distributed Erlang runtime system

Turns a distributed node into a non-distributed node. For diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index 2c9cc33eb7..56fc1834ec 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -4,7 +4,7 @@

- 19972009 + 19972011 Ericsson AB. All Rights Reserved. @@ -38,13 +38,10 @@ - cmd(Command) -> string() + Execute a command in a shell of the target OS - - Command = string() | atom() - -

Executes Command in a command shell of the target OS, +

Executes Command in a command shell of the target OS, captures the standard output of the command and returns this result as a string. This function is a replacement of the previous unix:cmd/1; on a Unix platform they are @@ -60,23 +57,18 @@ DirOut = os:cmd("dir"), % on Win32 platform - find_executable(Name) -> Filename | false - find_executable(Name, Path) -> Filename | false + + Absolute filename of a program - - Name = string() - Path = string() - Filename = string() -

These two functions look up an executable program given its name and a search path, in the same way as the underlying operating system. find_executable/1 uses the current execution path (that is, the environment variable PATH on Unix and Windows).

-

Path, if given, should conform to the syntax of +

Path, if given, should conform to the syntax of execution paths on the operating system. The absolute - filename of the executable program Name is returned, + filename of the executable program Name is returned, or false if the program was not found.

 @@ -137,7 +129,7 @@ DirOut = os:cmd("dir"), % on Win32 platform timestamp() -> {MegaSecs, Secs, MicroSecs} Returna a timestamp from the OS in the erlang:now/0 format - MegaSecs = Secs = MicroSecs = int() + MegaSecs = Secs = MicroSecs = integer() >= 0

Returns a tuple in the same format as erlang:now/0. 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 not guaranteed to be different.

@@ -165,19 +157,15 @@ format_utc_timestamp() -> - type() -> {Osfamily, Osname} | Osfamily + Return the OS family and, in some cases, OS name of the current operating system - - Osfamily = win32 | unix | vxworks - Osname = atom() - -

Returns the Osfamily and, in some cases, Osname +

Returns the Osfamily and, in some cases, Osname of the current operating system.

-

On Unix, Osname will have same value as +

On Unix, Osname will have same value as uname -s returns, but in lower case. For example, on Solaris 1 and 2, it will be sunos.

-

In Windows, Osname will be either nt (on +

In Windows, Osname will be either nt (on Windows NT), or windows (on Windows 95).

On VxWorks the OS family alone is returned, that is vxworks.

@@ -185,17 +173,13 @@ format_utc_timestamp() ->

Think twice before using this function. Use the filename module if you want to inspect or build file names in a portable way. - Avoid matching on the Osname atom.

+ Avoid matching on the Osname atom.

 - version() -> {Major, Minor, Release} | VersionString + Return the Operating System version - - Major = Minor = Release = integer() - VersionString = string() -

Returns the operating system version. On most systems, this function returns a tuple, but a string diff --git a/lib/kernel/doc/src/pg2.xml b/lib/kernel/doc/src/pg2.xml index 7463fd10f5..d26ff0fc6b 100644 --- a/lib/kernel/doc/src/pg2.xml +++ b/lib/kernel/doc/src/pg2.xml @@ -4,7 +4,7 @@

- 19972009 + 19972011 Ericsson AB. All Rights Reserved. @@ -60,13 +60,16 @@ to avoid name clashes.

+ + + +

The name of a process group.

 + + - create(Name) -> void() + Create a new, empty process group - - Name = term() -

Creates a new, empty process group. The group is globally visible on all nodes. If the group exists, nothing happens. @@ -74,24 +77,16 @@ - delete(Name) -> void() + Delete a process group - - Name = term() -

Deletes a process group.

- get_closest_pid(Name) -> Pid | {error, Reason} + Common dispatch function - - Name = term() - Pid = pid() - Reason = {no_process, Name} | {no_such_group, Name} -

This is a useful dispatch function which can be used from client functions. It returns a process on the local node, if @@ -100,13 +95,8 @@ - get_members(Name) -> [Pid] | {error, Reason} + Return all processes in a group - - Name = term() - Pid = pid() - Reason = {no_such_group, Name} -

Returns all processes in the group Name. This function should be used from within a client function that @@ -115,13 +105,8 @@ - get_local_members(Name) -> [Pid] | {error, Reason} + Return all local processes in a group - - Name = term() - Pid = pid() - Reason = {no_such_group, Name} -

Returns all processes running on the local node in the group Name. This function should to be used from @@ -131,13 +116,8 @@ - join(Name, Pid) -> ok | {error, Reason} + Join a process to a group - - Name = term() - Pid = pid() - Reason = {no_such_group, Name} -

Joins the process Pid to the group Name. A process can join a group several times; it must then @@ -146,13 +126,8 @@ - leave(Name, Pid) -> ok | {error, Reason} + Make a process leave a group - - Name = term() - Pid = pid() - Reason = {no_such_group, Name} -

Makes the process Pid leave the group Name. If the process is not a member of the group, ok is @@ -161,24 +136,17 @@ - which_groups() -> [Name] + Return a list of all known groups - - Name = term() -

Returns a list of all known groups.

- start() - start_link() -> {ok, Pid} | {error, Reason} + + Start the pg2 server - - Pid = pid() - Reason = term() -

Starts the pg2 server. Normally, the server does not need to be started explicitly, as it is started dynamically if it diff --git a/lib/kernel/doc/src/rpc.xml b/lib/kernel/doc/src/rpc.xml index 2b81de170d..b01ff16c85 100644 --- a/lib/kernel/doc/src/rpc.xml +++ b/lib/kernel/doc/src/rpc.xml @@ -4,7 +4,7 @@

- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -37,40 +37,34 @@ for collecting information on a remote node, or for running a function with some specific side effects on the remote node.

+ + + + +

As returned by + async_call/4.

+ + + - call(Node, Module, Function, Args) -> Res | {badrpc, Reason} + Evaluate a function call on a node - - Node = node() - Module = Function = atom() - Args = [term()] - Res = term() - Reason = term() - -

Evaluates apply(Module, Function, Args) on the node - Node and returns the corresponding value Res, or - {badrpc, Reason} if the call fails.

+

Evaluates apply(Module, Function, Args) on the node + Node and returns the corresponding value Res, or + {badrpc, Reason} if the call fails.

 - call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason} + Evaluate a function call on a node - - Node = node() - Module = Function = atom() - Args = [term()] - Res = term() - Reason = timeout | term() - Timeout = int() | infinity - -

Evaluates apply(Module, Function, Args) on the node - Node and returns the corresponding value Res, or - {badrpc, Reason} if the call fails. Timeout is +

Evaluates apply(Module, Function, Args) on the node + Node and returns the corresponding value Res, or + {badrpc, Reason} if the call fails. Timeout is a timeout value in milliseconds. If the call times out, - Reason is timeout.

+ Reason is timeout.

If the reply arrives after the call times out, no message will contaminate the caller's message queue, since this function spawns off a middleman process to act as (a void) @@ -80,17 +74,10 @@ - block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason} + Evaluate a function call on a node in the RPC server's context - - Node = node() - Module = Function = atom() - Args = [term()] - Res = term() - Reason = term() - -

Like call/4, but the RPC server at Node does +

Like call/4, but the RPC server at Node does not create a separate process to handle the call. Thus, this function can be used if the intention of the call is to block the RPC server from any other incoming requests until @@ -101,50 +88,31 @@ - block_call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason} + Evaluate a function call on a node in the RPC server's context - - Node = node() - Module = Function = atom() - Args = [term()] - Timeout = int() | infinity - Res = term() - Reason = term() -

Like block_call/4, but with a timeout value in the same manner as call/5.

 - async_call(Node, Module, Function, Args) -> Key + Evaluate a function call on a node, asynchronous version - - Node = node() - Module = Function = atom() - Args = [term()] - Key -- see below -

Implements call streams with promises, a type of RPC which does not suspend the caller until the result is finished. Instead, a key is returned which can be used at a later stage to collect the value. The key can be viewed as a promise to deliver the answer.

-

In this case, the key Key is returned, which can be +

In this case, the key Key is returned, which can be used in a subsequent call to yield/1 or nb_yield/1,2 to retrieve the value of evaluating - apply(Module, Function, Args) on the node Node.

+ apply(Module, Function, Args) on the node Node.

 - yield(Key) -> Res | {badrpc, Reason} + Deliver the result of evaluating a function call on a node (blocking) - - Key -- see async_call/4 - Res = term() - Reason = term() -

Returns the promised answer from a previous async_call/4. If the answer is available, it is @@ -153,87 +121,46 @@ - nb_yield(Key) -> {value, Val} | timeout + Deliver the result of evaluating a function call on a node (non-blocking) - - Key -- see async_call/4 - Val = Res | {badrpc, Reason} -  Res = term() -  Reason = term() - -

Equivalent to nb_yield(Key, 0).

+

Equivalent to nb_yield(Key, 0).

 - nb_yield(Key, Timeout) -> {value, Val} | timeout + Deliver the result of evaluating a function call on a node (non-blocking) - - Key -- see async_call/4 - Timeout = int() | infinity - Val = Res | {badrpc, Reason} -  Res = term() -  Reason = term() -

This is a non-blocking version of yield/1. It returns - the tuple {value, Val} when the computation has - finished, or timeout when Timeout milliseconds + the tuple {value, Val} when the computation has + finished, or timeout when Timeout milliseconds has elapsed.

 - multicall(Module, Function, Args) -> {ResL, BadNodes} + Evaluate a function call on a number of nodes - - Module = Function = atom() - Args = [term()] - ResL = [term()] - BadNodes = [node()] - -

Equivalent to multicall([node()|nodes()], Module, Function, Args, infinity).

+

Equivalent to multicall([node()|nodes()], Module, Function, Args, infinity).

 - multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes} + Evaluate a function call on a number of nodes - - Nodes = [node()] - Module = Function = atom() - Args = [term()] - ResL = [term()] - BadNodes = [node()] - -

Equivalent to multicall(Nodes, Module, Function, Args, infinity).

+

Equivalent to multicall(Nodes, Module, Function, Args, infinity).

 - multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes} + Evaluate a function call on a number of nodes - - Module = Function = atom() - Args = [term()] - Timeout = int() | infinity - ResL = [term()] - BadNodes = [node()] - -

Equivalent to multicall([node()|nodes()], Module, Function, Args, Timeout).

+

Equivalent to multicall([node()|nodes()], Module, Function, Args, Timeout).

 - multicall(Nodes, Module, Function, Args, Timeout) -> {ResL, BadNodes} + Evaluate a function call on a number of nodes - - Nodes = [node()] - Module = Function = atom() - Args = [term()] - Timeout = int() | infinity - ResL = [term()] - BadNodes = [node()] -

In contrast to an RPC, a multicall is an RPC which is sent concurrently from one client to multiple servers. This is @@ -243,12 +170,12 @@ making a series of RPCs on all the nodes, but the multicall is faster as all the requests are sent at the same time and are collected one by one as they come back.

-

The function evaluates apply(Module, Function, Args) +

The function evaluates apply(Module, Function, Args) on the specified nodes and collects the answers. It returns - {ResL, Badnodes}, where Badnodes is a list + {ResL, BadNodes}, where BadNodes is a list of the nodes that terminated or timed out during computation, - and ResL is a list of the return values. - Timeout is a time (integer) in milliseconds, or + and ResL is a list of the return values. + Timeout is a time (integer) in milliseconds, or infinity.

The following example is useful when new object code is to be loaded on all nodes in the network, and also indicates @@ -264,93 +191,60 @@ - cast(Node, Module, Function, Args) -> void() + Run a function on a node ignoring the result - - Node = node() - Module = Function = atom() - Args = [term()] - -

Evaluates apply(Module, Function, Args) on the node - Node. No response is delivered and the calling +

Evaluates apply(Module, Function, Args) on the node + Node. No response is delivered and the calling process is not suspended until the evaluation is complete, as is the case with call/4,5.

 - eval_everywhere(Module, Funtion, Args) -> void() + Run a function on all nodes, ignoring the result - - Module = Function = atom() - Args = [term()] - -

Equivalent to eval_everywhere([node()|nodes()], Module, Function, Args).

+

Equivalent to eval_everywhere([node()|nodes()], Module, Function, Args).

 - eval_everywhere(Nodes, Module, Function, Args) -> void() + Run a function on specific nodes, ignoring the result - - Nodes = [node()] - Module = Function = atom() - Args = [term()] - -

Evaluates apply(Module, Function, Args) on +

Evaluates apply(Module, Function, Args) on the specified nodes. No answers are collected.

 - abcast(Name, Msg) -> void() + Broadcast a message asynchronously to a registered process on all nodes - - Name = atom() - Msg = term() - -

Equivalent to abcast([node()|nodes()], Name, Msg).

+

Equivalent to abcast([node()|nodes()], Name, Msg).

 - abcast(Nodes, Name, Msg) -> void() + Broadcast a message asynchronously to a registered process on specific nodes - - Nodes = [node()] - Name = atom() - Msg = term() - -

Broadcasts the message Msg asynchronously to - the registered process Name on the specified nodes.

+

Broadcasts the message Msg asynchronously to + the registered process Name on the specified nodes.

 - sbcast(Name, Msg) -> {GoodNodes, BadNodes} + Broadcast a message synchronously to a registered process on all nodes - - Name = atom() - Msg = term() - GoodNodes = BadNodes = [node()] - -

Equivalent to sbcast([node()|nodes()], Name, Msg).

+

Equivalent to sbcast([node()|nodes()], Name, Msg).

 - sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes} + Broadcast a message synchronously to a registered process on specific nodes - - Name = atom() - Msg = term() - Nodes = GoodNodes = BadNodes = [node()] - -

Broadcasts the message Msg synchronously to - the registered process Name on the specified nodes.

-

Returns {GoodNodes, BadNodes}, where GoodNodes - is the list of nodes which have Name as a registered +

Broadcasts the message Msg synchronously to + the registered process Name on the specified nodes.

+

Returns {GoodNodes, BadNodes}, where GoodNodes + is the list of nodes which have Name as a registered process.

The function is synchronous in the sense that it is known that all servers have received the message when the call @@ -362,67 +256,46 @@ - server_call(Node, Name, ReplyWrapper, Msg) -> Reply | {error, Reason} + Interact with a server on a node - - Node = node() - Name = atom() - ReplyWrapper = Msg = Reply = term() - Reason = term() -

This function can be used when interacting with a server - called Name at node Node. It is assumed that + called Name at node Node. It is assumed that the server receives messages in the format - {From, Msg} and replies using From ! {ReplyWrapper, Node, Reply}. This function makes such + {From, Msg} and replies using From ! {ReplyWrapper, Node, Reply}. This function makes such a server call and ensures that the entire call is packed into an atomic transaction which either succeeds or fails. It never hangs, unless the server itself hangs.

-

The function returns the answer Reply as produced by - the server Name, or {error, Reason}.

+

The function returns the answer Reply as produced by + the server Name, or {error, Reason}.

 - multi_server_call(Name, Msg) -> {Replies, BadNodes} + Interact with the servers on a number of nodes - - Name = atom() - Msg = term() - Replies = [Reply] -  Reply = term() - BadNodes = [node()] - -

Equivalent to multi_server_call([node()|nodes()], Name, Msg).

+

Equivalent to multi_server_call([node()|nodes()], Name, Msg).

 - multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes} + Interact with the servers on a number of nodes - - Nodes = [node()] - Name = atom() - Msg = term() - Replies = [Reply] -  Reply = term() - BadNodes = [node()] -

This function can be used when interacting with servers - called Name on the specified nodes. It is assumed that - the servers receive messages in the format {From, Msg} - and reply using From ! {Name, Node, Reply}, where + called Name on the specified nodes. It is assumed that + the servers receive messages in the format {From, Msg} + and reply using From ! {Name, Node, Reply}, where Node is the name of the node where the server is - located. The function returns {Replies, Badnodes}, - where Replies is a list of all Reply values and - BadNodes is a list of the nodes which did not exist, or + located. The function returns {Replies, BadNodes}, + where Replies is a list of all Reply values and + BadNodes is a list of the nodes which did not exist, or where the server did not exist, or where the server terminated before sending any reply.

 - safe_multi_server_call(Name, Msg) -> {Replies, BadNodes} - safe_multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes} + + Interact with the servers on a number of nodes (deprecated) @@ -432,66 +305,47 @@

In Erlang/OTP R6B and earlier releases, multi_server_call/2,3 could not handle the case where the remote node exists, but there is no server called - Name. Instead this function had to be used. In + Name. Instead this function had to be used. In Erlang/OTP R7B and later releases, however, the functions are equivalent, except for this function being slightly slower.

 - parallel_eval(FuncCalls) -> ResL + Evaluate several function calls on all nodes in parallel - - FuncCalls = [{Module, Function, Args}] -  Module = Function = atom() -  Args = [term()] - ResL = [term()] - -

For every tuple in FuncCalls, evaluates - apply(Module, Function, Args) on some node in +

For every tuple in FuncCalls, evaluates + apply(Module, Function, Args) on some node in the network. Returns the list of return values, in the same - order as in FuncCalls.

+ order as in FuncCalls.

 - pmap({Module, Function}, ExtraArgs, List1) -> List2 + Parallell evaluation of mapping a function over a list - - Module = Function = atom() - ExtraArgs = [term()] - List1 = [Elem] -  Elem = term() - List2 = [term()] - -

Evaluates apply(Module, Function, [Elem|ExtraArgs]), - for every element Elem in List1, in parallel. +

Evaluates apply(Module, Function, [Elem|ExtraArgs]), + for every element Elem in List1, in parallel. Returns the list of return values, in the same order as in - List1.

+ List1.

 - pinfo(Pid) -> [{Item, Info}] | undefined + Information about a process - - Pid = pid() - Item, Info -- see erlang:process_info/1 -

Location transparent version of the BIF - process_info/1.

+ + process_info/1.

 - pinfo(Pid, Item) -> {Item, Info} | undefined | [] + Information about a process - - Pid = pid() - Item, Info -- see erlang:process_info/1 -

Location transparent version of the BIF - process_info/2.

+ + process_info/2.

 diff --git a/lib/kernel/doc/src/seq_trace.xml b/lib/kernel/doc/src/seq_trace.xml index 6c043dd767..1ab955bd8a 100644 --- a/lib/kernel/doc/src/seq_trace.xml +++ b/lib/kernel/doc/src/seq_trace.xml @@ -4,7 +4,7 @@
- 19982009 + 19982011 Ericsson AB. All Rights Reserved. @@ -47,17 +47,22 @@ from users.

+ + + + +

An opaque term (a tuple) representing a trace token.

+ + + - set_token(Token) -> PreviousToken + Set the trace token - - Token = PreviousToken = term() | [] - -

Sets the trace token for the calling process to Token. - If Token == [] then tracing is disabled, otherwise - Token should be an Erlang term returned from +

Sets the trace token for the calling process to Token. + If Token == [] then tracing is disabled, otherwise + Token should be an Erlang term returned from get_token/0 or set_token/1. set_token/1 can be used to temporarily exclude message passing from the trace by setting the trace token to empty like this:

@@ -72,18 +77,16 @@ seq_trace:set_token(OldToken), % activate the trace token again - set_token(Component, Val) -> {Component, OldVal} + Set a component of the trace token - - Component = label | serial | Flag -  Flag = send | 'receive' | print | timestamp - Val = OldVal -- see below - + + + -

Sets the individual Component of the trace token to - Val. Returns the previous value of the component.

+

Sets the individual Component of the trace token to + Val. Returns the previous value of the component.

- set_token(label, Int) + set_token(label, Integer)

The label component is an integer which identifies all events belonging to the same sequential @@ -93,31 +96,31 @@ seq_trace:set_token(OldToken), % activate the trace token again set_token(serial, SerialValue) -

SerialValue = {Previous, Current}. +

SerialValue = {Previous, Current}. The serial component contains counters which enables the traced messages to be sorted, should never be set explicitly by the user as these counters are updated automatically. Default is {0, 0}.

 - set_token(send, Bool) + set_token(send, Bool)

A trace token flag (true | false) which enables/disables tracing on message sending. Default is false.

 - set_token('receive', Bool) + set_token('receive', Bool)

A trace token flag (true | false) which enables/disables tracing on message reception. Default is false.

 - set_token(print, Bool) + set_token(print, Bool)

A trace token flag (true | false) which enables/disables tracing on explicit calls to seq_trace:print/1. Default is false.

 - set_token(timestamp, Bool) + set_token(timestamp, Bool)

A trace token flag (true | false) which enables/disables a timestamp to be generated for each @@ -127,11 +130,8 @@ seq_trace:set_token(OldToken), % activate the trace token again - get_token() -> TraceToken + Return the value of the trace token - - TraceToken = term() | [] -

Returns the value of the trace token for the calling process. If [] is returned, it means that tracing is not active. @@ -141,13 +141,11 @@ seq_trace:set_token(OldToken), % activate the trace token again - get_token(Component) -> {Component, Val} + Return the value of a trace token component - - Component = label | serial | Flag -  Flag = send | 'receive' | print | timestamp - Val -- see set_token/2 - + + +

Returns the value of the trace token component Component. See @@ -156,33 +154,26 @@ seq_trace:set_token(OldToken), % activate the trace token again - print(TraceInfo) -> void() + Put the Erlang term TraceInfointo the sequential trace output - - TraceInfo = term() - -

Puts the Erlang term TraceInfo into the sequential +

Puts the Erlang term TraceInfo into the sequential trace output if the calling process currently is executing within a sequential trace and the print flag of the trace token is set.

 - print(Label, TraceInfo) -> void() + Put the Erlang term TraceInfointo the sequential trace output - - Label = int() - TraceInfo = term() -

Same as print/1 with the additional condition that - TraceInfo is output only if Label is equal to + TraceInfo is output only if Label is equal to the label component of the trace token.

 - reset_trace() -> void() + Stop all sequential tracing on the local node

Sets the trace token to empty for all processes on the @@ -194,26 +185,22 @@ seq_trace:set_token(OldToken), % activate the trace token again - set_system_tracer(Tracer) -> OldTracer + Set the system tracer - - Tracer = OldTracer = pid() | port() | false - +

Sets the system tracer. The system tracer can be either a - process or port denoted by Tracer. Returns the previous + process or port denoted by Tracer. Returns the previous value (which can be false if no system tracer is active).

-

Failure: {badarg, Info}} if Pid is not an +

Failure: {badarg, Info}} if Pid is not an existing local pid.

 - get_system_tracer() -> Tracer + Return the pid() or port() of the current system tracer. - - Tracer = pid() | port() | false - +

Returns the pid or port identifier of the current system tracer or false if no system tracer is activated.

diff --git a/lib/kernel/doc/src/specs.xml b/lib/kernel/doc/src/specs.xml new file mode 100644 index 0000000000..b41addaa0c --- /dev/null +++ b/lib/kernel/doc/src/specs.xml @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/kernel/doc/src/wrap_log_reader.xml b/lib/kernel/doc/src/wrap_log_reader.xml index 18664a029f..6cf480b532 100644 --- a/lib/kernel/doc/src/wrap_log_reader.xml +++ b/lib/kernel/doc/src/wrap_log_reader.xml @@ -4,7 +4,7 @@
- 19982009 + 19982011 Ericsson AB. All Rights Reserved. @@ -50,18 +50,20 @@ the called node, it is entirely up to the user to be sure that all items are read.

+ + + +

Continuation returned by + open/1,2 or chunk/1,2.

+ + + - chunk(Continuation) - chunk(Continuation, N) -> {Continuation2, Terms} | {Continuation2, Terms, Badbytes} | {Continuation2, eof} | {error, Reason} + + Read a chunk of objects written to a wrap log. - - Continuation = continuation() - N = int() > 0 | infinity - Continuation2 = continuation() - Terms= [term()] - Badbytes = integer() - +

This function makes it possible to efficiently read the terms which have been appended to a log. It minimises disk @@ -70,29 +72,29 @@

The first time chunk is called an initial continuation returned from the open/1, open/2 must be provided.

-

When chunk/3 is called, N controls the +

When chunk/3 is called, N controls the maximum number of terms that are read from the log in each chunk. Default is infinity, which means that all the terms contained in the 8K chunk are read. If less than - N terms are returned, this does not necessarily mean + N terms are returned, this does not necessarily mean that end of file is reached.

The chunk function returns a tuple - {Continuation2, Terms}, where Terms is a list - of terms found in the log. Continuation2 is yet + {Continuation2, Terms}, where Terms is a list + of terms found in the log. Continuation2 is yet another continuation which must be passed on into any subsequent calls to chunk. With a series of calls to chunk it is then possible to extract all terms from a log.

The chunk function returns a tuple - {Continuation2, Terms, Badbytes} if the log is opened - in read only mode and the read chunk is corrupt. Badbytes + {Continuation2, Terms, Badbytes} if the log is opened + in read only mode and the read chunk is corrupt. Badbytes indicates the number of non-Erlang terms found in the chunk. Note also that the log is not repaired.

-

chunk returns {Continuation2, eof} when the end of the log is - reached, and {error, Reason} if an error occurs. +

chunk returns {Continuation2, eof} when the end of the log is + reached, and {error, Reason} if an error occurs.

The returned continuation may or may not be valid in the next call to chunk. This is because the log may wrap and delete @@ -103,37 +105,29 @@ - close(Continuation) -> ok + Close a log - - Continuation = continuation() -

This function closes a log file properly.

- open(Filename) -> OpenRet - open(Filename, N) -> OpenRet + + Open a log file - - File = string() | atom() - N = integer() - OpenRet = {ok, Continuation} | {error, Reason} - Continuation = continuation() - + -

Filename specifies the name of the file which is to be read.

-

N specifies the index of the file which is to be read. - If N is omitted the whole wrap log file will be read; if it +

Filename specifies the name of the file which is to be read.

+

N specifies the index of the file which is to be read. + If N is omitted the whole wrap log file will be read; if it is specified only the specified index file will be read.

-

The open function returns {ok, Continuation} if the - log/index file was successfully opened. The Continuation +

The open function returns {ok, Continuation} if the + log/index file was successfully opened. The Continuation is to be used when chunking or closing the file.

-

The function returns {error, Reason} for all errors. +

The function returns {error, Reason} for all errors.

-- cgit v1.2.3