"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/go1.10.html" (9 Sep 2020, 59272 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "Go 1.10 Release Notes",
    3     "Path":  "/doc/go1.10",
    4     "Template": true
    5 }-->
    6 
    7 <!--
    8 NOTE: In this document and others in this directory, the convention is to
    9 set fixed-width phrases with non-fixed-width spaces, as in
   10 <code>hello</code> <code>world</code>.
   11 Do not send CLs removing the interior tags from such phrases.
   12 -->
   13 
   14 <style>
   15   main ul li { margin: 0.5em 0; }
   16 </style>
   17 
   18 <h2 id="introduction">Introduction to Go 1.10</h2>
   19 
   20 <p>
   21 The latest Go release, version 1.10, arrives six months after <a href="go1.9">Go 1.9</a>.
   22 Most of its changes are in the implementation of the toolchain, runtime, and libraries.
   23 As always, the release maintains the Go 1 <a href="/doc/go1compat.html">promise of compatibility</a>.
   24 We expect almost all Go programs to continue to compile and run as before.
   25 </p>
   26 
   27 <p>
   28 This release improves <a href="#build">caching of built packages</a>,
   29 adds <a href="#test">caching of successful test results</a>,
   30 runs <a href="#test-vet">vet automatically during tests</a>,
   31 and
   32 permits <a href="#cgo">passing string values directly between Go and C using cgo</a>.
   33 A new <a href="#cgo">compiler option whitelist</a> may cause
   34 unexpected <a href="https://golang.org/s/invalidflag"><code>invalid
   35 flag</code></a> errors in code that built successfully with older
   36 releases.
   37 </p>
   38 
   39 <h2 id="language">Changes to the language</h2>
   40 
   41 <p>
   42 There are no significant changes to the language specification.
   43 </p>
   44 
   45 <p><!-- CL 60230 -->
   46 A corner case involving shifts of untyped constants has been clarified,
   47 and as a result the compilers have been updated to allow the index expression
   48 <code>x[1.0</code>&nbsp;<code>&lt;&lt;</code>&nbsp;<code>s]</code> where <code>s</code> is an unsigned integer;
   49 the <a href="/pkg/go/types/">go/types</a> package already did.
   50 </p>
   51 
   52 <p><!-- CL 73233 -->
   53 The grammar for method expressions has been updated to relax the
   54 syntax to allow any type expression as a receiver;
   55 this matches what the compilers were already implementing.
   56 For example, <code>struct{io.Reader}.Read</code> is a valid, if unusual,
   57 method expression that the compilers already accepted and is
   58 now permitted by the language grammar.
   59 </p>
   60 
   61 <h2 id="ports">Ports</h2>
   62 
   63 <p>
   64 There are no new supported operating systems or processor architectures in this release.
   65 Most of the work has focused on strengthening the support for existing ports,
   66 in particular <a href="#asm">new instructions in the assembler</a>
   67 and improvements to the code generated by the compilers.
   68 </p>
   69 
   70 <p id="freebsd">
   71 As <a href="go1.9#freebsd">announced in the Go 1.9 release notes</a>,
   72 Go 1.10 now requires FreeBSD 10.3 or later;
   73 support for FreeBSD 9.3 has been removed.
   74 </p>
   75 
   76 <p id="netbsd">
   77 Go now runs on NetBSD again but requires the unreleased NetBSD 8.
   78 Only <code>GOARCH</code> <code>amd64</code> and <code>386</code> have
   79 been fixed. The <code>arm</code> port is still broken.
   80 </p>
   81 
   82 <p id="mips">
   83 On 32-bit MIPS systems, the new environment variable settings
   84 <code>GOMIPS=hardfloat</code> (the default) and
   85 <code>GOMIPS=softfloat</code> select whether to use
   86 hardware instructions or software emulation for floating-point computations.
   87 </p>
   88 
   89 <p id="openbsd">
   90 Go 1.10 is the last release that will run on OpenBSD 6.0.
   91 Go 1.11 will require OpenBSD 6.2.
   92 </p>
   93 
   94 <p id="darwin">
   95 Go 1.10 is the last release that will run on OS X 10.8 Mountain Lion or OS X 10.9 Mavericks.
   96 Go 1.11 will require OS X 10.10 Yosemite or later.
   97 </p>
   98 
   99 <p id="windows">
  100 Go 1.10 is the last release that will run on Windows XP or Windows Vista.
  101 Go 1.11 will require Windows 7 or later.
  102 </p>
  103 
  104 <h2 id="tools">Tools</h2>
  105 
  106 <h3 id="goroot">Default GOROOT &amp; GOTMPDIR</h3>
  107 
  108 <p>
  109 If the environment variable <code>$GOROOT</code> is unset,
  110 the go tool previously used the default <code>GOROOT</code>
  111 set during toolchain compilation.
  112 Now, before falling back to that default, the go tool attempts to
  113 deduce <code>GOROOT</code> from its own executable path.
  114 This allows binary distributions to be unpacked anywhere in the
  115 file system and then be used without setting <code>GOROOT</code>
  116 explicitly.
  117 </p>
  118 
  119 <p>
  120 By default, the go tool creates its temporary files and directories
  121 in the system temporary directory (for example, <code>$TMPDIR</code> on Unix).
  122 If the new environment variable <code>$GOTMPDIR</code> is set,
  123 the go tool will creates its temporary files and directories in that directory instead.
  124 </p>
  125 
  126 <h3 id="build">Build &amp; Install</h3>
  127 
  128 <p>
  129 The <code>go</code>&nbsp;<code>build</code> command now detects out-of-date packages
  130 purely based on the content of source files, specified build flags, and metadata stored in the compiled packages.
  131 Modification times are no longer consulted or relevant.
  132 The old advice to add <code>-a</code> to force a rebuild in cases where
  133 the modification times were misleading for one reason or another
  134 (for example, changes in build flags) is no longer necessary:
  135 builds now always detect when packages must be rebuilt.
  136 (If you observe otherwise, please file a bug.)
  137 </p>
  138 
  139 <p>
  140 The <code>go</code>&nbsp;<code>build</code> <code>-asmflags</code>, <code>-gcflags</code>, <code>-gccgoflags</code>, and <code>-ldflags</code> options
  141 now apply by default only to the packages listed directly on the command line.
  142 For example, <code>go</code> <code>build</code> <code>-gcflags=-m</code> <code>mypkg</code>
  143 passes the compiler the <code>-m</code> flag when building <code>mypkg</code>
  144 but not its dependencies.
  145 The new, more general form <code>-asmflags=pattern=flags</code> (and similarly for the others)
  146 applies the <code>flags</code> only to the packages matching the pattern.
  147 For example: <code>go</code> <code>install</code> <code>-ldflags=cmd/gofmt=-X=main.version=1.2.3</code> <code>cmd/...</code>
  148 installs all the commands matching <code>cmd/...</code> but only applies the <code>-X</code> option
  149 to the linker flags for <code>cmd/gofmt</code>.
  150 For more details, see <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go</code> <code>help</code> <code>build</code></a>.
  151 </p>
  152 
  153 <p>
  154 The <code>go</code>&nbsp;<code>build</code> command now maintains a cache of
  155 recently built packages, separate from the installed packages in <code>$GOROOT/pkg</code> or <code>$GOPATH/pkg</code>.
  156 The effect of the cache should be to speed builds that do not explicitly install packages
  157 or when switching between different copies of source code (for example, when changing
  158 back and forth between different branches in a version control system).
  159 The old advice to add the <code>-i</code> flag for speed, as in <code>go</code> <code>build</code> <code>-i</code>
  160 or <code>go</code> <code>test</code> <code>-i</code>,
  161 is no longer necessary: builds run just as fast without <code>-i</code>.
  162 For more details, see <a href="/cmd/go/#hdr-Build_and_test_caching"><code>go</code> <code>help</code> <code>cache</code></a>.
  163 </p>
  164 
  165 <p>
  166 The <code>go</code>&nbsp;<code>install</code> command now installs only the
  167 packages and commands listed directly on the command line.
  168 For example, <code>go</code> <code>install</code> <code>cmd/gofmt</code>
  169 installs the gofmt program but not any of the packages on which it depends.
  170 The new build cache makes future commands still run as quickly as if the
  171 dependencies had been installed.
  172 To force the installation of dependencies, use the new
  173 <code>go</code> <code>install</code> <code>-i</code> flag.
  174 Installing dependency packages should not be necessary in general,
  175 and the very concept of installed packages may disappear in a future release.
  176 </p>
  177 
  178 <p>
  179 Many details of the <code>go</code>&nbsp;<code>build</code> implementation have changed to support these improvements.
  180 One new requirement implied by these changes is that
  181 binary-only packages must now declare accurate import blocks in their
  182 stub source code, so that those imports can be made available when
  183 linking a program using the binary-only package.
  184 For more details, see <a href="/cmd/go/#hdr-File_types"><code>go</code> <code>help</code> <code>filetype</code></a>.
  185 </p>
  186 
  187 <h3 id="test">Test</h3>
  188 
  189 <p>
  190 The <code>go</code>&nbsp;<code>test</code> command now caches test results:
  191 if the test executable and command line match a previous run
  192 and the files and environment variables consulted by that run
  193 have not changed either, <code>go</code> <code>test</code> will print
  194 the previous test output, replacing the elapsed time with the string “(cached).”
  195 Test caching applies only to successful test results;
  196 only to <code>go</code> <code>test</code>
  197 commands with an explicit list of packages; and
  198 only to command lines using a subset of the
  199 <code>-cpu</code>, <code>-list</code>, <code>-parallel</code>,
  200 <code>-run</code>, <code>-short</code>, and <code>-v</code> test flags.
  201 The idiomatic way to bypass test caching is to use <code>-count=1</code>.
  202 </p>
  203 
  204 <p id="test-vet">
  205 The <code>go</code>&nbsp;<code>test</code> command now automatically runs
  206 <code>go</code> <code>vet</code> on the package being tested,
  207 to identify significant problems before running the test.
  208 Any such problems are treated like build errors and prevent execution of the test.
  209 Only a high-confidence subset of the available <code>go</code> <code>vet</code>
  210 checks are enabled for this automatic check.
  211 To disable the running of <code>go</code> <code>vet</code>, use
  212 <code>go</code> <code>test</code> <code>-vet=off</code>.
  213 </p>
  214 
  215 <p>
  216 The <code>go</code> <code>test</code> <code>-coverpkg</code> flag now
  217 interprets its argument as a comma-separated list of patterns to match against
  218 the dependencies of each test, not as a list of packages to load anew.
  219 For example, <code>go</code> <code>test</code> <code>-coverpkg=all</code>
  220 is now a meaningful way to run a test with coverage enabled for the test package
  221 and all its dependencies.
  222 Also, the <code>go</code> <code>test</code> <code>-coverprofile</code> option is now
  223 supported when running multiple tests.
  224 </p>
  225 
  226 <p>
  227 In case of failure due to timeout, tests are now more likely to write their profiles before exiting.
  228 </p>
  229 
  230 <p>
  231 The <code>go</code>&nbsp;<code>test</code> command now always
  232 merges the standard output and standard error from a given test binary execution
  233 and writes both to <code>go</code> <code>test</code>'s standard output.
  234 In past releases, <code>go</code> <code>test</code> only applied this
  235 merging most of the time.
  236 </p>
  237 
  238 <p>
  239 The <code>go</code>&nbsp;<code>test</code> <code>-v</code> output
  240 now includes <code>PAUSE</code> and <code>CONT</code> status update
  241 lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
  242 </p>
  243 
  244 <p>
  245 The new <code>go</code> <code>test</code> <code>-failfast</code> flag
  246 disables running additional tests after any test fails.
  247 Note that tests running in parallel with the failing test are allowed to complete.
  248 </p>
  249 
  250 <p>
  251 Finally, the new <code>go</code> <code>test</code> <code>-json</code> flag
  252 filters test output through the new command
  253 <code>go</code> <code>tool</code> <code>test2json</code>
  254 to produce a machine-readable JSON-formatted description of test execution.
  255 This allows the creation of rich presentations of test execution
  256 in IDEs and other tools.
  257 </p>
  258 
  259 
  260 <p>
  261 For more details about all these changes,
  262 see <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>help</code> <code>test</code></a>
  263 and the <a href="/cmd/test2json/">test2json documentation</a>.
  264 </p>
  265 
  266 <h3 id="cgo">Cgo</h3>
  267 
  268 <p>
  269 Options specified by cgo using <code>#cgo CFLAGS</code> and the like
  270 are now checked against a whitelist of permitted options.
  271 This closes a security hole in which a downloaded package uses
  272 compiler options like
  273 <span style="white-space: nowrap"><code>-fplugin</code></span>
  274 to run arbitrary code on the machine where it is being built.
  275 This can cause a build error such as <code>invalid flag in #cgo CFLAGS</code>.
  276 For more background, and how to handle this error, see
  277 <a href="https://golang.org/s/invalidflag">https://golang.org/s/invalidflag</a>.
  278 </p>
  279 
  280 <p>
  281 Cgo now implements a C typedef like “<code>typedef</code> <code>X</code> <code>Y</code>” using a Go type alias,
  282 so that Go code may use the types <code>C.X</code> and <code>C.Y</code> interchangeably.
  283 It also now supports the use of niladic function-like macros.
  284 Also, the documentation has been updated to clarify that
  285 Go structs and Go arrays are not supported in the type signatures of cgo-exported functions.
  286 </p>
  287 
  288 <p>
  289 Cgo now supports direct access to Go string values from C.
  290 Functions in the C preamble may use the type <code>_GoString_</code>
  291 to accept a Go string as an argument.
  292 C code may call <code>_GoStringLen</code> and <code>_GoStringPtr</code>
  293 for direct access to the contents of the string.
  294 A value of type <code>_GoString_</code>
  295 may be passed in a call to an exported Go function that takes an argument of Go type <code>string</code>.
  296 </p>
  297 
  298 <p>
  299 During toolchain bootstrap, the environment variables <code>CC</code> and <code>CC_FOR_TARGET</code> specify
  300 the default C compiler that the resulting toolchain will use for host and target builds, respectively.
  301 However, if the toolchain will be used with multiple targets, it may be necessary to specify a different C compiler for each
  302 (for example, a different compiler for <code>darwin/arm64</code> versus <code>linux/ppc64le</code>).
  303 The new set of environment variables <code>CC_FOR_<i>goos</i>_<i>goarch</i></code>
  304 allows specifying a different default C compiler for each target.
  305 Note that these variables only apply during toolchain bootstrap,
  306 to set the defaults used by the resulting toolchain.
  307 Later <code>go</code> <code>build</code> commands use the <code>CC</code> environment
  308 variable or else the built-in default.
  309 </p>
  310 
  311 <p>
  312 Cgo now translates some C types that would normally map to a pointer
  313 type in Go, to a <code>uintptr</code> instead. These types include
  314 the <code>CFTypeRef</code> hierarchy in Darwin's CoreFoundation
  315 framework and the <code>jobject</code> hierarchy in Java's JNI
  316 interface.
  317 </p>
  318 
  319 <p>
  320 These types must be <code>uintptr</code> on the Go side because they
  321 would otherwise confuse the Go garbage collector; they are sometimes
  322 not really pointers but data structures encoded in a pointer-sized integer.
  323 Pointers to Go memory must not be stored in these <code>uintptr</code> values.
  324 </p>
  325 
  326 <p>
  327 Because of this change, values of the affected types need to be
  328 zero-initialized with the constant <code>0</code> instead of the
  329 constant <code>nil</code>. Go 1.10 provides <code>gofix</code>
  330 modules to help with that rewrite:
  331 </p>
  332 
  333 <pre>
  334 go tool fix -r cftype &lt;pkg&gt;
  335 go tool fix -r jni &lt;pkg&gt;
  336 </pre>
  337 
  338 <p>
  339 For more details, see the <a href="/cmd/cgo/">cgo documentation</a>.
  340 </p>
  341 
  342 <h3 id="doc">Doc</h3>
  343 
  344 <p>
  345 The <code>go</code>&nbsp;<code>doc</code> tool now adds functions returning slices of <code>T</code> or <code>*T</code>
  346 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.
  347 For example:
  348 </p>
  349 
  350 <pre>
  351 $ go doc mail.Address
  352 package mail // import "net/mail"
  353 
  354 type Address struct {
  355     Name    string
  356     Address string
  357 }
  358     Address represents a single mail address.
  359 
  360 func ParseAddress(address string) (*Address, error)
  361 func ParseAddressList(list string) ([]*Address, error)
  362 func (a *Address) String() string
  363 $
  364 </pre>
  365 
  366 <p>
  367 Previously, <code>ParseAddressList</code> was only shown in the package overview (<code>go</code> <code>doc</code> <code>mail</code>).
  368 </p>
  369 
  370 <h3 id="fix">Fix</h3>
  371 
  372 <p>
  373 The <code>go</code>&nbsp;<code>fix</code> tool now replaces imports of <code>"golang.org/x/net/context"</code>
  374 with <code>"context"</code>.
  375 (Forwarding aliases in the former make it completely equivalent to the latter when using Go 1.9 or later.)
  376 </p>
  377 
  378 <h3 id="get">Get</h3>
  379 
  380 <p>
  381 The <code>go</code>&nbsp;<code>get</code> command now supports Fossil source code repositories.
  382 </p>
  383 
  384 <h3 id="pprof">Pprof</h3>
  385 
  386 <p>
  387 The blocking and mutex profiles produced by the <code>runtime/pprof</code> package
  388 now include symbol information, so they can be viewed
  389 in <code>go</code> <code>tool</code> <code>pprof</code>
  390 without the binary that produced the profile.
  391 (All other profile types were changed to include symbol information in Go 1.9.)
  392 </p>
  393 
  394 <p>
  395 The <a href="/cmd/pprof/"><code>go</code>&nbsp;<code>tool</code>&nbsp;<code>pprof</code></a>
  396 profile visualizer has been updated to git version 9e20b5b (2017-11-08)
  397 from <a href="https://github.com/google/pprof">github.com/google/pprof</a>,
  398 which includes an updated web interface.
  399 </p>
  400 
  401 <h3 id="vet">Vet</h3>
  402 
  403 <p>
  404 The <a href="/cmd/vet/"><code>go</code>&nbsp;<code>vet</code></a> command now always has access to
  405 complete, up-to-date type information when checking packages, even for packages using cgo or vendored imports.
  406 The reports should be more accurate as a result.
  407 Note that only <code>go</code>&nbsp;<code>vet</code> has access to this information;
  408 the more low-level <code>go</code>&nbsp;<code>tool</code>&nbsp;<code>vet</code> does not
  409 and should be avoided except when working on <code>vet</code> itself.
  410 (As of Go 1.9, <code>go</code>&nbsp;<code>vet</code> provides access to all the same flags as
  411 <code>go</code>&nbsp;<code>tool</code>&nbsp;<code>vet</code>.)
  412 </p>
  413 
  414 <h3 id="diag">Diagnostics</h3>
  415 
  416 <p>
  417 This release includes a new <a href="/doc/diagnostics.html">overview of available Go program diagnostic tools</a>.
  418 </p>
  419 
  420 <h3 id="gofmt">Gofmt</h3>
  421 
  422 <p>
  423 Two minor details of the default formatting of Go source code have changed.
  424 First, certain complex three-index slice expressions previously formatted like
  425 <code>x[i+1</code>&nbsp;<code>:</code>&nbsp;<code>j:k]</code> and now
  426 format with more consistent spacing: <code>x[i+1</code>&nbsp;<code>:</code>&nbsp;<code>j</code>&nbsp;<code>:</code>&nbsp;<code>k]</code>.
  427 Second, single-method interface literals written on a single line,
  428 which are sometimes used in type assertions,
  429 are no longer split onto multiple lines.
  430 </p>
  431 
  432 <p>
  433 Note that these kinds of minor updates to gofmt are expected from time to time.
  434 In general, we recommend against building systems that check that source code
  435 matches the output of a specific version of gofmt.
  436 For example, a continuous integration test that fails if any code already checked into
  437 a repository is not “properly formatted” is inherently fragile and not recommended.
  438 </p>
  439 
  440 <p>
  441 If multiple programs must agree about which version of gofmt is used to format a source file,
  442 we recommend that they do this by arranging to invoke the same gofmt binary.
  443 For example, in the Go open source repository, our Git pre-commit hook is written in Go
  444 and could import <code>go/format</code> directly, but instead it invokes the <code>gofmt</code>
  445 binary found in the current path, so that the pre-commit hook need not be recompiled
  446 each time <code>gofmt</code> changes.
  447 </p>
  448 
  449 <h3 id="compiler">Compiler Toolchain</h3>
  450 
  451 <p>
  452 The compiler includes many improvements to the performance of generated code,
  453 spread fairly evenly across the supported architectures.
  454 </p>
  455 
  456 <p>
  457 The DWARF debug information recorded in binaries has been improved in a few ways:
  458 constant values are now recorded;
  459 line number information is more accurate, making source-level stepping through a program work better;
  460 and each package is now presented as its own DWARF compilation unit.
  461 </p>
  462 
  463 <p>
  464 The various <a href="https://docs.google.com/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit">build modes</a>
  465 have been ported to more systems.
  466 Specifically, <code>c-shared</code> now works on <code>linux/ppc64le</code>, <code>windows/386</code>, and <code>windows/amd64</code>;
  467 <code>pie</code> now works on <code>darwin/amd64</code> and also forces the use of external linking on all systems;
  468 and <code>plugin</code> now works on <code>linux/ppc64le</code> and <code>darwin/amd64</code>.
  469 </p>
  470 
  471 <p>
  472 The <code>linux/ppc64le</code> port now requires the use of external linking
  473 with any programs that use cgo, even uses by the standard library.
  474 </p>
  475 
  476 <h3 id="asm">Assembler</h3>
  477 
  478 <p>
  479 For the ARM 32-bit port, the assembler now supports the instructions
  480 <code><small>BFC</small></code>,
  481 <code><small>BFI</small></code>,
  482 <code><small>BFX</small></code>,
  483 <code><small>BFXU</small></code>,
  484 <code><small>FMULAD</small></code>,
  485 <code><small>FMULAF</small></code>,
  486 <code><small>FMULSD</small></code>,
  487 <code><small>FMULSF</small></code>,
  488 <code><small>FNMULAD</small></code>,
  489 <code><small>FNMULAF</small></code>,
  490 <code><small>FNMULSD</small></code>,
  491 <code><small>FNMULSF</small></code>,
  492 <code><small>MULAD</small></code>,
  493 <code><small>MULAF</small></code>,
  494 <code><small>MULSD</small></code>,
  495 <code><small>MULSF</small></code>,
  496 <code><small>NMULAD</small></code>,
  497 <code><small>NMULAF</small></code>,
  498 <code><small>NMULD</small></code>,
  499 <code><small>NMULF</small></code>,
  500 <code><small>NMULSD</small></code>,
  501 <code><small>NMULSF</small></code>,
  502 <code><small>XTAB</small></code>,
  503 <code><small>XTABU</small></code>,
  504 <code><small>XTAH</small></code>,
  505 and
  506 <code><small>XTAHU</small></code>.
  507 </p>
  508 
  509 <p>
  510 For the ARM 64-bit port, the assembler now supports the
  511 <code><small>VADD</small></code>,
  512 <code><small>VADDP</small></code>,
  513 <code><small>VADDV</small></code>,
  514 <code><small>VAND</small></code>,
  515 <code><small>VCMEQ</small></code>,
  516 <code><small>VDUP</small></code>,
  517 <code><small>VEOR</small></code>,
  518 <code><small>VLD1</small></code>,
  519 <code><small>VMOV</small></code>,
  520 <code><small>VMOVI</small></code>,
  521 <code><small>VMOVS</small></code>,
  522 <code><small>VORR</small></code>,
  523 <code><small>VREV32</small></code>,
  524 and
  525 <code><small>VST1</small></code>
  526 instructions.
  527 </p>
  528 
  529 <p>
  530 For the PowerPC 64-bit port, the assembler now supports the POWER9 instructions
  531 <code><small>ADDEX</small></code>,
  532 <code><small>CMPEQB</small></code>,
  533 <code><small>COPY</small></code>,
  534 <code><small>DARN</small></code>,
  535 <code><small>LDMX</small></code>,
  536 <code><small>MADDHD</small></code>,
  537 <code><small>MADDHDU</small></code>,
  538 <code><small>MADDLD</small></code>,
  539 <code><small>MFVSRLD</small></code>,
  540 <code><small>MTVSRDD</small></code>,
  541 <code><small>MTVSRWS</small></code>,
  542 <code><small>PASTECC</small></code>,
  543 <code><small>VCMPNEZB</small></code>,
  544 <code><small>VCMPNEZBCC</small></code>,
  545 and
  546 <code><small>VMSUMUDM</small></code>.
  547 </p>
  548 
  549 <p>
  550 For the S390X port, the assembler now supports the
  551 <code><small>TMHH</small></code>,
  552 <code><small>TMHL</small></code>,
  553 <code><small>TMLH</small></code>,
  554 and
  555 <code><small>TMLL</small></code>
  556 instructions.
  557 </p>
  558 
  559 <p>
  560 For the X86 64-bit port, the assembler now supports 359 new instructions,
  561 including the full AVX, AVX2, BMI, BMI2, F16C, FMA3, SSE2, SSE3, SSSE3, SSE4.1, and SSE4.2 extension sets.
  562 The assembler also no longer implements <code><small>MOVL</small></code>&nbsp;<code><small>$0,</small></code>&nbsp;<code><small>AX</small></code>
  563 as an <code><small>XORL</small></code> instruction,
  564 to avoid clearing the condition flags unexpectedly.
  565 </p>
  566 
  567 <h3 id="gccgo">Gccgo</h3>
  568 
  569 <p>
  570 Due to the alignment of Go's semiannual release schedule with GCC's
  571 annual release schedule,
  572 GCC release 7 contains the Go 1.8.3 version of gccgo.
  573 We expect that the next release, GCC 8, will contain the Go 1.10
  574 version of gccgo.
  575 </p>
  576 
  577 <h2 id="runtime">Runtime</h2>
  578 
  579 <p>
  580 The behavior of nested calls to
  581 <a href="/pkg/runtime/#LockOSThread"><code>LockOSThread</code></a> and
  582 <a href="/pkg/runtime/#UnlockOSThread"><code>UnlockOSThread</code></a>
  583 has changed.
  584 These functions control whether a goroutine is locked to a specific operating system thread,
  585 so that the goroutine only runs on that thread, and the thread only runs that goroutine.
  586 Previously, calling <code>LockOSThread</code> more than once in a row
  587 was equivalent to calling it once, and a single <code>UnlockOSThread</code>
  588 always unlocked the thread.
  589 Now, the calls nest: if <code>LockOSThread</code> is called multiple times,
  590 <code>UnlockOSThread</code> must be called the same number of times
  591 in order to unlock the thread.
  592 Existing code that was careful not to nest these calls will remain correct.
  593 Existing code that incorrectly assumed the calls nested will become correct.
  594 Most uses of these functions in public Go source code falls into the second category.
  595 </p>
  596 
  597 <p>
  598 Because one common use of <code>LockOSThread</code> and <code>UnlockOSThread</code>
  599 is to allow Go code to reliably modify thread-local state (for example, Linux or Plan 9 name spaces),
  600 the runtime now treats locked threads as unsuitable for reuse or for creating new threads.
  601 </p>
  602 
  603 <p>
  604 Stack traces no longer include implicit wrapper functions (previously marked <code>&lt;autogenerated&gt;</code>),
  605 unless a fault or panic happens in the wrapper itself.
  606 As a result, skip counts passed to functions like <a href="/pkg/runtime/#Caller"><code>Caller</code></a>
  607 should now always match the structure of the code as written, rather than depending on
  608 optimization decisions and implementation details.
  609 </p>
  610 
  611 <p>
  612 The garbage collector has been modified to reduce its impact on allocation latency.
  613 It now uses a smaller fraction of the overall CPU when running, but it may run more of the time.
  614 The total CPU consumed by the garbage collector has not changed significantly.
  615 </p>
  616 
  617 <p>
  618 The <a href="/pkg/runtime/#GOROOT"><code>GOROOT</code></a> function
  619 now defaults (when the <code>$GOROOT</code> environment variable is not set)
  620 to the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect
  621 at the time the calling program was compiled.
  622 Previously it used the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect
  623 at the time the toolchain that compiled the calling program was compiled.
  624 </p>
  625 
  626 <p>
  627 There is no longer a limit on the <a href="/pkg/runtime/#GOMAXPROCS"><code>GOMAXPROCS</code></a> setting.
  628 (In Go 1.9 the limit was 1024.)
  629 </p>
  630 
  631 <h2 id="performance">Performance</h2>
  632 
  633 <p>
  634 As always, the changes are so general and varied that precise
  635 statements about performance are difficult to make.  Most programs
  636 should run a bit faster, due to speedups in the garbage collector,
  637 better generated code, and optimizations in the core library.
  638 </p>
  639 
  640 <h2 id="gc">Garbage Collector</h2>
  641 
  642 <p>
  643 Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active.
  644 </p>
  645 
  646 <h2 id="library">Core library</h2>
  647 
  648 <p>
  649 All of the changes to the standard library are minor.
  650 The changes in <a href="#bytes">bytes</a>
  651 and <a href="#net/url">net/url</a> are the most likely to require updating of existing programs.
  652 </p>
  653 
  654 <h3 id="minor_library_changes">Minor changes to the library</h3>
  655 
  656 <p>
  657 As always, there are various minor changes and updates to the library,
  658 made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
  659 in mind.
  660 </p>
  661 
  662 <dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
  663 <dd>
  664 <p>
  665 In general, the handling of special header formats is significantly improved and expanded.
  666 </p>
  667 <p>
  668 <a href="/pkg/archive/tar/#FileInfoHeader"><code>FileInfoHeader</code></a> has always
  669 recorded the Unix UID and GID numbers from its <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> argument
  670 (specifically, from the system-dependent information returned by the <code>FileInfo</code>'s <code>Sys</code> method)
  671 in the returned <a href="/pkg/archive/tar/#Header"><code>Header</code></a>.
  672 Now it also records the user and group names corresponding to those IDs,
  673 as well as the major and minor device numbers for device files.
  674 </p>
  675 <p>
  676 The new <a href="/pkg/archive/tar/#Header"><code>Header.Format</code></a> field
  677 of type <a href="/pkg/archive/tar/#Format"><code>Format</code></a>
  678 controls which tar header format the <a href="/pkg/archive/tar/#Writer"><code>Writer</code></a> uses.
  679 The default, as before, is to select the most widely-supported header type
  680 that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
  681 The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads.
  682 </p>
  683 <p>
  684 <code>Reader</code> and the <code>Writer</code> now support arbitrary PAX records,
  685 using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field,
  686 a generalization of the existing <code>Xattrs</code> field.
  687 </p>
  688 <p>
  689 The <code>Reader</code> no longer insists that the file name or link name in GNU headers
  690 be valid UTF-8.
  691 </p>
  692 <p>
  693 When writing PAX- or GNU-format headers, the <code>Writer</code> now includes
  694 the <code>Header.AccessTime</code> and <code>Header.ChangeTime</code> fields (if set).
  695 When writing PAX-format headers, the times include sub-second precision.
  696 </p>
  697 </dl>
  698 
  699 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
  700 <dd>
  701 <p>
  702 Go 1.10 adds more complete support for times and character set encodings in ZIP archives.
  703 </p>
  704 <p>
  705 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.
  706 That encoding cannot represent time zones or odd seconds, so multiple extensions have been
  707 introduced to allow richer encodings.
  708 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>
  709 now support the widely-understood Info-Zip extension that encodes the time separately in the 32-bit Unix “seconds since epoch” form.
  710 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>
  711 obsoletes the <code>ModifiedTime</code> and <code>ModifiedDate</code> fields, which continue to hold the MS-DOS encoding.
  712 The <code>Reader</code> and <code>Writer</code> now adopt the common
  713 convention that a ZIP archive storing a time zone-independent Unix time
  714 also stores the local time in the MS-DOS field,
  715 so that the time zone offset can be inferred.
  716 For compatibility, the <a href="/pkg/archive/zip/#FileHeader.ModTime"><code>ModTime</code></a> and
  717 <a href="/pkg/archive/zip/#FileHeader.SetModTime"><code>SetModTime</code></a> methods
  718 behave the same as in earlier releases; new code should use <code>Modified</code> directly.
  719 </p>
  720 <p>
  721 The header for each file in a ZIP archive has a flag bit indicating whether
  722 the name and comment fields are encoded as UTF-8, as opposed to a system-specific default encoding.
  723 In Go 1.8 and earlier, the <code>Writer</code> never set the UTF-8 bit.
  724 In Go 1.9, the <code>Writer</code> changed to set the UTF-8 bit almost always.
  725 This broke the creation of ZIP archives containing Shift-JIS file names.
  726 In Go 1.10, the <code>Writer</code> now sets the UTF-8 bit only when
  727 both the name and the comment field are valid UTF-8 and at least one is non-ASCII.
  728 Because non-ASCII encodings very rarely look like valid UTF-8, the new
  729 heuristic should be correct nearly all the time.
  730 Setting a <code>FileHeader</code>'s new <code>NonUTF8</code> field to true
  731 disables the heuristic entirely for that file.
  732 </p>
  733 <p>
  734 The <code>Writer</code> also now supports setting the end-of-central-directory record's comment field,
  735 by calling the <code>Writer</code>'s new <a href="/pkg/archive/zip/#Writer.SetComment"><code>SetComment</code></a> method.
  736 </p>
  737 </dl>
  738 
  739 <dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt>
  740 <dd>
  741 <p>
  742 The new <a href="/pkg/bufio/#Reader.Size"><code>Reader.Size</code></a>
  743 and <a href="/pkg/bufio/#Writer.Size"><code>Writer.Size</code></a>
  744 methods report the <code>Reader</code> or <code>Writer</code>'s underlying buffer size.
  745 </p>
  746 </dl>
  747 
  748 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
  749 <dd>
  750 <p>
  751 The
  752 <a href="/pkg/bytes/#Fields"><code>Fields</code></a>,
  753 <a href="/pkg/bytes/#FieldsFunc"><code>FieldsFunc</code></a>,
  754 <a href="/pkg/bytes/#Split"><code>Split</code></a>,
  755 and
  756 <a href="/pkg/bytes/#SplitAfter"><code>SplitAfter</code></a>
  757 functions have always returned subslices of their inputs.
  758 Go 1.10 changes each returned subslice to have capacity equal to its length,
  759 so that appending to one cannot overwrite adjacent data in the original input.
  760 </p>
  761 </dl>
  762 
  763 <dl id="crypto/cipher"><dt><a href="/pkg/crypto/cipher/">crypto/cipher</a></dt>
  764 <dd>
  765 <p>
  766 <a href="/pkg/crypto/cipher/#NewOFB"><code>NewOFB</code></a> now panics if given
  767 an initialization vector of incorrect length, like the other constructors in the
  768 package always have.
  769 (Previously it returned a nil <code>Stream</code> implementation.)
  770 </p>
  771 </dl>
  772 
  773 <dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
  774 <dd>
  775 <p>
  776 The TLS server now advertises support for SHA-512 signatures when using TLS 1.2.
  777 The server already supported the signatures, but some clients would not select
  778 them unless explicitly advertised.
  779 </p>
  780 </dl>
  781 
  782 <dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
  783 <dd>
  784 <p>
  785 <a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>
  786 now enforces the name constraints for all
  787 names contained in the certificate, not just the one name that a client has asked about.
  788 Extended key usage restrictions are similarly now checked all at once.
  789 As a result, after a certificate has been validated, now it can be trusted in its entirety.
  790 It is no longer necessary to revalidate the certificate for each additional name
  791 or key usage.
  792 </p>
  793 
  794 <p>
  795 Parsed certificates also now report URI names and IP, email, and URI constraints, using the new
  796 <a href="/pkg/crypto/x509/#Certificate"><code>Certificate</code></a> fields
  797 <code>URIs</code>, <code>PermittedIPRanges</code>, <code>ExcludedIPRanges</code>,
  798 <code>PermittedEmailAddresses</code>, <code>ExcludedEmailAddresses</code>,
  799 <code>PermittedURIDomains</code>, and <code>ExcludedURIDomains</code>. Certificates with
  800 invalid values for those fields are now rejected.
  801 </p>
  802 
  803 <p>
  804 The new <a href="/pkg/crypto/x509/#MarshalPKCS1PublicKey"><code>MarshalPKCS1PublicKey</code></a>
  805 and <a href="/pkg/crypto/x509/#ParsePKCS1PublicKey"><code>ParsePKCS1PublicKey</code></a>
  806 functions convert an RSA public key to and from PKCS#1-encoded form.
  807 </p>
  808 
  809 <p>
  810 The new <a href="/pkg/crypto/x509/#MarshalPKCS8PrivateKey"><code>MarshalPKCS8PrivateKey</code></a>
  811 function converts a private key to PKCS#8-encoded form.
  812 (<a href="/pkg/crypto/x509/#ParsePKCS8PrivateKey"><code>ParsePKCS8PrivateKey</code></a>
  813 has existed since Go 1.)
  814 </p>
  815 </dl>
  816 
  817 <dl id="crypto/x509/pkix"><dt><a href="/pkg/crypto/x509/pkix/">crypto/x509/pkix</a></dt>
  818 <dd>
  819 <p>
  820 <a href="/pkg/crypto/x509/pkix/#Name"><code>Name</code></a> now implements a
  821 <a href="/pkg/crypto/x509/pkix/#Name.String"><code>String</code></a> method that
  822 formats the X.509 distinguished name in the standard RFC 2253 format.
  823 </p>
  824 </dl>
  825 
  826 <dl id="database/sql/driver"><dt><a href="/pkg/database/sql/driver/">database/sql/driver</a></dt>
  827 <dd>
  828 <p>
  829 Drivers that currently hold on to the destination buffer provided by
  830 <a href="/pkg/database/sql/driver/#Rows.Next"><code>driver.Rows.Next</code></a> should ensure they no longer
  831 write to a buffer assigned to the destination array outside of that call.
  832 Drivers must be careful that underlying buffers are not modified when closing
  833 <a href="/pkg/database/sql/driver/#Rows"><code>driver.Rows</code></a>.
  834 </p>
  835 <p>
  836 Drivers that want to construct a <a href="/pkg/database/sql/#DB"><code>sql.DB</code></a> for
  837 their clients can now implement the <a href="/pkg/database/sql/driver/#Connector"><code>Connector</code></a> interface
  838 and call the new <a href="/pkg/database/sql/#OpenDB"><code>sql.OpenDB</code></a> function,
  839 instead of needing to encode all configuration into a string
  840 passed to  <a href="/pkg/database/sql/#Open"><code>sql.Open</code></a>.
  841 </p>
  842 <p>
  843 Drivers that want to parse the configuration string only once per <code>sql.DB</code>
  844 instead of once per <a href="/pkg/database/sql/#Conn"><code>sql.Conn</code></a>,
  845 or that want access to each <code>sql.Conn</code>'s underlying context,
  846 can make their <a href="/pkg/database/sql/driver/#Driver"><code>Driver</code></a>
  847 implementations also implement <a href="/pkg/database/sql/driver/#DriverContext"><code>DriverContext</code></a>'s
  848 new <code>OpenConnector</code> method.
  849 </p>
  850 <p>
  851 Drivers that implement <a href="/pkg/database/sql/driver/#ExecerContext"><code>ExecerContext</code></a>
  852 no longer need to implement <a href="/pkg/database/sql/driver/#Execer"><code>Execer</code></a>;
  853 similarly, drivers that implement <a href="/pkg/database/sql/driver/#QueryerContext"><code>QueryerContext</code></a>
  854 no longer need to implement <a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>.
  855 Previously, even if the context-based interfaces were implemented they were ignored
  856 unless the non-context-based interfaces were also implemented.
  857 </p>
  858 <p>
  859 To allow drivers to better isolate different clients using a cached driver connection in succession,
  860 if a <a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a> implements the new
  861 <a href="/pkg/database/sql/driver/#SessionResetter"><code>SessionResetter</code></a> interface,
  862 <code>database/sql</code> will now call <code>ResetSession</code> before
  863 reusing the <code>Conn</code> for a new client.
  864 </p>
  865 </dl>
  866 
  867 <dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
  868 <dd>
  869 <p>
  870 This release adds 348 new relocation constants divided between the relocation types
  871 <a href="/pkg/debug/elf/#R_386"><code>R_386</code></a>,
  872 <a href="/pkg/debug/elf/#R_AARCH64"><code>R_AARCH64</code></a>,
  873 <a href="/pkg/debug/elf/#R_ARM"><code>R_ARM</code></a>,
  874 <a href="/pkg/debug/elf/#R_PPC64"><code>R_PPC64</code></a>,
  875 and
  876 <a href="/pkg/debug/elf/#R_X86_64"><code>R_X86_64</code></a>.
  877 </p>
  878 </dl>
  879 
  880 <dl id="debug/macho"><dt><a href="/pkg/debug/macho/">debug/macho</a></dt>
  881 <dd>
  882 <p>
  883 Go 1.10 adds support for reading relocations from Mach-O sections,
  884 using the <a href="/pkg/debug/macho#Section"><code>Section</code></a> struct's new <code>Relocs</code> field
  885 and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
  886 <a href="/pkg/debug/macho/#RelocTypeARM"><code>RelocTypeARM</code></a>,
  887 <a href="/pkg/debug/macho/#RelocTypeARM64"><code>RelocTypeARM64</code></a>,
  888 <a href="/pkg/debug/macho/#RelocTypeGeneric"><code>RelocTypeGeneric</code></a>,
  889 and
  890 <a href="/pkg/debug/macho/#RelocTypeX86_64"><code>RelocTypeX86_64</code></a>
  891 types and associated constants.
  892 </p>
  893 <p>
  894 Go 1.10 also adds support for the <code>LC_RPATH</code> load command,
  895 represented by the types
  896 <a href="/pkg/debug/macho/#RpathCmd"><code>RpathCmd</code></a> and
  897 <a href="/pkg/debug/macho/#Rpath"><code>Rpath</code></a>,
  898 and new <a href="/pkg/debug/macho/#pkg-constants">named constants</a>
  899 for the various flag bits found in headers.
  900 </p>
  901 </dl>
  902 
  903 <dl id="encoding/asn1"><dt><a href="/pkg/encoding/asn1/">encoding/asn1</a></dt>
  904 <dd>
  905 <p>
  906 <a href="/pkg/encoding/asn1/#Marshal"><code>Marshal</code></a> now correctly encodes
  907 strings containing asterisks as type UTF8String instead of PrintableString,
  908 unless the string is in a struct field with a tag forcing the use of PrintableString.
  909 <code>Marshal</code> also now respects struct tags containing <code>application</code> directives.
  910 </p>
  911 <p>
  912 The new <a href="/pkg/encoding/asn1/#MarshalWithParams"><code>MarshalWithParams</code></a>
  913 function marshals its argument as if the additional params were its associated
  914 struct field tag.
  915 </p>
  916 <p>
  917 <a href="/pkg/encoding/asn1/#Unmarshal"><code>Unmarshal</code></a> now respects
  918 struct field tags using the <code>explicit</code> and <code>tag</code>
  919 directives.
  920 </p>
  921 <p>
  922 Both <code>Marshal</code> and <code>Unmarshal</code> now support a new struct field tag
  923 <code>numeric</code>, indicating an ASN.1 NumericString.
  924 </p>
  925 </dl>
  926 
  927 <dl id="encoding/csv"><dt><a href="/pkg/encoding/csv/">encoding/csv</a></dt>
  928 <dd>
  929 <p>
  930 <a href="/pkg/encoding/csv/#Reader"><code>Reader</code></a> now disallows the use of
  931 nonsensical <code>Comma</code> and <code>Comment</code> settings,
  932 such as NUL, carriage return, newline, invalid runes, and the Unicode replacement character,
  933 or setting <code>Comma</code> and <code>Comment</code> equal to each other.
  934 </p>
  935 <p>
  936 In the case of a syntax error in a CSV record that spans multiple input lines, <code>Reader</code>
  937 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.
  938 </p>
  939 </dl>
  940 
  941 <dl id="encoding/hex"><dt><a href="/pkg/encoding/hex/">encoding/hex</a></dt>
  942 <dd>
  943 <p>
  944 The new functions
  945 <a href="/pkg/encoding/hex/#NewEncoder"><code>NewEncoder</code></a>
  946 and
  947 <a href="/pkg/encoding/hex/#NewDecoder"><code>NewDecoder</code></a>
  948 provide streaming conversions to and from hexadecimal,
  949 analogous to equivalent functions already in
  950 <a href="/pkg/encoding/base32/">encoding/base32</a>
  951 and
  952 <a href="/pkg/encoding/base64/">encoding/base64</a>.
  953 </p>
  954 
  955 <p>
  956 When the functions
  957 <a href="/pkg/encoding/hex/#Decode"><code>Decode</code></a>
  958 and
  959 <a href="/pkg/encoding/hex/#DecodeString"><code>DecodeString</code></a>
  960 encounter malformed input,
  961 they now return the number of bytes already converted
  962 along with the error.
  963 Previously they always returned a count of 0 with any error.
  964 </p>
  965 </dl>
  966 
  967 <dl id="encoding/json"><dt><a href="/pkg/encoding/json/">encoding/json</a></dt>
  968 <dd>
  969 <p>
  970 The <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
  971 adds a new method
  972 <a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
  973 that causes it to report inputs with unknown JSON fields as a decoding error.
  974 (The default behavior has always been to discard unknown fields.)
  975 </p>
  976 
  977 <p>
  978 As a result of <a href="#reflect">fixing a reflect bug</a>,
  979 <a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a>
  980 can no longer decode into fields inside
  981 embedded pointers to unexported struct types,
  982 because it cannot initialize the unexported embedded pointer
  983 to point at fresh storage.
  984 <code>Unmarshal</code> now returns an error in this case.
  985 </p>
  986 </dl>
  987 
  988 <dl id="encoding/pem"><dt><a href="/pkg/encoding/pem/">encoding/pem</a></dt>
  989 <dd>
  990 <p>
  991 <a href="/pkg/encoding/pem/#Encode"><code>Encode</code></a>
  992 and
  993 <a href="/pkg/encoding/pem/#EncodeToMemory"><code>EncodeToMemory</code></a>
  994 no longer generate partial output when presented with a
  995 block that is impossible to encode as PEM data.
  996 </p>
  997 </dl>
  998 
  999 <dl id="encoding/xml"><dt><a href="/pkg/encoding/xml/">encoding/xml</a></dt>
 1000 <dd>
 1001 <p>
 1002 The new function
 1003 <a href="/pkg/encoding/xml/#NewTokenDecoder"><code>NewTokenDecoder</code></a>
 1004 is like
 1005 <a href="/pkg/encoding/xml/#NewDecoder"><code>NewDecoder</code></a>
 1006 but creates a decoder reading from a <a href="/pkg/encoding/xml/#TokenReader"><code>TokenReader</code></a>
 1007 instead of an XML-formatted byte stream.
 1008 This is meant to enable the construction of XML stream transformers in client libraries.
 1009 </p>
 1010 </dl>
 1011 
 1012 <dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
 1013 <dd>
 1014 <p>
 1015 The default
 1016 <a href="/pkg/flag/#Usage"><code>Usage</code></a> function now prints
 1017 its first line of output to
 1018 <code>CommandLine.Output()</code>
 1019 instead of assuming <code>os.Stderr</code>,
 1020 so that the usage message is properly redirected for
 1021 clients using <code>CommandLine.SetOutput</code>.
 1022 </p>
 1023 <p>
 1024 <a href="/pkg/flag/#PrintDefaults"><code>PrintDefaults</code></a> now
 1025 adds appropriate indentation after newlines in flag usage strings,
 1026 so that multi-line usage strings display nicely.
 1027 </p>
 1028 <p>
 1029 <a href="/pkg/flag/#FlagSet"><code>FlagSet</code></a> adds new methods
 1030 <a href="/pkg/flag/#FlagSet.ErrorHandling"><code>ErrorHandling</code></a>,
 1031 <a href="/pkg/flag/#FlagSet.Name"><code>Name</code></a>,
 1032 and
 1033 <a href="/pkg/flag/#FlagSet.Output"><code>Output</code></a>,
 1034 to retrieve the settings passed to
 1035 <a href="/pkg/flag/#NewFlagSet"><code>NewFlagSet</code></a>
 1036 and
 1037 <a href="/pkg/flag/#FlagSet.SetOutput"><code>FlagSet.SetOutput</code></a>.
 1038 </p>
 1039 </dl>
 1040 
 1041 <dl id="go/doc"><dt><a href="/pkg/go/doc/">go/doc</a></dt>
 1042 <dd>
 1043 <p>
 1044 To support the <a href="#doc">doc change</a> described above,
 1045 functions returning slices of <code>T</code>, <code>*T</code>, <code>**T</code>, and so on
 1046 are now reported in <code>T</code>'s <a href="/pkg/go/doc/#Type"><code>Type</code></a>'s <code>Funcs</code> list,
 1047 instead of in the <a href="/pkg/go/doc/#Package"><code>Package</code></a>'s <code>Funcs</code> list.
 1048 </p>
 1049 </dl>
 1050 
 1051 <dl id="go/importer"><dt><a href="/pkg/go/importer/">go/importer</a></dt>
 1052 <dd>
 1053 <p>
 1054 The <a href="/pkg/go/importer/#For"><code>For</code></a> function now accepts a non-nil lookup argument.
 1055 </p>
 1056 </dl>
 1057 
 1058 <dl id="go/printer"><dt><a href="/pkg/go/printer/">go/printer</a></dt>
 1059 <dd>
 1060 <p>
 1061 The changes to the default formatting of Go source code
 1062 discussed in the <a href="#gofmt">gofmt section</a> above
 1063 are implemented in the <a href="/pkg/go/printer/">go/printer</a> package
 1064 and also affect the output of the higher-level <a href="/pkg/go/format/">go/format</a> package.
 1065 </p>
 1066 </dl>
 1067 
 1068 <dl id="hash"><dt><a href="/pkg/hash/">hash</a></dt>
 1069 <dd>
 1070 <p>
 1071 Implementations of the <a href="/pkg/hash/#Hash"><code>Hash</code></a> interface are now
 1072 encouraged to implement <a href="/pkg/encoding/#BinaryMarshaler"><code>encoding.BinaryMarshaler</code></a>
 1073 and <a href="/pkg/encoding/#BinaryUnmarshaler"><code>encoding.BinaryUnmarshaler</code></a>
 1074 to allow saving and recreating their internal state,
 1075 and all implementations in the standard library
 1076 (<a href="/pkg/hash/crc32/">hash/crc32</a>, <a href="/pkg/crypto/sha256/">crypto/sha256</a>, and so on)
 1077 now implement those interfaces.
 1078 </p>
 1079 </dl>
 1080 
 1081 <dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt>
 1082 <dd>
 1083 <p>
 1084 The new <a href="/pkg/html/template#Srcset"><code>Srcset</code></a> content
 1085 type allows for proper handling of values within the
 1086 <a href="https://w3c.github.io/html/semantics-embedded-content.html#element-attrdef-img-srcset"><code>srcset</code></a>
 1087 attribute of <code>img</code> tags.
 1088 </p>
 1089 </dl>
 1090 
 1091 <dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
 1092 <dd>
 1093 <p>
 1094 <a href="/pkg/math/big/#Int"><code>Int</code></a> now supports conversions to and from bases 2 through 62
 1095 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.
 1096 (Previously it only allowed bases 2 through 36.)
 1097 The value of the constant <code>MaxBase</code> has been updated.
 1098 </p>
 1099 <p>
 1100 <a href="/pkg/math/big/#Int"><code>Int</code></a> adds a new
 1101 <a href="/pkg/math/big/#CmpAbs"><code>CmpAbs</code></a> method
 1102 that is like <a href="/pkg/math/big/#Cmp"><code>Cmp</code></a> but
 1103 compares only the absolute values (not the signs) of its arguments.
 1104 </p>
 1105 <p>
 1106 <a href="/pkg/math/big/#Float"><code>Float</code></a> adds a new
 1107 <a href="/pkg/math/big/#Float.Sqrt"><code>Sqrt</code></a> method to
 1108 compute square roots.
 1109 </p>
 1110 </dl>
 1111 
 1112 <dl id="math/cmplx"><dt><a href="/pkg/math/cmplx/">math/cmplx</a></dt>
 1113 <dd>
 1114 <p>
 1115 Branch cuts and other boundary cases in
 1116 <a href="/pkg/math/cmplx/#Asin"><code>Asin</code></a>,
 1117 <a href="/pkg/math/cmplx/#Asinh"><code>Asinh</code></a>,
 1118 <a href="/pkg/math/cmplx/#Atan"><code>Atan</code></a>,
 1119 and
 1120 <a href="/pkg/math/cmplx/#Sqrt"><code>Sqrt</code></a>
 1121 have been corrected to match the definitions used in the C99 standard.
 1122 </p>
 1123 </dl>
 1124 
 1125 <dl id="math/rand"><dt><a href="/pkg/math/rand/">math/rand</a></dt>
 1126 <dd>
 1127 <p>
 1128 The new <a href="/pkg/math/rand/#Shuffle"><code>Shuffle</code></a> function and corresponding
 1129 <a href="/pkg/math/rand/#Rand.Shuffle"><code>Rand.Shuffle</code></a> method
 1130 shuffle an input sequence.
 1131 </p>
 1132 </dl>
 1133 
 1134 <dl id="math"><dt><a href="/pkg/math/">math</a></dt>
 1135 <dd>
 1136 <p>
 1137 The new functions
 1138 <a href="/pkg/math/#Round"><code>Round</code></a>
 1139 and
 1140 <a href="/pkg/math/#RoundToEven"><code>RoundToEven</code></a>
 1141 round their arguments to the nearest floating-point integer;
 1142 <code>Round</code> rounds a half-integer to its larger integer neighbor (away from zero)
 1143 while <code>RoundToEven</code> rounds a half-integer to its even integer neighbor.
 1144 </p>
 1145 
 1146 <p>
 1147 The new functions
 1148 <a href="/pkg/math/#Erfinv"><code>Erfinv</code></a>
 1149 and
 1150 <a href="/pkg/math/#Erfcinv"><code>Erfcinv</code></a>
 1151 compute the inverse error function and the
 1152 inverse complementary error function.
 1153 </p>
 1154 </dl>
 1155 
 1156 <dl id="mime/multipart"><dt><a href="/pkg/mime/multipart/">mime/multipart</a></dt>
 1157 <dd>
 1158 <p>
 1159 <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a>
 1160 now accepts parts with empty filename attributes.
 1161 </p>
 1162 </dl>
 1163 
 1164 <dl id="mime"><dt><a href="/pkg/mime/">mime</a></dt>
 1165 <dd>
 1166 <p>
 1167 <a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a> now discards
 1168 invalid attribute values; previously it returned those values as empty strings.
 1169 </p>
 1170 </dl>
 1171 
 1172 <dl id="net"><dt><a href="/pkg/net/">net</a></dt>
 1173 <dd>
 1174 <p>
 1175 The <a href="/pkg/net/#Conn"><code>Conn</code></a> and
 1176 <a href="/pkg/net/#Conn"><code>Listener</code></a> implementations
 1177 in this package now guarantee that when <code>Close</code> returns,
 1178 the underlying file descriptor has been closed.
 1179 (In earlier releases, if the <code>Close</code> stopped pending I/O
 1180 in other goroutines, the closing of the file descriptor could happen in one of those
 1181 goroutines shortly after <code>Close</code> returned.)
 1182 </p>
 1183 
 1184 <p>
 1185 <a href="/pkg/net/#TCPListener"><code>TCPListener</code></a> and
 1186 <a href="/pkg/net/#UnixListener"><code>UnixListener</code></a>
 1187 now implement
 1188 <a href="/pkg/syscall/#Conn"><code>syscall.Conn</code></a>,
 1189 to allow setting options on the underlying file descriptor
 1190 using <a href="/pkg/syscall/#RawConn"><code>syscall.RawConn.Control</code></a>.
 1191 </p>
 1192 
 1193 <p>
 1194 The <code>Conn</code> implementations returned by <a href="/pkg/net/#Pipe"><code>Pipe</code></a>
 1195 now support setting read and write deadlines.
 1196 </p>
 1197 
 1198 <p>
 1199 The <a href="/pkg/net/#IPConn.ReadMsgIP"><code>IPConn.ReadMsgIP</code></a>,
 1200 <a href="/pkg/net/#IPConn.WriteMsgIP"><code>IPConn.WriteMsgIP</code></a>,
 1201 <a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>UDPConn.ReadMsgUDP</code></a>,
 1202 and
 1203 <a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>UDPConn.WriteMsgUDP</code></a>,
 1204 methods are now implemented on Windows.
 1205 </p>
 1206 </dl>
 1207 
 1208 <dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
 1209 <dd>
 1210 <p>
 1211 On the client side, an HTTP proxy (most commonly configured by
 1212 <a href="/pkg/net/http/#ProxyFromEnvironment"><code>ProxyFromEnvironment</code></a>)
 1213 can now be specified as an <code>https://</code> URL,
 1214 meaning that the client connects to the proxy over HTTPS before issuing a standard, proxied HTTP request.
 1215 (Previously, HTTP proxy URLs were required to begin with <code>http://</code> or <code>socks5://</code>.)
 1216 </p>
 1217 <p>
 1218 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>
 1219 now apply <code>If-Range</code> checks to <code>HEAD</code> requests.
 1220 <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>.
 1221 The content-serving handlers also now omit the <code>Content-Type</code> header when serving zero-length content.
 1222 </p>
 1223 <p>
 1224 <a href="/pkg/net/http/#ResponseWriter"><code>ResponseWriter</code></a>'s <code>WriteHeader</code> method now panics
 1225 if passed an invalid (non-3-digit) status code.
 1226 </p>
 1227 <p>
 1228 <!-- CL 46631 -->
 1229 The <code>Server</code> will no longer add an implicit Content-Type when a <code>Handler</code> does not write any output.
 1230 </p>
 1231 <p>
 1232 <a href="/pkg/net/http/#Redirect"><code>Redirect</code></a> now sets the <code>Content-Type</code> header before writing its HTTP response.
 1233 </p>
 1234 </dl>
 1235 
 1236 <dl id="net/mail"><dt><a href="/pkg/net/mail/">net/mail</a></dt>
 1237 <dd>
 1238 <p>
 1239 <a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
 1240 <a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>
 1241 now support a variety of obsolete address formats.
 1242 </p>
 1243 </dl>
 1244 
 1245 <dl id="net/smtp"><dt><a href="/pkg/net/smtp/">net/smtp</a></dt>
 1246 <dd>
 1247 <p>
 1248 The <a href="/pkg/net/smtp/#Client"><code>Client</code></a> adds a new
 1249 <a href="/pkg/net/smtp/#Client.Noop"><code>Noop</code></a> method,
 1250 to test whether the server is still responding.
 1251 It also now defends against possible SMTP injection in the inputs
 1252 to the <a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>
 1253 and <a href="/pkg/net/smtp/#Client.Verify"><code>Verify</code></a> methods.
 1254 </p>
 1255 </dl>
 1256 
 1257 <dl id="net/textproto"><dt><a href="/pkg/net/textproto/">net/textproto</a></dt>
 1258 <dd>
 1259 <p>
 1260 <a href="/pkg/net/textproto/#ReadMIMEHeader"><code>ReadMIMEHeader</code></a>
 1261 now rejects any header that begins with a continuation (indented) header line.
 1262 Previously a header with an indented first line was treated as if the first line
 1263 were not indented.
 1264 </p>
 1265 </dl>
 1266 
 1267 <dl id="net/url"><dt><a href="/pkg/net/url/">net/url</a></dt>
 1268 <dd>
 1269 <p>
 1270 <a href="/pkg/net/url/#ResolveReference"><code>ResolveReference</code></a>
 1271 now preserves multiple leading slashes in the target URL.
 1272 Previously it rewrote multiple leading slashes to a single slash,
 1273 which resulted in the <a href="/pkg/net/http/#Client"><code>http.Client</code></a>
 1274 following certain redirects incorrectly.
 1275 </p>
 1276 <p>
 1277 For example, this code's output has changed:
 1278 </p>
 1279 <pre>
 1280 base, _ := url.Parse("http://host//path//to/page1")
 1281 target, _ := url.Parse("page2")
 1282 fmt.Println(base.ResolveReference(target))
 1283 </pre>
 1284 <p>
 1285 Note the doubled slashes around <code>path</code>.
 1286 In Go 1.9 and earlier, the resolved URL was <code>http://host/path//to/page2</code>:
 1287 the doubled slash before <code>path</code> was incorrectly rewritten
 1288 to a single slash, while the doubled slash after <code>path</code> was
 1289 correctly preserved.
 1290 Go 1.10 preserves both doubled slashes, resolving to <code>http://host//path//to/page2</code>
 1291 as required by <a href="https://tools.ietf.org/html/rfc3986#section-5.2">RFC 3986</a>.
 1292 </p>
 1293 
 1294 <p>This change may break existing buggy programs that unintentionally
 1295 construct a base URL with a leading doubled slash in the path and inadvertently
 1296 depend on <code>ResolveReference</code> to correct that mistake.
 1297 For example, this can happen if code adds a host prefix
 1298 like <code>http://host/</code> to a path like <code>/my/api</code>,
 1299 resulting in a URL with a doubled slash: <code>http://host//my/api</code>.
 1300 </p>
 1301 
 1302 <p>
 1303 <a href="/pkg/net/url/#UserInfo"><code>UserInfo</code></a>'s methods
 1304 now treat a nil receiver as equivalent to a pointer to a zero <code>UserInfo</code>.
 1305 Previously, they panicked.
 1306 </p>
 1307 </dl>
 1308 
 1309 <dl id="os"><dt><a href="/pkg/os/">os</a></dt>
 1310 <dd>
 1311 <p>
 1312 <a href="/pkg/os/#File"><code>File</code></a> adds new methods
 1313 <a href="/pkg/os/#File.SetDeadline"><code>SetDeadline</code></a>,
 1314 <a href="/pkg/os/#File.SetReadDeadline"><code>SetReadDeadline</code></a>,
 1315 and
 1316 <a href="/pkg/os/#File.SetWriteDeadline"><code>SetWriteDeadline</code></a>
 1317 that allow setting I/O deadlines when the
 1318 underlying file descriptor supports non-blocking I/O operations.
 1319 The definition of these methods matches those in <a href="/pkg/net/#Conn"><code>net.Conn</code></a>.
 1320 If an I/O method fails due to missing a deadline, it will return a
 1321 timeout error; the
 1322 new <a href="/pkg/os/#IsTimeout"><code>IsTimeout</code></a> function
 1323 reports whether an error represents a timeout.
 1324 </p>
 1325 
 1326 <p>
 1327 Also matching <code>net.Conn</code>,
 1328 <code>File</code>'s
 1329 <a href="/pkg/os/#File.Close"><code>Close</code></a> method
 1330 now guarantee that when <code>Close</code> returns,
 1331 the underlying file descriptor has been closed.
 1332 (In earlier releases,
 1333 if the <code>Close</code> stopped pending I/O
 1334 in other goroutines, the closing of the file descriptor could happen in one of those
 1335 goroutines shortly after <code>Close</code> returned.)
 1336 </p>
 1337 
 1338 <p>
 1339 On BSD, macOS, and Solaris systems,
 1340 <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a>
 1341 now supports setting file times with nanosecond precision
 1342 (assuming the underlying file system can represent them).
 1343 </p>
 1344 </dl>
 1345 
 1346 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
 1347 <dd>
 1348 <p>
 1349 The <a href="/pkg/reflect/#Copy"><code>Copy</code></a> function now allows copying
 1350 from a string into a byte array or byte slice, to match the
 1351 <a href="/pkg/builtin/#copy">built-in copy function</a>.
 1352 </p>
 1353 
 1354 <p>
 1355 In structs, embedded pointers to unexported struct types were
 1356 previously incorrectly reported with an empty <code>PkgPath</code>
 1357 in the corresponding <a href="/pkg/reflect/#StructField">StructField</a>,
 1358 with the result that for those fields,
 1359 and <a href="/pkg/reflect/#Value.CanSet"><code>Value.CanSet</code></a>
 1360 incorrectly returned true and
 1361 <a href="/pkg/reflect/#Value.Set"><code>Value.Set</code></a>
 1362 incorrectly succeeded.
 1363 The underlying metadata has been corrected;
 1364 for those fields,
 1365 <code>CanSet</code> now correctly returns false
 1366 and <code>Set</code> now correctly panics.
 1367 This may affect reflection-based unmarshalers
 1368 that could previously unmarshal into such fields
 1369 but no longer can.
 1370 For example, see the <a href="#encoding/json"><code>encoding/json</code> notes</a>.
 1371 </p>
 1372 </dl>
 1373 
 1374 <dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt>
 1375 <dd>
 1376 <p>
 1377 As <a href="#pprof">noted above</a>, the blocking and mutex profiles
 1378 now include symbol information so that they can be viewed without needing
 1379 the binary that generated them.
 1380 </p>
 1381 </dl>
 1382 
 1383 <dl id="strconv"><dt><a href="/pkg/strconv/">strconv</a></dt>
 1384 <dd>
 1385 <p>
 1386 <a href="/pkg/strconv/#ParseUint"><code>ParseUint</code></a> now returns
 1387 the maximum magnitude integer of the appropriate size
 1388 with any <code>ErrRange</code> error, as it was already documented to do.
 1389 Previously it returned 0 with <code>ErrRange</code> errors.
 1390 </p>
 1391 </dl>
 1392 
 1393 <dl id="strings"><dt><a href="/pkg/strings/">strings</a></dt>
 1394 <dd>
 1395 <p>
 1396 A new type
 1397 <a href="/pkg/strings/#Builder"><code>Builder</code></a> is a replacement for
 1398 <a href="/pkg/bytes/#Buffer"><code>bytes.Buffer</code></a> for the use case of
 1399 accumulating text into a <code>string</code> result.
 1400 The <code>Builder</code>'s API is a restricted subset of <code>bytes.Buffer</code>'s
 1401 that allows it to safely avoid making a duplicate copy of the data
 1402 during the <a href="/pkg/strings/#Builder.String"><code>String</code></a> method.
 1403 </p>
 1404 </dl>
 1405 
 1406 <dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
 1407 <dd>
 1408 <p>
 1409 On Windows,
 1410 the new <a href="/pkg/syscall/#SysProcAttr"><code>SysProcAttr</code></a> field <code>Token</code>,
 1411 of type <a href="/pkg/syscall/#Token"><code>Token</code></a> allows the creation of a process that
 1412 runs as another user during <a href="/pkg/syscall/#StartProcess"><code>StartProcess</code></a>
 1413 (and therefore also during <a href="/pkg/os/#StartProcess"><code>os.StartProcess</code></a> and
 1414 <a href="/pkg/os/exec/#Cmd.Start"><code>exec.Cmd.Start</code></a>).
 1415 The new function <a href="/pkg/syscall/#CreateProcessAsUser"><code>CreateProcessAsUser</code></a>
 1416 gives access to the underlying system call.
 1417 </p>
 1418 
 1419 <p>
 1420 On BSD, macOS, and Solaris systems, <a href="/pkg/syscall/#UtimesNano"><code>UtimesNano</code></a>
 1421 is now implemented.
 1422 </p>
 1423 </dl>
 1424 
 1425 <dl id="time"><dt><a href="/pkg/time/">time</a></dt>
 1426 <dd>
 1427 <p>
 1428 <a href="/pkg/time/#LoadLocation"><code>LoadLocation</code></a> now uses the directory
 1429 or uncompressed zip file named by the <code>$ZONEINFO</code>
 1430 environment variable before looking in the default system-specific list of
 1431 known installation locations or in <code>$GOROOT/lib/time/zoneinfo.zip</code>.
 1432 </p>
 1433 <p>
 1434 The new function <a href="/pkg/time/#LoadLocationFromTZData"><code>LoadLocationFromTZData</code></a>
 1435 allows conversion of IANA time zone file data to a <a href="/pkg/time/#Location"><code>Location</code></a>.
 1436 </p>
 1437 </dl>
 1438 
 1439 <dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
 1440 <dd>
 1441 <p>
 1442 The <a href="/pkg/unicode/"><code>unicode</code></a> package and associated
 1443 support throughout the system has been upgraded from Unicode 9.0 to
 1444 <a href="http://www.unicode.org/versions/Unicode10.0.0/">Unicode 10.0</a>,
 1445 which adds 8,518 new characters, including four new scripts, one new property,
 1446 a Bitcoin currency symbol, and 56 new emoji.
 1447 </p>
 1448 </dl>