diff options
Diffstat (limited to 'go/golang/go/doc/go1.10.html')
| -rw-r--r-- | go/golang/go/doc/go1.10.html | 1448 |
1 files changed, 1448 insertions, 0 deletions
diff --git a/go/golang/go/doc/go1.10.html b/go/golang/go/doc/go1.10.html new file mode 100644 index 00000000..2974fef9 --- /dev/null +++ b/go/golang/go/doc/go1.10.html @@ -0,0 +1,1448 @@ +<!--{ + "Title": "Go 1.10 Release Notes", + "Path": "/doc/go1.10", + "Template": true +}--> + +<!-- +NOTE: In this document and others in this directory, the convention is to +set fixed-width phrases with non-fixed-width spaces, as in +<code>hello</code> <code>world</code>. +Do not send CLs removing the interior tags from such phrases. +--> + +<style> +ul li { margin: 0.5em 0; } +</style> + +<h2 id="introduction">Introduction to Go 1.10</h2> + +<p> +The latest Go release, version 1.10, arrives six months after <a href="go1.9">Go 1.9</a>. +Most of its changes are in the implementation of the toolchain, runtime, and libraries. +As always, the release maintains the Go 1 <a href="/doc/go1compat.html">promise of compatibility</a>. +We expect almost all Go programs to continue to compile and run as before. +</p> + +<p> +This release improves <a href="#build">caching of built packages</a>, +adds <a href="#test">caching of successful test results</a>, +runs <a href="#test-vet">vet automatically during tests</a>, +and +permits <a href="#cgo">passing string values directly between Go and C using cgo</a>. +A new <a href="#cgo">compiler option whitelist</a> may cause +unexpected <a href="https://golang.org/s/invalidflag"><code>invalid +flag</code></a> errors in code that built successfully with older +releases. +</p> + +<h2 id="language">Changes to the language</h2> + +<p> +There are no significant changes to the language specification. +</p> + +<p><!-- CL 60230 --> +A corner case involving shifts of untyped constants has been clarified, +and as a result the compilers have been updated to allow the index expression +<code>x[1.0</code> <code><<</code> <code>s]</code> where <code>s</code> is an unsigned integer; +the <a href="/pkg/go/types/">go/types</a> package already did. +</p> + +<p><!-- CL 73233 --> +The grammar for method expressions has been updated to relax the +syntax to allow any type expression as a receiver; +this matches what the compilers were already implementing. +For example, <code>struct{io.Reader}.Read</code> is a valid, if unusual, +method expression that the compilers already accepted and is +now permitted by the language grammar. +</p> + +<h2 id="ports">Ports</h2> + +<p> +There are no new supported operating systems or processor architectures in this release. +Most of the work has focused on strengthening the support for existing ports, +in particular <a href="#asm">new instructions in the assembler</a> +and improvements to the code generated by the compilers. +</p> + +<p id="freebsd"> +As <a href="go1.9#freebsd">announced in the Go 1.9 release notes</a>, +Go 1.10 now requires FreeBSD 10.3 or later; +support for FreeBSD 9.3 has been removed. +</p> + +<p id="netbsd"> +Go now runs on NetBSD again but requires the unreleased NetBSD 8. +Only <code>GOARCH</code> <code>amd64</code> and <code>386</code> have +been fixed. The <code>arm</code> port is still broken. +</p> + +<p id="mips"> +On 32-bit MIPS systems, the new environment variable settings +<code>GOMIPS=hardfloat</code> (the default) and +<code>GOMIPS=softfloat</code> select whether to use +hardware instructions or software emulation for floating-point computations. +</p> + +<p id="openbsd"> +Go 1.10 is the last release that will run on OpenBSD 6.0. +Go 1.11 will require OpenBSD 6.2. +</p> + +<p id="darwin"> +Go 1.10 is the last release that will run on OS X 10.8 Mountain Lion or OS X 10.9 Mavericks. +Go 1.11 will require OS X 10.10 Yosemite or later. +</p> + +<p id="windows"> +Go 1.10 is the last release that will run on Windows XP or Windows Vista. +Go 1.11 will require Windows 7 or later. +</p> + +<h2 id="tools">Tools</h2> + +<h3 id="goroot">Default GOROOT & GOTMPDIR</h3> + +<p> +If the environment variable <code>$GOROOT</code> is unset, +the go tool previously used the default <code>GOROOT</code> +set during toolchain compilation. +Now, before falling back to that default, the go tool attempts to +deduce <code>GOROOT</code> from its own executable path. +This allows binary distributions to be unpacked anywhere in the +file system and then be used without setting <code>GOROOT</code> +explicitly. +</p> + +<p> +By default, the go tool creates its temporary files and directories +in the system temporary directory (for example, <code>$TMPDIR</code> on Unix). +If the new environment variable <code>$GOTMPDIR</code> is set, +the go tool will creates its temporary files and directories in that directory instead. +</p> + +<h3 id="build">Build & Install</h3> + +<p> +The <code>go</code> <code>build</code> command now detects out-of-date packages +purely based on the content of source files, specified build flags, and metadata stored in the compiled packages. +Modification times are no longer consulted or relevant. +The old advice to add <code>-a</code> to force a rebuild in cases where +the modification times were misleading for one reason or another +(for example, changes in build flags) is no longer necessary: +builds now always detect when packages must be rebuilt. +(If you observe otherwise, please file a bug.) +</p> + +<p> +The <code>go</code> <code>build</code> <code>-asmflags</code>, <code>-gcflags</code>, <code>-gccgoflags</code>, and <code>-ldflags</code> options +now apply by default only to the packages listed directly on the command line. +For example, <code>go</code> <code>build</code> <code>-gcflags=-m</code> <code>mypkg</code> +passes the compiler the <code>-m</code> flag when building <code>mypkg</code> +but not its dependencies. +The new, more general form <code>-asmflags=pattern=flags</code> (and similarly for the others) +applies the <code>flags</code> only to the packages matching the pattern. +For example: <code>go</code> <code>install</code> <code>-ldflags=cmd/gofmt=-X=main.version=1.2.3</code> <code>cmd/...</code> +installs all the commands matching <code>cmd/...</code> but only applies the <code>-X</code> option +to the linker flags for <code>cmd/gofmt</code>. +For more details, see <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go</code> <code>help</code> <code>build</code></a>. +</p> + +<p> +The <code>go</code> <code>build</code> command now maintains a cache of +recently built packages, separate from the installed packages in <code>$GOROOT/pkg</code> or <code>$GOPATH/pkg</code>. +The effect of the cache should be to speed builds that do not explicitly install packages +or when switching between different copies of source code (for example, when changing +back and forth between different branches in a version control system). +The old advice to add the <code>-i</code> flag for speed, as in <code>go</code> <code>build</code> <code>-i</code> +or <code>go</code> <code>test</code> <code>-i</code>, +is no longer necessary: builds run just as fast without <code>-i</code>. +For more details, see <a href="/cmd/go/#hdr-Build_and_test_caching"><code>go</code> <code>help</code> <code>cache</code></a>. +</p> + +<p> +The <code>go</code> <code>install</code> command now installs only the +packages and commands listed directly on the command line. +For example, <code>go</code> <code>install</code> <code>cmd/gofmt</code> +installs the gofmt program but not any of the packages on which it depends. +The new build cache makes future commands still run as quickly as if the +dependencies had been installed. +To force the installation of dependencies, use the new +<code>go</code> <code>install</code> <code>-i</code> flag. +Installing dependency packages should not be necessary in general, +and the very concept of installed packages may disappear in a future release. +</p> + +<p> +Many details of the <code>go</code> <code>build</code> implementation have changed to support these improvements. +One new requirement implied by these changes is that +binary-only packages must now declare accurate import blocks in their +stub source code, so that those imports can be made available when +linking a program using the binary-only package. +For more details, see <a href="/cmd/go/#hdr-File_types"><code>go</code> <code>help</code> <code>filetype</code></a>. +</p> + +<h3 id="test">Test</h3> + +<p> +The <code>go</code> <code>test</code> command now caches test results: +if the test executable and command line match a previous run +and the files and environment variables consulted by that run +have not changed either, <code>go</code> <code>test</code> will print +the previous test output, replacing the elapsed time with the string “(cached).” +Test caching applies only to successful test results; +only to <code>go</code> <code>test</code> +commands with an explicit list of packages; and +only to command lines using a subset of the +<code>-cpu</code>, <code>-list</code>, <code>-parallel</code>, +<code>-run</code>, <code>-short</code>, and <code>-v</code> test flags. +The idiomatic way to bypass test caching is to use <code>-count=1</code>. +</p> + +<p id="test-vet"> +The <code>go</code> <code>test</code> command now automatically runs +<code>go</code> <code>vet</code> on the package being tested, +to identify significant problems before running the test. +Any such problems are treated like build errors and prevent execution of the test. +Only a high-confidence subset of the available <code>go</code> <code>vet</code> +checks are enabled for this automatic check. +To disable the running of <code>go</code> <code>vet</code>, use +<code>go</code> <code>test</code> <code>-vet=off</code>. +</p> + +<p> +The <code>go</code> <code>test</code> <code>-coverpkg</code> flag now +interprets its argument as a comma-separated list of patterns to match against +the dependencies of each test, not as a list of packages to load anew. +For example, <code>go</code> <code>test</code> <code>-coverpkg=all</code> +is now a meaningful way to run a test with coverage enabled for the test package +and all its dependencies. +Also, the <code>go</code> <code>test</code> <code>-coverprofile</code> option is now +supported when running multiple tests. +</p> + +<p> +In case of failure due to timeout, tests are now more likely to write their profiles before exiting. +</p> + +<p> +The <code>go</code> <code>test</code> command now always +merges the standard output and standard error from a given test binary execution +and writes both to <code>go</code> <code>test</code>'s standard output. +In past releases, <code>go</code> <code>test</code> only applied this +merging most of the time. +</p> + +<p> +The <code>go</code> <code>test</code> <code>-v</code> output +now includes <code>PAUSE</code> and <code>CONT</code> status update +lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue. +</p> + +<p> +The new <code>go</code> <code>test</code> <code>-failfast</code> flag +disables running additional tests after any test fails. +Note that tests running in parallel with the failing test are allowed to complete. +</p> + +<p> +Finally, the new <code>go</code> <code>test</code> <code>-json</code> flag +filters test output through the new command +<code>go</code> <code>tool</code> <code>test2json</code> +to produce a machine-readable JSON-formatted description of test execution. +This allows the creation of rich presentations of test execution +in IDEs and other tools. +</p> + + +<p> +For more details about all these changes, +see <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>help</code> <code>test</code></a> +and the <a href="/cmd/test2json/">test2json documentation</a>. +</p> + +<h3 id="cgo">Cgo</h3> + +<p> +Options specified by cgo using <code>#cgo CFLAGS</code> and the like +are now checked against a whitelist of permitted options. +This closes a security hole in which a downloaded package uses +compiler options like +<span style="white-space: nowrap"><code>-fplugin</code></span> +to run arbitrary code on the machine where it is being built. +This can cause a build error such as <code>invalid flag in #cgo CFLAGS</code>. +For more background, and how to handle this error, see +<a href="https://golang.org/s/invalidflag">https://golang.org/s/invalidflag</a>. +</p> + +<p> +Cgo now implements a C typedef like “<code>typedef</code> <code>X</code> <code>Y</code>” using a Go type alias, +so that Go code may use the types <code>C.X</code> and <code>C.Y</code> interchangeably. +It also now supports the use of niladic function-like macros. +Also, the documentation has been updated to clarify that +Go structs and Go arrays are not supported in the type signatures of cgo-exported functions. +</p> + +<p> +Cgo now supports direct access to Go string values from C. +Functions in the C preamble may use the type <code>_GoString_</code> +to accept a Go string as an argument. +C code may call <code>_GoStringLen</code> and <code>_GoStringPtr</code> +for direct access to the contents of the string. +A value of type <code>_GoString_</code> +may be passed in a call to an exported Go function that takes an argument of Go type <code>string</code>. +</p> + +<p> +During toolchain bootstrap, the environment variables <code>CC</code> and <code>CC_FOR_TARGET</code> specify +the default C compiler that the resulting toolchain will use for host and target builds, respectively. +However, if the toolchain will be used with multiple targets, it may be necessary to specify a different C compiler for each +(for example, a different compiler for <code>darwin/arm64</code> versus <code>linux/ppc64le</code>). +The new set of environment variables <code>CC_FOR_<i>goos</i>_<i>goarch</i></code> +allows specifying a different default C compiler for each target. +Note that these variables only apply during toolchain bootstrap, +to set the defaults used by the resulting toolchain. +Later <code>go</code> <code>build</code> commands use the <code>CC</code> environment +variable or else the built-in default. +</p> + +<p> +Cgo now translates some C types that would normally map to a pointer +type in Go, to a <code>uintptr</code> instead. These types include +the <code>CFTypeRef</code> hierarchy in Darwin's CoreFoundation +framework and the <code>jobject</code> hierarchy in Java's JNI +interface. +</p> + +<p> +These types must be <code>uintptr</code> on the Go side because they +would otherwise confuse the Go garbage collector; they are sometimes +not really pointers but data structures encoded in a pointer-sized integer. +Pointers to Go memory must not be stored in these <code>uintptr</code> values. +</p> + +<p> +Because of this change, values of the affected types need to be +zero-initialized with the constant <code>0</code> instead of the +constant <code>nil</code>. Go 1.10 provides <code>gofix</code> +modules to help with that rewrite: +</p> + +<pre> +go tool fix -r cftype <pkg> +go tool fix -r jni <pkg> +</pre> + +<p> +For more details, see the <a href="/cmd/cgo/">cgo documentation</a>. +</p> + +<h3 id="doc">Doc</h3> + +<p> +The <code>go</code> <code>doc</code> tool now adds functions returning slices of <code>T</code> or <code>*T</code> +to the display of type <code>T</code>, similar to the existing behavior for functions returning single <code>T</code> or <code>*T</code> results. +For example: +</p> + +<pre> +$ go doc mail.Address +package mail // import "net/mail" + +type Address struct { + Name string + Address string +} + Address represents a single mail address. + +func ParseAddress(address string) (*Address, error) +func ParseAddressList(list string) ([]*Address, error) +func (a *Address) String() string +$ +</pre> + +<p> +Previously, <code>ParseAddressList</code> was only shown in the package overview (<code>go</code> <code>doc</code> <code>mail</code>). +</p> + +<h3 id="fix">Fix</h3> + +<p> +The <code>go</code> <code>fix</code> tool now replaces imports of <code>"golang.org/x/net/context"</code> +with <code>"context"</code>. +(Forwarding aliases in the former make it completely equivalent to the latter when using Go 1.9 or later.) +</p> + +<h3 id="get">Get</h3> + +<p> +The <code>go</code> <code>get</code> command now supports Fossil source code repositories. +</p> + +<h3 id="pprof">Pprof</h3> + +<p> +The blocking and mutex profiles produced by the <code>runtime/pprof</code> package +now include symbol information, so they can be viewed +in <code>go</code> <code>tool</code> <code>pprof</code> +without the binary that produced the profile. +(All other profile types were changed to include symbol information in Go 1.9.) +</p> + +<p> +The <a href="/cmd/pprof/"><code>go</code> <code>tool</code> <code>pprof</code></a> +profile visualizer has been updated to git version 9e20b5b (2017-11-08) +from <a href="https://github.com/google/pprof">github.com/google/pprof</a>, +which includes an updated web interface. +</p> + +<h3 id="vet">Vet</h3> + +<p> +The <a href="/cmd/vet/"><code>go</code> <code>vet</code></a> command now always has access to +complete, up-to-date type information when checking packages, even for packages using cgo or vendored imports. +The reports should be more accurate as a result. +Note that only <code>go</code> <code>vet</code> has access to this information; +the more low-level <code>go</code> <code>tool</code> <code>vet</code> does not +and should be avoided except when working on <code>vet</code> itself. +(As of Go 1.9, <code>go</code> <code>vet</code> provides access to all the same flags as +<code>go</code> <code>tool</code> <code>vet</code>.) +</p> + +<h3 id="diag">Diagnostics</h3> + +<p> +This release includes a new <a href="/doc/diagnostics.html">overview of available Go program diagnostic tools</a>. +</p> + +<h3 id="gofmt">Gofmt</h3> + +<p> +Two minor details of the default formatting of Go source code have changed. +First, certain complex three-index slice expressions previously formatted like +<code>x[i+1</code> <code>:</code> <code>j:k]</code> and now +format with more consistent spacing: <code>x[i+1</code> <code>:</code> <code>j</code> <code>:</code> <code>k]</code>. +Second, single-method interface literals written on a single line, +which are sometimes used in type assertions, +are no longer split onto multiple lines. +</p> + +<p> +Note that these kinds of minor updates to gofmt are expected from time to time. +In general, we recommend against building systems that check that source code +matches the output of a specific version of gofmt. +For example, a continuous integration test that fails if any code already checked into +a repository is not “properly formatted” is inherently fragile and not recommended. +</p> + +<p> +If multiple programs must agree about which version of gofmt is used to format a source file, +we recommend that they do this by arranging to invoke the same gofmt binary. +For example, in the Go open source repository, our Git pre-commit hook is written in Go +and could import <code>go/format</code> directly, but instead it invokes the <code>gofmt</code> +binary found in the current path, so that the pre-commit hook need not be recompiled +each time <code>gofmt</code> changes. +</p> + +<h3 id="compiler">Compiler Toolchain</h3> + +<p> +The compiler includes many improvements to the performance of generated code, +spread fairly evenly across the supported architectures. +</p> + +<p> +The DWARF debug information recorded in binaries has been improved in a few ways: +constant values are now recorded; +line number information is more accurate, making source-level stepping through a program work better; +and each package is now presented as its own DWARF compilation unit. +</p> + +<p> +The various <a href="https://docs.google.com/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit">build modes</a> +have been ported to more systems. +Specifically, <code>c-shared</code> now works on <code>linux/ppc64le</code>, <code>windows/386</code>, and <code>windows/amd64</code>; +<code>pie</code> now works on <code>darwin/amd64</code> and also forces the use of external linking on all systems; +and <code>plugin</code> now works on <code>linux/ppc64le</code> and <code>darwin/amd64</code>. +</p> + +<p> +The <code>linux/ppc64le</code> port now requires the use of external linking +with any programs that use cgo, even uses by the standard library. +</p> + +<h3 id="asm">Assembler</h3> + +<p> +For the ARM 32-bit port, the assembler now supports the instructions +<code><small>BFC</small></code>, +<code><small>BFI</small></code>, +<code><small>BFX</small></code>, +<code><small>BFXU</small></code>, +<code><small>FMULAD</small></code>, +<code><small>FMULAF</small></code>, +<code><small>FMULSD</small></code>, +<code><small>FMULSF</small></code>, +<code><small>FNMULAD</small></code>, +<code><small>FNMULAF</small></code>, +<code><small>FNMULSD</small></code>, +<code><small>FNMULSF</small></code>, +<code><small>MULAD</small></code>, +<code><small>MULAF</small></code>, +<code><small>MULSD</small></code>, +<code><small>MULSF</small></code>, +<code><small>NMULAD</small></code>, +<code><small>NMULAF</small></code>, +<code><small>NMULD</small></code>, +<code><small>NMULF</small></code>, +<code><small>NMULSD</small></code>, +<code><small>NMULSF</small></code>, +<code><small>XTAB</small></code>, +<code><small>XTABU</small></code>, +<code><small>XTAH</small></code>, +and +<code><small>XTAHU</small></code>. +</p> + +<p> +For the ARM 64-bit port, the assembler now supports the +<code><small>VADD</small></code>, +<code><small>VADDP</small></code>, +<code><small>VADDV</small></code>, +<code><small>VAND</small></code>, +<code><small>VCMEQ</small></code>, +<code><small>VDUP</small></code>, +<code><small>VEOR</small></code>, +<code><small>VLD1</small></code>, +<code><small>VMOV</small></code>, +<code><small>VMOVI</small></code>, +<code><small>VMOVS</small></code>, +<code><small>VORR</small></code>, +<code><small>VREV32</small></code>, +and +<code><small>VST1</small></code> +instructions. +</p> + +<p> +For the PowerPC 64-bit port, the assembler now supports the POWER9 instructions +<code><small>ADDEX</small></code>, +<code><small>CMPEQB</small></code>, +<code><small>COPY</small></code>, +<code><small>DARN</small></code>, +<code><small>LDMX</small></code>, +<code><small>MADDHD</small></code>, +<code><small>MADDHDU</small></code>, +<code><small>MADDLD</small></code>, +<code><small>MFVSRLD</small></code>, +<code><small>MTVSRDD</small></code>, +<code><small>MTVSRWS</small></code>, +<code><small>PASTECC</small></code>, +<code><small>VCMPNEZB</small></code>, +<code><small>VCMPNEZBCC</small></code>, +and +<code><small>VMSUMUDM</small></code>. +</p> + +<p> +For the S390X port, the assembler now supports the +<code><small>TMHH</small></code>, +<code><small>TMHL</small></code>, +<code><small>TMLH</small></code>, +and +<code><small>TMLL</small></code> +instructions. +</p> + +<p> +For the X86 64-bit port, the assembler now supports 359 new instructions, +including the full AVX, AVX2, BMI, BMI2, F16C, FMA3, SSE2, SSE3, SSSE3, SSE4.1, and SSE4.2 extension sets. +The assembler also no longer implements <code><small>MOVL</small></code> <code><small>$0,</small></code> <code><small>AX</small></code> +as an <code><small>XORL</small></code> instruction, +to avoid clearing the condition flags unexpectedly. +</p> + +<h3 id="gccgo">Gccgo</h3> + +<p> +Due to the alignment of Go's semiannual release schedule with GCC's +annual release schedule, +GCC release 7 contains the Go 1.8.3 version of gccgo. +We expect that the next release, GCC 8, will contain the Go 1.10 +version of gccgo. +</p> + +<h2 id="runtime">Runtime</h2> + +<p> +The behavior of nested calls to +<a href="/pkg/runtime/#LockOSThread"><code>LockOSThread</code></a> and +<a href="/pkg/runtime/#UnlockOSThread"><code>UnlockOSThread</code></a> +has changed. +These functions control whether a goroutine is locked to a specific operating system thread, +so that the goroutine only runs on that thread, and the thread only runs that goroutine. +Previously, calling <code>LockOSThread</code> more than once in a row +was equivalent to calling it once, and a single <code>UnlockOSThread</code> +always unlocked the thread. +Now, the calls nest: if <code>LockOSThread</code> is called multiple times, +<code>UnlockOSThread</code> must be called the same number of times +in order to unlock the thread. +Existing code that was careful not to nest these calls will remain correct. +Existing code that incorrectly assumed the calls nested will become correct. +Most uses of these functions in public Go source code falls into the second category. +</p> + +<p> +Because one common use of <code>LockOSThread</code> and <code>UnlockOSThread</code> +is to allow Go code to reliably modify thread-local state (for example, Linux or Plan 9 name spaces), +the runtime now treats locked threads as unsuitable for reuse or for creating new threads. +</p> + +<p> +Stack traces no longer include implicit wrapper functions (previously marked <code><autogenerated></code>), +unless a fault or panic happens in the wrapper itself. +As a result, skip counts passed to functions like <a href="/pkg/runtime/#Caller"><code>Caller</code></a> +should now always match the structure of the code as written, rather than depending on +optimization decisions and implementation details. +</p> + +<p> +The garbage collector has been modified to reduce its impact on allocation latency. +It now uses a smaller fraction of the overall CPU when running, but it may run more of the time. +The total CPU consumed by the garbage collector has not changed significantly. +</p> + +<p> +The <a href="/pkg/runtime/#GOROOT"><code>GOROOT</code></a> function +now defaults (when the <code>$GOROOT</code> environment variable is not set) +to the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect +at the time the calling program was compiled. +Previously it used the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect +at the time the toolchain that compiled the calling program was compiled. +</p> + +<p> +There is no longer a limit on the <a href="/pkg/runtime/#GOMAXPROCS"><code>GOMAXPROCS</code></a> setting. +(In Go 1.9 the limit was 1024.) +</p> + +<h2 id="performance">Performance</h2> + +<p> +As always, the changes are so general and varied that precise +statements about performance are difficult to make. Most programs +should run a bit faster, due to speedups in the garbage collector, +better generated code, and optimizations in the core library. +</p> + +<h2 id="gc">Garbage Collector</h2> + +<p> +Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active. +</p> + +<h2 id="library">Core library</h2> + +<p> +All of the changes to the standard library are minor. +The changes in <a href="#bytes">bytes</a> +and <a href="#net/url">net/url</a> are the most likely to require updating of existing programs. +</p> + +<h3 id="minor_library_changes">Minor changes to the library</h3> + +<p> +As always, there are various minor changes and updates to the library, +made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a> +in mind. +</p> + +<dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt> +<dd> +<p> +In general, the handling of special header formats is significantly improved and expanded. +</p> +<p> +<a href="/pkg/archive/tar/#FileInfoHeader"><code>FileInfoHeader</code></a> has always +recorded the Unix UID and GID numbers from its <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> argument +(specifically, from the system-dependent information returned by the <code>FileInfo</code>'s <code>Sys</code> method) +in the returned <a href="/pkg/archive/tar/#Header"><code>Header</code></a>. +Now it also records the user and group names corresponding to those IDs, +as well as the major and minor device numbers for device files. +</p> +<p> +The new <a href="/pkg/archive/tar/#Header"><code>Header.Format</code></a> field +of type <a href="/pkg/archive/tar/#Format"><code>Format</code></a> +controls which tar header format the <a href="/pkg/archive/tar/#Writer"><code>Writer</code></a> uses. +The default, as before, is to select the most widely-supported header type +that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU). +The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads. +</p> +<p> +<code>Reader</code> and the <code>Writer</code> now support arbitrary PAX records, +using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field, +a generalization of the existing <code>Xattrs</code> field. +</p> +<p> +The <code>Reader</code> no longer insists that the file name or link name in GNU headers +be valid UTF-8. +</p> +<p> +When writing PAX- or GNU-format headers, the <code>Writer</code> now includes +the <code>Header.AccessTime</code> and <code>Header.ChangeTime</code> fields (if set). +When writing PAX-format headers, the times include sub-second precision. +</p> +</dl> + +<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt> +<dd> +<p> +Go 1.10 adds more complete support for times and character set encodings in ZIP archives. +</p> +<p> +The original ZIP format used the standard MS-DOS encoding of year, month, day, hour, minute, and second into fields in two 16-bit values. +That encoding cannot represent time zones or odd seconds, so multiple extensions have been +introduced to allow richer encodings. +In Go 1.10, the <a href="/pkg/archive/zip/#Reader"><code>Reader</code></a> and <a href="/pkg/archive/zip/#Writer"><code>Writer</code></a> +now support the widely-understood Info-Zip extension that encodes the time separately in the 32-bit Unix “seconds since epoch” form. +The <a href="/pkg/archive/zip/#FileHeader"><code>FileHeader</code></a>'s new <code>Modified</code> field of type <a href="/pkg/time/#Time"><code>time.Time</code></a> +obsoletes the <code>ModifiedTime</code> and <code>ModifiedDate</code> fields, which continue to hold the MS-DOS encoding. +The <code>Reader</code> and <code>Writer</code> now adopt the common +convention that a ZIP archive storing a time zone-independent Unix time +also stores the local time in the MS-DOS field, +so that the time zone offset can be inferred. +For compatibility, the <a href="/pkg/archive/zip/#FileHeader.ModTime"><code>ModTime</code></a> and +<a href="/pkg/archive/zip/#FileHeader.SetModTime"><code>SetModTime</code></a> methods +behave the same as in earlier releases; new code should use <code>Modified</code> directly. +</p> +<p> +The header for each file in a ZIP archive has a flag bit indicating whether +the name and comment fields are encoded as UTF-8, as opposed to a system-specific default encoding. +In Go 1.8 and earlier, the <code>Writer</code> never set the UTF-8 bit. +In Go 1.9, the <code>Writer</code> changed to set the UTF-8 bit almost always. +This broke the creation of ZIP archives containing Shift-JIS file names. +In Go 1.10, the <code>Writer</code> now sets the UTF-8 bit only when +both the name and the comment field are valid UTF-8 and at least one is non-ASCII. +Because non-ASCII encodings very rarely look like valid UTF-8, the new +heuristic should be correct nearly all the time. +Setting a <code>FileHeader</code>'s new <code>NonUTF8</code> field to true +disables the heuristic entirely for that file. +</p> +<p> +The <code>Writer</code> also now supports setting the end-of-central-directory record's comment field, +by calling the <code>Writer</code>'s new <a href="/pkg/archive/zip/#Writer.SetComment"><code>SetComment</code></a> method. +</p> +</dl> + +<dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt> +<dd> +<p> +The new <a href="/pkg/bufio/#Reader.Size"><code>Reader.Size</code></a> +and <a href="/pkg/bufio/#Writer.Size"><code>Writer.Size</code></a> +methods report the <code>Reader</code> or <code>Writer</code>'s underlying buffer size. +</p> +</dl> + +<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt> +<dd> +<p> +The +<a href="/pkg/bytes/#Fields"><code>Fields</code></a>, +<a href="/pkg/bytes/#FieldsFunc"><code>FieldsFunc</code></a>, +<a href="/pkg/bytes/#Split"><code>Split</code></a>, +and +<a href="/pkg/bytes/#SplitAfter"><code>SplitAfter</code></a> +functions have always returned subslices of their inputs. +Go 1.10 changes each returned subslice to have capacity equal to its length, +so that appending to one cannot overwrite adjacent data in the original input. +</p> +</dl> + +<dl id="crypto/cipher"><dt><a href="/pkg/crypto/cipher/">crypto/cipher</a></dt> +<dd> +<p> +<a href="/pkg/crypto/cipher/#NewOFB"><code>NewOFB</code></a> now panics if given +an initialization vector of incorrect length, like the other constructors in the +package always have. +(Previously it returned a nil <code>Stream</code> implementation.) +</p> +</dl> + +<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt> +<dd> +<p> +The TLS server now advertises support for SHA-512 signatures when using TLS 1.2. +The server already supported the signatures, but some clients would not select +them unless explicitly advertised. +</p> +</dl> + +<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt> +<dd> +<p> +<a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a> +now enforces the name constraints for all +names contained in the certificate, not just the one name that a client has asked about. +Extended key usage restrictions are similarly now checked all at once. +As a result, after a certificate has been validated, now it can be trusted in its entirety. +It is no longer necessary to revalidate the certificate for each additional name +or key usage. +</p> + +<p> +Parsed certificates also now report URI names and IP, email, and URI constraints, using the new +<a href="/pkg/crypto/x509/#Certificate"><code>Certificate</code></a> fields +<code>URIs</code>, <code>PermittedIPRanges</code>, <code>ExcludedIPRanges</code>, +<code>PermittedEmailAddresses</code>, <code>ExcludedEmailAddresses</code>, +<code>PermittedURIDomains</code>, and <code>ExcludedURIDomains</code>. Certificates with +invalid values for those fields are now rejected. +</p> + +<p> +The new <a href="/pkg/crypto/x509/#MarshalPKCS1PublicKey"><code>MarshalPKCS1PublicKey</code></a> +and <a href="/pkg/crypto/x509/#ParsePKCS1PublicKey"><code>ParsePKCS1PublicKey</code></a> +functions convert an RSA public key to and from PKCS#1-encoded form. +</p> + +<p> +The new <a href="/pkg/crypto/x509/#MarshalPKCS8PrivateKey"><code>MarshalPKCS8PrivateKey</code></a> +function converts a private key to PKCS#8-encoded form. +(<a href="/pkg/crypto/x509/#ParsePKCS8PrivateKey"><code>ParsePKCS8PrivateKey</code></a> +has existed since Go 1.) +</p> +</dl> + +<dl id="crypto/x509/pkix"><dt><a href="/pkg/crypto/x509/pkix/">crypto/x509/pkix</a></dt> +<dd> +<p> +<a href="/pkg/crypto/x509/pkix/#Name"><code>Name</code></a> now implements a +<a href="/pkg/crypto/x509/pkix/#Name.String"><code>String</code></a> method that +formats the X.509 distinguished name in the standard RFC 2253 format. +</p> +</dl> + +<dl id="database/sql/driver"><dt><a href="/pkg/database/sql/driver/">database/sql/driver</a></dt> +<dd> +<p> +Drivers that currently hold on to the destination buffer provided by +<a href="/pkg/database/sql/driver/#Rows.Next"><code>driver.Rows.Next</code></a> should ensure they no longer +write to a buffer assigned to the destination array outside of that call. +Drivers must be careful that underlying buffers are not modified when closing +<a href="/pkg/database/sql/driver/#Rows"><code>driver.Rows</code></a>. +</p> +<p> +Drivers that want to construct a <a href="/pkg/database/sql/#DB"><code>sql.DB</code></a> for +their clients can now implement the <a href="/pkg/database/sql/driver/#Connector"><code>Connector</code></a> interface +and call the new <a href="/pkg/database/sql/#OpenDB"><code>sql.OpenDB</code></a> function, +instead of needing to encode all configuration into a string +passed to <a href="/pkg/database/sql/#Open"><code>sql.Open</code></a>. +</p> +<p> +Drivers that want to parse the configuration string only once per <code>sql.DB</code> +instead of once per <a href="/pkg/database/sql/#Conn"><code>sql.Conn</code></a>, +or that want access to each <code>sql.Conn</code>'s underlying context, +can make their <a href="/pkg/database/sql/driver/#Driver"><code>Driver</code></a> +implementations also implement <a href="/pkg/database/sql/driver/#DriverContext"><code>DriverContext</code></a>'s +new <code>OpenConnector</code> method. +</p> +<p> +Drivers that implement <a href="/pkg/database/sql/driver/#ExecerContext"><code>ExecerContext</code></a> +no longer need to implement <a href="/pkg/database/sql/driver/#Execer"><code>Execer</code></a>; +similarly, drivers that implement <a href="/pkg/database/sql/driver/#QueryerContext"><code>QueryerContext</code></a> +no longer need to implement <a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>. +Previously, even if the context-based interfaces were implemented they were ignored +unless the non-context-based interfaces were also implemented. +</p> +<p> +To allow drivers to better isolate different clients using a cached driver connection in succession, +if a <a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a> implements the new +<a href="/pkg/database/sql/driver/#SessionResetter"><code>SessionResetter</code></a> interface, +<code>database/sql</code> will now call <code>ResetSession</code> before +reusing the <code>Conn</code> for a new client. +</p> +</dl> + +<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt> +<dd> +<p> +This release adds 348 new relocation constants divided between the relocation types +<a href="/pkg/debug/elf/#R_386"><code>R_386</code></a>, +<a href="/pkg/debug/elf/#R_AARCH64"><code>R_AARCH64</code></a>, +<a href="/pkg/debug/elf/#R_ARM"><code>R_ARM</code></a>, +<a href="/pkg/debug/elf/#R_PPC64"><code>R_PPC64</code></a>, +and +<a href="/pkg/debug/elf/#R_X86_64"><code>R_X86_64</code></a>. +</p> +</dl> + +<dl id="debug/macho"><dt><a href="/pkg/debug/macho/">debug/macho</a></dt> +<dd> +<p> +Go 1.10 adds support for reading relocations from Mach-O sections, +using the <a href="/pkg/debug/macho#Section"><code>Section</code></a> struct's new <code>Relocs</code> field +and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>, +<a href="/pkg/debug/macho/#RelocTypeARM"><code>RelocTypeARM</code></a>, +<a href="/pkg/debug/macho/#RelocTypeARM64"><code>RelocTypeARM64</code></a>, +<a href="/pkg/debug/macho/#RelocTypeGeneric"><code>RelocTypeGeneric</code></a>, +and +<a href="/pkg/debug/macho/#RelocTypeX86_64"><code>RelocTypeX86_64</code></a> +types and associated constants. +</p> +<p> +Go 1.10 also adds support for the <code>LC_RPATH</code> load command, +represented by the types +<a href="/pkg/debug/macho/#RpathCmd"><code>RpathCmd</code></a> and +<a href="/pkg/debug/macho/#Rpath"><code>Rpath</code></a>, +and new <a href="/pkg/debug/macho/#pkg-constants">named constants</a> +for the various flag bits found in headers. +</p> +</dl> + +<dl id="encoding/asn1"><dt><a href="/pkg/encoding/asn1/">encoding/asn1</a></dt> +<dd> +<p> +<a href="/pkg/encoding/asn1/#Marshal"><code>Marshal</code></a> now correctly encodes +strings containing asterisks as type UTF8String instead of PrintableString, +unless the string is in a struct field with a tag forcing the use of PrintableString. +<code>Marshal</code> also now respects struct tags containing <code>application</code> directives. +</p> +<p> +The new <a href="/pkg/encoding/asn1/#MarshalWithParams"><code>MarshalWithParams</code></a> +function marshals its argument as if the additional params were its associated +struct field tag. +</p> +<p> +<a href="/pkg/encoding/asn1/#Unmarshal"><code>Unmarshal</code></a> now respects +struct field tags using the <code>explicit</code> and <code>tag</code> +directives. +</p> +<p> +Both <code>Marshal</code> and <code>Unmarshal</code> now support a new struct field tag +<code>numeric</code>, indicating an ASN.1 NumericString. +</p> +</dl> + +<dl id="encoding/csv"><dt><a href="/pkg/encoding/csv/">encoding/csv</a></dt> +<dd> +<p> +<a href="/pkg/encoding/csv/#Reader"><code>Reader</code></a> now disallows the use of +nonsensical <code>Comma</code> and <code>Comment</code> settings, +such as NUL, carriage return, newline, invalid runes, and the Unicode replacement character, +or setting <code>Comma</code> and <code>Comment</code> equal to each other. +</p> +<p> +In the case of a syntax error in a CSV record that spans multiple input lines, <code>Reader</code> +now reports the line on which the record started in the <a href="/pkg/encoding/csv/#ParseError"><code>ParseError</code></a>'s new <code>StartLine</code> field. +</p> +</dl> + +<dl id="encoding/hex"><dt><a href="/pkg/encoding/hex/">encoding/hex</a></dt> +<dd> +<p> +The new functions +<a href="/pkg/encoding/hex/#NewEncoder"><code>NewEncoder</code></a> +and +<a href="/pkg/encoding/hex/#NewDecoder"><code>NewDecoder</code></a> +provide streaming conversions to and from hexadecimal, +analogous to equivalent functions already in +<a href="/pkg/encoding/base32/">encoding/base32</a> +and +<a href="/pkg/encoding/base64/">encoding/base64</a>. +</p> + +<p> +When the functions +<a href="/pkg/encoding/hex/#Decode"><code>Decode</code></a> +and +<a href="/pkg/encoding/hex/#DecodeString"><code>DecodeString</code></a> +encounter malformed input, +they now return the number of bytes already converted +along with the error. +Previously they always returned a count of 0 with any error. +</p> +</dl> + +<dl id="encoding/json"><dt><a href="/pkg/encoding/json/">encoding/json</a></dt> +<dd> +<p> +The <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a> +adds a new method +<a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a> +that causes it to report inputs with unknown JSON fields as a decoding error. +(The default behavior has always been to discard unknown fields.) +</p> + +<p> +As a result of <a href="#reflect">fixing a reflect bug</a>, +<a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a> +can no longer decode into fields inside +embedded pointers to unexported struct types, +because it cannot initialize the unexported embedded pointer +to point at fresh storage. +<code>Unmarshal</code> now returns an error in this case. +</p> +</dl> + +<dl id="encoding/pem"><dt><a href="/pkg/encoding/pem/">encoding/pem</a></dt> +<dd> +<p> +<a href="/pkg/encoding/pem/#Encode"><code>Encode</code></a> +and +<a href="/pkg/encoding/pem/#EncodeToMemory"><code>EncodeToMemory</code></a> +no longer generate partial output when presented with a +block that is impossible to encode as PEM data. +</p> +</dl> + +<dl id="encoding/xml"><dt><a href="/pkg/encoding/xml/">encoding/xml</a></dt> +<dd> +<p> +The new function +<a href="/pkg/encoding/xml/#NewTokenDecoder"><code>NewTokenDecoder</code></a> +is like +<a href="/pkg/encoding/xml/#NewDecoder"><code>NewDecoder</code></a> +but creates a decoder reading from a <a href="/pkg/encoding/xml/#TokenReader"><code>TokenReader</code></a> +instead of an XML-formatted byte stream. +This is meant to enable the construction of XML stream transformers in client libraries. +</p> +</dl> + +<dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt> +<dd> +<p> +The default +<a href="/pkg/flag/#Usage"><code>Usage</code></a> function now prints +its first line of output to +<code>CommandLine.Output()</code> +instead of assuming <code>os.Stderr</code>, +so that the usage message is properly redirected for +clients using <code>CommandLine.SetOutput</code>. +</p> +<p> +<a href="/pkg/flag/#PrintDefaults"><code>PrintDefaults</code></a> now +adds appropriate indentation after newlines in flag usage strings, +so that multi-line usage strings display nicely. +</p> +<p> +<a href="/pkg/flag/#FlagSet"><code>FlagSet</code></a> adds new methods +<a href="/pkg/flag/#FlagSet.ErrorHandling"><code>ErrorHandling</code></a>, +<a href="/pkg/flag/#FlagSet.Name"><code>Name</code></a>, +and +<a href="/pkg/flag/#FlagSet.Output"><code>Output</code></a>, +to retrieve the settings passed to +<a href="/pkg/flag/#NewFlagSet"><code>NewFlagSet</code></a> +and +<a href="/pkg/flag/#FlagSet.SetOutput"><code>FlagSet.SetOutput</code></a>. +</p> +</dl> + +<dl id="go/doc"><dt><a href="/pkg/go/doc/">go/doc</a></dt> +<dd> +<p> +To support the <a href="#doc">doc change</a> described above, +functions returning slices of <code>T</code>, <code>*T</code>, <code>**T</code>, and so on +are now reported in <code>T</code>'s <a href="/pkg/go/doc/#Type"><code>Type</code></a>'s <code>Funcs</code> list, +instead of in the <a href="/pkg/go/doc/#Package"><code>Package</code></a>'s <code>Funcs</code> list. +</p> +</dl> + +<dl id="go/importer"><dt><a href="/pkg/go/importer/">go/importer</a></dt> +<dd> +<p> +The <a href="/pkg/go/importer/#For"><code>For</code></a> function now accepts a non-nil lookup argument. +</p> +</dl> + +<dl id="go/printer"><dt><a href="/pkg/go/printer/">go/printer</a></dt> +<dd> +<p> +The changes to the default formatting of Go source code +discussed in the <a href="#gofmt">gofmt section</a> above +are implemented in the <a href="/pkg/go/printer/">go/printer</a> package +and also affect the output of the higher-level <a href="/pkg/go/format/">go/format</a> package. +</p> +</dl> + +<dl id="hash"><dt><a href="/pkg/hash/">hash</a></dt> +<dd> +<p> +Implementations of the <a href="/pkg/hash/#Hash"><code>Hash</code></a> interface are now +encouraged to implement <a href="/pkg/encoding/#BinaryMarshaler"><code>encoding.BinaryMarshaler</code></a> +and <a href="/pkg/encoding/#BinaryUnmarshaler"><code>encoding.BinaryUnmarshaler</code></a> +to allow saving and recreating their internal state, +and all implementations in the standard library +(<a href="/pkg/hash/crc32/">hash/crc32</a>, <a href="/pkg/crypto/sha256/">crypto/sha256</a>, and so on) +now implement those interfaces. +</p> +</dl> + +<dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt> +<dd> +<p> +The new <a href="/pkg/html/template#Srcset"><code>Srcset</code></a> content +type allows for proper handling of values within the +<a href="https://w3c.github.io/html/semantics-embedded-content.html#element-attrdef-img-srcset"><code>srcset</code></a> +attribute of <code>img</code> tags. +</p> +</dl> + +<dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt> +<dd> +<p> +<a href="/pkg/math/big/#Int"><code>Int</code></a> now supports conversions to and from bases 2 through 62 +in its <a href="/pkg/math/big/#Int.SetString"><code>SetString</code></a> and <a href="/pkg/math/big/#Text"><code>Text</code></a> methods. +(Previously it only allowed bases 2 through 36.) +The value of the constant <code>MaxBase</code> has been updated. +</p> +<p> +<a href="/pkg/math/big/#Int"><code>Int</code></a> adds a new +<a href="/pkg/math/big/#CmpAbs"><code>CmpAbs</code></a> method +that is like <a href="/pkg/math/big/#Cmp"><code>Cmp</code></a> but +compares only the absolute values (not the signs) of its arguments. +</p> +<p> +<a href="/pkg/math/big/#Float"><code>Float</code></a> adds a new +<a href="/pkg/math/big/#Float.Sqrt"><code>Sqrt</code></a> method to +compute square roots. +</p> +</dl> + +<dl id="math/cmplx"><dt><a href="/pkg/math/cmplx/">math/cmplx</a></dt> +<dd> +<p> +Branch cuts and other boundary cases in +<a href="/pkg/math/cmplx/#Asin"><code>Asin</code></a>, +<a href="/pkg/math/cmplx/#Asinh"><code>Asinh</code></a>, +<a href="/pkg/math/cmplx/#Atan"><code>Atan</code></a>, +and +<a href="/pkg/math/cmplx/#Sqrt"><code>Sqrt</code></a> +have been corrected to match the definitions used in the C99 standard. +</p> +</dl> + +<dl id="math/rand"><dt><a href="/pkg/math/rand/">math/rand</a></dt> +<dd> +<p> +The new <a href="/pkg/math/rand/#Shuffle"><code>Shuffle</code></a> function and corresponding +<a href="/pkg/math/rand/#Rand.Shuffle"><code>Rand.Shuffle</code></a> method +shuffle an input sequence. +</p> +</dl> + +<dl id="math"><dt><a href="/pkg/math/">math</a></dt> +<dd> +<p> +The new functions +<a href="/pkg/math/#Round"><code>Round</code></a> +and +<a href="/pkg/math/#RoundToEven"><code>RoundToEven</code></a> +round their arguments to the nearest floating-point integer; +<code>Round</code> rounds a half-integer to its larger integer neighbor (away from zero) +while <code>RoundToEven</code> rounds a half-integer to its even integer neighbor. +</p> + +<p> +The new functions +<a href="/pkg/math/#Erfinv"><code>Erfinv</code></a> +and +<a href="/pkg/math/#Erfcinv"><code>Erfcinv</code></a> +compute the inverse error function and the +inverse complementary error function. +</p> +</dl> + +<dl id="mime/multipart"><dt><a href="/pkg/mime/multipart/">mime/multipart</a></dt> +<dd> +<p> +<a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> +now accepts parts with empty filename attributes. +</p> +</dl> + +<dl id="mime"><dt><a href="/pkg/mime/">mime</a></dt> +<dd> +<p> +<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a> now discards +invalid attribute values; previously it returned those values as empty strings. +</p> +</dl> + +<dl id="net"><dt><a href="/pkg/net/">net</a></dt> +<dd> +<p> +The <a href="/pkg/net/#Conn"><code>Conn</code></a> and +<a href="/pkg/net/#Conn"><code>Listener</code></a> implementations +in this package now guarantee that when <code>Close</code> returns, +the underlying file descriptor has been closed. +(In earlier releases, if the <code>Close</code> stopped pending I/O +in other goroutines, the closing of the file descriptor could happen in one of those +goroutines shortly after <code>Close</code> returned.) +</p> + +<p> +<a href="/pkg/net/#TCPListener"><code>TCPListener</code></a> and +<a href="/pkg/net/#UnixListener"><code>UnixListener</code></a> +now implement +<a href="/pkg/syscall/#Conn"><code>syscall.Conn</code></a>, +to allow setting options on the underlying file descriptor +using <a href="/pkg/syscall/#RawConn"><code>syscall.RawConn.Control</code></a>. +</p> + +<p> +The <code>Conn</code> implementations returned by <a href="/pkg/net/#Pipe"><code>Pipe</code></a> +now support setting read and write deadlines. +</p> + +<p> +The <a href="/pkg/net/#IPConn.ReadMsgIP"><code>IPConn.ReadMsgIP</code></a>, +<a href="/pkg/net/#IPConn.WriteMsgIP"><code>IPConn.WriteMsgIP</code></a>, +<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>UDPConn.ReadMsgUDP</code></a>, +and +<a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>UDPConn.WriteMsgUDP</code></a>, +methods are now implemented on Windows. +</p> +</dl> + +<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt> +<dd> +<p> +On the client side, an HTTP proxy (most commonly configured by +<a href="/pkg/net/http/#ProxyFromEnvironment"><code>ProxyFromEnvironment</code></a>) +can now be specified as an <code>https://</code> URL, +meaning that the client connects to the proxy over HTTPS before issuing a standard, proxied HTTP request. +(Previously, HTTP proxy URLs were required to begin with <code>http://</code> or <code>socks5://</code>.) +</p> +<p> +On the server side, <a href="/pkg/net/http/#FileServer"><code>FileServer</code></a> and its single-file equivalent <a href="/pkg/net/http/#ServeFile"><code>ServeFile</code></a> +now apply <code>If-Range</code> checks to <code>HEAD</code> requests. +<code>FileServer</code> also now reports directory read failures to the <a href="/pkg/net/http/#Server"><code>Server</code></a>'s <code>ErrorLog</code>. +The content-serving handlers also now omit the <code>Content-Type</code> header when serving zero-length content. +</p> +<p> +<a href="/pkg/net/http/#ResponseWriter"><code>ResponseWriter</code></a>'s <code>WriteHeader</code> method now panics +if passed an invalid (non-3-digit) status code. +</p> +<p> +<!-- CL 46631 --> +The <code>Server</code> will no longer add an implicit Content-Type when a <code>Handler</code> does not write any output. +</p> +<p> +<a href="/pkg/net/http/#Redirect"><code>Redirect</code></a> now sets the <code>Content-Type</code> header before writing its HTTP response. +</p> +</dl> + +<dl id="net/mail"><dt><a href="/pkg/net/mail/">net/mail</a></dt> +<dd> +<p> +<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and +<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a> +now support a variety of obsolete address formats. +</p> +</dl> + +<dl id="net/smtp"><dt><a href="/pkg/net/smtp/">net/smtp</a></dt> +<dd> +<p> +The <a href="/pkg/net/smtp/#Client"><code>Client</code></a> adds a new +<a href="/pkg/net/smtp/#Client.Noop"><code>Noop</code></a> method, +to test whether the server is still responding. +It also now defends against possible SMTP injection in the inputs +to the <a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a> +and <a href="/pkg/net/smtp/#Client.Verify"><code>Verify</code></a> methods. +</p> +</dl> + +<dl id="net/textproto"><dt><a href="/pkg/net/textproto/">net/textproto</a></dt> +<dd> +<p> +<a href="/pkg/net/textproto/#ReadMIMEHeader"><code>ReadMIMEHeader</code></a> +now rejects any header that begins with a continuation (indented) header line. +Previously a header with an indented first line was treated as if the first line +were not indented. +</p> +</dl> + +<dl id="net/url"><dt><a href="/pkg/net/url/">net/url</a></dt> +<dd> +<p> +<a href="/pkg/net/url/#ResolveReference"><code>ResolveReference</code></a> +now preserves multiple leading slashes in the target URL. +Previously it rewrote multiple leading slashes to a single slash, +which resulted in the <a href="/pkg/net/http/#Client"><code>http.Client</code></a> +following certain redirects incorrectly. +</p> +<p> +For example, this code's output has changed: +</p> +<pre> +base, _ := url.Parse("http://host//path//to/page1") +target, _ := url.Parse("page2") +fmt.Println(base.ResolveReference(target)) +</pre> +<p> +Note the doubled slashes around <code>path</code>. +In Go 1.9 and earlier, the resolved URL was <code>http://host/path//to/page2</code>: +the doubled slash before <code>path</code> was incorrectly rewritten +to a single slash, while the doubled slash after <code>path</code> was +correctly preserved. +Go 1.10 preserves both doubled slashes, resolving to <code>http://host//path//to/page2</code> +as required by <a href="https://tools.ietf.org/html/rfc3986#section-5.2">RFC 3986</a>. +</p> + +<p>This change may break existing buggy programs that unintentionally +construct a base URL with a leading doubled slash in the path and inadvertently +depend on <code>ResolveReference</code> to correct that mistake. +For example, this can happen if code adds a host prefix +like <code>http://host/</code> to a path like <code>/my/api</code>, +resulting in a URL with a doubled slash: <code>http://host//my/api</code>. +</p> + +<p> +<a href="/pkg/net/url/#UserInfo"><code>UserInfo</code></a>'s methods +now treat a nil receiver as equivalent to a pointer to a zero <code>UserInfo</code>. +Previously, they panicked. +</p> +</dl> + +<dl id="os"><dt><a href="/pkg/os/">os</a></dt> +<dd> +<p> +<a href="/pkg/os/#File"><code>File</code></a> adds new methods +<a href="/pkg/os/#File.SetDeadline"><code>SetDeadline</code></a>, +<a href="/pkg/os/#File.SetReadDeadline"><code>SetReadDeadline</code></a>, +and +<a href="/pkg/os/#File.SetWriteDeadline"><code>SetWriteDeadline</code></a> +that allow setting I/O deadlines when the +underlying file descriptor supports non-blocking I/O operations. +The definition of these methods matches those in <a href="/pkg/net/#Conn"><code>net.Conn</code></a>. +If an I/O method fails due to missing a deadline, it will return a +timeout error; the +new <a href="/pkg/os/#IsTimeout"><code>IsTimeout</code></a> function +reports whether an error represents a timeout. +</p> + +<p> +Also matching <code>net.Conn</code>, +<code>File</code>'s +<a href="/pkg/os/#File.Close"><code>Close</code></a> method +now guarantee that when <code>Close</code> returns, +the underlying file descriptor has been closed. +(In earlier releases, +if the <code>Close</code> stopped pending I/O +in other goroutines, the closing of the file descriptor could happen in one of those +goroutines shortly after <code>Close</code> returned.) +</p> + +<p> +On BSD, macOS, and Solaris systems, +<a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> +now supports setting file times with nanosecond precision +(assuming the underlying file system can represent them). +</p> +</dl> + +<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt> +<dd> +<p> +The <a href="/pkg/reflect/#Copy"><code>Copy</code></a> function now allows copying +from a string into a byte array or byte slice, to match the +<a href="/pkg/builtin/#copy">built-in copy function</a>. +</p> + +<p> +In structs, embedded pointers to unexported struct types were +previously incorrectly reported with an empty <code>PkgPath</code> +in the corresponding <a href="/pkg/reflect/#StructField">StructField</a>, +with the result that for those fields, +and <a href="/pkg/reflect/#Value.CanSet"><code>Value.CanSet</code></a> +incorrectly returned true and +<a href="/pkg/reflect/#Value.Set"><code>Value.Set</code></a> +incorrectly succeeded. +The underlying metadata has been corrected; +for those fields, +<code>CanSet</code> now correctly returns false +and <code>Set</code> now correctly panics. +This may affect reflection-based unmarshalers +that could previously unmarshal into such fields +but no longer can. +For example, see the <a href="#encoding/json"><code>encoding/json</code> notes</a>. +</p> +</dl> + +<dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt> +<dd> +<p> +As <a href="#pprof">noted above</a>, the blocking and mutex profiles +now include symbol information so that they can be viewed without needing +the binary that generated them. +</p> +</dl> + +<dl id="strconv"><dt><a href="/pkg/strconv/">strconv</a></dt> +<dd> +<p> +<a href="/pkg/strconv/#ParseUint"><code>ParseUint</code></a> now returns +the maximum magnitude integer of the appropriate size +with any <code>ErrRange</code> error, as it was already documented to do. +Previously it returned 0 with <code>ErrRange</code> errors. +</p> +</dl> + +<dl id="strings"><dt><a href="/pkg/strings/">strings</a></dt> +<dd> +<p> +A new type +<a href="/pkg/strings/#Builder"><code>Builder</code></a> is a replacement for +<a href="/pkg/bytes/#Buffer"><code>bytes.Buffer</code></a> for the use case of +accumulating text into a <code>string</code> result. +The <code>Builder</code>'s API is a restricted subset of <code>bytes.Buffer</code>'s +that allows it to safely avoid making a duplicate copy of the data +during the <a href="/pkg/strings/#Builder.String"><code>String</code></a> method. +</p> +</dl> + +<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt> +<dd> +<p> +On Windows, +the new <a href="/pkg/syscall/#SysProcAttr"><code>SysProcAttr</code></a> field <code>Token</code>, +of type <a href="/pkg/syscall/#Token"><code>Token</code></a> allows the creation of a process that +runs as another user during <a href="/pkg/syscall/#StartProcess"><code>StartProcess</code></a> +(and therefore also during <a href="/pkg/os/#StartProcess"><code>os.StartProcess</code></a> and +<a href="/pkg/os/exec/#Cmd.Start"><code>exec.Cmd.Start</code></a>). +The new function <a href="/pkg/syscall/#CreateProcessAsUser"><code>CreateProcessAsUser</code></a> +gives access to the underlying system call. +</p> + +<p> +On BSD, macOS, and Solaris systems, <a href="/pkg/syscall/#UtimesNano"><code>UtimesNano</code></a> +is now implemented. +</p> +</dl> + +<dl id="time"><dt><a href="/pkg/time/">time</a></dt> +<dd> +<p> +<a href="/pkg/time/#LoadLocation"><code>LoadLocation</code></a> now uses the directory +or uncompressed zip file named by the <code>$ZONEINFO</code> +environment variable before looking in the default system-specific list of +known installation locations or in <code>$GOROOT/lib/time/zoneinfo.zip</code>. +</p> +<p> +The new function <a href="/pkg/time/#LoadLocationFromTZData"><code>LoadLocationFromTZData</code></a> +allows conversion of IANA time zone file data to a <a href="/pkg/time/#Location"><code>Location</code></a>. +</p> +</dl> + +<dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt> +<dd> +<p> +The <a href="/pkg/unicode/"><code>unicode</code></a> package and associated +support throughout the system has been upgraded from Unicode 9.0 to +<a href="http://www.unicode.org/versions/Unicode10.0.0/">Unicode 10.0</a>, +which adds 8,518 new characters, including four new scripts, one new property, +a Bitcoin currency symbol, and 56 new emoji. +</p> +</dl> |