From 074286c9039a289ff97048a05bf53ab755781dbc Mon Sep 17 00:00:00 2001 From: Jeff Bezanson Date: Mon, 9 Mar 2015 17:16:47 -0400 Subject: [PATCH] docs and deprecations for Libc/Libdl --- NEWS.md | 3 + base/base.jl | 2 +- base/deprecated.jl | 18 ++++++ base/exports.jl | 1 + base/file.jl | 2 +- base/multi.jl | 2 +- base/replutil.jl | 2 +- base/sysimg.jl | 2 +- doc/stdlib/base.rst | 16 +----- doc/stdlib/c.rst | 112 -------------------------------------- doc/stdlib/index.rst | 2 + doc/stdlib/io-network.rst | 32 ----------- doc/stdlib/libc.rst | 86 +++++++++++++++++++++++++++++ doc/stdlib/libdl.rst | 81 +++++++++++++++++++++++++++ 14 files changed, 198 insertions(+), 163 deletions(-) create mode 100644 doc/stdlib/libc.rst create mode 100644 doc/stdlib/libdl.rst diff --git a/NEWS.md b/NEWS.md index 2c639df77898a..55640e6516b93 100644 --- a/NEWS.md +++ b/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 ========================== diff --git a/base/base.jl b/base/base.jl index c3ad12722383b..5940c40099257 100644 --- a/base/base.jl +++ b/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 diff --git a/base/deprecated.jl b/base/deprecated.jl index 9e244234b58c6..35740aa52db0f 100644 --- a/base/deprecated.jl +++ b/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) diff --git a/base/exports.jl b/base/exports.jl index ba0b22b509580..f8cd1de2fa4f9 100644 --- a/base/exports.jl +++ b/base/exports.jl @@ -1132,6 +1132,7 @@ export mark, mmap_array, mmap_bitarray, + msync, nb_available, ntoh, open, diff --git a/base/file.jl b/base/file.jl index 7ded92a659d30..285157b27ec18 100644 --- a/base/file.jl +++ b/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 diff --git a/base/multi.jl b/base/multi.jl index 86b0e15bafdbf..8b292705cf46f 100644 --- a/base/multi.jl +++ b/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 diff --git a/base/replutil.jl b/base/replutil.jl index 010150ec5dc62..0e79b2e342798 100644 --- a/base/replutil.jl +++ b/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") diff --git a/base/sysimg.jl b/base/sysimg.jl index 2c1f1253a6d75..1f4e2ec77fad2 100644 --- a/base/sysimg.jl +++ b/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") diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 4dfe1a1052d15..891a13322411c 100644 --- a/doc/stdlib/base.rst +++ b/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. diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index 375e5ec96be6e..a142a5c9056de 100644 --- a/doc/stdlib/c.rst +++ b/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``. diff --git a/doc/stdlib/index.rst b/doc/stdlib/index.rst index 43d2e38c62531..f655bca911ade 100644 --- a/doc/stdlib/index.rst +++ b/doc/stdlib/index.rst @@ -25,4 +25,6 @@ collections test c + libc + libdl profile diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 47dd60828a3d2..3bf644e59ca23 100644 --- a/doc/stdlib/io-network.rst +++ b/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 ----------- diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst new file mode 100644 index 0000000000000..12d8a6f33d562 --- /dev/null +++ b/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. diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst new file mode 100644 index 0000000000000..5620978db9d49 --- /dev/null +++ b/doc/stdlib/libdl.rst @@ -0,0 +1,81 @@ +.. module:: Libdl + +**************** + Dynamic Linker +**************** + +.. function:: dlopen(libfile::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(libfile::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.