# 15.2 Filesystem
  filename : (or/c path-string? #f)
  kind : (or/c 'shared 'exclusive)
  thunk : (  →   any)
  failure-thunk : (  →   any)
  lock-file : (or/c #f path-string?) = #f
  delay : (and/c real? (not/c negative?)) = 0.01
  max-delay : (and/c real? (not/c negative?)) = 0.2
```
Obtains a lock for the filename lock-file and then calls thunk. The filename argument specifies a file path prefix that is used only to generate the lock filename when lock-file is #f. Specifically, when lock-file is #f, then call-with-file-lock/timeout uses make-lock-file-name to build the lock filename. If the lock file does not yet exist, it is created; beware that the lock file is not deleted by call-with-file-lock/timeout.

When thunk returns, call-with-file-lock/timeout releases the lock, returning the result of thunk. The call-with-file-lock/timeout function will retry after delay seconds and continue retrying with exponential backoff until delay reaches max-delay. If call-with-file-lock/timeout fails to obtain the lock, failure-thunk is called in tail position. The kind argument specifies whether the lock is 'shared or 'exclusive in the sense of port-try-file-lock?.

Examples:

> ```racket
> > ( call-with-file-lock/timeout filename ' exclusive ( lambda ( ) ( printf "File is locked\n" ) ) ( lambda ( ) ( printf "Failed to obtain lock for file\n" ) ) )
> File is locked
> > ( call-with-file-lock/timeout #f ' exclusive ( lambda ( ) ( call-with-file-lock/timeout filename ' shared ( lambda ( ) ( printf "Shouldn't get here\n" ) ) ( lambda ( ) ( printf "Failed to obtain lock for file\n" ) ) ) ) ( lambda ( ) ( printf "Shouldn't get here either\n" ) ) #:lock-file ( make-lock-file-name filename ) )
> Failed to obtain lock for file
> ```

> ```
(make-lock-file-name path)   →   path?
  path : (or/c path-string? path-for-some-system?)
(make-lock-file-name dir name)   →   path?
  dir : (or/c path-string? path-for-some-system?)
  name : path-element?```

Creates a lock filename by prepending "\_LOCK" on Windows (i.e., when [cross-system-type](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=raco&rel=cross-system.html%23%2528def._%2528%2528lib._setup%252Fcross-system..rkt%2529._cross-system-type%2529%2529&version=8.18.0.13) reports 'windows) or ".LOCK" on other platforms to the file portion of the path.

Example:

> ```racket
> > ( make-lock-file-name "/home/george/project/important-file" )
> #<path:/home/george/project/.LOCKimportant-file>
> ```

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[file-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._file-type-bits%29%29) : #o170000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[socket-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._socket-type-bits%29%29) : #o140000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[symbolic-link-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._symbolic-link-type-bits%29%29) : #o120000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[regular-file-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._regular-file-type-bits%29%29) : #o100000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[block-device-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._block-device-type-bits%29%29) : #o060000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[directory-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._directory-type-bits%29%29) : #o040000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[character-device-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._character-device-type-bits%29%29) : #o020000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[fifo-type-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._fifo-type-bits%29%29) : #o010000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[set-user-id-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._set-user-id-bit%29%29) : #o004000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[set-group-id-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._set-group-id-bit%29%29) : #o002000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[sticky-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._sticky-bit%29%29) : #o001000</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[user-permission-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._user-permission-bits%29%29) : #o000700</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[user-read-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._user-read-bit%29%29) : #o000400</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[user-write-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._user-write-bit%29%29) : #o000200</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[user-execute-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._user-execute-bit%29%29) : #o000100</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[group-permission-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._group-permission-bits%29%29) : #o000070</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[group-read-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._group-read-bit%29%29) : #o000040</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[group-write-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._group-write-bit%29%29) : #o000020</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[group-execute-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._group-execute-bit%29%29) : #o000010</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[other-permission-bits](#%28def._%28%28lib._racket%2Ffile..rkt%29._other-permission-bits%29%29) : #o000007</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[other-read-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._other-read-bit%29%29) : #o000004</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[other-write-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._other-write-bit%29%29) : #o000002</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[other-execute-bit](#%28def._%28%28lib._racket%2Ffile..rkt%29._other-execute-bit%29%29) : #o000001</p></blockquote></td></tr></tbody></table></td></tr></tbody></table>

Constants that are useful with [file-or-directory-permissions](#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29), [file-or-directory-stat](#%28def._%28%28quote._~23~25kernel%29._file-or-directory-stat%29%29) and bitwise operations such as [bitwise-ior](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._bitwise-ior%29%29), and [bitwise-and](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._bitwise-and%29%29).

------------------------------------------------------------------------

# 15.3 Networking

### 15.3 Networking

|                                                       |
|-------------------------------------------------------|
|     [15.3.1 TCP](tcp.html) |
|     [15.3.2 UDP](udp.html) |

------------------------------------------------------------------------

# 15.3.1 TCP

#### 15.3.1 TCP

|                                                                                |                                                                                |
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/tcp]()) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |

The bindings documented in this section are provided by the [racket/tcp]() and [racket](index.html) libraries, but not [racket/base](index.html).

For information about TCP in general, see TCP/IP Illustrated, Volume 1 by W. Richard Stevens.

> ```
(tcp-listen port-no
   [ max-allow-wait
    reuse?
    hostname)    →    tcp-listener?

  port-no : listen-port-number?
  max-allow-wait : exact-nonnegative-integer? = 4
  reuse? : any/c = #f
  hostname : (or/c string? #f) = #f
```


# 15.2 Filesystem
Creates a “listening” server on the local machine at the port number specified by port-no. If port-no is 0 the socket binds to an ephemeral port, which can be determined by calling tcp-addresses. The max-allow-wait argument determines the maximum number of client connections that can be waiting for acceptance. (When max-allow-wait clients are awaiting acceptance, no new client connections can be made.)
If the reuse? argument is true, then tcp-listen will create a listener even if the port is involved in a TIME_WAIT state. Such a use of reuse? defeats certain guarantees of the TCP protocol; see Stevens’s book for details. Furthermore, on many modern platforms, a true value for reuse? overrides TIME_WAIT only if the listener was previously created with a true value for reuse?.
If hostname is #f (the default), then the listener accepts connections to all of the listening machine’s addresses. Otherwise, the listener accepts connections only at the interface(s) associated with the given hostname. For example, providing "127.0.0.1" as hostname creates a listener that accepts only connections to "127.0.0.1" (the loopback interface) from the local machine.


# 15.2 Filesystem
Racket implements a listener with multiple sockets, if necessary, to accommodate multiple addresses with different protocol families. On Linux, if hostname maps to both IPv4 and IPv6 addresses, then the behavior depends on whether IPv6 is supported and IPv6 sockets can be configured to listen to only IPv6 connections: if IPv6 is not supported or IPv6 sockets are not configurable, then the IPv6 addresses are ignored; otherwise, each IPv6 listener accepts only IPv6 connections.
On variants of Unix and MacOS that support FD_CLOEXEC, a listener socket is given that flag so that it is not shared with a subprocess created by subprocess.
The return value of tcp-listen is a TCP listener. This value can be used in future calls to tcp-accept, tcp-accept-ready?, and tcp-close. Each new TCP listener value is placed into the management of the current custodian (see Custodians).
If the server cannot be started by tcp-listen, the exn:fail:network exception is raised.
A TCP listener can be used as a synchronizable event (see Events). A TCP listener is ready for synchronization when tcp-accept would not block; the synchronization result of a TCP listener is the TCP listener itself.
Changed in version 8.11.1.6 of package base: Changed to use FD_CLOEXEC where supported by the operating system.
> ```
(tcp-connect hostname
    port-no
   [ local-hostname
    local-port-no)    →    input-port?   output-port?
  hostname : string?
  port-no : port-number?
  local-hostname : (or/c string? #f) = #f
  local-port-no : (or/c port-number? #f) = #f```


# 15.2 Filesystem
Attempts to connect as a client to a listening server. The hostname argument is the server host’s Internet address name, and port-no is the port number where the server is listening.
(If hostname is associated with multiple addresses, they are tried one at a time until a connection succeeds. The name "localhost" generally specifies the local machine.)
The optional local-hostname and local-port-no specify the client’s address and port. If both are #f (the default), the client’s address and port are selected automatically. If local-hostname is not #f, then local-port-no must be non-#f. If local-port-no is non-#f and local-hostname is #f, then the given port is used but the address is selected automatically.
Two values are returned by [tcp-connect](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-connect%29%29): an input port and an output port. Data can be received from the server through the input port and sent to the server through the output port. If the server is a Racket program, it can obtain ports to communicate to the client with [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29). These ports are placed into the management of the current custodian (see [Custodians](custodians.html)).


# 15.2 Filesystem
Initially, the returned input port is block-buffered, and the returned output port is block-buffered. Change the buffer mode using [file-stream-buffer-mode](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-stream-buffer-mode%29%29). When a TCP output port is block-buffered, Nagle’s algorithm is disabled for the port, which corresponds to setting the TCP_NODELAY socket option.
Both of the returned ports must be closed to terminate the TCP connection. When both ports are still open, closing the output port with [close-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29) sends a TCP close to the server (which is seen as an end-of-file if the server reads the connection through a port). In contrast, [tcp-abandon-port](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-abandon-port%29%29) (see below) closes the output port, but does not send a TCP close until the input port is also closed.
Note that the TCP protocol does not support a state where one end is willing to send but not read, nor does it include an automatic message when one end of a connection is fully closed. Instead, the other end of a connection discovers that one end is fully closed only as a response to sending data; in particular, some number of writes on the still-open end may appear to succeed, though writes will eventually produce an error.


# 15.2 Filesystem
On variants of Unix and MacOS that support FD_CLOEXEC, a connection socket is given that flag so that it is not shared with a subprocess created by [subprocess](subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29).
If a connection cannot be established by [tcp-connect](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-connect%29%29), the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.
Changed in version 8.8.0.8 of package base: Changed block buffering to imply TCP_NODELAY.
Changed in version 8.11.1.6: Changed to use FD_CLOEXEC where supported by the operating system.
> ```
(tcp-connect/enable-break hostname
    port-no
   [ local-hostname]
    local-port-no)
   →    input-port?   output-port?
  hostname : string?
  port-no : port-number?
  local-hostname : (or/c string? #f) = #f
  local-port-no : (or/c port-number? #f)


# 15.2 Filesystem
```
Like tcp-connect, but breaking is enabled (see Breaks) while trying to connect. If breaking is disabled when tcp-connect/enable-break is called, then either ports are returned or the exn:break exception is raised, but not both.

> ```
(tcp-accept listener)    →    input-port?   output-port?

  listener : tcp-listener?```

Accepts a client connection for the server associated with listener. If no client connection is waiting on the listening port, the call to [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29) will block. (See also [tcp-accept-ready?](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept-ready~3f%29%29).)

Two values are returned by [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29): an input port and an output port. Data can be received from the client through the input port and sent to the client through the output port. These ports are placed into the management of the current custodian (see [Custodians](custodians.html)).

In terms of buffering and connection states, the ports act the same as ports from [tcp-connect](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-connect%29%29).

On variants of Unix and MacOS that support FD_CLOEXEC, an accepted socket is given that flag so that it is not shared with a subprocess created by [subprocess](subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29).

If a connection cannot be accepted by [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29), or if the listener has been closed, the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.

Changed in version 8.11.1.6 of package base: Changed to use FD_CLOEXEC where supported by the operating system.

> ```
(tcp-accept/enable-break listener)    →    input-port?   output-port?

  listener : tcp-listener?
```


# 15.2 Filesystem
Like tcp-accept, but breaking is enabled (see Breaks) while trying to accept a connection. If breaking is disabled when tcp-accept/enable-break is called, then either ports are returned or the exn:break exception is raised, but not both.
> ```
(tcp-accept-ready? listener)   →   boolean?
  listener : tcp-listener?```
Tests whether an unaccepted client has connected to the server associated with listener. If a client is waiting, the return value is #t, otherwise it is #f. A client is accepted with the [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29) procedure, which returns ports for communicating with the client and removes the client from the list of unaccepted clients.
If the listener has been closed, the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.
> ```
(parameter)	→


# 15.2 Filesystem
```
Shuts down the server associated with listener. All unaccepted clients receive an end-of-file from the server; connections to accepted clients are unaffected.

If the listener has already been closed, the exn:fail:network exception is raised.

The listener’s port number may not become immediately available for new listeners (with the default reuse? argument of tcp-listen). For further information, see Stevens’s explanation of the TIME_WAIT TCP state.

> ```
(tcp-listener? v)   →   boolean?
  v : any/c```

Returns #t if v is a [TCP listener](#%28tech._tcp._listener%29) created by [tcp-listen](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-listen%29%29), #f otherwise.

> ```
(tcp-accept-evt listener)  →  evt?
  listener : tcp-listener?
```
(parameter)	→```
Like [close-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29) or [close-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29) (depending on whether tcp-port is an input or output port), but if tcp-port is an output port and its associated input port is not yet closed, then the other end of the TCP connection does not receive a TCP close message until the input port is also closed.
The TCP protocol does not include a “no longer reading” state on connections, so [tcp-abandon-port](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-abandon-port%29%29) is equivalent to [close-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29) on input [TCP ports](#%28tech._tcp._port%29).
> ```


# 15.2 Filesystem
(tcp-addresses tcp-port [port-numbers?)
   →    ( or/c ( values string? string? )
> ( values string? port-number?
> string? listen-port-number? ) )
  tcp-port : (or/c tcp-port? tcp-listener? udp?)
  port-numbers? : any/c = #f
```
Returns two strings when port-numbers? is #f (the default). The first string is the Internet address for the local machine as viewed by the given TCP port’s connection, for the TCP listener, or the UDP socket. (When a machine serves multiple addresses, as it usually does if you count the loopback device, the result is connection-specific or listener-specific.) If a listener or UDP socket is given and it has no specific host, the first string result is "0.0.0.0". The second string is the Internet address for the other end of the connection, or always "0.0.0.0" for a listener or unconnected UDP socket.

If port-numbers? is true, then four results are returned: a string for the local machine’s address, an exact integer between 1 and 65535 for the local machine’s port number, a string for the remote machine’s address, and an exact integer between 1 and 65535 for the remote machine’s port number or 0 for a listener.

If the given port, listener, or socket has been closed, the exn:fail:network exception is raised.

> ```
(tcp-port? v)   →   boolean?
  v : any/c```

Returns #t if v is a TCP port—which is a port returned by [tcp-accept](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%29%29), [tcp-connect](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-connect%29%29), [tcp-accept/enable-break](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-accept%2Fenable-break%29%29), or [tcp-connect/enable-break](#%28def._%28%28lib._racket%2Ftcp..rkt%29._tcp-connect%2Fenable-break%29%29)—#f otherwise.

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[port-number?](#%28def._%28%28lib._racket%2Ftcp..rkt%29._port-number~3f%29%29) : [contract?](contract-utilities.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fguts..rkt%29._contract~3f%29%29)</p></blockquote></td></tr></tbody></table>

Equivalent to ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 1 65535).

Added in version 6.3 of package base.

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[listen-port-number?](#%28def._%28%28lib._racket%2Ftcp..rkt%29._listen-port-number~3f%29%29) : [contract?](contract-utilities.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fguts..rkt%29._contract~3f%29%29)</p></blockquote></td></tr></tbody></table>

Equivalent to ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 65535).

Added in version 6.3 of package base.

------------------------------------------------------------------------

# 15.3.2 UDP

#### 15.3.2 UDP

|                                                                                |                                                                                |
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/udp]()) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |

The bindings documented in this section are provided by the [racket/udp]() and [racket](index.html) libraries, but not [racket/base](index.html).

For information about UDP in general, see TCP/IP Illustrated, Volume 1 by W. Richard Stevens.

> ```
(udp-open-socket [family-hostname
    family-port-no)    →    udp?

  family-hostname : (or/c string? #f) = #f
  family-port-no : (or/c port-number? #f) = #f
```


# 15.2 Filesystem
(parameter)	→
(-> or/c string? #f)```
Binds an unbound udp-socket to the local port number port-no. If port-no is 0 the udp-socket is bound to an ephemeral port, which can be determined by calling [udp-addresses](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-addresses%29%29).
If hostname-string is #f, then the socket accepts connections to all of the listening machine’s IP addresses at port-no. Otherwise, the socket accepts connections only at the IP address associated with the given name. For example, providing "127.0.0.1" as hostname-string typically creates a listener that accepts only connections to "127.0.0.1" from the local machine.
A socket cannot receive datagrams until it is bound to a local address and port. If a socket is not bound before it is used with a sending procedure [udp-send](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send%29%29), [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29), etc., the sending procedure binds the socket to a random local port. Similarly, if an event from [udp-send-evt](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-evt%29%29) or [udp-send-to-evt](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to-evt%29%29) is chosen for a synchronization (see [Events](sync.html)), the socket is bound; if the event is not chosen, the socket may or may not become bound.


# 15.2 Filesystem
The binding of a bound socket cannot be changed, with one exception: on some systems, if the socket is bound automatically when sending, if the socket is disconnected via [udp-connect!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-connect%21%29%29), and if the socket is later used again in a send, then the later send may change the socket’s automatic binding.
If udp-socket is already bound or closed, the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.
If the reuse? argument is true, then [udp-bind!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-bind%21%29%29) will set the SO_REUSEADDR socket option before binding, permitting the sharing of access to a UDP port between many processes on a single machine when using UDP multicast.
> ```
(parameter)	→
(-> or/c string? #f)


# 15.2 Filesystem
```
(parameter)	→
(-> bytes-length bstr)```

Sends ([subbytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._subbytes%29%29) [bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes%29%29) start-pos end-pos) as a datagram from the unconnected udp-socket to the socket at the remote machine hostname-address on the port port-no. The udp-socket need not be bound or connected; if it is not bound, [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29) binds it to a random local port. If the socket’s outgoing datagram queue is too full to support the send, [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29) blocks until the datagram can be queued.

If start-pos is greater than the length of bstr, or if end-pos is less than start-pos or greater than the length of bstr, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

If udp-socket is closed or connected, the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.

> ```
(parameter)	→
(-> bytes-length bstr)
```
Like udp-send-to, except that udp-socket must be connected, and the datagram goes to the connection target. If udp-socket is closed or unconnected, the exn:fail:network exception is raised.
> ```
(udp-send-to* udp-socket
    hostname
    port-no
    bstr
   [ start-pos
    end-pos)    →    boolean?


# 15.2 Filesystem
  udp-socket : udp?
  hostname : string?
  port-no : port-number?
  bstr : bytes?
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)```
Like [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29), but never blocks; if the socket’s outgoing queue is too full to support the send, #f is returned, otherwise the datagram is queued and the result is #t.
> ```
(udp-send* udp-socket bstr [start-pos end-pos) → boolean?
  udp-socket : udp?
  bstr : bytes?
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)
```
(parameter)	→
(-> bytes-length bstr)```

Like [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29), but breaking is enabled (see [Breaks](breakhandler.html)) while trying to send the datagram. If breaking is disabled when [udp-send-to/enable-break](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%2Fenable-break%29%29) is called, then either the datagram is sent or the [exn:break](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) exception is raised, but not both.

> ```
(parameter)	→
(-> bytes-length bstr)
```
Like udp-send, except that breaks are enabled like udp-send-to/enable-break.
> ```
(udp-receive! udp-socket
    bstr
   [ start-pos
    end-pos)    →    exact-nonnegative-integer?
string?
port-number?


# 15.2 Filesystem
  udp-socket : udp?
  bstr : (and/c bytes? (not immutable?))
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)```
Accepts up to end-pos-start-pos bytes of udp-socket’s next incoming datagram into bstr, writing the datagram bytes starting at position start-pos within bstr. The udp-socket must be bound to a local address and port (but need not be connected). If no incoming datagram is immediately available, [udp-receive!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-receive%21%29%29) blocks until one is available.
Three values are returned: the number of received bytes (between 0 and end-pos-start-pos, a hostname string indicating the source address of the datagram, and an integer indicating the source port of the datagram. If the received datagram is longer than end-pos-start-pos bytes, the remainder is discarded.
If start-pos is greater than the length of bstr, or if end-pos is less than start-pos or greater than the length of bstr, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
> ```
(udp-receive!* udp-socket
    bstr
   [ start-pos
    end-pos)
   →    (or/c exact-nonnegative-integer? #f)
(or/c string? #f)
(or/c port-number? #f)
  udp-socket : udp?
  bstr : (and/c bytes? (not immutable?))
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)


# 15.2 Filesystem
```
Like udp-receive!, except that it never blocks. If no datagram is available, the three result values are all #f.

> ```
(udp-receive!/enable-break udp-socket
    bstr
   [ start-pos
    end-pos)

   →    exact-nonnegative-integer?
string?
port-number?

  udp-socket : udp?
  bstr : (and/c bytes? (not immutable?))
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)```

Like [udp-receive!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-receive%21%29%29), but breaking is enabled (see [Breaks](breakhandler.html)) while trying to receive the datagram. If breaking is disabled when [udp-receive!/enable-break](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-receive%21%2Fenable-break%29%29) is called, then either a datagram is received or the [exn:break](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) exception is raised, but not both.

> ```
(parameter)	→
```
(SO_RCVBUF)	→```
Closes udp-socket, discarding unreceived datagrams. If the socket is already closed, the [exn:fail:network](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) exception is raised.
> ```
(udp? v)  →  boolean?
  v : any/c
```
Returns #t if v is a socket created by udp-open-socket, #f otherwise.

> ```
(udp-bound? udp-socket)   →   boolean?
  udp-socket : udp?```

Returns #t if udp-socket is bound to a local address and port, #f otherwise.

> ```
(udp-connected? udp-socket)  →  boolean?
  udp-socket : udp?
```


# 15.2 Filesystem
Returns #t if udp-socket is connected to a remote address and port, #f otherwise.
> ```
(udp-send-ready-evt udp-socket)  →  evt?
  udp-socket : udp?
```

Returns a [synchronizable event](sync.html#%28tech._synchronizable._event%29) (see [Events](sync.html)) that is in a blocking state when [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29) on udp-socket would block. The [synchronization result](sync.html#%28tech._synchronization._result%29) is the event itself.

> ```
(udp-receive-ready-evt udp-socket)  →  evt?
  udp-socket : udp?
```
Returns a synchronizable event (see Events) that is in a blocking state when udp-receive! on udp-socket would block. The synchronization result is the event itself.
> ```
(udp-send-to-evt udp-socket
    hostname
    port-no
    bstr
   [ start-pos
    end-pos)    →    evt?
  udp-socket : udp?
  hostname : string?
  port-no : port-number?
  bstr : bytes?
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)```


# 15.2 Filesystem
Returns a [synchronizable event](sync.html#%28tech._synchronizable._event%29). The event is in a blocking state when [udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29) on udp-socket would block. Otherwise, if the event is chosen in a synchronization, data is sent as for ([udp-send-to](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-send-to%29%29) udp-socket hostname-address port-no bstr start-pos end-pos), and the synchronization result is [#<void>](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.18.0.13). (No bytes are sent if the event is not chosen.)
> ```
(udp-send-evt udp-socket
    bstr
   [ start-pos
    end-pos)    →    evt?
  udp-socket : udp?
  bstr : bytes?
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)


# 15.2 Filesystem
```
Returns a synchronizable event. The event is ready for synchronization when udp-send on udp-socket would not block. Otherwise, if the event is chosen in a synchronization, data is sent as for (udp-send-to udp-socket bstr start-pos end-pos), and the synchronization result is #<void>. (No bytes are sent if the event is not chosen.) If udp-socket is closed or unconnected, the exn:fail:network exception is raised during a synchronization attempt.

> ```
(udp-receive!-evt udp-socket
    bstr
   [ start-pos
    end-pos)    →    evt?

  udp-socket : udp?
  bstr : (and/c bytes? (not immutable?))
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = (bytes-length bstr)```

Returns a [synchronizable event](sync.html#%28tech._synchronizable._event%29). The event is [ready for synchronization](sync.html#%28tech._ready._for._synchronization%29) when udp-receive on udp-socket would not block. Otherwise, if the event is chosen in a synchronization, data is received into bstr as for ([udp-receive!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-receive%21%29%29) udp-socket [bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes%29%29) start-pos end-pos), and the [synchronization result](sync.html#%28tech._synchronization._result%29) is a list of three values, corresponding to the three results from [udp-receive!](#%28def._%28%28lib._racket%2Fudp..rkt%29._udp-receive%21%29%29). (No bytes are received and the bstr content is not modified if the event is not chosen.)

> ```
(udp-addresses udp-port [port-numbers?)
   →    ( or/c ( values string? string? )
> ( values string? listen-port-number?
> string? listen-port-number? ) )

  udp-port : udp?
  port-numbers? : any/c = #f
```


# 15.2 Filesystem
(parameter)	→
(-> udp-ttl udp-socket)```
> > > Time-to-live settings correspond to the IP_TTL setting of the socket.
Sets or retrieves the current time-to-live setting of udp-socket.
Added in version 7.5.0.5 of package base.
> ```
(parameter)	→
(-> or/c string? #f)
```
(parameter)	→
(-> udp-multicast-set-interface! udp-socket
    hostname)```

Retrieves or sets the interface that udp-socket uses to send (not receive) multicast datagrams. If the result or hostname is either #f or "0.0.0.0", the kernel automatically selects an interface when a multicast datagram is sent.

> ```
(parameter)	→
(-> udp-multicast-loopback? udp-socket)
```
(parameter)	→
(-> udp-multicast-ttl udp-socket)```
> > > Time-to-live settings correspond to the IP_MULTICAST_TTL setting of the socket.
Sets or retrieves the current time-to-live setting of udp-socket.
The time-to-live setting should almost always be 1, and it is important that this number is as low as possible. In fact, these functions seldom should be used at all. See the documentation for your platform’s IP stack.
------------------------------------------------------------------------


# 15.4 Processes


### 15.4 Processes
> ```
(subprocess stdout
    stdin
    stderr
   [ group]
    command
    arg ...)
   →    subprocess?
(or/c (and/c input-port? file-stream-port?) #f)
(or/c (and/c output-port? file-stream-port?) #f)
(or/c (and/c input-port? file-stream-port?) #f)
  stdout : (or/c (and/c output-port? file-stream-port?) #f)
  stdin : (or/c (and/c input-port? file-stream-port?) #f)
  stderr : (or/c (and/c output-port? file-stream-port?) #f 'stdout)
   group   :   (or/c #f 'new subprocess)
      =   (and (subprocess-group-enabled) 'new)
  command : path-string?
  arg : (or/c path? string-no-nuls? bytes-no-nuls?)
(subprocess   stdout
    stdin
    stderr
   [ group]
    command
    exact
    arg)
   →    subprocess?
(or/c (and/c input-port? file-stream-port?) #f)
(or/c (and/c output-port? file-stream-port?) #f)
(or/c (and/c input-port? file-stream-port?) #f)
  stdout : (or/c (and/c output-port? file-stream-port?) #f)
  stdin : (or/c (and/c input-port? file-stream-port?) #f)
  stderr : (or/c (and/c output-port? file-stream-port?) #f)
   group   :   (or/c #f 'new subprocess)
      =   (and (subprocess-group-enabled) 'new)
  command : path-string?
  exact : 'exact
  arg : string?


# 15.4 Processes
```
(parameter)	→
(-> printf "stderr:\n~a" (port → string err))```

Blocks until the process represented by subproc terminates. The subproc value also can be used with [sync](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29) and [sync/timeout](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%2Ftimeout%29%29).

> ```
(subprocess-status subproc)    →    ( or/c ' running
> exact-nonnegative-integer? )

  subproc : subprocess?
```
(parameter)	→```
Terminates the subprocess represented by subproc. The precise action depends on whether force? is true, whether the process was created in its own group by setting the [subprocess-group-enabled](#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29) parameter to a true value, and the current platform:
-   force? is true, not a group, all platforms: Terminates the process if the process still running.
-   force? is false, not a group, on Unix or Mac OS: Sends the process an interrupt signal instead of a kill signal.
-   force? is false, not a group, on Windows: No action is taken.


# 15.4 Processes
-   force? is true, a group, on Unix or Mac OS: Terminates all processes in the group, but only if [subprocess-status](#%28def._%28%28quote._~23~25kernel%29._subprocess-status%29%29) has never produced a non-'running result for the subprocess and only if functions like [subprocess-wait](#%28def._%28%28quote._~23~25kernel%29._subprocess-wait%29%29) and [sync](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29) have not detected the subprocess’s completion. Otherwise, no action is taken (because the immediate process is known to have terminated while the continued existence of the group is unknown).
-   force? is true, a group, on Windows: Terminates the process if the process still running.
-   force? is false, a group, on Unix or Mac OS: The same as when force? is #t, but when the group is sent a signal, it is an interrupt signal instead of a kill signal.
-   force? is false, a group, on Windows: All processes in the group receive a CTRL-BREAK signal (independent of whether the immediate subprocess has terminated).
If an error occurs during termination, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.
> ```
(subprocess-pid subproc)  →  exact-nonnegative-integer?
  subproc : subprocess?
```

Returns the operating system’s numerical ID (if any) for the process represented by subproc. The result is valid only as long as the process is running.

> ```
(subprocess? v)  →  boolean?
  v : any/c
```
Returns #t if v is a subprocess value, #f otherwise.
> ```


# 15.4 Processes
(current-subprocess-custodian-mode)	→
(-> or/c #f 'kill 'interrupt)
(current-subprocess-custodian-mode mode) → void?
    mode	:
(-> or/c #f 'kill 'interrupt)
```
(subprocess-group-enabled)	→
(-> subprocess-group-enabled on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that determines whether a subprocess is created as a new process group by default. See [subprocess](#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29) and [subprocess-kill](#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29) for more information.

> ```
(current-subprocess-keep-file-descriptors)	→
(-> or/c 'inherited 'all '())
(current-subprocess-keep-file-descriptors keeps) → void?
    keeps	:
(-> or/c 'inherited 'all '())
```
(parameter)	→
(-> or/c string? #f)```
Performs the action specified by verb on target in Windows. For platforms other than Windows, the [exn:fail:unsupported](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29) exception is raised.
For example,
> ```racket
> ( shell-execute #f "http://racket-lang.org" ""
> ( current-directory ) ' sw_shownormal )
> ```
Opens the Racket home page in a browser window.
The verb can be #f, in which case the operating system will use a default verb. Common verbs include "open", "edit", "find", "explore", and "print".
The target is the target for the action, usually a filename path. The file could be executable, or it could be a file with a recognized extension that can be handled by an installed application.


# 15.4 Processes
The parameters argument is passed on to the system to perform the action. For example, in the case of opening an executable, the parameters is used as the command line (after the executable name).
The dir is used as the current directory when performing the action.
The show-mode sets the display mode for a Window affected by the action. It must be one of the following symbols; the description of each symbol’s meaning is taken from the Windows API documentation.
-   'sw_hide or 'SW_HIDE — Hides the window and activates another window.
-   'sw_maximize or 'SW_MAXIMIZE — Maximizes the window.
-   'sw_minimize or 'SW_MINIMIZE — Minimizes the window and activates the next top-level window in the z-order.
-   'sw_restore or 'SW_RESTORE — Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position.
-   'sw_show or 'SW_SHOW — Activates the window and displays it in its current size and position.
-   'sw_showdefault or 'SW_SHOWDEFAULT — Uses a default.
-   'sw_showmaximized or 'SW_SHOWMAXIMIZED — Activates the window and displays it as a maximized window.
-   'sw_showminimized or 'SW_SHOWMINIMIZED — Activates the window and displays it as a minimized window.
-   'sw_showminnoactive or 'SW_SHOWMINNOACTIVE — Displays the window as a minimized window. The active window remains active.
-   'sw_showna or 'SW_SHOWNA — Displays the window in its current state. The active window remains active.


# 15.4 Processes
-   'sw_shownoactivate or 'SW_SHOWNOACTIVATE — Displays a window in its most recent size and position. The active window remains active.
-   'sw_shownormal or 'SW_SHOWNORMAL — Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position.
If the action fails, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised. If the action succeeds, the result is #f.
In future versions of Racket, the result may be a subprocess value if the operating system did returns a process handle (but if a subprocess value is returned, its process ID will be 0 instead of the real process ID).


#### 15.4.1 Simple Subprocesses
|                                                                                |                                                                                |
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/system](#%28mod-path._racket%2Fsystem%29)) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |
The bindings documented in this section are provided by the [racket/system](#%28mod-path._racket%2Fsystem%29) and [racket](index.html) libraries, but not [racket/base](index.html).
> ```
(system command [#:set-pwd? set-pwd?) → boolean?
  command : (or/c string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))


# 15.4 Processes
```
(current-directory)	→
(-> or/c path? string-no-nuls? bytes-no-nuls?)```

Like [system](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29), except that command is a filename that is executed directly (instead of through a shell command; see [find-executable-path](Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29) for locating an executable based on the PATH environment variable), and the args are the arguments. The executed file is passed the specified string arguments (which must contain no nul characters).

On Windows, the first argument after command can be 'exact, and the final arg is a complete command line. See [subprocess](#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29) for details and for a specific warning about using a command that refers to a ".bat" or ".cmd" file.

> ```
(system/exit-code command
   [ #:set-pwd? set-pwd?)    →    byte?

  command : (or/c string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))
```
Like system, except that the result is the exit code returned by the subprocess. A 0 result normally indicates success.
> ```
(system*/exit-code command
    arg ...
   [ #:set-pwd? set-pwd?)    →    byte?
  command : path-string?
  arg : (or/c path? string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))
(system*/exit-code   command
    exact
    arg
   [ #:set-pwd? set-pwd?)    →    byte?


# 15.4 Processes
  command : path-string?
  exact : 'exact
  arg : string?
  set-pwd? : any/c = (member (system-type) '(unix macosx))```
Like [system*](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29), but returns the exit code like [system/exit-code](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2Fexit-code%29%29).
> ```
(process command [#:set-pwd? set-pwd?)
   →    ( list input-port?
> output-port?
> exact-nonnegative-integer?
> input-port?
> ( ( or/c ' status ' wait ' interrupt ' kill ) .  →  . any ) )
  command : (or/c string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))


# 15.4 Processes
```
(system-type)	→
(-> or/c path? string-no-nuls? bytes-no-nuls?)```

Like [process](#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29), except that command is a filename that is executed directly like [system*](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29), and the args are the arguments.

On Windows, as for [system*](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29), the first arg can be replaced with 'exact. See also [subprocess](#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29) for a specific warning about using a command that refers to a ".bat" or ".cmd" file.

> ```
(process/ports out
    in
    error-out
    command
   [ #:set-pwd? set-pwd?)    →    list?

  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port? 'stdout)
  command : (or/c path? string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))
```
Like process, except that out is used for the process’s standard output, in is used for the process’s standard input, and error-out is used for the process’s standard error. Any of the ports can be #f, in which case a system pipe is created and returned, as in process. If error-out is 'stdout, then standard error is redirected to standard output. For each port or 'stdout that is provided, no pipe is created, and the corresponding value in the returned list is #f.
> ```
(process*/ports out
    in
    error-out
    command
    arg ...
   [ #:set-pwd? set-pwd?)    →    list?


# 15.4 Processes
  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port? 'stdout)
  command : path-string?
  arg : (or/c path? string-no-nuls? bytes-no-nuls?)
  set-pwd? : any/c = (member (system-type) '(unix macosx))
(process*/ports   out
    in
    error-out
    command
    exact
    arg
   [ #:set-pwd? set-pwd?)    →    list?
  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port? 'stdout)
  command : path-string?
  exact : 'exact
  arg : string?
  set-pwd? : any/c = (member (system-type) '(unix macosx))```
Like [process*](#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2A%29%29), but with the port handling of [process/ports](#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2Fports%29%29).
The contracts of [system](#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29) and related functions may signal a contract error with references to the following functions.
> ```
(string-no-nuls? x)  →  boolean?
  x : any/c
```

Ensures that x is a string and does not contain "\\u0000".

> ```
(bytes-no-nuls? x)  →  boolean?
  x : any/c
```
Ensures that x is a byte-string and does not contain #"\\0".
------------------------------------------------------------------------


# 15.5 Logging


### 15.5 Logging
A logger accepts events that contain information to be logged for interested parties. A log receiver represents an interested party that receives logged events asynchronously. Each event has a topic and level of detail, and a [log receiver](#%28tech._log._receiver%29) subscribes to logging events at a certain level of detail (and lower) for a specific topic or for all topics. The levels, in increasing order of detail, are 'none, 'fatal, 'error, 'warning, 'info, and 'debug. The 'none level is intended for specifying receivers, and messages logged at that level are never sent to subscribers.
To help organize logged events, a [logger](#%28tech._logger%29) can have a default topic and/or a parent logger. Every event reported to a logger is propagated to its parent (if any), and the event message is prefixed with the logger’s topic (if any) if the message doesn’t already have a topic. Furthermore, events that are propagated from a logger to its parent can be filtered by level and topic.


# 15.5 Logging
On start-up, Racket creates an initial logger that is used to record events from the core run-time system. For example, a 'debug event is reported for each garbage collection (see [Garbage Collection](eval-model.html#%28part._gc-model%29)). For this initial logger, two log receivers are also created: one that writes events to the process’s original error output port, and one that writes events to the system log. The level of written events in each case is system-specific, and the default can be changed through command-line flags (see [Command Line](running-sa.html#%28part._mz-cmdline%29)) or through environment variables:
-   If the PLTSTDERR environment variable is defined and is not overridden by a command-line flag, it determines the level of the [log receiver](#%28tech._log._receiver%29) that propagates events to the original error port.
    The environment variable’s value can be a ‹level›: none, fatal, error, warning, info, or debug (from low detail to high detail); all events at the corresponding level of detail or lower are printed. After an initial ‹level›, the value can contain whitespace-separated specifications of the form ‹level›@‹topic›, which prints events whose topics match ‹topic› only at the given ‹level› or higher (where a ‹topic› contains any character other than whitespace or @). Leading and trailing whitespace is ignored. For example, the value "error debug@GC" prints all events at the 'error level and higher, but prints events for the topic 'GC at the 'debug level and higher (which includes all levels).
    The default is "error".


# 15.5 Logging
-   If the PLTSTDOUT environment variable is defined and is not overridden by a command-line flag, it determines the level of the [log receiver](#%28tech._log._receiver%29) that propagates events to the original output port. The possible values are the same as for PLTSTDERR.
    The default is "none".
-   If the PLTSYSLOG environment variable is defined and is not overridden by a command-line flag, it determines the level of the [log receiver](#%28tech._log._receiver%29) that propagates events to the system log. The possible values are the same as for PLTSTDERR.
    The default is "none" for Unix or "error" for Windows and Mac OS.
The [current-logger](#%28def._%28%28quote._~23~25kernel%29._current-logger%29%29) [parameter](eval-model.html#%28tech._parameter%29) determines the current logger that is used by forms such as [log-warning](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-warning%29%29). On start-up, the initial value of this parameter is the initial logger. The run-time system sometimes uses the current logger to report events. For example, the bytecode compiler sometimes reports 'warning events when it detects an expression that would produce a run-time error if evaluated.
Changed in version 6.6.0.2 of package base: Prior to version 6.6.0.2, parsing of PLTSTDERR and PLTSYSLOG was very strict. Leading and trailing whitespace was forbidden, and anything other than exactly one space character separating two specifications was rejected.
Changed in version 6.90.0.17: Added PLTSTDOUT.


#### 15.5.1 Creating Loggers
> ```
(logger? v)  →  boolean?
  v : any/c
```
(parameter)	→
(-> or/c symbol? #f)```

Creates a new [logger](#%28tech._logger%29) with an optional topic and parent.

The optional propagate-level and propagate-topic arguments constrain the events that are propagated from the new logger to parent (when parent is not #f) in the same way that events are described for a log receiver in [make-log-receiver](#%28def._%28%28quote._~23~25kernel%29._make-log-receiver%29%29). By default, all events are propagated to parent.

Changed in version 6.1.1.3 of package base: Removed an optional argument to specify a notification callback, and added propagate-level and propagate-topic constraints for events to propagate.

> ```
(parameter)	→
(-> or/c symbol? #f)
```
(current-logger)	→
(-> current-logger logger)
(current-logger logger) → void?
    logger	:
(-> current-logger logger)```
A [parameter](eval-model.html#%28tech._parameter%29) that determines the [current logger](#%28tech._current._logger%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax


# 15.5 Logging

([define-logger](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._define-logger%29%29) id maybe-parent)

<colgroup><col style="width: 20%" /><col style="width: 20%" /><col style="width: 20%" /><col style="width: 20%" /><col style="width: 20%" /></colgroup>

maybe-parent	 	=

 	 	|	 	#:parent parent-expr

  	parent-expr	 	:	 	([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) [logger?](#%28def._%28%28quote._~23~25kernel%29._logger~3f%29%29) #f)


# 15.5 Logging
Defines log-id-fatal, log-id-error, log-id-warning, log-id-info, and log-id-debug as forms like [log-fatal](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-fatal%29%29), [log-error](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-error%29%29),[log-warning](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-warning%29%29), [log-info](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-info%29%29), and [log-debug](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-debug%29%29). The [define-logger](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._define-logger%29%29) form also defines id-logger, which is a logger with default topic 'id that is a child of the result of parent-expr (if parent-expr does not produce #f), or of ([current-logger](#%28def._%28%28quote._~23~25kernel%29._current-logger%29%29)) if parent-expr not provided; the log-id-fatal, etc. forms use this new logger. The new logger is created when [define-logger](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._define-logger%29%29) is evaluated.
Changed in version 7.1.0.9 of package base: Added the #:parent option.


#### 15.5.2 Logging Events
> ```
(parameter)	→
(-> or/c symbol? #f)
```
(parameter)	→
(-> or/c symbol? #f)```

Reports whether any [log receiver](#%28tech._log._receiver%29) attached to logger or one of its ancestors is interested in level events (or potentially lower) for topic. If topic is #f, the result indicates whether a [log receiver](#%28tech._log._receiver%29) is interested in events at level for any topic. If level is 'none, the result is always #f.

Use this function to avoid work generating an event for [log-message](#%28def._%28%28quote._~23~25kernel%29._log-message%29%29) if no receiver is interested in the information; this shortcut is built into [log-fatal](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-fatal%29%29), [log-error](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-error%29%29), [log-warning](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-warning%29%29), [log-info](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-info%29%29), [log-debug](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-debug%29%29), and forms bound by [define-logger](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._define-logger%29%29), however, so it should not be used with those forms.

The result of this function can change if a garbage collection determines that a log receiver is no longer accessible (and therefore that any event information it receives will never become accessible).

Changed in version 6.1.1.3 of package base: Added the topic argument.
Changed in version 8.10.0.5: Changed the result for 'none to be consistently #f.

> ```
(parameter)	→
(-> or/c log-level/c #f)
```


# 15.5 Logging
(parameter)	→
(-> list/c (or/c #f log-level/c)
    (or/c #f symbol?)
    ... ...)```
Summarizes the possible results of [log-max-level](#%28def._%28%28quote._~23~25kernel%29._log-max-level%29%29) on all possible [interned](reader.html#%28tech._interned%29) symbols. The result list contains a sequence of symbols and #f, where the first, third, etc., list element corresponds to a level, and the second, fourth, etc., list element indicates a corresponding topic. The level is the result that [log-max-level](#%28def._%28%28quote._~23~25kernel%29._log-max-level%29%29) would produce for the topic, where the level for the #f topic (which is always present in the result list) indicates the result for any [interned](reader.html#%28tech._interned%29)-symbol topic that does not appear in the list.
The result is suitable as a sequence of arguments to [make-log-receiver](#%28def._%28%28quote._~23~25kernel%29._make-log-receiver%29%29) (after a [logger](#%28tech._logger%29) argument) to create a new receiver for events that currently have receivers in logger.
Added in version 6.1.1.4 of package base.
> ```
(log-level-evt logger)  →  evt?
  logger : logger?
```
(parameter)	→```

Returns #t if v is a [log receiver](#%28tech._log._receiver%29), #f otherwise.

> ```
(parameter)	→
(-> or/c #f symbol?)
```
Creates a log receiver to receive events of detail level and lower as reported to logger and its descendants, as long as either topic is #f or the event’s topic matches topic.


# 15.5 Logging
A log receiver is a synchronizable event. It becomes ready for synchronization when a logging event is received, so use sync to receive a logged event. The log receiver’s synchronization result is an immutable vector containing four values: the level of the event as a symbol, an immutable string for the event message, an arbitrary value that was supplied as the last argument to log-message when the event was logged, and a symbol or #f for the event topic.
Multiple pairs of level and topic can be provided to indicate different specific levels for different topics (where topic defaults to #f only for the last given level). A level for a #f topic applies only to events whose topic does not match any other provided topic. If the same topic is provided multiple times, the level provided with the last instance in the argument list takes precedence.


#### 15.5.4 Additional Logging Functions
|  |  |
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require racket/logging) |  package: base |
The bindings documented in this section are provided by the racket/logging library, not racket/base or racket.
> ```
(log-level/c v) → boolean?
  v : any/c```
Returns #t if v is a valid logging level ('none, 'fatal, 'error, 'warning, 'info, or 'debug), #f otherwise.
Added in version 6.3 of package base.
> ```
(parameter)	→
(-> (vector/c
    log-level/c
    string?
    any/c
    (or/c symbol? #f))
    any)


# 15.5 Logging
```
(parameter)	→
(-> any)```

Runs proc, outputting any logging that the execution of proc emits to [current-logger](#%28def._%28%28quote._~23~25kernel%29._current-logger%29%29) at the specified levels and topics. If #:logger is specified, intercepts events sent to that logger, otherwise uses a new child logger of the current logger. Returns whatever proc returns.

Example:

> ```racket
> > ( let ( [ my-log ( open-output-string ) ] ) ( with-logging-to-port my-log ( lambda ( ) ( log-warning "Warning World!" ) ( + 2 2 ) ) ' warning ) ( get-output-string my-log ) )
> "Warning World!\n"
> ```

Added in version 6.3 of package base.
Changed in version 6.7.0.1: Added #:logger argument.

------------------------------------------------------------------------

# 15.6 Time

### 15.6 Time

> ```
(current-seconds)	→
```
(current-inexact-milliseconds)	→```
Returns the current time in milliseconds since [the epoch](#%28tech._the._epoch%29). The result may contain fractions of a millisecond.
Example:
> ```racket
> > ( current-inexact-milliseconds )
> 1289513737015.418
> ```
In this example, 1289513737015 is in milliseconds and 418 is in microseconds.
> ```
(current-inexact-monotonic-milliseconds)	→


# 15.5 Logging
```
(parameter)	→```

Takes secs-n, a time in seconds since [the epoch](#%28tech._the._epoch%29) (like the value of ([current-seconds](#%28def._%28%28quote._~23~25kernel%29._current-seconds%29%29)), ([file-or-directory-modify-seconds](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29) path), or ([/](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2F%29%29) ([current-inexact-milliseconds](#%28def._%28%28quote._~23~25kernel%29._current-inexact-milliseconds%29%29)) 1000)), and returns an instance of the [date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%2A%29%29) structure type. Note that secs-n can include fractions of a second. If secs-n is too small or large, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.

The resulting [date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%2A%29%29) reflects the time according to the local time zone if local-time? is #t, otherwise it reflects a date in UTC.

>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29)	 (	second

 	 	 	 	minute

 	 	 	 	hour

 	 	 	 	day

 	 	 	 	month

 	 	 	 	year

 	 	 	 	week-day

 	 	 	 	year-day

 	 	 	 	dst?

 	 	 	 	time-zone-offset)

    #:extra-constructor-name [make-date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-date%29%29)

    #:transparent)

  second : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 60)

  minute : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 59)

  hour : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 23)

  day : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 1 31)

  month : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 1 12)

  year : [exact-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29)

  week-day : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 6)

  year-day : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 365)

  dst? : [boolean?](booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29)

  time-zone-offset : [exact-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29)

Represents a date. The second field reaches 60 only for leap seconds. The week-day field is 0 for Sunday, 1 for Monday, etc. The year-day field is 0 for January 1, 1 for January 2, etc.; the year-day field reaches 365 only in leap years.

The dst? field is #t if the date reflects a daylight-saving adjustment. The time-zone-offset field reports the number of seconds east of UTC (GMT) for the current time zone (e.g., Pacific Standard Time is -28800), including any daylight-saving adjustment (e.g., Pacific Daylight Time is -25200). When a [date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29) record is generated by [seconds->date](#%28def._%28%28quote._~23~25kernel%29._seconds-~3edate%29%29) with #f as the second argument, then the dst? and time-zone-offset fields are #f and 0, respectively.

The [date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29) constructor accepts any value for dst? and converts any non-#f value to #t.

The value produced for the time-zone-offset field tends to be sensitive to the value of the TZ environment variable, especially on Unix platforms; consult the system documentation (usually under tzset) for details.

See also the [racket/date](#%28mod-path._racket%2Fdate%29) library.

>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%2A%29%29) [date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29) (nanosecond time-zone-name)

    #:extra-constructor-name [make-date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-date%2A%29%29))

  nanosecond : ([integer-in](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29) 0 999999999)

  time-zone-name : ([and/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29) [string?](strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29) [immutable?](booleans.html#%28def._%28%28quote._~23~25kernel%29._immutable~3f%29%29))

Extends [date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29) with nanoseconds and a time zone name, such as "MDT", "Mountain Daylight Time", or "UTC".

When a [date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%2A%29%29) record is generated by [seconds->date](#%28def._%28%28quote._~23~25kernel%29._seconds-~3edate%29%29) with #f as the second argument, then the time-zone-name field is "UTC".

The [date*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%2A%29%29) constructor accepts a mutable string for time-zone-name and converts it to an immutable one.

> ```
(current-milliseconds)	→
```


# 15.5 Logging
(parameter)	→
(-> or/c #f thread? 'subprocesses)```
Returns an amount of processor time in [fixnum](numbers.html#%28tech._fixnum%29) milliseconds that has been consumed by on the underlying operating system, including both user and system time.
-   If scope is #f, the reported time is for all Racket threads and [places](places.html#%28tech._place%29).
-   If scope is a thread, the result is specific to the time while the thread ran, but it may include time for other [places](places.html#%28tech._place%29). The more a thread synchronizes with other threads, the less precisely per-thread processor time is recorded.
-   If scope is 'subprocesses, the result is the sum of process times for known-completed subprocesses (see [Processes](subprocess.html))—and known-completed children of the subprocesses, etc., on Unix and Mac OS—across all [places](places.html#%28tech._place%29).
The precision of the result is platform-specific, and since the result is a [fixnum](numbers.html#%28tech._fixnum%29), the value increases only over a limited (though reasonably long) time on a 32-bit platform.
Changed in version 6.1.1.4 of package base: Added 'subprocesses mode.
> ```
(current-gc-milliseconds)	→


# 15.5 Logging
```
(current-process-milliseconds)	→```

Collects timing information for a procedure application.

Four values are returned: a list containing the result(s) of applying proc to the arguments in lst, the number of milliseconds of CPU time required to obtain this result, the number of “real” milliseconds required for the result, and the number of milliseconds of CPU time (included in the first result) spent on garbage collection.

The reliability of the timing numbers depends on the platform. If multiple Racket threads are running, then the reported time may include work performed by other threads.

>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([time](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._time%29%29) body ...+)

Reports [time-apply](#%28def._%28%28quote._~23~25kernel%29._time-apply%29%29)-style timing information for the evaluation of expr directly to the current output port. The result is the result of the last body.

#### 15.6.1 Date Utilities

> > > For more date & time operations, see [the Gregor: Date and Time documentation](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?tag=%28part._%28.%27%28lib._gregor%2Fscribblings%2Fgregor..scrbl%29.%27._.%27top.%27%29%29&version=8.18.0.13) or [srfi/19](../srfi/srfi-19.html)

|                                                                                |                                                                                |
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/date](#%28mod-path._racket%2Fdate%29)) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |

The bindings documented in this section are provided by the [racket/date](#%28mod-path._racket%2Fdate%29) library, not [racket/base](index.html) or [racket](index.html).

> ```
(current-date)	→
```


# 15.5 Logging
(current-inexact-milliseconds)	→
(-> * 0.001 (current-inexact-milliseconds))```
Converts a date to a string. The returned string contains the time of day only if time?. See also [date-display-format](#%28def._%28%28lib._racket%2Fdate..rkt%29._date-display-format%29%29).
> ```
(date-display-format)	→
(-> or/c ' american
    ' chinese
    ' german
    ' indian
    ' irish
    ' iso-8601
    ' rfc2822
    ' julian)
(date-display-format format) → void?
    format	:
(-> or/c ' american
    ' chinese
    ' german
    ' indian
    ' irish
    ' iso-8601
    ' rfc2822
    ' julian)
```
Parameter that determines the date string format. The initial format is 'american.

> ```
(date → seconds date [local-time?) → exact-integer?
  date : date?
  local-time? : any/c = #t```

Finds the representation of a date in platform-specific seconds. If the platform cannot represent the specified date, [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.

The week-day, year-day fields of date are ignored. The dst? and time-zone-offset fields of date are also ignored; the date is assumed to be in local time by default or in UTC if local-time? is #f.

> ```
(date* → seconds date [local-time?) → real?
  date : date?
  local-time? : any/c = #t
```
Like date  →  seconds, but returns an exact number that can include a fraction of a second based on (date*-nanosecond date) if date is a date* instance.
> ```


# 15.5 Logging
(find-seconds second
    minute
    hour
    day
    month
    year
   [ local-time?)    →    exact-integer?
  second : (integer-in 0 61)
  minute : (integer-in 0 59)
  hour : (integer-in 0 23)
  day : (integer-in 1 31)
  month : (integer-in 1 12)
  year : exact-nonnegative-integer?
  local-time? : any/c = #t```
Finds the representation of a date in platform-specific seconds. The arguments correspond to the fields of the [date](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._date%29%29) structure—in local time by default or UTC if local-time? is #f. If the platform cannot represent the specified date, an error is signaled, otherwise an integer is returned.
> ```
(date  →  julian/scaliger date)  →  exact-integer?
  date : date?
```

Converts a date structure (up to 2099 BCE Gregorian) into a Julian date number. The returned value is not a strict Julian number, but rather Scaliger’s version, which is off by one for easier calculations.

> ```
(julian/scaliger  →  string date-number)  →  string?
  date-number : exact-integer?
```
Converts a Julian number (Scaliger’s off-by-one version) into a string.
> ```
(date  →  julian/scalinger date)  →  exact-integer?
  date : date?
(julian/scalinger  →  string date-number)  →  string?
  date-number : exact-integer?


# 15.5 Logging
```
(parameter)	→
(-> environment-variables? v)```

Returns #t if v is an [environment variable set](#%28tech._environment._variable._set%29), #f otherwise.

> ```
(current-environment-variables)	→
(-> current-environment-variables env)
(current-environment-variables env) → void?
    env	:
(-> current-environment-variables env)
```
A parameter that determines the environment variable set that is propagated to a subprocess and that is used as the default set for getenv and putenv.
> ```
(bytes-environment-variable-name? v)   →   boolean?
  v : any/c```
Returns #t if v is a byte string and if it is valid for an environment variable name. An environment variable name must contain no bytes with the value 0 or 61, where 61 is ([char->integer](characters.html#%28def._%28%28quote._~23~25kernel%29._char-~3einteger%29%29) #\\=). On Windows, an environment variable name also must have a non-zero length.
> ```
(make-environment-variables name val ... ...)
  →  environment-variables?
  name : bytes-environment-variable-name?
  val : bytes-no-nuls?


# 15.5 Logging
```
Creates a fresh environment variable set that is initialized with the given name to val mappings.

> ```
(environment-variables-ref env name)
   →   (or/c #f (and/c bytes-no-nuls? immutable?))
  env : environment-variables?
  name : bytes-environment-variable-name?```

Returns the mapping for name in env, returning #f if name has no mapping.

Normally, name should be a byte-string encoding of a string using the default encoding of the current [locale](encodings.html#%28tech._locale%29). On Windows, name is coerced to a UTF-8 encoding and case-normalized.

> ```
(environment-variables-set! env
    name
    maybe-bstr
   [ fail)    →    any

  env : environment-variables?
  name : bytes-environment-variable-name?
  maybe-bstr : (or/c bytes-no-nuls? #f)
   fail   :   (  →   any)   =   ( lambda ( )
> ( raise ( make-exn:fail .... ) ) )
```
Changes the mapping for name in env to maybe-bstr. If maybe-bstr is #f and env is the initial environment variable set of the Racket process, then the operating system environment-variable mapping for name is removed.
Normally, name and maybe-bstr should be a byte-string encoding of a string using the default encoding of the current locale. On Windows, name is coerced to a UTF-8 encoding and case-normalized, and maybe-bstr is coerced to a UTF-8 encoding if env is the initial environment variable set of the Racket process.


# 15.5 Logging
On success, the result of environment-variables-set! is #<void>. If env is the initial environment variable set of the Racket process, then attempting to adjust the operating system environment-variable mapping might fail for some reason, in which case fail is called in tail position with respect to the environment-variables-set!. The default fail raises an exception.
> ```
(environment-variables-names env)
   →   (listof (and/c bytes-environment-variable-name? immutable?))
  env : environment-variables?```
Returns a list of byte strings that corresponds to names mapped by env.
> ```
(environment-variables-copy env)  →  environment-variables?
  env : environment-variables?


# 15.5 Logging
```
Returns an environment variable set that is initialized with the same mappings as env.

> ```
(getenv name)   →   (or/c string-no-nuls? #f)
  name : string-environment-variable-name?

(putenv name value)   →   boolean?
  name : string-environment-variable-name?
  value : string-no-nuls?```

Convenience wrappers for [environment-variables-ref](#%28def._%28%28quote._~23~25kernel%29._environment-variables-ref%29%29) and [environment-variables-set!](#%28def._%28%28quote._~23~25kernel%29._environment-variables-set%21%29%29) that convert between strings and byte strings using the current [locale](encodings.html#%28tech._locale%29)’s default encoding (using #\\? as the replacement character for encoding errors) and always using the current [environment variable set](#%28tech._environment._variable._set%29) from [current-environment-variables](#%28def._%28%28quote._~23~25kernel%29._current-environment-variables%29%29). The [putenv](#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._putenv%29%29) function returns #t for success and #f for failure.

> ```
(string-environment-variable-name? v)  →  boolean?
  v : any/c
```
(parameter)	→
(-> or/c symbol? string? bytes? exact-positive-integer? vector? #f)```


# 15.5 Logging
Returns information about the operating system, build mode, or machine for a running Racket. (Installation tools should use [cross-system-type](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=raco&rel=cross-system.html%23%2528def._%2528%2528lib._setup%252Fcross-system..rkt%2529._cross-system-type%2529%2529&version=8.18.0.13), instead, to support cross-installation.)
In 'os mode, the possible symbol results are:
-   'unix
-   'windows
-   'macosx
> > > Prior to the introduction of 'os\* and 'arch modes, ([system-library-subpath](#%28def._%28%28quote._~23~25kernel%29._system-library-subpath%29%29) #f) could be used to obtain this information somewhat indirectly.
In 'os\* mode, the result is similar to 'os mode, but refined to a specific operating system, such as 'linux or 'freebsd, instead of a generic 'unix classification.
In 'arch mode, the result is a symbol representing an architecture. Possible results include 'x86_64, 'i386, 'aarch64, 'arm (32-bit), and 'ppc (32-bit).
In 'word mode, the result is either 32 or 64 to indicate whether Racket is running as a 32-bit program or 64-bit program.
> > > See [Racket Virtual Machine Implementations](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=performance.html%23%2528part._virtual-machines%2529&version=8.18.0.13) for more information about the 'vm and 'gc mode results.
In 'vm mode, the possible symbol results are (see also [Implementations](implementations.html)):
-   'racket
-   'chez-scheme


# 15.5 Logging
In 'gc mode, the possible symbol results are (see also [Implementations](implementations.html)):
-   'cgc — when ([system-type](#%28def._%28%28quote._~23~25kernel%29._system-type%29%29) 'vm) is 'racket
-   '3m — when ([system-type](#%28def._%28%28quote._~23~25kernel%29._system-type%29%29) 'vm) is 'racket
-   'cs — when ([system-type](#%28def._%28%28quote._~23~25kernel%29._system-type%29%29) 'vm) is 'chez-scheme
In 'link mode, the possible symbol results are:
-   'static (Unix)
-   'shared (Unix)
-   'dll (Windows)
-   'framework (Mac OS)
Future ports of Racket may expand the list of 'os, 'os\*, 'arch, 'vm, 'gc, and 'link results.
In 'machine mode, then the result is a string, which contains further details about the current machine in a platform-specific format.
In 'target-machine mode, the result is a symbol for the running Racket’s native bytecode format, or it is #f if there is no native format other than the machine-independent format. If the result is a symbol, then [compile-target-machine?](eval.html#%28def._%28%28quote._~23~25kernel%29._compile-target-machine~3f%29%29) returns #t when applied to the symbol; see also [current-compile-target-machine](eval.html#%28def._%28%28quote._~23~25kernel%29._current-compile-target-machine%29%29).


# 15.5 Logging
In 'so-suffix mode, then the result is a byte string that represents the file extension used for shared objects on the current platform. The byte string starts with a period, so it is suitable as a second argument to [path-replace-suffix](Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-replace-suffix%29%29).
In 'so-mode mode, then the result is 'local if foreign libraries should be opened in “local” mode by default (as on most platforms) or 'global if foreign libraries should be opened in “global” mode.
In 'fs-change mode, the result is an immutable vector of four elements. Each element is either #f or a symbol, where a symbol indicates the presence of a property and #f indicates the absence of a property. The possible symbols, in order, are:
-   'supported — [filesystem-change-evt](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt%29%29) can produce a [filesystem change event](Filesystem.html#%28tech._filesystem._change._event%29) to monitor filesystem changes; if this symbol is not first in the vector, all other vector elements are #f
-   'scalable — resources consumed by a [filesystem change event](Filesystem.html#%28tech._filesystem._change._event%29) are effectively limited only by available memory, as opposed to file-descriptor limits; this property is #f on Mac OS and BSD variants of Unix
-   'low-latency — creation and checking of a [filesystem change event](Filesystem.html#%28tech._filesystem._change._event%29) is practically instantaneous; this property is #f on Linux


# 15.5 Logging
-   'file-level — a [filesystem change event](Filesystem.html#%28tech._filesystem._change._event%29) can track changes at the level of a file, as opposed to the file’s directory; this property is #f on Windows
In 'cross mode, the result reports whether cross-platform build mode has been selected (through the -C or --cross argument to racket; see [Command Line](running-sa.html#%28part._mz-cmdline%29)). The possible symbols are:
-   'infer — infer cross-platform mode based on whether ([system-type](#%28def._%28%28quote._~23~25kernel%29._system-type%29%29)) and ([cross-system-type](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=raco&rel=cross-system.html%23%2528def._%2528%2528lib._setup%252Fcross-system..rkt%2529._cross-system-type%2529%2529&version=8.18.0.13)) report the same symbol
-   'force — use cross-platform mode, even if the current and target system types are the same, because the current and target executables can be different
Changed in version 6.8.0.2 of package base: Added 'vm mode.
Changed in version 6.9.0.1: Added 'cross mode.
Changed in version 7.1.0.6: Added 'target-machine mode.
Changed in version 7.9.0.6: Added 'os\* and 'arch modes.
> ```
(system-language+country)  →  string?


# 15.5 Logging
```
Returns a string to identify the current user’s language and country.

On Unix and Mac OS, the string is five characters: two lowercase ASCII letters for the language, an underscore, and two uppercase ASCII letters for the country. On Windows, the string can be arbitrarily long, but the language and country are in English (all ASCII letters or spaces) separated by an underscore.

On Unix, the result is determined by checking the LC_ALL, LC_TYPE, and LANG environment variables, in that order (and the result is used if the environment variable’s value starts with two lowercase ASCII letters, an underscore, and two uppercase ASCII letters, followed by either nothing or a period). On Windows and Mac OS, the result is determined by system calls.

> ```
(system-library-subpath [mode) → path?
  mode : (or/c 'cgc '3m 'cs #f) = (system-type 'gc)```

Returns a relative directory path. This string can be used to build paths to system-specific files. For example, when Racket is running on Solaris on a Sparc architecture, the subpath starts "sparc-solaris", while the subpath for Windows on an i386 architecture starts "win32\\\\i386".

The optional mode argument specifies the relevant garbage-collection variant, which one of the possible results of ([system-type](#%28def._%28%28quote._~23~25kernel%29._system-type%29%29) 'gc): 'cgc, '3m, or 'cs. It can also be #f, in which case the result is independent of the garbage-collection variant.

Installation tools should use [cross-system-library-subpath](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=raco&rel=cross-system.html%23%2528def._%2528%2528lib._setup%252Fcross-system..rkt%2529._cross-system-library-subpath%2529%2529&version=8.18.0.13), instead, to support cross-installation.

Changed in version 7.0 of package base: Added 'cs mode.

> ```
(version)  →  (and/c string? immutable?)
```


# 15.5 Logging
Returns an immutable string indicating the currently executing version of Racket.
> ```
(banner)  →  (and/c string? immutable?)
```

Returns an immutable string for Racket’s start-up banner text (or the banner text for an embedding program, such as GRacket). The banner string ends with a newline.

> ```
(current-command-line-arguments)	→
(-> vectorof (and/c string? immutable?))
(current-command-line-arguments argv) → void?
    argv	:
(-> vectorof (and/c string? immutable?))
```
(current-thread-initial-stack-size)	→
(-> current-thread-initial-stack-size)
(current-thread-initial-stack-size size) → void?
    size	:
(-> current-thread-initial-stack-size)```
A [parameter](eval-model.html#%28tech._parameter%29) that provides a hint about how much space to reserve for a newly created thread’s local variables. The actual space used by a computation is affected by [JIT](eval.html#%28tech._jit%29) compilation, but it is otherwise platform-independent.
> ```
(parameter)	→
(-> and/c vector?
    (not/c immutable?))


# 15.5 Logging
```
(parameter)	→```

Parses a command line according to the specification in the flag-clauses.

The name-expr, if provided, should produce a path or string to be used as the program name for reporting errors when the command-line is ill-formed. It defaults to ([find-system-path](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29) 'run-file). When a path is provided, only the last element of the path is used to report an error.

The argv-expr, if provided, must evaluate to a list or a vector of strings. It defaults to ([current-command-line-arguments](runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29)).

The command-line is disassembled into flags, each possibly with flag-specific arguments, followed by (non-flag) arguments. Command-line strings starting with - or + are parsed as flags, but arguments to flags are never parsed as flags, and integers and decimal numbers that start with - or + are not treated as flags. Non-flag arguments in the command-line must appear after all flags and the flags’ arguments. No command-line string past the first non-flag argument is parsed as a flag. The built-in -- flag signals the end of command-line flags; any command-line string past the -- flag is parsed as a non-flag argument.

A #:multi, #:once-each, #:once-any, or #:final clause introduces a set of command-line flag specifications. The clause tag indicates how many times the flag can appear on the command line:

-   #:multi — Each flag specified in the set can be represented any number of times on the command line; i.e., the flags in the set are independent and each flag can be used multiple times.

-   #:once-each — Each flag specified in the set can be represented once on the command line; i.e., the flags in the set are independent, but each flag should be specified at most once. If a flag specification is represented in the command line more than once, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.

-   #:once-any — Only one flag specified in the set can be represented on the command line; i.e., the flags in the set are mutually exclusive. If the set is represented in the command line more than once, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.

-   #:final — Like #:multi, except that no argument after the flag is treated as a flag. Note that multiple #:final flags can be specified if they have short names; for example, if -a is a #:final flag, then -aa combines two instances of -a in a single command-line argument.

A normal flag specification has four parts:

-   flags — a flag string, or a set of flag strings. If a set of flags is provided, all of the flags are equivalent. Each flag string must be of the form "-x" or "+x" for some character x, or "--x" or "++x" for some sequence of characters x. An x cannot contain only digits or digits plus a single decimal point, since simple (signed) numbers are not treated as flags. In addition, the flags "--", "-h", and "--help" are predefined and cannot be changed.

-   ids — identifier that are bound to the flag’s arguments. The number of identifiers determines how many arguments can be provided on the command line with the flag, and the names of these identifiers will appear in the help message describing the flag. The ids are bound to string values in the bodys for handling the flag.

-   help-spec — a string or sequence of strings that describes the flag. This string is used in the help message generated by the handler for the built-in -h (or --help) flag. A single literal string can be provided, or any number of expressions that produce strings; in the latter case, strings after the first one are displayed on subsequent lines.

-   bodys — expressions that are evaluated when one of the flags appears on the command line. The flags are parsed left-to-right, and each sequence of bodys is evaluated as the corresponding flag is encountered. When the bodys are evaluated, the preceding ids are bound to the arguments provided for the flag on the command line.

A flag specification using [=>](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._~3d~3e%29%29) escapes to a more general method of specifying the handler and help strings. In this case, the handler procedure and help string list returned by handler-expr and help-expr are used as in the table argument of [parse-command-line](#%28def._%28%28lib._racket%2Fcmdline..rkt%29._parse-command-line%29%29).

A #:usage-help clause inserts text lines immediately after the usage line. Each string in the clause provides a separate line of text.

A #:help-labels clause inserts text lines into the help table of command-line flags. Each string in the clause provides a separate line of text.

A #:ps clause inserts text lines at the end of the help output. Each string in the clause provides a separate line of text.

After the flag clauses, a final clause handles command-line arguments that are not parsed as flags:

-   Supplying no finish clause is the same as supplying #:args () ([void](void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29)).

-   For an #:args finish clause, identifiers in arg-formals are bound to the leftover command-line strings in the same way that identifiers are bound for a [lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) expression. Thus, specifying a single id (without parentheses) collects all of the leftover arguments into a list. The effective arity of the arg-formals specification determines the number of extra command-line arguments that the user can provide, and the names of the identifiers in arg-formals are used in the help string. When the command-line is parsed, if the number of provided arguments cannot be matched to identifiers in arg-formals, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised. Otherwise, args clause’s bodys are evaluated to handle the leftover arguments, and the result of the last body is the result of the [command-line](#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29) expression.

-   A #:handlers finish clause escapes to a more general method of handling the leftover arguments. In this case, the values of the expressions are used like the last two to four arguments [parse-command-line](#%28def._%28%28lib._racket%2Fcmdline..rkt%29._parse-command-line%29%29).

Example:

> ```racket
> ( define verbose-mode ( make-parameter #f ) )
> ( define profiling-on ( make-parameter #f ) )
> ( define optimize-level ( make-parameter 0 ) )
> ( define link-flags ( make-parameter null ) )
> ( define file-to-compile
> ( command-line
> #:program "compiler"
> #:once-each
> [ ( "-v" "--verbose" ) "Compile with verbose messages"
> ( verbose-mode #t ) ]
> [ ( "-p" "--profile" ) "Compile with profiling"
> ( profiling-on #t ) ]
> #:once-any
> [ ( "-o" "--optimize-1" ) "Compile with optimization level 1"
> ( optimize-level 1 ) ]
> [ "--optimize-2" ( ; show help on separate lines
> "Compile with optimization level 2,"
> "which includes all of level 1" )
> ( optimize-level 2 ) ]
> #:multi
> [ ( "-l" "--link-flags" ) lf ; flag takes one argument
> "Add a flag <lf> for the linker"
> ( link-flags ( cons lf ( link-flags ) ) ) ]
> #:args ( filename ) ; expect one command-line argument: <filename>
> ; return the argument as a filename to compile
> filename ) )
> ```

> ```
(str)	→
(-> or/c string? path?)
```