## [LAPACK functions](#man-linalg-lapack-functions)
Finds the eigensystem of `A` with matrix balancing. If `jobvl = N`, the left eigenvectors of `A` aren't computed. If `jobvr = N`, the right eigenvectors of `A` aren't computed. If `jobvl = V` or `jobvr = V`, the corresponding eigenvectors are computed. If `balanc = N`, no balancing is performed. If `balanc = P`, `A` is permuted but not scaled. If `balanc = S`, `A` is scaled but not permuted. If `balanc = B`, `A` is permuted and scaled. If `sense = N`, no reciprocal condition numbers are computed. If `sense = E`, reciprocal condition numbers are computed for the eigenvalues only. If `sense = V`, reciprocal condition numbers are computed for the right eigenvectors only. If `sense = B`, reciprocal condition numbers are computed for the right eigenvectors and the eigenvectors. If `sense = E,B`, the right and left eigenvectors must be computed.
```julia
ggev!(jobvl, jobvr, A, B) -> (alpha, beta, vl, vr)
```
Finds the generalized eigendecomposition of `A` and `B`. If `jobvl = N`, the left eigenvectors aren't computed. If `jobvr = N`, the right eigenvectors aren't computed. If `jobvl = V` or `jobvr = V`, the corresponding eigenvectors are computed.
```julia
ggev3!(jobvl, jobvr, A, B) -> (alpha, beta, vl, vr)
```
Finds the generalized eigendecomposition of `A` and `B` using a blocked algorithm. If `jobvl = N`, the left eigenvectors aren't computed. If `jobvr = N`, the right eigenvectors aren't computed. If `jobvl = V` or `jobvr = V`, the corresponding eigenvectors are computed. This function requires LAPACK 3.6.0.


## [LAPACK functions](#man-linalg-lapack-functions)
```julia
gtsv!(dl, d, du, B)
```
Solves the equation `A * X = B` where `A` is a tridiagonal matrix with `dl` on the subdiagonal, `d` on the diagonal, and `du` on the superdiagonal.
Overwrites `B` with the solution `X` and returns it.
```julia
gttrf!(dl, d, du) -> (dl, d, du, du2, ipiv)
```
Finds the `LU` factorization of a tridiagonal matrix with `dl` on the subdiagonal, `d` on the diagonal, and `du` on the superdiagonal.
Modifies `dl`, `d`, and `du` in-place and returns them and the second superdiagonal `du2` and the pivoting vector `ipiv`.
```julia
gttrs!(trans, dl, d, du, du2, ipiv, B)
```
Solves the equation `A * X = B` (`trans = N`), `transpose(A) * X = B` (`trans = T`), or `adjoint(A) * X = B` (`trans = C`) using the `LU` factorization computed by `gttrf!`. `B` is overwritten with the solution `X`.
```julia
orglq!(A, tau, k = length(tau))
```
Explicitly finds the matrix `Q` of a `LQ` factorization after calling `gelqf!` on `A`. Uses the output of `gelqf!`. `A` is overwritten by `Q`.
```julia
orgqr!(A, tau, k = length(tau))
```
Explicitly finds the matrix `Q` of a `QR` factorization after calling `geqrf!` on `A`. Uses the output of `geqrf!`. `A` is overwritten by `Q`.
```julia
orgql!(A, tau, k = length(tau))
```
Explicitly finds the matrix `Q` of a `QL` factorization after calling `geqlf!` on `A`. Uses the output of `geqlf!`. `A` is overwritten by `Q`.
```julia
orgrq!(A, tau, k = length(tau))
```


## [LAPACK functions](#man-linalg-lapack-functions)
Explicitly finds the matrix `Q` of a `RQ` factorization after calling `gerqf!` on `A`. Uses the output of `gerqf!`. `A` is overwritten by `Q`.
```julia
ormlq!(side, trans, A, tau, C)
```
Computes `Q * C` (`trans = N`), `transpose(Q) * C` (`trans = T`), `adjoint(Q) * C` (`trans = C`) for `side = L` or the equivalent right-sided multiplication for `side = R` using `Q` from a `LQ` factorization of `A` computed using `gelqf!`. `C` is overwritten.
```julia
ormqr!(side, trans, A, tau, C)
```
Computes `Q * C` (`trans = N`), `transpose(Q) * C` (`trans = T`), `adjoint(Q) * C` (`trans = C`) for `side = L` or the equivalent right-sided multiplication for `side = R` using `Q` from a `QR` factorization of `A` computed using `geqrf!`. `C` is overwritten.
```julia
ormql!(side, trans, A, tau, C)
```
Computes `Q * C` (`trans = N`), `transpose(Q) * C` (`trans = T`), `adjoint(Q) * C` (`trans = C`) for `side = L` or the equivalent right-sided multiplication for `side = R` using `Q` from a `QL` factorization of `A` computed using `geqlf!`. `C` is overwritten.
```julia
ormrq!(side, trans, A, tau, C)
```
Computes `Q * C` (`trans = N`), `transpose(Q) * C` (`trans = T`), `adjoint(Q) * C` (`trans = C`) for `side = L` or the equivalent right-sided multiplication for `side = R` using `Q` from a `RQ` factorization of `A` computed using `gerqf!`. `C` is overwritten.
```julia
gemqrt!(side, trans, V, T, C)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Computes `Q * C` (`trans = N`), `transpose(Q) * C` (`trans = T`), `adjoint(Q) * C` (`trans = C`) for `side = L` or the equivalent right-sided multiplication for `side = R` using `Q` from a `QR` factorization of `A` computed using `geqrt!`. `C` is overwritten.
```julia
posv!(uplo, A, B) -> (A, B)
```
Finds the solution to `A * X = B` where `A` is a symmetric or Hermitian positive definite matrix. If `uplo = U` the upper Cholesky decomposition of `A` is computed. If `uplo = L` the lower Cholesky decomposition of `A` is computed. `A` is overwritten by its Cholesky decomposition. `B` is overwritten with the solution `X`.
```julia
potrf!(uplo, A)
```
Computes the Cholesky (upper if `uplo = U`, lower if `uplo = L`) decomposition of positive-definite matrix `A`. `A` is overwritten and returned with an info code.
```julia
potri!(uplo, A)
```
Computes the inverse of positive-definite matrix `A` after calling `potrf!` to find its (upper if `uplo = U`, lower if `uplo = L`) Cholesky decomposition.
`A` is overwritten by its inverse and returned.
```julia
potrs!(uplo, A, B)
```
Finds the solution to `A * X = B` where `A` is a symmetric or Hermitian positive definite matrix whose Cholesky decomposition was computed by `potrf!`. If `uplo = U` the upper Cholesky decomposition of `A` was computed. If `uplo = L` the lower Cholesky decomposition of `A` was computed. `B` is overwritten with the solution `X`.
```julia
pstrf!(uplo, A, tol) -> (A, piv, rank, info)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Computes the (upper if `uplo = U`, lower if `uplo = L`) pivoted Cholesky decomposition of positive-definite matrix `A` with a user-set tolerance `tol`. `A` is overwritten by its Cholesky decomposition.
Returns `A`, the pivots `piv`, the rank of `A`, and an `info` code. If `info = 0`, the factorization succeeded. If `info = i > 0`, then `A` is indefinite or rank-deficient.
```julia
ptsv!(D, E, B)
```
Solves `A * X = B` for positive-definite tridiagonal `A`. `D` is the diagonal of `A` and `E` is the off-diagonal. `B` is overwritten with the solution `X` and returned.
```julia
pttrf!(D, E)
```
Computes the LDLt factorization of a positive-definite tridiagonal matrix with `D` as diagonal and `E` as off-diagonal. `D` and `E` are overwritten and returned.
```julia
pttrs!(D, E, B)
```
Solves `A * X = B` for positive-definite tridiagonal `A` with diagonal `D` and off-diagonal `E` after computing `A`'s LDLt factorization using `pttrf!`. `B` is overwritten with the solution `X`.
```julia
trtri!(uplo, diag, A)
```
Finds the inverse of (upper if `uplo = U`, lower if `uplo = L`) triangular matrix `A`. If `diag = N`, `A` has non-unit diagonal elements. If `diag = U`, all diagonal elements of `A` are one. `A` is overwritten with its inverse.
```julia
trtrs!(uplo, trans, diag, A, B)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Solves `A * X = B` (`trans = N`), `transpose(A) * X = B` (`trans = T`), or `adjoint(A) * X = B` (`trans = C`) for (upper if `uplo = U`, lower if `uplo = L`) triangular matrix `A`. If `diag = N`, `A` has non-unit diagonal elements. If `diag = U`, all diagonal elements of `A` are one. `B` is overwritten with the solution `X`.
```julia
trcon!(norm, uplo, diag, A)
```
Finds the reciprocal condition number of (upper if `uplo = U`, lower if `uplo = L`) triangular matrix `A`. If `diag = N`, `A` has non-unit diagonal elements. If `diag = U`, all diagonal elements of `A` are one. If `norm = I`, the condition number is found in the infinity norm. If `norm = O` or `1`, the condition number is found in the one norm.
```julia
trevc!(side, howmny, select, T, VL = similar(T), VR = similar(T))
```
Finds the eigensystem of an upper triangular matrix `T`. If `side = R`, the right eigenvectors are computed. If `side = L`, the left eigenvectors are computed. If `side = B`, both sets are computed. If `howmny = A`, all eigenvectors are found. If `howmny = B`, all eigenvectors are found and backtransformed using `VL` and `VR`. If `howmny = S`, only the eigenvectors corresponding to the values in `select` are computed.
```julia
trrfs!(uplo, trans, diag, A, B, X, Ferr, Berr) -> (Ferr, Berr)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Estimates the error in the solution to `A * X = B` (`trans = N`), `transpose(A) * X = B` (`trans = T`), `adjoint(A) * X = B` (`trans = C`) for `side = L`, or the equivalent equations a right-handed `side = R` `X * A` after computing `X` using `trtrs!`. If `uplo = U`, `A` is upper triangular. If `uplo = L`, `A` is lower triangular. If `diag = N`, `A` has non-unit diagonal elements. If `diag = U`, all diagonal elements of `A` are one. `Ferr` and `Berr` are optional inputs. `Ferr` is the forward error and `Berr` is the backward error, each component-wise.
```julia
stev!(job, dv, ev) -> (dv, Zmat)
```
Computes the eigensystem for a symmetric tridiagonal matrix with `dv` as diagonal and `ev` as off-diagonal. If `job = N` only the eigenvalues are found and returned in `dv`. If `job = V` then the eigenvectors are also found and returned in `Zmat`.
```julia
stebz!(range, order, vl, vu, il, iu, abstol, dv, ev) -> (dv, iblock, isplit)
```
Computes the eigenvalues for a symmetric tridiagonal matrix with `dv` as diagonal and `ev` as off-diagonal. If `range = A`, all the eigenvalues are found. If `range = V`, the eigenvalues in the half-open interval `(vl, vu]` are found. If `range = I`, the eigenvalues with indices between `il` and `iu` are found. If `order = B`, eigvalues are ordered within a block. If `order = E`, they are ordered across all the blocks. `abstol` can be set as a tolerance for convergence.
```julia
stegr!(jobz, range, dv, ev, vl, vu, il, iu) -> (w, Z)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Computes the eigenvalues (`jobz = N`) or eigenvalues and eigenvectors (`jobz = V`) for a symmetric tridiagonal matrix with `dv` as diagonal and `ev` as off-diagonal. If `range = A`, all the eigenvalues are found. If `range = V`, the eigenvalues in the half-open interval `(vl, vu]` are found. If `range = I`, the eigenvalues with indices between `il` and `iu` are found. The eigenvalues are returned in `w` and the eigenvectors in `Z`.
```julia
stein!(dv, ev_in, w_in, iblock_in, isplit_in)
```
Computes the eigenvectors for a symmetric tridiagonal matrix with `dv` as diagonal and `ev_in` as off-diagonal. `w_in` specifies the input eigenvalues for which to find corresponding eigenvectors. `iblock_in` specifies the submatrices corresponding to the eigenvalues in `w_in`. `isplit_in` specifies the splitting points between the submatrix blocks.
```julia
syconv!(uplo, A, ipiv) -> (A, work)
```
Converts a symmetric matrix `A` (which has been factorized into a triangular matrix) into two matrices `L` and `D`. If `uplo = U`, `A` is upper triangular. If `uplo = L`, it is lower triangular. `ipiv` is the pivot vector from the triangular factorization. `A` is overwritten by `L` and `D`.
```julia
sysv!(uplo, A, B) -> (B, A, ipiv)
```
Finds the solution to `A * X = B` for symmetric matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `B` is overwritten by the solution `X`. `A` is overwritten by its Bunch-Kaufman factorization. `ipiv` contains pivoting information about the factorization.


## [LAPACK functions](#man-linalg-lapack-functions)
```julia
sytrf!(uplo, A) -> (A, ipiv, info)
```
Computes the Bunch-Kaufman factorization of a symmetric matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored.
Returns `A`, overwritten by the factorization, a pivot vector `ipiv`, and the error code `info` which is a non-negative integer. If `info` is positive the matrix is singular and the diagonal part of the factorization is exactly zero at position `info`.
```julia
sytrf!(uplo, A, ipiv) -> (A, ipiv, info)
```
Computes the Bunch-Kaufman factorization of a symmetric matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored.
Returns `A`, overwritten by the factorization, the pivot vector `ipiv`, and the error code `info` which is a non-negative integer. If `info` is positive the matrix is singular and the diagonal part of the factorization is exactly zero at position `info`.
```julia
sytri!(uplo, A, ipiv)
```
Computes the inverse of a symmetric matrix `A` using the results of `sytrf!`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `A` is overwritten by its inverse.
```julia
sytrs!(uplo, A, ipiv, B)
```
Solves the equation `A * X = B` for a symmetric matrix `A` using the results of `sytrf!`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `B` is overwritten by the solution `X`.
```julia
hesv!(uplo, A, B) -> (B, A, ipiv)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Finds the solution to `A * X = B` for Hermitian matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `B` is overwritten by the solution `X`. `A` is overwritten by its Bunch-Kaufman factorization. `ipiv` contains pivoting information about the factorization.
```julia
hetrf!(uplo, A) -> (A, ipiv, info)
```
Computes the Bunch-Kaufman factorization of a Hermitian matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored.
Returns `A`, overwritten by the factorization, a pivot vector `ipiv`, and the error code `info` which is a non-negative integer. If `info` is positive the matrix is singular and the diagonal part of the factorization is exactly zero at position `info`.
```julia
hetrf!(uplo, A, ipiv) -> (A, ipiv, info)
```
Computes the Bunch-Kaufman factorization of a Hermitian matrix `A`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored.
Returns `A`, overwritten by the factorization, the pivot vector `ipiv`, and the error code `info` which is a non-negative integer. If `info` is positive the matrix is singular and the diagonal part of the factorization is exactly zero at position `info`.
```julia
hetri!(uplo, A, ipiv)
```
Computes the inverse of a Hermitian matrix `A` using the results of `sytrf!`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `A` is overwritten by its inverse.
```julia
hetrs!(uplo, A, ipiv, B)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Solves the equation `A * X = B` for a Hermitian matrix `A` using the results of `sytrf!`. If `uplo = U`, the upper half of `A` is stored. If `uplo = L`, the lower half is stored. `B` is overwritten by the solution `X`.
```julia
syev!(jobz, uplo, A)
```
Finds the eigenvalues (`jobz = N`) or eigenvalues and eigenvectors (`jobz = V`) of a symmetric matrix `A`. If `uplo = U`, the upper triangle of `A` is used. If `uplo = L`, the lower triangle of `A` is used.
```julia
syevr!(jobz, range, uplo, A, vl, vu, il, iu, abstol) -> (W, Z)
```
Finds the eigenvalues (`jobz = N`) or eigenvalues and eigenvectors (`jobz = V`) of a symmetric matrix `A`. If `uplo = U`, the upper triangle of `A` is used. If `uplo = L`, the lower triangle of `A` is used. If `range = A`, all the eigenvalues are found. If `range = V`, the eigenvalues in the half-open interval `(vl, vu]` are found. If `range = I`, the eigenvalues with indices between `il` and `iu` are found. `abstol` can be set as a tolerance for convergence.
The eigenvalues are returned in `W` and the eigenvectors in `Z`.
```julia
syevd!(jobz, uplo, A)
```
Finds the eigenvalues (`jobz = N`) or eigenvalues and eigenvectors (`jobz = V`) of a symmetric matrix `A`. If `uplo = U`, the upper triangle of `A` is used. If `uplo = L`, the lower triangle of `A` is used.


## [LAPACK functions](#man-linalg-lapack-functions)
Use the divide-and-conquer method, instead of the QR iteration used by `syev!` or multiple relatively robust representations used by `syevr!`. See James W. Demmel et al, SIAM J. Sci. Comput. 30, 3, 1508 (2008) for a comparison of the accuracy and performatce of different methods.
```julia
sygvd!(itype, jobz, uplo, A, B) -> (w, A, B)
```
Finds the generalized eigenvalues (`jobz = N`) or eigenvalues and eigenvectors (`jobz = V`) of a symmetric matrix `A` and symmetric positive-definite matrix `B`. If `uplo = U`, the upper triangles of `A` and `B` are used. If `uplo = L`, the lower triangles of `A` and `B` are used. If `itype = 1`, the problem to solve is `A * x = lambda * B * x`. If `itype = 2`, the problem to solve is `A * B * x = lambda * x`. If `itype = 3`, the problem to solve is `B * A * x = lambda * x`.
```julia
bdsqr!(uplo, d, e_, Vt, U, C) -> (d, Vt, U, C)
```
Computes the singular value decomposition of a bidiagonal matrix with `d` on the diagonal and `e_` on the off-diagonal. If `uplo = U`, `e_` is the superdiagonal. If `uplo = L`, `e_` is the subdiagonal. Can optionally also compute the product `Q' * C`.
Returns the singular values in `d`, and the matrix `C` overwritten with `Q' * C`.
```julia
bdsdc!(uplo, compq, d, e_) -> (d, e, u, vt, q, iq)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Computes the singular value decomposition of a bidiagonal matrix with `d` on the diagonal and `e_` on the off-diagonal using a divide and conqueq method. If `uplo = U`, `e_` is the superdiagonal. If `uplo = L`, `e_` is the subdiagonal. If `compq = N`, only the singular values are found. If `compq = I`, the singular values and vectors are found. If `compq = P`, the singular values and vectors are found in compact form. Only works for real types.
Returns the singular values in `d`, and if `compq = P`, the compact singular vectors in `iq`.
```julia
gecon!(normtype, A, anorm)
```
Finds the reciprocal condition number of matrix `A`. If `normtype = I`, the condition number is found in the infinity norm. If `normtype = O` or `1`, the condition number is found in the one norm. `A` must be the result of `getrf!` and `anorm` is the norm of `A` in the relevant norm.
```julia
gehrd!(ilo, ihi, A) -> (A, tau)
```
Converts a matrix `A` to Hessenberg form. If `A` is balanced with `gebal!` then `ilo` and `ihi` are the outputs of `gebal!`. Otherwise they should be `ilo = 1` and `ihi = size(A,2)`. `tau` contains the elementary reflectors of the factorization.
```julia
orghr!(ilo, ihi, A, tau)
```
Explicitly finds `Q`, the orthogonal/unitary matrix from `gehrd!`. `ilo`, `ihi`, `A`, and `tau` must correspond to the input/output to `gehrd!`.
```julia
gees!(jobvs, A) -> (A, vs, w)
```
Computes the eigenvalues (`jobvs = N`) or the eigenvalues and Schur vectors (`jobvs = V`) of matrix `A`. `A` is overwritten by its Schur form.


## [LAPACK functions](#man-linalg-lapack-functions)
Returns `A`, `vs` containing the Schur vectors, and `w`, containing the eigenvalues.
```julia
gges!(jobvsl, jobvsr, A, B) -> (A, B, alpha, beta, vsl, vsr)
```
Computes the generalized eigenvalues, generalized Schur form, left Schur vectors (`jobsvl = V`), or right Schur vectors (`jobvsr = V`) of `A` and `B`.
The generalized eigenvalues are returned in `alpha` and `beta`. The left Schur vectors are returned in `vsl` and the right Schur vectors are returned in `vsr`.
```julia
gges3!(jobvsl, jobvsr, A, B) -> (A, B, alpha, beta, vsl, vsr)
```
Computes the generalized eigenvalues, generalized Schur form, left Schur vectors (`jobsvl = V`), or right Schur vectors (`jobvsr = V`) of `A` and `B` using a blocked algorithm. This function requires LAPACK 3.6.0.
The generalized eigenvalues are returned in `alpha` and `beta`. The left Schur vectors are returned in `vsl` and the right Schur vectors are returned in `vsr`.
```julia
trexc!(compq, ifst, ilst, T, Q) -> (T, Q)
trexc!(ifst, ilst, T, Q) -> (T, Q)
```
Reorder the Schur factorization `T` of a matrix, such that the diagonal block of `T` with row index `ifst` is moved to row index `ilst`. If `compq = V`, the Schur vectors `Q` are reordered. If `compq = N` they are not modified. The 4-arg method calls the 5-arg method with `compq = V`.
```julia
trsen!(job, compq, select, T, Q) -> (T, Q, w, s, sep)
trsen!(select, T, Q) -> (T, Q, w, s, sep)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Reorder the Schur factorization of a matrix and optionally finds reciprocal condition numbers. If `job = N`, no condition numbers are found. If `job = E`, only the condition number for this cluster of eigenvalues is found. If `job = V`, only the condition number for the invariant subspace is found. If `job = B` then the condition numbers for the cluster and subspace are found. If `compq = V` the Schur vectors `Q` are updated. If `compq = N` the Schur vectors are not modified. `select` determines which eigenvalues are in the cluster. The 3-arg method calls the 5-arg method with `job = N` and `compq = V`.
Returns `T`, `Q`, reordered eigenvalues in `w`, the condition number of the cluster of eigenvalues `s`, and the condition number of the invariant subspace `sep`.
```julia
tgsen!(select, S, T, Q, Z) -> (S, T, alpha, beta, Q, Z)
```
Reorders the vectors of a generalized Schur decomposition. `select` specifies the eigenvalues in each cluster.
```julia
trsyl!(transa, transb, A, B, C, isgn=1) -> (C, scale)
```
Solves the Sylvester matrix equation `A * X +/- X * B = scale*C` where `A` and `B` are both quasi-upper triangular. If `transa = N`, `A` is not modified. If `transa = T`, `A` is transposed. If `transa = C`, `A` is conjugate transposed. Similarly for `transb` and `B`. If `isgn = 1`, the equation `A * X + X * B = scale * C` is solved. If `isgn = -1`, the equation `A * X - X * B = scale * C` is solved.
Returns `X` (overwriting `C`) and `scale`.
```julia
hseqr!(job, compz, ilo, ihi, H, Z) -> (H, Z, w)
```


## [LAPACK functions](#man-linalg-lapack-functions)
Computes all eigenvalues and (optionally) the Schur factorization of a matrix reduced to Hessenberg form. If `H` is balanced with `gebal!` then `ilo` and `ihi` are the outputs of `gebal!`. Otherwise they should be `ilo = 1` and `ihi = size(H,2)`. `tau` contains the elementary reflectors of the factorization.
-   [ACM832](#citeref-ACM832)Davis, Timothy A. (2004b). Algorithm 832: UMFPACK V4.3–-an Unsymmetric-Pattern Multifrontal Method. ACM Trans. Math. Softw., 30(2), 196–199. [doi:10.1145/992200.992206](https://doi.org/10.1145/992200.992206)
-   [ACM887](#citeref-ACM887)Chen, Y., Davis, T. A., Hager, W. W., & Rajamanickam, S. (2008). Algorithm 887: CHOLMOD, Supernodal Sparse Cholesky Factorization and Update/Downdate. ACM Trans. Math. Softw., 35(3). [doi:10.1145/1391989.1391995](https://doi.org/10.1145/1391989.1391995)
-   [DavisHager2009](#citeref-DavisHager2009)Davis, Timothy A., & Hager, W. W. (2009). Dynamic Supernodes in Sparse Cholesky Update/Downdate and Triangular Solves. ACM Trans. Math. Softw., 35(4). [doi:10.1145/1462173.1462176](https://doi.org/10.1145/1462173.1462176)
-   [Bischof1987](#citeref-Bischof1987)C Bischof and C Van Loan, "The WY representation for products of Householder matrices", SIAM J Sci Stat Comput 8 (1987), s2-s13. [doi:10.1137/0908009](https://doi.org/10.1137/0908009)


## [LAPACK functions](#man-linalg-lapack-functions)
-   [Schreiber1989](#citeref-Schreiber1989)R Schreiber and C Van Loan, "A storage-efficient WY representation for products of Householder transformations", SIAM J Sci Stat Comput 10 (1989), 53-57. [doi:10.1137/0910005](https://doi.org/10.1137/0910005)
-   [ACM933](#citeref-ACM933)Foster, L. V., & Davis, T. A. (2013). Algorithm 933: Reliable Calculation of Numerical Rank, Null Space Bases, Pseudoinverse Solutions, and Basic Solutions Using SuitesparseQR. ACM Trans. Math. Softw., 40(1). [doi:10.1145/2513109.2513116](https://doi.org/10.1145/2513109.2513116)
-   [Bunch1977](#citeref-Bunch1977)J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. [url](https://www.ams.org/journals/mcom/1977-31-137/S0025-5718-1977-0428694-0/).
-   [issue8859](#citeref-issue8859)Issue 8859, "Fix least squares", <https://github.com/JuliaLang/julia/pull/8859>
-   [B96](#citeref-B96)Åke Björck, "Numerical Methods for Least Squares Problems", SIAM Press, Philadelphia, 1996, "Other Titles in Applied Mathematics", Vol. 51. [doi:10.1137/1.9781611971484](http://epubs.siam.org/doi/book/10.1137/1.9781611971484)
-   [S84](#citeref-S84)G. W. Stewart, "Rank Degeneracy", SIAM Journal on Scientific and Statistical Computing, 5(2), 1984, 403-413. [doi:10.1137/0905030](http://epubs.siam.org/doi/abs/10.1137/0905030)


## [LAPACK functions](#man-linalg-lapack-functions)
-   [KY88](#citeref-KY88)Konstantinos Konstantinides and Kung Yao, "Statistical analysis of effective singular values in matrix rank determination", IEEE Transactions on Acoustics, Speech and Signal Processing, 36(5), 1988, 757-763. [doi:10.1109/29.1585](https://doi.org/10.1109/29.1585)
-   [H05](#citeref-H05)Nicholas J. Higham, "The squaring and scaling method for the matrix exponential revisited", SIAM Journal on Matrix Analysis and Applications, 26(4), 2005, 1179-1193. [doi:10.1137/090768539](https://doi.org/10.1137/090768539)
-   [AH12](#citeref-AH12)Awad H. Al-Mohy and Nicholas J. Higham, "Improved inverse scaling and squaring algorithms for the matrix logarithm", SIAM Journal on Scientific Computing, 34(4), 2012, C153-C169. [doi:10.1137/110852553](https://doi.org/10.1137/110852553)
-   [AHR13](#citeref-AHR13)Awad H. Al-Mohy, Nicholas J. Higham and Samuel D. Relton, "Computing the Fréchet derivative of the matrix logarithm and estimating the condition number", SIAM Journal on Scientific Computing, 35(4), 2013, C394-C410. [doi:10.1137/120885991](https://doi.org/10.1137/120885991)
-   [BH83](#citeref-BH83)Åke Björck and Sven Hammarling, "A Schur method for the square root of a matrix", Linear Algebra and its Applications, 52-53, 1983, 127-140. [doi:10.1016/0024-3795(83)80010-X](https://doi.org/10.1016/0024-3795(83)80010-X)


## [LAPACK functions](#man-linalg-lapack-functions)
-   [H87](#citeref-H87)Nicholas J. Higham, "Computing real square roots of a real matrix", Linear Algebra and its Applications, 88-89, 1987, 405-430. [doi:10.1016/0024-3795(87)90118-2](https://doi.org/10.1016/0024-3795(87)90118-2)
-   [S03](#citeref-S03)Matthew I. Smith, "A Schur Algorithm for Computing Matrix pth Roots", SIAM Journal on Matrix Analysis and Applications, vol. 24, 2003, pp. 971–989. [doi:10.1137/S0895479801392697](https://doi.org/10.1137/s0895479801392697)
-   [AH16_1](#citeref-AH16_1)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>
-   [AH16_2](#citeref-AH16_2)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>
-   [AH16_3](#citeref-AH16_3)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>
-   [AH16_4](#citeref-AH16_4)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>


## [LAPACK functions](#man-linalg-lapack-functions)
-   [AH16_5](#citeref-AH16_5)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>
-   [AH16_6](#citeref-AH16_6)Mary Aprahamian and Nicholas J. Higham, "Matrix Inverse Trigonometric and Inverse Hyperbolic Functions: Theory and Algorithms", MIMS EPrint: 2016.4. <https://doi.org/10.1137/16M1057577>
------------------------------------------------------------------------


# Logging · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Logging/


# [Logging](#man-logging)
The [`Logging`](#Logging.Logging) module provides a way to record the history and progress of a computation as a log of events. Events are created by inserting a logging statement into the source code, for example:
```julia
@warn "Abandon printf debugging, all ye who enter here!"
┌ Warning: Abandon printf debugging, all ye who enter here!
└ @ Main REPL[1]:1
```
The system provides several advantages over peppering your source code with calls to `println()`. First, it allows you to control the visibility and presentation of messages without editing the source code. For example, in contrast to the `@warn` above
```julia
@debug "The sum of some values $(sum(rand(100)))"
```
will produce no output by default. Furthermore, it's very cheap to leave debug statements like this in the source code because the system avoids evaluating the message if it would later be ignored. In this case `sum(rand(100))` and the associated string processing will never be executed unless debug logging is enabled.
Second, the logging tools allow you to attach arbitrary data to each event as a set of key–value pairs. This allows you to capture local variables and other program state for later analysis. For example, to attach the local array variable `A` and the sum of a vector `v` as the key `s` you can use
```julia
A = ones(Int, 4, 4)
v = ones(100)
@info "Some variables"  A  s=sum(v)

# output
┌ Info: Some variables
│   A =
│    4×4 Matrix{Int64}:
│     1  1  1  1
│     1  1  1  1
│     1  1  1  1
│     1  1  1  1
└   s = 100.0
```


# [Logging](#man-logging)
All of the logging macros `@debug`, `@info`, `@warn` and `@error` share common features that are described in detail in the documentation for the more general macro [`@logmsg`](#Logging.@logmsg).


## [Log event structure](#Log-event-structure)
Each event generates several pieces of data, some provided by the user and some automatically extracted. Let's examine the user-defined data first:
-   The *log level* is a broad category for the message that is used for early filtering. There are several standard levels of type [`LogLevel`](#Logging.LogLevel); user-defined levels are also possible. Each is distinct in purpose:
    -   [`Logging.Debug`](#Logging.Debug) (log level -1000) is information intended for the developer of the program. These events are disabled by default.
    -   [`Logging.Info`](#Logging.Info) (log level 0) is for general information to the user. Think of it as an alternative to using `println` directly.
    -   [`Logging.Warn`](#Logging.Warn) (log level 1000) means something is wrong and action is likely required but that for now the program is still working.
    -   [`Logging.Error`](#Logging.Error) (log level 2000) means something is wrong and it is unlikely to be recovered, at least by this part of the code. Often this log-level is unneeded as throwing an exception can convey all the required information.
-   The *message* is an object describing the event. By convention `AbstractString`s passed as messages are assumed to be in markdown format. Other types will be displayed using `print(io, obj)` or `string(obj)` for text-based output and possibly `show(io,mime,obj)` for other multimedia displays used in the installed logger.


## [Log event structure](#Log-event-structure)
-   Optional *key–value pairs* allow arbitrary data to be attached to each event. Some keys have conventional meaning that can affect the way an event is interpreted (see [`@logmsg`](#Logging.@logmsg)).
The system also generates some standard information for each event:
-   The `module` in which the logging macro was expanded.
-   The `file` and `line` where the logging macro occurs in the source code.
-   A message `id` that is a unique, fixed identifier for the *source code statement* where the logging macro appears. This identifier is designed to be fairly stable even if the source code of the file changes, as long as the logging statement itself remains the same.
-   A `group` for the event, which is set to the base name of the file by default, without extension. This can be used to group messages into categories more finely than the log level (for example, all deprecation warnings have group `:depwarn`), or into logical groupings across or within modules.
Notice that some useful information such as the event time is not included by default. This is because such information can be expensive to extract and is also *dynamically* available to the current logger. It's simple to define a [custom logger](#AbstractLogger-interface) to augment event data with the time, backtrace, values of global variables and other useful information as required.


## [Processing log events](#Processing-log-events)
As you can see in the examples, logging statements make no mention of where log events go or how they are processed. This is a key design feature that makes the system composable and natural for concurrent use. It does this by separating two different concerns:
-   *Creating* log events is the concern of the module author who needs to decide where events are triggered and which information to include.
-   *Processing* of log events — that is, display, filtering, aggregation and recording — is the concern of the application author who needs to bring multiple modules together into a cooperating application.


### [Loggers](#Loggers)
Processing of events is performed by a *logger*, which is the first piece of user configurable code to see the event. All loggers must be subtypes of [`AbstractLogger`](#Logging.AbstractLogger).
When an event is triggered, the appropriate logger is found by looking for a task-local logger with the global logger as fallback. The idea here is that the application code knows how log events should be processed and exists somewhere at the top of the call stack. So we should look up through the call stack to discover the logger — that is, the logger should be *dynamically scoped*. (This is a point of contrast with logging frameworks where the logger is *lexically scoped*; provided explicitly by the module author or as a simple global variable. In such a system it's awkward to control logging while composing functionality from multiple modules.)
The global logger may be set with [`global_logger`](#Logging.global_logger), and task-local loggers controlled using [`with_logger`](#Logging.with_logger). Newly spawned tasks inherit the logger of the parent task.


### [Loggers](#Loggers)
There are three logger types provided by the library. [`ConsoleLogger`](#Base.CoreLogging.ConsoleLogger) is the default logger you see when starting the REPL. It displays events in a readable text format and tries to give simple but user friendly control over formatting and filtering. [`NullLogger`](#Logging.NullLogger) is a convenient way to drop all messages where necessary; it is the logging equivalent of the [`devnull`](../../base/base/#Base.devnull) stream. [`SimpleLogger`](#Logging.SimpleLogger) is a very simplistic text formatting logger, mainly useful for debugging the logging system itself.
Custom loggers should come with overloads for the functions described in the [reference section](#AbstractLogger-interface).


### [Early filtering and message handling](#Early-filtering-and-message-handling)
When an event occurs, a few steps of early filtering occur to avoid generating messages that will be discarded:
1.  The message log level is checked against a global minimum level (set via [`disable_logging`](#Logging.disable_logging)). This is a crude but extremely cheap global setting.
2.  The current logger state is looked up and the message level checked against the logger's cached minimum level, as found by calling [`Logging.min_enabled_level`](#Logging.min_enabled_level). This behavior can be overridden via environment variables (more on this later).
3.  The [`Logging.shouldlog`](#Logging.shouldlog) function is called with the current logger, taking some minimal information (level, module, group, id) which can be computed statically. Most usefully, `shouldlog` is passed an event `id` which can be used to discard events early based on a cached predicate.
If all these checks pass, the message and key–value pairs are evaluated in full and passed to the current logger via the [`Logging.handle_message`](#Logging.handle_message) function. `handle_message()` may perform additional filtering as required and display the event to the screen, save it to a file, etc.


### [Early filtering and message handling](#Early-filtering-and-message-handling)
Exceptions that occur while generating the log event are captured and logged by default. This prevents individual broken events from crashing the application, which is helpful when enabling little-used debug events in a production system. This behavior can be customized per logger type by extending [`Logging.catch_exceptions`](#Logging.catch_exceptions).


## [Testing log events](#Testing-log-events)
Log events are a side effect of running normal code, but you might find yourself wanting to test particular informational messages and warnings. The `Test` module provides a [`@test_logs`](../Test/#Test.@test_logs) macro that can be used to pattern match against the log event stream.


## [Environment variables](#Environment-variables)
Message filtering can be influenced through the [`JULIA_DEBUG`](../../manual/environment-variables/#JULIA_DEBUG) environment variable, and serves as an easy way to enable debug logging for a file or module. Loading julia with `JULIA_DEBUG=loading` will activate `@debug` log messages in `loading.jl`. For example, in Linux shells:
```julia
$ JULIA_DEBUG=loading julia -e 'using OhMyREPL'
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an incompatible cache header
└ @ Base loading.jl:1328
[ Info: Recompiling stale cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji for module OhMyREPL
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/Tokenize.ji due to it containing an incompatible cache header
└ @ Base loading.jl:1328
...
```
On windows, the same can be achieved in `CMD` via first running `set JULIA_DEBUG="loading"` and in `Powershell` via `$env:JULIA_DEBUG="loading"`.
Similarly, the environment variable can be used to enable debug logging of modules, such as `Pkg`, or module roots (see [`Base.moduleroot`](../../base/base/#Base.moduleroot)). To enable all debug logging, use the special value `all`.
To turn debug logging on from the REPL, set `ENV["JULIA_DEBUG"]` to the name of the module of interest. Functions defined in the REPL belong to module `Main`; logging for them can be enabled like this:


## [Environment variables](#Environment-variables)
```julia-repl
julia> foo() = @debug "foo"
foo (generic function with 1 method)

julia> foo()

julia> ENV["JULIA_DEBUG"] = Main
Main

julia> foo()
┌ Debug: foo
└ @ Main REPL[1]:1
```
Use a comma separator to enable debug for multiple modules: `JULIA_DEBUG=loading,Main`.


## [Examples](#Examples)


### [Example: Writing log events to a file](#Example:-Writing-log-events-to-a-file)
Sometimes it can be useful to write log events to a file. Here is an example of how to use a task-local and global logger to write information to a text file:
```julia-repl
# Load the logging module
julia> using Logging

# Open a textfile for writing
julia> io = open("log.txt", "w+")
IOStream(<file log.txt>)

# Create a simple logger
julia> logger = SimpleLogger(io)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())

# Log a task-specific message
julia> with_logger(logger) do
           @info("a context specific log message")
       end

# Write all buffered messages to the file
julia> flush(io)

# Set the global logger to logger
julia> global_logger(logger)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())

# This message will now also be written to the file
julia> @info("a global log message")

# Close the file
julia> close(io)
```


### [Example: Enable debug-level messages](#Example:-Enable-debug-level-messages)
Here is an example of creating a [`ConsoleLogger`](#Base.CoreLogging.ConsoleLogger) that lets through any messages with log level higher than, or equal, to [`Logging.Debug`](#Logging.Debug).
```julia-repl
julia> using Logging

# Create a ConsoleLogger that prints any log messages with level >= Debug to stderr
julia> debuglogger = ConsoleLogger(stderr, Logging.Debug)

# Enable debuglogger for a task
julia> with_logger(debuglogger) do
           @debug "a context specific log message"
       end

# Set the global logger
julia> global_logger(debuglogger)
```


## [Reference](#Reference)


### [Logging module](#Logging-module)
Utilities for capturing, filtering and presenting streams of log events. Normally you don't need to import `Logging` to create log events; for this the standard logging macros such as `@info` are already exported by `Base` and available by default.


### [Creating events](#Creating-events)
```julia
@debug message  [key=value | value ...]
@info  message  [key=value | value ...]
@warn  message  [key=value | value ...]
@error message  [key=value | value ...]

@logmsg level message [key=value | value ...]
```
Create a log record with an informational `message`. For convenience, four logging macros `@debug`, `@info`, `@warn` and `@error` are defined which log at the standard severity levels `Debug`, `Info`, `Warn` and `Error`. `@logmsg` allows `level` to be set programmatically to any `LogLevel` or custom log level types.
`message` should be an expression which evaluates to a string which is a human readable description of the log event. By convention, this string will be formatted as markdown when presented.
The optional list of `key=value` pairs supports arbitrary user defined metadata which will be passed through to the logging backend as part of the log record. If only a `value` expression is supplied, a key representing the expression will be generated using [`Symbol`](../../base/base/#Core.Symbol). For example, `x` becomes `x=x`, and `foo(10)` becomes `Symbol("foo(10)")=foo(10)`. For splatting a list of key value pairs, use the normal splatting syntax, `@info "blah" kws...`.
There are some keys which allow automatically generated log data to be overridden:
-   `_module=mod` can be used to specify a different originating module from the source location of the message.
-   `_group=symbol` can be used to override the message group (this is normally derived from the base name of the source file).


### [Creating events](#Creating-events)
-   `_id=symbol` can be used to override the automatically generated unique message identifier. This is useful if you need to very closely associate messages generated on different source lines.
-   `_file=string` and `_line=integer` can be used to override the apparent source location of a log message.
There's also some key value pairs which have conventional meaning:
-   `maxlog=integer` should be used as a hint to the backend that the message should be displayed no more than `maxlog` times.
-   `exception=ex` should be used to transport an exception with a log message, often used with `@error`. An associated backtrace `bt` may be attached using the tuple `exception=(ex,bt)`.
**Examples**
```julia
@debug "Verbose debugging information.  Invisible by default"
@info  "An informational message"
@warn  "Something was odd.  You should pay attention"
@error "A non fatal error occurred"

x = 10
@info "Some variables attached to the message" x a=42.0

@debug begin
    sA = sum(A)
    "sum(A) = $sA is an expensive operation, evaluated only when `shouldlog` returns true"
end

for i=1:10000
    @info "With the default backend, you will only see (i = $i) ten times"  maxlog=10
    @debug "Algorithm1" i progress=i/10000
end
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L279-L346)
```julia
LogLevel(level)
```
Severity/verbosity of a log record.


### [Creating events](#Creating-events)
The log level provides a key against which potential log records may be filtered, before any other work is done to construct the log record data structure itself.
**Examples**
```julia-repl
julia> Logging.LogLevel(0) == Logging.Info
true
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L110-L124)
```julia
Debug
```
Alias for [`LogLevel(-1000)`](#Logging.LogLevel).
```julia
Info
```
Alias for [`LogLevel(0)`](#Logging.LogLevel).
```julia
Warn
```
Alias for [`LogLevel(1000)`](#Logging.LogLevel).
```julia
Error
```
Alias for [`LogLevel(2000)`](#Logging.LogLevel).
```julia
BelowMinLevel
```
Alias for [`LogLevel(-1_000_001)`](#Logging.LogLevel).
```julia
AboveMaxLevel
```
Alias for [`LogLevel(1_000_001)`](#Logging.LogLevel).


### [Processing events with AbstractLogger](#AbstractLogger-interface)
Event processing is controlled by overriding functions associated with `AbstractLogger`:
| Methods to implement                                      |                        | Brief description                            |
|:----------------------------------------------------------|:-----------------------|:---------------------------------------------|
| [`Logging.handle_message`](#Logging.handle_message)       |                        | Handle a log event                           |
| [`Logging.shouldlog`](#Logging.shouldlog)                 |                        | Early filtering of events                    |
| [`Logging.min_enabled_level`](#Logging.min_enabled_level) |                        | Lower bound for log level of accepted events |
| **Optional methods**                                      | **Default definition** | **Brief description**                        |
| [`Logging.catch_exceptions`](#Logging.catch_exceptions)   | `true`                 | Catch exceptions during event evaluation     |
A logger controls how log records are filtered and dispatched. When a log record is generated, the logger is the first piece of user configurable code which gets to inspect the record and decide what to do with it.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L25-L29)
```julia
handle_message(logger, level, message, _module, group, id, file, line; key1=val1, ...)
```


### [Processing events with AbstractLogger](#AbstractLogger-interface)
Log a message to `logger` at `level`. The logical location at which the message was generated is given by module `_module` and `group`; the source location by `file` and `line`. `id` is an arbitrary unique value (typically a [`Symbol`](../../base/base/#Core.Symbol)) to be used as a key to identify the log statement when filtering.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L32-L40)
```julia
shouldlog(logger, level, _module, group, id)
```
Return `true` when `logger` accepts a message at `level`, generated for `_module`, `group` and with unique log identifier `id`.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L43-L48)
```julia
min_enabled_level(logger)
```
Return the minimum enabled level for `logger` for early filtering. That is, the log level below or equal to which all messages are filtered.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L51-L56)
```julia
catch_exceptions(logger)
```
Return `true` if the logger should catch exceptions which happen during log record construction. By default, messages are caught
By default all exceptions are caught to prevent log message generation from crashing the program. This lets users confidently toggle little-used functionality - such as debug logging - in a production system.


### [Processing events with AbstractLogger](#AbstractLogger-interface)
If you want to use logging as an audit trail you should disable this for your logger type.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L59-L71)
```julia
disable_logging(level)
```
Disable all log messages at log levels equal to or less than `level`. This is a *global* setting, intended to make debug logging extremely cheap when disabled. Note that this cannot be used to enable logging that is currently disabled by other mechanisms.
**Examples**
```julia
Logging.disable_logging(Logging.Info) # Disable debug and info
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L529-L541)


### [Using Loggers](#Using-Loggers)
Logger installation and inspection:
```julia
global_logger()
```
Return the global logger, used to receive messages when no specific logger exists for the current task.
```julia
global_logger(logger)
```
Set the global logger to `logger`, and return the previous global logger.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L598-L607)
```julia
with_logger(function, logger)
```
Execute `function`, directing all log messages to `logger`.
**Examples**
```julia
function test(x)
    @info "x = $x"
end

with_logger(logger) do
    test(1)
    test([1,2])
end
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L616-L633)
```julia
current_logger()
```
Return the logger for the current task, or the global logger if none is attached to the task.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L638-L643)
Loggers that are supplied with the system:
```julia
NullLogger()
```
Logger which disables all messages and produces no output - the logger equivalent of /dev/null.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L94-L99)
```julia
ConsoleLogger([stream,] min_level=Info; meta_formatter=default_metafmt,
              show_limited=true, right_justify=0)
```
Logger with formatting optimized for readability in a text console, for example interactive work with the Julia REPL.


### [Using Loggers](#Using-Loggers)
Log levels less than `min_level` are filtered out.
This Logger is thread-safe, with locks for both orchestration of message limits i.e. `maxlog`, and writes to the stream.
Message formatting can be controlled by setting keyword arguments:
-   `meta_formatter` is a function which takes the log event metadata `(level, _module, group, id, file, line)` and returns a color (as would be passed to printstyled), prefix and suffix for the log message. The default is to prefix with the log level and a suffix containing the module, file and line location.
-   `show_limited` limits the printing of large data structures to something which can fit on the screen by setting the `:limit` `IOContext` key during formatting.
-   `right_justify` is the integer column which log metadata is right justified at. The default is zero (metadata goes on its own line).
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/ConsoleLogger.jl#L3-L27)
```julia
SimpleLogger([stream,] min_level=Info)
```
Simplistic logger for logging all messages with level greater than or equal to `min_level` to `stream`. If stream is closed then messages with log level greater or equal to `Warn` will be logged to `stderr` and below to `stdout`.
This Logger is thread-safe, with a lock taken around orchestration of message limits i.e. `maxlog`, and writes to the stream.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/logging/logging.jl#L651-L660)


### [Using Loggers](#Using-Loggers)
------------------------------------------------------------------------


# Markdown · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Markdown/


# [Markdown](#markdown_stdlib)
This section describes Julia's markdown syntax, which is enabled by the Markdown standard library. The following Markdown elements are supported:


## [Inline elements](#Inline-elements)
Here "inline" refers to elements that can be found within blocks of text, i.e. paragraphs. These include the following elements.


### [Bold](#Bold)
Surround words with two asterisks, `**`, to display the enclosed text in boldface.
```julia
A paragraph containing a **bold** word.
```


### [Italics](#Italics)
Surround words with one asterisk, `*`, to display the enclosed text in italics.
```julia
A paragraph containing an *italicized* word.
```


### [Literals](#Literals)
Surround text that should be displayed exactly as written with single backticks, `` ` `` .
```julia
A paragraph containing a `literal` word.
```
Literals should be used when writing text that refers to names of variables, functions, or other parts of a Julia program.
To include a backtick character within literal text use three backticks rather than one to enclose the text.
```julia
A paragraph containing ````backtick` characters ```.
```
By extension any odd number of backticks may be used to enclose a lesser number of backticks.


### [$\LaTeX$](#\\LaTeX)
Surround text that should be displayed as mathematics using $\\LaTeX$ syntax with double backticks, ````` ```.
```julia
A paragraph containing some ``\LaTeX`` markup.
```
As with literals in the previous section, if literal backticks need to be written within double backticks use an even number greater than two. Note that if a single literal backtick needs to be included within $\\LaTeX$ markup then two enclosing backticks is sufficient.
The `\` character should be escaped appropriately if the text is embedded in a Julia source code, for example, ```"``\\LaTeX`` syntax in a docstring." ```, since it is interpreted as a string literal. Alternatively, in order to avoid escaping, it is possible to use the `raw` string macro together with the `@doc` macro:
```julia
@doc raw"``\LaTeX`` syntax in a docstring." functionname
```


### [Links](#Links)
Links to either external or internal targets can be written using the following syntax, where the text enclosed in square brackets, `[ ]`, is the name of the link and the text enclosed in parentheses, `( )`, is the URL.
```julia
A paragraph containing a link to [Julia](https://www.julialang.org).
```
It's also possible to add cross-references to other documented functions/methods/variables within the Julia documentation itself. For example:
```julia
"""
    tryparse(type, str; base)

Like [`parse`](@ref), but returns either a value of the requested type,
or [`nothing`](@ref) if the string does not contain a valid number.
"""
```
This will create a link in the generated docs to the [`parse`](../../base/numbers/#Base.parse) documentation (which has more information about what this function actually does), and to the [`nothing`](../../base/constants/#Core.nothing) documentation. It's good to include cross references to mutating/non-mutating versions of a function, or to highlight a difference between two similar-seeming functions.
The above cross referencing is *not* a Markdown feature, and relies on [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), which is used to build base Julia's documentation.


### [Footnote references](#Footnote-references)
Named and numbered footnote references can be written using the following syntax. A footnote name must be a single alphanumeric word containing no punctuation.
```julia
A paragraph containing a numbered footnote [^1] and a named one [^named].
```
The text associated with a footnote can be written anywhere within the same page as the footnote reference. The syntax used to define the footnote text is discussed in the [Footnotes](#Footnotes) section below.


## [Toplevel elements](#Toplevel-elements)
The following elements can be written either at the "toplevel" of a document or within another "toplevel" element.


### [Paragraphs](#Paragraphs)
A paragraph is a block of plain text, possibly containing any number of inline elements defined in the [Inline elements](#Inline-elements) section above, with one or more blank lines above and below it.
```julia
This is a paragraph.

And this is *another* paragraph containing some emphasized text.
A new line, but still part of the same paragraph.
```


### [Headers](#Headers)
A document can be split up into different sections using headers. Headers use the following syntax:
```julia
# Level One
## Level Two
### Level Three
#### Level Four
##### Level Five
###### Level Six
```
A header line can contain any inline syntax in the same way as a paragraph can.
Try to avoid using too many levels of header within a single document. A heavily nested document may be indicative of a need to restructure it or split it into several pages covering separate topics.


### [Code blocks](#Code-blocks)
Source code can be displayed as a literal block using an indent of four spaces or one tab as shown in the following example.
```julia
This is a paragraph.

    function func(x)
        # ...
    end

Another paragraph.
```
Additionally, code blocks can be enclosed using triple backticks with an optional "language" to specify how a block of code should be highlighted.
````julia
A code block without a "language":

```
function func(x)
    # ...
end
```

and another one with the "language" specified as `julia`:

```julia
function func(x)
    # ...
end
```
````
"Fenced" code blocks, as shown in the last example, should be preferred over indented code blocks since there is no way to specify what language an indented code block is written in.


### [Block quotes](#Block-quotes)
Text from external sources, such as quotations from books or websites, can be quoted using `>` characters prepended to each line of the quote as follows.
```julia
Here's a quote:

> Julia is a high-level, high-performance dynamic programming language for
> technical computing, with syntax that is familiar to users of other
> technical computing environments.
```
Note that a single space must appear after the `>` character on each line. Quoted blocks may themselves contain other toplevel or inline elements.


### [Images](#Images)
The syntax for images is similar to the link syntax mentioned above. Prepending a `!` character to a link will display an image from the specified URL rather than a link to it.
```julia
![alternative text](link/to/image.png)
```


### [Lists](#Lists)
Unordered lists can be written by prepending each item in a list with either `*`, `+`, or `-`.
```julia
A list of items:

  * item one
  * item two
  * item three
```
Note the two spaces before each `*` and the single space after each one.
Lists can contain other nested toplevel elements such as lists, code blocks, or quoteblocks. A blank line should be left between each list item when including any toplevel elements within a list.
````julia
Another list:

  * item one

  * item two

    ```
    f(x) = x
    ```

  * And a sublist:

      + sub-item one
      + sub-item two
````
The contents of each item in the list must line up with the first line of the item. In the above example the fenced code block must be indented by four spaces to align with the `i` in `item two`.
Ordered lists are written by replacing the "bullet" character, either `*`, `+`, or `-`, with a positive integer followed by either `.` or `)`.
```julia
Two ordered lists:

 1. item one
 2. item two
 3. item three

 5) item five
 6) item six
 7) item seven
```
An ordered list may start from a number other than one, as in the second list of the above example, where it is numbered from five. As with unordered lists, ordered lists can contain nested toplevel elements.


### [Display equations](#Display-equations)
Large $\\LaTeX$ equations that do not fit inline within a paragraph may be written as display equations using a fenced code block with the "language" `math` as in the example below.
````julia
```math
f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta
```
````


### [Footnotes](#Footnotes)
This syntax is paired with the inline syntax for [Footnote references](#Footnote-references). Make sure to read that section as well.
Footnote text is defined using the following syntax, which is similar to footnote reference syntax, aside from the `:` character that is appended to the footnote label.
````julia
[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements
    indented by 4 spaces or one tab.

      * item one
      * item two
      * item three

    ```julia
    function func(x)
        # ...
    end
    ```
````
No checks are done during parsing to make sure that all footnote references have matching footnotes.


### [Horizontal rules](#Horizontal-rules)
The equivalent of an `<hr>` HTML tag can be achieved using three hyphens (`---`). For example:
```julia
Text above the line.

---

And text below the line.
```


### [Tables](#Tables)
Basic tables can be written using the syntax described below. Note that markdown tables have limited features and cannot contain nested toplevel elements unlike other elements discussed above – only inline elements are allowed. Tables must always contain a header row with column names. Cells cannot span multiple rows or columns of the table.
```julia
| Column One | Column Two | Column Three |
|:---------- | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |
```
As illustrated in the above example each column of `|` characters must be aligned vertically.
A `:` character on either end of a column's header separator (the row containing `-` characters) specifies whether the row is left-aligned, right-aligned, or (when `:` appears on both ends) center-aligned. Providing no `:` characters will default to right-aligning the column.


### [Admonitions](#Admonitions)
Specially formatted blocks, known as admonitions, can be used to highlight particular remarks. They can be defined using the following `!!!` syntax:
```julia
!!! note

    This is the content of the note.
    It is indented by 4 spaces. A tab would work as well.

!!! warning "Beware!"

    And this is another one.

    This warning admonition has a custom title: `"Beware!"`.
```
The first word after `!!!` declares the type of the admonition. There are standard admonition types that should produce special styling. Namely (in order of decreasing severity): `danger`, `warning`, `info`/`note`, and `tip`.
You can also use your own admonition types, as long as the type name only contains lowercase Latin characters (a-z). For example, you could have a `terminology` block like this:
```julia
!!! terminology "julia vs Julia"

    Strictly speaking, "Julia" refers to the language,
    and "julia" to the standard implementation.
```
However, unless the code rendering the Markdown special-cases that particular admonition type, it will get the default styling.
A custom title for the box can be provided as a string (in double quotes) after the admonition type. If no title text is specified after the admonition type, then the type name will be used as the title (e.g. `"Note"` for the `note` admonition).
Admonitions, like most other toplevel elements, can contain other toplevel elements (e.g. lists, images).


## [Markdown String Literals](#stdlib-markdown-literals)
The `md""` macro allows you to embed Markdown strings directly into your Julia code. This macro is designed to simplify the inclusion of Markdown-formatted text within your Julia source files.


### [Usage](#Usage)
```julia
result = md"This is a **custom** Markdown string with [a link](http://example.com)."
```


## [Markdown Syntax Extensions](#Markdown-Syntax-Extensions)
Julia's markdown supports interpolation in a very similar way to basic string literals, with the difference that it will store the object itself in the Markdown tree (as opposed to converting it to a string). When the Markdown content is rendered the usual `show` methods will be called, and these can be overridden as usual. This design allows the Markdown to be extended with arbitrarily complex features (such as references) without cluttering the basic syntax.
In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely custom flavour of Markdown can be used, but this should generally be unnecessary.


## [API reference](#stdlib-markdown-api)
```julia
MD
```
`MD` represents a Markdown document. Note that the `MD` constructor should not generally be used directly, since it constructs the internal data structures. Instead, you can construct `MD` objects using the exported macros [`@md_str`](#Markdown.@md_str) and [`@doc_str`](#Markdown.@doc_str).
```julia
@md_str -> MD
```
Parse the given string as Markdown text and return a corresponding [`MD`](#Markdown.MD) object.
**Examples**
```julia-repl
julia> s = md"# Hello, world!"
  Hello, world!
  ≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD
```
```julia
@doc_str -> MD
```
Parse the given string as Markdown text, add line and module information and return a corresponding [`MD`](#Markdown.MD) object.
`@doc_str` can be used in conjunction with the [`Base.Docs`](../../base/base/#Base.Docs) module. Please also refer to the manual section on [documentation](../../manual/documentation/#man-documentation) for more information.
**Examples**
```julia
julia> s = doc"f(x) = 2*x"
  f(x) = 2*x

julia> typeof(s)
Markdown.MD
```
```julia
html([io::IO], md)
```
Output the contents of the Markdown object `md` in HTML format, either writing to an (optional) `io` stream or returning a string.
One can alternatively use `show(io, "text/html", md)` or `repr("text/html", md)`, which differ in that they wrap the output in a ` ... ` element.
**Examples**
```julia-repl
julia> html(md"hello _world_")
"<p>hello <em>world</em></p>\n"
```
```julia
latex([io::IO], md)
```


## [API reference](#stdlib-markdown-api)
Output the contents of the Markdown object `md` in LaTeX format, either writing to an (optional) `io` stream or returning a string.
One can alternatively use `show(io, "text/latex", md)` or `repr("text/latex", md)`.
**Examples**
```julia-repl
julia> latex(md"hello _world_")
"hello \\emph{world}\n\n"
```
------------------------------------------------------------------------


# Memory-mapped I/O · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Mmap/


# [Memory-mapped I/O](#Memory-mapped-I/O)
Low level module for mmap (memory mapping of files).
```julia
Mmap.Anonymous(name::AbstractString="", readonly::Bool=false, create::Bool=true)
```
Create an `IO`-like object for creating zeroed-out mmapped-memory that is not tied to a file for use in [`mmap`](#Mmap.mmap). Used by `SharedArray` for creating shared memory arrays.
**Examples**
```julia-repl
julia> using Mmap

julia> anon = Mmap.Anonymous();

julia> isreadable(anon)
true

julia> iswritable(anon)
true

julia> isopen(anon)
true
```
```julia
mmap(io::Union{IOStream,AbstractString,Mmap.AnonymousMmap}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true)
mmap(type::Type{Array{T,N}}, dims)
```
Create an `Array` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory.
The type is an `Array{T,N}` with a bits-type element of `T` and dimension `N` that determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia).
`dims` is a tuple or single [`Integer`](../../base/numbers/#Core.Integer) specifying the size or length of the array.
The file is passed via the stream argument, either as an open [`IOStream`](../../base/io-network/#Base.IOStream) or filename string. When you initialize the stream, use `"r"` for a "read-only" array, and `"w+"` to create a new array used to write values to disk.


# [Memory-mapped I/O](#Memory-mapped-I/O)
If no `type` argument is specified, the default is `Vector{UInt8}`.
Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position for an `IOStream`.
The `grow` keyword argument specifies whether the disk file should be grown to accommodate the requested size of array (if the total file size is \< requested array size). Write privileges are required to grow the file.
The `shared` keyword argument specifies whether the resulting `Array` and changes made to it will be visible to other processes mapping the same file.
For example, the following code
```julia
# Create a file for mmapping
# (you could alternatively use mmap to do this step, too)
using Mmap
A = rand(1:20, 5, 30)
s = open("/tmp/mmap.bin", "w+")
# We'll write the dimensions of the array as the first two Ints in the file
write(s, size(A,1))
write(s, size(A,2))
# Now write the data
write(s, A)
close(s)

# Test by reading it back in
s = open("/tmp/mmap.bin")   # default is read-only
m = read(s, Int)
n = read(s, Int)
A2 = mmap(s, Matrix{Int}, (m,n))
```
creates a `m`-by-`n` `Matrix{Int}`, linked to the file associated with stream `s`.
A more portable file would need to encode the word size – 32 bit or 64 bit – and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping).
```julia
mmap(io, BitArray, [dims, offset])
```


# [Memory-mapped I/O](#Memory-mapped-I/O)
Create a [`BitArray`](../../base/arrays/#Base.BitArray) whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as [`mmap`](#Mmap.mmap), but the byte representation is different.
**Examples**
```julia-repl
julia> using Mmap

julia> io = open("mmap.bin", "w+");

julia> B = mmap(io, BitArray, (25,30000));

julia> B[3, 4000] = true;

julia> Mmap.sync!(B);

julia> close(io);

julia> io = open("mmap.bin", "r+");

julia> C = mmap(io, BitArray, (25,30000));

julia> C[3, 4000]
true

julia> C[2, 4000]
false

julia> close(io)

julia> rm("mmap.bin")
```
This creates a 25-by-30000 `BitArray`, linked to the file associated with stream `io`.
```julia
Mmap.sync!(array)
```
Forces synchronization between the in-memory version of a memory-mapped `Array` or [`BitArray`](../../base/arrays/#Base.BitArray) and the on-disk version.
------------------------------------------------------------------------


# Network Options · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/NetworkOptions/


# [Network Options](#Network-Options)
```julia
ca_roots() :: Union{Nothing, String}
```
The `ca_roots()` function tells the caller where, if anywhere, to find a file or directory of PEM-encoded certificate authority roots. By default, on systems like Windows and macOS where the built-in TLS engines know how to verify hosts using the system's built-in certificate verification mechanism, this function will return `nothing`. On classic UNIX systems (excluding macOS), root certificates are typically stored in a file in `/etc`: the common places for the current UNIX system will be searched and if one of these paths exists, it will be returned; if none of these typical root certificate paths exist, then the path to the set of root certificates that are bundled with Julia is returned.
The default value returned by `ca_roots()` may be overridden by setting the `JULIA_SSL_CA_ROOTS_PATH`, `SSL_CERT_DIR`, or `SSL_CERT_FILE` environment variables, in which case this function will always return the value of the first of these variables that is set (whether the path exists or not). If `JULIA_SSL_CA_ROOTS_PATH` is set to the empty string, then the other variables are ignored (as if unset); if the other variables are set to the empty string, they behave is if they are not set.
```julia
ca_roots_path() :: String
```


# [Network Options](#Network-Options)
The `ca_roots_path()` function is similar to the `ca_roots()` function except that it always returns a path to a file or directory of PEM-encoded certificate authority roots. When called on a system like Windows or macOS, where system root certificates are not stored in the file system, it will currently return the path to the set of root certificates that are bundled with Julia. (In the future, this function may instead extract the root certificates from the system and save them to a file whose path would be returned.)
If it is possible to configure a library that uses TLS to use the system certificates that is generally preferable: i.e. it is better to use `ca_roots()` which returns `nothing` to indicate that the system certs should be used. The `ca_roots_path()` function should only be used when configuring libraries which *require* a path to a file or directory for root certificates.
The default value returned by `ca_roots_path()` may be overridden by setting the `JULIA_SSL_CA_ROOTS_PATH`, `SSL_CERT_DIR`, or `SSL_CERT_FILE` environment variables, in which case this function will always return the value of the first of these variables that is set (whether the path exists or not). If `JULIA_SSL_CA_ROOTS_PATH` is set to the empty string, then the other variables are ignored (as if unset); if the other variables are set to the empty string, they behave is if they are not set.
```julia
ssh_dir() :: String
```


# [Network Options](#Network-Options)
The `ssh_dir()` function returns the location of the directory where the `ssh` program keeps/looks for configuration files. By default this is `~/.ssh` but this can be overridden by setting the environment variable `SSH_DIR`.
```julia
ssh_key_pass() :: String
```
The `ssh_key_pass()` function returns the value of the environment variable `SSH_KEY_PASS` if it is set or `nothing` if it is not set. In the future, this may be able to find a password by other means, such as secure system storage, so packages that need a password to decrypt an SSH private key should use this API instead of directly checking the environment variable so that they gain such capabilities automatically when they are added.
```julia
ssh_key_name() :: String
```
The `ssh_key_name()` function returns the base name of key files that SSH should use for when establishing a connection. There is usually no reason that this function should be called directly and libraries should generally use the `ssh_key_path` and `ssh_pub_key_path` functions to get full paths. If the environment variable `SSH_KEY_NAME` is set then this function returns that; otherwise it returns `id_rsa` by default.
```julia
ssh_key_path() :: String
```
The `ssh_key_path()` function returns the path of the SSH private key file that should be used for SSH connections. If the `SSH_KEY_PATH` environment variable is set then it will return that value. Otherwise it defaults to returning
```julia
joinpath(ssh_dir(), ssh_key_name())
```


# [Network Options](#Network-Options)
This default value in turn depends on the `SSH_DIR` and `SSH_KEY_NAME` environment variables.
```julia
ssh_pub_key_path() :: String
```
The `ssh_pub_key_path()` function returns the path of the SSH public key file that should be used for SSH connections. If the `SSH_PUB_KEY_PATH` environment variable is set then it will return that value. If that isn't set but `SSH_KEY_PATH` is set, it will return that path with the `.pub` suffix appended. If neither is set, it defaults to returning
```julia
joinpath(ssh_dir(), ssh_key_name() * ".pub")
```
This default value in turn depends on the `SSH_DIR` and `SSH_KEY_NAME` environment variables.
```julia
ssh_known_hosts_files() :: Vector{String}
```
The `ssh_known_hosts_files()` function returns a vector of paths of SSH known hosts files that should be used when establishing the identities of remote servers for SSH connections. By default this function returns
```julia
[joinpath(ssh_dir(), "known_hosts"), bundled_known_hosts]
```
where `bundled_known_hosts` is the path of a copy of a known hosts file that is bundled with this package (containing known hosts keys for `github.com` and `gitlab.com`). If the environment variable `SSH_KNOWN_HOSTS_FILES` is set, however, then its value is split into paths on the `:` character (or on `;` on Windows) and this vector of paths is returned instead. If any component of this vector is empty, it is expanded to the default known hosts paths.


# [Network Options](#Network-Options)
Packages that use `ssh_known_hosts_files()` should ideally look for matching entries by comparing the host name and key types, considering the first entry in any of the files which matches to be the definitive identity of the host. If the caller cannot compare the key type (e.g. because it has been hashes) then it must approximate the above algorithm by looking for all matching entries for a host in each file: if a file has any entries for a host then one of them must match; the caller should only continue to search further known hosts files if there are no entries for the host in question in an earlier file.
```julia
ssh_known_hosts_file() :: String
```
The `ssh_known_hosts_file()` function returns a single path of an SSH known hosts file that should be used when establishing the identities of remote servers for SSH connections. It returns the first path returned by `ssh_known_hosts_files` that actually exists. Callers who can look in more than one known hosts file should use `ssh_known_hosts_files` instead and look for host matches in all the files returned as described in that function's docs.
```julia
verify_host(url::AbstractString, [transport::AbstractString]) :: Bool
```
The `verify_host` function tells the caller whether the identity of a host should be verified when communicating over secure transports like TLS or SSH. The `url` argument may be:
1.  a proper URL staring with `proto://`
2.  an `ssh`-style bare host name or host name prefixed with `user@`
3.  an `scp`-style host as above, followed by `:` and a path location


# [Network Options](#Network-Options)
In each case the host name part is parsed out and the decision about whether to verify or not is made based solely on the host name, not anything else about the input URL. In particular, the protocol of the URL does not matter (more below).
The `transport` argument indicates the kind of transport that the query is about. The currently known values are `SSL`/`ssl` (alias `TLS`/`tls`) and `SSH`/`ssh`. If the transport is omitted, the query will return `true` only if the host name should not be verified regardless of transport.
The host name is matched against the host patterns in the relevant environment variables depending on whether `transport` is supplied and what its value is:
-   `JULIA_NO_VERIFY_HOSTS` — hosts that should not be verified for any transport
-   `JULIA_SSL_NO_VERIFY_HOSTS` — hosts that should not be verified for SSL/TLS
-   `JULIA_SSH_NO_VERIFY_HOSTS` — hosts that should not be verified for SSH
-   `JULIA_ALWAYS_VERIFY_HOSTS` — hosts that should always be verified
The values of each of these variables is a comma-separated list of host name patterns with the following syntax — each pattern is split on `.` into parts and each part must one of:
1.  A literal domain name component consisting of one or more ASCII letter, digit, hyphen or underscore (technically not part of a legal host name, but sometimes used). A literal domain name component matches only itself.
2.  A `**`, which matches zero or more domain name components.
3.  A `*`, which match any one domain name component.


# [Network Options](#Network-Options)
When matching a host name against a pattern list in one of these variables, the host name is split on `.` into components and that sequence of words is matched against the pattern: a literal pattern matches exactly one host name component with that value; a `*` pattern matches exactly one host name component with any value; a `**` pattern matches any number of host name components. For example:
-   `**` matches any host name
-   `**.org` matches any host name in the `.org` top-level domain
-   `example.com` matches only the exact host name `example.com`
-   `*.example.com` matches `api.example.com` but not `example.com` or `v1.api.example.com`
-   `**.example.com` matches any domain under `example.com`, including `example.com` itself, `api.example.com` and `v1.api.example.com`
------------------------------------------------------------------------


# Pkg · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Pkg/


# [Pkg](#Pkg)
Pkg is Julia's builtin package manager, and handles operations such as installing, updating and removing packages.
What follows is a very brief introduction to Pkg. For more information on `Project.toml` files, `Manifest.toml` files, package version compatibility (`[compat]`), environments, registries, etc., it is highly recommended to read the full manual, which is available here: <https://pkgdocs.julialang.org>.
What follows is a quick overview of the basic features of Pkg. It should help new users become familiar with basic Pkg features such as adding and removing packages and working with environments.
Some Pkg output is omitted in this section in order to keep this basic guide focused. This will help maintain a good pace and not get bogged down in details. If you require more details, refer to subsequent sections of the Pkg manual.
This guide uses the Pkg REPL to execute Pkg commands. For non-interactive use, we recommend the Pkg API. The Pkg API is fully documented in the [API Reference](https://pkgdocs.julialang.org/v1/api/) section of the Pkg documentation.
Pkg comes with a REPL. Enter the Pkg REPL by pressing `]` from the Julia REPL. To get back to the Julia REPL, press `Ctrl+C` or backspace (when the REPL cursor is at the beginning of the input).
Upon entering the Pkg REPL, you should see the following prompt:
```julia-repl
(@v1.9) pkg>
```
To add a package, use `add`:


# [Pkg](#Pkg)
```julia-repl
(@v1.9) pkg> add Example
   Resolving package versions...
   Installed Example ─ v0.5.3
    Updating `~/.julia/environments/v1.9/Project.toml`
  [7876af07] + Example v0.5.3
    Updating `~/.julia/environments/v1.9/Manifest.toml`
  [7876af07] + Example v0.5.3
```
After the package is installed, it can be loaded into the Julia session:
```julia-repl
julia> import Example

julia> Example.hello("friend")
"Hello, friend"
```
We can also specify multiple packages at once to install:
```julia-repl
(@v1.9) pkg> add JSON StaticArrays
```
The `status` command (or the shorter `st` command) can be used to see installed packages.
```julia-repl
(@v1.9) pkg> st
Status `~/.julia/environments/v1.6/Project.toml`
  [7876af07] Example v0.5.3
  [682c06a0] JSON v0.21.3
  [90137ffa] StaticArrays v1.5.9
```
Some Pkg REPL commands have a short and a long version of the command, for example `status` and `st`.
To remove packages, use `rm` (or `remove`):
```julia-repl
(@v1.9) pkg> rm JSON StaticArrays
```
Use `up` (or `update`) to update the installed packages
```julia-repl
(@v1.9) pkg> up
```
If you have been following this guide it is likely that the packages installed are at the latest version so `up` will not do anything. Below we show the status output in the case where we deliberately have installed an old version of the Example package and then upgrade it:


# [Pkg](#Pkg)
```julia-repl
(@v1.9) pkg> st
Status `~/.julia/environments/v1.9/Project.toml`
⌃ [7876af07] Example v0.5.1
Info Packages marked with ⌃ have new versions available and may be upgradable.

(@v1.9) pkg> up
    Updating `~/.julia/environments/v1.9/Project.toml`
  [7876af07] ↑ Example v0.5.1 ⇒ v0.5.3
```
We can see that the status output tells us that there is a newer version available and that `up` upgrades the package.
For more information about managing packages, see the [Managing Packages](https://pkgdocs.julialang.org/v1/managing-packages/) section of the documentation.
Up to this point, we have covered basic package management: adding, updating, and removing packages.
You may have noticed the `(@v1.9)` in the REPL prompt. This lets us know that `v1.9` is the **active environment**. Different environments can have different totally different packages and versions installed from another environment. The active environment is the environment that will be modified by Pkg commands such as `add`, `rm` and `update`.
Let's set up a new environment so we may experiment. To set the active environment, use `activate`:
```julia-repl
(@v1.9) pkg> activate tutorial
[ Info: activating new environment at `~/tutorial/Project.toml`.
```
Pkg lets us know we are creating a new environment and that this environment will be stored in the `~/tutorial` directory. The path to the environment is created relative to the current working directory of the REPL.
Pkg has also updated the REPL prompt in order to reflect the new active environment:
```julia-repl
(tutorial) pkg>
```


# [Pkg](#Pkg)
We can ask for information about the active environment by using `status`:
```julia-repl
(tutorial) pkg> status
    Status `~/tutorial/Project.toml`
   (empty environment)
```
`~/tutorial/Project.toml` is the location of the active environment's **project file**. A project file is a [TOML](https://toml.io/en/) file where Pkg stores the packages that have been explicitly installed. Notice this new environment is empty. Let us add some packages and observe:
```julia-repl
(tutorial) pkg> add Example JSON
...

(tutorial) pkg> status
    Status `~/tutorial/Project.toml`
  [7876af07] Example v0.5.3
  [682c06a0] JSON v0.21.3
```
We can see that the `tutorial` environment now contains `Example` and `JSON`.
If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Using only the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.
For more information about environments, see the [Working with Environments](https://pkgdocs.julialang.org/v1/environments/) section of the documentation.
If you are ever stuck, you can ask `Pkg` for help:
```julia-repl
(@v1.9) pkg> ?
```
You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:
```julia-repl
(@v1.9) pkg> ?develop
```


# [Pkg](#Pkg)
This guide should help you get started with `Pkg`. `Pkg` has much more to offer in terms of powerful package management, read the full manual to learn more!
------------------------------------------------------------------------


# Printf · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Printf/


# [Printf](#man-printf)
The `Printf` module provides formatted output functions similar to the C standard library's `printf`. It allows formatted printing to an output stream or to a string.
```julia
@printf([io::IO], "%Fmt", args...)
```
Print `args` using C `printf` style format specification string. Optionally, an `IO` may be passed as the first argument to redirect output.
**Examples**
```julia-repl
julia> @printf "Hello %s" "world"
Hello world

julia> @printf "Scientific notation %e" 1.234
Scientific notation 1.234000e+00

julia> @printf "Scientific notation three digits %.3e" 1.23456
Scientific notation three digits 1.235e+00

julia> @printf "Decimal two digits %.2f" 1.23456
Decimal two digits 1.23

julia> @printf "Padded to length 5 %5i" 123
Padded to length 5   123

julia> @printf "Padded with zeros to length 6 %06i" 123
Padded with zeros to length 6 000123

julia> @printf "Use shorter of decimal or scientific %g %g" 1.23 12300000.0
Use shorter of decimal or scientific 1.23 1.23e+07

julia> @printf "Use dynamic width and precision  %*.*f" 10 2 0.12345
Use dynamic width and precision        0.12
```
For a systematic specification of the format, see [here](https://en.cppreference.com/w/c/io/fprintf). See also [`@sprintf`](#Printf.@sprintf) to get the result as a `String` instead of it being printed.
**Caveats**


# [Printf](#man-printf)
`Inf` and `NaN` are printed consistently as `Inf` and `NaN` for flags `%a`, `%A`, `%e`, `%E`, `%f`, `%F`, `%g`, and `%G`. Furthermore, if a floating point number is equally close to the numeric values of two possible output strings, the output string further away from zero is chosen.
**Examples**
```julia-repl
julia> @printf("%f %F %f %F", Inf, Inf, NaN, NaN)
Inf Inf NaN NaN

julia> @printf "%.0f %.1f %f" 0.5 0.025 -0.0078125
0 0.0 -0.007812
```
Starting in Julia 1.8, `%s` (string) and `%c` (character) widths are computed using [`textwidth`](../../base/strings/#Base.Unicode.textwidth), which e.g. ignores zero-width characters (such as combining characters for diacritical marks) and treats certain "wide" characters (e.g. emoji) as width `2`.
Dynamic width specifiers like `%*s` and `%0*.*f` require Julia 1.10.
```julia
@sprintf("%Fmt", args...)
```
Return [`@printf`](#Printf.@printf) formatted output as string.
**Examples**
```julia-repl
julia> @sprintf "this is a %s %15.1f" "test" 34.567
"this is a test            34.6"
```
```julia
Printf.Format(format_str)
```
Create a C printf-compatible format object that can be used for formatting values.
The input `format_str` can include any valid format specifier character and modifiers.
A `Format` object can be passed to `Printf.format(f::Format, args...)` to produce a formatted string, or `Printf.format(io::IO, f::Format, args...)` to print the formatted string directly to `io`.


# [Printf](#man-printf)
For convenience, the `Printf.format"..."` string macro form can be used for building a `Printf.Format` object at macro-expansion-time.
`Printf.Format` requires Julia 1.6 or later.
```julia
Printf.format(f::Printf.Format, args...) => String
Printf.format(io::IO, f::Printf.Format, args...)
```
Apply a printf format object `f` to provided `args` and return the formatted string (1st method), or print directly to an `io` object (2nd method). See [`@printf`](#Printf.@printf) for more details on C `printf` support.
------------------------------------------------------------------------


# Profiling · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Profile/


# [Profiling](#lib-profiling)


## [CPU Profiling](#CPU-Profiling)
There are two main approaches to CPU profiling julia code:


## [Via @profile](#Via-@profile)
Where profiling is enabled for a given call via the `@profile` macro.
```julia-repl
julia> using Profile

julia> @profile foo()

julia> Profile.print()
Overhead ╎ [+additional indent] Count File:Line; Function
=========================================================
    ╎147  @Base/client.jl:506; _start()
        ╎ 147  @Base/client.jl:318; exec_options(opts::Base.JLOptions)
...
```


## [Triggered During Execution](#Triggered-During-Execution)
Tasks that are already running can also be profiled for a fixed time period at any user-triggered time.
To trigger the profiling:
-   MacOS & FreeBSD (BSD-based platforms): Use `ctrl-t` or pass a `SIGINFO` signal to the julia process i.e. `% kill -INFO $julia_pid`
-   Linux: Pass a `SIGUSR1` signal to the julia process i.e. `% kill -USR1 $julia_pid`
-   Windows: Not currently supported.
First, a single stack trace at the instant that the signal was thrown is shown, then a 1 second profile is collected, followed by the profile report at the next yield point, which may be at task completion for code without yield points e.g. tight loops.
Optionally set environment variable [`JULIA_PROFILE_PEEK_HEAP_SNAPSHOT`](../../manual/environment-variables/#JULIA_PROFILE_PEEK_HEAP_SNAPSHOT) to `1` to also automatically collect a [heap snapshot](#Heap-Snapshots).


## [Triggered During Execution](#Triggered-During-Execution)
```julia-repl
julia> foo()
##== the user sends a trigger while foo is running ==##
load: 2.53  cmd: julia 88903 running 6.16u 0.97s

======================================================================================
Information request received. A stacktrace will print followed by a 1.0 second profile
======================================================================================

signal (29): Information request: 29
__psynch_cvwait at /usr/lib/system/libsystem_kernel.dylib (unknown line)
_pthread_cond_wait at /usr/lib/system/libsystem_pthread.dylib (unknown line)
...

======================================================================
Profile collected. A report will print if the Profile module is loaded
======================================================================

Overhead ╎ [+additional indent] Count File:Line; Function
=========================================================
Thread 1 Task 0x000000011687c010 Total snapshots: 572. Utilization: 100%
   ╎147 @Base/client.jl:506; _start()
       ╎ 147 @Base/client.jl:318; exec_options(opts::Base.JLOptions)
...

Thread 2 Task 0x0000000116960010 Total snapshots: 572. Utilization: 0%
   ╎572 @Base/task.jl:587; task_done_hook(t::Task)
      ╎ 572 @Base/task.jl:879; wait()
...
```


### [Customization](#Customization)
The duration of the profiling can be adjusted via [`Profile.set_peek_duration`](#Profile.set_peek_duration)
The profile report is broken down by thread and task. Pass a no-arg function to `Profile.peek_report[]` to override this. i.e. `Profile.peek_report[] = () -> Profile.print()` to remove any grouping. This could also be overridden by an external profile data consumer.


## [Reference](#Reference)
```julia
@profile
```
`@profile <expression>` runs your expression while taking periodic backtraces. These are appended to an internal buffer of backtraces.
The methods in `Profile` are not exported and need to be called e.g. as `Profile.print()`.
```julia
clear()
```
Clear any existing backtraces from the internal buffer.
```julia
print([io::IO = stdout,] [data::Vector = fetch()], [lidict::Union{LineInfoDict, LineInfoFlatDict} = getdict(data)]; kwargs...)
```
Prints profiling results to `io` (by default, `stdout`). If you do not supply a `data` vector, the internal buffer of accumulated backtraces will be used.
The keyword arguments can be any combination of:
-   `format` – Determines whether backtraces are printed with (default, `:tree`) or without (`:flat`) indentation indicating tree structure.
-   `C` – If `true`, backtraces from C and Fortran code are shown (normally they are excluded).
-   `combine` – If `true` (default), instruction pointers are merged that correspond to the same line of code.
-   `maxdepth` – Limits the depth higher than `maxdepth` in the `:tree` format.
-   `sortedby` – Controls the order in `:flat` format. `:filefuncline` (default) sorts by the source line, `:count` sorts in order of number of collected samples, and `:overhead` sorts by the number of samples incurred by each function by itself.
-   `groupby` – Controls grouping over tasks and threads, or no grouping. Options are `:none` (default), `:thread`, `:task`, `[:thread, :task]`, or `[:task, :thread]` where the last two provide nested grouping.


## [Reference](#Reference)
-   `noisefloor` – Limits frames that exceed the heuristic noise floor of the sample (only applies to format `:tree`). A suggested value to try for this is 2.0 (the default is 0). This parameter hides samples for which `n <= noisefloor * √N`, where `n` is the number of samples on this line, and `N` is the number of samples for the callee.
-   `mincount` – Limits the printout to only those lines with at least `mincount` occurrences.
-   `recur` – Controls the recursion handling in `:tree` format. `:off` (default) prints the tree as normal. `:flat` instead compresses any recursion (by ip), showing the approximate effect of converting any self-recursion into an iterator. `:flatc` does the same but also includes collapsing of C frames (may do odd things around `jl_apply`).
-   `threads::Union{Int,AbstractVector{Int}}` – Specify which threads to include snapshots from in the report. Note that this does not control which threads samples are collected on (which may also have been collected on another machine).
-   `tasks::Union{Int,AbstractVector{Int}}` – Specify which tasks to include snapshots from in the report. Note that this does not control which tasks samples are collected within.
The `groupby`, `threads`, and `tasks` keyword arguments were introduced in Julia 1.8.
Profiling on windows is limited to the main thread. Other threads have not been sampled and will not show in the report.
```julia
print([io::IO = stdout,] data::Vector, lidict::LineInfoDict; kwargs...)
```


## [Reference](#Reference)
Prints profiling results to `io`. This variant is used to examine results exported by a previous call to [`retrieve`](#Profile.retrieve). Supply the vector `data` of backtraces and a dictionary `lidict` of line information.
See `Profile.print([io], data)` for an explanation of the valid keyword arguments.
```julia
init(; n::Integer, delay::Real)
```
Configure the `delay` between backtraces (measured in seconds), and the number `n` of instruction pointers that may be stored per thread. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Note that 6 spaces for instruction pointers per backtrace are used to store metadata and two NULL end markers. Current settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order `(n, delay)`.
```julia
fetch(;include_meta = true) -> data
```
Return a copy of the buffer of profile backtraces. Note that the values in `data` have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; [`retrieve`](#Profile.retrieve) may be a better choice for most users. By default metadata such as threadid and taskid is included. Set `include_meta` to `false` to strip metadata.
```julia
retrieve(; kwargs...) -> data, lidict
```