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.