go1.10.html 54.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
<!--{
	"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">DRAFT RELEASE NOTES - Introduction to Go 1.10</h2>

<p><strong>
  Go 1.10 is not yet released. These are work-in-progress
  release notes. Go 1.10 is expected to be released in February 2018.
</strong></p>

<p>
The latest Go release, version 1.10, arrives six months after <a href="go1.9">go1.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>
OVERVIEW HERE
</p>

<h2 id="language">Changes to the language</h2>

<p>
There are no substantive changes to the language.
</p>

<p><!-- CL 60230 -->
A corner case involving shifts by untyped constants has been clarified,
and as a result the compilers have been updated to allow the index expression
<code>x[1.0</code>&nbsp;<code>&lt;&lt;</code>&nbsp;<code>s]</code> where <code>s</code> is an untyped constant;
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>

67 68 69 70 71
<p id="darwin">
Go 1.10 is the last release that will run on OS X 10.8 Mountain Lion.
Go 1.11 will require OS X 10.9 Mavericks or later.
</p>

72 73 74 75 76 77
<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>

78 79 80
<p id="netbsd">
Go now runs on NetBSD again, but requires the unreleased NetBSD 8.
Only <code>GOARCH=amd64</code> running on NetBSD amd64 and <code>GOARCH=386</code>
81 82
running on NetBSD i386 are known to work. 32-bit Go binaries are known to
fail on 64-bit NetBSD kernels. <code>GOARCH=arm</code> is untested.
83 84 85 86 87 88 89
</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>

90 91 92 93 94 95 96
<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>

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
<h2 id="tools">Tools</h2>

<h3 id="goroot">Default GOROOT &amp; GOTMPDIR</h3>

<p>
TODO: default GOROOT changes in cmd/go
TODO: computed GOROOT change
</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 &amp; Install</h3>

<p>
The <code>go</code>&nbsp;<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>&nbsp;<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>.
Russ Cox's avatar
Russ Cox committed
137
For more details, see <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go</code> <code>help</code> <code>build</code></a>.
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
</p>

<p>
The <code>go</code>&nbsp;<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="TODO"><code>go</code> <code>help</code> <code>cache</code></a>.
</p>

<p>
153
The <code>go</code>&nbsp;<code>install</code> command now installs only the
154 155 156 157 158 159 160
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.
161 162
Installing dependency packages should not be necessary in general,
and the very concept of installed packages may disappear in a future release.
163 164 165 166 167 168 169 170
</p>

<p>
Many details of the <code>go</code>&nbsp;<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.
Russ Cox's avatar
Russ Cox committed
171
For more details, see <a href="/cmd/go/#hdr-File_types"><code>go</code> <code>help</code> <code>filetype</code></a>.
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
</p>

<h3 id="test">Test</h3>

<p>
The <code>go</code>&nbsp;<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>
The <code>go</code>&nbsp;<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>&nbsp;<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>&nbsp;<code>test</code> <code>-v</code> output
now includes <code>PAUSE</code> and <code>CONT</code> status update
228
lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
229 230
</p>

231 232 233 234 235 236
<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>

237 238 239 240 241
<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.
242
This allows the creation of rich presentations of test execution
243 244 245 246 247 248
in IDEs and other tools.
</p>


<p>
For more details about all these changes,
249
see <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>help</code> <code>test</code></a>
250 251 252 253 254 255 256 257 258 259 260 261 262
and the <a href="/cmd/test2json/">test2json documentation</a>.
</p>

<h3 id="cgo">Cgo</h3>

<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>

263 264 265 266 267 268
<p>
TODO: CL 70890 "permit passing string values directly between Go and C."
<br>
TODO: CL 66332 "special case C ptr types to use uintptr."
</p>

269 270 271 272 273 274 275 276 277 278 279
<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 refer to the <code>CC</code> environment
variable or else the built-in default.
280 281 282
</p>

<p>
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
For more details, see the <a href="/cmd/cgo/">cgo documentation</a>.
</p>

<h3 id="doc">Doc</h3>

<p>
The <code>go</code>&nbsp;<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>&nbsp;<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>&nbsp;<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>&nbsp;<code>tool</code>&nbsp;<code>pprof</code></a> profile visualizer has been updated to
340 341
the latest version from <a href="https://github.com/google/pprof">github.com/google/pprof</a>,
which includes an updated web interface.
342 343 344 345 346
</p>

<h3 id="vet">Vet</h3>

<p>
347
The <a href="/cmd/vet/"><code>go</code>&nbsp;<code>vet</code></a> command now always has access to
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365
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>&nbsp;<code>vet</code> has access to this information;
the more low-level <code>go</code>&nbsp;<code>tool</code>&nbsp;<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>&nbsp;<code>vet</code> provides access to all the same flags as
<code>go</code>&nbsp;<code>tool</code>&nbsp;<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>
366 367
Two minor details of the default formatting of Go source code have changed.
First, certain complex three-index slice expressions previously formatted like
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
<code>x[i+1</code>&nbsp;<code>:</code>&nbsp;<code>j:k]</code> and now
format with more consistent spacing: <code>x[i+1</code>&nbsp;<code>:</code>&nbsp;<code>j</code>&nbsp;<code>:</code>&nbsp;<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, we arrange for goimports and
our Git pre-commit hook to agree about source code formatting by having both
invoke the gofmt binary found in the current path.
TODO: Make goimports actually do that. #22695.
As another example, inside Google we arrange that source code presubmit
checks run a gofmt binary maintained at a fixed path in a shared, distributed file system;
that on engineering workstations <code>/usr/bin/gofmt</code>
is a symbolic link to that same path;
and that all editor integrations used for Google development
explicitly invoke /usr/bin/gofmt.
TODO: TMI?
</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>
407 408 409 410
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.
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509
</p>

<p>
The various <a href="https://docs.google.com/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit">build modes</a>
has 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>.
</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>
510 511
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.
512 513 514 515 516 517 518 519 520 521 522 523 524 525
The assembler also no longer implements <code><small>MOVL</small></code>&nbsp;<code><small>$0,</small></code>&nbsp;<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>
TODO: Words about GCC 8 and Go 1.10.
</p>

<h2 id="runtime">Runtime</h2>

<p>
526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546
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 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.
547 548 549 550 551
</p>

<p>
Stack traces no longer include implicit wrapper functions (previously marked <code>&lt;autogenerated&gt;</code>),
unless a fault or panic happens in the wrapper itself.
552 553 554
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.
555 556 557 558 559 560 561
</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>

Russ Cox's avatar
Russ Cox committed
562 563 564 565
<p>
TODO: Anything about CL 59970: "runtime: separate soft and hard heap limits"?
</p>

566 567 568 569 570 571 572 573 574 575 576 577
<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>
578
Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active.
579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614
</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
615
that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
616 617 618
The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads.
</p>
<p>
619 620 621
<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.
622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647
</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
648 649 650
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.
651 652 653
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.
654 655 656 657 658 659 660 661 662 663 664 665 666 667 668
</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>
669 670
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.
671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736
</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>
each already returned slices pointing into the same underlying array as its input.
Go 1.10 changes each of the returned subslices to have capacity equal to its length,
so that appending to a subslice will not 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>
Leaf certificate validation 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.
TODO: Link to docs that may not exist yet.
</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>.
</p>

737 738 739 740 741 742
<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>

743 744
<p>
The new <a href="/pkg/crypto/x509/#MarshalPKCS8PrivateKey"><code>MarshalPKCS8PrivateKey</code></a>
745 746 747
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.)
748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
</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 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>
770 771 772 773 774 775 776 777
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>
778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811
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
812
and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838
<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>
839 840 841 842 843
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>
844 845 846 847
<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>
848 849 850 851
<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>
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
</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,
888
they now return the number of bytes already converted
889 890 891 892 893 894 895 896 897 898
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
899
<a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
900 901 902
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>
Russ Cox's avatar
Russ Cox committed
903 904 905 906 907 908 909 910 911 912

<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>
913 914
</dl>

915 916 917 918 919 920 921 922 923 924 925
<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>

926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040
<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 actions <code>{{"{{break}}"}}</code> and <code>{{"{{continue}}"}}</code>
break out of the innermost <code>{{"{{range"}}</code>&nbsp;...<code>}}</code> loop,
like the corresponding Go statements.
</p>
<p>
TODO: something about the AddParseTree problem (#21844).
</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>

1041 1042 1043 1044
<dl id="math/cmplx"><dt><a href="/pkg/math/cmplx/">math/cmplx</a></dt>
<dd>
<p>
Branch cuts and other boundary cases in
1045 1046 1047
<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>,
1048
and
1049
<a href="/pkg/math/cmplx/#Sqrt"><code>Sqrt</code></a>
1050 1051 1052 1053
have been corrected to match the definitions used in the C99 standard.
</p>
</dl>

1054 1055 1056
<dl id="math/rand"><dt><a href="/pkg/math/rand/">math/rand</a></dt>
<dd>
<p>
1057
The new <a href="/pkg/math/rand/#Shuffle"><code>Shuffle</code></a> function and corresponding
1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
<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>
1070
round their arguments to the nearest floating-point integer;
1071
<code>Round</code> rounds a half-integer to its larger integer neighbor (away from zero)
1072
while <code>RoundToEven</code> rounds a half-integer to its even integer neighbor.
1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149
</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>.
1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163
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>
<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/http/httputil"><dt><a href="/pkg/net/http/httputil/">net/http/httputil</a></dt>
<dd>
<p>
1164
TODO: ReverseProxy and back end errors and ModifyResponse.
1165 1166 1167 1168 1169 1170 1171
</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
1172
<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>
1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192
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>
1193 1194 1195
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.
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232
</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 preseves 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>
1233 1234 1235 1236 1237 1238

<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>
1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280
</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>.
</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, like for <code>net.Conn</code>'s,
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>
1281 1282

<p>
Russ Cox's avatar
Russ Cox committed
1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299
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
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>
1300
</p>
1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371
</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="text/template"><dt><a href="/pkg/text/template/">text/template</a></dt>
<dd>
<p>
The new actions <code>{{"{{break}}"}}</code> and <code>{{"{{continue}}"}}</code>
break out of the innermost <code>{{"{{range"}}</code>&nbsp;...<code>}}</code> loop,
like the corresponding Go statements.
</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>
1372 1373
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>.
1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386
</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 version 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>