gsm-ussd - Man Page

Send USSD queries by GSM/UMTS modem


 gsm-ussd --help|-h|-?
 gsm-ussd [-m <modem>] [-t <timeout>] [-p <pin>] [-d] [-l <logfile>] [<ussd-cmd>...]
 gsm-ussd [-m <modem>] [-t <timeout>] [-d] [-l <logfile>] --cancel|-c


This script sends a USSD query to a modem, waits for the answer and displays it.  The modem type is detected and any necessary en-/decoding and error checking is done.


--modem|-m <modem>

Sets the device file to use to connect to the modem. Default is /dev/ttyUSB1.

Please note: Depending on your modem's make and model, you might get more than one serial USB interfaces when connecting the modem!  For example, the Huawei E160 gets two: /dev/ttyUSB0 and  /dev/ttyUSB1.  The first is for data, commands and state messages use the second port.

--timeout|-t <timeout_in_secs>

The timeout in seconds that the script will wait for an answer after each command sent to the modem. Default is 20 seconds.

--pin|-p <PIN>

The SIM PIN to use if the card is still locked.  This is typically  the case just after the modem got stuck into your computer. Attention: The SIM PIN can be seen in the process list as long as the script is running - use with care on multi user  systems!  Attention again: If you are using a shell with a  command line history, your SIM PIN will be stored there for a while in clear.


This option causes gsm-ussd to send USSD queries in cleartext, i.e. without encoding them into a 7bit-packed-hex-string, as is needed for Huaweis E160* series of UMTS modems.  This takes precedence before any detected modem type.


This is the opposite of the previous option: Use encoding, even if the modem type does not indicate that it is needed.  This (obviously) takes precedence before any detected modem type.


Aborts an active USSD session.  USSD sessions are queries for more information by the provider; they can take the form of simple menus with numbers to choose the menu entries or a query to enter a top up code.


Shows the online help.

The following options aren't meant for everyday usage, but as diagnostic aids in development or for the pathologically curious. Please be reminded again that any logs or debugging output will show your PIN if you're using option --pin <PIN>!  So use with care.

--logfile|-l <logfilename>

Writes the chat between modem and script into the named log file. Useful to look for unexpected modem answers (or expected modem  answers that nevertheless weren't handled correctly).  Clearly more a debugging help than anything else.


Switches debug mode on.  The script will then explain its actions  and their results in high detail.


A USSD query is a “phone number” starting with “*” and ending with  “#” which let's you do interesting things in a GSM network. By default, if you don't specify any USSD query, *100# will be used, which causes all GSM network providers known to me to provide the balance of your prepaid account.

If you enter more than one USSD query, they will be sent in order and the result of each on its own line.

Please note: USSD queries are different for each provider!

List of interesting things:

Exit Code Values

gsm-ussd(1) sets its exit code as follows:


Jochen Gruse, <>


2022-07-21 perl v5.36.0 User Contributed Perl Documentation