xrdfs(1)

🌸 xrdfs — the manual page, bestie edition 💅

okay so picture this: it's xrdfs(1), it lives in the General Commands Manual, and it is literally your go-to girl for xrootd file and directory meta-data. let's get into it 🫶

---

✨ NAME ✨

xrdfs — xrootd file and directory meta-data utility 🌈

---

✨ SYNOPSIS ✨

xrdfs [global-options] host[:port] [command [args]]

xrdfs [global-options] command [args containing complete URLs]

command: help, cache, chmod, ls, locate, mkdir, mv, stat, statvfs, query,
           rm, rmdir, truncate, prepare, cat, tail, spaceinfo, xattr

two whole forms, bestie. pick your lane 👑

---

✨ DESCRIPTION ✨

so xrdfs runs meta-data oriented operations (think ls, mv, rm, etc.) on one or more xrootd servers. the way it works:

• in batch mode, the endpoint can either be handed to you separately, before the command, or it gets inferred from complete URL path operands that come after the command.
• global options have to come first — before the endpoint or the command. no cutting the line 🙅
• the server-first form and the command-first form are alternatives. you may not mix them. it's giving choose one, periodt.
• all complete URLs in one command gotta use the same scheme, user information, host, and effective port. and yes — an omitted default port compares equal to that same port written out explicitly. equality slay ✨
• query stays server-first forever and always, because its implementation-dependent parameters might literally look like URLs themselves. it's not being difficult, it's just like that 💀
• local file:// and stdio:// operands are not remote endpoints and get straight up rejected in command-first form. not remote, not welcome 🚫
• want command help? invoke xrdfs with no command line options or parameters, wait for the input prompt, then type "help". iconic behaviour honestly 🎀

---

✨ OPTIONS ✨

• -4, --ipv4 — use only the IPv4 network stack and addresses. old school but make it work 💜
• -6, --ipv6 — use only the IPv6 network stack and addresses. future forward bestie 🌐
• -d, --debug level — set the debug level: 0 off, 1 low, 2 medium, or 3 high. 0 to 3, a whole mood scale 🔥
• -h, --help — display help and exit. the classic. the icon. 🙈
• --no-cwd — do not preset a CWD in interactive mode. if you don't want a cwd, you simply don't get one 💅

---

✨ EXAMPLES ✨

these server-first and command-first invocations are equivalent, no cap:

Server-first                    Command-first
xrdfs host stat /path           xrdfs stat root://host//path
xrdfs host ls /dir              xrdfs ls root://host//dir
xrdfs host mv /old /new         xrdfs mv root://host//old root://host//new

and real quick, a lil URL lore for you 🧚 — in an XRootD URL, the double slash after the host is actually two things holding hands: the slash separating the authority from the path, plus the leading slash of the absolute path. a single slash is also accepted, and it gets normalized to an absolute command path. so it's flexible. we love a flexible queen 💖

---

✨ COMMANDS ✨

chmod path <user><group><other>

modify permissions of the path. permission string example: rwxr-x--x 🔐

ls [-l] [-u] [-R] [-D] [-Z] [-C] [dirname]

get directory listing. the flags, bestie:

• -l stat every entry and print long listing
• -u print paths as URLs
• -R list subdirectories recursively
• -D show duplicate entries
• -Z check if file is a ZIP archive and if yes list its content
• -C checksum every entry

locate [-n] [-r] [-d] [-m] [-i] [-p] <path>

get the locations of the path. flags:

• -r refresh, don't use cached locations
• -n make the server return the response immediately even though it may be incomplete
• -d do a recursive, deep locate in order to find data servers
• -m prefer host names to IP addresses
• -i ignore network dependencies (IPv6/IPv4)
• -p be passive: ignore tried/triedrc cgi opaque info

mkdir [-p] [-m<user><group><other>] <dirname>

creates a directory / tree of directories 🌳

• -p create the entire directory tree recursively
• -m<user><group><other> permissions for newly created directories

mv <path1> <path2>

move path1 to path2 locally on the same server. local moves only, we're not shipping anything across servers 💫

stat <path> [<paths>]

get info about the file(s) or directory(ies).

• -q <flags> makes xrdfs return error code 55 to the shell if the requested flag combination is not present; flags may be combined together using '|' or '&'
• available flags: XBitSet, IsDir, Other, Offline, POSCPending, IsReadable, IsWriteable, BackUpExists

statvfs <path>

get info about a virtual file system 💾

query <code> <params>

obtain server information. query codes:

• config <what> — server configuration; <what> is one of the following:
  • bind_max — the maximum number of parallel streams
  • chksum — the supported checksum
  • pio_max — maximum number of parallel I/O requests
  • readv_ior_max — maximum size of a readv element
  • readv_iov_max — maximum number of readv entries
  • tpc — support for third party copies
  • wan_port — the port to use for wan copies
  • wan_window — the wan_port window size
  • window — the tcp window size
  • cms — the status of the cmsd
  • role — the role in a cluster
  • sitename — the site name
  • version — the version of the server
• checksumcancel <path> — file checksum cancellation
• checksum <path> — file checksum
• opaque <arg> — implementation dependent
• opaquefile <arg> — implementation dependent
• space <space> — logical space stats
• stats <what> — server stats; <what> is a list of letters indicating information to be returned:
  • a — all statistics
  • p — protocol statistics
  • b — buffer usage statistics
  • s — scheduling statistics
  • d — device polling statistics
  • u — usage statistics
  • i — server identification
  • z — synchronized statistics
  • l — connection statistics
• xattr <path> — extended attributes
• prepare <reqid> [filenames] — prepare request status

rm <filename> [<filenames>]

remove a file 🗑️

rmdir <dirname>

remove a directory 📁

truncate <filename> <length>

truncate a file ✂️

prepare [-c] [-f] [-s] [-w] [-e] [-p priority] [-a requestid] filenames

prepare one or more files for access.

• -c co-locate staged files if possible
• -f refresh file access time even if the location is known
• -s stage the files to disk if they are not online
• -w when files will be accessed for modification
• -p priority — priority of the request, 0 (lowest) – 3 (highest)
• -a requestid — abort the request
• -e evict the file from disk cache

cat [-o localfile] files

print contents of one or more files to stdout 🐱

• -o localfile — print to the specified local file

tail [-c bytes] [-f] file

output last part of files to stdout.

• -c num_bytes — out last num_bytes
• -f — output appended data as file grows

spaceinfo path

get space statistics for given path 📊

xattr <path> <code> <params>

operation on extended attributes. codes:

• set <attr> — set extended attribute; <attr> is string of form name=value
• get <name> — get extended attribute.
• del <name> — delete extended attribute.
• list — list extended attributes.

---

✨ RETURN CODES ✨

• 50 : generic error (e.g. config, internal, data, OS) 😭
• 51 : socket related error
• 52 : postmaster related error
• 53 : XRootD related error
• 54 : redirection error
• 55 : query response was negative (this is not an error) — not an error bestie, breathe 🫶

---

✨ NOTES ✨

for the list of available environment variables, please refer to xrdcopy(1) 📚

---

✨ DIAGNOSTICS ✨

errors yield an error message and a non-zero exit status. she tells you when something's wrong 💀

---

✨ LICENSE ✨

LGPL 📜

---

✨ SUPPORT LEVEL ✨

the xrdfs command is supported by the XRootD Collaboration. contact information can be found at

https://xrootd.org/contact.html

---

and that's the whole page, bestie 💖 this is version v6.2.0 energy — go forth, ls, mv, rm responsibly, and remember: server-first or command-first, never both. mwah 💅🎀🦋