From 4bd8ab6298961d564c34172c0a4d74cd08a08249 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 8 Jun 2011 09:23:14 +0200 Subject: Add more specs and types An incorrect spec, rpc:yield/1, has been fixed. --- lib/kernel/doc/src/Makefile | 2 + lib/kernel/doc/src/code.xml | 339 ++++++++++++++++---------------------------- lib/kernel/doc/src/file.xml | 21 +-- lib/kernel/doc/src/os.xml | 3 +- 4 files changed, 135 insertions(+), 230 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile index de10e31d36..214e994889 100644 --- a/lib/kernel/doc/src/Makefile +++ b/lib/kernel/doc/src/Makefile @@ -104,6 +104,8 @@ TOP_SPECS_FILE = specs.xml # ---------------------------------------------------- XML_FLAGS += +SPECS_ESRC = ../../src + SPECS_FLAGS = -I../../include # ---------------------------------------------------- diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index 6f85388c22..98cdd416b0 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -287,6 +287,9 @@ + + + @@ -294,190 +297,147 @@ - set_path(Path) -> true | {error, What} + Set the code server search path - - Path = [Dir] - Dir = string() - What = bad_directory | bad_path - -

Sets the code path to the list of directories Path.

+

Sets the code path to the list of directories Path.

Returns true if successful, or - {error, bad_directory} if any Dir is not + {error, bad_directory} if any Dir is not the name of a directory, or {error, bad_path} if the argument is invalid.

 - get_path() -> Path + Return the code server search path - - Path = [Dir] - Dir = string() -

Returns the code path

 - add_path(Dir) -> true | {error, What} - add_pathz(Dir) -> true | {error, What} + + Add a directory to the end of the code path - - Dir = string() - What = bad_directory - + -

Adds Dir to the code path. The directory is added as - the last directory in the new path. If Dir already +

Adds Dir to the code path. The directory is added as + the last directory in the new path. If Dir already exists in the path, it is not added.

Returns true if successful, or - {error, bad_directory} if Dir is not the name + {error, bad_directory} if Dir is not the name of a directory.

 - add_patha(Dir) -> true | {error, What} + Add a directory to the beginning of the code path - - Dir = string() - What = bad_directory - + -

Adds Dir to the beginning of the code path. If - Dir already exists, it is removed from the old +

Adds Dir to the beginning of the code path. If + Dir already exists, it is removed from the old position in the code path.

Returns true if successful, or - {error, bad_directory} if Dir is not the name + {error, bad_directory} if Dir is not the name of a directory.

 - add_paths(Dirs) -> ok - add_pathsz(Dirs) -> ok + + Add directories to the end of the code path - - Dirs = [Dir] - Dir = string() - -

Adds the directories in Dirs to the end of the code - path. If a Dir already exists, it is not added. This +

Adds the directories in Dirs to the end of the code + path. If a Dir already exists, it is not added. This function always returns ok, regardless of the validity - of each individual Dir.

+ of each individual Dir.

 - add_pathsa(Dirs) -> ok + Add directories to the beginning of the code path - - Dirs = [Dir] - Dir = string() - -

Adds the directories in Dirs to the beginning of - the code path. If a Dir already exists, it is removed +

Adds the directories in Dirs to the beginning of + the code path. If a Dir already exists, it is removed from the old position in the code path. This function always returns ok, regardless of the validity of each - individual Dir.

+ individual Dir.

 - del_path(Name | Dir) -> true | false | {error, What} + Delete a directory from the code path - - Name = atom() - Dir = string() - What = bad_name -

Deletes a directory from the code path. The argument can be - an atom Name, in which case the directory with - the name .../Name[-Vsn][/ebin] is deleted from the code + an atom Name, in which case the directory with + the name .../Name[-Vsn][/ebin] is deleted from the code path. It is also possible to give the complete directory name - Dir as argument.

+ Dir as argument.

Returns true if successful, or false if the directory is not found, or {error, bad_name} if the argument is invalid.

 - replace_path(Name, Dir) -> true | {error, What} + Replace a directory with another in the code path - - Name = atom() - Dir = string() - What = bad_name | bad_directory | {badarg, term()} -

This function replaces an old occurrence of a directory - named .../Name[-Vsn][/ebin], in the code path, with - Dir. If Name does not exist, it adds the new - directory Dir last in the code path. The new directory - must also be named .../Name[-Vsn][/ebin]. This function + named .../Name[-Vsn][/ebin], in the code path, with + Dir. If Name does not exist, it adds the new + directory Dir last in the code path. The new directory + must also be named .../Name[-Vsn][/ebin]. This function should be used if a new version of the directory (library) is added to a running system.

Returns true if successful, or - {error, bad_name} if Name is not found, or - {error, bad_directory} if Dir does not exist, or - {error, {badarg, [Name, Dir]}} if Name or - Dir is invalid.

+ {error, bad_name} if Name is not found, or + {error, bad_directory} if Dir does not exist, or + {error, {badarg, [Name, Dir]}} if Name or + Dir is invalid.

 - load_file(Module) -> {module, Module} | {error, What} + Load a module - - Module = atom() - What = nofile | sticky_directory | badarg | term() - + -

Tries to load the Erlang module Module, using +

Tries to load the Erlang module Module, using the code path. It looks for the object code file with an extension that corresponds to the Erlang machine used, for - example Module.beam. The loading fails if the module + example Module.beam. The loading fails if the module name found in the object code differs from the name - Module. + Module. load_binary/3 must be used to load object code with a module name that is different from the file name.

-

Returns {module, Module} if successful, or +

Returns {module, Module} if successful, or {error, nofile} if no object code is found, or {error, sticky_directory} if the object code resides in - a sticky directory, or {error, badarg} if the argument - is invalid. Also if the loading fails, an error tuple is + a sticky directory. Also if the loading fails, an error tuple is returned. See erlang:load_module/2 - for possible values of What.

+ for possible values of What.

 - load_abs(Filename) -> {module, Module} | {error, What} + Load a module, residing in a given file - - Filename = string() - Module = atom() - What = nofile | sticky_directory | badarg | term() - + + + -

Does the same as load_file(Module), but - Filename is either an absolute file name, or a +

Does the same as load_file(Module), but + Filename is either an absolute file name, or a relative file name. The code path is not searched. It returns a value in the same way as load_file/1. Note - that Filename should not contain the extension (for + that Filename should not contain the extension (for example ".beam"); load_abs/1 adds the correct extension itself.

 - ensure_loaded(Module) -> {module, Module} | {error, What} + Ensure that a module is loaded - - Module = atom() - What = nofile | sticky_directory | embedded | badarg | term() -

Tries to to load a module in the same way as load_file/1, @@ -487,54 +447,45 @@ - load_binary(Module, Filename, Binary) -> {module, Module} | {error, What} + Load object code for a module - - Module = atom() - Filename = string() - What = sticky_directory | badarg | term() - + +

This function can be used to load object code on remote - Erlang nodes. The argument Binary must contain - object code for Module. - Filename is only used by the code server to keep a - record of from which file the object code for Module - comes. Accordingly, Filename is not opened and read by + Erlang nodes. The argument Binary must contain + object code for Module. + Filename is only used by the code server to keep a + record of from which file the object code for Module + comes. Accordingly, Filename is not opened and read by the code server.

-

Returns {module, Module} if successful, or +

Returns {module, Module} if successful, or {error, sticky_directory} if the object code resides in a sticky directory, or {error, badarg} if any argument is invalid. Also if the loading fails, an error tuple is returned. See erlang:load_module/2 - for possible values of What.

+ for possible values of What.

 - delete(Module) -> true | false + Removes current code for a module - - Module = atom() - -

Removes the current code for Module, that is, - the current code for Module is made old. This means +

Removes the current code for Module, that is, + the current code for Module is made old. This means that processes can continue to execute the code in the module, but that no external function calls can be made to it.

Returns true if successful, or false if there - is old code for Module which must be purged first, or - if Module is not a (loaded) module.

+ is old code for Module which must be purged first, or + if Module is not a (loaded) module.

 - purge(Module) -> true | false + Removes old code for a module - - Module = atom() - -

Purges the code for Module, that is, removes code +

Purges the code for Module, that is, removes code marked as old. If some processes still linger in the old code, these processes are killed before the code is removed.

Returns true if successful and any process needed to @@ -542,31 +493,26 @@ - soft_purge(Module) -> true | false + Removes old code for a module, unless no process uses it - - Module = atom() - -

Purges the code for Module, that is, removes code +

Purges the code for Module, that is, removes code marked as old, but only if no processes linger in it.

Returns false if the module could not be purged due to processes lingering in old code, otherwise true.

 - is_loaded(Module) -> {file, Loaded} | false + Check if a module is loaded - - Module = atom() - Loaded = Absname | preloaded | cover_compiled - Absname = string() - - -

Checks if Module is loaded. If it is, - {file, Loaded} is returned, otherwise false.

-

Normally, Loaded is the absolute file name - Absname from which the code was obtained. If the module + + + Filename is an absolute filename + +

Checks if Module is loaded. If it is, + {file, Loaded} is returned, otherwise false.

+

Normally, Loaded is the absolute file name + Filename from which the code was obtained. If the module is preloaded (see script(4)), Loaded==preloaded. If the module is Cover compiled (see @@ -575,32 +521,26 @@ - all_loaded() -> [{Module, Loaded}] + Get all loaded modules - - Module = atom() - Loaded = Absname | preloaded | cover_compiled - Absname = string() - + + + Filename is an absolute filename -

Returns a list of tuples {Module, Loaded} for all - loaded modules. Loaded is normally the absolute file +

Returns a list of tuples {Module, Loaded} for all + loaded modules. Loaded is normally the absolute file name, as described for is_loaded/1.

 - which(Module) -> Which + The object code file of a module - - Module = atom() - Which = Filename | non_existing | preloaded | cover_compiled - Filename = string() - +

If the module is not loaded, this function searches the code path for the first file which contains object code for - Module and returns the absolute file name. If + Module and returns the absolute file name. If the module is loaded, it returns the name of the file which contained the loaded object code. If the module is pre-loaded, preloaded is returned. If the module is Cover compiled, @@ -609,21 +549,16 @@ - get_object_code(Module) -> {Module, Binary, Filename} | error + Get the object code for a module - - Module = atom() - Binary = binary() - Filename = string() -

Searches the code path for the object code of the module - Module. It returns {Module, Binary, Filename} - if successful, and error if not. Binary is a + Module. It returns {Module, Binary, Filename} + if successful, and error if not. Binary is a binary data object which contains the object code for the module. This can be useful if code is to be loaded on a remote node in a distributed system. For example, loading - module Module on a node Node is done as + module Module on a node Node is done as follows:

... @@ -633,7 +568,7 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - root_dir() -> string() + Root directory of Erlang/OTP

Returns the root directory of Erlang/OTP, which is @@ -644,7 +579,7 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - lib_dir() -> string() + Library directory of Erlang/OTP

Returns the library directory, $OTPROOT/lib, where @@ -655,19 +590,16 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - lib_dir(Name) -> string() | {error, bad_name} + Library directory for an application - - Name = atom() -

This function is mainly intended for finding out the path for the "library directory", the top directory, for an - application Name located under $OTPROOT/lib or + application Name located under $OTPROOT/lib or on a directory referred to via the ERL_LIBS environment variable.

-

If there is a regular directory called Name or - Name-Vsn in the code path with an ebin +

If there is a regular directory called Name or + Name-Vsn in the code path with an ebin subdirectory, the path to this directory is returned (not the ebin directory). If the directory refers to a directory in an archive, the archive name is stripped away @@ -681,23 +613,19 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), 

 > code:lib_dir(mnesia).
 "/usr/local/otp/lib/mnesia-4.2.2"
-

Returns {error, bad_name} if Name +

Returns {error, bad_name} if Name is not the name of an application under $OTPROOT/lib or on a directory referred to via the ERL_LIBS environment variable. Fails with an exception if Name has the wrong type.

-

For backward compatibility, Name is also allowed to +

For backward compatibility, Name is also allowed to be a string. That will probably change in a future release.

 - lib_dir(Name, SubDir) -> string() | {error, bad_name} + subdirectory for an application - - Name = atom() - SubDir = atom() -

Returns the path to a subdirectory directly under the top directory of an application. Normally the subdirectories @@ -711,12 +639,12 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), > code:lib_dir(megaco, priv). "/usr/local/otp/lib/megaco-3.9.1.1/priv" -

Fails with an exception if Name or SubDir has +

Fails with an exception if Name or SubDir has the wrong type.

 - compiler_dir() -> string() + Library directory for the compiler

Returns the compiler library directory. Equivalent to @@ -724,21 +652,18 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - priv_dir(Name) -> string() | {error, bad_name} + Priv directory for an application - - Name = atom() -

Returns the path to the priv directory in an - application. Equivalent to code:lib_dir(Name,priv)..

+ application. Equivalent to code:lib_dir(Name, priv)..

-

For backward compatibility, Name is also allowed to +

For backward compatibility, Name is also allowed to be a string. That will probably change in a future release.

 - objfile_extension() -> ".beam" + Object code file extension

Returns the object code file extension that corresponds to @@ -746,24 +671,16 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - stick_dir(Dir) -> ok | error + Mark a directory as sticky - - Dir = string() - What = term() - -

This function marks Dir as sticky.

+

This function marks Dir as sticky.

Returns ok if successful or error if not.

 - unstick_dir(Dir) -> ok | error + Remove a sticky directory mark - - Dir = string() - What = term() -

This function unsticks a directory which has been marked as sticky.

@@ -771,45 +688,39 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - is_sticky(Module) -> true | false + Test whether a module is sticky - - Module = atom() - -

This function returns true if Module is the +

This function returns true if Module is the name of a module that has been loaded from a sticky directory (or in other words: an attempt to reload the module will fail), - or false if Module is not a loaded module or is + or false if Module is not a loaded module or is not sticky.

 - rehash() -> ok + Rehash or create code path cache

This function creates or rehashes the code path cache.

 - where_is_file(Filename) -> Absname | non_existing + Full name of a file located in the code path - - Filename = Absname = string() - -

Searches the code path for Filename, a file of +

Searches the code path for Filename, a file of arbitrary type. If found, the full name is returned. non_existing is returned if the file cannot be found. The function can be useful, for example, to locate application resource files. If the code path cache is used, the code server will efficiently read the full name from - the cache, provided that Filename is an object code + the cache, provided that Filename is an object code file or an .app file.

 - clash() -> ok + Search for modules with identical names.

Searches the entire code space for module names with @@ -817,10 +728,10 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), - is_module_native(Module) -> true | false | undefined + is_module_native(Module) -> boolean() | undefined Test whether a module has native code - Module = atom() + Module = module()

This function returns true if Module is diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index e0feaf6ee7..861c582211 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -94,9 +94,6 @@ - - - @@ -135,12 +132,6 @@ Unix, and in the runtime libraries of most C compilers.

 - - - - - - @@ -1220,15 +1211,15 @@ f.txt: {person, "kalle", 25}.

The current system access to the file.

 - atime = time() + atime = date_time()

The last (local) time the file was read.

 - mtime = time() + mtime = date_time()

The last (local) time the file was written.

 - ctime = time() + ctime = date_time()

The interpretation of this time field depends on the operating system. On Unix, it is the last time @@ -1669,15 +1660,15 @@ f.txt: {person, "kalle", 25}.

The following fields are used from the record, if they are given.

- atime = time() + atime = date_time()

The last (local) time the file was read.

 - mtime = time() + mtime = date_time()

The last (local) time the file was written.

 - ctime = time() + ctime = date_time()

On Unix, any value give for this field will be ignored (the "ctime" for the file will be set to the current diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index 56fc1834ec..e94119845a 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -126,9 +126,10 @@ DirOut = os:cmd("dir"), % on Win32 platform - timestamp() -> {MegaSecs, Secs, MicroSecs} + timestamp() -> Timestamp Returna a timestamp from the OS in the erlang:now/0 format + Timestamp = {MegaSecs, Secs, MicroSecs} = erlang:timestamp() MegaSecs = Secs = MicroSecs = integer() >= 0 -- cgit v1.2.3