Move libc and libdl docstrings inline, out of helpdb.

base/deprecated.jl

@@ -608,6 +608,18 @@ end
 const MS_ASYNC = 1
 const MS_INVALIDATE = 2
 const MS_SYNC = 4
+"""
+    msync(ptr, len, [flags])
+
+Forces synchronization of the [`mmap`](: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.
+"""
 @noinline function msync(p::Ptr, len::Integer, flags::Integer=MS_SYNC)
     depwarn("`msync` is deprecated, use `Mmap.sync!(array)` instead", :msync)
     systemerror("msync", ccall(:msync, Cint, (Ptr{Void}, Csize_t, Cint), p, len, flags) != 0)

base/docs/helpdb.jl

@@ -2,8 +2,6 @@
 
 import .Docs: keywords
 
-include("helpdb/Libdl.jl")
-include("helpdb/Libc.jl")
 include("helpdb/Profile.jl")
 include("helpdb/Base.jl")
 include("helpdb/Dates.jl")

base/libc.jl

@@ -69,6 +69,12 @@ end
 Base.position(h::FILE) = ccall(:ftell, Clong, (Ptr{Void},), h.ptr)
 
 # flush C stdio output from external libraries
+
+"""
+    flush_cstdio()
+
+Flushes the C `stdout` and `stderr` streams (which may have been written to by external C code).
+"""
 flush_cstdio() = ccall(:jl_flush_cstdio, Void, ())
 
 ## time-related functions ##
@@ -89,6 +95,12 @@ function TimeVal()
     return tv[]
 end
 
+"""
+    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`.
+"""
 type TmStruct
     sec::Int32
     min::Int32
@@ -118,6 +130,13 @@ type TmStruct
     end
 end
 
+"""
+    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.
+"""
 strftime(t) = strftime("%c", t)
 strftime(fmt::AbstractString, t::Real) = strftime(fmt, TmStruct(t))
 function strftime(fmt::AbstractString, tm::TmStruct)
@@ -130,6 +149,16 @@ function strftime(fmt::AbstractString, tm::TmStruct)
     bytestring(pointer(timestr), n)
 end
 
+"""
+    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.
+"""
 strptime(timestr::AbstractString) = strptime("%c", timestr)
 function strptime(fmt::AbstractString, timestr::AbstractString)
     tm = TmStruct()
@@ -154,6 +183,12 @@ function strptime(fmt::AbstractString, timestr::AbstractString)
 end
 
 # system date in seconds
+
+"""
+    time(t::TmStruct)
+
+Converts a `TmStruct` struct to a number of seconds since the epoch.
+"""
 time(tm::TmStruct) = Float64(ccall(:mktime, Int, (Ptr{TmStruct},), &tm))
 time() = ccall(:jl_clock_now, Float64, ())
 
@@ -173,8 +208,24 @@ end
 
 ## system error handling ##
 
+"""
+    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.
+"""
 errno() = ccall(:jl_errno, Cint, ())
 errno(e::Integer) = ccall(:jl_set_errno, Void, (Cint,), e)
+
+"""
+    strerror(n=errno())
+
+Convert a system call error code to a descriptive string
+"""
 strerror(e::Integer) = bytestring(ccall(:strerror, Cstring, (Int32,), e))
 strerror() = strerror(errno())
 
@@ -213,10 +264,40 @@ end
 
 ## Memory related ##
 
+"""
+    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.
+"""
 free(p::Ptr) = ccall(:free, Void, (Ptr{Void},), p)
+
+"""
+    malloc(size::Integer) -> Ptr{Void}
+
+Call `malloc` from the C standard library.
+"""
 malloc(size::Integer) = ccall(:malloc, Ptr{Void}, (Csize_t,), size)
+
+"""
+    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`.
+"""
 realloc(p::Ptr, size::Integer) = ccall(:realloc, Ptr{Void}, (Ptr{Void}, Csize_t), p, size)
+
+"""
+    calloc(num::Integer, size::Integer) -> Ptr{Void}
+
+Call `calloc` from the C standard library.
+"""
 calloc(num::Integer, size::Integer) = ccall(:calloc, Ptr{Void}, (Csize_t, Csize_t), num, size)
+
 free(p::Cstring) = free(convert(Ptr{UInt8}, p))
 free(p::Cwstring) = free(convert(Ptr{Cwchar_t}, p))