CLASSADS(1)

📦
version 25.14.1 · 12 versions
, in fedora 43

🎀 NAME 🎀

okay so bestie, pull up a chair, we're talking about classads — straight out of the HTCondor Manual. 💖

ClassAds are a flexible mechanism for representing the characteristics and constraints of machines and jobs in the HTCondor system. fr fr. They get used extensively all over HTCondor to represent jobs, resources, submitters and other HTCondor daemons. And like… you genuinely need to understand this mechanism if you want to harness the full flexibility of the HTCondor system. no cap. 💅

A ClassAd is a set of uniquely named expressions. Each named expression is called an attribute. Here's what ten attributes look like — just a lil slice of an example ClassAd:

MyType       = "Machine"
TargetType   = "Job"
Machine      = "froth.cs.wisc.edu"
Arch         = "INTEL"
OpSys        = "LINUX"
Disk         = 35882
Memory       = 128
KeyboardIdle = 173
LoadAvg      = 0.1000
Requirements = TARGET.Owner=="smith" || LoadAvg<=0.3 && KeyboardIdle>15*60

ClassAd expressions look very much like expressions in C — like, siblings, honestly — and they're composed of literals and attribute references composed with operators and functions. 🦋 But the difference between ClassAd expressions and C expressions? It comes from the fact that ClassAd expressions operate in a much more dynamic environment. For example, an expression from a machine's ClassAd may refer to an attribute in a job's ClassAd, like TARGET.Owner in the example above. And the value and type of that attribute is not known until the expression is evaluated in an environment which pairs a specific job ClassAd with the machine ClassAd. it's giving "we'll find out when we get there." 😭

So how do ClassAd expressions handle all that uncertainty?? By defining all operators to be total operators, which means they have well defined behavior regardless of supplied operands. iconic. ✨ This functionality is provided through two distinguished values, UNDEFINED and ERROR, and by defining all operators so that they can operate on all possible values in the ClassAd system. For example, the multiplication operator — which usually only operates on numbers — has a well defined behavior if supplied with values which are not meaningful to multiply. Thus, the expression 10 * "A string" evaluates to the value ERROR. 💀 Most operators are strict with respect to ERROR, which means that they evaluate to ERROR if any of their operands are ERROR. Similarly, most operators are strict with respect to UNDEFINED. periodt.

🌈 CLASSADS: OLD AND NEW 🌈

okay so ClassAds have existed for quite some time in two forms: Old and New. 🫶

Old ClassAds were the original form and were used in HTCondor until HTCondor version 7.5.0. They were heavily tied to the HTCondor development libraries.

New ClassAds added new features and were designed as a stand-alone library that could be used apart from HTCondor. independently slaying. 👑

In HTCondor version 7.5.1, HTCondor switched to using the New ClassAd library for all use of ClassAds within HTCondor. The library is placed into a compatibility mode so that HTCondor 7.5.1 is still able to exchange ClassAds with older versions of HTCondor.

All user interaction with tools (such as condor_q) as well as output of tools is still compatible with Old ClassAds. Before HTCondor version 7.5.1, New ClassAds were used only in the Job Router. There are some syntax and behavior differences between Old and New ClassAds — all of which should remain invisible to users of HTCondor. 🙈

A complete description of New ClassAds can be found at ‐ http://htcondor.org/classad/classad.html, and in the ClassAd Language Reference Manual found on that web page.

Some of the features of New ClassAds that are not in Old ClassAds are:

  • lists
  • nested ClassAds
  • time values
  • matching groups of ClassAds

HTCondor has avoided using these features, as using them makes it difficult to interact with older versions of HTCondor. But — good news — users can start using them if they do not need to interact with versions of HTCondor older than 7.5.1. 🎀

The syntax varies slightly between Old and New ClassAds. Here's an example ClassAd presented in both forms. The Old form:

Foo = 3
Bar = "ab\"cd\ef"
Moo = Foo =!= Undefined

The New form:

[
Foo = 3;
Bar = "ab\"cd\\ef";
Moo = Foo isnt Undefined;
]

HTCondor will convert to and from Old ClassAd syntax as needed. 💅

✨ New ClassAd Attribute References ✨

Expressions often refer to ClassAd attributes. These attribute references work differently in Old ClassAds as compared with New ClassAds.

In New ClassAds, an unscoped reference is looked for only in the local ClassAd. An unscoped reference is an attribute that does not have a MY. or TARGET. prefix.

The local ClassAd may be described by an example. Matchmaking uses two ClassAds: the job ClassAd and the machine ClassAd. The job ClassAd is evaluated to see if it is a match for the machine ClassAd. The job ClassAd is the local ClassAd. Therefore, in the Requirements attribute of the job ClassAd, any attribute without the prefix TARGET. is looked up only in the job ClassAd. With New ClassAd evaluation, the use of the prefix MY. is eliminated, as an unscoped reference can only refer to the local ClassAd.

The MY. and TARGET. scoping prefixes only apply when evaluating an expression within the context of two ClassAds. Two examples that exemplify this are matchmaking and machine policy evaluation.

When evaluating an expression within the context of a single ClassAd, MY. and TARGET. are not defined. Using them within the context of a single ClassAd will result in a value of Undefined. Two examples that exemplify evaluating an expression within the context of a single ClassAd are during user job policy evaluation, and with the -constraint option to command-line tools. 😭

New ClassAds have no CurrentTime attribute. If needed, use the time() function instead. In order to mimic Old ClassAd semantics in current versions of HTCondor, all ClassAds have an implicit CurrentTime attribute, with a value of time(). 🦋

In current versions of HTCondor, New ClassAds will mimic the evaluation behavior of Old ClassAds. No configuration variables or submit description file contents should need to be changed. To eliminate this behavior and use only the semantics of New ClassAds, set the configuration variable STRICT_CLASSAD_EVALUATION to True. This permits testing expressions to see if any adjustment is required, before a future version of HTCondor potentially makes New ClassAds evaluation behavior the default or the only option. 🌸

✨ CLASSAD SYNTAX ✨

ok so bestie, ClassAd expressions? they're literally just literals + attribute references + other lil sub-expressions, all glued together with operators and functions. that's the whole vibe 💅

🎀 Composing Literals 🎀

literals in the ClassAd language can be integer, real, string, undefined or error types. here's the syntax tea:

  • Integer — a sequence of continuous digits (i.e., [0-9]). ALSO, plot twist: the keywords TRUE and FALSE (case insensitive, bestie) are syntactic representations of the integers 1 and 0 respectively. iconic behaviour tbh.
  • Real — two sequences of continuous digits separated by a period (i.e., [0-9]+.[0-9]+).
  • String — a double quote character, followed by a list of characters terminated by a double quote character. a backslash character inside the string makes the following character count as part of the string, no matter what that character is. yes really, it doesn't care.
  • Undefined — the keyword UNDEFINED (case insensitive) represents the UNDEFINED value. it's giving "idk her" 🦋
  • Error — the keyword ERROR (case insensitive) represents the ERROR value. 💀

🌸 Attributes 🌸

every expression in a ClassAd is named by an attribute name. together, the (name,expression) pair is called an attribute. and an attribute can be referred to in other expressions through its attribute name. so they're all gossiping about each other, basically.

attribute names are sequences of alphabetic characters, digits and underscores, and may not begin with a digit. all characters in the name are significant, but case is NOT significant. so Memory, memory and MeMoRy all refer to the same attribute. slay, case-insensitive queen 👑

an attribute reference consists of the name of the attribute being referenced, plus an optional scope resolution prefix. the prefixes you can use are MY. and TARGET.. case for these prefixes? not significant either. the semantics of supplying a prefix get discussed over in classads/classad-mechanism:classad evaluation semantics. we'll circle back, iykyk.

🦋 Expression Operators 🦋

the operators you can use in ClassAd expressions are similar to the ones in C. here's the full lineup and their relative precedence, from highest to lowest:

👑 Operator Precedence (highest to lowest) 👑

  1. (highest) - — Unary negation
  2. * / % — Multiplication, division, modulo
  3. + - — Addition, subtraction
  4. < <= >= > — Comparison
  5. == != =?= is =!= isnt — Equality and identity comparison
  6. && — Logical AND
  7. (lowest) || — Logical OR

the =?=, is, =!=, and isnt operators get their whole own moment in classads/classad-mechanism:classad evaluation semantics. not us skipping them, they just live over there 💖

🌈 CLASSAD EVALUATION SEMANTICS 🌈

ok so the ClassAd mechanism's primary purpose is matching entities that supply constraints on candidate matches. which means the mechanism is defined to carry out expression evaluations in the context of two ClassAds that are testing each other for a potential match. it's a situationship, but for constraint checking 😭

for example, condor_negotiator evaluates the Requirements expressions of machine and job ClassAds to test if they can be matched. the semantics of evaluating those constraints? defined below, bestie. let's go.

⭐ Evaluating Literals ⭐

literals are self-evaluating. thus, integer, string, real, undefined and error values evaluate to themselves. they're secure in who they are, we love that for them 🫶

💜 Attribute References 💜

since expression evaluation happens in the context of two ClassAds, there's potential for name space ambiguities. so here are the rules defining the semantics of attribute references made by ClassAd A that is being evaluated in a context with another ClassAd B:

  1. if the reference is prefixed by a scope resolution prefix,
    • if the prefix is MY., the attribute is looked up in ClassAd A. if the named attribute does not exist in A, the value of the reference is UNDEFINED. otherwise, the value of the reference is the value of the expression bound to the attribute name.
    • similarly, if the prefix is TARGET., the attribute is looked up in ClassAd B. if the named attribute does not exist in B, the value of the reference is UNDEFINED. otherwise, the value of the reference is the value of the expression bound to the attribute name.
  2. if the reference is NOT prefixed by a scope resolution prefix,
    • if the attribute is defined in A, the value of the reference is the value of the expression bound to the attribute name in A.
    • otherwise, if the attribute is defined in B, the value of the reference is the value of the expression bound to the attribute name in B.
    • otherwise, if the attribute is defined in the ClassAd environment, the value from the environment is returned. this is a special environment, bestie — to be distinguished from the Unix environment. currently, the only attribute of the environment is CurrentTime, which evaluates to the integer value returned by the system call time(2).
    • otherwise, the value of the reference is UNDEFINED.
  3. finally, if the reference refers to an expression that is itself in the process of being evaluated, there is a circular dependency in the evaluation. the value of the reference is ERROR. 🚨 no infinite loops in this house.

🔥 ClassAd Operators 🔥

all operators in the ClassAd language are total, and thus have well defined behavior regardless of the supplied operands. and most operators are strict with respect to ERROR and UNDEFINED, meaning they evaluate to ERROR or UNDEFINED if either of their operands has these exceptional values. no mercy, no exceptions (literally, that's the absence of exceptions).

  • Arithmetic operators:
    1. the operators \*, /, + and - operate arithmetically only on integers and reals.
    2. arithmetic is carried out in the same type as both operands, and type promotions from integers to reals are performed if one operand is an integer and the other real.
    3. the operators are strict with respect to both UNDEFINED and ERROR.
    4. if either operand is not a numerical type, the value of the operation is ERROR.
  • Comparison operators:
    1. the comparison operators ==, !=, <=, <, >= and > operate on integers, reals and strings.
    2. string comparisons are case insensitive for most operators. the only exceptions are the operators =?= and =!=, which do case sensitive comparisons assuming both sides are strings.
    3. comparisons are carried out in the same type as both operands, and type promotions from integers to reals are performed if one operand is a real, and the other an integer. strings may not be converted to any other type, so comparing a string and an integer or a string and a real results in ERROR.
    4. the operators ==, !=, <=, <, >=, and > are strict with respect to both UNDEFINED and ERROR.
    5. in addition, the operators =?=, is, =!=, and isnt behave similar to == and !=, but are NOT strict. semantically, the =?= and is test if their operands are "identical," i.e., have the same type and the same value. for example, 10 == UNDEFINED and UNDEFINED == UNDEFINED both evaluate to UNDEFINED, but 10 =?= UNDEFINED and UNDEFINED is UNDEFINED evaluate to FALSE and TRUE respectively. the =!= and isnt operators test for the "is not identical to" condition.

=?= and is have the same behavior as each other. and isnt and =!= behave the same as each other. the ClassAd unparser will always use =?= in preference to is and =!= in preference to isnt when printing out ClassAds. periodt.

  • Logical operators:
    1. the logical operators && and || operate on integers and reals. the zero value of these types are considered FALSE and non-zero values TRUE.
    2. the operators are not strict, and exploit the "don't care" properties of the operators to squash UNDEFINED and ERROR values when possible. for example, UNDEFINED && FALSE evaluates to FALSE, but UNDEFINED || FALSE evaluates to UNDEFINED.
    3. any string operand is equivalent to an ERROR operand for a logical operator. in other words, TRUE && "foobar" evaluates to ERROR. 🫠
  • The Ternary operator:
    1. the Ternary operator (expr1 ? expr2 : expr3) operate with expressions. if all three expressions are given, the operation is strict.
    2. however, if the middle expression is missing, eg. expr1 ?: expr3, then, when expr1 is defined, that defined value is returned. otherwise, when expr1 evaluated to UNDEFINED, the value of expr3 is evaluated and returned. this can be a convenient shortcut for writing what would otherwise be a much longer classad expression. shortcut queen 💅

🍓 Expression Examples 🍓

the =?= operator is similar to the == operator. it checks if the left hand side operand is identical in both type and value to the right hand side operand, returning TRUE when they are identical. simple as that, bestie ✨

⚠️ CAUTION: okay so for strings, == does not care about case (it's case-insensitive), but =?= is case-sensitive and it WILL notice. 🫶 And here's the key lore you need to lock in: =?= only ever hands back TRUE or FALSE, no drama, periodt. Meanwhile == can give you TRUE, FALSE, UNDEFINED, or ERROR. That's the whole plot twist. 💅

Table 4.1: Evaluation examples for the == operator ✨

  • (10 == 10) → TRUE
  • (10 == 5) → FALSE
  • (10 == "ABC") → ERROR
  • "ABC" == "abc" → TRUE
  • (10 == UNDEFINED) → UNDEFINED
  • (UNDEFINED == UNDEFINED) → UNDEFINED

Table 4.2: Evaluation examples for the =?= operator 🦋

  • (10 =?= 10) → TRUE
  • (10 =?= 5) → FALSE
  • (10 =?= "ABC") → FALSE
  • "ABC" =?= "abc" → FALSE
  • (10 =?= UNDEFINED) → FALSE
  • (UNDEFINED =?= UNDEFINED) → TRUE

Now the =!= operator, bestie, is basically the sibling of != except with high standards. 😌 It checks whether the left hand side operand is not identical in both type and value to the right hand side operand, and it returns FALSE when they are identical. So it's giving "same type AND same value or you're out". ✋

⚠️ CAUTION: same energy as before, but flipped — for strings, != doesn't care about case (case-insensitive) while =!= is case-sensitive. And the key understanding point is that =!= only ever produces TRUE and FALSE, whereas != can produce TRUE, FALSE, UNDEFINED, or ERROR. No cap. 🔥

Table 4.3: Evaluation examples for the != operator 🌸

  • (10 != 10) → FALSE
  • (10 != 5) → TRUE
  • (10 != "ABC") → ERROR
  • "ABC" != "abc" → FALSE
  • (10 != UNDEFINED) → UNDEFINED
  • (UNDEFINED != UNDEFINED) → UNDEFINED

Table 4.4: Evaluation examples for the =!= operator 💜

  • (10 =!= 10) → FALSE
  • (10 =!= 5) → TRUE
  • (10 =!= "ABC") → TRUE
  • "ABC" =!= "abc" → TRUE
  • (10 =!= UNDEFINED) → TRUE
  • (UNDEFINED =!= UNDEFINED) → FALSE

notice how the = twins are so much more decisive than the plain ones — =!= never ghosts you with an UNDEFINED, it always picks a side 👑

🏠 OLD CLASSADS IN THE HTCONDOR SYSTEM

okay bestie, so ClassAds are everywhere in HTCondor and honestly their whole thing is that they're simple and flexible and that gets ruthlessly exploited. 💅 They don't just stand in for machines and jobs in the pool — nah, they also represent submitters of jobs and master daemons, all that other stuff living in the pool. And because you can hand over arbitrary expressions and evaluate them over these ClassAds, you get one uniform, genuinely powerful mechanism for putting constraints on all of it. Those constraints can show up as Requirements expressions in resource and job ClassAds, or as queries over other ClassAds. 🌈

💖 Constraints and Preferences

The requirements and rank expressions inside the submit description file are literally the mechanism where users say what their jobs need and what they'd prefer. And for machines? The configuration decides both the constraints and the preferences of the machines. ✨

For both machine and job, the rank expression spells out how desirable a match is — and heads up, bigger numbers mean better matches. For example, a job ClassAd could hold these expressions:

Requirements = (Arch == "INTEL") && (OpSys == "LINUX")
Rank         = TARGET.Memory + TARGET.Mips

So here the job is like "I require a 32-bit Intel processor running a Linux operating system, no substitutions." And among all those computers, the customer prefers the ones with large physical memories and high MIPS ratings. Since Rank is a user-specified metric, literally any expression can define the perceived desirability of the match. The condor_negotiator daemon runs algorithms to deliver the best resource (as defined by the rank expression) while still satisfying the other required criteria. 👑

Same energy from the other side — the machine can put constraints and preferences on the jobs it'll run by setting the machine's configuration. Like:

Friend        = Owner == "tannenba" || Owner == "wright"
ResearchGroup = Owner == "jbasney" || Owner == "raman"
Trusted       = Owner != "rival" && Owner != "riffraff"
START         = Trusted && ( ResearchGroup || LoadAvg < 0.3 && KeyboardIdle > 15*60 )
RANK          = Friend + ResearchGroup*10

So this policy is saying, in order: this computer will never run jobs owned by the users rival and riffraff, and it will always run a job submitted by members of the research group. Also, jobs from friends are preferred over other foreign jobs, and jobs from the research group are preferred over jobs from friends. The hierarchy is real. 💅

Note: because ClassAd expressions are dynamic little creatures, there's no a priori notion of an integer-valued expression, a real-valued expression, etc. But it's intuitive to think of Requirements and Rank as integer-valued and real-valued expressions respectively. If the actual type of the expression isn't the type you expected, the value is assumed to be zero. 🫶

🔍 Querying with ClassAd Expressions

The flexibility of this whole system also comes out to play when you query ClassAds through the condor_status and condor_q tools, which let users supply ClassAd constraint expressions right from the command line. 😌

Now, plot twist: the syntax you need is different on Unix and Windows, because of how characters get interpreted when forming command-line arguments. The expression has to be a single command-line argument, and the resulting examples differ between the platforms:

  • On Unix shells, single quote marks delimit a single argument.
  • On a Windows command window, double quote marks delimit a single argument.

And inside that argument:

  • Unix escapes the double quote mark by prepending a backslash \ to the double quote mark.
  • Windows escapes the double quote mark by prepending another double quote mark.

There may not be spaces in between. 🚫

Okay here come the examples. Say you wanna find all computers that have had their keyboards idle for more than 60 minutes AND have more than 4000 MB of memory. The desired ClassAd expression is:

KeyboardIdle > 60*60 && Memory > 4000

On a Unix platform, the command looks like:

$ condor_status -const 'KeyboardIdle > 60*60 && Memory > 4000'

Name               OpSys   Arch   State     Activity LoadAv Mem  ActvtyTime
100
slot1@altair.cs.wi LINUX   X86_64 Owner     Idle     0.000 8018 13+00:31:46
slot2@altair.cs.wi LINUX   X86_64 Owner     Idle     0.000 8018 13+00:31:47
...
...
slot1@athena.stat. LINUX   X86_64 Unclaimed Idle     0.000 7946  0+00:25:04
slot2@athena.stat. LINUX   X86_64 Unclaimed Idle     0.000 7946  0+00:25:05
...
...

And the Windows equivalent is:

> condor_status -const "KeyboardIdle > 60*60 && Memory > 4000"

Next up, here's an example for a Unix platform that uses a regular expression ClassAd function to list specific information. A file holds ClassAd information, condor_advertise is used to inject that information, and condor_status constrains the search with an expression containing a ClassAd function. 🧚

$ cat ad
MyType = "Generic"
FauxType = "DBMS"
Name = "random-test"
Machine = "f05.cs.wisc.edu"
MyAddress = "<192.0.2.105:34000>"
DaemonStartTime = 1153192799
UpdateSequenceNumber = 1

$ condor_advertise UPDATE_AD_GENERIC ad

$ condor_status -any -constraint 'FauxType=="DBMS" && regexp("random.*", Name, "i")'

MyType               TargetType           Name

Generic              None                 random-test

And here's the ClassAd expression describing a machine that advertises a Windows operating system:

OpSys == "WINDOWS"

Now bestie, here are three equivalent ways on a Unix platform to list all machines advertising a Windows operating system. Spaces appear in these examples to show you where they're permitted. ✨

$ condor_status -constraint ' OpSys == "WINDOWS"  '

$ condor_status -constraint OpSys==\"WINDOWS\"

$ condor_status -constraint "OpSys==\"WINDOWS\""

The equivalent command on a Windows platform to list all machines advertising a Windows operating system has to delimit the single argument with double quote marks, and then escape the double quote marks that identify the string within the expression. Spaces appear in this example where they're permitted:

> condor_status -constraint " OpSys == ""WINDOWS"" "

✨ EXTENDING CLASSADS WITH USER-WRITTEN FUNCTIONS

The ClassAd language comes with a rich set of functions already, but plot twist — you can add new functions to the language without recompiling the HTCondor system or the ClassAd library. 😭 Obsessed. To do it you'll need to:

  • implement the new function in the C++ programming language,
  • compile that code into a shared library, and
  • tell HTCondor where in the file system the shared library lives.

The gritty details of the ClassAd implementation are beyond the scope of this document, but the ClassAd source distribution ships with an example source file that extends ClassAds by adding two new functions, named todays_date() and double(). Use it as a model to implement your own functions. 💖

To deploy this example extension, follow these steps on Linux:

  1. Download the ClassAd source distribution from http://www.cs.wisc.edu/condor/classad.
  2. Unpack the tarball.
  3. Inspect the source file shared.cpp. This one file contains the whole extension.
  4. Build shared.cpp into a shared library. On Linux, the command line to do so is:
$ g++ -DWANT_CLASSAD_NAMESPACE -I. -shared -o shared.so \
  -Wl,-soname,shared.so -o shared.so -fPIC shared.cpp
  1. Copy the file shared.so to a location that all of the HTCondor tools and daemons can read:
$ cp shared.so `condor_config_val LIBEXEC`
  1. Tell HTCondor to load the shared library into all tools and daemons, by setting the CLASSAD_USER_LIBS configuration variable to the full name of the shared library. In this case:
CLASSAD_USER_LIBS = $(LIBEXEC)/shared.so
  1. Restart HTCondor.
  2. Test the new functions by running:
$ condor_status -format "%s\n" todays_date()

💌 AUTHOR

HTCondor Team 🫶 the icons, the legends, the main characters fr fr

1990-2026, Center for High Throughput Computing, Computer Sciences Department, University of Wisconsin-Madison, Madison, WI, US. Licensed under the Apache License, Version 2.0.

and that's a wrap on CLASSADS(1) bestie!! 👑 this page is dated Oct 16, 2026 and it's the CLASSADS(1) manual page from the HTCondor docs — you're officially certified, go forth and constrain things ✨💅🦋

📦 where this page comes from