docs and deprecations for Libc/Libdl

NEWS.md

@@ -284,6 +284,9 @@ Deprecated or removed
     `Array{T}(x)`, `map(T,x)`, or `round(T,x)`. To parse a string as an integer
     or floating-point number, use `parseint` or `parsefloat` ([#1470], [#6211]).
 
+  * Low-level functions from the C library and dynamic linker have been moved to
+    modules `Libc` and `Libdl`, respectively ([#10328]).
+
 Julia v0.3.0 Release Notes
 ==========================
 

base/base.jl

@@ -74,7 +74,7 @@ type SystemError <: Exception
     prefix::AbstractString
     errnum::Int32
     SystemError(p::AbstractString, e::Integer) = new(p, e)
-    SystemError(p::AbstractString) = new(p, errno())
+    SystemError(p::AbstractString) = new(p, Libc.errno())
 end
 
 type TypeError <: Exception

base/deprecated.jl

@@ -421,6 +421,24 @@ end
 @deprecate flipud(A::AbstractArray) flipdim(A, 1)
 @deprecate fliplr(A::AbstractArray) flipdim(A, 2)
 
+@deprecate strftime     Libc.strftime
+@deprecate strptime     Libc.strptime
+@deprecate flush_cstdio Libc.flush_cstdio
+@deprecate mmap         Libc.mmap
+@deprecate c_free       Libc.free
+@deprecate c_malloc     Libc.malloc
+@deprecate c_calloc     Libc.calloc
+@deprecate c_realloc    Libc.realloc
+@deprecate errno        Libc.errno
+@deprecate strerror     Libc.strerror
+
+@deprecate dlclose      Libdl.dlclose
+@deprecate dlopen       Libdl.dlopen
+@deprecate dlopen_e     Libdl.dlopen_e
+@deprecate dlsym        Libdl.dlsym
+@deprecate dlsym_e      Libdl.dlsym_e
+@deprecate find_library Libdl.find_library
+
 # 0.4 discontinued functions
 
 @noinline function subtypetree(x::DataType, level=-1)

base/exports.jl

@@ -1132,6 +1132,7 @@ export
     mark,
     mmap_array,
     mmap_bitarray,
+    msync,
     nb_available,
     ntoh,
     open,

base/file.jl

@@ -164,7 +164,7 @@ function mktempdir()
         if ret == 0
             return filename
         end
-        systemerror(:mktempdir, errno()!=EEXIST)
+        systemerror(:mktempdir, Libc.errno()!=EEXIST)
         seed += 1
     end
 end

base/multi.jl

@@ -1571,7 +1571,7 @@ function disable_nagle(sock)
     @linux_only begin
         # tcp_quickack is a linux only option
         if ccall(:jl_tcp_quickack, Cint, (Ptr{Void}, Cint), sock.handle, 1) < 0
-            warn_once("Parallel networking unoptimized ( Error enabling TCP_QUICKACK : ", strerror(errno()), " )")
+            warn_once("Parallel networking unoptimized ( Error enabling TCP_QUICKACK : ", Libc.strerror(Libc.errno()), " )")
         end
     end
 end

base/replutil.jl

@@ -109,7 +109,7 @@ function showerror(io::IO, ex::DomainError, bt)
     show_backtrace(io, bt)
 end
 
-showerror(io::IO, ex::SystemError) = print(io, "SystemError: $(ex.prefix): $(strerror(ex.errnum))")
+showerror(io::IO, ex::SystemError) = print(io, "SystemError: $(ex.prefix): $(Libc.strerror(ex.errnum))")
 showerror(io::IO, ::DivideError) = print(io, "DivideError: integer division error")
 showerror(io::IO, ::StackOverflowError) = print(io, "StackOverflowError:")
 showerror(io::IO, ::UndefRefError) = print(io, "UndefRefError: access to undefined reference")

base/sysimg.jl

@@ -101,7 +101,7 @@ include("iostream.jl")
 
 # system & environment
 include("libc.jl")
-using .Libc: getpid, gethostname, errno, strerror, time
+using .Libc: getpid, gethostname, time, msync
 include("libdl.jl")
 include("env.jl")
 include("path.jl")

doc/stdlib/base.rst

@@ -713,26 +713,14 @@ System
 
    Get julia's process ID.
 
-.. function:: time([t::TmStruct])
+.. function:: time()
 
-   Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. When passed a ``TmStruct``, converts it to a number of seconds since the epoch.
+   Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution.
 
 .. function:: time_ns()
 
    Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years.
 
-.. function:: strftime([format], time)
-
-   Convert time, given as a number of seconds since the epoch or a ``TmStruct``, to a formatted string using the given format. Supported formats are the same as those in the standard C library.
-
-.. function:: strptime([format], timestr)
-
-   Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the ``isdst`` field should be filled in manually. Setting it to ``-1`` will tell the C library to use the current system settings to determine the timezone.
-
-.. function:: TmStruct([seconds])
-
-   Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, ``year``, ``wday``, ``yday``, and ``isdst``.
-
 .. function:: tic()
 
    Set a timer to be read by the next call to :func:`toc` or :func:`toq`. The macro call ``@time expr`` can also be used to time evaluation.

doc/stdlib/c.rst

@@ -36,104 +36,6 @@
 
    	bar = cfunction(foo, Float64, ())
 
-
-.. function:: dlopen(library_file::AbstractString [, flags::Integer])
-
-   Load a shared library, returning an opaque handle.
-
-   The optional flags argument is a bitwise-or of zero or more of
-   ``RTLD_LOCAL``, ``RTLD_GLOBAL``, ``RTLD_LAZY``, ``RTLD_NOW``, ``RTLD_NODELETE``,
-   ``RTLD_NOLOAD``, ``RTLD_DEEPBIND``, and ``RTLD_FIRST``.  These are converted to
-   the corresponding flags of the POSIX (and/or GNU libc and/or MacOS)
-   dlopen command, if possible, or are ignored if the specified
-   functionality is not available on the current platform.  The
-   default is ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL``.  An important usage
-   of these flags, on POSIX platforms, is to specify
-   ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` in order for the library's
-   symbols to be available for usage in other shared libraries, in
-   situations where there are dependencies between shared libraries.
-
-.. function:: dlopen_e(library_file::AbstractString [, flags::Integer])
-
-   Similar to :func:`dlopen`, except returns a ``NULL`` pointer instead of raising errors.
-
-.. data:: RTLD_DEEPBIND
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_FIRST
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_GLOBAL
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_LAZY
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_LOCAL
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_NODELETE
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_NOLOAD
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. data:: RTLD_NOW
-
-   Enum constant for :func:`dlopen`. See your platform man page for details, if applicable.
-
-.. function:: dlsym(handle, sym)
-
-   Look up a symbol from a shared library handle, return callable function pointer on success.
-
-.. function:: dlsym_e(handle, sym)
-
-   Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure.
-
-.. function:: dlclose(handle)
-
-   Close shared library referenced by handle.
-
-.. function:: find_library(names, locations)
-
-   Searches for the first library in ``names`` in the paths in the ``locations`` list, ``DL_LOAD_PATH``, or system
-   library paths (in that order) which can successfully be dlopen'd. On success, the return value will be one of
-   the names (potentially prefixed by one of the paths in locations). This string can be assigned to a ``global const``
-   and used as the library name in future ``ccall``'s. On failure, it returns the empty string.
-
-.. data:: DL_LOAD_PATH
-
-   When calling ``dlopen``, the paths in this list will be searched first, in order, before searching the
-   system locations for a valid library handle.
-
-.. function:: c_malloc(size::Integer) -> Ptr{Void}
-
-   Call ``malloc`` from the C standard library.
-
-.. function:: c_calloc(num::Integer, size::Integer) -> Ptr{Void}
-
-   Call ``calloc`` from the C standard library.
-
-.. function:: c_realloc(addr::Ptr, size::Integer) -> Ptr{Void}
-
-   Call ``realloc`` from the C standard library.
-
-   See warning in ``c_free`` documentation regarding only using this on memory originally obtained from ``c_malloc``.
-
-.. function:: c_free(addr::Ptr)
-
-   Call ``free`` from the C standard library. Only use this on memory obtained from ``c_malloc``,
-   not on pointers retrieved from other C libraries.
-   ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library,
-   to avoid assertion failures if multiple ``libc`` libraries exist on the system.
-
 .. function:: unsafe_convert(T,x)
 
    Convert "x" to a value of type "T"
@@ -162,7 +64,6 @@
 
 .. function:: unsafe_load(p::Ptr{T},i::Integer)
 
-
    Load a value of type ``T`` from the address of the ith element (1-indexed)
    starting at ``p``. This is equivalent to the C expression ``p[i-1]``.
 
@@ -249,23 +150,10 @@
    Re-enable Ctrl-C handler during execution of a function. Temporarily
    reverses the effect of ``disable_sigint``.
 
-.. function:: errno([code])
-
-   Get the value of the C library's ``errno``. If an argument is specified, it is
-   used to set the value of ``errno``.
-
-   The value of ``errno`` is only valid immediately after a ``ccall`` to a C
-   library routine that sets it. Specifically, you cannot call ``errno`` at the next
-   prompt in a REPL, because lots of code is executed between prompts.
-
 .. function:: systemerror(sysfunc, iftrue)
 
    Raises a ``SystemError`` for ``errno`` with the descriptive string ``sysfunc`` if ``bool`` is true
 
-.. function:: strerror(errno)
-
-   Convert a system call error code to a descriptive string
-
 .. data:: Ptr{T}
 
    A memory address referring to data of type ``T``.

doc/stdlib/index.rst

@@ -25,4 +25,6 @@
    collections
    test
    c
+   libc
+   libdl
    profile

doc/stdlib/io-network.rst

@@ -77,11 +77,6 @@ General I/O
 
    Commit all currently buffered writes to the given stream.
 
-.. function:: flush_cstdio()
-
-   Flushes the C ``stdout`` and ``stderr`` streams (which may have been
-   written to by external C code).
-
 .. function:: close(stream)
 
    Close an I/O stream. Performs a ``flush`` first.
@@ -659,33 +654,6 @@ Memory-mapped I/O
 
    Forces synchronization between the in-memory version of a memory-mapped ``Array`` or ``BitArray`` and the on-disk version.
 
-.. function:: msync(ptr, len, [flags])
-
-   Forces synchronization of the :func:`mmap`\ ped memory region from ``ptr`` to ``ptr+len``. Flags defaults to ``MS_SYNC``, but can be a combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows.
-
-   You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation.
-
-.. data:: MS_ASYNC
-
-   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
-
-.. data:: MS_SYNC
-
-   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
-
-.. data:: MS_INVALIDATE
-
-   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
-
-.. function:: mmap(len, prot, flags, fd, offset)
-
-   Low-level interface to the ``mmap`` system call. See the man page.
-
-.. function:: munmap(pointer, len)
-
-   Low-level interface for unmapping memory (see the man page). With :func:`mmap_array` you do not need to call this directly; the memory is unmapped for you when the array goes out of scope.
-
-
 Network I/O
 -----------
 

doc/stdlib/libc.rst

@@ -0,0 +1,86 @@
+.. module:: Libc
+
+********************
+ C Standard Library
+********************
+
+.. function:: malloc(size::Integer) -> Ptr{Void}
+
+   Call ``malloc`` from the C standard library.
+
+.. function:: calloc(num::Integer, size::Integer) -> Ptr{Void}
+
+   Call ``calloc`` from the C standard library.
+
+.. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void}
+
+   Call ``realloc`` from the C standard library.
+
+   See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``.
+
+.. function:: free(addr::Ptr)
+
+   Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``,
+   not on pointers retrieved from other C libraries.
+   ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library,
+   to avoid assertion failures if multiple ``libc`` libraries exist on the system.
+
+.. function:: errno([code])
+
+   Get the value of the C library's ``errno``. If an argument is specified, it is
+   used to set the value of ``errno``.
+
+   The value of ``errno`` is only valid immediately after a ``ccall`` to a C
+   library routine that sets it. Specifically, you cannot call ``errno`` at the next
+   prompt in a REPL, because lots of code is executed between prompts.
+
+.. function:: strerror(n)
+
+   Convert a system call error code to a descriptive string
+
+.. function:: time(t::TmStruct)
+
+   Converts a ``TmStruct`` struct to a number of seconds since the epoch.
+
+.. function:: strftime([format], time)
+
+   Convert time, given as a number of seconds since the epoch or a ``TmStruct``, to a formatted string using the given format. Supported formats are the same as those in the standard C library.
+
+.. function:: strptime([format], timestr)
+
+   Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the ``isdst`` field should be filled in manually. Setting it to ``-1`` will tell the C library to use the current system settings to determine the timezone.
+
+.. function:: TmStruct([seconds])
+
+   Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, ``year``, ``wday``, ``yday``, and ``isdst``.
+
+.. function:: flush_cstdio()
+
+   Flushes the C ``stdout`` and ``stderr`` streams (which may have been
+   written to by external C code).
+
+.. function:: msync(ptr, len, [flags])
+
+   Forces synchronization of the :func:`mmap`\ ped memory region from ``ptr`` to ``ptr+len``. Flags defaults to ``MS_SYNC``, but can be a combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows.
+
+   You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation.
+
+.. data:: MS_ASYNC
+
+   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
+
+.. data:: MS_SYNC
+
+   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
+
+.. data:: MS_INVALIDATE
+
+   Enum constant for :func:`msync`. See your platform man page for details. (not available on Windows).
+
+.. function:: mmap(len, prot, flags, fd, offset)
+
+   Low-level interface to the ``mmap`` system call. See the man page.
+
+.. function:: munmap(pointer, len)
+
+   Low-level interface for unmapping memory (see the man page). With :func:`mmap_array` you do not need to call this directly; the memory is unmapped for you when the array goes out of scope.