---
name: "birthday"
section: "1"
platform: "linux"
package: "birthday"
version: "1.6.2-6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/birthday"
---

# birthday(1)

warn about upcoming birthdays and other events

## NAME

birthday - warn about upcoming birthdays and other events

## SYNOPSIS

**birthday** \[**-w**\|**-c**\] \[**-f** *file*\] \[**-W** *defwarn*\] \[**-M** *maxwarn*\] \[**-m** *minwarn*\] \[**-l** *lines*\] \[**-p** *weeks*\] \[**-d** *total*\] \[**-i** *width*\] \[**-L**\]

## DESCRIPTION

The  **birthday** command reads a file, by default *~/.birthdays*, which gives a list of events in the near future (see section **FILE FORMAT** for details). It can then produce either a list of events which are coming up within the next few weeks, or a text-based calendar with a few lines for each day.

## OPTIONS

- **-w**

  Display a list of upcoming events. This is the default.

- **-c**

  Display a calendar, designed to be piped to [**lpr**(1)](/lpr/1.md).

- **-f** *file*

  Read the events from *file* rather than *~/.birthdays.* If *file* is a single hyphen, read the events from the standard input (usually the terminal).

### List Options

- **-W** *warn*

  Warn *warn* days in advance, for entries that have no **w** flag (see **FILE FORMAT**). If this switch is not specified, it defaults to 21 days.

- **-M** *max*

  Warn at most *max* days in advance. This overrides any flag given in the file.

- **-m** *min*

  Warn at least *min* days in advance. This overrides any flag given in the file.

- **-L**

  Also output the day and name of month after the number of days hence.

### Calendar Options

- **-l** *lines*

  Print *lines* lines for every day.

- **-p** *weeks*

  Print *weeks* weeks on every page of the calendar. If set to *0*, the default, disables page breaks.

- **-d** *days*

  Print the calendar for up to *days* days in advance.

- **-i** *width*

  Print the calendar *width* characters wide. This affects the length of the lines separating each day, and the point at which events will be word-wrapped.

## FILE FORMAT

Each line beginning with a hash sign,  \`**#**', is a comment and will be ignored. Lines beginning with an ampersand, \`**&**', are directives. Currently there is only one such directive, **&include** *file*, which reads in a seperate file from your *.birthdays* file. *file* should be given with an absolute path, which should not use the tilde notation to specify your home directory.

Any other line specifies the name of a person or event, followed by an equals sign and a date (*DD/MM*, *DD/MM/YY* or *DD/MM/YYYY*, where the form *DD/MM/YY* is assumed to give a date in the 20th century and is now deprecated), and finally some extra options. These options are:

- **bd**

  This line is a birthday (the default). The year, if given, should be when the person was born. A line designated as a birthday will produce output like **Erin has a birthday in 3 days' time** or **Jemima is 3 in 2 weeks' time**.

- **ann**

  This line is an anniversary. The year, if given, should be the year in which the thing happened, producing output like **Pen exploded 3 years ago tomorrow** given a line such as **Pen exploded=12/09/93 ann**.

- **ev**

  This line is an event of some sort. If a year is given, the text will be displayed in that year only; otherwise, it will be displayed every year. The remaining time is simply appended to the text; for instance, the input **Easter=7/4/1996 ev** would give rise to the text **Easter in 1 week's time**.

- **w***n*

  Warn *n* days in advance of the date, rather than the default of 21 days or the number given with the **-W** flag.

- **to***date*

  The event lasts until *date*, which should be in the same format as for the date of the event.

- **for***days*

  The event lasts for **days** days.

## DATE SPECIFICATION

The file format documented here handles dates in a couple of slightly non-standard ways.  Firstly, the dates are given in British format of *DD/MM/YYYY*, as opposed to the more normal US format *MM/DD/YYYY*.

Secondly, dates with a two-digit year are assumed to be in the 20th century (19*xx*), rather than taking the standard convention of assuming all two-digit years less than 70 are in the 21st century.  This is for reasons of compatibility with older data files, since many people have birthdays before 1970, and the program was written before I came across the Y2K issues. :-(  You should probably avoid this format.

## EXAMPLE

Joe Blow=25/04/1974

## FILES

- *~/.birthdays*

  Your default birthdays file.

## SEE ALSO

[**cal**(1)](/cal/1.md)

## BUGS

Both the "features" in the **DATE SPECIFICATION** section could be construed as bugs, and are mostly present for backwards compatibility.

The calendar mode should be a seperate program.

The program cannot warn more than one year in advance of anything.

## AUTHOR

Andy Mortimer \<andy.mortimer@zetnet.co.uk\>