From 037150979ff809df85757bd2b3f676e2e4c6be88 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 17 Jan 2012 12:28:32 +0100 Subject: Move types and specs from erl_bif_types.erl to modules --- lib/kernel/doc/src/code.xml | 13 ++- lib/kernel/doc/src/erl_ddll.xml | 159 +++++++++++++----------------------- lib/kernel/doc/src/error_logger.xml | 7 +- lib/kernel/doc/src/file.xml | 6 +- lib/kernel/doc/src/os.xml | 40 +++------ 5 files changed, 81 insertions(+), 144 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index ee687511a3..bb111a2242 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -4,7 +4,7 @@
- 19962011 + 19962012 Ericsson AB. All Rights Reserved. @@ -728,16 +728,13 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - is_module_native(Module) -> boolean() | undefined + Test whether a module has native code - - Module = module() - -

This function returns true if Module is +

This function returns true if Module is name of a loaded module that has native code loaded, and - false if Module is loaded but does not have - native. If Module is not loaded, this function returns + false if Module is loaded but does not have + native. If Module is not loaded, this function returns undefined.

 diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml index 1911fb628e..26db11cfcd 100644 --- a/lib/kernel/doc/src/erl_ddll.xml +++ b/lib/kernel/doc/src/erl_ddll.xml @@ -4,7 +4,7 @@
- 19972011 + 19972012 Ericsson AB. All Rights Reserved. @@ -182,11 +182,8 @@ - demonitor(MonitorRef) -> ok + Remove a monitor for a driver - - MonitorRef = reference() -

Removes a driver monitor in much the same way as erlang:demonitor/1 does with process @@ -232,24 +229,19 @@ - info(Name, Tag) -> Value + Retrieve specific information about one driver - - Name = string() | atom() - Tag = processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload - Value = term() -

This function returns specific information about one aspect - of a driver. The Tag parameter specifies which aspect - to get information about. The Value return differs + of a driver. The Tag parameter specifies which aspect + to get information about. The Value return differs between different tags:

processes

Return all processes containing users of the specific drivers - as a list of tuples {pid(),int()}, where the - int() denotes the number of users in the process + as a list of tuples {pid(),integer() >= 0}, where the + integer() denotes the number of users in the process pid().

 driver_options @@ -261,16 +253,16 @@ port_count -

Return the number of ports (an int()) using the driver.

+

Return the number of ports (an integer >= 0()) using the driver.

 linked_in_driver -

Return a bool(), being true if the driver is a +

Return a boolean(), being true if the driver is a statically linked in one and false otherwise.

 permanent -

Return a bool(), being true if the driver has made +

Return a boolean(), being true if the driver has made itself permanent (and is not a statically linked in driver). false otherwise.

 @@ -278,14 +270,14 @@

Return a list of all processes having monitors for loading active, each process returned as - {pid(),int()}, where the int() is the + {pid(),integer() >= 0}, where the integer() is the number of monitors held by the process pid().

 awaiting_unload

Return a list of all processes having monitors for unloading active, each process returned as - {pid(),int()}, where the int() is the + {pid(),integer() >= 0}, where the integer() is the number of monitors held by the process pid().

 @@ -377,41 +369,34 @@ - monitor(Tag, Item) -> MonitorRef + Create a monitor for a driver - - Tag = driver - Item = {Name, When} - Name = atom() | string() - When = loaded | unloaded | unloaded_only - MonitorRef = reference() -

This function creates a driver monitor and works in many ways as the function erlang:monitor/2, does for processes. When a driver changes state, the monitor results in a monitor-message being sent to the calling - process. The MonitorRef returned by this function is + process. The MonitorRef returned by this function is included in the message sent.

As with process monitors, each driver monitor set will only generate one single message. The monitor is "destroyed" after the message is sent and there is then no need to call demonitor/1.

-

The MonitorRef can also be used in subsequent calls +

The MonitorRef can also be used in subsequent calls to demonitor/1 to remove a monitor.

The function accepts the following parameters:

- Tag + Tag

The monitor tag is always driver as this function can only be used to create driver monitors. In the future, driver monitors will be integrated with process monitors, why this parameter has to be given for consistence.

 - Item + Item -

The Item parameter specifies which driver one +

The Item parameter specifies which driver one wants to monitor (the name of the driver) as well as which state change one wants to monitor. The parameter is a tuple of arity two whose first element is the @@ -588,22 +573,8 @@ - try_load(Path, Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc} + Load a driver - - Path = Name = string() | atom() - OptionList = [ Option ] - Option = {driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption} - DriverOptionList = [ DriverOption ] - DriverOption = kill_ports - MonitorOption = pending_driver | pending - ReloadOption = pending_driver | pending - Status = loaded | already_loaded | PendingStatus - PendingStatus = pending_driver | pending_process - Ref = reference() - ErrorDesc = ErrorAtom | OpaqueError - ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process -

This function provides more control than the load/2/reload/2 and @@ -655,65 +626,65 @@

When the function returns {ok, pending_driver} or {ok, pending_process}, one might want to get information about when the driver is actually loaded. This can - be achieved by using the {monitor, PendingOption} option.

+ be achieved by using the {monitor, MonitorOption} option.

When monitoring is requested, and a corresponding {ok, pending_driver} or {ok, pending_process} would be - returned, the function will instead return a tuple {ok, PendingStatus, reference()} and the process will, at a later + returned, the function will instead return a tuple {ok, PendingStatus, reference()} and the process will, at a later time when the driver actually gets loaded, get a monitor message. The monitor message one can expect is described in the monitor/2 function description.

Note that in case of loading, monitoring can - not only get triggered by using the {reload, ReloadOption} option, but also in special cases where + not only get triggered by using the {reload, ReloadOption} option, but also in special cases where the load-error is transient, why {monitor, pending_driver} should be used under basically all real world circumstances!

The function accepts the following parameters:

- Path + Path

The filesystem path to the directory where the driver object file is situated. The filename of the object file (minus extension) must correspond to the driver name (used in the name parameter) and the driver must identify itself with the very same name. The - Path might be provided as an io_list, - meaning it can be a list of other io_lists, characters + Path might be provided as an iolist(), + meaning it can be a list of other iolist()s, characters (eight bit integers) or binaries, all to be flattened into a sequence of characters.

-

The (possibly flattened) Path parameter must be +

The (possibly flattened) Path parameter must be consistent throughout the system, a driver should, by all users, be loaded - using the same literalPath. The + using the same literalPath. The exception is when reloading is requested, in - which case the Path may be specified + which case the Path may be specified differently. Note that all users trying to load the - driver at a later time will need to use the newPath if the Path is changed using a + driver at a later time will need to use the newPath if the Path is changed using a reload option. This is yet another reason to have only one loader of a driver one wants to upgrade in a running system!

- Name + Name

The name parameter is the name of the driver to be used in subsequent calls to open_port. The - name can be specified either as an io_list() or + name can be specified either as an iolist() or as an atom(). The name given when loading is used to find the actual object file (with the - help of the Path and the system implied + help of the Path and the system implied extension suffix, i.e. .so). The name by which the driver identifies itself must also be consistent - with this Name parameter, much as a beam-file's + with this Name parameter, much as a beam-file's module name much correspond to its filename.

 - OptionList + OptionList

A number of options can be specified to control the loading operation. The options are given as a list of two-tuples, the tuples having the following values and meanings:

- {driver_options, DriverOptionsList} + {driver_options, DriverOptionList}

This option is to provide options that will change its general behavior and will "stick" to the driver @@ -729,14 +700,14 @@ when the last user calls try_unload/2, or the last process having loaded the driver exits.

 - {monitor, MonitorOption} + {monitor, MonitorOption} -

A MonitorOption tells try_load/3 to +

A MonitorOption tells try_load/3 to trigger a driver monitor under certain conditions. When the monitor is triggered, the - function will return a three-tuple {ok, PendingStatus, reference()}, where the reference() is + function will return a three-tuple {ok, PendingStatus, reference()}, where the reference() is the monitor ref for the driver monitor.

-

Only one MonitorOption can be specified and +

Only one MonitorOption can be specified and it is either the atom pending, which means that a monitor should be created whenever a load operation is delayed, and the atom @@ -747,7 +718,7 @@ is present for completeness, it is very well defined which reload-options might give rise to which delays. It might, however, be a good idea to use the - same MonitorOption as the ReloadOption + same MonitorOption as the ReloadOption if present.

If reloading is not requested, it might still be useful to specify the monitor option, as @@ -760,12 +731,12 @@ {monitor, pending_driver} in production code (see the monitor discussion above).

- {reload,RealoadOption} + {reload,ReloadOption}

This option is used when one wants to reload a driver from disk, most often in a code upgrade scenario. Having a reload option - also implies that the Path parameter need + also implies that the Path parameter need not be consistent with earlier loads of the driver.

To reload a driver, the process needs to have previously @@ -814,9 +785,9 @@ {error,inconsistent}

The driver has already been loaded with either other - DriverOptions or a different literalPath argument.

+ DriverOptionList or a different literalPath argument.

This can happen even if a reload option is given, - if the DriverOptions differ from the current.

+ if the DriverOptionList differ from the current.

 {error, permanent} @@ -830,19 +801,19 @@ {error, pending_reload} -

Driver reload is already requested by another user when the {reload, ReloadOption} option was given.

+

Driver reload is already requested by another user when the {reload, ReloadOption} option was given.

 {error, not_loaded_by_this_process}

Appears when the reload option is given. The - driver Name is present in the system, but there is no + driver Name is present in the system, but there is no user of it in this process.

 {error, not_loaded}

Appears when the reload option is given. The - driver Name is not in the system. Only drivers + driver Name is not in the system. Only drivers loaded by this process can be reloaded.

 @@ -856,18 +827,8 @@ - try_unload(Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom} + Unload a driver - - Name = string() | atom() - OptionList = [ Option ] - Option = {monitor, MonitorOption} | kill_ports - MonitorOption = pending_driver | pending - Status = unloaded | PendingStatus - PendingStatus = pending_driver | pending_process - Ref = reference() - ErrorAtom = linked_in_driver | not_loaded | not_loaded_by_this_process | permanent -

This is the low level function to unload (or decrement reference counts of) a driver. It can be used to force port @@ -948,15 +909,15 @@

The function accepts the following parameters:

- Name + Name

The name parameter is the name of the driver to be unloaded. The name can be specified either as an - io_list() or as an atom().

+ iolist() or as an atom().

- OptionList + OptionList -

The OptionList argument can be used to specify +

The OptionList argument can be used to specify certain behavior regarding ports as well as triggering monitors under certain conditions:

@@ -972,10 +933,10 @@ unloads, one should use the driver option kill_ports when loading the driver instead.

 - {monitor, MonitorOption} + {monitor, MonitorOption}

This option creates a driver monitor if the condition - given in MonitorOptions is true. The valid + given in MonitorOption is true. The valid options are:

pending_driver @@ -989,7 +950,7 @@ {ok, pending_driver} or {ok, pending_process}.

 -

The pending_driver MonitorOption is by far +

The pending_driver MonitorOption is by far the most useful and it has to be used to ensure that the driver has really been unloaded and the ports closed whenever the kill_ports option is used or the @@ -1016,11 +977,11 @@ {error, not_loaded} -

The driver Name is not present in the system.

+

The driver Name is not present in the system.

{error, not_loaded_by_this_process} -

The driver Name is present in the system, but +

The driver Name is present in the system, but there is no user of it in this process.

As a special case, drivers can be unloaded from @@ -1088,12 +1049,8 @@ - loaded_drivers() -> {ok, Drivers} + List loaded drivers - - Drivers = [Driver] - Driver = string() -

Returns a list of all the available drivers, both (statically) linked-in and dynamically loaded ones.

diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index 2d95f96ac7..5781591cca 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -4,7 +4,7 @@
- 19962011 + 19962012 Ericsson AB. All Rights Reserved. @@ -127,11 +127,8 @@ ok - warning_map() -> Tag + Return the current mapping for warning events - - Tag = error | warning | info -

Returns the current mapping for warning events. Events sent using warning_msg/1,2 or warning_report/1,2 diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 772eff13cc..b2a259080d 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -4,7 +4,7 @@

- 19962011 + 19962012 Ericsson AB. All Rights Reserved. @@ -412,7 +412,7 @@ - file_info(Filename) -> {ok, FileInfo} | {error, Reason} + Get information about a file (deprecated)

This function is obsolete. Use read_file_info/1,2 @@ -598,7 +598,7 @@ - native_name_encoding() -> latin1 | utf8 + Return the VM's configured filename encoding.

This function returns the configured default file name encoding to use for raw file names. Generally an application supplying file names raw (as binaries), should obey the character encoding returned by this function.

diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index e94119845a..1bc5b9e464 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -4,7 +4,7 @@
- 19972011 + 19972012 Ericsson AB. All Rights Reserved. @@ -73,7 +73,7 @@ DirOut = os:cmd("dir"), % on Win32 platform - getenv() -> [string()] + List all environment variables

Returns a list of all environment variables. @@ -83,55 +83,41 @@ DirOut = os:cmd("dir"), % on Win32 platform - getenv(VarName) -> Value | false + Get the value of an environment variable - - VarName = string() - Value = string() - -

Returns the Value of the environment variable - VarName, or false if the environment variable +

Returns the Value of the environment variable + VarName, or false if the environment variable is undefined.

 - getpid() -> Value + Return the process identifier of the emulator process - - Value = string() -

Returns the process identifier of the current Erlang emulator in the format most commonly used by the operating system - environment. Value is returned as a string containing + environment. Value is returned as a string containing the (usually) numerical identifier for a process. On Unix, this is typically the return value of the getpid() - system call. On VxWorks, Value contains the task id + system call. On VxWorks, Value contains the task id (decimal notation) of the Erlang task. On Windows, the process id as returned by the GetCurrentProcessId() system call is used.

 - putenv(VarName, Value) -> true + Set a new value for an environment variable - - VarName = string() - Value = string() - -

Sets a new Value for the environment variable - VarName.

+

Sets a new Value for the environment variable + VarName.

 - timestamp() -> Timestamp + + Timestamp = {MegaSecs, Secs, MicroSecs} Returna a timestamp from the OS in the erlang:now/0 format - - Timestamp = {MegaSecs, Secs, MicroSecs} = erlang:timestamp() - 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.

The most obvious use for this function is logging. The tuple can be used together with the function calendar:now_to_universal_time/1 -- cgit v1.2.3